Claude Code Headless 模式与 CI 集成

什么是 Headless 模式

Claude Code 的 Headless 模式（也叫 --print 模式）允许在没有交互式终端的环境中运行。它接收输入、执行任务、输出结果，然后退出——不需要人工干预。

这让 Claude Code 可以在 CI/CD 流水线、定时任务、自动化脚本中运行。

# 交互模式（默认）
claude
# 进入交互式对话...

# Headless 模式
claude --print "分析 src/ 目录的代码质量"
# 输出结果后自动退出

基础用法

—print 标志

# 最简单的用法
claude --print "解释 package.json 中的 scripts"

# 指定工作目录
claude --print --cwd /path/to/project "运行测试并报告结果"

# 输出到文件
claude --print "生成 API 文档" > api-docs.md

# 管道输入
cat error.log | claude --print "分析这个错误日志，找出根本原因"

常用选项

选项	说明	示例
—print	启用 Headless 模式	`claude --print "任务"`
—cwd	指定工作目录	`--cwd /path/to/project`
—model	指定模型	`--model claude-sonnet-4-20250514`
—max-tokens	最大输出 Token	`--max-tokens 4096`
—allowedTools	允许的工具	`--allowedTools Read,Grep,Glob`
—output-format	输出格式	`--output-format json`

JSON 输出

claude --print --output-format json "列出所有 TODO 注释"

输出：

{
  "text": "找到以下 TODO 注释：...",
  "usage": {
    "inputTokens": 1234,
    "outputTokens": 567
  },
  "toolCalls": [
    {
      "tool": "Grep",
      "input": { "pattern": "TODO", "path": "src/" }
    }
  ],
  "duration": 3456
}

CI 环境配置

认证方式

在 CI 环境中，Claude Code 需要通过 API Key 认证：

# 设置环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 然后正常使用
claude --print "任务"

GitHub Actions 中的配置

# .github/workflows/claude-code.yml
name: Claude Code CI

on:
  pull_request:
    branches: [main]

env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

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

      - name: Run AI Task
        run: claude --print "分析代码质量"

GitLab CI 中的配置

# .gitlab-ci.yml
ai-review:
  image: node:22
  stage: review
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - claude --print "审查最近的代码变更"
  only:
    - merge_requests

GitHub Actions 实战

场景 1：PR 自动代码审查

name: AI Code 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: Setup
        run: |
          npm install -g @anthropic-ai/claude-code
          # 获取变更文件列表
          echo "CHANGED_FILES=$(git diff --name-only origin/main...HEAD | tr '\n' ',')" >> $GITHUB_ENV

      - name: AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          REVIEW=$(claude --print "审查以下文件的代码变更，关注：
          1. 潜在的 Bug
          2. 性能问题
          3. 安全隐患
          4. 代码风格

          变更的文件：${{ env.CHANGED_FILES }}

          以 Markdown 格式输出审查结果。")

          echo "$REVIEW" > review.md

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

场景 2：自动修复 Lint 错误

name: Auto Fix Lint

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

      - name: Run Lint
        id: lint
        continue-on-error: true
        run: npx eslint src/ --format json > lint-results.json 2>&1

      - name: AI Fix
        if: steps.lint.outcome == 'failure'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          claude --print "读取 lint-results.json 中的 ESLint 错误，
          修复所有可以自动修复的问题。
          对于不能自动修复的问题，在代码中添加注释说明。"

      - name: Commit Fixes
        if: steps.lint.outcome == 'failure'
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "bot@example.com"
          git add -A
          git diff --staged --quiet || git commit -m "fix: auto-fix lint errors via Claude Code"
          git push

场景 3：自动生成 Changelog

name: Generate Changelog

on:
  push:
    tags:
      - 'v*'

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

      - name: Setup
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate Changelog
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取上一个 tag
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")

          if [ -n "$PREV_TAG" ]; then
            COMMITS=$(git log ${PREV_TAG}..HEAD --oneline)
          else
            COMMITS=$(git log --oneline -20)
          fi

          claude --print "根据以下 commit 记录生成 Changelog：

          $COMMITS

          格式要求：
          - 按类型分组（Features, Bug Fixes, Documentation 等）
          - 每条记录包含简短描述
          - Markdown 格式" > CHANGELOG_ENTRY.md

      - name: Create Release
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const changelog = fs.readFileSync('CHANGELOG_ENTRY.md', 'utf8');
            await github.rest.repos.createRelease({
              owner: context.repo.owner,
              repo: context.repo.repo,
              tag_name: context.ref.replace('refs/tags/', ''),
              name: context.ref.replace('refs/tags/', ''),
              body: changelog
            });

场景 4：PR 描述自动生成

name: Auto PR Description

on:
  pull_request:
    types: [opened]

jobs:
  describe:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate Description
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD --stat)
          COMMITS=$(git log origin/main..HEAD --oneline)

          claude --print "根据以下信息生成 PR 描述：

          ## Commits
          $COMMITS

          ## Changed Files
          $DIFF

          格式：
          ## 变更说明
          （简要描述做了什么）

          ## 变更详情
          （列出主要变更点）

          ## 测试
          （建议的测试方式）" > pr-body.md

      - name: Update PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('pr-body.md', 'utf8');
            await github.rest.pulls.update({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number,
              body: body
            });

环境变量参考

在 CI 环境中可能需要的环境变量：

变量	说明	必需
ANTHROPIC_API_KEY	Anthropic API 密钥	是
CLAUDE_CODE_MODEL	使用的模型	否
CLAUDE_CODE_MAX_TOKENS	最大输出 Token	否
CLAUDE_CODE_TIMEOUT	超时时间（秒）	否
CI	标识 CI 环境	自动设置

安全存储 API Key

在 GitHub Actions 中：

Settings → Secrets and variables → Actions → New repository secret
Name: ANTHROPIC_API_KEY
Value: sk-ant-xxxxx

在 GitLab CI 中：

Settings → CI/CD → Variables
Key: ANTHROPIC_API_KEY
Value: sk-ant-xxxxx
Protected: Yes
Masked: Yes

成本控制

CI 中的 Claude Code 调用可能产生大量费用。这里有几个控制成本的方法：

1. 限制触发条件

# 只在特定文件变更时触发
on:
  pull_request:
    paths:
      - 'src/**'
      - '!src/**/*.test.ts'
      - '!src/**/*.md'

2. 使用更便宜的模型

# CI 中用 Haiku 做简单检查
claude --print --model claude-haiku-4-20250514 "检查代码格式"

# 只在需要深度分析时用 Sonnet
claude --print --model claude-sonnet-4-20250514 "审查安全漏洞"

3. 缓存结果

- name: Cache Review Results
  uses: actions/cache@v4
  with:
    path: .claude-cache
    key: claude-review-${{ hashFiles('src/**') }}

- name: AI Review
  run: |
    if [ ! -f .claude-cache/review.md ]; then
      claude --print "审查代码" > .claude-cache/review.md
    fi

4. 设置 Token 上限

claude --print --max-tokens 2048 "简要审查代码变更"

调试技巧

本地模拟 CI 环境

# 模拟 CI 环境变量
export CI=true
export ANTHROPIC_API_KEY="your-key"

# 运行和 CI 相同的命令
claude --print "你的 CI 任务"

查看详细输出

# JSON 格式输出包含更多调试信息
claude --print --output-format json "任务" | jq .

常见问题排查

问题	原因	解决方案
认证失败	API Key 未设置或无效	检查 ANTHROPIC_API_KEY 环境变量
超时	任务太复杂或网络问题	增加超时时间或简化任务
权限不足	工具被限制	检查 allowedTools 配置
输出为空	模型没有生成内容	检查提示是否清晰

完整 CI 工作流示例

这是一个综合的 CI 工作流，包含代码审查、自动修复和报告生成：

name: AI-Powered CI

on:
  pull_request:
    branches: [main]
    paths:
      - 'src/**'
      - 'tests/**'

env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

jobs:
  # 第一步：代码质量检查
  quality-check:
    runs-on: ubuntu-latest
    outputs:
      has-issues: ${{ steps.check.outputs.has-issues }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm install -g @anthropic-ai/claude-code

      - name: AI Quality Check
        id: check
        run: |
          RESULT=$(claude --print --output-format json \
            "检查 src/ 目录的代码质量，关注：
            1. TypeScript 类型安全
            2. 未处理的错误
            3. 潜在的内存泄漏
            以 JSON 格式返回 {hasIssues: boolean, issues: []}")

          HAS_ISSUES=$(echo "$RESULT" | jq -r '.text' | jq -r '.hasIssues')
          echo "has-issues=$HAS_ISSUES" >> $GITHUB_OUTPUT

  # 第二步：安全审查
  security-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code

      - name: Security Review
        run: |
          claude --print \
            --model claude-sonnet-4-20250514 \
            "对 src/ 目录进行安全审查：
            1. 检查是否有硬编码的密钥
            2. 检查 SQL 注入风险
            3. 检查 XSS 风险
            4. 检查不安全的依赖使用
            输出 Markdown 格式的安全报告" > security-report.md

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: security-report
          path: security-report.md

  # 第三步：汇总报告
  summary:
    needs: [quality-check, security-review]
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - name: Download Reports
        uses: actions/download-artifact@v4

      - name: Post Summary
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            let comment = '## CI Report\n\n';

            if (fs.existsSync('security-report/security-report.md')) {
              const security = fs.readFileSync('security-report/security-report.md', 'utf8');
              comment += `### Security Review\n${security}\n\n`;
            }

            comment += `### Quality Check\n`;
            comment += `Has Issues: ${{ needs.quality-check.outputs.has-issues }}\n`;

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: comment
            });

Headless 模式让 Claude Code 从”开发者的助手”变成了”团队的基础设施”。把它集成到 CI/CD 中，每一个 PR 都能得到 AI 的审查，每一次发布都有智能的 Changelog——这不是未来，这是现在就能实现的工作流。

加载中...