目录
在 Claude Code 里干活时，回答写到一半突然停住，屏幕上出现这一行：
API Error: Connection closed mid-response. The response above may be incomplete.
它可能出现在写长报告的途中、读多个文件的途中，也可能出现在刚开启新会话之后。时机毫无规律，也没有可靠的复现方法。这不是你的提示词写得不好，而是传输层事件：承载流式响应的连接，在响应还在传输的过程中被关闭了。
而有一个事实比任何猜测都重要。这个错误的公开报告，绝大多数都来自 Claude Code 改变断连处理方式之前的版本。翻一遍官方 CHANGELOG 就会发现，从 2.1.179 开始，与连接和重试相关的修复一共有五项。本文只依据官方错误参考、官方 CHANGELOG，以及带抓包证据的真实 Issue，梳理①这条消息的准确含义 ②此刻该做什么 ③连接究竟断在哪一层 ④各版本之间发生了什么变化 ⑤开发者如何从设计上规避。
已经传过来的部分完好无损。官方给出的恢复方式是回复 continue。
2.1.198 解决了短暂网络中断导致整轮失败的问题，2.1.214 解决了重试复用已死连接的问题。
本机、链路（代理/VPN）、服务端——各层的应对方式不同。已有服务端主动关闭连接的报告。
1. 这条消息到底在说什么——官方定义
首先要明确：这段文字是 Claude Code 自己写出来的提示，并不是 API 返回的错误响应。Claude Code 官方错误参考对所有以「The response above may be incomplete.」结尾的消息给出了统一解释：当流式响应在 Claude 已经产生可见输出之后失败时，重新发送请求可能会把同样的工具调用执行两遍，因此 Claude Code 会保留已经传输的内容，并附上这条提示，而不是把整轮丢弃。
而句尾的措辞，就是原因的名字。该参考列出了三种。
官方解释只有一句：连接被断开了。流本身在正常工作，但承载它的连接关闭了。
官方说法是「流不再发送数据」。连接还活着，只是陷入沉默。不是断开，而是停滞。
流传输中途出现过载或 5xx。据官方文档，这种显示本身需要 v2.1.199 及以后版本；在此之前会丢弃已输出内容，把整轮当作错误。
一句话区分三者。被切断的是 Connection closed，陷入沉默的是 Response stalled，服务端摔倒的是 Server error。表面上都是「中途停住了」，但发生在传输的不同位置。
官方还明确了另一个值得知道的行为：如果同样的失败发生在任何可见输出之前，Claude Code 会重试请求，而不是就此收尾。换句话说，你能看到这条消息，恰恰说明此前已经有输出出现——重发有可能造成副作用重复执行，所以 Claude Code 才刻意没有自动重试。出现错误并不等于什么都没尝试过。
2. 第一件该做的事——内容并没有丢
先别慌着把同样的指令再发一遍，按下面的顺序确认。
如官方文档所说，什么都没有丢失。缺的多半只是最后几句话，或者最后一次工具调用。
continue官方错误参考明确给出的恢复步骤。让它从停下的地方继续，而不是从头再来。
若断在文件编辑或命令执行途中，可能已经执行了一部分。先用 git status 等看清实际状态再继续。
如果一次会话内出现多次，先确认版本再谈其他。这一块一直在被持续修复。
不要轻视 STEP 3。官方之所以写「重发可能把同样的工具调用执行两遍」，反过来说就是断开的那一刻，部分工具可能已经执行完毕。如果是在写文件、提交、部署的途中断掉，先看实际状态才是最短的恢复路径。
3. 为什么会断——连接被关闭的三个层次
只说「连接被断开」无从下手，所以要把关闭可能发生的位置拆开来看。已有的报告大致分为三层。
Wi-Fi 瞬断、移动网络切换、电脑从睡眠中唤醒。官方 CHANGELOG 里就有「机器从睡眠唤醒后流式请求失败」的修复（2.1.186），说明这一层确实存在。
有效对策：有线或稳定链路；长任务期间不要让机器休眠。
Claude API 官方错误文档明确写道，有些网络会在不定时长后断开空闲连接，并建议设置 TCP keep-alive。企业代理和 VPN 恰恰容易有这种行为。
有效对策：临时绕过代理／VPN，看是否还能复现。
有抓包层面的报告显示，连接是在流传输过程中被服务端关闭的（见下一节）。这种情况下，本机怎么调整都防不住。
有效对策：客户端侧的重试设计——这正是升级有效的原因。
事实上，GitHub Issue #69415（[BUG] API Error: Connection closed mid-response ==> frequent enough to make Claude Code unusable for any task，2026 年 6 月 18 日创建，本文撰写时仍为 open）的报告者给出的条件是：Windows 11／WSL2，没有企业防火墙也没有代理的直连环境，Claude Code 2.1.181。也就是说，其主张是在排除第 1、2 层之后依然会发生。该 Issue 带有 area:networking／platform:vscode／platform:wsl 标签。
同一位报告者还写道，在同一台机器、同一条网络上，其他 AI 助手（GitHub Copilot、Cursor 等）能把同样的任务跑完。不过这是报告者自己的对比，并非 Anthropic 对原因的认定，这一点需要区分清楚。
另有一份条件明显不同的报告。Issue #69336（occurs immediately in new context window，2026 年 6 月 18 日创建、open，Claude Code 2.1.173，Debian 13，自建的 Claude Agent SDK）报告称，上下文摘要（compact）跑完之后频率上升。它带有 area:agent-sdk／area:api／platform:linux 标签，并把开启全新对话描述为临时规避手段。Issue #69517（发生在 Claude Cowork，2026 年 6 月 19 日，macOS，2.1.183）已被作为重复问题关闭。
4. 抓包揭示的事实：服务端主动关闭
关于这类错误，目前最深入的一手调查是 Issue #67766（2026 年 6 月 12 日创建，仍为 open）。报告者在自己的环境里抓了包，并对十次发生做了交叉比对。
出处：GitHub Issue #67766 报告者公开的抓包与会话记录。这是单个用户环境下的实测，并非 Anthropic 的验证结果。
技术上最关键的一点是「关闭是有选择性的」。据该报告，当时连向同一目标的其他连接都保持存活，被关闭的只有正在执行请求的那个进程所持有的连接。同时运行的另外两个 claude 进程的连接毫发无损。如果是链路掉线，理应全部一起遭殃，而事实并非如此。
此外，十次中有四次观测到多个连接池中的连接被「成批」发送 FIN，还有三次发生在相邻分钟的第 54 秒（01:19:54／01:20:54／01:22:54 UTC）——报告者据此推测可能存在某种 60 秒周期的处理。
🟡 关于本节的确信度
Issue #67766 屏幕上显示的是「API Error: The socket connection was closed unexpectedly」，与本文这条消息措辞不同，不能断定是同一个缺陷。不过，就「流传输过程中连接被关闭」这一同层现象而言，它是目前唯一公开的抓包级证据，作为原因推测仍有参考价值。另外需要说明，截至本文撰写时，Anthropic 尚未就该报告公开任何说明。
5. 先看版本——修复的时间线
这是本文最有实用价值的部分。翻一遍 Claude Code 官方 CHANGELOG 就会发现，流传输中断连的处理一直在被持续改进。以下每一条都真实记载于 CHANGELOG。
流传输中断连时，已输出的部分开始被保留。此前只会抛出原始错误，而且转圈提示会卡在「running tool」。
流停滞时的提示改为「Waiting for API response · will retry in …」，并且触发条件由静默 10 秒改为 20 秒，短暂波动不再弹出警告。
修复了响应途中短暂网络中断导致整轮被中止的问题。ECONNRESET 这类临时性错误改为带退避的重试，而不是直接失败。
修复了流传输中途出现过载／服务端错误时丢弃已输出内容的问题。现在会保留已输出部分并附上「不完整」提示——前述 Server error mid-response 的显示正来源于此。
keep-alive 连接池改为在出现「陈旧连接」错误后停用，使重试改开新的 socket。这直接对应 #67766 指出的「被复用的连接遭到关闭」的结构。
把这条时间线，与开头那些报告所用的版本对照一下。
| 报告 | 报告时的版本 | 当时尚未包含的修复 |
|---|---|---|
| #69336 | 2.1.173 | 2.1.179／198／199／214 全部 |
| #69415 | 2.1.181 | 2.1.198／199／214（即重试改进与连接池修复） |
| #69517 | 2.1.183 | 2.1.198／199／214 |
三份报告都早于用重试吸收临时断连的 2.1.198。所以首先该确认的是自己的版本。
claude --version若低于 2.1.198，比起排查，先升级更快见效。本文撰写时 CHANGELOG 的最新版本是 2.1.220，上述修复均已包含在内。
但也不能说「升级就一定不再出现」。CHANGELOG 中并没有直接点名「Connection closed」的修复条目，上述都是相邻的连接处理改进。请把升级理解为性价比最高的第一步，而非根治的保证。
6. 更容易触发的条件
各份报告中反复出现、会抬高发生概率的因素如下。
读取多个大文件并生成结构化报告等，会让流长时间保持开启的任务（#69415）。
有报告称上下文摘要跑完之后频率上升（#69336）。摘要之后发送的请求往往会变大。
#67766 的实测中，被关闭的连接所承载的请求体为 1〜2.5 MB。作为参考，Messages API 的官方请求上限是 32 MB。
企业代理、VPN、跨境连接。正是官方文档提到「有些网络会断开空闲连接」的那一层。
官方 CHANGELOG 2.1.186 修复了「机器唤醒后流式请求失败」。长任务期间别让电脑睡过去。
#67766 中 171 次里有 87 次发生在距上次 API 通信不到 5 秒之内，仅用空闲断开无法解释。
7. 立刻处理——用户侧检查清单
从上往下、由低成本到高成本依次尝试即可。
| 顺序 | 做什么 | 目的 |
|---|---|---|
| 1 | 回复 continue | 官方给出的恢复步骤。利用已输出的内容从中断处继续。 |
| 2 | 执行 claude --version，版本旧就升级 | 让 2.1.198 的重试改进和 2.1.214 的连接池修复生效。最优先。 |
| 3 | 确认副作用（git status 等） | 看断开时工具是否已经执行了一部分，避免重复执行造成事故。 |
| 4 | 把任务拆小 | 缩短单次响应，减少流的暴露时间。把「读完所有文件再写报告」拆成几步。 |
| 5 | 临时关闭代理／VPN 再复现一次 | 排查第 2 层。关掉就不再出现，即可确定是链路问题。 |
| 6 | 关闭休眠与省电，改用有线 | 排查第 1 层。笔记本长时间跑任务时尤其重要。 |
| 7 | 换一个全新会话试试 | #69336 报告的临时规避手段。摘要之后频发的场景有时有效。 |
| 8 | 能复现就带信息去反馈 | 按官方 API 文档的建议附上 request_id（以 req_ 开头的标识符），调查会快得多。 |
绝对不要做的事。因为「连接老是断」就去关闭 TLS 校验（NODE_TLS_REJECT_UNAUTHORIZED=0 之类），既是在治另一种完全不同的症状，又等于放弃了通信安全，非常不可取。证书错误属于另一类错误，处理方式也不同。
8. 面向开发者——在 API/SDK 层面预防
如果你是在 Claude Agent SDK 或自建的 API 集成中被同类断连困扰，Claude API 官方错误文档给出了具体的设计指引。
官方建议「超过 10 分钟这类长请求，使用流式 Messages API 或 Message Batches API」。把大 max_tokens 用非流式发出去，是最容易被切断的形态。
官方明确指出，自行编写 API 集成时设置 TCP keep-alive 可减轻空闲断开的影响。官方 SDK 已默认设置。自己写 HTTP 客户端的话务必确认。
官方 SDK 对连接错误、限流、5xx 等临时性失败默认重试两次，采用指数退避并尊重 retry-after 头。次数可通过客户端选项调整或禁用。
官方点名的陷阱：SSE 下返回 200 之后仍可能发生错误，因此不会走常规 HTTP 错误处理路径。必须单独处理流传输中的错误事件。
Claude Code 自己在 2.1.179 和 2.1.199 就转向了这个方向。断开时保留已接收的块并请求后续，无论在成本还是副作用上都优于全部丢弃后重发。
Claude Code 在 2.1.214 改为「出现陈旧连接错误后停用 keep-alive 池，重试改开新 socket」。值得确认你的重试是不是抓着同一条已死的连接。
对于批处理这类「本来就不想依赖不间断连接」的工作负载，按官方推荐改用 Message Batches API 并以轮询取结果，能从结构上消除网络风险，而不只是缓解。
9. 与相似错误的区分方法
Claude Code 的通信类错误显示得很像，容易混淆。按「走到了哪一步」来区分最快。
| 消息 | 停在哪里 | 主要对策 |
|---|---|---|
| Connection closed mid-response（本文） | 已连上、响应也开始传输之后被切断 | continue／升级版本／排查链路 |
| Response stalled mid-stream | 连接还活着但陷入沉默 | 另有专文（注意与重复循环的连锁） |
| Server error mid-response | 流传输中服务端出现 5xx／过载 | 等一会儿再试。参见 529/500 一文 |
| Unable to connect / SSL certificate verification failed | 根本没连上 | 代理、企业 CA、防火墙。参见 连接错误一文 |
| Prompt is too long | 发送前就被拒绝（通信正常） | 削减上下文。参见专文 |
最大的分岔点，就是「屏幕上有没有出现过响应」。一个字都没出现，就怀疑连接本身（配置与链路）；已经出现了一部分，那就是连接成功过的证据，与其去改配置，不如按本文的排查步骤往下走。
10. 官方处理状况与尚未确定的部分
为避免误解，把「官方可确认的」和「不可确认的」分开列出。
- 该消息已正式记载于官方错误参考，含义是「连接被断开」
- 已传输的输出会被保留（有意为之的设计）
- 恢复步骤是回复
continue - 输出出现之前的失败会自动重试
- 断连相关修复分别在 2.1.179／198／199／214
- 服务端在流传输中发送 FIN（#67766 的实测，但显示消息不同）
- 可能存在 60 秒周期的清理处理（同一报告者的推测）
- compact 之后频发（#69336 的报告）
- 同等条件下其他 AI 助手不出问题（#69415 报告者的对比）
- Anthropic 对原因的官方说明（#69415／#69336／#67766 均无公开回复）
- 点名「Connection closed」的修复条目（CHANGELOG 中不存在该字符串）
- #69415、#69336、#67766 均仍为 open
简而言之，症状与对策已被官方文档化，但「为什么会断」的官方说明尚未给出。在这种局面下，与其追查原因，不如把运维习惯做实：把每一轮拆短、涉及副作用的操作边确认状态边推进、版本保持最新——这些做法的收益更确定。
常见问题
Q1. 出现「Connection closed mid-response」后，之前的输出会消失吗？
不会。正如官方错误参考明确写的那样，已经传输过来的内容会原样保留。Claude Code 之所以不重发而是附上提示，是因为重发有可能把同样的工具调用执行两遍。缺的多半只是最后几句话或最后一次工具调用。
Q2. 回复什么才能从中断处继续？
回复 continue。这是官方错误参考给出的恢复步骤。从头重新下指令，则有让已执行操作重复的风险。
Q3. token 会白白浪费吗？
已经生成的那部分是被消耗掉的。Issue #69336 的报告者也写道「消耗的 token 不会退回」。正因如此，用 continue 从中断处继续、而不是从头再来，在成本上同样重要。
Q4. 它和「Response stalled mid-stream」是一回事吗？
不是。按官方定义，Connection closed 是「连接被断开」，Response stalled 是「流不再发送数据」——断开与停滞是两回事。表面症状相似，但 stalled 一侧有与模型重复循环连锁发生的报告，处理方式也不同。详见Response stalled mid-stream 一文。
Q5. 是我的网络不好吗？
有这个可能，但未必只是如此。Issue #69415 的报告者是在没有代理也没有防火墙的直连环境下遇到的，而 Issue #67766 的抓包显示关闭是由服务端发起的。先临时绕过代理／VPN 看是否还能复现；若毫无变化，就可以判断不只是本机的问题。
Q6. 升级 Claude Code 就能解决吗？
这是最值得优先尝试的一步。官方 CHANGELOG 中，2.1.198 修复了「响应途中短暂网络中断导致整轮被中止」，2.1.214 改为「出现陈旧连接错误后停用 keep-alive 池，让重试开启新 socket」。报告集中的 2.1.173〜2.1.183 都早于这些版本。不过 CHANGELOG 中并无点名「Connection closed」的修复条目，因此升级是改善的可能性，而不是根治的保证。
Q7. 长任务下频发，有规避办法吗？
把任务拆小、让单次响应更短，是最可靠的做法。「读完多个大文件再写报告」这类一次性处理会让流长时间开着；仅仅把读取与撰写分开，暴露窗口就会缩短，撞上断连的概率随之下降。Issue #69336 中也有「开启新对话可临时规避」的报告。
Q8. 作为开发者，如何在自己的应用里预防？
Claude API 官方文档的指引很清楚：①长响应务必走流式（超过 10 分钟可考虑 Batches API）；②设置 TCP keep-alive（官方 SDK 已默认设置）；③SSE 下 200 之后仍可能来错误，须单独处理流中的错误事件；④断开时保留已接收内容并请求后续。联系支持时请附上 request_id。
Q9. 在 Claude Cowork 和 Agent SDK 里也遇到同样的错误。
同样的消息在那里也有报告。Issue #69517 是 Claude Cowork 上的报告（已作为重复关闭），#69336 则是经由自建 Claude Agent SDK 的报告。这是处理流式响应那一层的共通现象，因此思路不变：从中断处继续、保持版本最新、把重试设计好。
