---
read_when:
  - 调试模型认证或 OAuth 过期
  - 编写有关认证或凭证存储的文档
summary: 模型认证：OAuth、API key 和 setup-token
title: 认证
x-i18n:
  generated_at: "2026-03-16T06:22:17Z"
  model: gpt-5.4
  provider: openai
  source_hash: 219ac1acd7d192a5a12779e204cca65dae77a852fdc668271c45c01e0c69b7c9
  source_path: gateway/authentication.md
  workflow: 15
---

# 认证

OpenClaw 支持模型提供商使用 OAuth 和 API key。对于始终在线的 Gateway 网关
主机，API key 通常是最可预测的选项。当它们与你的提供商账号模型匹配时，
也支持订阅/OAuth 流程。

完整的 OAuth 流程和存储布局，请参阅 [/concepts/oauth](/concepts/oauth)。
关于基于 SecretRef 的认证（`env`/`file`/`exec` 提供商），请参阅 [Secrets Management](/gateway/secrets)。
关于 `models status --probe` 使用的凭证资格/原因码规则，请参阅
[Auth Credential Semantics](/auth-credential-semantics)。

## 推荐设置（API key，任意提供商）

如果你正在运行长期存活的 Gateway 网关，请先为你选择的
提供商配置一个 API key。
对于 Anthropic，API key 认证是更稳妥的方式，推荐优先于
订阅 setup-token 认证。

1. 在你的提供商控制台中创建一个 API key。
2. 将它放在 **Gateway 网关主机** 上（运行 `openclaw gateway` 的机器）。

```bash
export <PROVIDER>_API_KEY="..."
openclaw models status
```

3. 如果 Gateway 通过 systemd/launchd 运行，建议将 key 放入
   `~/.openclaw/.env`，这样守护进程就可以读取它：

```bash
cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF
```

然后重启守护进程（或重启你的 Gateway 网关进程）并重新检查：

```bash
openclaw models status
openclaw doctor
```

如果你不想自己管理环境变量，设置向导可以为守护进程使用场景存储
API key：`openclaw onboard`。

有关环境继承（`env.shellEnv`、
`~/.openclaw/.env`、systemd/launchd）的详细信息，请参阅 [Help](/help)。

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

如果你使用的是 Claude 订阅，则支持 setup-token 流程。请在
**Gateway 网关主机** 上运行：

```bash
claude setup-token
```

然后将它粘贴到 OpenClaw 中：

```bash
openclaw models auth setup-token --provider anthropic
```

如果 token 是在另一台机器上创建的，请手动粘贴：

```bash
openclaw models auth paste-token --provider anthropic
```

如果你看到类似这样的 Anthropic 错误：

```
This credential is only authorized for use with Claude Code and cannot be used for other API requests.
```

……请改用 Anthropic API key。

<Warning>
Anthropic setup-token 支持仅是技术兼容性。Anthropic 过去曾阻止
Claude Code 之外的某些订阅用法。只有在你认为相关策略风险可接受时才使用它，
并请你自行核实 Anthropic 当前的条款。
</Warning>

手动输入 token（任意提供商；会写入 `auth-profiles.json` + 更新配置）：

```bash
openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter
```

静态凭证也支持凭证配置文件引用：

- `api_key` 凭证可以使用 `keyRef: { source, provider, id }`
- `token` 凭证可以使用 `tokenRef: { source, provider, id }`

适合自动化的检查（已过期/缺失时退出码为 `1`，即将过期时为 `2`）：

```bash
openclaw models status --check
```

可选的运维脚本（systemd/Termux）记录在这里：
[/automation/auth-monitoring](/automation/auth-monitoring)

> `claude setup-token` 需要交互式 TTY。

## 检查模型认证状态

```bash
openclaw models status
openclaw doctor
```

## API key 轮换行为（Gateway 网关）

某些提供商支持在 API 调用触发提供商限流时，使用替代 key 重试请求。

- 优先级顺序：
  - `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个覆盖值）
  - `<PROVIDER>_API_KEYS`
  - `<PROVIDER>_API_KEY`
  - `<PROVIDER>_API_KEY_*`
- Google 提供商还将 `GOOGLE_API_KEY` 作为额外回退项。
- 使用前会对同一组 key 列表去重。
- 仅当出现限流错误时，OpenClaw 才会使用下一个 key 重试（例如
  `429`、`rate_limit`、`quota`、`resource exhausted`）。
- 非限流错误不会使用替代 key 重试。
- 如果所有 key 都失败，则返回最后一次尝试的最终错误。

## 控制使用哪个凭证

### 每个会话（聊天命令）

使用 `/model <alias-or-id>@<profileId>` 为当前会话固定使用特定的提供商凭证（示例配置文件 id：`anthropic:default`、`anthropic:work`）。

使用 `/model`（或 `/model list`）查看紧凑选择器；使用 `/model status` 查看完整视图（候选项 + 下一个凭证配置文件，以及在已配置时显示提供商端点详情）。

### 每个智能体（CLI 覆盖）

为智能体设置显式的凭证配置文件顺序覆盖（存储在该智能体的 `auth-profiles.json` 中）：

```bash
openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
```

使用 `--agent <id>` 指定特定智能体；省略它则使用已配置的默认智能体。

## 故障排除

### “No credentials found”

如果缺少 Anthropic token 配置文件，请在
**Gateway 网关主机** 上运行 `claude setup-token`，然后重新检查：

```bash
openclaw models status
```

### Token 即将过期/已过期

运行 `openclaw models status` 以确认哪个配置文件即将过期。如果该配置文件
缺失，请重新运行 `claude setup-token` 并再次粘贴 token。

## 要求

- Anthropic 订阅账号（用于 `claude setup-token`）
- 已安装 Claude Code CLI（`claude` 命令可用）