网关与 Webhook 配置
单一发送方。指定一台稳定主机（小 VM、跳板或专用 Mac）运行 OpenClaw 网关进程，由它独占对外的 IM 集成；构建节点不要直连 Mattermost，而是把事件推入队列，思路与 共享构建 Webhook 通知 一致。
创建入站 Webhook。在 Mattermost：集成 → 入站 Webhook，选定团队与频道，复制形如 https://<host>/hooks/<token> 的 URL。路径中的 token 即等同密码的 Bearer，任何能 POST 的人都能往频道发帖。
网关侧接线。使用 Content-Type: application/json，最小正文示例：{"text": "main 分支构建成功"}。需要卡片化展示时可使用 attachments，并保留简短 text 作移动端回退。正文过大易返回 400，日志摘要请放在 run_url 链接后而非整段粘贴。
连通性与 TLS。在网关 shell 用 curl 对 Webhook 发探测 JSON，确认返回 2xx；若经 HTTP 代理，与 OpenClaw 服务使用相同的 HTTPS_PROXY。超时与并发请与 网关限流与会话并发 对齐，避免慢响应拖死队列消费者。
- 调试日志只打 Mattermost 主机名与 token 片段末四位，禁止打印完整 URL。
- 测试与生产使用不同 Webhook，避免测试流水线刷屏业务频道。
多节点状态聚合最小步骤
步骤 1 — 入站规范化。每台 MeshMac worker 在任务结束时发出紧凑 JSON，至少包含：workflow、state（成功/失败/取消）、branch、短 commit、run_url、mesh_node_id（主机名或池标签）、provider_run_id（GitHub/GitLab 等运行 ID）。
步骤 2 — 按状态迁移发帖。仅在从「运行中」进入终态时触发 Mattermost，而不是逐行日志推送。若多节点报告同一 provider_run_id，网关在去重后再调用 Webhook，退避策略可参考 任务队列与重试步骤。
步骤 3 — 故障转移说明。若存在双网关或热备，文档写明哪一进程持有 Webhook、切换时如何避免双写，与 集群权限与故障转移 一并演练。
| 字段 | 在 Mattermost 中的价值 |
|---|---|
mesh_node_id | 标明池内哪台 Mac 执行，便于排查环境差异。 |
provider_run_id + state | 稳定冪等键，抑制重试导致的重复帖子。 |
run_url | 一键打开完整日志，频道内保持简短。 |
令牌与最小权限
Incoming Webhook 没有独立 HMAC 头，URL 机密即密钥。建议路径如 /etc/openclaw/secrets.d/mattermost/build-status.url，权限 0440，进程用户属专用组，与 密钥与 MeshMac 节点最小权限 一致；交互开发者与 CI 用户不应在该组内。
勿为「省事」把个人访问令牌与 Webhook 混用；若确需 Mattermost REST（如线程回复），为 bot 单独建最小频道权限并分文件存放，与 Webhook 文件隔离。
轮换：在 Mattermost 新建 Webhook → 更新网关秘密文件 → 重载服务 → 发测试消息 → 删除旧集成。节奏可与 频道告警与 IM 令牌轮换 同一运维日历。
收不到消息排查 FAQ
| 现象 | 排查要点 |
|---|---|
| CI 绿但频道空 | 查网关是否记录出站 POST 与 HTTP 状态（不能只看流水线成功）；用最小 JSON 在网关本机复现；确认集成未被删、频道仍存在。 |
| HTTP 400 | JSON 非法、缺 text（在所需 schema 下）、或负载超服务器限制；缩小附件与正文长度。 |
| HTTP 403 / 404 | Token 已轮换或集成已删；团队/频道迁移后需换新 URL 并更新秘密文件。 |
| 仅部分 Mac「丢」通知 | 可能仍直连 Mattermost 或绕过代理；强制仅网关出站并去掉各节点例外。 |
| 间歇重复帖子 | 无冪等重试：对 provider_run_id+state 去重后再发帖。 |
下一步（公开页）
多节点只加构建位，频道保持单一真相源
队列同步密钥与网关出站策略后，池化扩容不必复制 Mattermost Webhook；选型与工单请走公开页。