Claude Code 无头模式与 CI/CD 集成

来源：code.claude.com/docs/en/headless · github-actions | 整理时间：2026-04-04

概述

Claude Code 不仅可以在终端交互使用，还支持无头模式（Headless Mode）——通过命令行或 API 以非交互方式运行，适合 CI/CD 管道、批量处理和自动化工作流。

无头模式基础

基本命令

# 最简单的无头调用
claude -p "Explain what this project does"

# JSON 输出（适合脚本处理）
claude -p "List all API endpoints" --output-format json

# 流式 JSON（实时获取输出）
claude -p "Analyze this log file" --output-format stream-json

# 限制可用工具
claude -p "Fix all lint errors" --allowedTools "Edit,Bash(npm run lint)"

关键参数

权限模式

# 自动模式：Claude 自行判断是否执行命令
claude --permission-mode auto -p "fix all lint errors"

# 计划模式：只读不写
claude --permission-mode plan -p "analyze the codebase architecture"

# 指定允许的 Bash 命令模式
claude -p "run tests" --allowedTools "Bash(npm test)" --permission-mode auto

SDK 编程调用

TypeScript

import { query } from "@anthropic-ai/claude-code";

const result = await query({
  prompt: "Explain the authentication flow in this codebase",
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Glob"],
    outputFormat: "json",
  },
});

console.log(result);

Python

from claude_code import query

result = query(
    prompt="Generate a README for this project",
    options={
        "max_turns": 3,
        "allowed_tools": ["Read", "Glob"],
    }
)
print(result)

批量处理

# 批量处理多个文件
for file in src/**/*.test.ts; do
  claude -p "Improve the test coverage of $file. Return OK or FAIL." \
    --allowedTools "Edit,Read,Bash(npm test)" \
    --permission-mode auto \
    --max-turns 20
done

GitHub Actions 集成

基本配置

在 PR 中 @claude 提及即可触发：

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  issue_comment:
    types: [created]

jobs:
  review:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

触发方式

自动 PR 审查

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

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this PR for:
            - Security vulnerabilities
            - Performance issues
            - Code style consistency
            - Missing tests
          max_turns: 10

Issue 自动处理

name: Auto Fix Issues
on:
  issues:
    types: [labeled]

jobs:
  fix:
    if: contains(github.event.label.name, 'auto-fix')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Read issue #${{ github.event.issue.number }} and fix it.
            Create a new branch, implement the fix, and open a PR.

GitLab CI/CD 集成

# .gitlab-ci.yml
claude-review:
  stage: review
  image: node:20
  script:
    - npm install -g @anthropic-ai/claude-code
    - claude -p "Review the changes in this MR" --output-format json
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

支持 AWS Bedrock 和 Google Vertex AI 作为模型提供商。

安全最佳实践

1. 使用最小权限

# 只允许读取和编辑，不执行任意命令
claude -p "refactor" --allowedTools "Edit,Read,Grep,Glob" --permission-mode auto

2. 限制 Bash 命令范围

# 只允许特定 Bash 命令
claude -p "run tests" --allowedTools "Bash(npm test),Bash(npm run lint)" --permission-mode auto

3. 使用沙盒环境

# 在 Docker 容器中运行
docker run --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY \
  claude-code-image \
  claude -p "analyze the codebase" --bare

4. 限制轮数

# 限制最大轮数，防止失控
claude -p "fix the bug" --max-turns 10 --permission-mode auto

5. 使用作用域令牌

# 为 CI/CD 创建专用的 API Key
# 在 GitHub/GitLab 中使用 Secrets 管理

实际使用案例

案例 1：每日代码质量检查

name: Daily Code Quality
on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analyze the codebase for:
            1. Dead code that can be removed
            2. Dependencies that need updating
            3. Performance bottlenecks
            Create issues for any findings.

案例 2：自动化迁移

# 批量迁移文件（使用 exit code 判断成功）
for file in $(find src -name "*.js"); do
  if claude -p "Convert $file from CommonJS to ES Modules" \
     --allowedTools "Edit,Read" \
     --max-turns 5 \
     --bare; then
    echo "OK: $file"
  else
    echo "FAIL: $file"
  fi
done

案例 3：安全审查流水线

name: Security Review
on: [push]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Perform a security review:
            - SQL injection
            - XSS vulnerabilities
            - Hardcoded secrets
            - Insecure dependencies
            Block the PR if critical issues found.

相关链接

• 最佳实践
• 多 Agent 协作
• 技能与钩子
• 无头模式文档：https://code.claude.com/docs/en/headless
• GitHub Actions 文档：https://code.claude.com/docs/en/github-actions
• GitLab CI/CD 文档：https://code.claude.com/docs/en/gitlab-ci-cd
• SDK 文档：https://code.claude.com/docs/en/sdk
• 生产基础设施示例：https://github.com/diet103/claude-code-infrastructure-showcase