網關安裝與令牌
選一台穩定入口機（或內網穿透後的固定位址）跑 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，確認房間出現訊息。 - 在房間主題或 Runbook 約定：每則通知攜帶
mesh_node_id，讓多節點協作時一眼看出由哪台建置機回報。
若你同時維護非 Matrix 的共用建置 Webhook，可與 多節點共用建置 Webhook 設定 中的驗簽、佇列寫法交叉參考，維持同一套冪等與重試策略。
訊息簽章或最小權限校驗
所有進入網關的 POST 都應驗真：優先對原始請求本文計算 HMAC-SHA256，與請求標頭中的簽章做常數時間比對；若 CI 平台不支援 HMAC，可退化為 Bearer 密鑰並搭配CI 出口 IP 白名單。拒絕時間戳過舊（例如超過 5 分鐘）的請求以防重放。
Matrix 側權限壓到最小：僅允許向指定建置房間發訊息，禁止任意邀請、建房或管理使用者。Authorization 標頭不要打進應用日誌；驗簽邏輯只放在網關，不要在每台遠端 Mac 上重複暴露密鑰。如此即使某節點遭入侵，也不致拖垮整個 Matrix 帳戶面。
與 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 編排文。