"API Error: Stream idle timeout - partial response received"：怎么修

在一条长回答进行到一半时，CLI 突然停止输出，并返回：

API Error: Stream idle timeout - partial response received

会话仍然开着，历史记录也没丢，但这一轮就到这里结束了。错误来自 CLI 本身，而不是你的账号：流式看门狗因为字节长时间没有到达而放弃了这条响应。它在不同场景下出现，对应不同的修法，本文逐一拆开。

"Stream idle timeout - partial response received" 是什么意思？

意思是响应已经开始，然后被从中间切断。最初的字节到达了，流也打开了，但在某个 chunk 之后，连接进入静默，直到看门狗触发并中止这一轮。

它和 No response from API 不是一回事，后者是首字节之前的等待。这里响应已经在进行中。你失去的是正在生成的那一段，而不是整段对话：你的消息、已读取的文件和已执行的工具都还在会话里。

为什么响应会在中途被切断？

三类原因覆盖了几乎全部反馈，每一类需要不同的修法。动手改配置之前，先判断你属于哪一种。

原因	如何辨认	解决办法
提供方或到提供方的链路静默	长轮次被切断，有时全部被切断	调大看门狗阈值
代理或网关对响应做缓冲	在 VPN、网关或 ANTHROPIC_BASE_URL 后面必然切断	绕过代理测试，调整重试时限
CLI 自身的 keep-alive 锁死	会话越跑越差，重启就好	重启会话或回退版本

我调大了 API_TIMEOUT_MS，却没有任何变化，为什么？

因为 API_TIMEOUT_MS 不是流式响应的上限。更新日志写得很清楚：当 API 没有返回响应头时，重试最多会等到 API_TIMEOUT_MS，它的默认值是 10 分钟。这是一个等待答复的时限，而不是衡量 chunk 之间静默多久的计时器。

看到 idle timeout 就去调这个数字的人，会继续撞在同一个看门狗上，因为触发的是另一个计时器。

哪个变量控制流式看门狗？

是 CLAUDE_STREAM_IDLE_TIMEOUT_MS，它设置流式空闲看门狗的阈值，默认是 90 秒。当这个窗口内没有任何字节到达，这一轮就会被中止，你看到的就是 partial response 消息。

变量	控制什么	默认值
CLAUDE_STREAM_IDLE_TIMEOUT_MS	流式空闲看门狗的阈值	90 秒
API_TIMEOUT_MS	重试等待一个没有响应头的答复多久	10 分钟
API_FORCE_IDLE_TIMEOUT	在 Vertex 和 Foundry 上默认恢复的 5 分钟空闲超时	在这两个提供方上生效；0 可关闭
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK	流式失败时关闭非流式回退	关闭

注意每一个的作用范围：CLAUDE_STREAM_IDLE_TIMEOUT_MS 是通用的流静默看门狗，而 API_FORCE_IDLE_TIMEOUT 动的是 Vertex 和 Foundry 专属的超时。如果你不在这两个提供方上，第二个变量就不是你的抓手。

只对当前会话生效，打开 CLI 之前先导出。单位是毫秒，所以 180000 就是三分钟：

export CLAUDE_STREAM_IDLE_TIMEOUT_MS=180000
claude

要对所有会话生效，把它写进 ~/.claude/settings.json 的 env 块：

{
  "env": {
    "CLAUDE_STREAM_IDLE_TIMEOUT_MS": "180000"
  }
}

PowerShell 里的写法是 $env:CLAUDE_STREAM_IDLE_TIMEOUT_MS = "180000"。保存后运行 /status，查看 Setting sources 这一行，确认 CLI 是否加载了这个文件。

为什么长会话会越跑越差？

连接池里有一个加重因素。更新日志记录了这个改动：在遇到陈旧连接后会关闭 keep-alive，好让重试打开一个新 socket。而按 issue #100353 的说法，代码把这个开关关掉之后没有任何地方再打开它：进程从此每个请求都新开一条连接，直到重启。

作者在一个带大量子代理的编排会话里测到了效果，环境是 Linux，看门狗设为 60 秒：

场景	请求数	看门狗中止	40 秒以上的空档	400 续接错误
锁死生效时	约 1,725	131（7.6%）	66	101
在二进制里关掉锁死	约 2,190	0	0	2

这些数字来自那份反馈，不是我们的实测，issue 目前仍然开着。信号在日志里：用 --debug-file 运行，找以 Stale connection 开头、以 disabling keep-alive for retry 结尾的那一行。它出现之后，会话通常会一路变差，直到重启。

如果只是重启就解决，该怎么办？

如果日志里看到锁死，按成本从低到高有三条路：

1. 在第一次告警后就重启长会话。这也是 issue 作者的做法，它把停顿率降到零。
2. 回退到 issue 里描述的那次 keep-alive 改动之前的版本，那时这个触发还没生效。
3. 如果必须留在当前版本，关掉非流式回退，它是把一次停顿变成整段对话重发的元凶：

   export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1

第 3 条并不能修好锁死。它只是避开那笔昂贵的开销：按同一份反馈，每次停顿要重发 0.35 到 1.1 MB 的对话。

超过 5 分钟的请求也会出现这个错误吗？

那种情况下的限制是另一回事。2026-11-04 提交、2026-11-07 更新的一份反馈，用的是 CLI 2.1.317，描述的是通过 ANTHROPIC_BASE_URL 提供的本地大模型：任何超过 5 分钟的请求都会被中止，并伴随一串 Request timed out. Retrying，直到重试次数用尽。

在这个场景里，流式看门狗不是唯一的角色，作者本人也指出可能是运行时 HTTP 层的空闲超时。对一个每次回答都要超过 5 分钟的本地模型来说，实际做法是把任务拆小，或者等修复，而不是去调看门狗的变量。

怎么降低再次出现的概率？

• 把长轮次拆开。在一次轮次里要一份超大的计划，是反馈里反复出现的场景之一。
• 长任务之前先跑 /compact，让下一轮要撑住的上下文少一些。
• 错误持续出现时，去掉 VPN、代理或网关测试一次，和直连 API 做对比。
• 在自动化里优先用短的无头会话，批次之间重启。
• 长会话用 --debug-file 打开，好在你损失一下午之前先看到锁死。