OAuth

OpenClaw 通过 OAuth 支持”订阅认证”，适用于提供此功能的服务商（主要是 OpenAI Codex（ChatGPT OAuth））。Anthropic 订阅认证走的是 setup-token 流程。Anthropic 过去曾限制部分用户在 Claude Code 之外使用订阅，所以这属于用户自行承担的风险——请自行确认 Anthropic 的最新政策。OpenAI Codex OAuth 明确支持在 OpenClaw 等外部工具中使用。本页将介绍：

在生产环境中使用 Anthropic，API key 认证是比订阅 setup-token 更稳妥的方案。

OAuth 令牌交换的工作原理（PKCE）
令牌的存储位置（以及为什么这样设计）
如何处理多账号（profiles + 按会话覆盖）

OpenClaw 还支持服务商插件自带的 OAuth 或 API key 流程。通过以下命令启动：

openclaw models auth login --provider <id>

Token sink（为什么需要它）

OAuth 服务商在登录/刷新时通常会签发新的 refresh token。部分服务商（或 OAuth 客户端）在为同一用户/应用签发新 token 时，会使旧 token 失效。

实际症状：

你同时通过 OpenClaw 和 Claude Code / Codex CLI 登录 → 其中一个随后会被”踢下线”

为了缓解这个问题，OpenClaw 把 auth-profiles.json 当作统一的 token 汇聚点：

运行时只从一个地方读取凭据
可以维护多个 profile，按确定性规则路由

存储（令牌存放在哪里）

凭据按 agent 维度存储：

Auth profiles（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（状态目录覆盖）。完整参考：/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

如果 token 是在别处生成的，手动粘贴即可：

openclaw models auth paste-token --provider anthropic

验证：

openclaw models status

OAuth 交换（登录的工作流程）

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

Anthropic setup-token

流程概要：

运行 claude setup-token
把 token 粘贴到 OpenClaw
以 token auth profile 形式存储（无需刷新）

向导路径：openclaw onboard → 认证方式选择 setup-token（Anthropic）。

OpenAI Codex（ChatGPT OAuth）

OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工作流。

流程概要（PKCE）：

生成 PKCE verifier/challenge + 随机 state
打开 https://auth.openai.com/oauth/authorize?...
尝试在 http://127.0.0.1:1455/auth/callback 上捕获回调
如果无法绑定端口（或在远程/无头环境下），手动粘贴重定向 URL/code
在 https://auth.openai.com/oauth/token 完成令牌交换
从 access token 中提取 accountId，存储 { access, refresh, expires, accountId }

向导路径：openclaw onboard → 认证方式选择 openai-codex。

刷新与过期

Profile 中存储了 expires 时间戳。

运行时逻辑：

expires 还没到 → 直接用已存储的 access token
已过期 → 在文件锁保护下刷新，并覆盖写入存储的凭据

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

多账号（profiles）与路由

两种方案：

1) 推荐：独立 agent

如果希望”个人”和”工作”完全隔离，使用独立的 agent（各自有独立的会话 + 凭据 + 工作空间）：

openclaw agents add work
openclaw agents add personal

然后为每个 agent 单独配置认证（通过向导），把聊天路由到对应的 agent。

2) 进阶：同一 agent 下多个 profile

auth-profiles.json 支持同一服务商下的多个 profile ID。

选择使用哪个 profile：

全局配置排序（auth.order）
按会话指定：/model ...@<profileId>

示例（会话级覆盖）：

/model Opus@anthropic:work

查看已有的 profile ID：

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