OAuth

OpenClaw 支持通过 OAuth 进行”订阅认证”，适用于提供此功能的 Provider（特别是 OpenAI Codex (ChatGPT OAuth)）。对于 Anthropic 订阅，请使用 setup-token 流程。本页面介绍：

  • OAuth Token 交换的工作原理（PKCE）
  • Token 存储位置（以及原因）
  • 如何处理多个账号（Profile + 单次会话覆盖）

OpenClaw 还支持 Provider Plugin，它们自带 OAuth 或 API Key 流程。运行方式：

openclaw models auth login --provider <id>

Token Sink（为什么需要它）

OAuth Provider 通常会在登录或刷新流程中生成新的 Refresh Token。某些 Provider（或 OAuth 客户端）会在为同一用户/应用颁发新 Token 时，使旧的 Refresh Token 失效。

实际表现：

  • 你同时通过 OpenClaw 和 Claude Code / Codex CLI 登录 → 其中一个会随机”登出”

为了减少这种情况，OpenClaw 将 auth-profiles.json 作为 Token Sink：

  • Runtime 从同一位置读取凭证
  • 我们可以保留多个 Profile 并确定性地路由它们

存储位置（Token 存放在哪里）

密钥按 Agent 存储：

  • Auth Profile（OAuth + API Key）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Runtime 缓存（自动管理，不要编辑）：~/.openclaw/agents/<agentId>/agent/auth.json

旧版仅导入文件（仍支持，但不是主存储）：

  • ~/.openclaw/credentials/oauth.json（首次使用时导入到 auth-profiles.json）

以上所有路径都遵循 $OPENCLAW_STATE_DIR（状态目录覆盖）。完整参考：/gateway/configuration

Anthropic setup-token（订阅认证）

在任意机器上运行 claude setup-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 (Claude Pro/Max) setup-token

流程形式：

  1. 运行 claude setup-token
  2. 将 Token 粘贴到 OpenClaw
  3. 存储为 Token Auth Profile（无刷新）

向导路径是 openclaw onboard → 认证选择 setup-token (Anthropic)。

OpenAI Codex (ChatGPT OAuth)

流程形式（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 时间戳。

Runtime 运行时：

  • 如果 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 支持同一 Provider 的多个 Profile ID。

选择使用哪个 Profile：

  • 全局通过配置顺序（auth.order）
  • 单次 Session 通过 /model ...@<profileId>

示例（Session 覆盖）：

  • /model Opus@anthropic:work

查看存在哪些 Profile ID：

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

相关文档：