文档
OAuth

OAuth

适用范围

在以下情况使用此页面：

  • 您想端到端了解 Moltbot OAuth
  • 您遇到令牌失效/注销问题
  • 您想重用 Claude Code / Codex CLI OAuth 令牌
  • 您想要多个帐户或配置文件路由

Moltbot 支持通过提供订阅身份验证的提供程序使用 OAuth（特别是 Anthropic (Claude Pro/Max) 和 OpenAI Codex (ChatGPT OAuth)）。本页面解释：

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

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

moltbot models auth login --provider <id>

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

OAuth 提供程序通常在登录/刷新期间铸造新的刷新令牌。一些提供程序（或 OAuth 客户端）可能会在为同一用户/应用发出新刷新令牌时使旧的刷新令牌失效。

实际症状：

  • 您通过 Moltbot 登录并且通过 Claude Code / Codex CLI 登录 → 其中一个随机"注销"后

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

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

存储（令牌所在位置）

机密是每个代理存储的：

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

传统仅导入文件（仍然支持，但不是主存储）：

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

所有上述内容也尊重 $MOLTBOT_STATE_DIR（状态目录覆盖）。完整参考：/gateway/configuration

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

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

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

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

如何验证：

moltbot models status
moltbot channels list

或 JSON：

moltbot channels list --json

OAuth 交换（登录如何工作）

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

Anthropic (Claude Pro/Max)

流程形状（PKCE）：

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

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

OpenAI Codex (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 }

向导路径是 moltbot onboard → 身份验证选择 openai-codex（或 codex-cli 以重用现有的 Codex CLI 登录）。

刷新 + 过期

配置文件存储 expires 时间戳。

在运行时：

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

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

与 Claude Code 的双向同步

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

  • Linux/Windows：更新 ~/.claude/.credentials.json
  • macOS：更新钥匙串项 “Claude Code-credentials”

这确保两种工具保持同步，并且在另一种刷新后都不会"注销"。

为什么这对长期运行的代理很重要：

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

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

使用双向同步，两种工具始终具有最新的有效令牌，可以实现数天或数周的自主运行，而无需人工干预。

多个帐户（配置文件）+ 路由

两种模式：

1) 推荐：独立的代理

如果您希望"个人"和"工作"永不交互，请使用隔离的代理（独立的会话 + 凭据 + 工作空间）：

moltbot agents add work
moltbot agents add personal

然后为每个代理配置身份验证（向导）并将聊天路由到正确的代理。

2) 高级：一个代理中的多个配置文件

auth-profiles.json 支持同一提供程序的多个配置文件 ID。

选择使用哪个配置文件：

  • 通过配置顺序全局（auth.order）
  • 通过 /model ...@<profileId> 每会话

示例（会话覆盖）：

  • /model Opus@anthropic:work

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

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

相关文档：

Multi-Agent Sandbox & Tools ConfigurationOpenProse