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 setup-token 驗證仍是受支援的途徑。此整合也允許重用 Claude 命令列介面（claude -p 形式的用法）；當主機上已有可用的 Claude 命令列介面登入時，這是本機/桌面使用的首選途徑。對於長期運作的閘道主機，Anthropic API 金鑰仍是最可預測的選擇，並可明確控制伺服器端計費。

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

bash
# 在閘道主機上執行claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

此流程分為兩個步驟：先在主機上將 Claude Code 登入 Anthropic，接著指示 OpenClaw 透過本機 claude-cli 後端路由 Anthropic 模型選擇，並儲存相符的 OpenClaw 驗證設定檔。

閘道服務必須能在 PATH 上解析 claude。如果部署需要 非標準的執行檔路徑，請透過 命令列介面後端外掛註冊包裝程式。

手動輸入權杖

適用於任何供應商；會寫入每個代理程式各自的 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 setup-token 途徑，然後再次檢查：

bash
openclaw models status

權杖即將過期/已過期

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

相關內容

Was this useful?
On this page

On this page