OAuth

OpenClaw 透過 OAuth 支援「訂閱制驗證」，適用於提供此機制的供應商（特別是 OpenAI Codex（ChatGPT OAuth））。若要使用 Anthropic 訂閱，請改用 setup-token 流程。過去 Anthropic 曾限制部分用戶在 Claude Code 以外使用訂閱，因此是否啟用訂閱驗證屬於個人風險決策，請自行確認 Anthropic 目前的使用政策。OpenAI Codex OAuth 則明確支援在 OpenClaw 等外部工具中使用。本頁說明：

在正式環境中使用 Anthropic 時，API key 驗證是比訂閱制 setup-token 驗證更安全的建議路徑。

  • OAuth Token 交換的運作方式（PKCE）
  • Token 的儲存位置（及其設計考量）
  • 如何處理多帳號（Profile 機制 + 依 Session 覆蓋設定）

OpenClaw 也支援供應商外掛，外掛可自帶 OAuth 或 API key 流程。透過以下指令執行：

openclaw models auth login --provider <id>

Token Sink（為什麼需要它）

OAuth 供應商在登入或刷新流程中通常會發出新的 Refresh Token。某些供應商（或 OAuth 用戶端）會在為同一使用者/應用程式核發新 Token 時，使舊的 Refresh Token 失效。

實際常見症狀：

  • 你透過 OpenClaw 以及 Claude Code / Codex CLI 登入 → 其中一個之後會隨機「被登出」

為了降低這種情況，OpenClaw 把 auth-profiles.json 當作Token Sink：

  • 執行期間從單一來源讀取憑證
  • 可以維護多組 Profile，並確定性地進行路由

儲存位置（Token 放在哪裡）

Secret 依各 Agent 分別儲存：

  • Auth Profile（OAuth + API key + 可選的值層級參照）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 舊版相容檔案：~/.openclaw/agents/<agentId>/agent/auth.json （發現靜態 api_key 項目時會自動清除）

僅供匯入的舊版檔案（仍支援，但不再作為主要儲存）：

  • ~/.openclaw/credentials/oauth.json（首次使用時會匯入 auth-profiles.json）

以上路徑皆遵循 $OPENCLAW_STATE_DIR（State 目錄覆蓋）。完整參考：/gateway/configuration

靜態 Secret 參照與執行期間快照啟用行為，請參閱 Secrets Management。

Anthropic setup-token（訂閱驗證）

警告： Anthropic setup-token 支援屬於技術相容性，而非政策保證。 Anthropic 過去曾封鎖部分在 Claude Code 以外的訂閱使用行為。 請自行判斷是否使用訂閱驗證，並查閱 Anthropic 當前條款。

在任何機器上執行 claude setup-token，然後把 Token 貼入 OpenClaw：

openclaw models auth setup-token --provider anthropic

如果你在其他地方產生了 Token，可以手動貼上：

openclaw models auth paste-token --provider anthropic

驗證：

openclaw models status

OAuth 交換（登入流程詳解）

OpenClaw 的互動式登入流程實作在 @mariozechner/pi-ai 中，並串接至精靈引導/指令介面。

Anthropic setup-token

流程概覽：

  1. 執行 claude setup-token
  2. 將 Token 貼入 OpenClaw
  3. 以 Token Auth Profile 儲存（不含 Refresh）

精靈引導路徑為 openclaw onboard → 驗證方式選擇 setup-token（Anthropic）。

OpenAI Codex（ChatGPT OAuth）

OpenAI Codex OAuth 明確支援在 Codex CLI 以外使用，包含 OpenClaw 工作流程。

流程概覽（PKCE）：

  1. 產生 PKCE verifier/challenge + 隨機 state
  2. 開啟 https://auth.openai.com/oauth/authorize?...
  3. 嘗試在 http://127.0.0.1:1455/auth/callback 擷取回呼
  4. 若回呼無法綁定（或在遠端/無頭環境），手動貼上重導向 URL/code
  5. 在 https://auth.openai.com/oauth/token 進行交換
  6. 從 Access Token 中擷取 accountId，儲存 { access, refresh, expires, accountId }

精靈引導路徑為 openclaw onboard → 驗證方式選擇 openai-codex。

刷新與到期

Profile 會儲存一個 expires 時間戳。

執行期間的行為：

  • 若 expires 在未來 → 直接使用已儲存的 Access Token
  • 若已過期 → 刷新（使用檔案鎖）並覆寫儲存的憑證

刷新流程是自動的，一般不需要手動管理 Token。

多帳號（Profile）與路由

兩種模式：

1) 推薦做法：獨立 Agent

如果你希望「個人」和「工作」完全隔離，使用獨立的 Agent（各自擁有 Session、憑證、Workspace）：

openclaw agents add work
openclaw agents add personal

接著針對各 Agent 分別設定驗證（透過精靈引導），並將對話路由到正確的 Agent。

2) 進階做法：單一 Agent 中使用多組 Profile

auth-profiles.json 支援同一供應商下的多組 Profile ID。

選擇使用哪個 Profile：

  • 全域設定：透過設定順序（auth.order）
  • 依 Session 覆蓋：透過 /model ...@<profileId>

範例（Session 覆蓋）：

  • /model Opus@anthropic:work

查看現有的 Profile ID：

  • openclaw channels list --json（顯示 auth[]）

相關文件：

arrow_back
上一頁
Agent Workspace
下一頁
Bootstrapping
arrow_forward