# Mattermost > Mattermost Bot 设置和 OpenClaw 配置 - 网址：https://funcoding.ai/agents/openclaw/channels/mattermost/ - 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/channels/mattermost --- 状态：可下载插件（Bot 令牌 + WebSocket 事件）。支持频道、私密频道、群组私信和私信。Mattermost 是一个可自行托管的团队消息平台（[mattermost.com](https://mattermost.com)）。 ## 安装 **npm registry** ```bash openclaw plugins install @openclaw/mattermost ``` **Local checkout** ```bash openclaw plugins install ./path/to/local/mattermost-plugin ``` 详情：[插件](https://funcoding.ai/agents/openclaw/tools/plugin/) ## 快速设置 **确保插件可用** 使用上述命令安装 `@openclaw/mattermost`，如果 Gateway 网关已在运行，请重启它。 **创建 Mattermost Bot** 创建一个 Mattermost Bot 账户，复制 **Bot 令牌**，并将 Bot 添加到它应读取的团队和频道中。 **复制基础 URL** 复制 Mattermost **基础 URL**（例如 `https://chat.example.com`）。末尾的 `/api/v4` 会自动移除。 **配置 OpenClaw 并启动 Gateway 网关** 最小配置： ```json5 { channels: { mattermost: { enabled: true, botToken: "mm-token", baseUrl: "https://chat.example.com", dmPolicy: "pairing", }, }, } ``` 非交互式替代方案： ```bash openclaw channels add --channel mattermost --bot-token --http-url https://chat.example.com ```
对于位于私有地址、局域网地址或 tailnet 地址上的自行托管 Mattermost：出站 Mattermost API 请求会经过 SSRF 防护，默认阻止私有和内部 IP。可使用 `channels.mattermost.network.dangerouslyAllowPrivateNetwork: true` 选择启用（每个账户：`channels.mattermost.accounts..network.dangerouslyAllowPrivateNetwork`）。
## 原生斜杠命令 原生斜杠命令需要选择启用。启用后，OpenClaw 会在 Bot 所属的每个团队中注册 `oc_*` 斜杠命令，并在 Gateway 网关 HTTP 服务器上接收回调 POST 请求。 ```json5 { channels: { mattermost: { commands: { native: true, nativeSkills: true, callbackPath: "/api/channels/mattermost/command", // 当 Mattermost 无法直接访问 Gateway 网关时使用（反向代理/公共 URL）。 callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, }, }, } ``` 注册的命令：`/oc_status`、`/oc_model`、`/oc_models`、`/oc_new`、`/oc_help`、`/oc_think`、`/oc_reasoning`、`/oc_verbose`、`/oc_queue`。使用 `nativeSkills: true` 时，技能命令也会注册为 `/oc_`。
行为说明 - `native` 和 `nativeSkills` 默认为 `"auto"`，对于 Mattermost，这会解析为禁用。请将它们显式设置为 `true`。 - `callbackPath` 默认为 `/api/channels/mattermost/command`。 - 如果省略 `callbackUrl`，OpenClaw 会派生 `http://:`。通配绑定主机（`0.0.0.0`、`::`）会回退到 `localhost`。 - 对于多账户设置，可以在顶层或 `channels.mattermost.accounts..commands` 下设置 `commands`（账户值会覆盖顶层字段）。 - 由其他集成创建且触发词相同的现有斜杠命令会保持不变（注册时会跳过）；当回调 URL 发生偏移时，Bot 创建的命令会被更新或重新创建。 - 命令回调使用 OpenClaw 注册 `oc_*` 命令时 Mattermost 返回的每命令令牌进行验证。 - OpenClaw 会在接受每个回调前刷新当前的 Mattermost 命令注册，因此已删除或重新生成的斜杠命令所对应的过期令牌无需重启 Gateway 网关便会停止被接受。 - 如果 Mattermost API 无法确认命令仍为当前命令，回调验证会以关闭方式失败；失败的验证会被短暂缓存，并发查找会合并处理，并且每个命令的新查找启动会受到速率限制，以约束重放压力。 - 如果注册失败、启动未完整完成，或回调令牌与解析到的命令所注册的令牌不匹配，斜杠回调会以关闭方式失败（对某一命令有效的令牌无法通过其他命令到达上游验证）。 - 已接受的回调会通过一条仅发送者可见的“处理中...”回复进行确认；实际回答会作为普通消息送达。
可访问性要求 Mattermost 服务器必须能够访问回调端点。 - 除非 Mattermost 与 OpenClaw 运行在同一主机/网络命名空间中，否则不要将 `callbackUrl` 设置为 `localhost`。 - 除非你的 Mattermost 基础 URL 会将 `/api/channels/mattermost/command` 反向代理到 OpenClaw，否则不要将 `callbackUrl` 设置为该基础 URL。 - 可使用 `curl https:///api/channels/mattermost/command` 快速检查；GET 请求应从 OpenClaw 返回 `405 Method Not Allowed`，而不是 `404`。
Mattermost 出站允许列表 如果回调目标是私有地址、tailnet 地址或内部地址，请设置 Mattermost `ServiceSettings.AllowedUntrustedInternalConnections`，使其包含回调主机/域名。 请使用主机/域名条目，而非完整 URL。 - 正确：`gateway.tailnet-name.ts.net` - 错误：`https://gateway.tailnet-name.ts.net`
## 环境变量（默认账户） 如果更倾向于使用环境变量，请在 Gateway 网关主机上设置以下变量： - `MATTERMOST_BOT_TOKEN=...` - `MATTERMOST_URL=https://chat.example.com`
环境变量仅适用于**默认**账户（`default`）。其他账户必须使用配置值。 无法通过工作区 `.env` 设置 `MATTERMOST_URL`；请参阅[工作区 .env 文件](https://funcoding.ai/agents/openclaw/gateway/security/)。
## 聊天模式 Mattermost 会自动回复私信。频道行为由 `chatmode` 控制： **oncall (default)** 仅在频道中被 @提及时回复。 **onmessage** 回复每条频道消息。 **onchar** 当消息以触发前缀开头时回复。 配置示例： ```json5 { channels: { mattermost: { chatmode: "onchar", oncharPrefixes: [">", "!"], // 默认值 }, }, } ``` 说明： - `onchar` 仍会响应显式 @提及。 - 仍支持 `channels.mattermost.requireMention`，但首选 `chatmode`。每频道的 `groups..requireMention` 设置优先于二者。 - Bot 在频道帖子串中发送可见回复后，同一帖子串中的后续消息无需新的 @提及或 `onchar` 前缀即可得到回复，从而保持多轮帖子串对话持续进行。参与状态会从 Bot 最后一次回复该帖子串起保留 7 天，并在 Gateway 网关重启后继续保留。Bot 仅观察过的帖子串不受影响；若要重新要求显式提及，请发起新的顶层消息。 - 将 `channels.mattermost.implicitMentions.threadParticipation: false` 设置为停止让已参与帖子串的后续消息绕过提及门控。账户覆盖使用 `channels.mattermost.accounts..implicitMentions`。Mattermost 目前不会产生 `replyToBot` 或 `quotedBot` 事实，因此这些标志在此处不起作用。 ## 帖子串和会话 使用 `channels.mattermost.replyToMode` 控制频道和群组回复是保留在主频道中，还是在触发帖子下启动帖子串。 - `off`（默认）：仅当入站帖子已位于帖子串中时，才在帖子串中回复。 - `first`：对于顶层频道/群组帖子，在该帖子下启动帖子串，并将对话路由到帖子串范围的会话。 - 目前对于 Mattermost，`all` 和 `batched` 的行为与 `first` 相同，因为 Mattermost 一旦存在帖子串根，后续分块和媒体就会继续发送到同一帖子串。 - 即使已设置 `replyToMode`，私信仍默认为 `off`。 使用 `channels.mattermost.replyToModeByChatType` 覆盖 `direct`、`group` 或 `channel` 聊天的模式。设置 `direct` 以选择让私信使用帖子串： - `off`（默认）：私信保持不使用帖子串，并共用一个滚动会话。 - `first`、`all` 或 `batched`：每条顶层私信都会启动一个 Mattermost 帖子串，并由一个全新、独立的会话提供支持。 ```json5 { channels: { mattermost: { replyToMode: "all", replyToModeByChatType: { direct: "first", }, }, }, } ``` 说明： - 帖子串范围的会话使用触发帖子的 ID 作为帖子串根。 - `first` 和 `all` 目前等效，因为 Mattermost 一旦存在帖子串根，后续分块和媒体就会继续发送到同一帖子串。 - 每聊天类型的覆盖优先于 `replyToMode`。如果没有 `direct` 覆盖，现有部署会继续使用扁平、不分帖子的私信。 ## 访问控制（私信） - 默认值：`channels.mattermost.dmPolicy = "pairing"`（未知发送者会收到配对码）。其他值：`allowlist`、`open`、`disabled`。 - 批准方式： - `openclaw pairing list mattermost` - `openclaw pairing approve mattermost ` - 公开私信：`channels.mattermost.dmPolicy="open"` 加 `channels.mattermost.allowFrom=["*"]`（配置架构会强制要求通配符）。 - `channels.mattermost.allowFrom` 接受用户 ID（推荐）和 `accessGroup:` 条目。请参阅[访问组](https://funcoding.ai/agents/openclaw/channels/access-groups/)。 ## 频道（群组） - 默认值：`channels.mattermost.groupPolicy = "allowlist"`（需要提及）。 - 使用 `channels.mattermost.groupAllowFrom` 将发送者加入允许列表（推荐使用用户 ID）。 - `channels.mattermost.groupAllowFrom` 接受 `accessGroup:` 条目。请参阅[访问组](https://funcoding.ai/agents/openclaw/channels/access-groups/)。 - 每频道的提及覆盖位于 `channels.mattermost.groups..requireMention` 下，也可使用 `channels.mattermost.groups["*"].requireMention` 设置默认值。 - `@username` 匹配是可变的，并且仅在 `channels.mattermost.dangerouslyAllowNameMatching: true` 时启用。 - 开放频道：`channels.mattermost.groupPolicy="open"`（需要提及）。 - 解析顺序：先 `channels.mattermost.groupPolicy`，再 `channels.defaults.groupPolicy`，最后 `"allowlist"`。 - 运行时说明：如果完全缺少 `channels.mattermost` 部分，运行时会针对群组检查以关闭方式回退到 `groupPolicy="allowlist"`（即使已设置 `channels.defaults.groupPolicy`），并记录一次性警告。 示例： ```json5 { channels: { mattermost: { groupPolicy: "open", groups: { "*": { requireMention: true }, "team-channel-id": { requireMention: false }, }, }, }, } ``` ## 出站投递目标 将以下目标格式与 `openclaw message send` 或定时任务/Webhooks 一起使用： | 目标 | 投递至 | | ----------------------------------- | ------------------------------------------------------------- | | `channel:` | 按 ID 指定的频道 | | `channel:` 或 `#channel-name` | 按名称指定的频道，在 Bot 所属的所有团队中搜索 | | `user:` 或 `mattermost:` | 与该用户的私信 | | `@username` | 私信（通过 Mattermost API 解析用户名） | 每条出站消息最多支持一个附件；请将多个文件拆分为多次发送。
裸露的不透明 ID（如 `64ifufp...`）在 Mattermost 中存在**歧义**（用户 ID 与频道 ID）。 OpenClaw 会**优先按用户解析**： - 如果该 ID 对应一个用户（`GET /api/v4/users/` 成功），OpenClaw 会通过 `/api/v4/channels/direct` 解析私信频道来发送一条**私信**。 - 否则，该 ID 将被视为**频道 ID**。 如果需要确定性行为，请始终使用显式前缀（`user:` / `channel:`）。
## 私信频道重试 当 OpenClaw 向 Mattermost 私信目标发送消息且需要先解析私信频道时，默认会重试暂时性的私信频道创建失败。 使用 `channels.mattermost.dmChannelRetry` 为 Mattermost 插件全局调整该行为，或使用 `channels.mattermost.accounts..dmChannelRetry` 为单个账户调整。默认值： ```json5 { channels: { mattermost: { dmChannelRetry: { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 10000, timeoutMs: 30000, }, }, }, } ``` 注意： - 这仅适用于创建私信频道（`/api/v4/channels/direct`），而非每次 Mattermost API 调用。 - 重试采用带抖动的指数退避，适用于速率限制、5xx 响应以及网络或超时错误等暂时性故障。 - 除 `429` 之外的 4xx 客户端错误会被视为永久性错误，不会重试。 ## 预览流式传输 Mattermost 会将思考过程、工具活动和部分回复文本流式传输到一个**草稿预览帖子**中，并在最终答案可安全发送时原地完成该帖子。在 `partial` 模式下，预览会在同一帖子 ID 上更新，而不是为每个分块发送消息来刷屏。在 `block` 模式下，预览会在已完成文本与工具活动块之间轮换，因此较早的块会作为独立帖子保持可见，而不会被下一个块覆盖。包含媒体或错误的最终结果会取消待处理的预览编辑，并改用正常投递，而不是提交一个无用的预览帖子。 预览流式传输在 `partial` 模式下**默认开启**。通过 `channels.mattermost.streaming.mode` 配置（旧版标量/布尔值 `streaming` 会由 `openclaw doctor --fix` 迁移）： ```json5 { channels: { mattermost: { streaming: { mode: "partial" }, // 关闭 | 部分 | 分块 | 进度 }, }, } ```
流式传输模式 - `partial`（默认）：使用一个预览帖子，随着回复内容增加而编辑，最后用完整答案完成。 - `block` 会在已完成文本与工具活动块之间轮换预览，因此每个块都会作为独立帖子保持可见，而不会被原地覆盖。并行和连续的工具更新会共享当前工具活动帖子。 - `progress` 会在生成期间显示状态预览，仅在完成时发布最终答案。 - `off` 会禁用预览流式传输。使用 `streaming.block.enabled: true` 时，已完成的助手块仍会作为普通分块回复（独立帖子）投递，而不是合并为单个最终帖子。
流式传输行为说明 - 如果无法原地完成流式传输（例如帖子在传输过程中被删除），OpenClaw 会回退为发送新的最终帖子，以确保回复绝不丢失。 - 仅包含思考过程的载荷不会发布到频道帖子中，包括以 `> Thinking` 引用块形式到达的文本。设置 `/reasoning on` 可在其他界面中查看思考过程；Mattermost 最终帖子只保留答案。 - 有关频道映射矩阵，请参阅[流式传输](https://funcoding.ai/agents/openclaw/concepts/streaming/#preview-streaming-modes)。
## 表情回应（消息工具） - 将 `message action=react` 与 `channel=mattermost` 一起使用。 - `messageId` 是 Mattermost 帖子 ID。 - `emoji` 接受 `thumbsup` 或 `:+1:` 之类的名称（冒号可选）。 - 设置 `remove=true`（布尔值）可移除表情回应。 - 添加/移除表情回应事件会作为系统事件转发到所路由的智能体会话，并受到与消息相同的私信/群组策略检查。 示例： ```text message action=react channel=mattermost target=channel: messageId= emoji=thumbsup message action=react channel=mattermost target=channel: messageId= emoji=thumbsup remove=true ``` 配置： - `channels.mattermost.actions.reactions`：启用/禁用表情回应操作（默认为 true）。 - 每账户覆盖：`channels.mattermost.accounts..actions.reactions`。 ## 交互式按钮（消息工具） 发送带有可点击按钮的消息。当用户点击按钮时，智能体会收到所选内容并可进行响应。 按钮来自语义化 `presentation` 载荷（用于普通智能体回复和 `message action=send`）。OpenClaw 将值按钮渲染为 Mattermost 交互式按钮，在消息文本中保留 URL 按钮，并将选择菜单降级为可读文本。 ```text message action=send channel=mattermost target=channel: presentation={"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"yes"},{"label":"No","value":"no"}]}]} ``` 呈现按钮字段： 显示标签（别名：`text`）。 点击时发回的值，用作操作 ID（别名：`callback_data`、`callbackData`）。除非设置了 `url`，否则可点击按钮必须提供此项。 链接按钮；在消息正文中渲染为 `label: url` 文本，而不是交互式按钮。 按钮样式。对于 Mattermost 不支持的值，将应用默认样式。 要在智能体系统提示词中声明支持按钮，请将 `inlineButtons` 添加到频道能力中： ```json5 { channels: { mattermost: { capabilities: ["inlineButtons"], }, }, } ``` 当用户点击按钮时： **访问检查** 点击者必须通过与消息发送者相同的私信/群组策略检查；未经授权的点击会收到一条临时通知，并被忽略。 **用确认信息替换按钮** 所有按钮都会替换为一行确认信息（例如，“✓ **Yes** 已由 @user 选择”）。 **智能体收到所选内容** 智能体会将所选内容作为入站消息（以及系统事件）接收并进行响应。
实现说明 - 按钮回调使用 HMAC-SHA256 验证（自动进行，无需配置）。 - 点击时会替换整个附件块，因此所有按钮会一起移除，无法只移除一部分。 - 包含连字符或下划线的操作 ID 会被自动清理（Mattermost 路由限制）。 - 如果点击的 `action_id` 与原始帖子中的任何操作都不匹配，则会被拒绝并返回 `403`（“未知操作”）。
配置和可达性 - `channels.mattermost.capabilities`：能力字符串数组。添加 `"inlineButtons"` 可在智能体系统提示词中启用按钮工具说明。 - `channels.mattermost.interactions.callbackBaseUrl`：按钮回调的可选外部基础 URL（例如 `https://gateway.example.com`）。当 Mattermost 无法通过 Gateway 网关的绑定主机直接访问它时，请使用此项。 - 在多账户设置中，也可以在 `channels.mattermost.accounts..interactions.callbackBaseUrl` 下设置相同字段。 - 如果省略 `interactions.callbackBaseUrl`，OpenClaw 会根据 `gateway.customBindHost` + `gateway.port`（默认值为 18789）派生回调 URL，然后回退到 `http://localhost:`。回调路径为 `/mattermost/interactions/`。 - 可达性规则：Mattermost 服务器必须能够访问按钮回调 URL。只有当 Mattermost 和 OpenClaw 运行在同一主机/网络命名空间中时，`localhost` 才有效。 - `channels.mattermost.interactions.allowedSourceIps`：按钮回调的源 IP 允许列表。如果未设置，则只接受回环源（`127.0.0.1`、`::1`），因此必须在此处将远程 Mattermost 服务器加入允许列表，否则其点击会被拒绝并返回 `403`。如果位于反向代理后方，还需设置 `gateway.trustedProxies`，以便从转发标头中派生真实客户端 IP。 - 如果回调目标位于私有网络、tailnet 或内部网络，请将其主机/域名添加到 Mattermost `ServiceSettings.AllowedUntrustedInternalConnections`。
### 直接 API 集成（外部脚本） 外部脚本和 Webhooks 可以通过 Mattermost REST API 直接发布按钮，而无需通过智能体的 `message` 工具。建议使用 OpenClaw 的 `message` 工具。对于直接集成，请从 `@openclaw/mattermost/api.js` 导入 `buildButtonAttachments`；如果发布原始 JSON，请遵循以下规则： **载荷结构：** ```json5 { channel_id: "", message: "选择一个选项：", props: { attachments: [ { actions: [ { id: "mybutton01", // 只能使用字母和数字——见下文 type: "button", // 必填，否则点击会被静默忽略 name: "批准", // 显示标签 style: "primary", // 可选："default"、"primary"、"danger" integration: { url: "https://gateway.example.com/mattermost/interactions/default", context: { action_id: "mybutton01", // 必须与按钮 ID 匹配 action: "approve", // ... 任意自定义字段 ... _token: "", // 请参阅下方 HMAC 部分 }, }, }, ], }, ], }, } ```
**关键规则** 1. 附件应放在 `props.attachments` 中，而不是顶层 `attachments` 中（否则会被静默忽略）。 2. 每个操作都需要 `type: "button"`，否则点击会被静默吞掉。 3. 每个操作都需要一个 `id` 字段，Mattermost 会忽略没有 ID 的操作。 4. 操作 `id` **只能包含字母和数字**（`[a-zA-Z0-9]`）。连字符和下划线会破坏 Mattermost 的服务器端操作路由（返回 404）。使用前请将其移除。 5. `context.action_id` 必须与按钮的 `id` 匹配；如果点击的 `action_id` 不存在于帖子中，Gateway 网关会拒绝该点击。 6. `context.action_id` 为必填项，没有它，交互处理程序会返回 400。 7. 回调源 IP 必须被允许（请参阅上方的 `interactions.allowedSourceIps`）。
**HMAC 令牌生成** Gateway 网关使用 HMAC-SHA256 验证按钮点击。外部脚本必须生成与 Gateway 网关验证逻辑匹配的令牌： **从 Bot 令牌派生密钥** `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`，以十六进制编码。 **构建上下文对象** 使用除 `_token` 之外的所有字段构建上下文对象。 **使用排序后的键进行序列化** 使用**递归排序的键**且**不含空格**进行序列化（Gateway 网关也会规范化嵌套对象，并生成紧凑 JSON）。 **对载荷签名** `HMAC-SHA256(key=secret, data=serializedContext)` **添加令牌** 将生成的十六进制摘要作为上下文中的 `_token` 添加。 Python 示例： ```python import hmac, hashlib, json secret = hmac.new( b"openclaw-mattermost-interactions", bot_token.encode(), hashlib.sha256 ).hexdigest() ctx = {"action_id": "mybutton01", "action": "approve"} payload = json.dumps(ctx, sort_keys=True, separators=(",", ":")) token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() context = {**ctx, "_token": token} ```
常见 HMAC 陷阱 - Python 的 `json.dumps` 默认会添加空格（`{"key": "val"}`）。使用 `separators=(",", ":")` 以匹配 JavaScript 的紧凑输出（`{"key":"val"}`）。 - 始终对**所有**上下文字段（`_token` 除外）进行签名。Gateway 网关会移除 `_token`，然后对剩余所有字段签名。仅签名部分字段会导致验证静默失败。 - 使用 `sort_keys=True`——Gateway 网关会在签名前对键进行排序，而 Mattermost 在存储载荷时可能会重新排列上下文字段。 - 从 Bot 令牌派生密钥（确定性方式），不要使用随机字节。创建按钮的进程和执行验证的 Gateway 网关必须使用相同的密钥。
## 目录适配器 Mattermost 插件包含一个目录适配器，可通过 Mattermost API 解析频道和用户名。这样即可在 `openclaw message send` 和定时任务/webhook 投递中使用 `#channel-name` 和 `@username` 目标。 无需配置——适配器使用账户配置中的 Bot 令牌。 ## 多账户 Mattermost 支持在 `channels.mattermost.accounts` 下配置多个账户： ```json5 { channels: { mattermost: { accounts: { default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" }, alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" }, }, }, }, } ``` 账户值会覆盖顶层字段；未指定账户时，`channels.mattermost.defaultAccount` 决定使用哪个账户。 ## 故障排查
频道中没有回复 确保 Bot 已加入频道并提及它（oncall），使用触发前缀（onchar），或设置 `chatmode: "onmessage"`。
身份验证或多账户错误 - 检查 Bot 令牌、基础 URL，以及账户是否已启用。 - 多账户问题：环境变量仅适用于 `default` 账户。 - 私有/LAN Mattermost 主机需要设置 `network.dangerouslyAllowPrivateNetwork: true`（SSRF 防护默认阻止私有 IP）。
原生斜杠命令失败 - `Unauthorized: invalid command token.`：OpenClaw 未接受回调令牌。常见原因： - 斜杠命令注册失败，或在启动时仅完成了部分注册 - 回调请求发送到了错误的 Gateway 网关/账户 - Mattermost 中仍有旧命令指向之前的回调目标 - Gateway 网关重启后未重新激活斜杠命令 - 如果原生斜杠命令停止工作，请检查日志中是否有 `mattermost: failed to register slash commands` 或 `mattermost: native slash commands enabled but no commands could be registered`。 - 如果省略了 `callbackUrl`，且日志警告回调解析到了类似 `http://localhost:18789/...` 的环回 URL，那么仅当 Mattermost 与 OpenClaw 运行在同一主机/网络命名空间中时，该 URL 才可能可访问。请改为显式设置可从外部访问的 `commands.callbackUrl`。
按钮问题 - 按钮显示为空白框或完全不显示：按钮数据格式错误。每个呈现按钮都需要 `label` 和 `value`（缺少任一字段的按钮都会被丢弃）。 - 按钮可以显示，但点击后无反应：确认 Mattermost 服务器能够访问 Gateway 网关、Mattermost 服务器 IP 已包含在 `channels.mattermost.interactions.allowedSourceIps` 中（未配置时仅接受环回地址），并且对于私有目标，`ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机。 - 点击按钮时返回 404：按钮的 `id` 可能包含连字符或下划线。Mattermost 的操作路由器无法处理非字母数字 ID。仅使用 `[a-zA-Z0-9]`。 - Gateway 网关记录 `rejected callback source`：点击请求来自 `interactions.allowedSourceIps` 之外的 IP。将 Mattermost 服务器或入口加入允许列表，并在反向代理后设置 `gateway.trustedProxies`。 - Gateway 网关记录 `invalid _token`：HMAC 不匹配。检查是否对所有上下文字段（而非部分字段）签名、是否对键排序，以及是否使用紧凑 JSON（无空格）。请参阅上方的 HMAC 部分。 - Gateway 网关记录 `missing _token in context`：按钮上下文中不存在 `_token` 字段。构建集成载荷时，请确保包含该字段。 - Gateway 网关以 `Unknown action` 拒绝点击：`context.action_id` 与帖子上任何操作的 `id` 都不匹配。请将二者设置为相同的清理后值。 - 智能体不提供按钮：将 `capabilities: ["inlineButtons"]` 添加到 Mattermost 频道配置中。
## 相关内容 - [频道路由](https://funcoding.ai/agents/openclaw/channels/channel-routing/)——消息的会话路由 - [渠道概览](https://funcoding.ai/agents/openclaw/channels/)——所有支持的渠道 - [群组](https://funcoding.ai/agents/openclaw/channels/groups/)——群聊行为和提及门控 - [配对](https://funcoding.ai/agents/openclaw/channels/pairing/)——私信身份验证和配对流程 - [安全性](https://funcoding.ai/agents/openclaw/gateway/security/)——访问模型和安全加固