$cd ../troubleshooting/
High🧠 Models
Anthropic API 401 — 密钥缺失、过期或配置错误
// OpenClaw 调用 Claude 时若 gateway 日志出现 api.anthropic.com 的 HTTP 401，模型根本不会运行——Agent 挂起、心跳失败，Discord/Telegram 可能只显示笼统的「提供商错误」。与 429 限流不同，401 表示认证彻底失败：账户无计费、密钥被吊销或拼写错误、错误的 sk-ant- 前缀，或密钥放在错误配置字段而陈旧的 ANTHROPIC_API_KEY 环境变量覆盖了 openclaw.json。本非官方指南说明如何在 console.anthropic.com 验证密钥、在 ~/.openclaw/openclaw.json 的 providers 下正确放置，以及解决环境变量与配置不一致——这类问题连有经验的自托管用户也会踩坑。
diagnose.sh
🔍 这是您的问题吗？
?日志显示来自 api.anthropic.com 的 `401` 或 `authentication_error`
?Agent 立即失败无模型响应——不是慢，不是 429
?刚创建密钥但未在 Anthropic 控制台添加计费
?密钥以 sk-（OpenAI 风格）开头而非 sk-ant-
?在 .env 设置了密钥但 openclaw.json 仍是不同（空）密钥
verify_key.sh
✅ 修复方法 1 — 验证密钥格式与 Anthropic 控制台
验证前缀并对 Anthropic API 做 live 认证
# 确认密钥形状（切勿在公开日志粘贴完整密钥）
echo "$ANTHROPIC_API_KEY" | head -c 12
# 期望前缀：sk-ant-api
# 直接测试密钥
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'控制台检查：计费 + 密钥活跃状态
# 浏览器：console.anthropic.com # 1. Settings → Billing — 支付方式已激活 # 2. Settings → API Keys — 密钥状态 Active # 3. 不确定则重新生成；吊销旧密钥 # 记录新密钥末 4 位以便与配置对照
openclaw.json
✅ 修复方法 2 — 在 openclaw.json 中设置提供商密钥
密钥在 providers；agent provider id 须匹配
// ~/.openclaw/openclaw.json — providers 段
{
"providers": [
{
"id": "anthropic",
"type": "anthropic",
"apiKey": "sk-ant-api03-XXXXXXXX"
}
],
"agents": {
"defaults": {
"provider": "anthropic",
"model": "claude-sonnet-4-20250514"
}
}
}密钥优先放 .env；编辑后重启 gateway
# 或引用环境变量而非内联密钥 # openclaw.json: # "apiKeyEnv": "ANTHROPIC_API_KEY" # ~/.openclaw/.env ANTHROPIC_API_KEY=sk-ant-api03-XXXXXXXX # 验证配置 openclaw doctor openclaw gateway restart
env_override.sh
✅ 修复方法 3 — 解决 ANTHROPIC_API_KEY 环境变量覆盖
定位主机上每个 ANTHROPIC_API_KEY 来源
# 查找环境变量覆盖 env | grep -i ANTHROPIC grep -r ANTHROPIC ~/.config/systemd/user/ 2>/dev/null # 与配置文件对比 grep -i anthropic ~/.openclaw/openclaw.json grep ANTHROPIC ~/.openclaw/.env 2>/dev/null
环境变量优先于 json——删除陈旧 Environment= 行
# 从 systemd 删除陈旧覆盖（示例） # 编辑 ~/.config/systemd/user/openclaw-gateway.service # 删除：Environment=ANTHROPIC_API_KEY=old-value systemctl --user daemon-reload systemctl --user restart openclaw-gateway # 确认 gateway 使用正确密钥 openclaw gateway status
💡 专业技巧：密钥单一来源
Anthropic 密钥放在 ~/.openclaw/.env 或 openclaw.json providers 之一——不要用不同值两处都写。环境变量会静默覆盖配置。任何变更后重启 gateway，先用单条测试消息验证再开 heartbeat。
🛡️ 预防清单
- • 在 console.anthropic.com 创建密钥并启用计费——无额度的免费密钥常立即 401
- • 使用 sk-ant-api03- 前缀；OpenAI 风格 sk- 密钥无法用于 Anthropic 端点
- • 除非每次轮换都更新，否则不要把 ANTHROPIC_API_KEY 写进 systemd 单元
- • 编辑 providers 后运行 `openclaw doctor`——在 Agent 上生产通道前发现缺失密钥
- • 切勿将 live 密钥粘贴到 GitHub issue；意外泄露请轮换
❓ 常见问题
Q1. OpenClaw 日志里 Anthropic 401 长什么样？
常见行包括 `Anthropic API error: 401`、`authentication_error` 或 `invalid x-api-key`。Gateway 可能短暂重试后将提供商标为不健康。Agent 在工具调用前就失败。启用 debug 日志（log_level: debug）查看完整 HTTP 响应体——Anthropic 返回的 JSON 可区分无效密钥、缺失计费与错误组织。
Q2. curl 能用但 OpenClaw 不行——为什么？
OpenClaw 可能从 systemd、launchd、Docker compose 或 ~/.openclaw/.env 的 ANTHROPIC_API_KEY 读取不同密钥，而您用 curl -H 手动测试的是另一把。运行 `openclaw config get providers`（或查看 openclaw.json）对比末四位。确认 agents.defaults.provider 的 id 与您配置的 anthropic 条目一致——provider 名拼写错误会落到空凭证。
Q3. 需要 Anthropic 付费账户吗？
多数地区 API 访问需设置计费。控制台可能允许创建密钥，但在添加支付方式并激活用量限制前请求会 401。查看 console.anthropic.com/settings/billing。部分团队/组织密钥需在生成时选择正确工作区。试用额度过期时部分端点也会出现类似 401 的错误。
Q4. openclaw.json 里密钥具体放哪？
在 providers 数组中添加或编辑 type 为 anthropic 的对象（或与 Agent 引用的 id 一致）。常见形式：`{ "id": "anthropic", "type": "anthropic", "apiKey": "sk-ant-api03-..." }`。也可用 apiKeyEnv: "ANTHROPIC_API_KEY" 并仅在 ~/.openclaw/.env 设置变量。不要把密钥放在通道区或不相关 agent 字段——只有 provider 块提供模型认证。
Q5. 能用 AWS Bedrock 或 Vertex 避免直接 Anthropic 密钥吗？
若 OpenClaw 版本支持这些 provider 类型可以。Bedrock 用 IAM 角色而非 sk-ant- 密钥。配置单独 provider 条目并将 agents.defaults.provider 指向它。这绕过 console.anthropic.com 计费但需云 IAM 设置。社区反馈对家庭实验室 Mac Mini，直接 Anthropic API 更简单。
Q6. 轮换密钥后还要更新什么？
旧密钥复制过的每一处：~/.openclaw/.env、openclaw.json providers.apiKey、Docker compose 环境、systemd Environment= 行，以及远程 Agent 的 CI 密钥。变更后重启 gateway。控制台吊销的旧密钥立即 401——无宽限期。官方项目：github.com/openclaw/openclaw。