OAuth
OpenClaw 为支持 OAuth 的提供商提供 OAuth(“订阅认证”)支持,尤其是 OpenAI Codex(ChatGPT OAuth) 和 Anthropic Claude CLI 复用。针对 Anthropic,实际区别如下:
- Anthropic API key:正常的 Anthropic API 计费。
- Anthropic Claude CLI / OpenClaw 内的订阅认证:Anthropic 工作人员告诉我们这种用法已再次获得允许,因此 OpenClaw 将 Claude CLI 复用和
claude -p用法视为该集成的授权行为,除非 Anthropic 发布新政策。对于生产环境中的 Anthropic,API key 认证仍然是更安全的推荐路径。
OpenClaw 将 OpenAI API key 认证和 ChatGPT/Codex OAuth 都存储在规范 provider id openai 下。旧的 openai-codex:* profile id 和 auth.order.openai-codex 条目是遗留状态,可由 openclaw doctor --fix 修复;新配置请使用 openai:* profile id 和 auth.order.openai。
本页涵盖:
- OAuth token 交换的工作原理(PKCE)
- token 的存储位置(以及原因)
- 如何处理多个账户(profile + 按会话覆盖)
自带 OAuth 或 API key 流程的提供商插件都通过同一个入口运行:
在 Control UI 中,打开 Settings → Models → Connect provider 即可保存受支持的账户,而无需请求模型回复。Model Setup 中的 Connect provider 会打开相同的选择器和连接流程。当你想要验证并选择模型时,请选择 Test & use。仅支持完整设置的插件会保留其单独的设置操作。
OpenClaw 的浏览器回调页面会跟随系统的浅色或深色外观。如果页面显示 Authorization received,请在 OpenClaw 完成交换并保存账户时返回终端。当登录完成时,终端或 Control UI 会进行报告。
Token sink(为什么存在)¶
OAuth 提供商通常会在每次登录/刷新时生成一个新的 refresh token。某些提供商在为同一用户/应用签发新 token 时会使之前的 refresh token 失效。实际症状:通过 OpenClaw 和 Claude Code / Codex CLI 登录后,其中一个稍后会被随机登出。
为减少这种情况,OpenClaw 将认证 profile 存储视为一个 token sink:
- 运行时每个 agent 只从一个位置读取凭据
- 多个 profile 可以共存并确定性路由
- 外部 CLI 复用是特定于提供商的:一旦 OpenClaw 拥有某个提供商的本地 OAuth profile,本地 refresh token 就是规范来源。如果该本地 refresh token 被拒绝,OpenClaw 会报告该 profile 需要重新认证,而不是回退到外部 CLI token 材料。Codex CLI 的引导则更局限:它只能在 OpenClaw 拥有该提供商的 OAuth 之前,播种一个空的
openai:default风格 profile;此后,OpenClaw 拥有的 refresh 继续作为规范来源 - 状态/启动路径会将外部 CLI 发现范围限定在已配置的提供商集合内,因此单提供商设置不会去检查不相关的 CLI 登录存储
存储(token 存放在哪里)¶
凭据使用共享的直读基础,而每个 agent 拥有自己的本地凭据覆盖和认证路由状态:
- 共享凭据:
~/.openclaw/state/openclaw.sqlite - Agent 本地凭据和状态:
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite - Agent 凭据行:
auth_profile_store - Agent 顺序、最近成功、冷却期和使用量行:
auth_profile_state
从 Profile 或 models accounts login 添加的个人账户,会在所选 Gateway 的共享状态数据库中使用私有身份作用域记录:model-accounts 拥有所选链接,每个凭据都有自己对应的 model-account:<profile-id> 记录,其中包含其机密和使用状态。一次运行只会加载一个被选中的个人 profile;普通的共享账户读取永远不会枚举这些记录。个人 OAuth refresh 会写回该人的账户记录,而不是共享或 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
关于静态机密引用和运行时快照激活行为,请参阅机密管理。
当一个 agent 没有本地认证 profile 时,OpenClaw 会读取共享认证存储;它不会将共享凭据克隆到 agent 数据库中。OAuth refresh token 尤其敏感:普通复制流程默认会跳过它们,因为某些提供商会在使用后轮换或使 refresh token 失效。当 agent 需要独立账户时,请为其配置单独的 OAuth 登录。
Anthropic Claude CLI 复用¶
OpenClaw 支持 Anthropic Claude CLI 复用,并将 claude -p 视为受认可的认证路径。如果你在主机上已有本地的 Claude 登录,onboarding/configure 可以直接复用它。Anthropic setup-token 仍然作为受支持的令牌认证路径可用,但 OpenClaw 在可用时优先选择 Claude CLI 复用。
Warning
Anthropic 公开的 Claude Code 文档指出,直接使用 Claude Code 仍受 Claude 订阅额度限制,而且 Anthropic 工作人员告诉我们,OpenClaw 风格的 Claude CLI 用法已重新获得允许。因此,除非 Anthropic 发布新政策,OpenClaw 将 Claude CLI 复用和 claude -p 用法视为本次集成的受认可方式。
关于 Anthropic 当前直接使用 Claude Code 的套餐文档,请参阅 在 Pro 或 Max 套餐中使用 Claude Code 和 在 Team 或 Enterprise 套餐中使用 Claude Code。
如果你希望在 OpenClaw 中使用其他订阅式选项,请参阅 OpenAI Codex、Qwen Cloud Coding Plan、MiniMax Coding Plan 和 Z.AI / GLM Coding Plan。
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 中的认证命令会运行所选 provider 的方法,并持久化返回的 profiles。
在 Model Setup 中重新启动登录¶
在 Model Setup 中,针对同一 agent 和工作区再次启动相同的登录,会替换你未完成的登录尝试。这包括 Sign in with ChatGPT 以及其他 provider 的登录流程。请使用最新的浏览器链接;之前尝试的回调将不再被接受。
其他用户的登录、不同的设置流程,或已在保存凭据或配置的尝试仍会受到保护。请等待该操作完成后再重试。
Anthropic setup-token¶
流程结构:
- 在任意安装了 Claude Code 的机器上运行
claude setup-token创建令牌,然后从 OpenClaw 启动 Anthropic setup-token 或 paste-token - OpenClaw 将生成的 Anthropic 凭据存储在 auth profile 中
- 模型选择保持在
anthropic/... - 现有的 Anthropic auth profiles 仍可用于回滚/顺序控制
OpenAI Codex(ChatGPT OAuth)¶
OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用,包括 OpenClaw 工作流。
登录命令使用规范的 OpenAI provider id:
在同一个 agent 中,如需使用多个 ChatGPT/Codex OAuth 账户,请使用 --profile-id openai:<name>。不要为新 profiles 使用 openai-codex:<name>。Doctor 会将较旧的前缀迁移为无冲突的 openai:* profile id;修复后,在将 profile id 复制到 auth.order 或 /model ...@<profileId> 之前,请先运行 openclaw models auth list --provider openai。
流程结构(PKCE):
- 生成 PKCE verifier/challenge 和一个随机
state - 打开
https://auth.openai.com/oauth/authorize?...(scope 为openid profile email offline_access) - 尝试在
http://localhost:1455/auth/callback上捕获回调(回调主机默认为localhost,且仅接受 loopback 主机;可通过OPENCLAW_OAUTH_CALLBACK_HOST覆盖) - 如果可以在回调到达之前粘贴 code(或者你处于远程/无头环境,回调无法绑定),则改为粘贴重定向 URL/code——手动粘贴与浏览器回调竞争,先完成者胜出
- 在
https://auth.openai.com/oauth/token交换 code - 从 access token 中提取
accountId,并存储{ access, refresh, expires, accountId }
向导路径为 openclaw onboard → 认证选择 openai。
刷新与过期¶
Profiles 存储 expires 时间戳。运行时:
- 如果
expires在未来,则使用存储的 access token - 如果已过期,则刷新并将新凭据保存回所属的 SQLite 存储
- 如果 agent 从共享存储读取 OAuth profile,刷新会写回该共享所有者,而不是将 refresh token 复制到 agent 存储中
- 外部托管的 CLI 凭据(Claude CLI、受限的 Codex CLI bootstrap;参见 The token sink)会被重新读取,而不是消耗复制的 refresh token。如果受管理的刷新失败,OpenClaw 会报告受影响的 profile 以进行重新认证,而不会返回外部 CLI 令牌数据。
刷新流程是自动的;通常你无需手动管理令牌。
多账户(profiles)与路由¶
三种模式:
1) 首选:独立 agents¶
如果你希望“个人”和“工作”永不互相干扰,请使用隔离的 agents(独立的 sessions + 凭据 + workspace):
然后按 agent 配置认证(向导),并将聊天路由到正确的 agent。
2) 高级:单个 agent 中的多个 profiles¶
auth profile 存储支持同一 provider 的多个 profile ID。选择使用哪一个:
- 全局:通过配置顺序(
auth.order) - 按会话:通过
/model ...@<profileId> -s
示例(会话级覆盖):
/model Opus@anthropic:work -s
3) 多用户:个人账户¶
在共享网关上,每个经过验证的人员可以在 Settings → Profile → Connected accounts 中为每个 provider 保存多个账户,并选择一个作为其新聊天默认账户。Add account 和 openclaw models accounts login 使用由 Gateway 管理的同一 provider 和登录方式目录。Anthropic 个人设置接受 API key,而不是 Claude 订阅令牌;系统/agent 认证仍是独立的流程。
两个登录界面都会在请求 provider 凭据之前显示 Gateway、经过验证的人员以及 Personal 范围。Gateway 身份与 provider 登录是分开的;共享的 Gateway token 不能标识个人。参见 personal-account CLI setup。
新会话或现有聊天中的模型选择器可以为该聊天选择一个账户,而无需更改默认设置。有序的共享账户仍为同提供商故障转移候选项;该选择不是计费保证。个人凭据保留在共享配置文件列表之外。参见每人模型账户。
使用以下命令列出已保存的个人账户:
对于共享或代理本地配置文件 ID,请使用:
相关文档:
相关¶
- OpenAI 身份验证 - 登录方法、身份和能力
- 身份验证 - 模型提供商身份验证概览
- 密钥 - 凭据存储和 SecretRef
- 配置参考 - 身份验证配置键
- 身份验证凭据语义 - 身份验证配置文件排序和运行时凭据解析的规范规则
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw