English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

基础

OAuth

OpenClaw 支持通过 OAuth 为提供该能力的提供商使用“订阅式认证” （尤其是 OpenAI Codex（ChatGPT OAuth））。对于 Anthropic，实际划分 现在是：

  • Anthropic API key：常规 Anthropic API 计费
  • Anthropic Claude CLI / OpenClaw 内的订阅式认证：Anthropic 员工 告诉我们这种用法已再次允许

OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具。本页说明：

对于生产环境中的 Anthropic，API key 认证是更安全的推荐路径。

  • OAuth 令牌交换的工作方式（PKCE）
  • 令牌存储在哪里（以及原因）
  • 如何处理多个账号（配置文件 + 按会话覆盖）

OpenClaw 还支持提供商插件，它们会自带 OAuth 或 API key 流程。通过以下命令运行：

bash
openclaw models auth login --provider <id>

令牌接收端（为什么存在）

OAuth 提供商通常会在登录/刷新流程中签发一个新的刷新令牌。某些提供商（或 OAuth 客户端）可能会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。

实际症状：

  • 你通过 OpenClaw 并且 通过 Claude Code / Codex CLI 登录 → 之后其中一个会随机“退出登录”

为减少这种情况，OpenClaw 将 auth-profiles.json 视为令牌接收端：

  • 运行时从一个位置读取凭证
  • 我们可以保留多个配置文件，并以确定性方式路由它们
  • 外部 CLI 复用是提供商特定的：Codex CLI 可以引导一个空的 openai-codex:default 配置文件，但一旦 OpenClaw 有了本地 OAuth 配置文件， 本地刷新令牌就是规范来源；其他集成可以保持由外部管理，并重新读取它们的 CLI 认证存储
  • 已经知道已配置提供商集合的状态和启动路径，会将外部 CLI 发现范围限制在该集合内， 因此单一提供商设置不会探测无关的 CLI 登录存储

存储（令牌存放在哪里）

密钥存储在 agent 认证存储中：

  • 认证配置文件（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。

当辅助 agent 没有本地认证配置文件时，OpenClaw 会使用从默认/主 agent 存储的读取穿透继承。它不会在读取时克隆主 agent 的 auth-profiles.json。OAuth 刷新令牌尤其敏感：普通复制流程默认会跳过它们，因为某些提供商会在使用后轮换 或失效刷新令牌。当某个 agent 需要独立账号时，请为它配置单独的 OAuth 登录。

Anthropic 旧版令牌兼容性

OpenClaw 也将 Anthropic setup-token 暴露为受支持的令牌认证路径，但现在会在可用时优先复用 Claude CLI 和 claude -p。

Anthropic Claude CLI 迁移

OpenClaw 再次支持复用 Anthropic Claude CLI。如果你已经在主机上有本地 Claude 登录，新手引导/配置可以直接复用它。

OAuth 交换（登录如何工作）

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

Anthropic setup-token

流程形态：

  1. 从 OpenClaw 启动 Anthropic setup-token 或 paste-token
  2. OpenClaw 将生成的 Anthropic 凭证存储在认证配置文件中
  3. 模型选择保持在 anthropic/...
  4. 现有 Anthropic 认证配置文件仍可用于回滚/顺序控制

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. 如果回调无法绑定（或你在远程/无头环境中），粘贴重定向 URL/code
  5. 在 https://auth.openai.com/oauth/token 交换
  6. 从访问令牌中提取 accountId 并存储 { access, refresh, expires, accountId }

向导路径是 openclaw onboard → 认证选择 openai-codex。

刷新 + 过期

配置文件会存储 expires 时间戳。

运行时：

  • 如果 expires 在未来 → 使用已存储的访问令牌
  • 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭证
  • 如果辅助 agent 读取继承来的主 agent OAuth 配置文件，刷新会写回主 agent 存储， 而不是把刷新令牌复制到辅助 agent 存储中
  • 例外：某些外部 CLI 凭证仍由外部管理；OpenClaw 会重新读取这些 CLI 认证存储， 而不是消耗复制的刷新令牌。Codex CLI 引导有意更窄：它会种下一个空的 openai-codex:default 配置文件，然后由 OpenClaw 拥有的刷新让本地配置文件保持为规范来源。

刷新流程是自动的；通常你不需要手动管理令牌。

多账号（配置文件）+ 路由

两种模式：

1) 首选：分离 agent

如果你希望“个人”和“工作”永不交互，请使用隔离的 agent（分离的会话 + 凭证 + 工作区）：

bash
openclaw agents add workopenclaw agents add personal

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

2) 高级：一个 agent 中多个配置文件

auth-profiles.json 支持为同一提供商配置多个配置文件 ID。

选择使用哪个配置文件：

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

示例（会话覆盖）：

  • /model Opus@anthropic:work

如何查看存在哪些配置文件 ID：

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

相关文档：

相关

Was this useful?