Claude Code 报错排查：ECONNRESET 与 API ERROR

某天下午，我在终端里敲下claude，回车，光标闪了两下，正准备把一段两百行的重构需求贴进去，屏幕上先甩出来一行红字：Unable to connect to API (ECONNRESET)。再试一次，变成API ERROR，第三次干脆卡在Connecting...不动了。同一台机器、同一个终端、十分钟前还好好的。这种时候最容易犯的错就是立刻怀疑"是不是服务挂了"，然后开始无脑重试，重试十几次之后彻底放弃。实际上ECONNRESET这个错误码的信息量非常大，它几乎在明明白白告诉你：链路是通的，握手是完成的，是对端（或者链路中途的某个设备）在某个时刻把这条 TCP 连接掐掉了。搞清这一点，排查方向立刻从"网通不通"切换到"谁在什么时候掐的、为什么掐"。这篇内容围绕 Claude Code 在真实使用中遇到的 API ERROR 与 ECONNRESET 两类报错展开，讲清楚它们的层次差异、请求链路上每一道关卡各自的断连习惯、一套可以照着复现的四层排查流程，以及让长请求不再被中途截断的参数调优和脚本兜底方案。无论你是刚装好 CLI 想跑通第一次对话，还是已经用了几个月开始频繁撞墙，下面这些排查路径和参数取舍都能直接拿去用。

1. 报错文本背后的分层含义：先把 ECONNRESET 翻译成人话

1.1 RST 不是"网络不通"，而是"对面先挂了电话"

很多人把ECONNRESET和"断网"划等号，这是排查跑偏的头号原因。从 TCP 层面看，ECONNRESET对应的是一次RST报文的收发——连接已经建立，三次握手早就完成，数据也可能已经发出去了，然后某一方（或者链路上的中间设备）发出了一个RST，强制终止这条连接。换句话说，电话是打通了的，只是对方在你说话说到一半的时候把话筒扣了。这和ENOTFOUND、EAI_AGAIN（域名根本没解析出来）、ECONNREFUSED（端口没人监听，连接请求被直接拒绝）、ETIMEDOUT（长时间没响应）是完全不同层面的问题。区分这几个错误码，能省下大量瞎试的时间。

我在实际排查里习惯先做一个错误码对照，把"症状"和"病灶位置"对上号。下面这张表是我自己常用的一张速查表，遇到报错先归类，能直接把排查范围从"整条链路"缩到"某一段"：

这张表的意义在于：ECONNREFUSED要去查"地址对不对、服务起没起"，而ECONNRESET要去查"什么时候断的、断之前发生了什么"。两者的动作完全不同，搞混了就只能靠运气。

1.2 API ERROR 与 Unable to connect 分属两个不同阶段

Unable to connect to API (ECONNRESET)和裸的API ERROR看似都是"连不上"，实际发生在完全不同的阶段。前者是传输层没走完，客户端根本没拿到有效响应；后者是请求已经发出去、服务端也回了东西，只是回的不是成功状态。这个区别决定了你要不要去看请求内容本身。

API ERROR后面通常会跟一个状态码或者一段服务端返回的错误描述。这一步非常关键，很多人只看到"API ERROR"四个字母就开始重装 CLI，其实往下几行就有更具体的信息。常见的情况有：请求体太大被拒（上下文贴了太多文件）、短时间请求频率过高触发了限流、模型名称或参数不被接受、鉴权信息失效。这些都属于"请求本身有问题"，跟网络半毛钱关系没有，重装一百遍也不会好。

Unable to connect则完全在网络与传输这一层。它说明客户端在建立连接、发送请求体、等待响应这几个动作中的某一个环节被打断了。我个人的经验是，如果报错出现得非常快（一两秒内），多半是连接复用出了问题或者 TLS 握手失败；如果是等了一段时间（十几秒、几十秒）才报，那更像是某个环节的超时阈值到了，或者请求体写到一半被掐。

1.3 为什么交互式 CLI 比 curl 更容易撞上断连

一个很反直觉的现象：同一个端点在浏览器和 curl 里访问正常，偏偏 Claude Code 一直报 ECONNRESET。原因在于这类交互式 CLI 的请求特征和普通 HTTP 请求差别很大。

第一，请求体大。一次对话请求里带着完整的上下文，动辄几万 token，序列化之后可能是几百 KB 甚至上 MB 的 JSON。大请求体意味着更长的上传时间，也意味着更容易在传输过程中被中间设备的策略拦下。第二，会话长。交互式使用是连续的，一次任务可能产生几十次请求，中间夹杂着用户思考、看代码、改需求的间隔，这就产生了大量的"空闲期"，而空闲期正是连接被中间设备回收的高发时段。第三，连接复用。CLI 为了省掉反复握手的开销，通常会保持长连接并复用，一旦池子里的某条连接被对端悄悄关掉了，客户端并不一定立刻知道，下一次直接拿这条"僵尸连接"发请求，收到的就是 RST，报错就成了 ECONNRESET。

这三条叠加起来，就解释了为什么"浏览器能打开、CLI 却报错"。浏览器有更激进的连接管理策略和更完善的重试，而 CLI 的行为取决于它底层用的 HTTP 客户端配置。

2. 请求穿过的五道关卡，以及各自的断连习惯

2.1 从敲下回车到首字节返回的完整链路

把一次请求拆开看，它至少要穿过五道关卡：本机应用层（Node 运行时与 HTTP 客户端）→ 本机操作系统网络栈（含 DNS 解析）→ 本机所在网络的出口设备 → 中间传输链路 → 目标服务前面的接入层（负载均衡、网关）→ 应用服务本身。任何一道关卡做了"主动关闭"的动作，客户端看到的现象都可能是ECONNRESET。

这个拆法的价值在于：它能帮你判断"该在自己机器上折腾，还是该去找网络环境的管理方"。我遇到过的情况里，本机层面的问题占了大概六成（配置残留、证书、DNS、Node 版本），出口与中间设备占三成，剩下的一成才是服务端本身。所以排查顺序一定是"从近到远"，而不是一上来就怀疑远端。

有一个很实用的判断方法：准备一个极简的连通性测试，用同样的运行时、同样的配置发一个最小请求。如果最小请求能通、大请求不通，问题在体积和超时；如果最小请求也不通，问题在连接建立或配置。这一步能把排查空间砍掉一半。

2.2 空闲连接回收：最常见也最容易被误判的一种

这是我见过最高频、也最容易被误判成"服务不稳定"的一类 ECONNRESET。表现特征非常明显：连续对话时一切正常，去开了个会回来，或者切到别的窗口看了会儿文档，回来发第一条消息，立刻报错，第二次发就正常了。

原因就在于中间设备和接入层的空闲连接回收策略。为了节省资源，链路上的设备会记录每条连接的最后活跃时间，超过一定时间没有数据往来就主动关闭。问题在于，关闭动作有时只发给了服务端而没同步到客户端，或者客户端收到了 FIN 但没及时清理连接池。于是客户端认为这条连接还活着，直接拿来发新请求，服务端那边已经没这条连接了，回的当然是 RST。

针对这一类，最直接的缓解手段是缩短客户端的连接复用时间，让它别把连接留太久。如果你是用脚本调同类 API，Node 的undici可以这样配——把keepAliveTimeout设得比链路上的空闲回收阈值更短，让客户端主动先放弃旧连接，比被动收到 RST 优雅得多：

import { Agent, setGlobalDispatcher } from 'undici'; setGlobalDispatcher(new Agent({ keepAliveTimeout: 10_000, // 客户端 10 秒没动静就自己关，抢在中间设备之前 keepAliveMaxTimeout: 30_000, // 单条连接最长存活时间 connect: { timeout: 15_000 }, // 建连超时 headersTimeout: 60_000, // 等响应头超时 bodyTimeout: 120_000, // 等响应体超时 }));

这段配置的核心思路是"主动比被动好"。客户端自己关连接是干净的 FIN，服务端不会产生异常；等服务端或中间设备来关，客户端拿到的就是 RST，就变成了报错。用 CLI 的话不能直接改这段代码，但可以理解这个机制，从而知道"空闲后首次请求失败"根本不是硬件问题、也不是服务问题，而是连接生命周期管理的问题。

2.3 请求体体积与上下文长度带来的隐性压力

第二类高频原因跟体积有关。Claude Code 的工作方式决定了请求体天然偏大：它会把项目结构、相关文件内容、对话历史一起打包发出去。当你让它在多文件之间跳转分析、或者把几百行日志贴进去让它找问题时，请求体可能瞬间涨到几 MB。

体积带来两个后果。一是上传耗时变长，整个请求处于"传输中"状态的时间窗口变宽，撞上中间设备策略的概率上升。二是很多接入层对单请求体大小有硬性上限，超了之后不是返回一个漂亮的 413，而是在读请求体的过程中直接断连——客户端这时看到的就是 ECONNRESET，而且往往发生在"等了十几秒之后"，很容易被误判成服务端处理慢。

我在实践中总结出一个很粗糙但好用的经验值：单次请求携带的文件内容控制在合理范围内，遇到需要分析大量代码的场景，先用目录级概览让模型定位到具体文件，再分批把文件内容送进去。这不是妥协，反而是更高效的工作方式——把一次巨型请求拆成几次小请求，既降低了断连概率，也让模型的注意力更集中，输出质量往往更好。

3. 一套可复现的四层排查链路

3.1 第一层：用最小请求区分"出不去"和"回不来"

排查的第一步永远是做减法。不要在一个复杂的交互场景里调问题，先退到最小可复现单元。我的做法是在一个干净目录下，用最短的提示词发一次请求，把所有可能干扰的因素（项目上下文、历史会话、自定义配置）全部排除。

具体动作是：切到一个空目录，运行一次最简单的单轮对话。如果这一步就报错，说明问题跟上下文无关，直接进入配置和链路排查。如果这一步正常，那就逐项加回变量——先加项目上下文，再加长历史，再加大文件，每次只加一个，直到复现。这个"二分加变量"的过程看起来笨，但它是唯一能确定因果关系的方法。

还有一个小技巧：把claude --version和node -v的输出先记下来。Node 版本对 HTTP 客户端行为影响很大，Node 18 早期版本的fetch实现（基于 undici）在 keep-alive 和超时处理上有过若干已知问题，版本太旧或者太新（比如某些奇数版本）都可能踩到边缘 case。把版本信息固定下来，至少能保证你后面所有的对比测试是在同一个基线上做的。

3.2 第二层：把环境变量和配置文件的隐性残留清一遍

这一层是我踩坑最多的地方。CLI 工具的行为高度依赖环境变量和用户级配置文件，而这些地方最容易留下的就是"历史残留"——几个月前配过的东西，早就没人维护了，但每次启动都在生效，悄悄地改变着请求的走向。

排查方法是把当前 shell 里所有相关的环境变量列出来看一遍。重点看三类：一是 API 端点相关的（有没有被改成指向某个已经不存在的地址），二是超时与重试相关的（有没有被设成一个很小的值），三是证书与 TLS 相关的（有没有指向一个过期的证书文件）。用env | grep -i配合关键词过滤，比一个一个猜要快得多。

配置文件也要看。Claude Code 的用户级配置一般在用户主目录下的隐藏目录里，项目级配置可能在项目根目录。这两处可能同时存在配置，且优先级不同。我遇到过的情况是：项目目录里留着一份早期调试时写的配置，指向了一个测试用的端点，后来项目被复制到别的地方，配置文件跟着走了，于是新的环境里一直在往错误地址发请求。这种问题不看配置文件是绝对查不出来的。

清理的时候遵循一个原则：先备份再删，一次只改一处。把所有可疑配置一次性清空，虽然大概率能好，但你永远不知道是哪一项起的效，下次再遇到还是不会查。改成一次动一个，改完立刻测，虽然慢一点，但能积累出真正有用的认知。

3.3 第三层：DNS、系统时间与 TLS 握手的三个硬条件

过了配置这一关，往下就是三个"硬条件"，任何一个不满足都会导致握手失败或者连上就断。

第一个是 DNS。检查方法很直接：确认域名解析出来的地址是不是你预期的。在受管网络环境里，内网 DNS 和公网 DNS 的解析结果经常不一样，而 CLI 用的是系统解析器，跟你在浏览器里看到的可能不同。如果解析结果指向了一个不通的地址，表现出来可能是超时，也可能是在某个中间设备那里被直接重置。

第二个是系统时间。这个原因听起来很荒谬，但 TLS 证书校验依赖时间戳，系统时间偏差过大（比如虚拟机休眠后时间没同步、或者时区配置错了导致偏差几小时），握手阶段就会失败。有些实现下表现为证书错误，有些实现下就表现为连接被重置。检查一下系统时间跟标准时间的偏差，几秒钟的事，但能排掉一大类玄学问题。

第三个是证书链。很多受管网络环境会在出口做 TLS 检查，意味着你实际握手的是中间设备而不是目标服务，它出示的证书由企业自己的根证书签发。这时候需要在本地信任这个根证书，Node 运行时可以通过NODE_EXTRA_CA_CERTS指定：

# 指向企业根证书（PEM 格式），仅对当前 shell 生效 export NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem # 验证一下 Node 是否真的读到了 node -e "console.log(process.env.NODE_EXTRA_CA_CERTS)"

注意：网上有些"偏方"会建议关掉证书校验（把NODE_TLS_REJECT_UNAUTHORIZED设为0）。这个做法等于把传输层的身份验证完全放弃，任何中间设备都可以冒充目标服务，风险极高。正确的做法是把该信任的根证书装进信任链，而不是把门拆了。

3.4 第四层：出口设备与中间节点的会话裁剪

如果前三层都干净，问题大概率在出口这一侧。这一层的典型特征是"间歇性"——不是每次都失败，而是有规律地失败。比如每天早上第一次用必失败，或者每连续对话超过二十分钟必失败一次。

判断方法看时间规律。记录下每次失败的时间点和上一次成功请求的时间点，算一下间隔。如果间隔固定在某个值附近（比如 60 秒、300 秒），那基本可以确定是某处设了固定的空闲回收或会话存活上限。这种规律性问题是最好解决的，因为你知道阈值在哪，只要让客户端的行为跑在阈值之内就行。

另一个特征是"特定操作必失败"。比如每次贴超过某个大小的文件就断，每次让模型读取某个特定目录就断。这说明中间设备在做内容层面的策略，可能跟请求体大小、请求频率或者请求的路径有关。这种情况下把操作拆小、把频率降下来，基本都能绕过。

需要强调的是，这一层的问题往往不在你能直接控制的范围内。你能做的是让客户端的行为更"温和"：减少并发、拉长间隔、缩小请求体、缩短连接复用时间。这些调整不会让链路变得更好，但能让你的请求更不容易撞在策略的枪口上。

3.5 把证据钉死：日志、版本与诊断命令

排查过程中最忌讳的就是"凭感觉改"，改完好了也不知道为什么好，下次再犯还是不会查。所以每一步都要留下证据。

Claude Code 提供了诊断入口，/doctor会检查安装完整性、版本、配置状态等基础信息，是排查的第一站。如果 CLI 支持详细日志开关（不同版本可能是--debug参数或者对应的环境变量），一定要打开，把完整请求链路打出来。日志里能看到的关键信息包括：实际请求的端点地址、DNS 解析结果、连接建立耗时、请求体大小、失败时的具体错误码和堆栈。有了这些，你能明确区分"根本没发出去"和"发出去了但没回来"。

我个人习惯把每次出问题的现场信息记成一个小卡片，格式固定：时间、CLI 版本、Node 版本、失败操作、报错原文、是否可复现、重试后是否成功。积累十几条之后，规律自己就浮出来了。这个习惯帮我定位过好几次那种"只在特定时段出现"的问题，光靠当场调试是查不出来的。

4. 让长请求不再被中途截断的参数与工程手段

4.1 超时与重试的取值逻辑

超时参数的设置有一个常见的误区：认为设得越大越安全。实际上超时设得过大反而有害——请求被中间设备掐断之后，客户端还会傻等很久才报错，用户体验极差；而且超时太久会占着连接不放，进一步加剧连接池耗尽的问题。

合理的取值逻辑是"分层设置、逐层递增"。建连超时应该最短，因为 TCP 握手正常情况下是毫秒级的事，给 10 到 15 秒已经很宽容了；等响应头的超时要长一些，因为服务端要做推理，首字节返回可能需要几秒到几十秒；等响应体的超时要最长，因为流式输出可能持续很久。三层的比例大概是 1 : 4 : 8。

重试策略则要区分错误类型。ECONNRESET这类传输层错误，重试是合理的，因为下一次大概率会走一条新连接。API ERROR里的 4xx 类错误（比如请求体过大、参数不合法）重试毫无意义，只会浪费时间。限流类的错误要退避重试，而且退避时间要递增。判断错的类型再重试，是自动化脚本里最容易忽略的一环。

4.2 上下文瘦身：把一次大请求拆成几次小请求

这是我用得最多、效果最直接的一招。很多人习惯把整个需求一次性丢进去——"帮我看看这个项目有什么问题"，然后让工具自己去翻。这种用法下请求体巨大、耗时长、断连概率高，而且模型的输出往往也比较泛。

改成两段式：第一段只让模型看目录结构和关键文件清单，让它自己指出哪些文件需要细看；第二段只把那几个文件的内容送进去。这样单次请求的体积可能下降一个数量级，断连概率大幅降低，而输出质量反而更高，因为模型的注意力集中在了真正相关的代码上。

对于确实需要大段输入的场景（比如让它分析一大段日志），也可以切块。先送前一部分，让它给出初步结论，再送后一部分，让它基于已有结论继续。这种"分段落"的方式模拟了人处理大信息量的过程，不仅降低了传输压力，也让每一轮的输出更容易验证。

4.3 连接复用的取舍与 Node 侧参数

如果你的用法是通过脚本调用同类 API（比如做批量处理、自动化流水线），那么连接复用策略就需要认真设计。复用的好处是省掉握手开销，坏处是遇到"僵尸连接"时会直接失败。这是一个明确的权衡。

我的建议是：低频调用（间隔几十秒以上）干脆不复用，每次新建连接，代价是几十毫秒的握手，换来的是完全避开空闲回收问题。高频连续调用（间隔几秒）则复用，但要把keepAliveTimeout设得比链路上的空闲阈值更小，主动关比被动断好。具体到 Node 环境，undici的Agent提供了这几个可调参数，前面第 2.2 节已经给过配置示例，核心就是三个值：keepAliveTimeout控制空闲多久关、keepAliveMaxTimeout控制单连接最长寿命、connect.timeout控制建连超时。

还有一个容易被忽略的点：连接池大小。默认情况下池子可能有若干条并发连接，如果其中一条变成了僵尸，后续请求可能还会被分配到它上面。可以在错误处理里加一个逻辑：捕获ECONNRESET之后，主动销毁当前连接池，让下一次请求全新建立。这样虽然粗暴，但在排查阶段非常有效，能立刻验证"死连接"这个假设。

4.4 用一个守护脚本把重试自动化

对于必须长时间跑的任务，最实用的做法是外面套一层重试。不是在代码里改，而是用一个 shell 脚本把 CLI 包起来，识别出可重试的错误就自动重来。这样既不侵入工具本身，又能显著提高长任务的完成率：

#!/usr/bin/env bash # run-claude.sh —— 带可重试错误识别的包装脚本 set -u MAX_RETRY=5 attempt=1 while [ "$attempt" -le "$MAX_RETRY" ]; do output=$(claude -p "$@" 2>&1) status=$? if [ "$status" -eq 0 ]; then printf '%s\n' "$output" exit 0 fi # 命中传输层断连类错误才重试 if printf '%s' "$output" | grep -qE 'ECONNRESET|Unable to connect to API'; then wait=$(( attempt * 5 )) echo "[warn] 第 ${attempt} 次失败命中可重试错误，${wait}s 后重试" >&2 sleep "$wait" attempt=$(( attempt + 1 )) continue fi # 其他错误（如参数错误、鉴权失败）直接透传，不做无意义重试 printf '%s\n' "$output" exit "$status" done echo "[error] 连续 ${MAX_RETRY} 次失败，请人工介入" >&2 exit 1

这段脚本有两个设计要点值得说。一是只对特定错误重试，用grep -qE做白名单匹配，其他错误直接透传退出码。这个设计避免了"参数写错了还傻重试五次"的尴尬。二是退避时间递增，attempt * 5让间隔从 5 秒逐步涨到 25 秒，给链路一个缓冲期。如果是限流导致的失败，递增退避几乎是唯一有效的策略。

提示：把2>&1保留住非常重要。CLI 的错误信息有时走 stderr 有时走 stdout，只抓一个会漏掉关键判断依据，导致脚本误判成功。

5. 几个反直觉的案例与一页纸应急清单

5.1 三个反直觉的真实案例

案例一：换了个工作目录就好了。某次排查，所有配置都干净、网络也正常，但在特定项目目录下必报错。最后发现是那个目录里有一份遗留的项目级配置，指向了一个早期测试用的端点地址。因为项目是从别处复制过来的，配置文件跟着一起过来了，谁也没注意到。这类问题的教训是：排错时一定要在"干净目录"里做对照实验，否则你无法确定问题是环境级还是项目级。

案例二：时间同步问题伪装成网络问题。一台长期休眠的开发机，唤醒后立刻报 ECONNRESET。各种网络检查都正常，最后发现是系统时间落后了将近半小时。TLS 校验对时间敏感，偏差过大时握手会在某个环节失败，而失败的表现形式在客户端看来就是连接被重置。这个案例告诉我，遇到"什么都对但就是不通"的情况，先看一眼系统时间，成本极低。

案例三：请求体太大，报错却长得像网络问题。一次让工具分析大量的运行日志，每次都断，重试也没用。后来把日志切成三段分别处理，一次都没断。原因不是网络差，而是单次请求体超过了链路上某处的限制，在传输过程中被直接切断。这类问题的识别特征是"小请求永远成功、大请求永远失败"，跟时间无关，跟内容大小强相关。

5.2 受管网络环境下的注意事项

在单位网络里用这类工具，有几个点需要提前确认，能省掉大量来回折腾的时间。

首先确认本地信任的根证书清单。如果有中间设备做 TLS 检查，它的根证书必须被本地运行时信任，Node 环境要用NODE_EXTRA_CA_CERTS显式指定。这件事最好在第一次使用前就配好，不要等到报错了才查。

其次确认 DNS 解析结果。受管环境里内网 DNS 和公网 DNS 的解析可能完全不同，如果发现解析结果不符合预期，需要跟网络管理方确认正确的解析配置。这一步不要自己瞎改hosts文件，改错了影响面更大。

第三，注意请求频率。共享出口环境下，短时间高频请求容易触发整体限流，表现出来就是一阵一阵的失败。批量任务一定要加间隔，宁可跑得慢一点，也不要一次性把请求打满。

最后，所有配置变更都要留记录。环境变量改了哪个、证书换成了哪个路径、配置文件动了哪一行，写在你自己的笔记里。这类问题复发率不低，有记录的话第二次处理只要五分钟。

5.3 一页纸应急清单

真出问题的时候，人容易慌，所以我给自己整理了一份从上到下照做的清单，按顺序走一遍，八成问题能定位：

1. 记下报错原文的完整几行，尤其是括号里的错误码，不要只看第一行。
2. 在空目录下用最简提示词发一次请求，确认是否与环境无关。
3. 检查claude --version与node -v，记下来作为基线。
4. 列出当前 shell 里所有相关环境变量，看有无指向失效地址的残留。
5. 检查用户级与项目级配置文件，确认没有历史遗留的错误端点。
6. 核对系统时间偏差，超过几分钟就要处理。
7. 确认自定义根证书路径存在且被正确加载。
8. 观察失败的时间规律，判断是否与空闲时长相关。
9. 换一个小请求测试，判断是否与请求体体积相关。
10. 打开详细日志，看请求到底发到了哪个地址、卡在哪一步。
11. 用外面套重试脚本的方式跑一次长任务，看能否绕过。
12. 以上都过一遍仍然失败，再考虑把完整现场信息整理后反馈。

这份清单的价值不在于每一步都多高明，而在于它强制你按"从近到远、从简到繁"的顺序走，避免一上来就做最复杂的操作。

最后分享一个我在长期使用里形成的习惯：把"第一次失败"和"第二次失败"严格区分开。第一次失败时不要急着改配置，先原样重试一次，观察是否自愈。如果自愈，那大概率是空闲连接或瞬时抖动，记一笔就行，不用动任何东西；如果连续两次都失败且错误码一致，再按上面的清单开始排查。这个习惯帮我避免了无数次"为了修一个本来会自己好的问题，把好好的配置改坏了"的情况。工具和人一样，偶尔打个嗝很正常，重要的是分清楚打嗝和生病。