11 - 非互動模式與腳本化
← 10-MCP與外部工具 | 00-Index | 下一篇 → 12-設定檔與CLI旗標速查
基本：-p
任何 claude 指令加上 -p（--print）就變成非互動：
claude -p "What does the auth module do?"- 成功 exit 0，失敗非零 → 腳本可以用 exit status 分支
- 傳了無效 flag → 錯誤印到 stderr，執行前就中止
- 執行中的失敗（例如沒登入）→ 當成結果印到 stdout
所有 CLI 選項 都能跟 -p 一起用。
--bare：腳本應該用的模式 ⭐
claude --bare -p "Summarize README.md" --allowedTools "Read"--bare 跳過自動探索：hooks、skills、plugins、MCP servers、auto memory、CLAUDE.md 全部不載入。啟動更快，而且每台機器結果一致。
⚠️ 重要副作用：bare mode 不讀 OAuth 憑證也不讀系統 keychain。要用 Anthropic API 就得設
ANTHROPIC_API_KEY，或在--settingsJSON 裡給apiKeyHelper。也就是說 bare mode 用不到你的 Claude Pro 訂閱登入。
Bare mode 下 Claude 有 Bash、讀檔、改檔工具。要載入其他東西用 flag：
| 要載入 | 用 |
|---|---|
| System prompt 補充 | --append-system-prompt / --append-system-prompt-file |
| 設定 | --settings <file-or-json> |
| MCP servers | --mcp-config <file-or-json> |
| 自訂 agent | --agents <json> |
| Plugin | --plugin-dir <path> / --plugin-url <url> |
📌 官方說
--bare是腳本和 SDK 呼叫的建議模式，未來會變成-p的預設。
Pipe 進去
非互動模式會讀 stdin：
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txtgit diff main --name-only | claude -p "review these changed files for security issues"tail -200 app.log | claude -p "if you see any anomalies, summarize them"⚠️ stdin 上限 10MB。超過會用非零狀態退出。更大的內容寫成檔案、在 prompt 裡提檔案路徑。
輸出格式
claude -p "query" --output-format text # 預設，純文字
claude -p "query" --output-format json # 結構化 JSON（含 result、session_id、metadata）
claude -p "query" --output-format stream-json # NDJSON 即時串流--output-format json 的 payload 含 total_cost_usd 和每個模型的成本細分——腳本可以自己追蹤花費。
用 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"]}'結果在 structured_output 欄位。用 jq 取：
claude -p "..." --output-format json | jq -r '.result'
claude -p "..." --output-format json --json-schema '...' | jq '.structured_output'⚠️ Schema 無效會直接錯誤退出。
format關鍵字（如"format": "email"）會被接受但只當註解，不做驗證。
串流
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages最後一行是 result 訊息，含最終文字、成本、session metadata。
只顯示串流文字：
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'自動核准工具
claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"比較精細的版本用權限規則語法：
claude -p "Look at my staged changes and create an appropriate commit" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"⚠️ 尾巴 * 前面那個空格很重要：Bash(git diff *) 只比對 git diff 開頭；Bash(git diff*) 會連 git diff-index 一起中。
或者設整個 session 的基準模式：
claude -p "Apply the lint fixes" --permission-mode acceptEdits
claude -p "..." --permission-mode dontAsk # 鎖死的 CI：只跑你 allow 過的接續對話
claude -p "Review this codebase for performance issues"
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue多條對話並行時，抓 session ID：
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"⚠️ 兩個指令要在同一個目錄跑——session ID 查詢是以目前專案目錄（和它的 git worktree）為範圍。
幾個實用的護欄 flag
| Flag | 作用 |
|---|---|
--max-turns N | 限制 agentic 輪數（print mode）。到上限會錯誤退出 |
--max-budget-usd 5.00 | 花超過就停（print mode）。subagent 的花費也算進去；到上限後再生 subagent 會以 Budget limit reached 失敗，並停掉還在跑的背景 subagent |
--no-session-persistence | 不存 session、不可 resume（print mode） |
--fallback-model sonnet,haiku | 主模型過載或不可用時依序 fallback |
--tools "Bash,Edit,Read" | 限制可用的內建工具（"" 全關、"default" 全開）。不影響 MCP 工具——要一起擋加 --disallowedTools "mcp__*" |
💡
--max-budget-usd對「不小心跑一整晚」是很便宜的保險。 CI 腳本裡建議一律加。
實用範例
當專案的 linter
package.json：
{
"scripts": {
"lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
}
}安全審查腳本
#!/usr/bin/env bash
# review.sh <PR-number>
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json給你 vault 的範例：批次盤點 frontmatter
#!/usr/bin/env bash
set -euo pipefail
for dir in "Nephrology(NEP)" "Cardiology(CV)" "Endocrinology(ENDO)"; do
claude --bare -p "掃描 '$dir' 底下所有 *_overview.md 的 YAML frontmatter，
列出缺少 modified 欄位、或 YAML 不合法的檔案。只回報，不要改檔。" \
--allowedTools "Read,Glob,Grep" \
--max-budget-usd 1.00 \
--output-format json \
--json-schema '{"type":"object","properties":{"problems":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"issue":{"type":"string"}},"required":["file","issue"]}}},"required":["problems"]}' \
| jq -r --arg d "$dir" '.structured_output.problems[] | "\($d)\t\(.file)\t\(.issue)"'
done設計重點：--bare 保證一致、--allowedTools 限制成唯讀、--max-budget-usd 設上限、--json-schema 保證輸出可被 jq 解析。
⚠️ 記得
--bare需要ANTHROPIC_API_KEY（走 API 計費）。想用訂閱登入就拿掉--bare，代價是會載入你的 hooks / skills / CLAUDE.md。
幾個容易踩的行為
- 背景 bash 任務：
claude -p期間 Claude 起的背景 shell（dev server、watch build），會在最終結果回傳且 stdin 關閉後約 5 秒被終止。 - 背景 subagent 和 workflow 不受那 5 秒限制（它們的結果是最終輸出的一部分），但預設最多等 10 分鐘（
CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS可調，0= 不限）。 - SIGTERM：中止當輪、終止 bash 指令的整個 process tree、跑
SessionEndhook、以 exit code 143 結束。 -p裡可以用 skill：prompt 字串裡放/skill-name，Claude Code 會先展開。但只在終端介面能用的內建指令（如/login）在-p模式不可用。/model、/effort、/fast、/color、/rename可以帶值（/model sonnet），/config可以key=value。
🔗 相關筆記
- 10-MCP與外部工具 — 上一步
- 12-設定檔與CLI旗標速查 — 下一步：完整旗標表
- 05-權限模式與安全 —
dontAsk是 CI 的正確模式 - Codex CLI 06 - codex exec — Codex 那邊的對應功能
- Python 07 - 實戰自動化範例 — 可以被包成 pipeline 的既有腳本
最後更新：2026-08-04