【Claude】Request timed out 请求超时报错已解决

关键词：Claude Code、Request timed out、API_TIMEOUT_MS、请求超时、网络代理、自动重试、Waiting for API response

一、问题现象：一行干巴巴的超时

Claude Code 干着干着，终端冒出极简的一行：

Request timed out

如果你设置过 API_TIMEOUT_MS 环境变量，它可能还会带上提示：

Request timed out (API_TIMEOUT_MS=60000ms, try increasing it)

或者在网络场景下变体为：

Request timed out. Check your internet connection and proxy settings

这个错误的特征很鲜明：信息极短，就一句"请求超时"，不带堆栈、不带细节。也正因为它"太简洁"，很多人第一眼根本不知道从哪下手。它通常发生在：

• 执行长时间任务（大文件分析、多步编排、大型重构）；
• 慢速网络 / 代理 / VPN 环境下；
• 服务端高负载、或正在生成超大响应时。

二、超时是什么：连接没在截止时间内完成

Request timed out 的本质很直白：API 在连接截止时间（deadline）到达之前没有返回响应。

Claude Code 对每个请求有一个超时阈值，默认是 600000 毫秒（10 分钟）。当一个请求从发出到这个时间点都还没拿到完整响应，CLI 就会判定它超时并中止，抛出 Request timed out。

这里要分清两个容易混淆的概念：

概念	含义	触发条件
请求超时（Request timed out）	整个请求在截止时间内没完成	超过 API_TIMEOUT_MS（默认 10 分钟）
数据停滞看门狗（Waiting for API response）	响应流中途 20 秒没有新数据	流式响应卡住

后者其实还不是真正的失败——它是 Claude Code 的一个"早期预警"机制，下一节细说。

三、关键机制：Waiting for API response 不等于超时

这是理解超时问题最重要的一节。

3.1 数据停滞看门狗

当一个请求还在处理中，如果响应流上连续 20 秒没有任何数据到达，Claude Code 的微调器会显示这样一条横幅：

Waiting for API response · will retry in … · check your network

注意：此时请求并没有失败！ 这条横幅表示的是：

• 响应流暂时卡住了（没新数据）；
• 倒计时正在走，走到尽头时 Claude Code 会主动中止这个停滞的连接并重试；
• 一旦数据恢复流动、或重试成功，这条横幅会自动消失。

所以看到 Waiting for API response 先别急着 Ctrl+C，给它一点时间——很可能数据马上就回来了，横幅自动清除，任务继续。

3.2 阈值的版本差异

• v2.1.185 及以后：停滞阈值是 20 秒；
• 早期版本：是 10 秒后就显示横幅，且措辞略有不同。

3.3 判断信号：横幅反复出现 = 网络问题

一个非常实用的诊断技巧：

如果 Waiting for API response 横幅在每次尝试时都反复重新出现，就把它当作网络问题来处理。

偶发一次、然后恢复，那是正常的流式波动；但如果它一次次卷土重来、每次重试都卡住，那大概率是你和 API 之间的网络链路（代理、VPN、防火墙）有问题，需要去排查网络配置。

四、根因分析：超时的三种典型场景

Request timed out 背后通常对应三类根因，对症下药才有效：

场景一：任务太大 / 响应太长

你让 Claude 干一件巨大的活——分析几千行的大文件、做一次涉及十几个文件的重构、生成超长文档。模型要生成的响应非常长，整个请求-响应周期超过了超时阈值。

特征：网络其实没问题，就是任务本身太重。

场景二：网络 / 代理 / VPN 慢或不稳

你在公司代理后面、或挂着 VPN、或网络本身就慢。数据在链路上走走停停，迟迟凑不齐一个完整响应。

特征：Waiting for API response 横幅反复出现；其他网络操作也慢。

场景三：服务端高负载

服务端正处于高负载期，处理你的请求比平时慢很多，慢到超过了截止时间。

特征：可能伴随 500/529；状态页可能有公告。

五、解决方案

方案一：直接重试（首选，针对偶发超时）

很多超时是一次性的偶发抖动。直接重试即可。由于原始消息还在上下文，长 prompt 输入 try again 就行，不用重新粘贴。

方案二：把大任务拆小（针对场景一，最治本）

如果是因为任务太大导致的超时，最有效的办法是把工作拆成更小的提示。

比如：

• 不要一次性"重构整个模块"，而是"先重构 A 文件，再重构 B 文件"；
• 不要一次性"分析这个 5000 行的文件全部逻辑"，而是分函数 / 分段落让它读；
• 大文档生成拆成章节逐步产出。

拆小不仅能避开超时，往往结果质量也更高（模型注意力更聚焦）。

方案三：调大 API_TIMEOUT_MS（针对慢网络/代理）

如果你确实在慢速网络或代理环境，且任务又不便拆分，可以把单请求超时调大。默认是 600000ms（10 分钟），按需往上调：

export API_TIMEOUT_MS=1200000   # 20 分钟
claude

很多接入第三方网关 / 国内中转的用户会把它设得很大（比如 3000000ms = 50 分钟），写进 settings.json 或 shell 启动脚本里：

{
  "env": {
    "API_TIMEOUT_MS": "3000000"
  }
}

但请注意：调大超时只是"给慢请求更多时间"，它不能解决网络本身断流的问题。 如果是链路彻底卡死，调多大都没用，还是得去排查网络（方案四）。

方案四：排查网络与代理（针对场景二）

如果 Waiting for API response 反复出现，按网络问题排查：

1. 确认能连通 API 主机，从同一个 shell 跑：

   curl -I https://api.anthropic.com
   

   Windows PowerShell 用 curl.exe -I https://api.anthropic.com（避免用到内置的 Invoke-WebRequest 别名）。

2. 公司代理后面：启动 Claude Code 前设置代理：

   export HTTPS_PROXY=http://你的代理地址:端口
   

3. 走 LLM 网关 / 中继：把 ANTHROPIC_BASE_URL 指向网关地址。

4. 防火墙：确认放行了官方网络访问要求中列出的主机。

5. curl 通但 Claude Code 还失败 的疑难情况：

   • Linux / WSL：检查 /etc/resolv.conf 里有没有不可达的 DNS 服务器（WSL 容易从主机继承坏解析器）；
   • macOS：检查 ifconfig 里有没有 VPN 断开后残留的 utun 接口或路由规则，去系统设置删掉 VPN 的网络扩展；
   • Docker Desktop 等容器运行时可能拦截出站流量，先退出它们排除一下。

方案五：脚本里调小重试次数（让失败更快暴露）

在脚本场景，如果你不想干等很久才看到失败，可以调小重试次数：

export CLAUDE_CODE_MAX_RETRIES=3

超时也属于会被自动重试的瞬时故障，调小这个值能让脚本更快"认输"并报错，方便你及时介入。

六、验证与回归

1. 重发请求：try again，看是否正常返回。
2. 拆小任务后验证：把大任务拆成小步后逐个执行，确认不再超时。
3. curl 连通性测试：curl -I https://api.anthropic.com 应快速返回头信息。
4. 观察横幅：Waiting for API response 不再反复出现，说明网络稳定。
5. 恢复配置：临时调大的 API_TIMEOUT_MS 或调小的 MAX_RETRIES 按需还原。

七、避坑与最佳实践

别犯的错

• ❌ 看到 Waiting for API response 立刻 Ctrl+C：它还没失败，给它倒计时跑完的机会。
• ❌ 只会无脑调大 API_TIMEOUT_MS：网络断流时调多大都没用，要去查链路。
• ❌ 把超时当成账户/认证问题：超时是连接层面的事，跟 key、配额无关。

该养成的习惯

• ✅ 大任务主动拆小：既防超时又提质量。
• ✅ 慢网络配代理 + 调大超时：HTTPS_PROXY + API_TIMEOUT_MS 组合拳。
• ✅ 横幅反复出现就查网络：这是最可靠的诊断信号。
• ✅ 备好 curl 自检命令：快速判断是网络还是 CLI 的问题。
• ✅ 第三方网关写进 settings.json：把超时、BASE_URL 等固化，避免每次手敲。

八、相关错误的区分

错误	本质	关键区别	处理
Request timed out	请求超过截止时间未完成	信息极简，连接层面	拆任务 / 调 timeout / 查网络
Waiting for API response	流式响应中途停滞	还没失败，是预警	等倒计时；反复出现则查网络
Unable to connect to API	TCP 连接根本没建上	带 ECONNREFUSED/ETIMEDOUT 等	查网络/代理/防火墙
500 / 529	服务端崩溃 / 过载	明确写 server-side	等 / 换模型

一条决策线：信息极简的 Request timed out → 先想"是不是任务太大"，再想"是不是网络慢"；反复 Waiting for API response → 直接当网络问题查。

九、总结

Request timed out 是 Claude Code 里信息最少、却最考验排查思路的报错之一。核心要点：

1. 它表示请求在截止时间（默认 10 分钟 / API_TIMEOUT_MS）内没完成；
2. Waiting for API response 横幅 ≠ 超时失败，它是流式停滞的预警，会自动重试/恢复；但反复出现就要当网络问题处理；
3. 三种根因：任务太大、网络慢、服务端高负载——对症下药；
4. 最治本的解法是拆小任务；慢网络则调大 API_TIMEOUT_MS 并排查代理 / VPN / DNS / 容器拦截；
5. 超时和认证、配额无关，别往 key 上想。

下次再看到那行孤零零的 Request timed out，先问自己一句："是我让它干的活太大了，还是我的网络在拖后腿？"——答案基本就在这两者之间。

---

参考：Claude Code 官方《错误参考》"自动重试 / 服务器错误 / 网络与连接错误"章节、官方网络配置文档、社区超时排查实战。 本文基于 Claude Code v2.1.x 行为整理（停滞阈值 20s 适用于 v2.1.185+），不同版本细节可能略有差异。