> ## Documentation Index
> Fetch the complete documentation index at: https://cryptoclawdocs.termix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

# OAuth

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

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

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

```bash theme={null}
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](/gateway/configuration#auth-storage-oauth--api-keys)

## Anthropic setup-token（订阅认证）

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

```bash theme={null}
openclaw models auth setup-token --provider anthropic
```

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

```bash theme={null}
openclaw models auth paste-token --provider anthropic
```

验证：

```bash theme={null}
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）推荐：独立智能体

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

```bash theme={null}
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[]`）

相关文档：

* [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
* [/tools/slash-commands](/tools/slash-commands)（命令界面）