Claude Code --output-format json 与 stream-json 结构化输出怎么用:嵌进自动化脚本解析消息流

在无头脚本模式(claude -p)下,--output-format 支持 text、json 与 stream-json 三种输出格式。本文讲清完整返回体字段、NDJSON 逐行事件流解析以及搭配 jq 与 Python 的自动化写法。

NNathaniel bigo··原创首发·AI 辅助撰写
10 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Pro 账号

结论先说

  1. 仅限非交互打印模式生效:--output-format 必须配合 -p(或 --print)无头模式使用,可选值为 text(默认纯文本)、json 和 stream-json。
  2. 短任务等结果选 json:进程跑完后一次性输出单个 JSON 对象,内含 result(最终回复)、session_id、is_error、duration_ms 与费用统计,最适合用 jq 直接取值。
  3. 长任务盯进度选 stream-json:按换行符分隔(NDJSON)逐行实时吐出初始化、模型消息、工具调用与最终汇总事件;加上 --include-partial-messages 还能拿到逐字增量块。
  4. 自动续聊靠 session_id 串联:从首轮 json 输出里提取 session_id,下一条脚本命令用 claude -p -r "$SESSION_ID" 即可无缝继承上下文。
  5. 脚本配额与开通入口:批量自动化脚本对 5 小时与周度配额消耗较快;国内开发者可通过本站 Claude Code 订阅专页 或 5 倍额度的 Claude Max 升级服务 开通,轻量脚本测试也可选免密兑换的 Claude Pro iOS 卡密。

三种无头输出格式对比

图:本站根据 Claude Code 官方文档:CLI reference 整理的示意图

本文根据 Claude Code 官方文档《CLI reference》与《Run Claude Code programmatically》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。

适用于谁

  • 想在 Shell、Python 或 CI 流水线里调用 claude -p,并准确提取最终文本、session_id、耗时与费用的开发者;
  • 运行长任务时不想干等几分钟黑盒输出,需要实时监听工具调用进度与增量文本流的人;
  • 分不清 json、stream-json 与 --include-partial-messages 搭配关系的人。

一、text、json 与 stream-json 三种格式怎么选

在自动化脚本里直接抓默认 text 纯文本有两个痛点:一是拿不到本次运行的会话 ID 和耗时账单,二是长任务执行期间你不知道它是正在读文件还是卡住了。官方提供的三种格式分工如下:

格式参数输出形态写出时机典型下游消费方式
text(默认)人类可读纯文本全部执行完毕后一次性打印简单管道重定向生成 .md 或终端直看
json单个标准 JSON 对象全部执行完毕后一次性打印用 jq -r '.result' 取答案或取 session_id
stream-json每行一个 JSON(NDJSON)每发生一次消息或工具动作实时刷出一行Python / Node 逐行流式读取做进度条或日志审计

如果你只需要让模型严格按你给定的业务字段(如漏洞数组)返回 JSON,还应叠加 --json-schema;若想了解完整 CI 流水线接入,见 Claude Code 在 CI 里无头运行示例。

二、--output-format json 实战:提取结果与串联多轮会话

最稳妥的 Shell 批处理模式是先跑一轮 json 拿到结果和 session_id,需要追问时再按 ID 续跑:

bash
resp=$(claude -p "统计 src 目录下未捕获异常的异步函数" --output-format json)

# 提取模型最终文本回答与会话 ID
echo "$resp" | jq -r '.result'
sid=$(echo "$resp" | jq -r '.session_id')

# 基于同一上下文继续下一轮动作
claude -p -r "$sid" "给刚才列出的第一个函数补上 try/catch" --output-format json

返回的单体 JSON 中,最常用于监控告警的四个顶层字段是:

  • is_error:布尔值,脚本可据此判断本轮调用是否异常终止;
  • result:最终汇总文本字符串;
  • session_id:当前会话唯一标识,后续恢复历史用法可参考 Claude Code 查看与恢复历史会话;
  • total_cost_usd 与 duration_ms:便于记录单次构建任务的耗时与成本账单。
自动化脚本配额与账号提示:在本地批处理或定时巡检脚本里循环调用 claude -p 时,很容易在半小时内触及普通 Pro 账号的滚动窗口上限。日常自动化负载较高的开发者建议直接配置 Claude Max 会员升级 或在 Claude Pro 自助充值页 提前备好订阅,防止流水线跑到一半因限额中断。

三、--output-format stream-json 实战:逐行解析实时事件流

当单个重构或代码扫描任务要跑三五分钟时,stream-json 会按事件顺序逐行输出 NDJSON(注意新版本通常需同时传入 --verbose):

stream-json 实时事件流消费步骤

图:本站根据 Claude Code 官方文档:Run Claude Code programmatically 整理的示意图

bash
claude -p "检查当前分支改动并运行相关单测" \
  --output-format stream-json \
  --verbose \
  --include-partial-messages | while IFS= read -r line; do
    etype=$(echo "$line" | jq -r '.type // empty')
    echo "[事件类型] $etype"
done

逐行事件流主要包含四类记录:

  1. system(subtype: "init"):第一行刷出,带出当前工作目录、已加载工具列表、模型名称与 session_id;
  2. assistant:模型发出的推理文本块或发起的 tool_use(如准备读取哪个文件、执行哪条 Bash);
  3. user:工具执行完毕回传给模型的 tool_result;
  4. result:最后一行收尾事件,结构与单体 json 模式一致,代表整轮执行闭环。

如果你是在自定义前端面板里做打字机效果,加上 --include-partial-messages 即可收到细粒度的增量片段;若业务已经升级到用代码库直接编排智能体,也可以对比 Claude Agent SDK 流式输出与权限控制。平时想手动导出交互历史里的 .jsonl 文件结构做对比,见 Claude Code 导出会话与 .jsonl 记录说明。

常见问题

问:为什么直接敲 claude --output-format json 不带 -p 没有输出 JSON?

答:因为 --output-format 只对非交互打印模式生效。不加 -p 会进入全屏交互终端(TUI),该标志会被忽略或报错提示需搭配 --print。

问:用 Python subprocess 读 stream-json 为什么半天收不到一行?

答:排查两点:一是确认按命令行提示带上了 --verbose;二是在 Python 读取子进程标准输出时开启按行缓冲(bufsize=1, text=True),并用 for line in proc.stdout: 逐行迭代而不是 proc.communicate() 阻塞等待。

问:管道里跑自动化怎么避免卡在「是否允许修改文件」的交互确认?

答:无头模式下没有人工按键,若任务需要改文件或跑测试命令,必须通过 --allowedTools "Edit,Bash(npm test:*)" 显式放行白名单工具,否则工具调用会被拒绝。

问:国内团队没有外币卡,怎么开通跑自动化所需的订阅并开具报销发票?

答:可通过本站 Claude Code 订阅专页 或 AI 会员充值总览 选购,支持支付宝、微信支付与 AlipayHK,提供免交账号密码的卡密自助兑换,企业采购支持开具国内增值税发票。实时价格与售后边界以页面展示为准:订阅期内非违规掉订阅按剩余天数折退,风控封号不在质保范围。

相关教程

参考资料

  • Claude Code 官方文档:CLI reference — https://code.claude.com/docs/en/cli-reference
  • Claude Code 官方文档:Run Claude Code programmatically — https://code.claude.com/docs/en/headless

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~