OpenClaw 的 OAuth 通过 Token sink 集中管理凭据，避免 OpenClaw 与其他 CLI（如 Claude Code 或 Codex CLI）同时登录同一账号时随机登出。支持多 Profile 路由和自动刷新，配置可通过 openclaw onboard 向导完成，Token 存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json。生产环境推荐 Anthropic API key。

OpenClaw OAuth 配置：Token 存储、多账号路由与 Anthropic 兼容

OpenClaw 对部分 provider 支持“订阅式 Auth”（OAuth）。当前重点：

• OpenAI Codex（ChatGPT OAuth）：明确支持在 OpenClaw 等外部工具中使用
• Anthropic：API key 是生产环境推荐路径；Claude CLI 重用（claude -p）被 Anthropic 工作人员告知再次允许

Token Sink（为什么需要它）

OAuth provider 通常在登录/刷新时签发新的 refresh token，部分 provider（或 OAuth 客户端）会在新 token 签发时使旧 token 失效。

典型症状：你同时在 OpenClaw 和 Claude Code / Codex CLI 登录同一账号 → 其中一个随机“被登出”。

OpenClaw 通过将 auth-profiles.json 作为 token sink 解决这个问题：

• 运行时只从一个地方读取凭据
• 可以管理多个 profile 并确定性路由
• 复用外部 CLI（如 Codex CLI）的凭据时，OpenClaw 只镜像，不消耗 refresh token
• 外部 CLI 发现范围限定在已配置的 provider 集合，不会扫描无关的 CLI 登录存储

Token 存储位置

密钥按 per-agent 存储：

• 主存储：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 旧兼容文件：~/.openclaw/agents/<agentId>/agent/auth.json（静态 api_key 条目在发现时被擦除）
• 遗留 import 文件：~/.openclaw/credentials/oauth.json（首次使用时导入到 auth-profiles.json）

所有路径也支持 $OPENCLAW_STATE_DIR 环境变量覆盖。完整参考：auth 存储配置

当二级 agent 没有本地 auth profile 时，OpenClaw 会从默认主 agent 存储读取继承（不复制 auth-profiles.json）。OAuth refresh token 特别敏感：普通复制流程默认跳过，因为部分 provider 在使用后轮转或使其失效。如果需要独立账号，请为 agent 配置单独 OAuth 登录。

Anthropic Claude CLI 兼容与迁移

Warning
Anthropic 公开的 Claude Code 文档说明直接使用 Claude Code 在订阅限制内，Anthropic 工作人员告诉我们在 OpenClaw 中重用 Claude CLI 目前再次允许。OpenClaw 因此将 Claude CLI 重用和 claude -p 视为该集成中的授权行为，除非 Anthropic 发布新政策。
如需其他订阅式选项，可参考：OpenAI Codex、Qwen Cloud Coding Plan、MiniMax Coding Plan、Z.AI / GLM Coding Plan。

OpenClaw 也支持 Anthropic setup-token 作为 token-auth 路径，但现在优先使用 Claude CLI 重用和 claude -p。

Anthropic Claude CLI 迁移

如果你已在主机上本地登录 Claude，配置向导可以直接重用该登录。

OAuth 授权流程

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

Anthropic setup-token

1. 从 OpenClaw 启动 Anthropic setup-token 或粘贴 token
2. OpenClaw 将生成的 Anthropic 凭据存入 auth profile
3. 模型选择保持在 anthropic/...
4. 已有的 Anthropic auth profile 可回滚/控制顺序

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. 如果回调无法绑定（远程/无头模式），粘贴 redirect URL/code
5. 在 https://auth.openai.com/oauth/token 交换 token
6. 从 access token 提取 accountId 并存储 { access, refresh, expires, accountId }

Wizard 路径：openclaw onboard → 选择 openai-codex

Token 刷新与过期

Profile 存储 expires 时间戳。运行时：

• expires 在未来 → 直接使用已存储的 access token
• 已过期 → 在文件锁下刷新并覆写存储的凭据
• 如果二级 agent 读取继承的主 agent OAuth profile，刷新写入主 agent 存储，不将 refresh token 复制到二级 agent 存储
• 例外：某些外部 CLI 凭据保持外部管理；OpenClaw 重新读取 CLI auth 存储，不消耗复制来的 refresh token。Codex CLI 启动特意更窄：它播种空 openai-codex:default profile，之后 OpenClaw 拥有的刷新使本地 profile 成为规范。如果本地 Codex 刷新失败且 Codex CLI 有同一账号的可用 token，OpenClaw 可以在当前运行时请求中使用该 token，但不写回 auth-profiles.json

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

多账号（Profiles）路由

方案一（推荐）：独立 Agent

个人和工作账号完全不交叉，使用隔离 Agent（独立会话 + 凭据 + workspace）：

openclaw agents add work
openclaw agents add personal

然后通过 wizard 为每个 agent 配置 Auth，并路由聊天到对应 agent。

方案二（高级）：单 Agent 多 Profile

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

选择使用哪个 profile：

• 全局：通过 auth.order 配置顺序
• 会话级：/model ...@<profileId>（示例：/model Opus@anthropic:work）

查看已有 profile ID：

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

相关参考：

• 模型故障转移（轮转 + 冷却规则）
• 斜杠命令（命令面）

相关

• 身份验证 – 模型 provider auth 概览
• Secrets 管理 – 凭据存储与 SecretRef
• 配置参考 – auth 配置键

常见问题

在 OpenClaw 登录后，其他 CLI（Claude Code / Codex CLI）被登出怎么办？

Token sink 机制减少了此问题：集中管理凭据后，只有 OpenClaw 持有规范 refresh token。如果两个客户端同时活跃刷新，仍可能冲突。建议只使用 OpenClaw 登录，不手动在外部 CLI 重复登录。

Anthropic API key 和 Claude CLI 登录有什么区别？生产环境用哪个？

API key 更简单、稳定，是生产环境推荐路径。Claude CLI 登录（订阅式）受 Anthropic 政策影响，虽然目前允许在 OpenClaw 中重用，但可能随时变化。API key 无此风险。

怎么配置多账号？同一个 Provider 能同时登录个人和工作账号吗？

推荐方案：使用隔离的 agent（openclaw agents add work 和 openclaw agents add personal），每个 agent 独立配置 OAuth 或 API key。高级用法：在单 agent 内设置多个 profile，通过 auth.order 或 /model ...@<profileId> 切换。查看 profile ID 用 openclaw channels list --json。