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

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 的进程。

先区分错误类型

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 这类 gateway 时，把它当作独立 provider-gateway：endpoint、model ID、price、quota、tool support 都要当前验证。

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。