Claude API 流式输出（SSE）实战指南：从打字机效果到 Agent 工具调用完整落地

很多人第一次接 Claude API，基本都从 messages.create() 开始：发请求、等返回、打印结果。刚开始做 Demo 没问题，但只要项目进入真实场景，很快就会发现这种模式根本撑不住。

聊天框会白屏十几秒，长文本生成经常超时，Agent 工具调用必须傻等整轮响应结束，Cursor 那种“边生成边输出”的体验完全做不出来。

真正到了生产环境，你会发现：Claude API 的核心能力，其实不是 messages.create()，而是 SSE 流式输出。

尤其是现在越来越多人开始做：

• Claude Code 工作流

• AI IDE

• Agent 框架

• RAG 问答系统

• AI 客服

• 自动代码修复

• 长文生成平台

这些场景里，不上流式基本等于不可用。

本文会完整讲清楚：

• Claude SSE 的事件结构

• Python / Node.js / cURL 三套可运行代码

• Tool Use 流式调用

• 前端打字机效果

• 断流重连

• Nginx / Cloudflare 反代避坑

• 国内环境如何稳定接入 Claude SSE

为什么 Claude API 必须使用流式输出

很多开发者会把流式理解成“体验优化”，但实际上，它已经属于工程层面的刚需。

最典型的问题就是长输出。

现在 Claude Opus 4.7 很多人拿来跑：

• AI 写作

• 长代码生成

• 项目分析

• 多文件重构

• Agent 推理

这种场景下，一次输出几千 tokens 很正常。如果走普通非流式请求，用户会面对：

白屏几十秒。

更麻烦的是，大量反向代理默认超时只有 60 秒。很多人看到的 524、504，本质上不是 Claude 崩了，而是：

你的代理层先断了。

流式模式最大的意义不是“更快结束”，而是：

更快出现首 token。

哪怕总耗时一样，只要 700ms 内能看到首字，用户感知就完全不同。

Cursor、Claude Code、Cherry Studio 之所以体验顺滑，本质上全靠 SSE。

Claude API 流式输出的核心结构

Claude 的流式协议底层走的是 SSE（Server-Sent Events）。很多人第一次解析会懵，因为它和 OpenAI 的 chunk 结构不一样。Claude SSE 最重要的不是代码，而是先理解事件结构。一次完整响应，本质上是一串连续事件。

最核心的几个：

• message_start

• content_block_start

• content_block_delta

• content_block_stop

• message_delta

• message_stop

其中真正决定你前端显示逻辑的，是：

content_block_delta

文本内容会不断以 delta 形式推送。而且 Claude 的 content block 不一定是 text。它还可能是：

• thinking

• tool_use

• tool_result

所以很多人第一次做 Agent 会踩坑。因为tool_use 的增量不是 text，而是 partial_json。

这个后面会重点讲。

国内开发者如何稳定接入 Claude SSE

这是现在很多人真正卡住的地方。

理论上官方 Anthropic API 支持流式没问题，但国内环境里实际会出现：

• 长连接断流

• npm 安装失败

• Claude Code 无法连接

• SSE 中途 reset

• Cloudflare 超时

• HTTP/2 异常断开

尤其流式输出对网络稳定性要求比普通 API 高很多。因为SSE 本质是长连接。如果网络不稳定，前端会频繁中断。所以现在很多开发者会直接换成兼容 Anthropic 协议的国内优化入口。

我自己最近在跑：

• Claude Code

• RooCode

• OpenHands

• Cursor Agent

• 长文本流式生成

时，用得比较稳定的是 ClaudeAPI 的 SSE 接入点。打开   ​ClaudeAPI.com，注册登录后进入控制台。在 API 令牌页面创建 Key，会得到一串 sk- 开头的字符串。

这里有三个必须注意的点：

这个 Key 只会显示一次，之后无法完整查看 很多 401 错误来自复制时多了空格 Key 一旦泄露，会直接被盗刷这一点在生产环境里非常关键。创建 Key 后，直接替换 base_url 即可。

流式接口入口：

base_url="https://gw.claudeapi.com"

这一点非常关键。因为很多人其实代码没问题，真正的问题是官方 SSE 长连接在国内网络下不稳定。

Python 流式输出（推荐方案）

Anthropic SDK 已经帮你封装好了 SSE 解析，所以 Python 是最简单的。安装 SDK：

pip install anthropic

最小流式示例：

import anthropic

client = anthropic.Anthropic(
    api_key="sk-你的ClaudeAPI密钥",
    base_url="https://gw.claudeapi.com"
)

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "写一篇关于 AI Agent 的技术博客"
        }
    ]
) as stream:

    for text in stream.text_stream:
        print(text, end="", flush=True)

    final_message = stream.get_final_message()

print(
    final_message.usage.input_tokens,
    final_message.usage.output_tokens
)

这里最关键的是：

stream.text_stream

它已经自动帮你过滤掉：

• thinking

• tool_use

• message_delta

只保留文本增量。如果你只是做聊天框，这种方式最省事。

Node.js 流式输出

Node.js 的 SDK 写法和 Python 很像。安装：

npm install @anthropic-ai/sdk

然后直接：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk-你的ClaudeAPI密钥",
  baseURL: "https://gw.claudeapi.com",
});

const stream = client.messages.stream({
  model: "claude-opus-4-7",
  max_tokens: 2048,
  messages: [
    {
      role: "user",
      content: "解释什么是 SSE 流式输出"
    }
  ]
});

for await (const event of stream) {
  if (
    event.type === "content_block_delta" &&
    event.delta.type === "text_delta"
  ) {
    process.stdout.write(event.delta.text);
  }
}

很多人第一次看到这里会觉得复杂。其实核心就一句Claude SSE 本质就是不断收到 delta。

cURL 调试 SSE（非常重要）

真正排查问题时，不要先怀疑 SDK。直接用 cURL 看原始事件流最快。

curl -N https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的ClaudeAPI密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model":"claude-opus-4-7",
    "stream":true,
    "max_tokens":1024,
    "messages":[
      {
        "role":"user",
        "content":"Hello"
      }
    ]
  }'

重点一定是：

-N

否则 cURL 默认会缓冲输出，你会误以为 SSE 没生效。

Tool Use 流式输出才是真正的大坑

很多人做 Agent 时，最大的坑都在这里。因为：

tool_use

返回的不是普通文本。工具参数会以：

partial_json

的形式一点点推送。错误写法：

json.loads(delta.partial_json)

这会直接报错。因为JSON 还没传完。正确方式一定是：

• 先字符串拼接

• content_block_stop 后再 parse

示例：

tool_inputs = {}

if event.delta.type == "input_json_delta":
    tool_inputs[event.index] += event.delta.partial_json

等：

content_block_stop

时再：

json.loads(...)

这是现在绝大多数 Agent 项目都会踩的坑。

前端打字机效果怎么做

很多人以为浏览器直接 EventSource 就行。但实际上：EventSource 不支持自定义 Header。也就是说：

API Key 没法传。

正确方式一般是前端 → 自己后端 → Claude API

由后端做代理转发 SSE。

Express 示例：

res.setHeader("Content-Type", "text/event-stream");
res.setHeader("Cache-Control", "no-cache");
res.setHeader("Connection", "keep-alive");

前端再用：

fetch + ReadableStream

持续读取 chunk。

这里还有个经典坑：

SSE 的：

\n\n

分隔符可能被 chunk 截断。

所以必须维护 buffer。

否则前端一定丢字。

SSE 生产环境最容易踩的几个坑

第一个坑是 Nginx 默认缓冲。

很多人明明开了 stream，但前端就是等几十秒才一起返回。

原因其实是：

proxy_buffering on;

必须关闭：

proxy_buffering off;

第二个坑是 Cloudflare。

很多人 CDN 默认缓存 SSE。

结果首 token 永远出不来。

第三个坑是移动网络断流。

尤其国内移动端切 WiFi / 4G 时，SSE 特别容易中断。

所以生产环境一定要做：

• 网络异常重试

• 上下文续写

• 增量恢复

否则用户体验会非常差。

为什么现在越来越多 AI IDE 都基于 SSE

因为真正的 AI 编程体验，本质上就是：

持续增量输出。

你会发现：

• Cursor

• Claude Code

• RooCode

• OpenHands

• Continue.dev

底层几乎都 heavily 依赖流式。

因为 Agent 的本质不是“一次回答”。

而是：

• 边思考

• 边调用工具

• 边生成内容

• 边更新状态

SSE 恰好就是最适合这种工作流的协议。

小结

很多人以为 Claude API 最核心的是模型能力，但真正开始做工程后会发现：

流式输出能力，才决定了产品体验。

尤其现在 AI 应用越来越 Agent 化之后：

• Tool Use

• 长上下文

• 多轮推理

• IDE 集成

• 实时生成

这些能力都高度依赖 SSE。

真正要记住的核心其实只有三件事：

第一，先理解 Claude 的事件结构，再写解析逻辑。

第二，Tool Use 的 partial_json 必须拼接后再解析。

第三，国内环境下做 SSE，一定优先考虑稳定长连接。

否则你会发现：

模型明明很强，但用户体验烂得像 2015 年的网页聊天室。