跳转至

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 流程的提供商插件都通过同一个入口运行:

openclaw models auth login --provider <id>

在 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

流程结构:

  1. 在任意安装了 Claude Code 的机器上运行 claude setup-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 中,如需使用多个 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):

  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. 如果可以在回调到达之前粘贴 code(或者你处于远程/无头环境,回调无法绑定),则改为粘贴重定向 URL/code——手动粘贴与浏览器回调竞争,先完成者胜出
  5. 在 https://auth.openai.com/oauth/token 交换 code
  6. 从 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):

openclaw agents add work
openclaw agents add personal

然后按 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。

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

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

openclaw models accounts list

对于共享或代理本地配置文件 ID,请使用:

openclaw models auth list --provider <id>

相关文档:

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw