【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_MS60000ms, 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先别急着 CtrlC给它一点时间——很可能数据马上就回来了横幅自动清除任务继续。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针对慢网络/代理如果你确实在慢速网络或代理环境且任务又不便拆分可以把单请求超时调大。默认是 600000ms10 分钟按需往上调export API_TIMEOUT_MS1200000 # 20 分钟 claude很多接入第三方网关 / 国内中转的用户会把它设得很大比如 3000000ms 50 分钟写进settings.json或 shell 启动脚本里{ env: { API_TIMEOUT_MS: 3000000 } }但请注意调大超时只是给慢请求更多时间它不能解决网络本身断流的问题。如果是链路彻底卡死调多大都没用还是得去排查网络方案四。方案四排查网络与代理针对场景二如果Waiting for API response反复出现按网络问题排查确认能连通 API 主机从同一个 shell 跑curl -I https://api.anthropic.comWindows PowerShell 用curl.exe -I https://api.anthropic.com避免用到内置的Invoke-WebRequest别名。公司代理后面启动 Claude Code 前设置代理export HTTPS_PROXYhttp://你的代理地址:端口走 LLM 网关 / 中继把ANTHROPIC_BASE_URL指向网关地址。防火墙确认放行了官方网络访问要求中列出的主机。curl 通但 Claude Code 还失败的疑难情况Linux / WSL检查/etc/resolv.conf里有没有不可达的 DNS 服务器WSL 容易从主机继承坏解析器macOS检查ifconfig里有没有 VPN 断开后残留的utun接口或路由规则去系统设置删掉 VPN 的网络扩展Docker Desktop 等容器运行时可能拦截出站流量先退出它们排除一下。方案五脚本里调小重试次数让失败更快暴露在脚本场景如果你不想干等很久才看到失败可以调小重试次数export CLAUDE_CODE_MAX_RETRIES3超时也属于会被自动重试的瞬时故障调小这个值能让脚本更快认输并报错方便你及时介入。六、验证与回归重发请求try again看是否正常返回。拆小任务后验证把大任务拆成小步后逐个执行确认不再超时。curl 连通性测试curl -I https://api.anthropic.com应快速返回头信息。观察横幅Waiting for API response不再反复出现说明网络稳定。恢复配置临时调大的API_TIMEOUT_MS或调小的MAX_RETRIES按需还原。七、避坑与最佳实践别犯的错❌看到Waiting for API response立刻 CtrlC它还没失败给它倒计时跑完的机会。❌只会无脑调大API_TIMEOUT_MS网络断流时调多大都没用要去查链路。❌把超时当成账户/认证问题超时是连接层面的事跟 key、配额无关。该养成的习惯✅大任务主动拆小既防超时又提质量。✅慢网络配代理 调大超时HTTPS_PROXYAPI_TIMEOUT_MS组合拳。✅横幅反复出现就查网络这是最可靠的诊断信号。✅备好 curl 自检命令快速判断是网络还是 CLI 的问题。✅第三方网关写进 settings.json把超时、BASE_URL 等固化避免每次手敲。八、相关错误的区分错误本质关键区别处理Request timed out请求超过截止时间未完成信息极简连接层面拆任务 / 调 timeout / 查网络Waiting for API response流式响应中途停滞还没失败是预警等倒计时反复出现则查网络Unable to connect to APITCP 连接根本没建上带 ECONNREFUSED/ETIMEDOUT 等查网络/代理/防火墙500 / 529服务端崩溃 / 过载明确写 server-side等 / 换模型一条决策线信息极简的Request timed out→ 先想是不是任务太大再想是不是网络慢反复Waiting for API response→ 直接当网络问题查。九、总结Request timed out是 Claude Code 里信息最少、却最考验排查思路的报错之一。核心要点它表示请求在截止时间默认 10 分钟 /API_TIMEOUT_MS内没完成Waiting for API response横幅 ≠ 超时失败它是流式停滞的预警会自动重试/恢复但反复出现就要当网络问题处理三种根因任务太大、网络慢、服务端高负载——对症下药最治本的解法是拆小任务慢网络则调大API_TIMEOUT_MS并排查代理 / VPN / DNS / 容器拦截超时和认证、配额无关别往 key 上想。下次再看到那行孤零零的Request timed out先问自己一句是我让它干的活太大了还是我的网络在拖后腿——答案基本就在这两者之间。参考Claude Code 官方《错误参考》自动重试 / 服务器错误 / 网络与连接错误章节、官方网络配置文档、社区超时排查实战。 本文基于 Claude Code v2.1.x 行为整理停滞阈值 20s 适用于 v2.1.185不同版本细节可能略有差异。
