APIMODELSAPIMODELS

Claude Code「Stream idle timeout」是什么意思、怎么解决

更新于 2026-11-19

TL;DR 一句话:流还开着,但数据不再到达,Claude Code 的空闲看门狗把它断掉了,并保留已经收到的部分(所以叫「partial response received」)。先升级 Claude Code,好几个版本专门修过这个报错;如果你的网络或代理经常长时间没数据,再调大 CLAUDE_STREAM_IDLE_TIMEOUT_MS。

模型页: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 也没用。

相关阅读

收录于
APIMODELS on Product HuntAPIMODELS featured on ToolifyAPIMODELS featured on There's An AI For That