# 修复 OpenClaw Anthropic API Key 错误：401、缺失认证、OAuth 与冷却

> OpenClaw Anthropic API key 错误要先看责任归属：Anthropic auth 是否缺失、key 是否被拒、OAuth 是否刷新失败、环境变量是否覆盖配置、所选模型是否可用，或只是早前失败后的 provider cooldown。

- URL: https://blog.laozhang.ai/zh/posts/openclaw-anthropic-api-key-error
- Published: 2026-02-04
- Updated: 2026-05-08
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: 故障排查
- Tags: OpenClaw, Anthropic API, 认证错误, API 故障排除, 401 错误

---
OpenClaw Anthropic API key 错误会让所选 Anthropic route 无法发出有效模型请求。修复不一定是换一个新的 Anthropic key。先证明失败来自缺失 Anthropic auth、provider key 无效或被撤销、OAuth/CLI-backed auth 刷新失败、环境变量覆盖、模型权限、账单/账户状态，还是早前失败后的 provider cooldown。如果日志显示 `AUTH_TOKEN_MISMATCH`、`PAIRING_REQUIRED` 或 device token 相关代码，你看的不是 Anthropic key 问题：先修 gateway/client auth，再复测 Anthropic。

## 快速答案

先跑：

```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw models status
```

如果 `models status` 显示 Anthropic auth 缺失，运行 `openclaw onboard` 或按当前 OpenClaw provider docs 添加 Anthropic auth profile。如果 provider 拒绝 key，到 Anthropic Console 替换或重新授权，并确认当前账户能访问所选模型。如果走 OAuth 或 CLI-backed auth，刷新或替换该 profile。如果 `env | grep -i anthropic` 出现旧值，清掉覆盖项并重启运行 gateway 的进程。

## 先区分错误类型

| 现象 | 真实 owner | 下一步 |
|---|---|---|
| `No API key found for provider 'anthropic'` | Anthropic provider auth 缺失 | onboarding 或补 auth profile |
| `authentication_error`, `invalid bearer token` | provider key 被拒 | Anthropic Console 验证 key、billing、model access |
| `permission_error`, 403 | key 有效但权限/模型/账户不匹配 | 查账户和模型权限 |
| `OAuth token refresh failed` | OAuth/CLI-backed auth 失效 | 刷新 profile 或改用 direct API key |
| `all in cooldown` | 早前失败后的 gateway state | 读第一条失败日志，修 root cause |
| `AUTH_TOKEN_MISMATCH` / `PAIRING_REQUIRED` | gateway/client auth | 回到 gateway token 或 device pairing |

`cooldown` 尤其容易误导。它说明 OpenClaw 暂时不再使用 Anthropic route，但不说明当前 key 一定无效。先查 cooldown 之前的第一条 provider log。

## 修复缺失或无效 Anthropic key

第一步不是看 key 前缀，而是确认 OpenClaw 实际加载了哪个 credential。Shell env、Docker `.env`、per-agent auth profile、旧配置片段都可能互相覆盖。key prefix 只能做粗略 sanity check；真正证据是 Anthropic 是否接受该 key 访问你选择的 model route。

如果要在 OpenClaw 外做最小验证，用当前 Anthropic API docs 和你账号能访问的模型：

```bash
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY_HERE" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"YOUR_ACCESSIBLE_MODEL","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' \
  | head -c 200
```

如果 direct provider call 成功，问题更可能在 OpenClaw route、auth profile、base URL、allowlist 或 env override。若 provider 返回 authentication error，回到 Anthropic Console 重新生成或检查该 key 的状态、账单和模型权限。

手动写 config 时只使用当前文档支持的路径。下面是形状示例，不是保证字段：

```json
{
  "env": {
    "ANTHROPIC_API_KEY": "your-current-anthropic-key"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/model-you-can-access"
      }
    }
  }
}
```

更新后，用 `openclaw models status` 验证，而不是只确认文件里出现了 key。

## OAuth、CLI-backed auth 和 setup token

OAuth 或 CLI-backed auth 适合当前 OpenClaw docs 明确支持的场景，但它比 direct API key 多了刷新、浏览器、host 和账户策略约束。生产或无头服务器通常更容易用 direct API key 或已验证的 provider-gateway route 管理。

如果你继续使用 OAuth，先确认当前 OpenClaw 版本的 credential 路径和 refresh 命令。不要把旧文章里的 `paste-token`、`setup-token` 或 plugin command 当成长期可用接口。setup/bootstrap token 应只用于 provisioning：创建或刷新真正 auth profile 后，就应该从 CI logs、compose file 和长期环境变量中移除。

## 解决环境变量覆盖

环境变量是 Anthropic auth 混乱的常见来源。直接使用 Anthropic API、Claude CLI、Docker compose、CI 或旧脚本时留下的变量，可能覆盖 OpenClaw 里的 auth profile。

```bash
env | grep -i anthropic
env | grep -i claude
```

重点检查：

- `ANTHROPIC_API_KEY`
- `ANTHROPIC_AUTH_TOKEN`
- `ANTHROPIC_BASE_URL`
- `ANTHROPIC_API_URL`
- Docker compose `.env` 或 service environment
- per-agent auth profile

如果你不是故意覆盖，就在启动 gateway 的同一个环境里移除旧变量，然后重启 gateway。只在当前 shell 里 unset，不一定会影响 systemd、Docker、LaunchAgent 或 CI 中的进程。

## 理解 cooldown

Cooldown 是保护机制。OpenClaw 在 provider 反复失败后会暂时停止向该 route 发送请求，以避免重复失败、浪费 quota 或触发更多上游拒绝。触发原因可能是 401、429、timeout、billing、network 或 provider outage。

恢复时按顺序做：

1. 在 logs 里找到 cooldown 前的第一条 provider failure。
2. 修该 owner：key、quota、billing、base URL、model access 或 network。
3. 等待 cooldown 自然恢复，或在确认 root cause 已修后重启 gateway。
4. 用 `openclaw models status` 验证 route。

不要把重启当成 provider-quota solution。重启只能清本地状态，不能补上游额度，也不能修无效 key。

## 选择 auth 方法

**Direct API key**：适合 server、CI、团队 route 和需要清晰 billing owner 的场景。轮换和权限管理都在 Anthropic Console 里完成。

**OAuth / CLI-backed auth**：只在当前 docs 支持并且你接受 refresh、browser、host 和 account-policy 约束时使用。

**Setup/bootstrap token**：用于 provisioning，不是长期 inference credential。用完后应从长期环境里移除。

**Auth profiles**：适合 per-agent、team 或 billing isolation。复杂度在于新 agent 不一定继承主 agent credential，需要显式配置。

## 预防清单

1. 把 `openclaw models status` 加入健康检查。
2. 记录每个 provider route 的 billing owner、模型权限和 secret 来源。
3. 只保留一个权威 credential 来源，减少 shell env、Docker env 和 per-agent profile 冲突。
4. 更新 OpenClaw 前读 auth 相关 release notes。
5. 生产 fallback 只放入已认证、已测试、quota 和 tool support 都确认过的 route。
6. 使用 [laozhang.ai](https://docs.laozhang.ai/) 这类 gateway 时，把它当作独立 provider-gateway：endpoint、model ID、price、quota、tool support 都要当前验证。

*说明：[laozhang.ai 是我们自己的服务](https://blog.laozhang.ai/zh/about#laozhang)，其价格是平台报价，不是独立比较的结论。*

## FAQ

**应用修复后仍然认证失败怎么办？**

说明可能有多个配置源互相覆盖。用 logs、`models status`、环境变量和 Docker/service 环境查“有效 auth route”，不要只看你刚编辑的文件。

**凭证正确为什么还显示 all in cooldown？**

Cooldown 来自过去失败，不代表当前 key 一定无效。找到第一条失败日志；如果 root cause 已修，等待或重启 gateway 清本地 cooldown。

**可以同时配置 OAuth 和 API key 吗？**

可以，但复杂度会上升。大多数个人部署最好选择一种 auth 方法并保持一致；团队部署再用 auth profiles 做隔离。

**怎么知道现在用的是哪种认证方式？**

运行 `openclaw models status`，再检查当前 provider 的 auth profile/config path 和 gateway logs。日志通常会显示失败来自 missing provider auth、invalid provider auth、OAuth refresh 还是 gateway/client auth。

**新 agent 为什么没有主 agent 的凭据？**

per-agent auth profile 可能不会自动继承。给新 agent 跑 onboarding，或按当前 OpenClaw 文档复制/配置它自己的 auth profile。