模型偏樂觀，基礎設施不能跟著賭。若讓代理在未經 Schema 護欄與硬超時的情況下呼叫 shell、HTTP 或儲存庫工具，一次錯誤迴圈就可能塞滿 worker、灌爆磁碟或對 API 集體撞牆。解法很樸素：執行前校驗參數、為長呼叫裝熔斷、在可預期的失敗模式後打開電路，並在凡有副作用之處共用同一套重試範本。

本文假設遠端 Mac 已安裝 OpenClaw，並以本機回環閘道承載 IDE 或無頭代理。導覽見首頁；安裝與權杖見說明中心 · OpenClaw 指南；獨立節點見購買頁（免登入瀏覽）。目錄與權限請與IDE 橋接沙箱與健康探針對齊：唯讀程式碼樹、可寫 scratch，避免驗證與重試日誌污染 Git。

閘道與技能目錄

可重現性始於「任何人複製路徑就能落地」。在遠端 Mac 上，將閘道狀態收斂到單一根目錄（例如 ~/.openclaw：設定、權杖、本機快取指標），版控技能置於 ~/openclaw-skills/<技能名>/，內含 skill.yaml 或 skill.json manifest，以及選用的 schemas/、scripts/ 子目錄。另保留 ~/openclaw-scratch/ 給結構化日誌、暫存酬載與探針輸出——切勿當成 Git 工作區根目錄。

  • 一技能一 manifest。宣告工具名稱、進入點、預設政策與 JSON Schema 檔案引用，讓 reviewer 能在 Git diff 裡對齊行為變更。
  • 機密分離。權杖放 0600 檔案，以 OPENCLAW_TOKEN_FILE 引用；manifest 只寫路徑，不內嵌 secret。
  • 行程管理。以 launchd KeepAlive 跑閘道，日誌輪替指向 ~/openclaw-scratch/logs/gateway.log，環境變數明確指向上述技能與 scratch——並把 plist 與 manifest 放在同一儲存庫。

調整目錄後執行 openclaw doctor --json > ~/openclaw-scratch/probe/doctor-last.json，在微調工具前先凍結一版基線。

Schema 校驗範例

凡模型可能呼叫的工具都應掛上 inputSchema。優先採 JSON Schema Draft 2020-12 或 Draft-07（與您所用 OpenClaw 內建驗證器一致）。校驗必須在任何子行程或 HTTP 客戶端啟動之前完成；失敗時回傳機器可讀錯誤（欄位名、預期型別、違反的約束），方便模型自我修正。

範例：擷取議題工具，禁止任意 URL 與無上限標籤字串：

{ "name": "linear.fetch_issue", "description": "以穩定 id 擷取單一 Linear 議題", "inputSchema": { "type": "object", "additionalProperties": false, "required": ["issueId"], "properties": { "issueId": { "type": "string", "pattern": "^[A-Z]{2,10}-[0-9]+$", "maxLength": 32 }, "includeComments": { "type": "boolean", "default": false } } } }

實務規則：物件設 additionalProperties: false、字串 maxLength、陣列 maxItems、模式用 enum。大型 schema 可拆檔於 ~/openclaw-skills/…/schemas/ 並由 manifest 引用。驗證失敗記錄 tool、correlationId 與錯誤路徑，勿寫入使用者機密。

超時與熔斷參數

超時是熔斷單次呼叫：避免單一工具卡死整個 worker 池。熔斷則阻斷連續劣化對下游的撞擊。兩者都寫進技能 manifest（或共用 policies.yaml），讓工具繼承預設值、僅覆寫必要欄位。

  • executionTimeoutMs — 通過校驗後，工具本體的牆鐘上限。HTTP 小助手可先設 8–30 秒，有界儲存庫掃描 60–120 秒，純 CPU 轉換則應更短。
  • queueWaitMs（選用） — 呼叫在佇列中可等待的上限，逾時由閘道以 503 tool_backpressure 拒絕，避免模型平行噴出數十個呼叫造成雷群。
  • 熔斷視窗 — 例如連續失敗 breaker.failureThreshold: 5，或 60 秒滑動視窗內 breaker.errorRatePercent: 40，再 breaker.openDurationMs: 30000，新呼叫快速失敗並附 breaker_open 代碼。
  • 半開探測 — 開路視窗結束後允許單次試探呼叫，自動驗證恢復而無需人工重啟閘道。

請在 code review 註明每個工具的數字。下游 SLO 變更時先改 manifest 再部署閘道，避免「只有某台筆電知道」的神秘環境變數。

重試退避

重試應集中在一個共用範本，而非在每支腳本複製 sleep 迴圈。冪等讀取適用指數退避加抖動；寫入則嚴格限制次數並搭配供應商支援的冪等鍵。遠端 Mac 閘道對外 API 的實用預設可如下：

retry: maxAttempts: 4 initialDelayMs: 200 multiplier: 2.0 maxDelayMs: 8000 jitterRatio: 0.2 retryOnHttpStatus: [408, 425, 429, 500, 502, 503, 504] nonRetryOnHttpStatus: [401, 403, 404, 422]

變更路由若支援冪等鍵請一併帶上。子行程類工具除非 manifest 標記 idempotent: true 且腳本以不同離開碼區分「暫態基礎設施」與「輸入錯誤」，否則避免自動重試。每次嘗試輸出結構化日誌：attempt、delayMs、errorClass、correlationId。熔斷開路時應跳過重試，並把狀態回傳模型，使其改策略而非放大傷害。

日誌排錯 FAQ

升級模型後驗證錯誤暴增。新型號常多送鍵名或拉長字串。先記錄頂層未知鍵，流量乾淨後再將 additionalProperties 設為 false。

超時觸發但下游服務看似健康。請在 Mac 本機查 DNS 與 TLS，勿僅從筆電推斷；對照 executionTimeoutMs 與 p95 延遲，無伺服器運算冷啟動預算時，預設常過樂觀。

恢復後熔斷仍常開。確認半開探測、4xx／5xx 分桶正確、時鐘同步；留意長期 ECONNRESET 是否誤計熔斷。

重試放大限流。遵守 Retry-After、涵蓋 429，並對突發工具調低 maxAttempts。

日誌成功但無副作用。可能非同步未完成即回傳；拉長超時或拆「入佇／查狀態」兩工具並分別定 schema。

doctor 通過執行仍敗。Doctor 不保證線上憑證；以 dry-run 試探、確認權杖可讀，並對齊 launchd 與互動 shell 的技能路徑。

摘要：統一閘道、技能與 scratch 目錄；執行前以 JSON Schema 校驗每個工具；為單次呼叫設超時、為劣化序列設熔斷視窗；以指數退避加抖動集中管理重試；讓 correlation ID 貫穿校驗、嘗試與熔斷轉折。此堆疊能把「代理混亂」變成可在遠端 Mac 演練、並可移交下一位維運者的操作。

若您認同 2026 年仍以 Schema 優先、可觀測的方式跑代理，請把閘道放在您可控的硬體上：於購買頁瀏覽 Mac mini M4 雲端方案，在定價頁比對方案，並將 runbook 收斂在說明中心。準備開通時從首頁進入控制台，讓同一套工具政策在各環境可複製落地。