目標架構：從 Webhook 到多節點共享構建
建議把 Webhook 處理層放在「薄閘道」：只做驗證、鑑權、限速與記錄，通過後將正規化後的任務描述丟給 OpenClaw 或中央佇列。實際編譯與腳本跑在 MeshMac 各節點的 worker 上，共享同一套 repo 快取與構建隔離目錄策略，避免互相覆寫。狀態則不要只留在單節點記憶體：應寫入共享狀態儲存（或事件匯流排），再由通用通知適配器（出站 HTTP、MQTT、企業 IM 的 Incoming Webhook 等）發給人類或下游系統。這樣任一節點完成或失敗，團隊看到的通知內容都一致。
對照表：Webhook 安全與觸發鏈各層建議
| 層次／能力 | 建議作法（通用、可審計） |
|---|---|
| 入參校驗 | JSON Schema 或白名單欄位；限制字串長度與巢狀深度；未知欄位可拒絕或剝離；錯誤回 400 並帶簡短 error_code |
| 鑑權 Token | Authorization: Bearer <token> 或自訂 X-Webhook-Secret；高安全場景用 HMAC-SHA256 本文簽名並校驗時間窗（防重放） |
| 與 OpenClaw 任務觸發 | 將校驗後本文映射為 task_type、payload、idempotency_key；寫入佇列或呼叫 OpenClaw 任務 API；回 202 或 200 附 job_id |
| 多節點狀態廣播／通知 | 狀態機：queued／running／success／failed；寫共享儲存後由通知服務訂閱變更，對 Slack／飛書／釘釘／Teams 等使用各平台 Incoming Webhook 或 Bot API（二選一即可） |
可複現配置步驟
- 契約先行。 與事件來源約定 JSON 欄位（例如
event、ref、actor），並在閘道實作 Schema 校驗與錯誤碼，避免髒資料進佇列。 - 鑑權上線。 在秘密管理（環境變數或密鑰庫）存放 Token／HMAC 金鑰；旋轉時支援新舊雙金鑰過渡；拒絕缺少或錯誤標頭的請求（
401／403）。 - 觸發 OpenClaw。 通過鑑權後組裝任務：帶上
BUILD_ID或idempotency_key，避免 Webhook 重送造成重複構建；寫入與各節點 worker 共用的後端。 - 多節點執行共享構建。 節點從同一佇列領取任務，工作目錄與產物路徑按任務 ID 隔離；節點標籤（例如
macos-14、xcode-16）可用於路由。 - 狀態與通知。 每個狀態轉移寫入共享儲存並發事件；通知服務讀取後以 HTTPS POST 送到 IM 或內部狀態 API，內容含
job_id、節點名、結束碼與日誌連結。 - 可觀測性。 為 Webhook 與出站通知保留 request_id、延遲與非 2xx 計數，便於對照下方 HTTP 表快速定位。
常見 HTTP 錯誤排查表
下列為 Webhook 閘道與下游 OpenClaw／佇列／通知鏈路上最常遇到的狀態碼與檢查方向。
| HTTP | 可能原因與排查 |
|---|---|
400 |
本文非 JSON、缺必填欄位、Schema 不符；檢查來源範例與伺服器校驗日誌是否一致 |
401 |
未帶 Token、Bearer 格式錯誤、金鑰已旋轉；比對 Authorization 與環境變數是否為同一組 |
403 |
Token 有效但無權限觸發該 event 或專案；檢查 IP 允許清單與簽名時間窗 |
404 |
Webhook 路徑錯誤或反向代理未轉發；用 curl 直連上游確認路由 |
408／連線逾時 |
上游 TLS 或防火牆慢；調整閘道與客戶端逾時，避免長任務阻塞 Webhook（應先 ACK 再非同步跑構建） |
413 |
本文過大；限制 payload 大小或改為只傳引用 ID、由 worker 再拉詳情 |
429 |
觸發過於頻繁；為來源與全局限流，並回傳 Retry-After |
502／504 |
反向代理後端不可用或逾時；檢查 OpenClaw／佇列服務健康與連線池 |
500 |
閘道或任務入佇列未捕獲例外；查應用日誌與追蹤 ID，確認非資料庫或序列化錯誤 |