Claude Code 唔使開 terminal 都跑得：headless + cron 起夜貓自動化 workflow

情境

你 install 咗 Claude Code 兩個月，interactive session 用到出神入化。但你開始留意到一啲規律：

• 每朝返工頭 30 分鐘做 git pull + 讀 PR + 大致睇一睇啲改動
• 每個禮拜五手動跑 pnpm outdated + npm audit，再決定升邊個
• 每次 push 上 GitHub 都要等同事得閒先 review，PR 喺隊列度排幾個鐘

呢啲動作有個共通點：重複、有規律、唔需要即時對話。你開緊 Claude Code、揼緊 prompt、等緊 output——但其實全部都可以喺你訓緊覺嘅時候做完。

Claude Code 有個 mode 叫 headless：claude -p "task" 直接畀任務、唔開 interactive session、做完即 exit、出入 stdout。呢個 mode 就係專門畀 cron、launchd、GitHub Actions、npm script 入面跑。

呢篇拆 4 個真實 headless 設定：

• 每日 code health 報告（每朝 7 點 cron）
• 每週 dep 升級（加埋安全閘）
• GitHub Actions PR 自動 review
• 排好時間嘅 refactor 批次

撐住，會技術啲。但行完一次，你會明點解 senior dev 個 laptop 凌晨 3 點仍然「咁勤力」。

跟住做

1. Headless mode 基本

Headless 嘅入口就一句：

claude -p "讀 README.md 同 summarize 3 句"

-p = print mode（即係 non-interactive / headless）。Claude 收 prompt → 做 → 出 stdout → 收工。冇對話、冇等你按 Y/N。

關鍵 flags：

# Output 做 JSON，方便落腳本 parse
claude -p "任務" --output-format json

# 明確限制 tools（headless 安全大原則）
claude -p "任務" --allowed-tools "Read,Grep,Bash(git diff:*,git log:*)"

# 完全唔問權限（小心用，只喺 CI / 你控制嘅環境）
claude -p "任務" --dangerously-skip-permissions

# 揀模型
claude -p "任務" --model claude-haiku-4-5

⚠️ 點樣理解 --dangerously-skip-permissions：headless mode 預設仍然會問你攞權限（但因為冇 TTY，會卡住）。呢個 flag 等於話「我已經用 --allowed-tools 鎖死範圍，唔好再問」。永遠配 --allowed-tools 一齊用，唔好淨係跳過權限但唔限 tools。

試一個無害嘅 baseline：

claude -p "用 1 句講 current directory 入面有咩 file" \
  --allowed-tools "Bash(ls:*)" \
  --dangerously-skip-permissions

出到一句 → 你已經有 headless 嘅基本積木。

2. 每日 code health 報告（cron）

目標：每朝 7:00，Claude 自動讀 main branch 嘅最新改動、寫一段「健康摘要」入 file，你食早餐睇。

建立 script ~/scripts/daily-health.sh：

#!/usr/bin/env bash
set -euo pipefail

REPO=~/work/my-app
REPORT=~/reports/health-$(date +%Y-%m-%d).md

cd "$REPO"
git fetch origin main --quiet
git checkout main --quiet
git pull --quiet

claude -p "睇過去 24 小時 main branch 嘅 commit (git log --since='24 hours ago')。
為每個重要 commit 出：
1. 一句總結改動
2. 風險等級（低/中/高）
3. 需唔需要 follow up

最後出一段 3 句嘅 daily summary。" \
  --output-format text \
  --allowed-tools "Bash(git log:*,git diff:*,git show:*),Read,Grep" \
  --dangerously-skip-permissions \
  > "$REPORT"

echo "Report ready: $REPORT"

chmod +x ~/scripts/daily-health.sh 後加落 crontab：

crontab -e

入面加：

0 7 * * * /bin/bash ~/scripts/daily-health.sh >> ~/reports/cron.log 2>&1

每朝 7:00 自動跑。你訓醒已經有當日報告喺 ~/reports/health-2026-05-27.md。

⚠️ API key：cron 環境唔會載入你個 .zshrc，要喺 crontab 開頭明確 export：

ANTHROPIC_API_KEY=sk-ant-xxx
0 7 * * * /bin/bash ~/scripts/daily-health.sh

或者喺 script 入面 source ~/.env。

3. 每週 dep 審查（加安全閘）

目標：每個禮拜一凌晨 2 點，Claude 跑 pnpm outdated、評估邊啲升得安全、自動開 PR。

~/scripts/weekly-deps.sh：

#!/usr/bin/env bash
set -euo pipefail

cd ~/work/my-app
git checkout main && git pull --quiet

BRANCH="bot/deps-$(date +%Y-%m-%d)"
git checkout -b "$BRANCH"

claude -p "你係 dep update bot。

步驟：
1. 跑 'pnpm outdated --format json' 攞 outdated list
2. 只升 patch 同 minor（major 列出但唔好升）
3. 跑 'pnpm update <pkg>' 逐個升安全嘅
4. 跑 'pnpm test' 確保唔 break
5. 如果 test fail，rollback 嗰個 dep
6. 最後出一個 markdown summary：升咗咩、跳過咩、原因

絕對唔好 commit。我會 review。" \
  --allowed-tools "Bash(pnpm:*,git diff:*,git status:*),Read,Edit" \
  --dangerously-skip-permissions \
  > /tmp/dep-summary.md

git add -A
git commit -m "chore(deps): weekly automated update $(date +%Y-%m-%d)"
git push origin "$BRANCH"

gh pr create --title "chore(deps): weekly update" --body-file /tmp/dep-summary.md

Crontab：

0 2 * * 1 /bin/bash ~/scripts/weekly-deps.sh

禮拜一返工已經有條 PR 等你 review。測試 pass、摘要清楚、major 版本升級列咗出嚟畀你揀。

呢個設定嘅安全閘：Claude 唔可以 git push --force、唔可以合併、唔可以郁 major 版本。你保留最終決定權。

4. GitHub Actions PR 自動 review

目標：每條 PR 開出嚟，Claude 自動覆檢、留低意見。

.github/workflows/claude-review.yml：

name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review the diff between origin/main and HEAD.
          Focus on: bugs, security, error handling.
          Output 3-5 specific findings, each with file:line.
          If no issues, just say 'LGTM'." \
            --allowed-tools "Bash(git diff:*,git log:*),Read,Grep" \
            --dangerously-skip-permissions \
            > review.md

      - name: Post review comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## Claude Review\n\n' + body,
            });

ANTHROPIC_API_KEY 加落 GitHub repo secrets。Push → 每條 PR 自動有第一輪 review，真人 reviewer 慳返 15 分鐘第一遍掃描。

⚠️ 成本：每條 PR 一次 review，月 100 條 PR、用 Sonnet，大約 USD $5-15。先用 --model claude-haiku-4-5 封住成本，發覺漏嘢先升 Sonnet。

變化

變化 1：macOS launchd 取代 cron

Mac 用家：cron 用得，但 Apple 官方推 launchd（更穩、log 更靚、識重新啟動）。

建立 ~/Library/LaunchAgents/com.you.daily-health.plist：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.you.daily-health</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/you/scripts/daily-health.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>7</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/you/reports/cron.log</string>
  <key>StandardErrorPath</key>
  <string>/Users/you/reports/cron.err</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>ANTHROPIC_API_KEY</key>
    <string>sk-ant-xxx</string>
  </dict>
</dict>
</plist>

Load：

launchctl load ~/Library/LaunchAgents/com.you.daily-health.plist

開關更可控、laptop 訓覺醒返會自動補跑（如果你設 RunAtLoad）。

變化 2：Output 直推 Slack / Discord webhook

唔想讀 file，想改睇手機通知？將 Claude output 接駁入 webhook：

SUMMARY=$(claude -p "summarize PR queue" \
  --allowed-tools "Bash(gh pr list:*)" \
  --dangerously-skip-permissions)

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg text "$SUMMARY" '{text: $text}')"

每朝個 Slack channel 自動有「今日 PR 狀況」摘要。Discord 寫法一樣，淨係換埋個 webhook URL。

變化 3：Claude Agent SDK（TypeScript wrapper）

claude -p 簡單，但如果你想喺 output parsing、重試、成本記錄方面控制得細啲，就用 Claude Agent SDK：

import { query } from "@anthropic-ai/claude-agent-sdk"

const result = await query({
  prompt: "Review git diff and output JSON of findings",
  options: {
    allowedTools: ["Read", "Bash(git diff:*)"],
    permissionMode: "bypassPermissions",
    model: "claude-sonnet-4-6",
  },
})

for await (const message of result) {
  if (message.type === "result") {
    console.error(JSON.stringify(message, null, 2))
  }
}

包入 npm script，放落 package.json：

{
  "scripts": {
    "review": "tsx scripts/review.ts",
    "deps:audit": "tsx scripts/deps-audit.ts"
  }
}

Solo dev 唔需要。Agency / startup 跑 5 條以上 automation workflow 嗰陣，SDK 嘅重試、錯誤處理、成本記錄就抵返成本。

拆解：點解 work，同邊度會仆街

跟到上面就已經跑得起。下面呢段係畀想由「跑一次靚仔」做到「跑足半年都唔出事」嘅人——初學者可以跳過，唔影響你跟住做。

Headless automation 最陰公嘅地方係：冇人睇住。Interactive 你會即刻見到出錯、即刻 Ctrl-C；headless 喺凌晨 3 點靜雞雞做嘢，做錯咗都冇人知，直到你某朝發現條 PR 一早合咗、又或者三個禮拜冇出過報告。呢幾個位，就係 headless 真實會仆街嘅地方，你要預咗：

1. 靜默失敗，跑咗等於冇跑 cron 跑你個 script，就算 Claude 中途死咗、API timeout、quota 爆咗，cron 都唔會嘈——佢只係照樣 schedule 下一次。你以為日日有報告，其實個 file 兩個禮拜前已經停咗喺度。

• 會出事：你以為個系統幫緊手，實情佢靜咗好耐，你反而少咗份警覺。
• 點救：script 開頭 set -euo pipefail（範本已經有），出事即刻非零 exit。再加一句「跑成功就掂一吓 healthcheck URL / 出一個『我仲生勾勾』嘅訊息」——連續幾日冇收到，你就知佢死咗。寧願嘈，唔好靜。

2. --dangerously-skip-permissions 配錯 --allowed-tools 範圍 個 flag 個名已經叫你小心。Headless 冇 TTY，冇人撳 Y/N，所以 Claude 喺你開放嘅 tool 範圍內可以為所欲為。如果你 Bash(git:*) 開太闊，理論上 git push --force、git reset --hard 都喺範圍內。

• 會出事：一個你冇預到嘅破壞性指令喺無人看管下執行咗，而且冇人即時截停。
• 點救：tool scope 收到最窄——要乜開乜，唔好用 Bash(git:*) 咁闊，寫明 Bash(git diff:*,git log:*)。破壞性嘅嘢(push、合併、major 升級)留返畀人手，prompt 入面寫死「絕對唔好 commit / push，我會 review」(範本嘅 dep script 正正係咁做)。

3. LLM 唔係 deterministic，同一個 prompt 唔保證同一個結果 你今日試 review prompt 出到 3 個準確 finding，唔代表下次同一條 PR 都出返一樣。Headless 跑落去，有時會多嘢、漏嘢、format 走樣。如果你下游靠 parse 佢個 output(例如當「LGTM」做 pass 訊號去自動合併)，格式一變就會出事。

• 會出事：下游腳本撞到意料之外嘅 output,parse 錯、或者攞咗個唔啱嘅訊號去做下一步。
• 點救：要落腳本 parse 就用 --output-format json，唔好靠 grep 段自由文字。任何「自動做下一步」嘅決定(自動合併、自動 deploy)都要有一道人手閘，唔好畀 LLM 嘅一句說話直接觸發。

4. 個 repo state 唔係你 script 預期嗰個 你個 dep script 假設一開波喺乾淨嘅 main。但如果上次跑到一半死咗，留低咗條 bot/deps-xxx branch 未清、或者 working tree 有未 commit 嘅嘢，今次 git checkout -b 就會撞名失敗，成個 script 連鎖爆煲。

• 會出事：script 喺一個你冇預到嘅 git state 開波，做出嚟嘅嘢唔係你想要嗰樣，甚至污染咗個 repo。
• 點救：script 開頭先做 idempotent 嘅清理——確認喺 main、git stash 或者 check 過 working tree 乾淨先行落去；branch 名撞到就先刪舊嗰條。每次跑都當「由零開始」咁設計，唔好假設上次跑得乾淨。

5. 成本同 quota，跑得越密蝕得越靜 Headless 嘅 bill 唔似你坐喺度睇住跳。一條 cron 每 5 分鐘跑一次、又或者你 schedule 咗一個大 refactor 批次跑到失控，個數會喺你訓覺嗰陣一路堆上去。撞到 rate limit / quota，輕則靜默失敗(見第 1 點)，重則一個月嘅 budget 一個禮拜燒晒。

• 會出事：月底個 bill 嚇你一跳，又或者半夜撞爆 quota，連帶第二朝你真係要用嗰陣都用唔到。
• 點救：先用平 model(--model claude-haiku-4-5)封住成本，發覺漏嘢先升。頭一個月每日睇 Anthropic console 摸清真實單價。高頻 cron 加埋一個「今日已經跑咗幾多次」嘅上限，唔好任由佢無限重試。

呢幾個位，就係「跑一次 demo 靚仔」同「跑足半年、你訓得安樂」之間嘅距離。Headless 唔係叫你撒手不管，係叫你預先諗定「佢出事嗰陣，我點樣即刻知」。

一個心態

Headless 嘅深層體會：你嘅產出唔再受你個鐘頭數限制。

之前：每日 8 個有生產力嘅鐘頭，你親手敲 prompt 攞 output。 而家：8 個鐘 interactive + 16 個鐘 cron 跑緊嘢。每日報告、每週審查、PR review 全部喺你訓覺嘅時候做晒。

呢個改變對 3 類人特別顯著：

• Solo dev：你冇 reviewer、冇 ops、冇 dep bot。Headless Claude 幫你補上呢 3 個角色，自己一個 ship 嘅速度追平 5 人 team。
• Startup 早期 team：3 個工程師，所有 review、審查、雜務都要人做。Headless 食晒呢層瑣碎工夫，工程師可以專注喺真正嘅 feature。
• Agency / consulting：10 個客戶 project，每個都要每週做一次 health check。Cron 跑 10 條 script、出入客戶 Slack。一個人服務 10 個客戶。

最後提醒：

• ✅ 由 1 條 cron 開始。揀最悶嗰個重複動作（你每日做都覺得煩嗰樣），先自動化嗰一條。一個禮拜驗證 output 質素，先加第 2 條。
• ⚠️ 睇住成本。Headless 跑得密 = 個 bill 升得快。頭一個月每日睇 Anthropic console，摸清真實成本，再決定要唔要由 Sonnet 降去 Haiku。
• 🎯 --allowed-tools 唔好懶。Headless = 冇人喺度問你 Y/N。Tool 鎖死 = 你訓得安樂。

今晚加一條 cron，聽朝 7 點睇佢嘅 output。一個禮拜後你會問自己：「點解之前所有嘢都要手動跑？」