Claude Code「Stream idle timeout」是什么意思、怎么解决
更新于 2026-11-19
模型页:Claude Opus 5.5 API —— 价格、规格与在线体验
这个报错有好几种写法。「API Error: Stream idle timeout - partial response received」是大家搜得最多的,也是 Claude Code GitHub 仓库里一个讨论很多、仍未关闭的 issue 的标题。现在的 Claude Code 文档把同一种情况写成「API Error: The response stopped arriving. The response above may be incomplete.」,另外还有一种「Stream idle timeout - no chunks received」,指的是流从头到尾没出过内容。
它们说的是一回事:连接还开着,但数据停下来的时间超过了看门狗允许的长度,Claude Code 宁可断掉也不一直挂着。这是客户端的计时器在触发,起因是流安静下来了,所以它常出现在模型长时间思考的时候,或者网络、代理不稳定的时候。
能切断安静流的四个计时器
| 计时器 | 什么时候触发 | 默认值 / 设置 |
|---|---|---|
| 首字节截止 | 请求发出后一直没收到响应头(直连 Anthropic API 和 Claude Platform on AWS) | CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS |
| 事件级看门狗 | 一直解析不到响应事件;收到的字节(包括保活 ping)也能在一段时间内重置它 | 300 秒;CLAUDE_STREAM_IDLE_TIMEOUT_MS |
| 字节级看门狗 | 线上一个字节都没到,保活 ping 也算字节(直连 API、Claude Platform on AWS 和网关连接) | 直连 API 上 180 秒;CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS |
| 响应体空闲超时 | 5 分钟没有任何字节,等响应头的时间也算(其他服务商) | 5 分钟;API_FORCE_IDLE_TIMEOUT |
怎么解决
1. 用 claude update 升级 Claude Code。 更新日志里多次修过这个报错,包括「在 Bedrock、Vertex 和网关上,空闲超时直接让请求失败、而不是恢复」的问题,以及「Mac 睡眠唤醒后请求报这个错」的问题。
2. 给安静的流多留时间。 把 CLAUDE_STREAM_IDLE_TIMEOUT_MS 调大,比如 600000(10 分钟)。低于 5 分钟的值会被提到 5 分钟,字节级看门狗最多 30 分钟。
3. 查一查你和 API 之间隔着什么。 公司代理、VPN 和一些 Wi-Fi 会断掉空闲连接。换个网络报错就消失,那原因就在这里。
4. 重跑这一轮。 Claude Code 会留住已收到的内容,让它接着写或重跑这一步。工具调用和 thinking 块没法只恢复一半,断在里面的那一轮要重来。
APIMODELS 怎么让长的 Claude 流不「安静」
大多数 stream idle timeout 发生在模型长时间思考、线上没有任何数据的时候。在 APIMODELS 上,Claude 的 /v1/messages 请求如果上游 30 秒内还没开始回答,我们先用 HTTP 200 把流打开,每 15 秒发一个 Anthropic 的 ping 事件,直到内容到达;之后流里一安静也会继续发 ping。Claude Code 文档写明,字节级看门狗把保活 ping 算作到达的字节,而且这个看门狗在网关连接上同样生效。所以长时间思考不会再被当成一条断掉的连接。
ping 救不了直接把连接断掉的网络;流开始之后才出的错,也还是会以流里的错误到达。用法是把 ANTHROPIC_BASE_URL 设成 https://api.apimodels.app、ANTHROPIC_AUTH_TOKEN 设成你的 APIMODELS key,完整步骤见下面的 Claude Code 接入指南。
调用示例
~/.claude/settings.json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.apimodels.app",
"ANTHROPIC_AUTH_TOKEN": "sk_...your_apimodels_key...",
"ANTHROPIC_MODEL": "claude-opus-5-5",
"CLAUDE_STREAM_IDLE_TIMEOUT_MS": "600000"
}
}cURL
curl https://api.apimodels.app/v1/messages \
-H "x-api-key: $APIMODELS_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Summarise this error log in three bullet points."}]
}'Python
import anthropic
# Same Anthropic SDK, pointed at APIMODELS. The SDK already retries 408/409/429/5xx
# with exponential backoff (twice by default); raise it for batch jobs.
client = anthropic.Anthropic(
base_url="https://api.apimodels.app",
api_key="sk_...your_apimodels_key...",
max_retries=4,
timeout=600,
)
try:
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Summarise this error log in three bullet points."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
except anthropic.APIStatusError as e:
# e.status_code: 429 / 500 / 529 ...; the body carries error.type and a request id
print("failed:", e.status_code, e.response.headers.get("request-id"), e.message)常见问题
「Stream idle timeout - partial response received」是什么意思?
流还开着,但数据停下来的时间超过了 Claude Code 空闲看门狗允许的长度,于是 Claude Code 把它断掉,保留已经到达的那部分。现在的文档把同一种情况写成「The response stopped arriving」。这是客户端计时器对安静的流做出的反应。
Claude Code 的 stream idle timeout 怎么解决?
先跑 claude update,好几个版本修过这个报错。然后调大 CLAUDE_STREAM_IDLE_TIMEOUT_MS(低于 5 分钟会被提到 5 分钟,字节级看门狗最多 30 分钟),检查会断开空闲连接的代理或 VPN,再重跑这一轮。
CLAUDE_STREAM_IDLE_TIMEOUT_MS 是什么?
这是 Claude Code 的环境变量,单位毫秒,决定一个流可以安静多久,超过就会被事件级和字节级看门狗切断。低于 5 分钟的值会被提到 5 分钟,字节级看门狗最多 30 分钟。可以写在终端环境变量里,也可以写在 ~/.claude/settings.json 的 env 里。
保活 ping 能防住 stream idle timeout 吗?
能防住字节级看门狗,Claude Code 文档写明它把保活 ping 算作到达的字节;对事件级看门狗,也能在一段时间内重置它。APIMODELS 在 Claude 流等待或安静时每 15 秒发一个 Anthropic ping。网络本身把连接断了的话,ping 也没用。
