OpenClaw 入站 Webhook 實戰（2026）：GitHub 與 Slack 的 HMAC 原始報文驗證、重放視窗、macOS 閘道演練與雲端 Mac mini

當你在 macOS 上對外開放 OpenClaw 閘道以接收 Slack、GitHub 或內部機器人回呼，2026 年最常見的「靈異現象」往往不是模型延遲，而是簽章邏輯看似正確卻與廠商位元組流不一致：中介層先 JSON.parse 再序列化，導致 X-Hub-Signature-256 永遠對不起來；或簽章通過卻沒有重放控制，同一筆推送在重試風暴裡把靜態資源改了兩次。本文說明如何在原始本文上計算 HMAC、如何把重放視窗寫成可稽核的秒級策略、如何把 NTP 漂移與 Slack 的時間戳驗簽綁在一起，並如何搭配 冪等鍵與去重 吸收廠商的指數退避。延伸閱讀 Webhook 驅動 Ollama 的接線範式、doctor 診斷 與 JWT／TLS 時鐘漂移，它們與入站安全共用同一條排障時間軸。

讀完你會拿到一組在平台審查裡站得住腳的數字：300 秒作為多數即時通訊回呼的起步重放容忍，600 秒面向 GitHub 等可能在事故窗延遲抵達的重試；以及一張可直接貼進變更單的演練清單。若需要與生產 launchd 行為一致的演練主機，可參考 MacHTML 公開定價裡約 16.9 美元／天 的 Apple Silicon Mac mini 雲端節點，把高壓回放與筆電睡眠策略解耦。

入站自動化的威脅模型

OpenClaw 一旦接通寫倉庫、跑建置或批次改寫 HTML／CSS 的工具鏈，每一次未鑑別的 POST 都是潛在的供應鏈風險面。簽章驗證是必要條件而非充分條件：外洩的 webhook secret 仍可被濫用，因此金鑰輪替、最小權限工具白名單與網路層 IP 限制必須並行。建議至少假設三類對手：對公網 URL 掃段的腳本、在事故復盤裡重放擷取資料的內部人員、以及在上游遭入侵後利用合法簽章重投的自動化重試。

釐清哪些路徑面向瀏覽器 CORS、哪些只接受機器對機器 Webhook，不要把兩類流量混在同一監聽埠上——否則容易出現「為了前端偵錯放寬跨域」卻與 HMAC 無關的橫向風險。若財務允許，可為 hooks.internal.example 單獨子網域疊加 mTLS 或固定出口 IP 白名單，把 OpenClaw 的暴露面收斂到安全域可觀測的範圍內。

原始 body 紀律與 JSON 解析順序

主流簽章演算法定義在位元組序列上，而不是解析後的物件。若 Express、Hono 或 Fastify 在驗簽前呼叫 JSON.parse，再以不同格式化選項寫回字串，即便語意 JSON 完全一致，sha256= 前綴後的十六進位也不會匹配。工程解法是顯式暴露 rawBody 緩衝：先驗簽、再解析。閘道前若還有 nginx，確認沒有在 Webhook 路徑上疊多餘的 sub_filter 或意外雙重 gzip，否則終端應用雜湊的位元組流與廠商簽名時並不一致。

排障階段可記錄 Content-Length 與對原始 body 加鹽後的摘要指紋，嚴禁把完整客戶 HTML 或金鑰寫進日誌。把筆電、CI 與租用 mini 三處指紋對齊，往往比肉眼比對十六進位更快定位「只有生產驗簽飄紅」的根因。

GitHub、Slack 與通用 HMAC 標頭

GitHub 使用 X-Hub-Signature-256，值為 sha256= 加十六進位摘要。去掉前綴後對 body 做 HMAC-SHA256，並以恆定時間比對。GitHub 同時提供 X-GitHub-Delivery，極適合作為冪等鍵：TTL 建議覆蓋官方重試視窗，內部 SRE 常把熱儲存視窗放在 48 至 72 小時 量級，再依合規要求歸檔冷資料。

Slack 對字串 v0:{timestamp}:{body} 做 HMAC-SHA256，再把結果 Base64 寫入 X-Slack-Signature。時間戳必須落在廠商允許的分鐘級偏差內，這直接把驗簽與主機時鐘綁定。企業協作工具各有變體，務必依官方文件實作一廠商一模組，避免 OpenClaw 路由層繞過硬編碼檢查。

自研回呼常見 X-Signature 十六進位形式。設定檔應白名單允許的演算法族，2026 年仍應拒絕呼叫端自選 md5 之類的弱摘要。HTTP 狀態碼上，格式錯誤與金鑰錯誤都會洩漏資訊，需分別限流：格式類回 400 並記錄低基數指標，金鑰類回 401／403 並觸發告警。

重放視窗決策表

即便 HMAC 完全正確，攻擊者只要在視窗內重放擷取到的合法報文，仍可能觸發二次副作用。視窗越窄越安全，但佇列抖動會把真流量誤殺。下表給出 OpenClaw 維運常見的第一版參數，後續請以你們實測的投递 p95 偏差迭代。

來源類型	建議首版視窗	備註
Slack Events	300 秒	與時間戳標頭強耦合，必須配 NTP 巡檢。
GitHub 儲存庫 Webhook	600 秒	事故期重試可能偏晚，用 Delivery ID 去重。
內網任務系統	120 秒	同機房低延遲，可收緊。
未知 SLA 的 SaaS 夥伴	900 秒	Redis 記憶體壓力上升，需成本評估。

任何調整都要同步到與防火牆規則同級的維運手冊，避免安全組與閘道各自假設不同的秒數。另：若 nginx proxy_read_timeout 設為 120 秒，卻把重放容忍寫到 300 秒，夥伴側會先逾時再重試，形成「驗簽看似正常但業務永遠排隊」的假性故障。

時鐘漂移與時間戳驗簽

Slack 方案把 Unix 時間戳寫進待簽名字串。若 Mac mini 相對標準時間漂移超過五分鐘，合法事件會被拒，而一線往往誤怪 OpenClaw 升級。請落實 NTP 與 JWT 專文 中的 timed 巡檢腳本，把絕對偏移連續兩次超過 2 秒 作為告警閾值——比一般桌面建議更嚴，因為 Webhook 驗簽對時間更敏感。使用者層級 LaunchAgent 若在筆電上跑，睡眠喚醒會迅速放大漂移，這也是團隊願意把閘道放到常電 mini 上的現實原因之一。

Redis TTL 與冪等指紋

驗簽與時間窗通過後，應在入隊工具任務前寫入投递指紋，使用 SET key NX EX ttl 避免併發雙消費。TTL 取「重放視窗」與「廠商重試文件」二者較大值；若對客承諾 48 小時 冪等，而 Redis 只保留 6 小時，就會在合規上自相矛盾。具體鍵設計與稽核欄位可參考 閘道冪等鍵專文。記憶體方面：100 萬筆活躍鍵、每筆約 100 位元組 粗算已是 100 MB 量級，對 16 GB 統一記憶體的 Mac mini 可控，但要在監控裡單獨追蹤驅逐次數。

nginx 終止 TLS 與二次解壓陷阱

常見拓撲是 nginx 對外終止 TLS，再轉明文到本機 127.0.0.1:8787。請確認 Webhook 路由未啟用會改寫 body 的模組，合理設定 client_max_body_size 以覆蓋最大 JSON 推送，並把 $request_length 尖峰與業務錯誤分開打點。若 gzip 在 nginx 與 Node 兩側各解壓一次，最終參與雜湊的位元組可能與 GitHub 簽名時不一致，表現為「間歇性驗簽失敗」。健康檢查路徑應與 Webhook 路徑隔離限流，避免大型儲存庫 push 時把合成探針一併衝垮。

curl 固定樣本與三輪探針

把帶簽章的樣本放進私有儲存庫而非公開 gist，用 curl --data-binary @payload.json 複現，以確保換行與廠商一致。務必帶上與線上一致的 Content-Type。基礎設施調整後至少跑三輪：合法簽章、竄改 body 但保留舊簽章（應失敗）、過期時間戳（應失敗且指標分桶不同）。把這些探針與 doctor 退出碼接入同一套看板，值班同仁只需盯一條時間軸。

# 範例骨架——請替換 URL、標頭與 sha256= 摘要
curl -sS -X POST 'https://hooks.staging.example/openclaw/github' \
  -H 'Content-Type: application/json' \
  -H 'X-GitHub-Delivery: test-delivery-001' \
  -H 'X-Hub-Signature-256: sha256=REPLACE' \
  --data-binary @fixtures/push-main.json

上線前檢查清單

1. 凍結 OpenClaw 版本並把 openclaw doctor 輸出 JSON 歸檔。
2. 對 1000 次合成投递蒐集基線 p95 延遲。
3. 先以「只記錄不攔截」模式運行 24 小時，統計本會被拒的樣本。
4. 切換強制驗簽，觀察錯誤預算，並保留一鍵回退到只記錄模式。
5. 金鑰雙活輪替：至少 15 分鐘 內新舊 secret 同時接受。
6. 把 curl 樣本、nginx diff 與變更單號綁定，便於稽核追溯。

常見問題

Webhook 與瀏覽器 SPA 能共用埠嗎？

技術上可以，工程上不建議：分流監聽才能分別做防火牆與限流策略。

驗簽失敗應回什麼狀態碼？

多用 401／403；盡量避免誤用 500，以免觸發廠商不同的退避曲線。

有了 HMAC 還需要 CSRF 嗎？

Webhook 通道不需要瀏覽器 CSRF 權杖，但任何人類可點的管理後台仍要保留 CSRF 防護。

Apple Silicon Mac mini 在輕載常開情境下整機 idle 功耗常被引用在約 6–12 瓦區間，適合作為夜間佇列消費者而不打擾辦公環境；macOS 與多數團隊既有腳本（launchd、鑰匙圈彈窗、Safari 冒煙）一致，能讓驗簽行為在預發與生產對齊。MacHTML 提供的雲端租賃節點支援 SSH 批次重放 curl 樣本，也可在需要人工點授權時用 VNC 介入，避免讓筆電在飯店網路裡通宵值守。專案結束後按天彈性縮容，而不是為三年折舊背一台多數時間閒置的機器。

若你的路線把 HTML／CSS 稽核與聊天審批串在一起，請把閘道放在離程式碼倉更近的區域，並把 Webhook 安全做得「無聊卻可靠」：原始位元組、明確秒級視窗、可觀測的冪等與 doctor 健康檢查。這樣 OpenClaw 才能從演示走向資安團隊願意簽字的基礎設施。