OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

驗證

OpenClaw 支援模型供應商使用 OAuth 和 API 金鑰。對於持續運作的閘道主機，API 金鑰是最可預期的選項；訂閱／OAuth 流程只要符合您的供應商帳戶模式，也同樣可用。

建議設定：API 金鑰（任何供應商）

  1. 在供應商控制台中建立 API 金鑰。
  2. 將它放在閘道主機（執行 openclaw gateway 的機器）上：
bash
export <PROVIDER>_API_KEY="..."openclaw models status
  1. 如果閘道在 systemd/launchd 下執行，請將金鑰放入 ~/.openclaw/.env，以便常駐程式讀取：
bash
cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF
  1. 重新啟動閘道程序（或常駐程式），然後再次檢查：
bash
openclaw models statusopenclaw doctor

如果您不想自行管理環境變數，openclaw onboard 也可以儲存 API 金鑰供常駐程式使用。如需完整的環境變數載入優先順序（env.shellEnv、~/.openclaw/.env、systemd/launchd），請參閱環境變數。

Anthropic：重用 Claude 命令列介面

Anthropic 設定權杖驗證仍是受支援的方式。此整合也允許重用 Claude 命令列介面（claude -p 類型的用法）；如果主機上已有可用的 Claude 命令列介面登入，這是本機／桌面使用情境的首選方式。對於長期運作的閘道主機，Anthropic API 金鑰仍是最可預期的選擇，並可明確控制伺服器端計費。

重用 Claude 命令列介面的主機設定：

bash
# Run on the gateway hostclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

這包含兩個步驟：先在主機上讓 Claude Code 登入 Anthropic，再告知 OpenClaw 透過本機 claude-cli 後端路由 Anthropic 模型選擇，並儲存相符的 OpenClaw 驗證設定檔。

如果 claude 不在 PATH 中，請安裝 Claude Code，或將 agents.defaults.cliBackends.claude-cli.command 設為二進位檔路徑。

手動輸入權杖

適用於任何供應商；會寫入各代理程式的 SQLite 驗證儲存區並更新設定：

bash
openclaw models auth paste-token --provider openrouter

OpenClaw 會從各代理程式的 openclaw-agent.sqlite 讀取驗證設定檔。端點詳細資料（baseUrl、api、模型 ID、標頭、逾時）應置於 openclaw.json 或 models.json 的 models.providers.<id> 下，而非驗證設定檔中。

如果較舊的安裝仍有 auth-profiles.json、auth-state.json，或 { "openrouter": { "apiKey": "..." } } 之類的扁平結構，請執行 openclaw doctor --fix 將其匯入 SQLite；doctor 會在原始 JSON 檔案旁保留加上時間戳記的備份。

Bedrock auth: "aws-sdk" 等外部驗證路由並非憑證。若要設定具名 Bedrock 路由，請在 openclaw.json 中設定 auth.profiles.<id>.mode: "aws-sdk"，不要將 type: "aws-sdk" 寫入驗證設定檔儲存區。openclaw doctor --fix 會將舊版 AWS SDK 標記從憑證儲存區遷移至設定中繼資料。

以 SecretRef 為基礎的憑證

  • api_key 憑證可以使用 keyRef: { source, provider, id }
  • token 憑證可以使用 tokenRef: { source, provider, id }
  • OAuth 模式設定檔會拒絕 SecretRef 憑證：如果 auth.profiles.<id>.mode 為 "oauth"，則會拒絕該設定檔以 SecretRef 為基礎的 keyRef/tokenRef。

檢查模型驗證狀態

bash
openclaw models statusopenclaw doctor

適合自動化的檢查：過期／缺少時以 1 結束，即將過期時以 2 結束：

bash
openclaw models status --check

即時驗證探測（加入 --probe-provider、--probe-profile、--probe-timeout、--probe-concurrency 或 --probe-max-tokens 以縮小範圍）：

bash
openclaw models status --probe

注意事項：

  • 探測資料列可來自驗證設定檔、環境憑證或 models.json。
  • 如果 auth.order.<provider> 省略已儲存的設定檔，探測會針對該設定檔回報 excluded_by_auth_order，而不會嘗試使用它。
  • 如果已有驗證資料，但 OpenClaw 無法為該供應商解析出可探測的模型，探測會回報 status: no_model。
  • 速率限制冷卻可限定於模型：某個設定檔針對一個模型處於冷卻狀態時，仍可服務相同供應商下的同層級模型。

選用的維運指令稿（systemd/Termux）：驗證監控指令稿。

API 金鑰輪替（閘道）

某些供應商在呼叫觸及供應商速率限制時，會使用另一個已設定的金鑰重試要求。

各供應商的金鑰優先順序：

  1. OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY（單一覆寫，鎖定一個金鑰）
  2. &lt;PROVIDER&gt;_API_KEYS（以逗號／空格／分號分隔的清單）
  3. &lt;PROVIDER&gt;_API_KEY
  4. &lt;PROVIDER&gt;_API_KEY_*（任何具有此前綴的環境變數）

Google 供應商（google、google-vertex）還會額外回退至 GOOGLE_API_KEY。合併後的清單會在使用前去除重複項目。

只有當錯誤訊息符合下列內容時，OpenClaw 才會輪替至下一個金鑰：rate_limit、rate limit、429、quota exceeded/quota_exceeded、resource exhausted/resource_exhausted 或 too many requests。其他錯誤不會使用替代金鑰重試。如果所有金鑰皆失敗，則傳回最後一次嘗試的最終錯誤。

移除已儲存的驗證資料不會在供應商端撤銷金鑰；需要使其在供應商端失效時，請在供應商儀表板中輪替或撤銷該金鑰。

在閘道執行時移除供應商驗證資料

當您透過閘道控制平面移除供應商驗證資料時，OpenClaw 會刪除該供應商已儲存的驗證設定檔，並中止所選模型供應商與已移除供應商相符的進行中聊天／代理程式執行。已中止的執行會發出一般的取消／生命週期事件，並包含 stopReason: "auth-revoked"，讓已連線的用戶端可以顯示該執行因憑證遭移除而停止。

控制使用哪個憑證

OpenAI 與舊版 openai-codex ID

OpenAI API 金鑰設定檔和 ChatGPT/Codex OAuth 設定檔都使用標準供應商 ID openai。新設定請使用 openai:* 設定檔 ID 和 auth.order.openai。

如果您在較舊的設定、驗證設定檔 ID 或 auth.order.openai-codex 中看到 openai-codex，請將它視為舊版遷移輸入，不要建立新的 openai-codex 設定檔。請執行：

bash
openclaw doctor --fixopenclaw models auth list --provider openai

Doctor 會將舊版 openai-codex:* 設定檔 ID 和 auth.order.openai-codex 項目改寫至標準 openai 路由。如需 OpenAI 特定的模型／執行階段路由資訊，請參閱 OpenAI。

登入期間（命令列介面）

bash
openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id 會在同一個代理程式內，將相同供應商的多個 OAuth 登入分開保存。

--force 會刪除所選代理程式目錄中該供應商已儲存的驗證設定檔，然後重新執行相同的驗證流程。當已儲存的設定檔卡住、過期或綁定至錯誤帳戶時，請使用此選項。它不會在供應商端撤銷憑證。

bash
openclaw models auth login --provider anthropic --force

各工作階段（聊天命令）

  • /model <alias-or-id>@<profileId> 會將目前工作階段鎖定至特定供應商憑證（設定檔 ID 範例：anthropic:default、anthropic:work）。
  • /model（或 /model list）會顯示精簡選擇器；/model status 會顯示完整檢視（候選項目與下一個驗證設定檔，以及設定後的供應商端點詳細資料）。

如果您變更已在執行之聊天的驗證順序或設定檔鎖定，請傳送 /new 或 /reset 以開始新的工作階段；現有工作階段在重設前會保留目前的模型／設定檔選擇。

各代理程式（命令列介面覆寫）

驗證順序覆寫會儲存在該代理程式的 SQLite 驗證狀態中：

bash
openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

使用 --agent <id> 指定特定代理程式；省略時使用已設定的預設代理程式。openclaw models status --probe 會將省略的已儲存設定檔顯示為 excluded_by_auth_order，而不是默默略過。

疑難排解

「找不到憑證」

在閘道主機上設定 Anthropic API 金鑰，或設定 Anthropic 設定權杖路徑，然後再次檢查：

bash
openclaw models status

權杖即將過期／已過期

執行 openclaw models status 以查看即將過期的設定檔。如果 Anthropic 權杖設定檔缺少或已過期，請透過設定權杖重新整理，或遷移至 Anthropic API 金鑰。

相關內容

Was this useful?
On this page

On this page