问题描述
启动 OpenClaw 或在对话过程中，遇到与 API 认证相关的错误：
[openclaw:gateway] Error: 401 Unauthorized - Invalid API key provided.
[openclaw:gateway] Provider: openai, Model: gpt-4o
或者 Anthropic 的认证错误：
[openclaw:gateway] Error: 401 - {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Google Gemini 的认证失败：
[openclaw:gateway] Error: 403 - API key not valid. Please pass a valid API key.
认证错误意味着 OpenClaw 无法通过 AI 模型提供商的身份验证，请求被拒绝。这通常是 API Key 配置错误、已过期或被撤销导致的。
诊断步骤
第一步：确认配置文件中的 Key
查看当前配置中的 API Key 设置（注意，密钥仅显示部分字符）：
openclaw config show --unmask-partial
输出示例：
providers.openai.apiKey: sk-proj-...Xk3a
providers.anthropic.apiKey: sk-ant-...9f2b
确认显示的 Key 前缀和后缀与你在提供商控制台中看到的一致。
第二步：直接验证 API Key
使用 curl 直接测试各提供商的 API Key 是否有效：
OpenAI：
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer sk-your-key-here"
Anthropic：
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: sk-ant-your-key-here" \
-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"}]}'
Google Gemini：
curl "https://generativelanguage.googleapis.com/v1/models?key=YOUR_API_KEY"
如果返回 401 或 403 错误，说明 Key 本身就无效。
第三步：检查环境变量覆盖
OpenClaw 支持通过环境变量设置 API Key，环境变量的优先级高于配置文件。检查是否存在环境变量覆盖：
env | grep -i "OPENCLAW\|OPENAI\|ANTHROPIC\|GEMINI"
如果环境变量中设置了错误的 Key，会覆盖配置文件中正确的 Key。
解决方案
问题一：API Key 错误或格式不正确
不同提供商的 API Key 有不同的格式：
- OpenAI：以
sk-proj-或sk-开头 - Anthropic：以
sk-ant-api03-开头 - Google Gemini：通常为 39 字符的字母数字字符串
检查配置文件中是否有多余的空格、换行符或引号问题：
cat -A ~/.openclaw/openclaw.json | grep apiKey
如果行尾有 ^M（Windows 换行符）或多余空格，需要清理。
更新 API Key 的推荐方式：
openclaw config set providers.openai.apiKey "sk-proj-your-new-key"
openclaw config set providers.anthropic.apiKey "sk-ant-api03-your-new-key"
使用 openclaw config set 命令可以避免手动编辑 JSON 时的格式错误。
问题二：API Key 已过期或被撤销
API Key 可能因为以下原因失效：
- 在提供商控制台中手动撤销了旧 Key
- Key 达到了设定的过期时间
- 提供商因安全原因强制轮换了 Key
- 账户欠费导致 Key 被暂停
解决方法是登录对应提供商的控制台，生成新的 API Key：
- OpenAI：platform.openai.com/api-keys
- Anthropic：console.anthropic.com/settings/keys
- Google AI Studio：aistudio.google.com/apikey
生成新 Key 后更新到 OpenClaw 配置中。
问题三：配置多提供商 Key 轮换
为了避免单个 Key 失效导致服务中断，配置 Key 轮换和自动验证：
{
"providers": {
"openai": {
"apiKeys": [
"sk-proj-primary-key",
"sk-proj-backup-key"
],
"keyValidation": {
"enabled": true,
"intervalMinutes": 60,
"removeInvalid": true
}
}
}
}
keyValidation 功能会定期检查每个 Key 的有效性。当发现某个 Key 失效时，自动从轮换列表中移除，并在日志中发出警告。
问题四：使用环境变量安全管理 Key
为了避免将 API Key 明文写在配置文件中，建议使用环境变量：
export OPENCLAW_OPENAI_API_KEY="sk-proj-your-key"
export OPENCLAW_ANTHROPIC_API_KEY="sk-ant-api03-your-key"
在配置文件中引用环境变量：
{
"providers": {
"openai": {
"apiKey": "${OPENCLAW_OPENAI_API_KEY}"
},
"anthropic": {
"apiKey": "${OPENCLAW_ANTHROPIC_API_KEY}"
}
}
}
如果使用 systemd 管理 OpenClaw 服务，在 service 文件中配置环境变量：
[Service]
EnvironmentFile=/etc/openclaw/env
ExecStart=/usr/local/bin/openclaw start
验证修复
更新 Key 后重启 OpenClaw 并验证：
openclaw restart
openclaw doctor
openclaw doctor 会对所有配置的提供商进行 API 连通性测试，显示每个提供商的认证状态。如果所有提供商显示绿色状态，说明认证问题已解决。
也可以手动触发一次测试请求：
openclaw test-message --channel telegram --text "测试消息"
观察日志确认消息被成功处理。