它到底是什么

--output-format 用于控制 print 模式（-p / --print）下 Claude Code 响应的结构。它只在 print 模式中生效，交互模式下不适用。

接受三个值：

• text（默认）——纯文本输出
• json——一个结构化 JSON 对象，包含最终文本（result 字段）、session_id、total_cost_usd、按模型拆分的成本明细等元数据
• **`stream-json``——按行输出的 JSON（JSONL），每行一个事件对象，用于实时获取流式结果

用法

claude -p "query" --output-format json

获取结构化输出（按 JSON Schema 约束返回）时，搭配 --json-schema:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

此时响应仍包含 session_id、usage 等请求元数据，结构化结果放在 structured_output 字段中。

流式获取 token 级增量：

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

与其他 flag 的组合 / 互斥

• 必须搭配 -p / --print，官方文档将其归类为 print 模式下的选项（CLI reference 原文：“Specify output format for print mode”）。
• stream-json 常与 --verbose 搭配使用：官方文档指出 --prompt-suggestions（用于获取 prompt suggestions）需要同时搭配 --print、--output-format stream-json 和 --verbose 三个 flag 才会生效。
• stream-json + --include-partial-messages：开启逐 token 的 stream_event 增量，用于实时展示文本（需要 stream-json 格式）。
• stream-json + --include-hook-events：在流中附带 hook 生命周期事件（需要 stream-json 格式）。
• stream-json + --forward-subagent-text（或环境变量 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT）：让子代理（subagent）/派生 skill 的文本与思考块也进入主流，便于重建每个子代理的完整对话记录；此功能要求 Claude Code v2.1.211 及以上，嵌套子代理的消息要求 v2.1.219 及以上，更深层嵌套（forked skill 内再嵌套）要求 v2.1.275 及以上。
• json + --json-schema：让 json 格式的响应附带按 Schema 校验的 structured_output 字段。
• 与 --input-format（取值 text / stream-json）是两个独立方向的 flag:--output-format 控制响应怎么输出，--input-format 控制输入怎么被解析，二者可以独立选择、也可以同时使用（如管道式的 stream-json in / stream-json out）。

运行约束 / 限制

经典使用场景

• CI/CD 成本追踪：--output-format json 的响应带 total_cost_usd 与按模型拆分的成本明细，脚本可以直接消费，无需查看 usage 面板（该成本是客户端估算值，可能与实际账单有出入）。
• 用 jq 提取结果：

  claude -p "Summarize this project" --output-format json | jq -r '.result'
  

  复制
• 约束结构化输出：--output-format json --json-schema '...' 后用 jq 取 .structured_output，用于把 Claude 的输出直接接入下游程序而无需再做文本解析。
• 实时展示流式文本：

  claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
    jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
  

  复制
• 捕获 session_id 用于续接对话：

  session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
  claude -p "Continue that review" --resume "$session_id"
  

  复制

常见坑

• 只顾着加 stream-json 却漏加 --verbose：官方文档规定 --prompt-suggestions 必须同时搭配 --print、--output-format stream-json 与 --verbose 三个 flag，缺一不可。
• --json-schema 写错格式直接导致整个调用失败：v2.1.205 之后，非法 Schema 会让命令以错误退出而不是静默退化为纯文本，脚本里做 Schema 校验时要注意这个行为变化。
• 消费 stream-json 的下游太慢：老版本（v2.1.214 之前）进程退出等待队列排空的时间封顶只有约 2 秒，大响应结尾可能被截断；新版本封顶提高到 30 秒，但仍不是无限等待。

来源

• CLI reference
• Run Claude Code programmatically(headless)
• Agent SDK overview
• What is --output-format in Claude Code | ClaudeLog