一、问题描述

1.1 环境信息

项目	信息
工具	Claude Code (CLI)
操作系统	macOS / Windows / Linux
网络环境	需区别：直连 / 代理 / VPN
默认超时	600000ms（10 分钟）
相关配置	API_TIMEOUT_MS, CLAUDE_CODE_MAX_RETRIES

1.2 报错现象

在 Claude Code 中执行长时间任务（大文件分析、多步编排等）
时，终端输出：

Request timed out

关键特征：

• 错误信息简短，仅 “Request timed out”。
• 通常发生在请求发起后较长时间（接近或超过默认 10 分钟）。
• 如果错误提示中明确提到互联网连接或网络问题，则优先
  排查网络层面。
• 如果错误信息仅 “Request timed out” 而无网络参考，则
  更可能是 API 高负载或超大响应所致。

注意：务必区分"网络超时"与"API 响应超时"，二者的
处理路径不同。

---

二、根因分析

2.1 错误链路追踪

Claude Code 的超时机制如下：

1. CLI 向 API 发起请求，启动计时器。
2. 计时器以 API_TIMEOUT_MS 为上限（默认 600000ms）。
3. 如果在截止时间前未收到完整响应，连接被强制关闭。
4. CLI 抛出 Request timed out。

# 超时流程示意
[CLI] POST /v1/messages (timeout=600000ms)
[CLI]  Waiting for response stream...
[CLI]  600000ms elapsed, no complete response
[CLI] → Request timed out

2.2 三种根因场景

场景	特征	判断依据
API 高负载	无网络错误提示，发生在高峰时段	status.claude.com
超大响应	任务描述极长，或要求生成大量代码	拆分后每段都能完成
网络/代理慢	错误带有网络相关措辞，ping 延迟高	ping api.anthropic.com

2.3 可能原因分述

1. API 高负载导致响应延迟

   • 推理节点排队时间过长，响应流迟迟不返回。
   • 此时请求未失败，只是未在截止时间内完成。

2. 超大响应超出超时窗口

   • 一次请求要求 AI 分析整个代码仓库或生成数千行代码。
   • 即使推理正常，生成 token 的速度不足以在 10 分钟内完成。

3. 网络代理引入额外延迟

   • 公司 VPN 或 HTTP 代理增加数十秒到数分钟的延迟。
   • 叠加多次自动重试后总耗时轻易突破 10 分钟。

4. CLAUDE_CODE_MAX_RETRIES 与超时的交互

   • 如果 CLAUDE_CODE_MAX_RETRIES 设置为较高值，单次
     超时后还会再重试，总等待时间成倍增加。

---

三、解决方案

方案一：拆分大任务（推荐）

适用场景：任务本身复杂，响应自然耗时。

将大任务拆分为多个独立步骤：

# 不推荐：一次要求分析整个项目
$ claude -p "分析整个 src/ 目录的所有文件并给出重构建议"

# 推荐：分步骤进行
$ claude -p "分析 src/models/ 目录的数据模型设计"
$ claude -p "分析 src/services/ 目录的服务层设计"
$ claude -p "综合上述分析，给出重构建议"

拆分后每步请求在 1-3 分钟内完成，远低于超时阈值。

注意：Claude Code 支持在对话中引用上一步的分析结果，
无需每次重新描述上下文。

方案二：调整 API_TIMEOUT_MS

适用场景：网络环境确实较慢，且任务无法拆分。

通过环境变量提高超时上限：

# Linux / macOS
export API_TIMEOUT_MS=1200000   # 20 分钟

# Windows (PowerShell)
$env:API_TIMEOUT_MS=1200000

# Windows (CMD)
set API_TIMEOUT_MS=1200000

参数	默认值	建议范围
API_TIMEOUT_MS	600000ms (10min)	300000 - 1800000ms

注意：不建议设置超过 30 分钟的超时，过长等待会阻塞
工作流。如果 20 分钟仍超时，应回到方案一拆分任务。

方案三：排查网络与代理

适用场景：错误信息中带有"网络"或"连接"相关措辞。

# 测试 API 连通性
curl -I https://api.anthropic.com

# 测试延迟
ping api.anthropic.com

常见网络问题及处理：

问题	处理方式
VPN 延迟高	暂时断开 VPN，使用直连
HTTP 代理超时	增加代理超时配置或在 CLI 中设置 NO_PROXY
DNS 解析慢	切换至 8.8.8.8 或 1.1.1.1

方案四：减少 CLAUDE_CODE_MAX_RETRIES

适用场景：超时与重试叠加导致长时间无反馈。

# 减少重试次数，更快获得超时反馈
export CLAUDE_CODE_MAX_RETRIES=2

配合较低的重试次数，超时后能更快让用户介入决策，而非
长时间静默。

---

四、验证与回归测试

1. 连通性测试

curl -w "\ntime_total: %{time_total}s\n" \
  -o /dev/null -s https://api.anthropic.com

响应时间应在 1 秒以内（不含 API 推理时间）。

2. 小任务验证

$ claude -p "1+1等于几?"

若小任务正常完成，排除网络或认证问题。

3. 中任务逐步放大

# 从单个文件开始
$ claude -p "分析 src/main.py 的入口逻辑"

# 然后扩大到模块
$ claude -p "分析 src/app/ 的模块划分"

4. 配置生效确认

echo $API_TIMEOUT_MS
# 应输出新的超时值（单位毫秒）

---

五、总结与预防

5.1 核心要点

1. Request timed out 有两种可能的根因：网络问题与
   API 响应过慢，需根据错误细节区分。
2. 默认超时为 10 分钟，对大多数任务足够，对超大响应则偏紧。
3. 优先拆分任务而不是盲目提高超时——拆分后每步都有清晰
   的检查点。
4. CLAUDE_CODE_MAX_RETRIES 与 API_TIMEOUT_MS 叠加
   使用时需关注总等待时间。

5.2 最佳实践建议

• 在 .bashrc 或 .zshrc 中预设 API_TIMEOUT_MS=600000
  作为基准配置，仅按需临时调高。
• 养成任务拆分习惯：一次请求不超过 3 个独立子任务。
• 定期用 curl 或 ping 检测到 API 的延迟基线，建立心理
  预期。
• 如果使用 CI/CD 集成 Claude Code，在流水线中显式设置
  超时变量，避免依赖默认值可能带来的差异。

---

六、参考资料

• Claude Code 环境变量配置
• Anthropic API 参考