OAuth

OpenClaw 支持通过 OAuth 进行"订阅认证"（主要用于 OpenAI Codex / ChatGPT OAuth）。对于 Anthropic 订阅，可以使用 setup-token 流程，或复用 gateway 主机上的本地 Claude CLI 登录。由于 Anthropic 过去曾限制 Claude Code 以外的订阅使用，请自行评估风险并核实当前 Anthropic 政策。OpenAI Codex OAuth 明确支持在 OpenClaw 等外部工具中使用。

在生产环境中，Anthropic API key 认证是比订阅 setup-token 更安全的推荐路径。

本页介绍：

• OAuth 令牌交换的工作方式（PKCE）
• Token 的存储位置（及原因）
• 如何管理多个账号（profile + per-session 覆盖）

OpenClaw 还支持提供自有 OAuth 或 API key 流程的 provider 插件，通过以下命令运行：

openclaw models auth login --provider <id>

Token 汇聚池（为何存在）

OAuth provider 通常在登录/刷新流程中会铸造新的 refresh token。某些 provider（或 OAuth 客户端）在为同一用户/应用签发新 token 时，会使旧的 refresh token 失效。

实际症状：

• 你同时通过 OpenClaw 和 Claude Code / Codex CLI 登录 → 其中一个之后随机被"登出"

为减少这种情况，OpenClaw 将 auth-profiles.json 视为 token 汇聚池：

• 运行时从一处读取凭据
• 可以保留多个 profile 并确定性地路由

存储（Token 存放位置）

密钥以 per-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（状态目录覆盖）。完整参考参见 /openclaw/gateway/index。

关于静态 secret ref 和运行时快照激活行为，参见 Secrets Management（如有相关文档）。

Anthropic setup-token（订阅认证）

警告：Anthropic setup-token 支持是技术兼容性，不代表策略保证。Anthropic 过去曾限制 Claude Code 以外的订阅使用。请自行决定是否使用订阅认证，并核实 Anthropic 当前条款。

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

openclaw models auth setup-token --provider anthropic

若在其他地方生成了 token，手动粘贴：

openclaw models auth paste-token --provider anthropic

验证：

openclaw models status

Anthropic Claude CLI 迁移

若 gateway 主机上已安装并登录了 Claude CLI，可切换 Anthropic 模型选择到本地 CLI 后端：

openclaw models auth login --provider anthropic --method cli --set-default

上线快捷方式：

openclaw onboard --auth-choice anthropic-cli

这会保留现有 Anthropic auth profile 以便回滚，但将主默认模型路径从 anthropic/... 改写为 claude-cli/...。

OAuth 交换（登录如何工作）

OpenClaw 的交互式登录流程在 @mariozechner/pi-ai 中实现，并集成到 wizard/命令中。

Anthropic setup-token / Claude CLI

Setup-token 路径：

1. 运行 claude setup-token
2. 将 token 粘贴到 OpenClaw
3. 以 token auth profile 存储（无刷新）

Claude CLI 路径：

1. 在 gateway 主机上用 claude auth login 登录
2. 运行 openclaw models auth login --provider anthropic --method cli --set-default
3. 不存储新 auth profile；切换模型选择到 claude-cli/...

Wizard 路径：

• openclaw onboard → 认证选项 anthropic-cli
• openclaw onboard → 认证选项 setup-token（Anthropic）

OpenAI Codex（ChatGPT OAuth）

OpenAI Codex OAuth 明确支持在 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 }

Wizard 路径：openclaw onboard → 认证选项 openai-codex。

刷新与过期

Profile 存储了 expires 时间戳。

运行时：

• 若 expires 在未来 → 使用存储的 access token
• 若已过期 → 刷新（加文件锁）并覆盖存储的凭据

刷新流程是自动的，通常不需要手动管理 token。

多账号（Profile）+ 路由

两种模式：

1）推荐：独立 Agent

若你希望"个人"和"工作"永不交叉，使用隔离 agent（独立 session + 凭据 + 工作空间）：

openclaw agents add work
openclaw agents add personal

然后按 per-agent 配置认证（wizard）并将聊天路由到正确的 agent。

养两只龙虾，一只管私事，一只跑工作，互不干扰。

2）进阶：单 Agent 内多 Profile

auth-profiles.json 支持同一 provider 的多个 profile ID。

选择使用哪个 profile：

• 全局：通过配置顺序（auth.order）
• per-session：通过 /model ...@<profileId>

示例（session 覆盖）：

• /model Opus@anthropic:work

查看已有的 profile ID：

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

相关文档：

• /openclaw/concepts/model-failover（轮换 + cooldown 规则）
• /openclaw/tools/exec（命令界面，如有相关文档）