結論先說
- 僅限非交互打印模式生效:
--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 條評論
還沒有評論,來搶沙發~