你在終端機裡跟 Claude Code 對話，它很聰明。但你不可能 24 小時坐在終端機前面。

每次跑 CI 的時候自動讓 AI review PR、每天凌晨三點自動掃描 codebase 裡的安全問題、每週一早上自動生成上週的開發報告——這些事情需要 Claude Code 在沒有人坐在前面的情況下自己跑。

這就是 Headless Mode。一個 -p flag，把互動式的 AI 助手變成可以塞進任何腳本的命令列工具。

什麼是 Headless Mode

想像你平常跟 Claude Code 的互動方式像打電話：你說一句，它回一句，你可以隨時插嘴改方向。Headless Mode 像寄信：你把要做的事寫清楚，封好信封寄出去，它做完把結果寄回來。中間不會打電話問你。

技術上就是加一個 -p（或 --print）flag：

1
claude -p "找出 auth.py 裡的 bug 並修復"

Claude 收到 prompt，跑完整個 agent loop——思考、呼叫工具、編輯檔案——然後把結果輸出到 stdout，程序結束。不會開互動式介面，不會等你輸入。

跑完就退出。這一點很重要，因為它代表你可以把 claude -p 當成任何其他 CLI 工具來用：串在 pipe 裡、放進 shell script、排進 cron job。

最基本的用法

1
2
3
4
5
6
7
8
9
10
11
# 最簡單的形式
claude -p "解釋 src/utils/cache.ts 的設計"

# 指定輸出格式
claude -p "列出所有 TODO 註解" --output-format json

# 限制可用工具（安全性關鍵）
claude -p "Review 這個 PR 的變更" --allowedTools "Read,Bash(grep:*)"

# 限制執行步數和花費
claude -p "重構 auth module" --max-turns 20 --max-budget-usd 5.00

--output-format 有三個選項：text（預設，人類可讀）、json（結構化輸出，方便程式處理）、stream-json（串流式，即時拿到每一步的輸出）。

如果你要在腳本裡解析結果，json 是最穩的選擇。如果你想做即時監控面板，stream-json 配合 jq 可以即時抓取每一個 tool call 和回應。

安全控制：不設限的 AI 在凌晨三點能幹什麼

Headless Mode 最重要的設計決策不是「怎麼跑」，而是「怎麼限制」。

一個沒有人盯著的 AI agent 拿到完整的檔案系統存取權限和 shell 執行能力——凌晨三點它 rm -rf 了你的原始碼怎麼辦？不是開玩笑，PocketOS 事件裡 Cursor agent 就是在九秒內刪光了正式資料庫加備份。

--allowedTools 是安全的核心。它用白名單的方式定義 Claude 能用什麼工具：

1
2
3
4
5
6
7
8
# 只能讀檔案和跑 grep
claude -p "分析 codebase 結構" --allowedTools "Read,Bash(grep:*)"

# 可以讀寫檔案，可以跑 npm test，其他 shell 指令都不行
claude -p "修復失敗的測試" --allowedTools "Read,Edit,Write,Bash(npm test:*)"

# 完全禁止 shell 存取
claude -p "Review 這段 code" --allowedTools "Read"

--max-turns 限制 agent 可以執行幾步。一個 review 任務 10 步夠了，一個重構任務可能要 50 步。設太低會中斷未完成的工作，設太高等於沒限制。

--max-budget-usd 設花費上限。跑到上限就停。六月十五號之後 claude -p 的用量會從新的 Agent SDK credit 扣，跟互動式使用分開計費。

三個限制一起用才完整：

1
2
3
4
claude -p "掃描安全漏洞" \
  --allowedTools "Read,Bash(grep:*),Bash(find:*)" \
  --max-turns 30 \
  --max-budget-usd 2.00

實戰場景一：CI/CD 自動 Code Review

每次有人開 PR，GitHub Actions 自動跑一次 Claude review：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          DIFF=$(git diff origin/main...HEAD)
          claude -p "Review 以下 PR diff，找出潛在問題：\n\n$DIFF" \
            --allowedTools "Read" \
            --max-turns 10 \
            --output-format json > review.json

重點在 --allowedTools "Read"：CI 環境裡 Claude 只能讀不能寫。它的工作是找問題不是修問題。

實戰場景二：排程安全掃描

每天凌晨跑一次安全檢查，結果寄到 Slack：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#!/bin/bash
# daily-security-scan.sh

RESULT=$(claude -p "掃描 src/ 目錄的所有檔案，找出以下問題：
1. 硬編碼的 API key 或密碼
2. SQL injection 風險
3. 未驗證的使用者輸入
4. 過時的依賴套件（檢查 package.json）
輸出 JSON 格式，包含 severity、file、line、description。" \
  --allowedTools "Read,Bash(grep:*),Bash(find:*),Bash(npm audit:*)" \
  --max-turns 30 \
  --max-budget-usd 3.00 \
  --output-format json)

# 有發現就通知
if echo "$RESULT" | jq -e '.issues | length > 0' > /dev/null 2>&1; then
  curl -X POST "$SLACK_WEBHOOK" \
    -H 'Content-Type: application/json' \
    -d "{\"text\": \"🔍 安全掃描發現問題：\n$(echo $RESULT | jq -r '.issues[] | \"- [\(.severity)] \(.file):\(.line) - \(.description)\"')\"}"
fi

放進 crontab：

1
0 3 * * * cd /path/to/project && ./daily-security-scan.sh

實戰場景三：批次處理多個任務

Headless Mode 的一個強項是可以用迴圈批次跑：

1
2
3
4
5
6
7
8
# 幫每個模組生成文件
for dir in src/modules/*/; do
  module=$(basename "$dir")
  claude -p "讀取 ${dir} 下的所有檔案，生成一份 README.md 包含：模組用途、主要 API、使用範例" \
    --allowedTools "Read,Write" \
    --max-turns 15
  echo "✅ ${module} 文件已生成"
done

–bare：極速模式

如果你只是要跑一個簡單的查詢，不需要 hooks、skills、plugins、MCP servers、auto memory 那些東西，--bare 可以跳過所有自動發現流程：

1
claude -p "這段 code 有什麼問題？$(cat bug.py)" --bare

啟動時間從幾秒壓到幾乎即時。適合大量短任務的批次場景。

串流輸出：即時監控

stream-json 格式讓你可以即時看到 Claude 正在做什麼：

1
2
3
4
claude -p "重構 auth module" \
  --output-format stream-json \
  --verbose \
  | jq -r 'select(.type == "stream_event") | .event.delta.text // empty'

每一步的思考、工具呼叫、檔案編輯都會即時串流出來。拿來做監控面板或者 debug 長時間任務很好用。

常見的坑

**忘記設 --allowedTools**。預設情況下 Claude 有完整的工具存取權限。在無人看管的環境裡這等於開著門離開家。

Prompt 太模糊。互動模式裡你可以來回澄清。Headless Mode 你只有一次機會把需求講清楚。寫 prompt 的時候假設對方是一個聰明但什麼背景資訊都沒有的同事——把目標、範圍、限制都講明。

沒有處理失敗。Claude 可能遇到權限問題、檔案不存在、或者 token 用完而中途停止。腳本裡要檢查 exit code 和輸出內容。

--max-turns 設太低。一個看起來簡單的任務可能需要 Claude 讀五個檔案、跑兩次測試、修一個 bug。每個工具呼叫算一步。10 步很快就用完了。建議先互動模式跑一次看需要幾步，再設限制。

跟 Routines 有什麼不同

Routines 是 Claude Code 的雲端排程功能——你設定好觸發條件（時間、GitHub event、API call），Claude 在 Anthropic 的雲端容器裡跑。你的電腦可以關機。

Headless Mode 是你自己的機器上跑的。你控制環境、你控制網路、你控制存取權限。適合需要存取本地檔案、內部 API、或者有資安限制不能把 code 送到雲端的場景。

兩者互補，不是替代。CI/CD 通常用 Headless Mode（跑在你自己的 runner 上）；定期的背景任務如果不涉及敏感資料，Routines 更方便。

學完之後

Headless Mode 打開的是自動化的大門。一旦 Claude Code 可以在腳本裡跑，你能做的事就不受限於「人坐在終端機前面的時間」了。

下一步可以看 Claude Code GitHub Actions 教學 了解怎麼在 CI 裡整合，或者看 Claude Code Routines 教學 了解雲端排程的做法。兩個加起來就是一個完整的「人不在也能持續運作」的 AI 工作流。

參考來源：Run Claude Code programmatically — Claude Code Docs
參考來源：Claude Code Headless Mode: The CI/CD Automation Playbook — Code With Seb