OpenClaw 閘道死信佇列與工具呼叫安全重播（2026）：毒訊息隔離、契約漂移、冪等 drain、與熔斷器和指標協同，以及在雲端 Mac mini 上的 macOS 演練

當智慧代理閘道把流量扇出到大量 HTTP 工具，總會遇到內聯指數退避無法化解的失敗：參數永遠無法通過 JSON Schema、上游在憑證輪替期間連續回 5xx、或租戶政策禁止自動重試寫入。到 2026 年，成熟的 OpenClaw 部署會把這些終態失敗隔離進死信佇列（DLQ），讓 SRE 在受控吞吐下檢視、修正並重播，而不是讓熱路執行緒池被毒訊息占滿。本文說明入隊條件、信封欄位、與 冪等鍵與去重 的銜接、與 熔斷器 的 drain 協同、該在 Prometheus 上暴露哪些深度與成功率指標，以及如何用 日誌脫敏與輪替 保留稽核價值。

成本觀點：在 MacHTML 以約 每天 16.9 美元 租用專用 Mac mini 預演死信 drain，比正式環境因重複重播導致重複扣款或 CRM 雙寫的事故便宜一個數量級。

為何僅有重試佇列不足

重試佇列假設故障會在秒級解除；但合作夥伴灰度改名欄位、向量庫分片再平衡時連續 12 分鐘 500、或企業出口突然封鎖網域，都會讓「無限重試」變成放大器。若失敗請求仍占用 worker，模型串流會被拖慢，記憶體中懸掛的 trace 與緩衝也會提高 OOM 風險。把終態與未知類型錯誤轉入 DLQ，可把熱路徑從「等待一個可能永不成功的上游」解放出來。

實務閾值（起步參考）：對冪等讀介面，內聯重試不超過 3 次、總視窗 2.5 秒；超過仍失敗則依錯誤類分流。對缺少冪等鍵的寫入，要嘛快速回傳結構化錯誤給規劃器，要嘛進入需人工簽核的死信分割區，絕不可默默迴圈。

OpenClaw 單次規劃可能平行觸發六個工具：務必為每個工具劃分 DLQ 分割區（依 tool_name + 租戶），避免 CRM 毒包阻塞健康計算機工具的 drain。

毒訊息與 Schema 拒收

毒訊息指不改程式或資料就永遠不會成功的載荷：閘道 JSON Schema 驗證失敗、被出口政策拒絕的 URL、或指向已下線能力的工具名。應立即標記 failure_class（如 SCHEMA_REJECT、EGRESS_DENY），並附上原始 request_id 以利客服工單對齊。

契約漂移要記錄 tool_contract_version，例如 20260425.3，並在維運手冊寫明「若版本早於 14:00 UTC 的熱修復，優先嘗試自動重播」。常見留存 14 天、單分割區磁碟預算 500 MB；逾自動 tombstone，同時遞增 dlq_expired_total 以滿足刪除證明與統計。

批次索引若 100 筆中 5 筆驗證失敗，應以列層級拆死信，避免整批回滾拖累其餘 95 筆成功路徑。

死信信封欄位

信封至少含：tenant_id、request_id、idempotency_key 或顯式空值、tool_name、tool_version、first_seen_at、last_error_code、retry_count、failure_class，以及限幅 4 KB 的脫敏 HTTP 標頭副本。正文超過 256 KB 應寫物件儲存指標，避免 Redis 或 Kafka 單則過大阻塞複寫。

{
  "dlq_version": 1,
  "request_id": "req_9f2c…",
  "idempotency_key": "idem_7a91…",
  "tool": {"name": "crm_search", "contract": "20260425.3"},
  "failure_class": "UPSTREAM_TIMEOUT",
  "retry_count": 3,
  "last_http_status": 504
}

權杖與重新整理憑證僅寫 Vault 參考路徑，由重播 worker 執行時再取，避免磁碟快照外洩。

重播安全與人工門檻

無冪等的重播等於主動製造雙寫發票。要嘛在 TTL（常見 24–72 小時）內重用原冪等鍵，要嘛簽發新鍵並寫 supersedes_request_id 讓下游辨識「有意二次執行」。人工 drain 建議從每條依賴每秒 1 則起步，若 5 分鐘內錯誤率低於 0.5% 再線性提速；並為併發加操作員級配額，避免兩位值班同時把吞吐加倍。

對資金／寫庫工具，可在信封要求雙人簽核旗標後才允許 worker 出隊；CI 觸發的自動重播應使用獨立服務帳號，金鑰 30 天輪替，指標標籤與人工 drain 分離。

與熔斷狀態機協同

熔斷開啟時盲目 drain 會對正在恢復的故障源二次投毒。正確順序是：觀察半開探測成功後，再啟用受控 drain，並在熔斷再次開啟時自動暫停且遞增 dlq_drain_paused_total。若上游回 429 並附 Retry-After，drain 端應如一般用戶端般尊重該標頭並加 250 毫秒 內抖動，避免多 worker 齊步走。

指標與 48 小時處置 SLO

至少匯出：dlq_depth 依工具分割區、dlq_ingress_total{failure_class}、dlq_replay_success_total、dlq_replay_failure_total、從首次失敗到成功重播的 dlq_age_seconds 直方圖、以及合規用 dlq_expired_total。示例 SLO：48 小時內 95% 死信要嘛成功重播要嘛被顯式處置；單一租戶 15 分鐘內深度超 10000 多半代表上游大面積事故被誤判為用戶端錯誤。

日誌、脫敏與留存

每次重播紀錄操作者、時間戳、新舊冪等鍵與參數 diff（脫敏後）。搭配 newsyslog 或 logrotate 將單檔限制 50 MB、保留 7 代，可與 DLQ 留存對齊，便於事故週後期仍能關聯。

對照：熱重試 / DLQ / 發件箱

維度	熱重試佇列	死信佇列	交易式發件箱
延遲預算	毫秒級	分鐘到數天	受資料庫提交約束
人工介入	少見	預期流程	可選
順序語意	依 key 近似有序	分割區內 FIFO 近似	單寫者可較強一致
典型用途	短暫 5xx 浪湧	毒包、長中斷、政策凍結	對自有資料庫副作用的準一次遞送

值班 runbook

1. 對照訊息中介控制台與 dlq_depth，排除抓取間隔造成的假峰值。
2. 隨機抽樣 5 則，若 failure_class 一致，合併為單一根因工單。
3. 核對熔斷與錯誤預算，再開啟 drain。
4. 以每秒 1 則起步觀察 dlq_replay_failure_total。
5. 結束後匯出指標快照附到事故紀錄。

常見問題

死信與熱重試能共用 Redis 嗎？

可以共用機器，但應使用不同 key 前綴與記憶體淘汰策略，避免死信積壓擠掉熱重試中繼資料。

代理能自動重播嗎？

僅建議對唯讀且已證明冪等並有嚴格限速的工具；其餘需人工意圖以防自治迴圈。

可靠的死信流程一半在佇列設計，一半在可觀測性與演練。透過 MacHTML 租用 Mac mini，在原生 macOS 與生產相近的 LaunchAgent、磁碟配額與網路堆疊上預演 broker、閘道與 Prometheus 邊車，可把 drain 劇本在真實 Safari 與桌面工具鏈旁驗熟，日成本仍約 16.9 美元，卻能顯著降低夜間事故的情緒與時間成本。