前言
OpenClaw 需要与各种 AI 模型提供商的 API 通信。在使用过程中，你可能会遇到各类连接错误。本文将系统性地介绍每种错误的原因和解决方案，帮助你快速定位并修复问题。
一、快速诊断工具
在排查之前，先使用 OpenClaw 内置的诊断工具：
# 运行综合诊断
openclaw doctor
# 查看实时日志中的错误
openclaw logs | grep -i "error\|fail\|timeout"
# 测试 API 连接
curl -v https://api.anthropic.com/v1/messages \
-H "x-api-key: YOUR_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"}]}'
二、HTTP 错误码详解
2.1 401 Unauthorized — 认证失败
症状：
Error: API request failed with status 401: Invalid API key
原因和解决方案：
| 可能原因 | 解决方案 |
|---|---|
| API Key 错误或已过期 | 重新生成 Key 并更新配置 |
| Key 格式不完整 | 检查是否有多余空格或换行 |
| 使用了错误提供商的 Key | 确认 Key 与提供商匹配 |
| 环境变量未生效 | 重启 OpenClaw 使配置生效 |
# 检查配置文件中的 API Key
cat ~/.config/openclaw/openclaw.json5 | grep -i "key\|token"
# 确保 Key 格式正确（以 Anthropic 为例，应以 sk-ant- 开头）
# 更新后重启
openclaw restart
2.2 403 Forbidden — 权限不足
症状：
Error: API request failed with status 403: Permission denied
常见原因：
- API Key 没有对应模型的访问权限
- 账户未开通某些模型的使用资格（如 Claude Opus）
- IP 地址被 API 提供商封禁
- 所在地区不在服务范围内
# 检查是否是 IP 限制问题
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $API_KEY" \
-H "anthropic-version: 2023-06-01" \
-w "\n%{http_code}" 2>&1
# 如果使用代理，确认代理配置正确
echo $HTTP_PROXY
echo $HTTPS_PROXY
2.3 429 Too Many Requests — 速率限制
症状：
Error: Rate limit exceeded. Please retry after 30 seconds.
各提供商的速率限制参考：
| 提供商 | 免费额度 | 基础限制 | 高级限制 |
|---|---|---|---|
| Anthropic | 无 | 60 RPM | 4000 RPM |
| OpenAI | 有 | 60 RPM | 10000 RPM |
| Groq | 有 | 30 RPM | 无限制 |
| Deepseek | 有 | 60 RPM | 600 RPM |
解决方案：
// ~/.config/openclaw/openclaw.json5
{
"rateLimiting": {
// 全局请求间隔（毫秒）
"minInterval": 1000,
// 速率限制时的重试策略
"retry": {
"enabled": true,
"maxRetries": 3,
"backoffMultiplier": 2,
"initialDelay": 5000
}
}
}
2.4 500 Internal Server Error — 服务器内部错误
处理方式：
# 这通常是提供商侧的问题，检查服务状态页面
# Anthropic: https://status.anthropic.com
# OpenAI: https://status.openai.com
# 配置备用模型自动切换
// ~/.config/openclaw/openclaw.json5
{
"models": {
"primary": {
"provider": "anthropic",
"model": "claude-sonnet-4-20250514"
},
"fallback": {
"provider": "openai",
"model": "gpt-4o"
}
}
}
2.5 502/503 Bad Gateway / Service Unavailable
症状：
Error: 502 Bad Gateway
Error: 503 Service Unavailable - The server is temporarily overloaded
排查步骤：
# 1. 确认是否为提供商服务故障
curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com/v1/messages
# 2. 检查本地网络是否正常
ping api.anthropic.com
traceroute api.anthropic.com
# 3. 如果使用反向代理，检查代理是否正常
nginx -t
systemctl status nginx
三、超时问题排查
3.1 连接超时
Error: connect ETIMEDOUT 104.18.0.1:443
# 测试与 API 端点的连接
curl -v --connect-timeout 10 https://api.anthropic.com/v1/messages
# 如果连接超时，可能需要配置代理
// ~/.config/openclaw/openclaw.json5
{
"proxy": {
"enabled": true,
"url": "http://127.0.0.1:7890",
// 或使用 SOCKS5 代理
// "url": "socks5://127.0.0.1:1080"
},
"timeout": {
"connect": 30000, // 连接超时 30 秒
"request": 120000 // 请求超时 120 秒
}
}
3.2 请求超时
当模型生成长文本时，可能会超过默认超时时间：
// 增加超时时间
{
"timeout": {
"request": 300000 // 5分钟
}
}
四、DNS 解析失败
症状：
Error: getaddrinfo ENOTFOUND api.anthropic.com
Error: querySrv ESERVFAIL _http._tcp.api.openai.com
解决方案：
# 1. 检查 DNS 解析
nslookup api.anthropic.com
dig api.anthropic.com
# 2. 尝试使用公共 DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf
# 3. 手动添加 hosts 记录（临时方案）
echo "104.18.0.1 api.anthropic.com" | sudo tee -a /etc/hosts
# 4. 测试修复后的解析
nslookup api.anthropic.com
五、SSL 证书错误
症状：
Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
Error: CERT_HAS_EXPIRED
排查和解决：
# 1. 检查证书信息
openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com </dev/null 2>/dev/null | openssl x509 -noout -dates
# 2. 更新系统 CA 证书
# Ubuntu/Debian
sudo apt update && sudo apt install -y ca-certificates
sudo update-ca-certificates
# CentOS/RHEL
sudo yum install -y ca-certificates
sudo update-ca-trust
# 3. 如果是代理的中间人证书问题
# 将代理的 CA 证书添加到 Node.js 信任列表
export NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.crt
警告：永远不要在生产环境设置
NODE_TLS_REJECT_UNAUTHORIZED=0，这会完全禁用 SSL 验证，存在严重安全风险。
六、代理配置问题
6.1 HTTP 代理
// ~/.config/openclaw/openclaw.json5
{
"proxy": {
"enabled": true,
"url": "http://127.0.0.1:7890"
}
}
6.2 环境变量方式
# 在系统环境中设置
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
# 重启 OpenClaw
openclaw restart
6.3 代理连通性测试
# 通过代理测试 API 访问
curl -x http://127.0.0.1:7890 -v https://api.anthropic.com/v1/messages
# 测试 SOCKS5 代理
curl -x socks5://127.0.0.1:1080 -v https://api.anthropic.com/v1/messages
七、各提供商专项排查
7.1 Anthropic (Claude)
# 验证 API Key 有效性
curl 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":5,"messages":[{"role":"user","content":"test"}]}'
常见问题：API Key 格式为 sk-ant-api03-...，注意不要与 OpenAI 的 Key 混淆。
7.2 OpenAI (GPT)
# 验证 API Key
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}],"max_tokens":5}'
常见问题：免费额度用完后会返回 429 错误，需要绑定付费方式。
7.3 Ollama（本地模型）
# 检查 Ollama 服务是否运行
curl http://localhost:11434/api/tags
# 确认模型已下载
ollama list
# 测试模型调用
curl http://localhost:11434/api/generate \
-d '{"model":"llama3","prompt":"test","stream":false}'
常见问题：Ollama 默认只监听 localhost，如果 OpenClaw 在其他机器需要设置 OLLAMA_HOST=0.0.0.0。
7.4 OpenRouter
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"anthropic/claude-sonnet-4-20250514","messages":[{"role":"user","content":"test"}]}'
八、错误排查检查清单
遇到 API 连接错误时，按以下顺序排查：
1. ✅ 运行 openclaw doctor 查看诊断结果
2. ✅ 确认 API Key 正确且未过期
3. ✅ 检查网络连接（ping、curl）
4. ✅ 确认代理配置正确（如果使用代理）
5. ✅ 检查 DNS 解析是否正常
6. ✅ 验证 SSL 证书是否有效
7. ✅ 查看提供商服务状态页面
8. ✅ 检查速率限制是否触发
9. ✅ 查看 openclaw logs 中的详细错误信息
10. ✅ 尝试直接用 curl 调用 API 排除 OpenClaw 本身问题
掌握这些排查技巧，你就能快速定位并解决绝大多数 API 连接问题，保持 OpenClaw 服务的稳定运行。