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

Fundamentals

OAuth

OpenClaw 支援提供 OAuth（「訂閱驗證」）的供應商， 其中主要包括 **OpenAI Codex（ChatGPT OAuth）**與 Anthropic Claude 命令列介面重複使用。 對 Anthropic 而言，實務上的區分如下：

  • Anthropic API 金鑰：一般 Anthropic API 計費。
  • OpenClaw 內的 Anthropic Claude 命令列介面／訂閱驗證：Anthropic 工作人員 告知我們目前再次允許此用法，因此除非 Anthropic 發布新政策，否則 OpenClaw 會將 Claude 命令列介面重複使用與 claude -p 用法視為此整合所允許的方式。若在正式環境使用 Anthropic，API 金鑰驗證仍是 較安全的建議方式。

OpenClaw 會將 OpenAI API 金鑰驗證與 ChatGPT/Codex OAuth 都儲存在 標準供應商 ID openai 下。較舊的 openai-codex:* 設定檔 ID 與 auth.order.openai-codex 項目是由 openclaw doctor --fix 修復的舊版狀態；新設定請使用 openai:* 設定檔 ID 與 auth.order.openai。

本頁涵蓋：

  • OAuth 權杖交換的運作方式（PKCE）
  • 權杖的儲存位置（及其原因）
  • 如何處理多個帳號（設定檔 + 個別工作階段覆寫）

隨附自身 OAuth 或 API 金鑰流程的供應商外掛會透過 相同的進入點執行：

bash
openclaw models auth login --provider <id>

權杖匯集處（為何需要它）

OAuth 供應商通常會在每次登入／重新整理時產生新的重新整理權杖。 有些供應商會在為同一使用者／應用程式核發新權杖時， 使先前的重新整理權杖失效。實際症狀是：同時透過 OpenClaw 及 Claude Code／Codex 命令列介面登入後，其中一方之後會隨機被登出。

為減少這種情況，OpenClaw 將驗證設定檔儲存區視為權杖匯集處：

  • 執行階段會從每個代理程式的單一位置讀取認證資訊
  • 多個設定檔可同時存在，並以確定性的方式路由
  • 外部命令列介面重複使用會因供應商而異：一旦 OpenClaw 擁有某供應商的本機 OAuth 設定檔，本機重新整理權杖即為標準來源。如果該本機 重新整理權杖遭拒，OpenClaw 會回報該設定檔需要 重新驗證，而不會改用外部命令列介面的權杖資料。 Codex 命令列介面啟動程序的範圍更窄：它只能在 OpenClaw 尚未擁有該 供應商的 OAuth 前，為空白的 openai:default 樣式設定檔植入初始資料；此後，由 OpenClaw 執行的重新整理會維持為標準來源
  • 狀態／啟動路徑會將外部命令列介面探索限制於 已設定的供應商集合，因此單一供應商設定不會探查 無關命令列介面的登入儲存區

儲存空間（權杖的存放位置）

祕密會依代理程式分別儲存，並以邏輯名稱 auth-profiles.json 作為索引鍵（ 底層儲存區是代理程式的 SQLite 資料庫；為了 相容性與工具顯示，仍保留 JSON 名稱）：

  • 驗證設定檔（OAuth + API 金鑰 + 選用的值層級參照）： ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 舊版相容性檔案：~/.openclaw/agents/<agentId>/agent/auth.json （發現靜態 api_key 項目時會將其清除）

僅供舊版匯入的檔案（仍受支援，但不是主要儲存區）：

  • ~/.openclaw/credentials/oauth.json（首次使用時匯入驗證設定檔儲存區）

上述所有項目也都遵循 $OPENCLAW_STATE_DIR（狀態目錄覆寫）。完整參考資料：/gateway/configuration-reference#auth-storage

如需靜態祕密參照與執行階段快照啟用行為的相關資訊，請參閱祕密管理。

當次要代理程式沒有本機驗證設定檔時，OpenClaw 會以唯讀穿透方式 繼承預設／主要代理程式的儲存區；讀取時不會複製主要 代理程式的儲存區。OAuth 重新整理權杖尤其敏感：一般 複製流程預設會略過這些權杖，因為有些供應商會在使用後輪替或使 重新整理權杖失效。當代理程式需要獨立帳號時，請為其設定 個別的 OAuth 登入。

Anthropic Claude 命令列介面重複使用

OpenClaw 支援將 Anthropic Claude 命令列介面重複使用與 claude -p 作為允許的 驗證路徑。如果主機上已有本機 Claude 登入， 初始設定／設定程序可直接重複使用。Anthropic setup-token 仍可作為受支援的權杖驗證路徑， 但在可用時，OpenClaw 會優先重複使用 Claude 命令列介面。

OAuth 交換（登入運作方式）

OpenClaw 的互動式登入流程實作於 openclaw/plugin-sdk/llm.ts，並連接至精靈／命令。

Anthropic setup-token

流程形式：

  1. 在任何已安裝 Claude Code 的機器上執行 claude setup-token 以建立權杖，然後從 OpenClaw 啟動 Anthropic setup-token 或 paste-token
  2. OpenClaw 會將產生的 Anthropic 認證資訊儲存在驗證設定檔中
  3. 模型選擇會維持在 anthropic/...
  4. 現有的 Anthropic 驗證設定檔仍可用於復原／順序控制

OpenAI Codex（ChatGPT OAuth）

OpenAI Codex OAuth 明確支援在 Codex 命令列介面以外使用，包括 OpenClaw 工作流程。

登入命令使用標準 OpenAI 供應商 ID：

bash
openclaw models auth login --provider openai

若要在一個代理程式中使用多個 ChatGPT/Codex OAuth 帳號， 請使用 --profile-id openai:<name>。不要將 openai-codex:<name> 用於新設定檔。Doctor 會將 該舊前綴移轉為不會發生衝突的 openai:* 設定檔 ID；修復後請先執行 openclaw models auth list --provider openai，再將 設定檔 ID 複製到 auth.order 或 /model ...@<profileId>。

流程形式（PKCE）：

  1. 產生 PKCE 驗證碼／挑戰碼與隨機 state
  2. 開啟 https://auth.openai.com/oauth/authorize?...（範圍 openid profile email offline_access）
  3. 嘗試在 http://localhost:1455/auth/callback 擷取回呼（ 回呼主機預設為 localhost，且僅接受回送主機； 可使用 OPENCLAW_OAUTH_CALLBACK_HOST 覆寫）
  4. 如果你能在回呼抵達前貼上程式碼（或你處於 遠端／無介面環境且回呼無法繫結），請改為貼上重新導向 URL／程式碼—— 手動貼上會與瀏覽器回呼競速，先完成者勝出
  5. 在 https://auth.openai.com/oauth/token 交換程式碼
  6. 從存取權杖擷取 accountId，並儲存 { access, refresh, expires, accountId }

精靈路徑為 openclaw onboard → 驗證選項 openai。

重新整理 + 到期

設定檔會儲存 expires 時間戳記。在執行階段：

  • 如果 expires 是未來時間，使用已儲存的存取權杖
  • 如果已到期，則進行重新整理（在檔案鎖定下），並覆寫已儲存的認證資訊
  • 如果次要代理程式讀取繼承自主要代理程式的 OAuth 設定檔， 重新整理結果會寫回主要代理程式的儲存區，而不會將重新整理 權杖複製到次要代理程式的儲存區
  • 由外部管理的命令列介面認證資訊（Claude 命令列介面、範圍有限的 Codex 命令列介面啟動程序； 請參閱權杖匯集處）會重新讀取，而不會 耗用已複製的重新整理權杖。如果受管理的重新整理失敗，OpenClaw 會回報受影響的設定檔需要重新驗證，而不會傳回 外部命令列介面的權杖資料。

重新整理流程會自動進行；你通常不需要手動管理權杖。

多個帳號（設定檔）+ 路由

有兩種模式：

1) 建議方式：個別代理程式

如果你希望「個人」與「工作」永不互動，請使用隔離的代理程式（個別的工作階段 + 認證資訊 + 工作區）：

bash
openclaw agents add workopenclaw agents add personal

接著依代理程式設定驗證（使用精靈），並將聊天路由至正確的代理程式。

2) 進階方式：在一個代理程式中使用多個設定檔

驗證設定檔儲存區支援同一供應商使用多個設定檔 ID。 選擇要使用的設定檔：

  • 透過設定順序全域選擇（auth.order）
  • 透過 /model ...@<profileId> 依工作階段選擇

範例（工作階段覆寫）：

  • /model Opus@anthropic:work

使用以下命令列出現有設定檔 ID：

bash
openclaw models auth list --provider <id>

相關文件：

相關內容

Was this useful?
On this page

On this page