ClawRouter

ClawRouter 為 OpenClaw 提供一個受原則範圍限制的金鑰，用於多個上游模型 供應商。內建的 clawrouter 外掛只會探索該金鑰允許的模型， 依各模型宣告的通訊協定進行路由，並在 OpenClaw 的用量介面上回報 該金鑰的預算與彙總用量。

上游認證資訊與供應商特定的轉送處理都保留在 ClawRouter 中，因此 你完全不需要在 OpenClaw 主機上安裝或驗證各個上游供應商外掛。 此外掛隨 OpenClaw 內建提供（enabledByDefault: true）； 你只需要取得核發的 ClawRouter 認證資訊。

開始使用

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

openclaw models set clawrouter/<provider>/<model>

受管理的非互動式部署

將代理伺服器金鑰保留在工作負載的密鑰注入機制中，並只在 openclaw.json 儲存 SecretRef。標準的受管理欄位如下：

例如，部署控制器可以管理以下 JSON5 修補檔：

{  plugins: {    entries: { clawrouter: { enabled: true } },  },  models: {    providers: {      clawrouter: {        baseUrl: "https://clawrouter.internal.example",        apiKey: {          source: "env",          provider: "default",          id: "CLAWROUTER_API_KEY",        },        headers: {          "X-ClawRouter-Project-Id": "fakeco",        },      },    },  },  agents: {    defaults: {      model: { primary: "clawrouter/openai/gpt-5.5" },    },  },}

如果部署設定了 plugins.allow，請保留其現有項目並加入 clawrouter。不使用互動式精靈即可驗證並套用：

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

試執行會解析 SecretRef，但絕不會輸出其值。若要輪替 認證資訊，請更新提供 CLAWROUTER_API_KEY 的外部 Secret，並 重新啟動閘道工作負載，以載入新的程序環境。 設定檔與模型參照不需變更。

對於從原始碼建置的獨立 Docker 閘道，ClawRouter 已包含在 根執行階段中。只需選取需要獨立封裝的頻道外掛， 例如 OPENCLAW_EXTENSIONS=clickclack、slack 或 msteams；請參閱 包含指定外掛的原始碼建置映像。 封存／設備型部署必須透過自身的成品流水線封裝相同的已合併原始碼， 而不是使用 OCI 映像。

就緒狀態與即時驗證

下列檢查驗證的是不同邊界；不可互相替代：

# 僅檢查 ClawRouter 程序健康狀態；不會使用認證資訊或上游模型。curl -fsS https://clawrouter.internal.example/v1/health # 僅檢查 OpenClaw 閘道啟動就緒狀態；不會呼叫模型。curl -fsS http://127.0.0.1:18789/readyz # 探索限定認證資訊範圍的目錄。openclaw models list --all --provider clawrouter --json # 透過已設定的 ClawRouter 供應商執行最小的實際推論探測。openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # 使用明確授權模型參照的工作負載金絲雀測試。openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "請完全照此回覆：CLAWROUTER_CANARY_OK" \  --json

請使用限定範圍目錄所傳回的模型，而不要直接照抄範例 模型。成功的 /readyz 回應表示閘道可以處理 要求；這不代表 ClawRouter、其認證資訊或上游 供應商已就緒。模型探測與代理程式金絲雀測試才是推論驗證。

若要進行即時診斷，請執行金絲雀測試並檢查閘道的標準記錄。 現有僅包含中繼資料的模型傳輸診斷會輸出如下格式的行：

[model-fetch] 開始 provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] 回應 provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

當這些識別碼可用時，外掛會傳送有長度限制的 X-ClawRouter-Client、 X-ClawRouter-Agent-Id 和 X-ClawRouter-Session-Id 標頭。它也會 將模型呼叫的診斷 callId（<run-id>:model:<n>）對應至 X-Request-ID，讓 OpenClaw 模型呼叫事件可與 ClawRouter 僅包含中繼資料的稽核軌跡進行關聯。在 128 字元要求 ID 預算內的值 會完全相同。較長的值會保留 :model:<n> 後綴與確定性 雜湊，使不同呼叫仍維持在長度限制內並可供關聯。靜態部署中繼資料 （例如 X-ClawRouter-Project-Id）可在供應商的 headers 對應表中設定。 代理程式與工作階段歸屬標頭會保留各自獨立的 256 字元 限制。若自動要求 ID 包含 ClawRouter ASCII 識別碼集合以外的字元，則會使用相同的確定性限長格式。 明確設定的標頭（包括 X-Request-ID 的任何大小寫變體）優先於 自動值。傳輸診斷只記錄路由與回應 中繼資料；不會記錄認證資訊、要求 ID、提示或完成內容。 ClawRouter 自身的稽核事件會提供選定的上游供應商與 內容保留狀態。

模型探索

GET /v1/catalog 會傳回 { providers: [...] }，其中每個供應商項目 都會列出其自身的 models[]（包含上游 ID、功能與定價），以及其 支援的要求路由。OpenClaw 不會附帶另一份固定的 ClawRouter 模型清單。符合下列條件時，目錄模型會公布為 OpenClaw 模型：

• 認證資訊的原則授權其供應商；
• 目錄模型公布受支援的 LLM 功能（llm.responses、 llm.chat、llm.messages，或具有相符串流 路由的 llm.stream）；且
• 供應商為下列其中一種傳輸方式公開相符的路由。

將模型加入受支援的 ClawRouter 供應商不需要發布新版 OpenClaw： 下一次目錄重新整理（依認證資訊範圍快取 60 秒）就會探索到 該模型。需要新線路通訊協定的模型，則必須先由外掛提供支援。

通訊協定與供應商外掛

ClawRouter 管理上游認證資訊；其目錄會告知 OpenClaw 應使用哪種 傳輸方式，因此你完全不需要安裝每家上游公司的驗證外掛。

此外掛也會為這些系列套用相符的重播與工具結構描述原則 （OpenAI/DeepSeek/Gemini/Perplexity 工具結構描述相容性；原生 Anthropic 與 Google Gemini 重播原則）。Perplexity 模型會套用嚴格的 結構描述改寫：移除 patternProperties 與 additionalProperties，且 每個物件結構描述都會宣告 properties，因為 Perplexity 會拒絕 缺少這些內容的工具結構描述。若目錄供應商只公開 不受支援的要求格式，則會刻意不將其公布為 OpenClaw 文字模型。請在 ClawRouter 中將這些供應商正規化為 其中一種受支援的合約，而不要傳送不相容的承載內容。

配額與用量

ClawRouter 的 /v1/usage 回應會提供給一般的 OpenClaw 供應商用量 介面：要求、權杖及支出總計；如果金鑰設有限額，也會提供 每月預算期間。未計量的金鑰仍會顯示彙總用量，但不會顯示 百分比期間。

配額查詢使用與模型探索相同的限定範圍金鑰。配額 查詢失敗不會阻止模型執行。

使用以下命令檢查即時快照：

openclaw status --usageopenclaw models status

相同的供應商快照也可供聊天中的 /status 與 OpenClaw 用量介面使用。預算適用於整個原則，因此使用 相同 ClawRouter 原則的其他用戶端所發出的要求，可能會改變剩餘百分比。

疑難排解

安全性行為

• 目錄探索的範圍限定於已設定的 proxy key，並依各認證資訊範圍快取（代理程式目錄、工作區目錄、驗證設定檔 ID 及基底 URL）。
• proxy key 僅在分派請求時附加；不會儲存在模型中繼資料中。
• 自動歸屬與請求關聯值會先去除前後空白並拒絕控制字元，再進行分派。歸屬值上限為 256 個字元；請求 ID 上限為 128 個字元。
• 模型傳輸診斷僅包含中繼資料，絕不包含 proxy key 或模型內容。
• 原生 Anthropic 與 Gemini 模型 ID 僅在分派時改寫為其上游 ID。
• 不受支援或未獲授權的目錄資料列會以封閉方式失敗，且無法選取。

相關內容