OpenClaw 🦞

OAuth

OAuth

OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供它的提供者（特别是OpenAI Codex (ChatGPT OAuth)）。对于 Anthropic 订阅，使用setup-token流程。Anthropic 订阅在 Claude Code 之外的使用过去曾被一些用户限制，因此将其视为用户选择风险并自行验证当前 Anthropic 策略。OpenAI Codex OAuth 明确支持在 OpenClaw 工作流等外部工具中使用。此页面解释：

对于生产中的 Anthropic，API 密钥认证是比订阅 setup-token 认证更安全的推荐路径。

  • OAuth令牌交换如何工作（PKCE）
  • 令牌存储在哪里（以及为什么）
  • 如何处理多账户（配置文件 + 每会话覆盖）

OpenClaw 还支持提供者插件，它们提供自己的 OAuth 或 API 密钥流程。通过以下方式运行它们：

openclaw models auth login --provider <id>

令牌接收器（为什么存在）

OAuth 提供者通常在登录/刷新流程期间铸造新的刷新令牌。一些提供者（或 OAuth 客户端）在为同一用户/应用发出新令牌时可以使旧的刷新令牌失效。

实际症状：

  • 你通过 OpenClaw 和 通过 Claude Code / Codex CLI 登录 → 其中一个后来随机"注销"

为减少这种情况，OpenClaw 将 auth-profiles.json 视为令牌接收器：

  • 运行时从一个地方读取凭据
  • 我们可以保留多个配置文件并确定性地路由它们

存储（令牌存在的地方）

机密每 agent存储：

  • 认证配置文件（OAuth + API 密钥 + 可选值级引用）：~/.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（状态目录覆盖）。完整参考：/gateway/configuration

对于静态机密引用和运行时快照激活行为，参见 Secrets Management。

Anthropic setup-token（订阅认证）

Anthropic setup-token 支持是技术兼容性，不是策略保证。 Anthropic 过去曾阻止 Claude Code 之外的一些订阅使用。 自行决定是否使用订阅认证，并验证 Anthropic 的当前条款。

在任何机器上运行 claude setup-token，然后将其粘贴到 OpenClaw：

openclaw models auth setup-token --provider anthropic

如果你在其他地方生成令牌，手动粘贴它：

openclaw models auth paste-token --provider anthropic

验证：

openclaw models status

OAuth 交换（登录如何工作）

OpenClaw 的交互式登录流程在 @mariozechner/pi-ai 中实现，并连接到向导/命令。

Anthropic setup-token

流程形状：

  1. 运行 claude setup-token
  2. 将令牌粘贴到 OpenClaw
  3. 存储为令牌认证配置文件（无刷新）

向导路径是 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. 如果回调无法绑定（或你是远程/headless），粘贴重定向 URL/代码
  5. 在 https://auth.openai.com/oauth/token 交换
  6. 从访问令牌提取 accountId 并存储 { access, refresh, expires, accountId }

向导路径是 openclaw onboard → 认证选择 openai-codex。

刷新 + 到期

配置文件存储 expires 时间戳。

运行时：

  • 如果 expires 在未来 → 使用存储的访问令牌
  • 如果到期 → 刷新（在文件锁下）并覆盖存储的凭据

刷新流程是自动的；你通常不需要手动管理令牌。

多账户（配置文件）+ 路由

两种模式：

1) 首选：单独的 agent

如果你希望"personal"和"work"从不交互，使用隔离的 agent（单独的会话 + 凭据 + 工作空间）：

openclaw agents add work
openclaw agents add personal

然后为每个 agent 配置认证（向导）并将聊天路由到正确的 agent。

2) 高级：一个 agent 中的多个配置文件

auth-profiles.json 支持同一提供者的多个配置文件 ID。

选择使用哪个配置文件：

  • 通过配置排序全局（auth.order）
  • 通过 /model ...@<profileId> 每会话

示例（会话覆盖）：

  • /model Opus@anthropic:work

如何查看存在哪些配置文件 ID：

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

相关文档：