Claude Code 频繁提示“连接中断”或直接连不上，该怎么办？
Claude Code 依赖长连接的流式传输来实时返回生成内容，一旦这条连接在传输过程中被意外掐断，就会出现“Connection reset by peer”“socket hang up”或“API Error: Connection closed mid-response”这类报错。多数情况下问题不在 Anthropic 服务端，而出在你和服务端之间的链路——公司代理、家用路由器或运营商出口的空闲连接超时策略，往往先于 Claude Code 自身的重试机制生效，把还在工作的长连接判定为“空闲”并直接切断。本文按“先分层定位、再逐项排查”的顺序，梳理一套可以按步骤走完的排查方案。
第一步：分清是网络层问题还是 API 返回的错误
遇到连不上，先别急着改配置，官方内置的 /doctor 自诊断命令是最快的起点，它会检查安装完整性、鉴权状态和基础网络连通性，先跑一遍能排除掉一大半“低级”问题。如果 /doctor 通过但请求仍然失败，下一步是区分故障层级：请求如果连 状态码和 request-id 都拿不到，说明问题出在连接层，还没到 Anthropic 的 API 处理逻辑；如果拿到了带 request_id 的 JSON 错误体，那就是 API 返回的业务错误，两者的排查方向完全不同，前者要查链路，后者要查请求参数或额度。
快速判断连通性
可以用 curl 直接探测 https://api.anthropic.com 是否可达，同时检查 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 这几个环境变量有没有被系统或终端工具意外覆盖——尤其是 WSL 环境，经常会继承一个不可达的 DNS 解析地址，导致看似“网络正常”实则请求根本发不出去。
长任务、后台任务跑到一半就断线，大概率是中间链路的空闲超时
Claude Code 在执行长时间重构或多文件编辑这类任务时，请求处理加流式输出很容易超过 30-60 秒——而这恰好是很多运营商出口设备、企业代理和家用路由器对长连接设置的默认空闲超时阈值。连接被中间设备判定超时掐断后，应用层往往连报错信息都来不及看到，表现就是“任务跑到一半突然没反应”“claude 进程还在但没有任何输出”。这类问题的另一个变种是下载或更新超时：如果一次下载在 10 分钟总时限内没有完成，会报“Download timed out: exceeded the total deadline”，且 Claude Code 不会对超时下载做立即重试，因为链路慢到跑不完一次的连接，立刻重试大概率还是跑不完。
这类“中间链路超时”问题，本质上是从你的出口到 Anthropic 服务端之间要经过多段公共网络节点，每一段都有各自的超时策略和拥塞情况，链路越长、经过的中转越多，被某一段提前判定超时的概率就越高。这也是为什么不少团队在切换到延迟更低、跳数更少的国际专线接入之后，长任务断线的频率会明显下降——专线走的是相对固定的出口路径，减少了被中间代理设备提前掐断的变量。通宝 VPN 的 IEPL 国际专线 + AI 智能路由会针对 Claude、GPT 等海外 AI 服务自动择优直连，团队席位下每个成员都能拿到独立稳定的出口，不用逐人排查代理配置。
企业代理、VSCode 插件场景下的额外排查项
VSCode 插件不会自动继承终端代理配置
如果你在终端里 export 过 HTTPS_PROXY，但 VSCode 里的 Claude 插件依然连不上，这是因为插件有自己独立的网络栈，不会自动读取终端的环境变量，需要在插件设置里单独配置代理地址，优先级从高到低依次是：插件专属配置 > 系统环境变量 > 命令行环境变量 > 系统代理设置。
TLS 版本不匹配
部分年代较久的企业级 SSL 中间设备只支持 TLS 1.2，而 Claude Code 默认协商 TLS 1.3，握手阶段就会报版本不匹配的错误。如果确认自己在企业网络环境下，可以让 IT 提供内部 CA 证书，通过 NODE_EXTRA_CA_CERTS 环境变量指定证书路径。
调大超时与重试阈值
API_TIMEOUT_MS 环境变量控制单次请求的超时时间（单位毫秒），把它调大到 900000 能给复杂任务多留 5 分钟处理时间；CLAUDE_CODE_MAX_RETRIES 则控制失败后的重试次数。如果连的是 MCP Server，还要额外确认 claude mcp list 里对应服务是“已连接”状态，启动较慢的 MCP Server 可以调大 MCP_TIMEOUT 给它更多启动时间。
公共网络链路与专线接入，长连接稳定性差在哪
| 维度 | 公共网络多跳链路 | IEPL 国际专线 |
|---|---|---|
| 出口路径 | 经多段公共骨干网中转，路径不固定 | 相对固定的专属出口路径 |
| 中间代理超时风险 | 途经节点多，任一段都可能提前判定空闲超时 | 跳数更少，被中转设备提前掐断的概率更低 |
| 长任务/流式传输 | 抖动和丢包更容易打断长连接 | 链路更稳定，长任务掉线频率明显下降 |
| 多工具并发访问 | Claude Code、Cursor、Copilot 分别走不同出口，体验不一致 | AI 智能路由统一择优直连，体验一致 |
排查思路总结与 8 步检查清单
Claude Code 连不上或频繁断线，先用 /doctor 和 curl 定位是连接层还是 API 层问题，再针对长任务的中间链路超时、VSCode 插件代理配置、TLS 版本这几个高频原因逐项排查，可以按下面这张清单逐条走一遍：
- 先跑 /doctor 做基础自检
- curl 探测 api.anthropic.com 是否可达
- 检查 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 是否被意外覆盖或残留
- WSL 环境检查 /etc/resolv.conf 是否指向不可达的 DNS
- macOS 检查 ifconfig 有没有残留的 utun 隧道接口（卸载过 VPN 客户端后常见）
- VSCode 插件单独确认代理配置，不要依赖终端环境变量
- 调整 API_TIMEOUT_MS / CLAUDE_CODE_MAX_RETRIES 应对复杂任务
- 把超大任务拆成多个小任务，降低单次请求触发中间链路超时的概率
如果基础排查都做完问题依然反复出现，大概率是链路本身不够稳定，这时候优化接入链路会比继续调整客户端参数更有效。
常见问题
Claude Code 报错 Connection reset by peer 是什么原因？
通常是长连接在传输过程中被中间的代理、路由器或运营商出口设备判定为空闲并主动切断，而不是 Anthropic 服务端主动断开，建议按前文的分层排查顺序定位具体是哪一段链路超时。
调大 API_TIMEOUT_MS 之后还是会断线怎么办？
调大超时阈值只能延长客户端等待时间，如果中间链路本身有更短的空闲超时策略，连接依然会在到达客户端设定的超时之前被提前掐断，这种情况需要从链路本身入手，而不是继续调大客户端参数。
VSCode 里配置了代理为什么 Claude 插件还是连不上？
VSCode 插件的网络栈和终端是分离的，插件不会自动读取你在终端里 export 的代理变量，需要在插件设置里单独填写代理地址。
