身分驗證

OpenClaw 支援模型提供者使用 OAuth 與 API 金鑰。對於常駐 Gateway 主機，API 金鑰通常是最可預期的選項。當訂閱/OAuth 流程符合你的提供者帳號模型時，也支援這些流程。

請參閱 /concepts/oauth 了解完整 OAuth 流程與儲存 配置。 如需 SecretRef 型驗證（env/file/exec 提供者），請參閱密鑰管理。 如需 models status --probe 使用的憑證資格/原因碼規則，請參閱 驗證憑證語意。

# 建議設定（API 金鑰，任何提供者）

如果你正在執行長時間存活的 Gateway，請先為你選擇的提供者設定 API 金鑰。 特別是 Anthropic，API 金鑰驗證仍是最可預期的伺服器 設定，但 OpenClaw 也支援重用本機 Claude CLI 登入。

1. 在你的提供者主控台建立 API 金鑰。
2. 將它放在 Gateway 主機（執行 openclaw gateway 的機器）上。

export <PROVIDER>_API_KEY="..."
openclaw models status

3. 如果 Gateway 在 systemd/launchd 下執行，建議將金鑰放在 ~/.openclaw/.env，讓守護程式可以讀取：

cat >> ~/.openclaw/.env <<'EOF'
&lt;PROVIDER&gt;_API_KEY=...
EOF

接著重新啟動守護程式（或重新啟動你的 Gateway 程序）並重新檢查：

openclaw models status
openclaw doctor

如果你不想自行管理環境變數，onboarding 可以儲存 API 金鑰供守護程式使用：openclaw onboard。

如需環境繼承（env.shellEnv、 ~/.openclaw/.env、systemd/launchd）的詳細資料，請參閱說明。

# Anthropic：Claude CLI 與權杖相容性

Anthropic setup-token 驗證仍在 OpenClaw 中作為受支援的權杖 路徑提供。Anthropic 員工後來告知我們，OpenClaw 風格的 Claude CLI 使用方式 已再次允許，因此除非 Anthropic 發布新政策，OpenClaw 會將 Claude CLI 重用與 claude -p 使用 視為此整合的核准方式。當主機上可使用 Claude CLI 重用時，這現在是偏好的路徑。

對於長時間存活的 Gateway 主機，Anthropic API 金鑰仍是最可預期的 設定。如果你想在同一台主機上重用既有 Claude 登入，請在 onboarding/configure 中使用 Anthropic Claude CLI 路徑。

Claude CLI 重用的建議主機設定：

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

這是兩步驟設定：

1. 讓 Claude Code 本身在 Gateway 主機上登入 Anthropic。
2. 告訴 OpenClaw 將 Anthropic 模型選擇切換到本機 claude-cli 後端，並儲存相符的 OpenClaw 驗證設定檔。

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

手動輸入權杖（任何提供者；寫入 auth-profiles.json + 更新設定）：

openclaw models auth paste-token --provider openrouter

auth-profiles.json 只儲存憑證。標準形狀為：

{
  "version": 1,
  "profiles": {
    "openrouter:default": {
      "type": "api_key",
      "provider": "openrouter",
      "key": "OPENROUTER_API_KEY"
    }
  }
}

OpenClaw 在執行階段預期使用標準的 version + profiles 形狀。如果較舊的安裝仍有像 { "openrouter": { "apiKey": "..." } } 這樣的扁平檔案，請執行 openclaw doctor --fix，將它重寫為 openrouter:default API 金鑰設定檔；doctor 會在原始檔旁保留 .legacy-flat.*.bak 副本。baseUrl、api、模型 ID、標頭與逾時等端點詳細資料，應放在 openclaw.json 或 models.json 的 models.providers.<id> 下，而不是放在 auth-profiles.json 中。

像 Bedrock auth: "aws-sdk" 這類外部驗證路由也不是憑證。如果你想要具名的 Bedrock 路由，請在 openclaw.json 中放入 auth.profiles.<id>.mode: "aws-sdk"；不要將 type: "aws-sdk" 寫入 auth-profiles.json。openclaw doctor --fix 會將舊版 AWS SDK 標記從憑證儲存移到設定中繼資料。

靜態憑證也支援驗證設定檔參照：

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

適合自動化的檢查（過期/遺失時結束碼 1，即將過期時為 2）：

openclaw models status --check

即時驗證探測：

openclaw models status --probe

注意：

• 探測列可以來自驗證設定檔、環境憑證或 models.json。
• 如果明確的 auth.order.<provider> 省略已儲存的設定檔，探測會針對該設定檔回報 excluded_by_auth_order，而不是嘗試使用它。
• 如果驗證存在，但 OpenClaw 無法為該提供者解析可探測的模型候選項， 探測會回報 status: no_model。
• 速率限制冷卻可以限定於模型。某個設定檔因一個 模型而冷卻時，仍可用於同一提供者上的同層模型。

可選的維運腳本（systemd/Termux）記錄在此： 驗證監控腳本

# Anthropic 注意事項

Anthropic claude-cli 後端已再次受支援。

• Anthropic 員工告訴我們，此 OpenClaw 整合路徑已再次允許。
• 因此，除非 Anthropic 發布新政策，OpenClaw 會將 Claude CLI 重用與 claude -p 使用 視為 Anthropic 支援執行的核准方式。
• Anthropic API 金鑰仍是長時間存活 Gateway 主機與明確伺服器端計費控制的最可預期選擇。

# 檢查模型驗證狀態

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、Too many concurrent requests、ThrottlingException、concurrency limit reached 或 workers_ai ... quota limit exceeded）。
• 非速率限制錯誤不會使用替代金鑰重試。
• 如果所有金鑰都失敗，會傳回最後一次嘗試的最終錯誤。

# 控制使用哪個憑證

# 每個工作階段（聊天指令）

使用 /model <alias-or-id>@<profileId> 為目前工作階段固定特定提供者憑證（設定檔 ID 範例：anthropic:default、anthropic:work）。

使用 /model（或 /model list）取得精簡選擇器；使用 /model status 取得完整檢視（候選項 + 下一個驗證設定檔，以及已設定時的提供者端點詳細資料）。

# 每個代理（CLI 覆寫）

為代理設定明確的驗證設定檔順序覆寫（儲存在該代理的 auth-state.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> 指定特定代理；省略則使用已設定的預設代理。 當你偵錯順序問題時，openclaw models status --probe 會將被省略的 已儲存設定檔顯示為 excluded_by_auth_order，而不是默默跳過。 當你偵錯冷卻問題時，請記得速率限制冷卻可能綁定到 某一個模型 ID，而不是整個提供者設定檔。

# 疑難排解

###「找不到憑證」

如果 Anthropic 設定檔遺失，請在 Gateway 主機上設定 Anthropic API 金鑰，或設定 Anthropic setup-token 路徑，然後重新檢查：

openclaw models status

# 權杖即將過期/已過期

執行 openclaw models status 以確認哪個設定檔即將過期。如果 Anthropic 權杖設定檔遺失或已過期，請透過 setup-token 重新整理該設定，或遷移到 Anthropic API 金鑰。

# 相關

• 密鑰管理
• 遠端存取
• 驗證儲存