Headless 与 CI/CD

Headless 模式适合把 Claude Code 放进脚本、CI 或批处理任务里运行。核心入口是 -p / --print：传入提示词，执行完成后输出结果并退出。

基本用法

单次执行

claude -p "检查代码中的安全风险"

JSON 输出

claude -p "分析项目依赖的安全性" --output-format json

JSON 适合被 CI、脚本或 GitHub Actions 解析。

流式 JSON

claude -p "修复所有 lint 错误" --output-format stream-json

长任务可以用流式输出记录进度。

权限控制

自动化环境里不要默认放开所有权限。先写清楚允许的工具：

claude -p "跑测试并解释失败原因" \
  --permission-mode dontAsk \
  --allowedTools "Read,Glob,Grep,Bash(pnpm test)"

dontAsk 会拒绝未预先允许的工具，适合需要确定性的 CI。

跳过权限检查

claude -p "修复 lint 错误" --dangerously-skip-permissions

这个选项只适合一次性容器、临时 worktree 或 VM。不要在日常开发主机上使用，也不要和真实生产凭证放在一起。

GitHub Actions

自动代码审查

name: AI Code Review

on:
  pull_request:

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

      - name: Install Claude Code
        run: |
          curl -fsSL https://claude.ai/install.sh | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "审查这个 PR 的代码变更，关注安全性、性能和回归风险。" \
            --permission-mode dontAsk \
            --allowedTools "Read,Glob,Grep,Bash(git diff *)" \
            --output-format json > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('node:fs');
            const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review.result || 'Claude Code did not return a review body.'
            });

修复 Lint 并输出 diff

name: AI Lint Assist

on:
  workflow_dispatch:

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: |
          curl -fsSL https://claude.ai/install.sh | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Fix lint errors
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "运行 lint 检查，修复可自动修复的问题，最后输出 git diff 摘要。不要提交，不要推送。" \
            --allowedTools "Read,Glob,Grep,Edit,Write,Bash(pnpm lint),Bash(pnpm format),Bash(git diff *)" \
            --output-format json > result.json

      - name: Show diff
        run: git diff --stat && git diff --check

这种流程适合人工检查后再决定是否提交。自动 commit、自动 push、自动发布应该单独加审批门禁。

生成 Changelog

- name: Generate Changelog Draft
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p "基于最近 20 个 commit 生成 CHANGELOG 草稿。" \
      --permission-mode dontAsk \
      --allowedTools "Read,Bash(git log *)" \
      --output-format json > changelog.json

批量处理

多文件处理

for file in src/components/*.tsx; do
  claude -p "给 $file 补充必要的可访问性属性，并保持现有设计风格" \
    --allowedTools "Read,Edit,Write"
done

多项目分析

for dir in packages/*/; do
  claude -p "分析 $dir 的测试覆盖和主要风险，输出简短结论" \
    --permission-mode dontAsk \
    --allowedTools "Read,Glob,Grep,Bash(pnpm test *)" \
    --output-format json
done

与其他工具组合

管道输入

git diff HEAD~5 | claude -p "总结这些代码变更"

预提交检查

claude -p "检查暂存区代码是否有明显安全问题" \
  --permission-mode dontAsk \
  --allowedTools "Read,Bash(git diff --cached *)" \
  --output-format json

注意事项

CI 只注入当前任务必需的 secret
--allowedTools 越窄越好
写入类任务优先输出 diff，不要直接发布
需要网络或外部系统时，把工具封装成 MCP 并单独授权
高风险任务放进隔离环境，不要复用日常开发目录

On this page