OpenClaw从入门到应用——频道：Mattermost

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》Plugin requiredMattermost 以插件形式提供不捆绑在核心安装包中。通过 CLInpm 仓库安装openclaw pluginsinstallopenclaw/mattermost本地检出从 git 仓库运行时openclaw pluginsinstall./extensions/mattermost如果在配置/引导期间选择了 Mattermost 并且检测到 git 检出OpenClaw 会自动提供本地安装路径。详细信息插件Quick setup安装 Mattermost 插件。创建一个 Mattermost 机器人账户并复制机器人令牌。复制 Mattermost基础 URL例如https://chat.example.com。配置 OpenClaw 并启动网关。最小配置{ channels: { mattermost: { enabled: true, botToken: mm-token, baseUrl: https://chat.example.com, dmPolicy: pairing, }, }, }Native slash commands原生斜杠命令为可选启用。启用后OpenClaw 通过 Mattermost API 注册oc_*斜杠命令并在网关 HTTP 服务器上接收回调 POST。{ channels: { mattermost: { commands: { native: true, nativeSkills: true, callbackPath: /api/channels/mattermost/command, // 当 Mattermost 无法直接访问网关时使用反向代理/公网 URL。 callbackUrl: https://gateway.example.com/api/channels/mattermost/command, }, }, }, }说明native: auto对于 Mattermost 默认为禁用。设置native: true以启用。如果省略callbackUrlOpenClaw 会根据网关主机/端口 callbackPath推导出一个。对于多账户设置commands可以在顶层或channels.mattermost.accounts.account.commands下设置账户值会覆盖顶层字段。命令回调使用每个命令的令牌进行验证令牌校验失败时请求会被拒绝。可达性要求回调端点必须能从 Mattermost 服务器访问。除非 Mattermost 与 OpenClaw 运行在同一主机/网络命名空间中否则不要将callbackUrl设置为localhost。除非该 URL 将/api/channels/mattermost/command反向代理到 OpenClaw否则不要将callbackUrl设置为你的 Mattermost 基础 URL。快速检查curl https://your-gateway/api/channels/mattermost/commandGET 请求应从 OpenClaw 返回405 Method Not Allowed而不是404。Mattermost 出站白名单要求如果你的回调目标指向私有/tailnet/内部地址请将回调主机/域名添加到 Mattermost 的ServiceSettings.AllowedUntrustedInternalConnections中。使用主机/域名条目而不是完整的 URL。正确gateway.tailnet-name.ts.net错误https://gateway.tailnet-name.ts.netEnvironment variables (default account)在网关主机上设置以下环境变量如果你更喜欢环境变量MATTERMOST_BOT_TOKEN...MATTERMOST_URLhttps://chat.example.com环境变量仅适用于默认账户default。其他账户必须使用配置值。Chat modesMattermost 会自动响应私信。频道行为由chatmode控制oncall默认仅在频道中被 提及 时响应。onmessage响应频道中的每条消息。onchar当消息以触发前缀开头时响应。配置示例{ channels: { mattermost: { chatmode: onchar, oncharPrefixes: [, !], }, }, }说明onchar仍然会响应显式的 提及。对于旧配置channels.mattermost.requireMention仍然有效但推荐使用chatmode。Threading and sessions使用channels.mattermost.replyToMode来控制频道和群组回复是留在主频道中还是以触发消息为根开启一个会话线程。off默认仅当入站消息已在某个线程中时才在线程中回复。first对于顶层的频道/群组消息在该消息下开启一个线程并将对话路由到线程范围的会话。all目前对于 Mattermost 与first行为相同。私信忽略此设置保持非线程模式。配置示例{ channels: { mattermost: { replyToMode: all, }, }, }说明线程范围的会话使用触发消息的帖子 ID 作为线程根。first和all目前等效因为一旦 Mattermost 有了线程根后续的消息块和媒体都会继续在同一线程中发送。Access control (DMs)默认channels.mattermost.dmPolicy pairing未知发送者会收到配对码。批准方式openclaw pairing list mattermostopenclaw pairing approve mattermost 用户ID公开私信channels.mattermost.dmPolicyopen加上channels.mattermost.allowFrom[*]。Channels (groups)默认channels.mattermost.groupPolicy allowlist受提及限制。使用channels.mattermost.groupAllowFrom来允许列表中的发送者推荐使用用户 ID。username匹配是可变的并且仅在channels.mattermost.dangerouslyAllowNameMatching: true时启用。开放频道channels.mattermost.groupPolicyopen仍受提及限制。运行时注意如果完全缺少channels.mattermost配置运行时会回退到groupPolicyallowlist进行群组检查即使设置了channels.defaults.groupPolicy。Targets for outbound delivery在openclaw message send或 cron/webhook 中使用以下目标格式channel:频道ID用于频道user:用户ID用于私信username用于私信通过 Mattermost API 解析裸露的不透明 ID如64ifufp...在 Mattermost 中是有歧义的用户 ID 还是频道 ID。OpenClaw 按用户优先方式解析如果该 ID 作为用户存在GET /api/v4/users/id成功OpenClaw 通过/api/v4/channels/direct解析直接频道来发送私信。否则该 ID 被视为频道 ID。如果需要确定性行为请始终使用显式前缀user:/channel:。Reactions (message tool)使用message actionreactchannelmattermost。messageId是 Mattermost 帖子 ID。emoji接受名称如thumbsup或:1:冒号可选。设置removetrue布尔值以移除反应。添加/移除反应的事件会作为系统事件转发给路由到的代理会话。示例message actionreact channelmattermost targetchannel:频道ID messageId帖子ID emojithumbsup message actionreact channelmattermost targetchannel:频道ID messageId帖子ID emojithumbsup removetrue配置channels.mattermost.actions.reactions启用/禁用反应操作默认为 true。按账户覆盖channels.mattermost.accounts.account.actions.reactions。Interactive buttons (message tool)发送带有可点击按钮的消息。当用户点击按钮时代理会收到选择并可以响应。通过将inlineButtons添加到频道能力中来启用按钮{ channels: { mattermost: { capabilities: [inlineButtons], }, }, }使用message actionsend并附带buttons参数。buttons是一个二维数组按钮的行message actionsend channelmattermost targetchannel:频道ID buttons[[{text:Yes,callback_data:yes},{text:No,callback_data:no}]]按钮字段text必需显示标签。callback_data必需点击时发送回的值用作操作 ID。style可选default、primary或danger。当用户点击按钮时所有按钮会被替换为确认行例如 “✓Yesselected by user”。代理将收到的选择作为入站消息并响应。说明按钮回调使用 HMAC-SHA256 验证自动无需配置。Mattermost 会从其 API 响应中剥离回调数据安全特性因此点击后所有按钮都会被移除 —— 无法部分移除。包含连字符或下划线的操作 ID 会被自动清理Mattermost 路由限制。配置channels.mattermost.capabilities能力字符串数组。添加inlineButtons以在代理系统提示中启用按钮工具描述。channels.mattermost.interactions.callbackBaseUrl按钮回调的可选外部基础 URL例如https://gateway.example.com。当 Mattermost 无法直接访问网关的绑定主机时使用。在多账户设置中也可以在channels.mattermost.accounts.account.interactions.callbackBaseUrl下设置相同字段。如果省略interactions.callbackBaseUrlOpenClaw 会从gateway.customBindHostgateway.port推导回调 URL然后回退到http://localhost:port。可达性规则按钮回调 URL 必须能从 Mattermost 服务器访问。localhost仅在 Mattermost 和 OpenClaw 运行在同一主机/网络命名空间时有效。如果你的回调目标是私有/tailnet/内部地址请将其主机/域名添加到 Mattermost 的ServiceSettings.AllowedUntrustedInternalConnections中。Direct API integration (external scripts)外部脚本和 webhook 可以通过 Mattermost REST API 直接发送按钮而不必经过代理的message工具。尽可能使用扩展中的buildButtonAttachments()如果发送原始 JSON请遵循以下规则负载结构{ channel_id: 频道ID, message: 选择一个选项, props: { attachments: [ { actions: [ { id: mybutton01, // 仅限字母数字 —— 见下文 type: button, // 必需否则点击会被静默忽略 name: Approve, // 显示标签 style: primary, // 可选default、primary、danger integration: { url: https://gateway.example.com/mattermost/interactions/default, context: { action_id: mybutton01, // 必须与按钮 id 匹配用于名称查找 action: approve, // ... 任意自定义字段 ... _token: , // 见下面的 HMAC 部分 }, }, }, ], }, ], }, }关键规则附件放在props.attachments中而不是顶层的attachments后者会被静默忽略。每个 action 都需要type: button—— 没有它点击会被静默丢弃。每个 action 都需要id字段 —— Mattermost 会忽略没有 ID 的 action。Action 的id必须是仅字母数字[a-zA-Z0-9]。连字符和下划线会破坏 Mattermost 服务端的 action 路由返回 404。使用前请去除它们。context.action_id必须与按钮的id匹配这样确认消息才会显示按钮名称例如 “Approve”而不是原始 ID。context.action_id是必需的 —— 没有它交互处理程序会返回 400。HMAC 令牌生成网关使用 HMAC-SHA256 验证按钮点击。外部脚本必须生成与网关验证逻辑匹配的令牌从机器人令牌派生密钥HMAC-SHA256(keyopenclaw-mattermost-interactions, databotToken)构建包含所有字段的 context 对象除去_token。使用排序键且无空格序列化网关使用带排序键的JSON.stringify生成紧凑输出。签名HMAC-SHA256(keysecret, dataserializedContext)将得到的十六进制摘要作为_token添加到 context 中。Python 示例importhmac,hashlib,json secrethmac.new(bopenclaw-mattermost-interactions,bot_token.encode(),hashlib.sha256).hexdigest()ctx{action_id:mybutton01,action:approve}payloadjson.dumps(ctx,sort_keysTrue,separators(,,:))tokenhmac.new(secret.encode(),payload.encode(),hashlib.sha256).hexdigest()context{**ctx,_token:token}常见 HMAC 陷阱Python 的json.dumps默认会添加空格{key: val}。使用separators(,, :)以匹配 JavaScript 的紧凑输出{key:val}。始终签名所有context 字段除去_token。网关会剥离_token然后签名所有剩余字段。签名子集会静默导致验证失败。使用sort_keysTrue—— 网关在签名前会排序键而且 Mattermost 在存储负载时可能重新排序 context 字段。从机器人令牌派生密钥确定性而不是随机字节。创建按钮的进程和验证的网关必须使用相同的密钥。Directory adapterMattermost 插件包含一个目录适配器通过 Mattermost API 解析频道和用户名称。这允许在openclaw message send以及 cron/webhook 投递中使用#频道名称和用户名目标。无需配置 —— 适配器使用账户配置中的机器人令牌。Multi-accountMattermost 支持在channels.mattermost.accounts下配置多个账户{ 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 }, }, }, }, }Troubleshooting频道中没有回复确保机器人在频道中并提及它oncall使用触发前缀onchar或设置chatmode: onmessage。认证错误检查机器人令牌、基础 URL 以及账户是否启用。多账户问题环境变量仅适用于default账户。按钮显示为白框代理可能发送了格式错误的按钮数据。检查每个按钮是否同时具有text和callback_data字段。按钮渲染但点击无反应验证 Mattermost 服务器配置中的AllowedUntrustedInternalConnections是否包含127.0.0.1 localhost并且ServiceSettings中的EnablePostActionIntegration是否为true。按钮点击返回 404按钮的id很可能包含连字符或下划线。Mattermost 的 action 路由器在非字母数字 ID 上会出问题。请仅使用[a-zA-Z0-9]。网关日志显示invalid _tokenHMAC 不匹配。检查你是否签名了所有 context 字段不是子集、使用了排序键、使用了紧凑 JSON无空格。请参见上面的 HMAC 部分。网关日志显示missing _token in context_token字段不在按钮的 context 中。确保在构建 integration 负载时包含了它。确认消息显示原始 ID 而不是按钮名称context.action_id与按钮的id不匹配。将两者设置为相同的清理后的值。代理不知道按钮在 Mattermost 频道配置中添加capabilities: [inlineButtons]。