【Bug已解决】openclaw: "network timeout" / Connection timed out — OpenClaw 网络超时解决方案

1. 问题描述

OpenClaw 在请求过程中遇到网络超时错误：

# 请求超时 $ openclaw "分析代码" Error: Request timeout exceeded 30000ms # 或连接超时 $ openclaw --print "task" Error: ETIMEDOUT Connection timed out to api.anthropic.com. # 或流式超时 $ openclaw "长任务" Error: Stream timeout No data received for 30000ms. # 或 DNS 超时 $ openclaw "task" Error: ENOTFOUND Could not resolve api.anthropic.com.

这个问题在以下场景中特别常见：

• 网络不稳定
• 服务端响应慢
• DNS 解析慢
• 企业安全策略策略限制
• 安全策略阻断
• 流量高峰

2. 原因分析

原因分类表

3. 解决方案

方案一：增加超时（最推荐）

# 步骤 1：增加请求超时 export OPENCLAW_REQUEST_TIMEOUT=120000 # 120 秒 # 步骤 2：永久设置 echo 'export OPENCLAW_REQUEST_TIMEOUT=120000' >> ~/.bashrc source ~/.bashrc # 步骤 3：或使用 --timeout openclaw --timeout 120000 "task" # 步骤 4：验证 openclaw --print "hello"

方案二：检查网络

# 步骤 1：测试连通性 ping -c 5 api.anthropic.com # 步骤 2：检查 DNS nslookup api.anthropic.com # 步骤 3：检查带宽 # 速度测试: fast.com 或 speed-test # 步骤 4：验证 openclaw --print "hello"

方案三：检查 DNS 和安全策略

# 步骤 1：检查 DNS 解析速度 time nslookup api.anthropic.com # 如果解析超过 2 秒，DNS 有问题 # 步骤 2：更换 DNS 服务器 sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf' nslookup api.anthropic.com # 步骤 3：检查安全策略是否阻断 443 端口 # Linux (iptables) sudo iptables -L -n | grep 443 # macOS (pfctl) sudo pfctl -sr 2>/dev/null | grep -i block # 步骤 4：验证连通性 curl -I https://api.anthropic.com --max-time 10 openclaw --print "hello"

方案四：使用 --no-stream

# 步骤 1：非流式模式 openclaw --no-stream "task" # 步骤 2：或 --print --no-stream openclaw --print --no-stream "task" # 步骤 3：增加超时 export OPENCLAW_REQUEST_TIMEOUT=120000 openclaw --no-stream "长任务" # 步骤 4：验证 openclaw --print --no-stream "hello"

方案五：重试

# 步骤 1：简单重试 openclaw "task" # 如果超时，重试 # 步骤 2：重试脚本 for i in 1 2 3 4 5; do output=$(openclaw --print --no-stream "task" 2>&1) if echo "$output" | grep -qi "timeout\|ETIMEDOUT\|ENOTFOUND"; then echo "Timeout, retry $i in 10s..." sleep 10 else echo "$output" break fi done # 步骤 3：CI/CD 中 openclaw --print "task" || sleep 30 && openclaw --print "task"

方案六：切换模型

# 步骤 1：切换到更快模型 openclaw --model claude-3-haiku "task" # 步骤 2：减少 max_tokens openclaw --max-tokens 4096 "task" # 步骤 3：简化提示 openclaw --print "分析 src/index.js" # 步骤 4：验证 openclaw --model claude-3-haiku --print "hello"

4. 各方案对比总结

5. 常见问题 FAQ

5.1 默认超时多少

通常 30 秒。通过OPENCLAW_REQUEST_TIMEOUT调整。

5.2 如何增加超时

export OPENCLAW_REQUEST_TIMEOUT=120000 # 120 秒

5.3 ETIMEDOUT 是什么

连接超时。网络无法在指定时间内建立连接。

5.4 ENOTFOUND 是什么

DNS 解析失败。无法解析域名。

5.5 如何检查网络

ping -c 5 api.anthropic.com nslookup api.anthropic.com

5.6 安全策略导致超时

企业安全策略可能限制 443 端口出站流量。使用sudo iptables -L -n（Linux）或sudo pfctl -sr（macOS）检查安全策略规则，确认 API 端点未被拦截。

5.7 --no-stream 有帮助吗

有时。非流式模式不保持长连接，减少超时。

5.8 如何重试

openclaw --print "task" || sleep 30 && openclaw --print "task"

5.9 claude-3-haiku 更快吗

是的。Haiku 响应更快，减少超时概率。

5.10 排查清单速查表

□ 1. OPENCLAW_REQUEST_TIMEOUT=120000 □ 2. openclaw --timeout 120000 "task" □ 3. ping api.anthropic.com 检查网络 □ 4. nslookup 检查 DNS □ 5. nslookup 检查 DNS 解析速度 □ 6. 更换 DNS 8.8.8.8 测试 □ 7. --no-stream 非流式 □ 8. 重试: for + sleep + grep timeout □ 9. --model haiku 更快 □ 10. --max-tokens 4096 减少

6. 总结

1. 根本原因：网络超时最常见原因是网络不稳定（35%）和服务端响应慢（25%）
2. 最佳实践：使用export OPENCLAW_REQUEST_TIMEOUT=120000（120 秒）增加超时
3. 检查网络：ping api.anthropic.com和nslookup检查连通性和 DNS
4. --no-stream：非流式模式 +--timeout减少超时
5. 最佳实践建议：CI/CD 中使用重试脚本 +--no-stream+OPENCLAW_REQUEST_TIMEOUT=120000

故障排查流程图

flowchart TD A[网络超时] --> B[增加超时] B --> C[OPENCLAW_REQUEST_TIMEOUT=120000] C --> D[openclaw 验证] D --> E{成功?} E -->|是| F[✅ 问题解决] E -->|否| G[检查网络] G --> H[ping api.anthropic.com] H --> I{网络正常?} I -->|否| j[切换网络/修复] I -->|是| K[检查 DNS/安全策略] j --> D K --> L{DNS 正常?} L -->|否| M[更换 DNS 8.8.8.8] L -->|是| N[使用 --no-stream] M --> D N --> O[openclaw --no-stream "task"] O --> P{成功?} P -->|是| F P -->|否| Q[重试脚本] Q --> R[for + sleep + grep timeout] R --> S{成功?} S -->|是| F S -->|否| T[切换模型] T --> U[--model claude-3-haiku] U --> D D --> V{成功?} V -->|是| F V -->|否| W[检查 DNS] W --> X[nslookup api.anthropic.com] X --> Y{DNS 正常?} Y -->|否| Z[更换 DNS 8.8.8.8] Y -->|是| AA[避开高峰期] Z --> D AA --> AB[非高峰使用] AB --> D F --> AC[长期: 超时 + --no-stream + 重试] AC --> AD[✅ 长期方案]