OAuth 认证

概述

OpenClaw 通过 OAuth 支持”订阅认证”，主要用于 OpenAI Codex（ChatGPT OAuth）。对于 Anthropic，推荐使用 API Key 认证；Claude CLI 复用也被允许。OAuth 令牌统一存储在 auth-profiles.json 作为”令牌汇聚点”，避免多客户端登录导致的令牌失效问题。

核心要点

• 令牌汇聚点设计：运行时从单一位置读取凭证，避免多个 OAuth 客户端互相使令牌失效
• 存储位置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json（主存储）；旧版兼容文件 auth.json 和 credentials/oauth.json
• PKCE 流程（OpenAI Codex）：生成 verifier/challenge → 打开授权 URL → 捕获回调（或粘贴重定向 URL）→ 交换令牌 → 存储 {access, refresh, expires, accountId}
• 自动刷新：令牌过期时自动刷新（文件锁保护），无需手动管理
• 继承机制：次级 Agent 无本地 auth profile 时，从默认/主 Agent 存储读取（不克隆，OAuth refresh token 默认跳过复制）
• 多账号支持：推荐用独立 Agent 隔离（openclaw agents add work）；高级用法可在同一 Agent 中使用多个 profile，通过 /model ...@<profileId> 切换

配置/使用

OpenAI Codex OAuth 登录：

openclaw onboard  # 选择 openai-codex 认证方式

多账号（推荐方式）：

openclaw agents add work
openclaw agents add personal
# 分别为每个 agent 配置认证

会话内切换 profile：

/model Opus@anthropic:work

查看已有 profile：

openclaw channels list --json  # 显示 auth[] 字段

Anthropic 认证路径优先级：

1. Claude CLI 复用（claude -p）
2. Anthropic setup-token
3. API Key（生产环境推荐）

相关页面

• model-providers — 模型提供商配置
• model-failover — Auth profile 轮换与冷却
• models — 模型选择与动态切换
• agent — Agent 隔离与工作区