结论先说
- 仅限非交互打印模式生效:
--output-format必须配合-p(或--print)无头模式使用,可选值为text(默认纯文本)、json和stream-json。 - 短任务等结果选
json:进程跑完后一次性输出单个 JSON 对象,内含result(最终回复)、session_id、is_error、duration_ms与费用统计,最适合用jq直接取值。 - 长任务盯进度选
stream-json:按换行符分隔(NDJSON)逐行实时吐出初始化、模型消息、工具调用与最终汇总事件;加上--include-partial-messages还能拿到逐字增量块。 - 自动续聊靠
session_id串联:从首轮json输出里提取session_id,下一条脚本命令用claude -p -r "$SESSION_ID"即可无缝继承上下文。 - 脚本配额与开通入口:批量自动化脚本对 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):

图:本站根据 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
逐行事件流主要包含四类记录:
system(subtype: "init"):第一行刷出,带出当前工作目录、已加载工具列表、模型名称与session_id;assistant:模型发出的推理文本块或发起的tool_use(如准备读取哪个文件、执行哪条 Bash);user:工具执行完毕回传给模型的tool_result;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 在 CI 里跑:从本机 claude -p 到 GitHub Actions
- Claude Code 怎么导出会话与 .jsonl 记录区别
- Claude Code 怎么看历史对话、恢复之前的会话
- Claude Agent SDK 流式输出与会话恢复怎么写
参考资料
- 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
0 条评论
还没有评论,来抢沙发~