Claude Code headless 模式：用 claude -p 寫腳本和自動化

本文根據 Claude Code 官方文檔《Run Claude Code programmatically》《CLI reference》《Authentication》整理，核對日期 2026-10-07。示例改寫自官方示例。

適用於誰

• 想在 shell 腳本、package.json、CI 流水線、定時任務裏調用 Claude Code 的開發者；
• 搜「claude code headless 是什麼」「headless mode」「headless authentication」的人；
• 想把 Claude 的輸出變成 JSON 交給其他程序處理的人。

結論先說

1. headless 模式 = 給 claude 加上 -p（或 --print）：不進交互介面，處理完這一句就把結果打印出來並退出。官方現在把它歸入 Agent SDK 的命令行用法。
2. 成功時退出碼為 0，失敗為非 0，腳本可以據此判斷；可以用管道把內容餵給它，也能把結果重定向到文件。
3. 沒人點「允許」，所以要提前用 --allowedTools 或 --permission-mode 規定它能做什麼，CI 裏推薦 dontAsk 加精確白名單。
4. 在 CI 和腳本里官方推薦加 --bare：跳過本機的 Hooks、技能、插件、MCP、CLAUDE.md 自動加載，保證每台機器結果一致，但它只認 API Key，不認訂閱登入。
5. 沒有瀏覽器的環境要用訂閱帳號，用 claude setup-token 生成長期令牌，設定為 CLAUDE_CODE_OAUTH_TOKEN。

一、基本用法

bash
# 問一個問題，打印回答後退出
claude -p "認證模組是做什麼的？"

# 讓它修 bug，並預先允許讀、改文件和執行命令
claude -p "找到並修復 auth.py 裏的 bug" --allowedTools "Read,Edit,Bash"

用管道處理數據：

bash
cat build-error.txt | claude -p "簡要說明這個構建錯誤的根本原因" > output.txt

管道輸入上限 10MB，超過會報錯退出；更大的內容先寫進文件，再在提示詞裏給出路徑。

放進構建腳本（官方示例：把相對 main 的 diff 交給 Claude 找錯別字）：

json
{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"你是錯別字檢查器。對 diff 裏的每個錯別字，第一行寫 文件名:行號，第二行寫問題。其他什麼都不要輸出。\""
  }
}

運行 npm run lint:claude 即可。把 diff 通過管道喂進去，Claude 就不需要執行 git 命令的權限。

二、常用參數

三、拿到結構化結果

bash
# JSON：文本結果在 result 字段，另含 session_id、用量和預估花費
claude -p "總結一下這個項目" --output-format json | jq -r '.result'

# 按指定結構輸出
claude -p "提取 auth.py 裏主要的函數名" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

json 輸出裏帶有 total_cost_usd 和按模型拆分的花費，方便腳本統計開銷；官方說明這是客戶端估算，可能和實際帳單不同。

流式輸出（邊生成邊顯示）：

bash
claude -p "解釋一下遞歸" --output-format stream-json --verbose --include-partial-messages

每行一個 JSON 事件，最後一行是包含最終結果、花費和會話資訊的 result 消息。

四、權限：沒人點「允許」怎麼辦

方式一：精確列出允許的工具

bash
claude -p "查看暫存的改動並寫一個合適的提交" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Bash(git diff ) 裏 前面的空格很重要：沒有空格的 Bash(git diff*) 還會匹配到 git diff-index。

方式二：設定權限模式

• --permission-mode dontAsk：凡是需要詢問的一律拒絕，只執行無需批准的讀取和你白名單裏的工具，最適合鎖死權限的 CI；
• --permission-mode acceptEdits：自動改文件和執行常見文件命令，其他 shell 命令仍需白名單；
• --permission-mode auto：由分類器審核每個操作。

官方提醒：不指定時會採用內置的起始模式（可能是 auto），所以腳本里最好明確寫出你想要的模式。完全無人值守的定時任務可以再加 --permission-prompts none（v2.1.259 起），讓所有「本該彈窗詢問」的請求直接拒絕並告訴 Claude 不要重試。權限模式詳解見本站《Claude Code 權限模式詳解：auto、手動、plan、bypass 與權限規則配置》。

五、--bare 模式：CI 的推薦寫法

不加 --bare 時，claude -p 會像交互會話一樣加載當前目錄和 ~/.claude 裏的一切：Hooks、技能、插件、MCP 伺服器、自動記憶和 CLAUDE.md。而且-p 模式不會彈出「信任此文件夾」和 MCP 批准提示，在陌生倉庫裏運行會直接執行它 .claude/settings.json 裏的 Hooks、連接它 .mcp.json 裏的伺服器。

加上 --bare 後這些都不自動加載，需要的東西用參數顯式傳入：

bash
claude --bare -p "總結 README.md" --allowedTools "Read"

官方說明 --bare 是腳本和 SDK 調用的推薦模式，未來會成為 -p 的預設行為。注意：bare 模式不讀訂閱登入憑據，要用 Claude Console 的 ANTHROPIC_API_KEY（或 apiKeyHelper）。

六、在伺服器 / CI 裏怎麼登入

bash
export CLAUDE_CODE_OAUTH_TOKEN=你的令牌    # macOS / Linux
$env:CLAUDE_CODE_OAUTH_TOKEN = "你的令牌"  # PowerShell

官方說明：這個訂閱令牌只能發起模型請求，不能建立 Remote Control 會話，也拿不到 claude.ai 上的連接器；本地配置的 MCP 伺服器照常可用。--bare 模式不讀這個令牌。令牌等同於帳號憑據，務必放在 CI 的密鑰管理裏，不要寫進倉庫。

七、多輪對話

bash
claude -p "檢查這個代碼庫的性能問題"
claude -p "現在重點看數據庫查詢" --continue
claude -p "彙總所有發現的問題" --continue

同時跑多個對話時，記下會話 ID 再精確恢復：

bash
session_id=$(claude -p "開始一次代碼審查" --output-format json | jq -r '.session_id')
claude -p "繼續剛才的審查" --resume "$session_id"

常見問題

Q：-p 模式下能用斜槓命令嗎？

你自己寫的技能和自定義命令可以，把 /技能名 寫進提示詞即可；/login 這類只能在交互介面運行的命令不行。/model sonnet、/config thinking=false 這類帶參數的寫法新版本支持。

Q：GitHub Actions 裏怎麼用？

官方有專門的 Claude Code GitHub Action，詳見本站《Claude Code GitHub Actions 配置教學：@claude 自動審 PR、修 issue》。

Q：想在 Python / TypeScript 程序裏調用怎麼辦？

用 Claude Agent SDK，它提供和 Claude Code 相同的工具、智能體循環和上下文管理，還有結構化輸出和工具審批迴調，詳見本站《Claude Agent SDK 入門：是什麼、怎麼裝、第一個智能體（Python / TypeScript）》。

Q：headless 模式會消耗訂閱額度嗎？

用訂閱令牌登入時，用量和交互使用一樣計入你的套餐額度；用 API Key 時按 API 用量計費。額度說明詳見本站《Claude 使用限制與額度：用量怎麼看、什麼時候重置（Free / Pro / Max / Claude Code）》。

參考資料

• Run Claude Code programmatically（官方）：https://code.claude.com/docs/en/headless
• CLI reference（官方）：https://code.claude.com/docs/en/cli-reference
• Authentication（官方）：https://code.claude.com/docs/en/authentication
• Choose a permission mode（官方）：https://code.claude.com/docs/en/permission-modes
• Agent SDK overview（官方）：https://code.claude.com/docs/en/agent-sdk/overview