身份驗證

OpenClaw 支援 OAuth 和 API 金鑰來驗證模型提供者。如果你的 Gateway 是長時間運行的，API 金鑰通常是最穩定可靠的選擇。當你的提供者帳號支援訂閱制或 OAuth 時，也可以使用對應的認證流程。

完整的 OAuth 流程與儲存結構請參閱 /concepts/oauth。 SecretRef 驗證方式（env/file/exec 提供者）請參閱 Secrets 管理。 models status --probe 所使用的憑證資格與原因碼規則，請參閱 Auth Credential Semantics。

建議設定（API 金鑰，適用所有提供者）

如果你要跑一個長期運行的 Gateway，先從你選用的提供者取得 API 金鑰開始。 特別是 Anthropic，用 API 金鑰驗證是最安全的做法，建議優先於訂閱制 setup-token。

  1. 在你的提供者管理後台建立 API 金鑰。
  2. 把金鑰放到 Gateway 主機（也就是執行 openclaw gateway 的那台機器）上。
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. 如果 Gateway 是透過 systemd/launchd 運行，建議把金鑰寫在 ~/.openclaw/.env，這樣 daemon 才讀得到：
cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

接著重啟 daemon（或重啟 Gateway 程序），然後再確認一次：

openclaw models status
openclaw doctor

如果你不想自己管環境變數，入門精靈可以幫你把 API 金鑰存好供 daemon 使用：openclaw onboard。

關於環境繼承（env.shellEnv、~/.openclaw/.env、systemd/launchd）的細節，請參閱 Help。

Anthropic：setup-token（訂閱制驗證）

如果你用的是 Claude 訂閱方案，可以透過 setup-token 流程來驗證。在 Gateway 主機上執行：

claude setup-token

然後貼到 OpenClaw 裡：

openclaw models auth setup-token --provider anthropic

如果 token 是在另一台機器上產生的，直接手動貼上：

openclaw models auth paste-token --provider anthropic

如果你看到 Anthropic 回傳這樣的錯誤：

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

請改用 Anthropic API 金鑰。

警告： Anthropic setup-token 支援僅為技術相容性。Anthropic 過去曾限制部分訂閱制使用者在 Claude Code 以外的用途。只有在你認為政策風險可接受時才使用，並請自行確認 Anthropic 目前的使用條款。

手動輸入 token（適用任何提供者；會寫入 auth-profiles.json 並更新設定）：

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

Auth profile 參照也支援靜態憑證：

  • api_key 憑證可用 keyRef: { source, provider, id }
  • token 憑證可用 tokenRef: { source, provider, id }

自動化用檢查指令（過期或缺失時回傳 exit 1，即將過期時回傳 2）：

openclaw models status --check

可選的自動化腳本（systemd/Termux）說明請見： /automation/auth-monitoring

claude setup-token 需要互動式終端（TTY）。

查看模型驗證狀態

openclaw models status
openclaw doctor

API 金鑰輪替行為（Gateway）

部分提供者支援在 API 呼叫遇到速率限制時，自動換用其他金鑰重試。

  • 優先順序：
    • OPENCLAW_LIVE_<PROVIDER>_KEY（單一覆寫）
    • <PROVIDER>_API_KEYS
    • <PROVIDER>_API_KEY
    • <PROVIDER>_API_KEY_*
  • Google 系提供者還會額外退回到 GOOGLE_API_KEY。
  • 同一批金鑰在使用前會先去重。
  • OpenClaw 只在遇到速率限制錯誤時才會換用下一把金鑰（例如 429、rate_limit、quota、resource exhausted）。
  • 非速率限制的錯誤不會觸發金鑰輪替。
  • 如果所有金鑰都失敗，會回傳最後一次嘗試的錯誤。

控制使用哪個憑證

依對話階段（chat 指令）

用 /model <alias-or-id>@<profileId> 在當前對話階段固定使用特定提供者憑證（profile id 範例：anthropic:default、anthropic:work）。

用 /model（或 /model list）開啟簡易選擇器；用 /model status 查看完整資訊（候選憑證 + 下一個 auth profile，以及已設定的提供者端點細節）。

依 Agent（CLI 覆寫）

為特定 agent 設定明確的 auth profile 優先順序（儲存在該 agent 的 auth-profiles.json）：

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

用 --agent <id> 指定特定 agent；省略的話會使用預設 agent。

疑難排解

「No credentials found」

如果 Anthropic token profile 不存在，在 Gateway 主機上執行 claude setup-token，然後重新檢查：

openclaw models status

Token 即將過期或已過期

執行 openclaw models status 確認哪個 profile 即將過期。如果 profile 不存在，重新執行 claude setup-token 並再次貼上 token。

前置需求

  • Anthropic 訂閱帳號（用於 claude setup-token）
  • 已安裝 Claude Code CLI（claude 指令可用）
arrow_back
上一頁
Configuration Examples
下一頁
Auth Credential Semantics
arrow_forward