MaxClaw API 连接报错（401/429/Timeout）故障排查

dctc_shouhuzhe

echo -n "$YOUR_API_KEY" | tr -d '\r' > clean_key.txt
```

第四步，若 Key 确认有效但仍报 401，重置配置后重启：

```bash
openclaw config unset providers.openai.apiKey
openclaw config unset providers.openai.baseUrl

openclaw config set providers.openai.apiKey "*"
openclaw config set providers.openai.baseUrl "https://correct-endpoint.com/v1"

openclaw gateway restart
```

---

## 二、429 Rate Limit：请求频率超限

典型现象

```
Error: 429 Too Many Requests
Retry-After: 60
```

或

```
Error: 429 Rate limit exceeded
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1719123456
```

原理剖析

429 错误的本质是 API 服务商对客户端请求频率的限制机制。当用户在单位时间内发送的请求数量超过了服务商设定的阈值时，服务商会暂时拒绝后续请求，并返回 429 状态码告知客户端需要降低请求频率。这种限流机制的核心目的是保护 API 服务的稳定性和公平性，防止个别用户过度消耗服务器资源而影响其他用户的正常使用。

从技术实现角度，API 限流通常基于以下几种策略：

- RPM（Requests Per Minute）：每分钟允许的最大请求数
- TPM（Tokens Per Minute）：每分钟允许的最大 Token 消耗量
- RPD（Requests Per Day）：每日允许的最大请求数
- 并发连接数限制：同一时刻允许的最大并发请求数

理解这些限流维度对于精准定位 429 错误原因至关重要。有时候请求数没有超标，但 Token 消耗量超标了，同样会触发 429。

可能原因

1. 短时间内请求频率超过 API 提供商限额 — 这是最直接的触发原因。当 Agent 在短时间内密集调用 API（如批量处理任务、实时对话流式响应等场景），很容易突破 RPM 限制。
2. 多个 Agent 或任务并行使用同一 API Key — 在分布式部署或多任务并行场景下，多个进程共享同一个 API Key，其请求量会叠加计算，容易触发共享密钥的全局限流。
3. 未配置指数退避（Exponential Backoff），失败重试时雪崩 — 当请求失败后，客户端如果立即发起重试，会在原有请求量的基础上叠加额外的重试请求，导致"重试风暴"，使限流情况急剧恶化。
4. 所用模型的 RPM（Requests Per Minute）限额本身较低 — 部分高参数量的模型（如 GPT-4、Claude Opus 等）由于运行成本高昂，服务商设置的默认 RPM 限额相对较低，更容易触发限流。

解决步骤

第一步，查看当前请求量与限额差距：

```bash

openclaw config get rateLimits
```

常见 API 服务商默认限额参考（实际限额请以官方文档为准）：

| API 提供商 | 模型 | 默认 RPM | 默认 TPM |
|-----------|------|---------|---------|
| OpenAI | GPT-4 | 500 | 150,000 |
| OpenAI | GPT-3.5-Turbo | 3,500 | 160,000 |
| MiniMax | abab6.5s | 1,000 | 100,000 |
| DeepSeek | DeepSeek-chat | 1,000 | 200,000 |

第二步，配置请求频率限制与指数退避：

在 `~/.openclaw/openclaw.json` 中配置全局限频策略：

```json
{
  "rateLimits": {
    "apiCallsPerMinute": 20,
    "apiCallsPerHour": 200,
    "apiCallsPerDay": 2000
  },
  "retry": {
    "maxAttempts": 3,
    "backoff": "exponential",
    "initialDelay": "30s",
    "maxDelay": "5m",
    "retryableStatuses": [429, 500, 502, 503, 504]
  }
```

指数退避原理详解：

指数退避是防止重试风暴的关键机制。其核心思想是：每次重试失败后，等待时间按指数增长，而非线性或立即重试。

```
重试次数    等待时间
第1次失败 → 等待 30 秒
第2次失败 → 等待 60 秒（30 × 2^1）
第3次失败 → 等待 120 秒（30 × 2^2）
第4次失败 → 等待 240 秒（30 × 2^3）
...
最大等待时间不超过 5 分钟
```

这种策略的优势在于：当限流发生时，客户端会主动降低请求频率，给服务端足够的时间来刷新限流计数器，从而避免持续触发限流。

第三步，拆分 Key 负载：

```bash

openclaw config set providers.openai-secondary.apiKey "sk-ano…-key"
openclaw config set providers.openai-secondary.baseUrl "https://api.openai.com/v1"

```

第四步，若持续触发 429，考虑升级套餐或换用限额更高的 API 提供商。

---

## 三、Connection Timeout：网络超时

典型现象

```
Error: ECONNREFUSED
Connection refused - HTTP/2 connection failed
```

或

```
Error: ETIMEDOUT
Connection timed out after 30000ms
```

或

```
Error: EAI_AGAIN
DNS lookup failed for api.openai.com
```

原理剖析

Connection Timeout 错误的本质是客户端与 API 服务器之间的网络通道无法建立或中途断裂。与 401（认证问题）和 429（频率问题）不同，Timeout 错误的根因完全在网络层面，涉及 DNS 解析、TCP 连接建立、TLS 握手等网络通信的各个环节。

从一次 HTTP 请求的生命周期来看，可能触发 Timeout 的关键节点包括：

1. DNS 解析阶段：客户端将域名解析为 IP 地址，国内服务器访问海外 API 时，DNS 污染或解析超时是常见问题。

---

【标签】
Thinkpad, IBM, X1 Carbon, AI开发, Ollama部署, 本地大语言模型, VSCode配置, 华强北, 选购指南

【相关阅读】
- Thinkpad T14 深度评测：商务本的性能极限在哪里
- OpenClaw多模型集成配置指南
- 华强北Thinkpad港版购买防坑指南