定时任务与批处理

定时任务与批处理

Headless 模式让 Claude Code 变成「调一次返回一次」的函数。但很多自动化场景需要的是周期性——每天 9 点跑一遍代码审查、每 5 分钟检查 CI 状态、每周一生成一份迁移报告。

这一页讲怎么把 headless 接上时间维度：用 cron / systemd / GitHub Actions schedule 调度，用 --max-budget-usd / --max-turns 控制成本，用 --init / --maintenance 跑项目维护，用 setup-token 拿长期 CI token。

三种调度方案

调度器	适合	优势
cron / systemd	本地机器、自建服务器	不依赖第三方，完全可控
GitHub Actions schedule	仓库相关自动化	跑在 GitHub runner，能直接 push 到 repo
Claude Code /loop	单会话内轮询	会话内调度，跨 session 不持久（详见下文）

cron：最朴素的调度

cron 是 Unix 几十年的老朋友，每分钟检查一次 crontab。配 headless 跑 Claude Code 很自然：

# 每天早上 9 点跑代码审查
0 9 * * * cd /path/to/repo && claude -p "Review yesterday's commits and post a summary to Slack" \
  --output-format json \
  --max-budget-usd 2 \
  --max-turns 20 \
  >> /var/log/claude-daily-review.log 2>&1

cron 没有 timeout 概念，记得套 timeout 防卡死：

0 9 * * * cd /path/to/repo && timeout 600 claude -p "..." --output-format json

systemd：更现代的本地调度

systemd timer 比 cron 更灵活——支持秒级精度、依赖关系、失败重试。一个简单的 systemd timer：

/etc/systemd/system/claude-daily-review.service

[Unit]
Description=Daily Claude Code review

[Service]
Type=oneshot
WorkingDirectory=/path/to/repo
Environment=ANTHROPIC_API_KEY=...
ExecStart=/usr/bin/claude -p "Review yesterday's commits and post a summary" --output-format json --max-budget-usd 2
TimeoutStartSec=600

/etc/systemd/system/claude-daily-review.timer

[Unit]
Description=Run daily Claude Code review at 9am

[Timer]
OnCalendar=*-*-* 09:00:00
Persistent=true

[Install]
WantedBy=timers.target

sudo systemctl enable --now claude-daily-review.timer

Persistent=true 让错过了（机器当时关机）的执行在开机后补跑——比 cron 强。

GitHub Actions schedule

GitHub Actions 内置 schedule 触发器，跑在 GitHub runner 上，能直接 push 到你的 repo：

name: Daily Code Review
on:
  schedule:
    - cron: "0 9 * * *"   # 每天 UTC 9 点
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review yesterday's commits and open issues for an issue if anything needs follow-up" \
            --output-format json \
            --max-budget-usd 2 \
            --max-turns 15

或者直接用 Claude Code GitHub Actions，把 prompt 写进 action：

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Generate a summary of yesterday's commits and open issues"
    claude_args: "--model opus --max-turns 10"

控制成本的护栏

定时任务最怕「跑飞了」——一次任务因为某种原因无限轮次，账单爆炸。headless 三个护栏必备：

Flag	作用
--max-budget-usd <n>	限美元花费上限，到顶就停
--max-turns <n>	限 agentic 轮数，到顶报错
timeout <s>	限总时长，防卡死

timeout 600 claude -p "重构 src/legacy" \
  --max-budget-usd 5 \
  --max-turns 30 \
  --output-format json

定时任务里这三个永远要一起出现。--max-budget-usd 是钱袋子的硬保险。

–init：跑 Setup hooks

--init 在 session 启动前跑 Setup hooks（用 init matcher）——例如自动装依赖、跑 lint 修复、初始化环境。配 cron 用很自然：

claude -p --init "检查测试是否通过" --output-format json

--init-only 更进一步：只跑 Setup 和 SessionStart hooks 然后退出，不开启对话。适合纯维护性的初始化任务：

claude --init-only

–maintenance：跑维护 matcher

--maintenance 用 maintenance matcher 跑 Setup hooks——专门给「项目维护」类任务用。它和 --init 的差别是 matcher 不同，你可以为这两类 hook 写不同的逻辑：

claude -p --maintenance "跑一遍代码维护清单" --output-format json

在 .claude/settings.json 里配 Setup hook 时区分 init 和 maintenance matcher，让初始化任务和维护任务走不同的脚本。

claude setup-token：长期 CI token

定时任务最烦的是 token 管理——OAuth token 会过期，CI 里没法走交互登录。claude setup-token 解决这个问题：生成一个长期有效的 OAuth token 给 CI 和脚本用。

claude setup-token

它把 token 打印到终端，不存盘——你需要自己把它存进 CI secret（GitHub Actions / GitLab CI variables / 你的脚本环境变量）。需要 Claude 订阅才能用。

适合的周期任务

场景	频率	怎么做
每日代码审查	每天一次	cron / Actions schedule + --init
定期 lint 修复	每天或每 PR	cron + --allowedTools "Bash,Edit"
自动翻译新文案	每次新文案	webhook 触发 + headless（详见 管道）
批量改造（重命名、加错误处理）	一次性大批量	--bg 后台会话或 workflow
全量审计	每周	cron + Agent Teams fan out
跑 Setup 维护	每次部署	--init-only 嵌进部署脚本

/loop：会话内调度

除了 cron 这类外部调度器，Claude Code 还内置了 /loop——一个 slash command 在当前会话里跑周期 prompt。它有三种用法：

/loop 5m check the deploy           # 固定间隔跑指定 prompt
/loop check whether CI passed       # 让 Claude 自己挑间隔
/loop                               # 跑内置 maintenance prompt

/loop 是会话内调度的——任务和当前会话绑定，新开会话就停止。--resume / --continue 恢复会话时也带回来（7 天内有效）。要跨会话、跨重启的调度，用 cron / systemd / GitHub Actions schedule，或者用 Anthropic 的 Routines（云上调度）。

/loop 跑的内置 maintenance prompt 会按顺序做这些事：

1. 继续上次没做完的活
2. 照看当前分支的 PR——审查评论、失败的 CI、合并冲突
3. 没事干时跑清理类活——bug 找茬、代码简化

不会主动起新方向，不可逆动作（push / delete）只在上次 transcript 已授权时才继续。

可以用 loop.md 覆盖默认 prompt：

.claude/loop.md

Check the `release/next` PR. If CI is red, pull the failing job log, diagnose, and push a minimal fix.
If new review comments have arrived, address each one and resolve the thread.
If everything is green and quiet, say so in one line.

放在 .claude/loop.md（项目级）或 ~/.claude/loop.md（用户级），项目级优先。

一句话总结

把 headless 接上时间维度就成了周期自动化：cron / systemd / GitHub Actions schedule 是调度器，--max-budget-usd 和 --max-turns 是钱袋子护栏，--init / --maintenance / --init-only 跑项目维护，claude setup-token 给 CI 长期 token，/loop 在单会话里做轻量轮询。

回 Headless 模式 复习整套 headless 基础，或去 Agent SDK 看怎么把这种调度写成完整程序。⏰