OAuth
CoderClaw 支持通过 OAuth 进行”订阅认证”，适用于提供此功能的提供商（特别是 OpenAI Codex（ChatGPT OAuth））。对于 Anthropic 订阅，请使用 setup-token 流程。本页说明：
- OAuth 令牌交换的工作原理（PKCE）
- 令牌存储在哪里（以及原因）
- 如何处理多账户（配置文件 + 按会话覆盖）
CoderClaw 还支持提供商插件，它们自带 OAuth 或 API 密钥流程。通过以下命令运行：
coderclaw models auth login --provider <id>令牌汇聚点（为什么需要它）
Section titled “令牌汇聚点（为什么需要它）”OAuth 提供商通常在登录/刷新流程中发放新的刷新令牌。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。
实际症状：
- 你通过 CoderClaw 和 Claude Code / Codex CLI 登录 → 其中一个稍后会随机”登出”
为减少这种情况，CoderClaw 将 auth-profiles.json 视为令牌汇聚点：
- 运行时从同一个位置读取凭据
- 我们可以保留多个配置文件并确定性地路由它们
存储（令牌存放位置）
Section titled “存储（令牌存放位置）”密钥按智能体存储：
- 认证配置文件（OAuth + API 密钥）：
~/.coderclaw/agents/<agentId>/agent/auth-profiles.json - 运行时缓存（自动管理；请勿编辑）：
~/.coderclaw/agents/<agentId>/agent/auth.json
仅用于导入的旧版文件（仍然支持，但不是主存储）：
~/.coderclaw/credentials/oauth.json（首次使用时导入到auth-profiles.json）
以上所有路径也遵循 $CODERCLAW_STATE_DIR（状态目录覆盖）。完整参考：/gateway/configuration
Anthropic setup-token（订阅认证）
Section titled “Anthropic setup-token（订阅认证）”在任意机器上运行 claude setup-token，然后将其粘贴到 CoderClaw 中：
coderclaw models auth setup-token --provider anthropic如果你在其他地方生成了令牌，可以手动粘贴：
coderclaw models auth paste-token --provider anthropic验证：
coderclaw models statusOAuth 交换（登录工作原理）
Section titled “OAuth 交换（登录工作原理）”CoderClaw 的交互式登录流程在 @mariozechner/pi-ai 中实现，并集成到向导/命令中。
Anthropic（Claude Pro/Max）setup-token
Section titled “Anthropic（Claude Pro/Max）setup-token”流程概要：
- 运行
claude setup-token - 将令牌粘贴到 CoderClaw
- 作为令牌认证配置文件存储（无刷新）
向导路径为 coderclaw onboard → 认证选择 setup-token（Anthropic）。
OpenAI Codex（ChatGPT OAuth）
Section titled “OpenAI Codex（ChatGPT OAuth）”流程概要（PKCE）：
- 生成 PKCE 验证器/质询 + 随机
state - 打开
https://auth.openai.com/oauth/authorize?... - 尝试在
http://127.0.0.1:1455/auth/callback捕获回调 - 如果回调无法绑定（或你在远程/无头环境中），手动粘贴重定向 URL/代码
- 在
https://auth.openai.com/oauth/token进行交换 - 从访问令牌中提取
accountId并存储{ access, refresh, expires, accountId }
向导路径为 coderclaw onboard → 认证选择 openai-codex。
刷新 + 过期
Section titled “刷新 + 过期”配置文件存储 expires 时间戳。
运行时：
- 如果
expires在未来 → 使用已存储的访问令牌 - 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
刷新流程是自动的；你通常不需要手动管理令牌。
多账户（配置文件）+ 路由
Section titled “多账户（配置文件）+ 路由”两种模式：
1）推荐：独立智能体
Section titled “1）推荐：独立智能体”如果你希望”个人”和”工作”永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：
coderclaw agents add workcoderclaw agents add personal然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
2）高级：单个智能体中的多个配置文件
Section titled “2）高级：单个智能体中的多个配置文件”auth-profiles.json 支持同一提供商的多个配置文件 ID。
选择使用哪个配置文件：
- 通过配置顺序全局设置（
auth.order） - 通过
/model ...@<profileId>按会话设置
示例（会话覆盖）：
/model Opus@anthropic:work
如何查看存在哪些配置文件 ID：
coderclaw channels list --json（显示auth[]）
相关文档：
- /concepts/model-failover（轮换 + 冷却规则）
- /tools/slash-commands（命令界面）