OAuth

OpenClaw 为支持 OAuth（“订阅认证”）的提供商提供 OAuth 支持，尤其是 OpenAI Codex（ChatGPT OAuth） 和 Anthropic Claude CLI 复用。对于 Anthropic，实际区别如下：

• Anthropic API key：常规 Anthropic API 计费。
• Anthropic Claude CLI / OpenClaw 内的订阅认证：Anthropic 工作人员告诉我们，这种用法已重新获准，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 claude -p 用法视为该集成的合规用法。对于生产环境中的 Anthropic，API key 认证仍是更安全的推荐路径。

OpenClaw 将 OpenAI API key 认证和 ChatGPT/Codex OAuth 都存储在标准提供商 ID openai 下。旧的 openai-codex:* profile ID 和 auth.order.openai-codex 条目是可由 openclaw doctor --fix 修复的旧式状态；新配置请使用 openai:* profile ID 和 auth.order.openai。

本页内容包括：

• OAuth 令牌交换 如何工作（PKCE）
• 令牌存储在哪里（以及原因）
• 如何处理多个账户（profiles + 每会话覆盖）

自带 OAuth 或 API key 流程的提供商插件也通过同一入口运行：

openclaw models auth login --provider <id>

在 Control UI 中，打开 Settings → Models → Connect provider 即可保存受支持的账户，而无需请求模型回复。Model Setup 中的 Connect provider 会打开同一个选择器和连接流程。当你想验证并选择模型时，请选择 Test & use。仅支持完整设置的插件会保留其独立的设置操作。

OpenClaw 的浏览器回调页面会跟随系统浅色或深色外观。如果页面显示 Authorization received，请返回终端，OpenClaw 会完成令牌交换并保存账户。登录完成后，终端或 Control UI 会给出提示。

令牌汇点（它为何存在）¶

OAuth 提供商通常会在每次登录/刷新时签发新的 refresh token。对于同一用户/应用，有些提供商在签发新 token 时会使旧 refresh token 失效。实际症状：通过 OpenClaw 和 Claude Code / Codex CLI 登录后，其中一个会在之后随机被登出。

为了减少这种情况，OpenClaw 将 auth profile 存储视为令牌汇点：

• 运行时为每个 agent 从一个位置读取凭据
• 多个 profile 可以共存并确定性路由
• 外部 CLI 复用因提供商而异：一旦 OpenClaw 拥有某提供商的本地 OAuth profile，本地 refresh token 就是权威来源。如果该本地 refresh token 被拒绝，OpenClaw 会报告该 profile 需要重新认证，而不是回退到外部 CLI 的 token 材料。Codex CLI 引导甚至更受限：在 OpenClaw 拥有该提供商的 OAuth 之前，它只能初始化一个空的 openai:default 风格 profile；之后，OpenClaw 拥有的刷新令牌始终保持权威来源
• 状态/启动路径会将外部 CLI 发现范围限定在已配置的提供商集合内，因此单提供商设置不会探测无关的 CLI 登录存储

存储（令牌存放位置）¶

凭据使用共享的直读基础存储，而每个 agent 拥有自己的本地凭据覆盖和认证路由状态：

• 共享凭据：~/.openclaw/state/openclaw.sqlite
• Agent 本地凭据和状态： ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• Agent 凭据行：auth_profile_store
• Agent 顺序、last-good、cooldown 和 usage 行：auth_profile_state

从 Profile 或通过 models accounts login 添加的个人账户，会在所选 Gateway 的共享状态数据库中使用私有的、按身份作用域隔离的记录：model-accounts 拥有所选的链接，每个凭据都有自己的 model-account:<profile-id> 记录，其中包含其 secret 和使用状态。每次运行只会加载一个所选的个人 profile；普通的共享账户读取永远不会枚举这些记录。个人 OAuth 刷新会写回该用户的账户记录，而不是共享或 agent 本地的凭据。

较旧的安装可能仍包含 auth-profiles.json、auth-state.json 或每个 agent 的 auth.json。升级后请运行一次 openclaw doctor --fix。Doctor 会导入已验证的值，记录迁移回执，并将原始文件重命名为带时间戳的归档文件。

旧的共享 credentials/oauth.json 导入器已退役。Doctor 不会改动该文件，并会提示需要先升级到 2026.9.5，才能导入它，然后再安装最新版本。

运行时绝不会使用这些退役文件中的凭据。当某个受支持的导入文件仍然存在时，会发生什么取决于 SQLite 是否已经能为该 agent 提供凭据：

• 存储中已有 profile 记录：退役文件只是多余的字节。运行时会记录一条一次性的警告，指出该文件名并继续工作；Doctor 会在下一次 --fix 时将其归档。Doctor 绝不会用导入的值覆盖可用的已存储凭据，因此该文件无法让过期 token 复活。
• 存储为空：运行时只读取 auth-profiles.json 中的提供商元数据来界定 AUTH_PROFILE_MIGRATION_REQUIRED。其中列出的提供商不能回退到环境或配置认证；无关的提供商继续正常解析。错误消息和 Doctor 的发现结果会列出受影响的提供商及恢复命令 openclaw doctor --fix。
• 如果无法确定提供商范围（包括 JSON 格式错误或其他已退役凭据格式），该拒绝将保持为 agent 级。Gateway 启动时会降级凭据所有者，而不是拒绝启动。凭据写入和快照发布会保持受限，直到迁移被清除。

数据库和迁移来源都会遵循 $OPENCLAW_STATE_DIR。完整参考：/gateway/config-secrets-env#auth-storage

有关静态 secret 引用和运行时快照激活行为，请参阅 Secrets Management。

当 agent 没有本地 auth profile 时，OpenClaw 会读取共享的 auth 存储；它不会将共享凭据克隆到 agent 数据库中。OAuth refresh token 尤其敏感：普通的复制流程默认会跳过它们，因为有些提供商在使用后会轮换 refresh token 或使其失效。当 agent 需要独立账户时，请为它配置单独的 OAuth 登录。

Anthropic Claude CLI 复用¶

OpenClaw 支持 Anthropic Claude CLI 复用，并将 claude -p 作为受认可的认证路径。如果你在主机上已有本地 Claude 登录，onboarding/configure 流程可以直接复用该登录。Anthropic setup-token 仍然作为受支持的 token 认证路径可用，但 OpenClaw 在可用时更偏好 Claude CLI 复用。

OAuth 交换（登录如何工作）¶

OpenClaw 的 OAuth 注册表和适配器位于 src/llm/utils/oauth/。共享的 provider 辅助程序位于 src/plugin-sdk/provider-oauth-runtime.ts 和 src/plugin-sdk/provider-auth-runtime.ts。src/commands/models/auth.ts 中的 auth 命令会运行选定的 provider 方法，并持久化返回的 profiles。

在 Model Setup 中重新开始登录¶

在 Model Setup 中，再次开始相同的登录会替换你在同一 agent 和 workspace 中未完成的尝试。这包括 Sign in with ChatGPT 和其他 provider 登录流程。请使用最新的浏览器链接；来自前一次尝试的回调将不再被接受。

其他用户的登录、不同的设置流程，或已经在保存凭据/配置的尝试仍受到保护。请等待该操作完成后再重试。

Anthropic setup-token¶

流程结构：

1. 在任意安装了 Claude Code 的机器上运行 claude setup-token 创建 token，然后从 OpenClaw 启动 Anthropic setup-token 或 paste-token
2. OpenClaw 将生成的 Anthropic 凭据存储到一个 auth profile 中
3. 模型选择保持在 anthropic/...
4. 现有的 Anthropic auth profiles 仍可用于回滚/顺序控制

OpenAI Codex（ChatGPT OAuth）¶

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

登录命令使用标准的 OpenAI provider id：

openclaw models auth login --provider openai

在同一个 agent 中，使用 --profile-id openai:<name> 来管理多个 ChatGPT/Codex OAuth 账户。不要为新 profiles 使用 openai-codex:<name>。Doctor 会将那个旧前缀迁移为无冲突的 openai:* profile id；修复后，在将 profile id 复制到 auth.order 或 /model ...@<profileId> 之前，先运行 openclaw models auth list --provider openai。

流程结构（PKCE）：

1. 生成一个 PKCE verifier/challenge 和一个随机的 state
2. 打开 https://auth.openai.com/oauth/authorize?...（scope 为 openid profile email offline_access）
3. 尝试在 http://localhost:1455/auth/callback 上捕获回调（回调主机默认为 localhost，且仅接受 loopback 主机；可通过 OPENCLAW_OAUTH_CALLBACK_HOST 覆盖）
4. 如果你能在回调到达之前粘贴代码（或者你处于远程/无头环境，且回调无法绑定），请改而粘贴重定向 URL/代码——手动粘贴会与浏览器回调竞争，先完成者生效
5. 在 https://auth.openai.com/oauth/token 处交换代码
6. 从访问 token 中提取 accountId，并存储 { access, refresh, expires, accountId }

向导路径为 openclaw onboard → auth 选项选择 openai。

刷新与过期¶

Profiles 会存储 expires 时间戳。在运行时：

• 如果 expires 在将来，则使用存储的访问 token
• 如果已过期，则刷新并将新凭据保存回所属的 SQLite 存储
• 如果 agent 从共享存储读取 OAuth profile，则刷新会写回该共享所有者，而不是将刷新 token 复制到 agent 存储中
• 外部管理的 CLI 凭据（Claude CLI、窄范围 Codex CLI 引导；参见 token 汇聚点）会被重新读取，而不是消耗复制的刷新 token。如果受管理的刷新失败，OpenClaw 会报告受影响的 profile 以进行重新认证，而不是返回外部 CLI token 材料。

刷新流程是自动的；你通常无需手动管理 token。

多账户（profiles）+ 路由¶

三种模式：

1) 首选：独立 agent¶

如果你希望“个人”和“工作”永不互相干扰，请使用隔离的 agent（独立的会话 + 凭据 + workspace）：

openclaw agents add work
openclaw agents add personal

然后按 agent 配置 auth（使用向导），并将聊天路由到正确的 agent。

2) 高级：在一个 agent 中使用多个 profile¶

auth profile 存储支持同一 provider 的多个 profile ID。选择要使用哪一个：

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

示例（会话覆盖）：

• /model Opus@anthropic:work -s

3) 多用户：个人账户¶

在共享 Gateway 上，每个经过验证的人员都可以在 Settings → Profile → Connected accounts 中按 provider 保存多个账户，并选择其中一个作为新聊天的默认账户。Add account 和 openclaw models accounts login 使用相同的 Gateway 所属 provider 与登录方式目录。Anthropic 个人设置接受 API key，而不是 Claude 订阅 token；系统/agent 认证仍然是独立的流程。

两个登录界面在请求 provider 凭据之前，都会显示 Gateway、经过验证的人员和 Personal 范围。Gateway 身份与 provider 登录是分开的；共享的 Gateway token 无法识别个人身份。参见 个人账户 CLI 设置。

在新会话或现有聊天中的模型选择器可以为该聊天选择一个账户，而不会更改默认设置。按顺序排列的共享账户仍然是同一提供者的故障转移候选项；该选择不构成计费保证。个人凭据保留在共享配置文件列表之外。参见每人模型账户。

使用以下命令列出已保存的个人账户：

openclaw models accounts list

对于共享或代理本地配置文件 ID，使用：

openclaw models auth list --provider <id>

相关文档：

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

相关¶

• OpenAI 身份验证 - 登录方法、身份和能力
• 身份验证 - 模型提供者身份验证概览
• 密钥 - 凭据存储和 SecretRef
• 配置参考 - 身份验证配置键
• 身份验证凭据语义 - 身份验证配置文件排序和运行时凭据解析的规范规则