Agno負責輕量執行面與工具編排語意；OpenClaw負責對外邊界上的名稱、權杖與有界逾時。兩者對齊後，遠端 Mac 上的代理演練才能用同一套 JSON 設定重放，並把失敗收斂成可簽核的摘要。
本篇目錄
前置巡檢與對照讀物
在改動白名單或逾時前，建議先完成與執行環境無關的邊界巡檢：對齊閘道與執行階段的版別、跑官方建議的 doctor、確認回環埠與權杖檔權限，並以最小探針驗證「閘道→上游」鏈路；細節可併讀《OpenClaw 遠端 Mac：IDE 橋、沙箱差分與健康探測》中的健康探測與最小權限目錄思路。契約與重試語意請對齊《閘道工具與 JSON Schema 重試》；若你正在做運行時選型與槽位驗收，可一併參考《Agno 與 OpenAI Agents SDK 決策矩陣》中的觀測與併發座標。
可重現步驟與 JSON 占位
下列鍵名為教學占位，請替換為你環境中實際設定檔的欄位；切勿把真實 Bearer 或雲端金鑰寫進版控。占位路徑與毫秒值僅示意。
- 隔離工作目錄：在遠端 Mac 建立專用專案路徑、虛擬環境與暫存目錄，與桌面與其他代理專案分離。
- 閘道先於對外：於
127.0.0.1固定埠啟動 OpenClaw；權杖檔chmod 600。doctor與健康檢查通過後，再開 SSH 反向隧道或對內網反向代理。 - 閘道側白名單與逾時熔斷（示意 JSON）：將允許工具表、連線／首包／整段請求上限，以及錯誤視窗熔斷寫進單一設定來源，由部署流程注入，而非散落在程式常數。
{
"gateway": {
"listen": { "host": "127.0.0.1", "port": 8787 },
"auth": {
"mode": "bearer_file",
"bearerFile": "/secure/openclaw/gateway.token"
},
"tools": {
"allowlist": ["search_public_docs_v1", "read_repo_file_v1"],
"denyUnknownToolNames": true
},
"timeoutsMs": {
"connect": 2500,
"firstByte": 15000,
"fullRequest": 120000
},
"circuitBreaker": {
"windowSec": 30,
"failureThreshold": 5,
"halfOpenProbeAfterSec": 15
},
"failureResponse": {
"format": "envelope_v1",
"includeCorrelationId": true,
"maxClientHintChars": 200,
"omitUpstreamBody": true
}
}
}- Agno 客戶端只認閘道：將 LLM 的基底網址改為閘道 OpenAI 相容路徑；工具顯示名僅使用上列白名單鍵。下列為執行期覆寫占位（非真實端點）。
{
"agno_runtime": {
"llm": {
"baseUrl": "http://127.0.0.1:8787/v1",
"apiKeyEnv": "OPENCLAW_GATEWAY_TOKEN"
},
"tools": {
"registrySource": "gateway_allowlist",
"refuseDirectUpstream": true
}
}
}- 失敗摘要回傳：由閘道統一包裝
envelope_v1：含關聯編號、階段代碼（例如timeout_full_request）、可公開的指標鍵與單行修復提示；不附上游原文、堆疊或使用者資料。 - 簽核重放：以固定種子與錄製請求各跑一輪成功、兩輪預期失敗（未知工具名、逾時、熔斷），確認 CI 或排程能消費摘要欄位。
排障要點
| 現象 | 優先檢查 |
|---|---|
| 工具遭拒或 404 | 白名單是否含穩定鍵名；Agno 是否仍引用舊別名或繞過環境變數直連上游。 |
| 頻繁熔斷、延遲不高 | fullRequest 是否過緊；未知參數是否觸發連續驗證失敗。先放寬有界逾時並縮小工具輸出欄位。 |
| 摘要缺關聯編號 | 中介層是否剝除錯誤本文；應在閘道出口統一封裝再回 Agno。 |
小結：Agno 管「怎麼呼叫」；OpenClaw 管「邊界上允許什麼、多久算失敗、失敗怎麼說」。白名單、請求逾時熔斷與失敗信封三者併用，才能在遠端節點做到可簽核、可重放的最小權限演練。
站內公開頁（免登入）：首頁、說明中心、方案定價。延伸閱讀：PydanticAI 閘道綱要。