openclaw 文档

简体中文

English

简体中文

English

Appearance

OAuth ​

Moltbot 支持对提供“订阅鉴权”的 providers 使用 OAuth（尤其是 OpenAI Codex（ChatGPT OAuth））。对 Anthropic 订阅，请使用 setup-token 流程。本文解释：

  • OAuth token exchange（PKCE）如何工作
  • tokens 存储在何处（以及原因）
  • 如何处理 多账号（profiles + per-session 覆盖）

Moltbot 也支持 provider plugins，它们可以自带 OAuth 或 API-key 的流程。通过以下命令运行：

bash
moltbot models auth login --provider <id>

token sink（为什么需要它） ​

OAuth providers 常在登录/刷新流程中签发 新的 refresh token。部分 providers（或 OAuth clients）在为同一 user/app 生成新 refresh token 时，可能会使旧 refresh token 失效。

常见症状：

  • 你通过 Moltbot 同时又通过 Claude Code / Codex CLI 登录 → 之后其中一个会“随机被登出”

为减少这种情况，Moltbot 将 auth-profiles.json 视为一个 token sink：

  • 运行时从一个地方读取凭据
  • 可以保留多个 profiles，并进行确定性的路由

存储（tokens 放在哪里） ​

Secrets 按 每个 agent 存储：

  • Auth profiles（OAuth + API keys）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Runtime cache（自动管理；不要手工编辑）：~/.openclaw/agents/<agentId>/agent/auth.json

legacy 的 import-only 文件（仍支持，但不是主存储）：

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

以上路径也都支持 $openclaw_STATE_DIR（state dir 覆盖）。完整参考：/gateway/configuration

Anthropic setup-token（订阅鉴权） ​

在任意机器上运行 claude setup-token，然后把 token 粘贴到 Moltbot：

bash
moltbot models auth setup-token --provider anthropic

如果 token 是在别处生成的，也可以手工粘贴：

bash
moltbot models auth paste-token --provider anthropic

验证：

bash
moltbot models status

OAuth exchange（登录流程如何工作） ​

Moltbot 的交互式登录流程由 @mariozechner/pi-ai 实现，并接入各类 wizards/commands。

Anthropic（Claude Pro/Max）的 setup-token ​

流程形态：

  1. 运行 claude setup-token
  2. 把 token 粘贴到 Moltbot
  3. 以 token auth profile 的形式存储（不需要 refresh）

向导路径：moltbot onboard → auth choice setup-token（Anthropic）。

OpenAI Codex（ChatGPT OAuth） ​

流程形态（PKCE）：

  1. 生成 PKCE verifier/challenge + 随机 state
  2. 打开 https://auth.openai.com/oauth/authorize?...
  3. 尝试在 http://127.0.0.1:1455/auth/callback 捕获回调
  4. 如果回调端口无法绑定（或你在 remote/headless 环境），则粘贴 redirect URL/code
  5. 在 https://auth.openai.com/oauth/token 交换 token
  6. 从 access token 中提取 accountId，并存储 { access, refresh, expires, accountId }

向导路径：moltbot onboard → auth choice openai-codex。

刷新与过期（Refresh + expiry） ​

profiles 会存储一个 expires 时间戳。

运行时：

  • 若 expires 仍在未来 → 直接使用存储的 access token
  • 若已过期 → 在文件锁下刷新（refresh），并覆盖存储的凭据

刷新流程是自动的；一般不需要手工管理 tokens。

多账号（profiles）+ 路由 ​

两种模式：

1) 推荐：使用不同 agents ​

如果你希望“个人”和“工作”永不互相影响，使用隔离的 agents（独立 sessions + 凭据 + workspace）：

bash
moltbot agents add work
moltbot agents add personal

然后按 agent 分别配置 auth（wizard），并把聊天路由到正确的 agent。

2) 高级：单个 agent 下使用多个 profiles ​

auth-profiles.json 支持同一 provider 下的多个 profile IDs。

选择使用哪个 profile：

  • 全局：通过配置排序（auth.order）
  • 单 session：通过 /model ...@<profileId>

示例（session override）：

  • /model Opus@anthropic:work

查看有哪些 profile IDs：

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

相关文档：