admin/Moltbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5676a6b38de81a13194223ac688e20087d5b74e7
Moltbot/docs/zh-CN/concepts/oauth.md
Josh Palmer 5676a6b38d Docs: normalize zh-CN terminology + tone 
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build
2026-02-02 16:38:25 +01:00

4.7 KiB
Raw Blame History

read_when, summary, title, x-i18n
read_when summary title x-i18n
你想全面了解 OpenClaw 的 OAuth 流程
你遇到了令牌失效/登出问题
你想了解 setup-token 或 OAuth 认证流程
你想使用多账户或配置文件路由
OpenClaw 中的 OAuth：令牌交换、存储和多账户模式 OAuth
generated_at model provider source_hash source_path workflow
2026-02-01T20:23:29Z claude-opus-4-5 pi af714bdadc4a89295a18da1eba5f5b857c8d533ebabe9b0758b722fe60c36124 concepts/oauth.md 14

OAuth

OpenClaw 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 OpenAI Codex（ChatGPT OAuth））。对于 Anthropic 订阅，请使用 setup-token 流程。本页说明：

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

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

openclaw models auth login --provider <id>

令牌汇聚点（为什么需要它）

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

实际症状：

  • 你通过 OpenClaw 和 Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出"

为减少这种情况，OpenClaw 将 auth-profiles.json 视为令牌汇聚点：

  • 运行时从同一个位置读取凭据
  • 我们可以保留多个配置文件并确定性地路由它们

存储（令牌存放位置）

密钥按智能体存储：

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

仅用于导入的旧版文件（仍然支持，但不是主存储）：

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

以上所有路径也遵循 $OPENCLAW_STATE_DIR（状态目录覆盖）。完整参考：/gateway/configuration

Anthropic setup-token（订阅认证）

在任意机器上运行 claude setup-token，然后将其粘贴到 OpenClaw 中：

openclaw models auth setup-token --provider anthropic

如果你在其他地方生成了令牌，可以手动粘贴：

openclaw models auth paste-token --provider anthropic

验证：

openclaw models status

OAuth 交换（登录工作原理）

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

Anthropic（Claude Pro/Max）setup-token

流程概要：

  1. 运行 claude setup-token
  2. 将令牌粘贴到 OpenClaw
  3. 作为令牌认证配置文件存储（无刷新）

向导路径为 openclaw onboard → 认证选择 setup-token（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 }

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

刷新 + 过期

配置文件存储 expires 时间戳。

运行时：

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

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

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

两种模式：

1）推荐：独立智能体

如果你希望"个人"和"工作"永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：

openclaw agents add work
openclaw agents add personal

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

2）高级：单个智能体中的多个配置文件

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

选择使用哪个配置文件：

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

示例（会话覆盖）：

  • /model Opus@anthropic:work

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

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

相关文档：

Reference in New Issue View Git Blame Copy Permalink