跳到主要内容

OAuth

Clawdbot 为提供该功能的提供商（特别是 Anthropic (Claude Pro/Max) 和 OpenAI (ChatGPT OAuth)）提供基于 OAuth 的“订阅身份验证”。本页面将解释：

  • OAuth 令牌交换 是如何工作的 (PKCE)
  • 令牌 存储 在哪里（以及为什么）
  • 我们如何 重用外部 CLI 令牌 (Claude Code / ChatGPT CLI)
  • 如何处理 多个账户（配置文件 + 每个会话的覆盖设置）

Clawdbot 还支持自带 OAuth 或 API 密钥流程的 提供商插件。通过以下命令运行它们：

clawdbot models auth login --provider <id>

令牌槽 (The token sink) —— 为什么它存在​

OAuth 提供商通常在登录/刷新流程中铸造 新的刷新令牌 (refresh token)。一些提供商（或 OAuth 客户端）在为同一用户/应用颁发新令牌时，可能会使旧的刷新令牌失效。

实际症状：

  • 您通过 Clawdbot 和 通过 Claude Code / ChatGPT CLI 登录 → 稍后其中之一会随机“注销”。

为了减少这种情况，Clawdbot 将 auth-profiles.json 视为 令牌槽 (token sink)：

  • 运行时从 一个地方 读取凭据。
  • 我们可以从外部 CLI 同步 凭据，而不是进行第二次登录。
  • 我们可以保留多个配置文件并进行确定性的路由。

存储（令牌存在哪里）​

密钥按 智能体 存储：

  • 身份验证配置文件（OAuth + API 密钥）：~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
  • 运行时缓存（自动管理；请勿编辑）：~/.clawdbot/agents/<agentId>/agent/auth.json

旧版仅供导入的文件（仍受支持，但不是主要存储位置）：

  • ~/.clawdbot/credentials/oauth.json（首次使用时导入到 auth-profiles.json 中）

上述所有文件也遵循 $CLAWDBOT_STATE_DIR（状态目录覆盖设置）。完整参考：/gateway/configuration

重用 Claude Code / ChatGPT CLI OAuth 令牌（推荐）​

如果您已经在 网关主机 上使用外部 CLI 登录，Clawdbot 可以重用这些令牌而无需启动单独的 OAuth 流程：

  • Claude Code：anthropic:claude-cli
    • macOS：钥匙串 (Keychain) 条目 "Claude Code-credentials"（选择“始终允许”以避免 launchd 提示）
    • Linux/Windows：~/.claude/.credentials.json
  • ChatGPT CLI：读取 ~/.codex/auth.json → 配置文件 openai:chatgpt-cli

同步发生在 Clawdbot 加载身份验证存储时（因此当 CLI 刷新令牌时，它能保持最新状态）。 在 macOS 上，第一次读取可能会触发钥匙串提示；如果网关无头运行且无法访问该条目，请在终端中运行一次 clawdbot models status。

如何验证：

clawdbot models status
clawdbot channels list

或使用 JSON 格式：

clawdbot channels list --json

OAuth 交换（登录原理）​

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

Anthropic (Claude Pro/Max)​

流程结构 (PKCE)：

  1. 生成 PKCE 验证器 (verifier) / 挑战 (challenge)
  2. 打开 https://claude.ai/oauth/authorize?...
  3. 用户粘贴 code#state
  4. 在 https://console.anthropic.com/v1/oauth/token 进行交换
  5. 将 { access, refresh, expires } 存储在身份验证配置文件下

向导路径为 clawdbot onboard → 身份验证选择 oauth (Anthropic)。

OpenAI (ChatGPT OAuth)​

流程结构 (PKCE)：

  1. 生成 PKCE 验证器/挑战 + 随机 state
  2. 打开 https://auth.openai.com/oauth/authorize?...
  3. 尝试捕获 http://127.0.0.1:1455/auth/callback 上的回调
  4. 如果回调无法绑定（或者您处于远程/无头状态），请粘贴重定向 URL/代码
  5. 在 https://auth.openai.com/oauth/token 进行交换
  6. 从访问令牌中提取 accountId 并存储 { access, refresh, expires, accountId }

向导路径为 clawdbot onboard → 身份验证选择 openai（或 openai:chatgpt-cli 以重用现有的 ChatGPT CLI 登录）。

刷新 + 过期​

配置文件存储一个 expires（过期）时间戳。

在运行时：

  • 如果 expires 在未来 → 使用存储的访问令牌。
  • 如果已过期 → 进行刷新（在文件锁保护下）并覆盖存储的凭据。

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

与 Claude Code 的双向同步​

当 Clawdbot 刷新 Anthropic OAuth 令牌（配置文件 anthropic:claude-cli）时，它会 将新凭据写回 到 Claude Code 的存储中：

  • Linux/Windows：更新 ~/.claude/.credentials.json
  • macOS：更新钥匙串条目 "Claude Code-credentials"

这确保了两个工具保持同步，并且在其中一个刷新后，另一个不会被“注销”。

为什么这对于长期运行的智能体很重要：

Anthropic OAuth 令牌在几小时后过期。如果没有双向同步：

  1. Clawdbot 刷新令牌 → 获取新的访问令牌。
  2. Claude Code 仍持有旧令牌 → 被注销。

通过双向同步，两个工具始终拥有最新的有效令牌，从而实现长达数天或数周的自主运行，无需手动干预。

多账户（配置文件）+ 路由​

两种模式：

1) 首选：独立的智能体​

如果您希望“个人”和“工作”内容永不互动，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：

clawdbot agents add work
clawdbot agents add personal

然后为每个智能体配置身份验证（通过向导），并将聊天路由到正确的智能体。

2) 进阶：在一个智能体中使用多个配置文件​

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

选择使用哪个配置文件：

  • 全局：通过配置顺序 (auth.order)。
  • 每个会话：通过 /model ...@<profileId>。

示例（会话覆盖）：

  • /model Opus@anthropic:work

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

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

相关文档：