---
read_when:
    - 调试模型认证或 OAuth 过期问题
    - 编写认证或凭证存储相关文档
summary: 模型认证：OAuth、API 密钥、Claude CLI 复用，以及 Anthropic setup-token
title: 认证
x-i18n:
    generated_at: "2026-04-06T15:27:45Z"
    model: gpt-5.4
    provider: openai
    source_hash: 9db0ad9eccd7e3e3ca328adaad260bc4288a8ccdbe2dc0c24d9fd049b7ab9231
    source_path: gateway/authentication.md
    workflow: 15
---

# 认证（模型提供商）

<Note>
本页介绍**模型提供商**认证（API 密钥、OAuth、Claude CLI 复用，以及 Anthropic setup-token）。关于 **Gateway 网关连接** 认证（令牌、密码、trusted-proxy），请参阅 [Configuration](/zh-CN/gateway/configuration) 和 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)。
</Note>

OpenClaw 支持模型提供商使用 OAuth 和 API 密钥。对于长期运行的 Gateway 网关主机，API 密钥通常是最可预测的选项。当订阅 / OAuth 流程与你的提供商账户模型匹配时，也支持这类流程。

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

## 推荐设置（API 密钥，适用于任何提供商）

如果你正在运行一个长期存在的 Gateway 网关，请先为你选择的提供商使用 API 密钥。
对于 Anthropic 而言，API 密钥认证仍然是最可预测的服务器端设置，但 OpenClaw 也支持复用本地 Claude CLI 登录。

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

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

3. 如果 Gateway 在 systemd/launchd 下运行，建议将密钥放在
   `~/.openclaw/.env` 中，以便守护进程可以读取：

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

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

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

如果你不想自己管理环境变量，新手引导可以为守护进程使用存储
API 密钥：`openclaw onboard`。

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

## Anthropic：Claude CLI 和令牌兼容性

Anthropic setup-token 认证在 OpenClaw 中仍然作为受支持的令牌路径提供。此后，Anthropic 工作人员告知我们，允许再次使用 OpenClaw 风格的 Claude CLI 用法，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的认可方式，除非 Anthropic 发布新的政策。当主机上可用 Claude CLI 复用时，这现在是首选路径。

对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是最可预测的设置。如果你想在同一台主机上复用现有的 Claude 登录，请在新手引导 / 配置中使用 Anthropic Claude CLI 路径。

手动输入令牌（适用于任何提供商；会写入 `auth-profiles.json` 并更新配置）：

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

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

- `api_key` 凭证可以使用 `keyRef: { source, provider, id }`
- `token` 凭证可以使用 `tokenRef: { source, provider, id }`
- OAuth 模式的配置文件不支持 SecretRef 凭证；如果 `auth.profiles.<id>.mode` 设置为 `"oauth"`，则会拒绝该配置文件中由 SecretRef 支持的 `keyRef`/`tokenRef` 输入。

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

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

实时认证探测：

```bash
openclaw models status --probe
```

说明：

- 探测行可来自认证配置文件、环境凭证或 `models.json`。
- 如果显式的 `auth.order.<provider>` 省略了已存储的配置文件，探测会为该配置文件报告
  `excluded_by_auth_order`，而不是尝试使用它。
- 如果认证存在，但 OpenClaw 无法为该提供商解析出可探测的候选模型，探测会报告
  `status: no_model`。
- 限流冷却期可以按模型范围生效。对某个模型处于冷却中的配置文件，仍然可能可用于同一提供商下的同级模型。

可选运维脚本（systemd/Termux）文档在这里：
[Auth monitoring scripts](/zh-CN/help/scripts#auth-monitoring-scripts)

## Anthropic 说明

Anthropic `claude-cli` 后端现已再次受支持。

- Anthropic 工作人员告诉我们，这条 OpenClaw 集成路径已再次被允许。
- 因此，OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为
  Anthropic 支持运行中的认可方式，除非 Anthropic 发布新的政策。
- 对于长期运行的 Gateway 网关主机，以及需要明确服务器端计费控制的场景，
  Anthropic API 密钥仍然是最可预测的选择。

## 检查模型认证状态

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

## API 密钥轮换行为（Gateway 网关）

某些提供商支持在 API 调用触发提供商限流时，使用其他密钥重试请求。

- 优先级顺序：
  - `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个覆盖项）
  - `<PROVIDER>_API_KEYS`
  - `<PROVIDER>_API_KEY`
  - `<PROVIDER>_API_KEY_*`
- Google 提供商还会额外将 `GOOGLE_API_KEY` 作为回退项。
- 相同的密钥列表在使用前会去重。
- 只有在限流错误时，OpenClaw 才会使用下一个密钥重试（例如
  `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent
requests`、`ThrottlingException`、`concurrency limit reached`，或
  `workers_ai ... quota limit exceeded`）。
- 非限流错误不会使用备用密钥重试。
- 如果所有密钥都失败，将返回最后一次尝试产生的最终错误。

## 控制使用哪个凭证

### 按会话（聊天命令）

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

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

### 按智能体（CLI 覆盖）

为某个智能体设置显式的认证配置文件顺序覆盖（存储在该智能体的 `auth-state.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>` 可指定特定智能体；省略时则使用已配置的默认智能体。
当你调试顺序问题时，`openclaw models status --probe` 会将被省略的
已存储配置文件显示为 `excluded_by_auth_order`，而不是静默跳过它们。
当你调试冷却问题时，请记住限流冷却期可能只绑定到某个模型 id，
而不是整个提供商配置文件。

## 故障排除

### “未找到凭证”

如果缺少 Anthropic 配置文件，请在**Gateway 网关主机**上配置 Anthropic API 密钥，或设置 Anthropic setup-token 路径，然后重新检查：

```bash
openclaw models status
```

### 令牌即将过期 / 已过期

运行 `openclaw models status` 以确认哪个配置文件即将过期。如果某个
Anthropic 令牌配置文件缺失或已过期，请通过
setup-token 刷新该设置，或迁移到 Anthropic API 密钥。
