网关安装与令牌
选一台稳定入口机（或内网穿透后的固定地址）跑 OpenClaw 网关，确保 Synapse 与 CI 出站都能访问其 HTTPS。设置 OPENCLAW_CONFIG_ROOT，配置与密钥不进 Git；构建 Worker 节点只消费队列或执行脚本，不挂载完整 Matrix 用户会话，避免令牌在多台远程 Mac 上扩散。
为「构建状态机器人」单独建用户，手动加入团队房间一次，将其访问令牌写入仅网关运行用户可读的密钥文件（建议权限 0440）。记录 homeserver 基址（与证书一致）、完整 room_id（不要只靠别名），并在日志里用 correlation_id 串联 CI → 网关 → Matrix。令牌轮换节奏可与站内 频道告警与令牌轮换 一文对照。多机场景下，通知应经统一网关与共享队列发出，具体拓扑见 多节点部署与任务队列同步，避免每台 Mac 各自直连 Matrix 造成时间线分裂。
Matrix Webhook/应用服务配置步骤
轻量起步可用「HTTP 入站 → 桥接/机器人」把 JSON 映射为 m.room.message；需要幽灵用户、多房间路由或事务型自动化时再上应用服务。
- 在反向代理上暴露 TLS 路径，例如
/hooks/matrix/build-status，staging 与 prod 使用不同路径或不同注册，防止环境串线。 - 在 Synapse 侧通过集成管理器填写 Webhook URL，或将
app_service_config_files指向你的注册 YAML。 - 应用服务 YAML 填写
id、url、as_token、hs_token、sender_localpart与合理命名空间（如专用前缀）。 - 重载 Synapse，从可信主机
curl发送带签名的样例 POST，确认房间出现消息。 - 在房间主题或运维文档中约定：每条通知携带
mesh_node_id，便于多节点协作时一眼看出由哪台构建机回报。
若你还负责非 Matrix 的共享构建 Webhook，可与 多节点共享构建 Webhook 配置 中的验签、队列写法交叉参考，保持同一套幂等与重试策略。
消息签名或最小权限校验
所有进入网关的 POST 都应验真：优先对原始请求体计算 HMAC-SHA256，与请求头中的签名做常量时间比较；若 CI 平台不支持 HMAC，可退化为 Bearer 密钥并配合CI 出口 IP 白名单。拒绝时间戳过旧（例如超过 5 分钟）的请求以防重放。
Matrix 侧令牌权限压到最小：仅允许向指定构建房间发送消息，禁止随意邀请、建房间或管理用户。Authorization 头不要打进应用日志；验签逻辑只放在网关，不要在每台远程 Mac 上重复暴露密钥。
与 CI 状态字段映射表
先把各 CI 提供商的 JSON 规范化为网关内部结构，再格式化为 Matrix 消息（纯文本或 Markdown），避免模板里直接嵌套未校验字段。
| CI 源字段（示例） | 网关内部键 | Matrix 消息用途 |
|---|---|---|
| workflow / pipeline 名称 | workflow | 首行加粗，标识哪条流水线 |
| status / conclusion | state | 映射为排队、运行中、成功、失败等（团队统一 emoji 规则） |
| head branch / ref | branch | 第二行区分发布分支与特性分支 |
| head sha / commit id | commit | 短 SHA + 链接到运行详情 |
| html_url / web_url | run_url | 可点击链接，便于跳转日志与制品 |
| runner 名或自定义标签 | mesh_node_id | 页脚标明多节点中具体构建机，无需 SSH 即可区分 |
收不到消息排错 FAQ
| 现象 | 优先排查 |
|---|---|
| CI 成功但房间无事件 | 房间 id/别名是否与令牌一致；bot 是否在房内；桥接是否丢弃空 body；结论字段是否为 null 导致模板跳过 |
| 应用服务报签名校验失败 | 磁盘 YAML 与 Synapse 内 hs_token/as_token 是否一致；密钥是否含多余换行；从 Synapse 主机 curl 网关排除 TLS 问题 |
| 仅部分节点有通知 | 各 Runner 是否仍指向旧 Webhook URL；出站是否被防火墙拦到非统一网关 |
| 同一运行多条重复消息 | 在网关用 run id + state 做短时去重（如 Redis/SQLite 窗口 60～72 小时） |
下一步（首页 / 购买 / 帮助 / 博客）
完成上述步骤后，多节点远程 Mac 上的构建状态应汇总到同一 Matrix 房间，协作者无需登录各机即可跟进。无需账号即可继续访问：首页（含购买与套餐说明）、帮助中心、博客列表，以及 OpenClaw 专栏 获取更多 MeshMac 编排文。
用一条时间线覆盖整个构建池
从首页了解远程 Mac 资源，在帮助中心查 SSH 与协作说明，在博客与 OpenClaw 专栏补齐队列、密钥与告警实践。