自动化与 CI/CD

完整掌握 Claude Code 无头模式 — 参数参考、5 个 CI/CD 实战、Docker 隔离、会话恢复与 Codex 对比

自动化与 CI/CD ¶

Claude Code 支持无头（headless）模式，可在脚本、CI/CD 管线和自动化工作流中使用，无需人工交互。本文涵盖完整参数参考和多个实战场景。

一、基本用法 ¶

单次执行（-p 模式）¶

# 基本执行
claude -p "分析这个项目的架构"

# JSON 输出格式
claude -p "列出所有 TODO 注释" --output-format json

# 限制执行轮次
claude -p "为 UserService 编写单元测试" --max-turns 5

# 指定模型
claude -p "审查代码安全" --model claude-opus-4-6

限制可用工具 ¶

# 只读分析（不允许写入和执行）
claude -p "分析代码质量" --allowedTools Read,Glob,Grep

# 允许读写（不允许执行命令）
claude -p "重构这个文件" --allowedTools Read,Write,Edit,Glob,Grep

# 全部工具（受控环境）
claude -p "修复 lint 错误" --allowedTools Read,Write,Edit,Bash,Glob,Grep

跳过权限提示 ¶

# 仅在安全的隔离环境中使用！
claude -p "修复所有 lint 错误并提交" --dangerously-skip-permissions

安全警告：--dangerously-skip-permissions 跳过所有权限确认，仅在 Docker 容器或 CI 隔离环境中使用。

二、完整参数参考 ¶

执行控制 ¶

参数	说明	示例
`-p "prompt"`	无头模式，执行单次任务	`claude -p "分析架构"`
`--bare`	最小模式，跳过 hooks/LSP/plugins	`claude --bare -p "..."`
`--max-turns N`	限制最大交互轮次	`--max-turns 5`
`--model MODEL`	指定模型	`--model claude-opus-4-6`
`--dangerously-skip-permissions`	跳过所有权限确认	仅隔离环境

输出格式 ¶

参数	说明	适用场景
`--output-format text`	纯文本（默认）	人类阅读
`--output-format json`	结构化 JSON	脚本解析
`--output-format stream-json`	流式 JSON	实时处理

工具限制 ¶

参数	说明
`--allowedTools Tool1,Tool2`	仅允许指定工具

可用工具名：Read、Write、Edit、Bash、Glob、Grep、WebFetch、WebSearch、Agent、NotebookEdit

会话管理 ¶

参数	说明
`--session-id ID`	指定会话 ID
`--resume`	恢复之前的会话

环境变量 ¶

变量	说明
`ANTHROPIC_BASE_URL`	API 端点（QCode.cc: `http://103.236.53.153/api`）
`ANTHROPIC_AUTH_TOKEN`	API 密钥（`cr_` 开头）
`CLAUDE_CODE_MAX_TURNS`	默认最大轮次
`CLAUDE_CODE_OUTPUT_FORMAT`	默认输出格式
`CLAUDE_MODEL`	默认模型

三、CI/CD 实战 ¶

实战 1：GitHub Actions — AI 代码审查 ¶

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 获取完整历史，用于 diff

      - 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: AI Code Review
        env:
          ANTHROPIC_BASE_URL: "http://103.236.53.153/api"
          ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
        run: |
          # 获取 PR 变更文件
          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)

          claude -p "请审查以下文件的代码变更，重点关注：
          1. 安全漏洞（SQL 注入、XSS、敏感信息泄露）
          2. 性能问题（N+1 查询、内存泄漏）
          3. 逻辑错误
          4. 代码风格问题

          变更文件：
          $FILES" \
            --output-format json \
            --max-turns 3 \
            --model claude-sonnet-4-6 \
            --allowedTools Read,Glob,Grep \
            > review.json

          echo "Review completed"
          cat review.json | jq -r '.result' || cat review.json

实战 2：自动生成测试 ¶

name: Auto Generate Tests
on:
  push:
    paths: ['src/**/*.ts', '!src/**/*.test.ts']

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: |
          npm ci
          npm install -g @anthropic-ai/claude-code

      - name: Generate missing tests
        env:
          ANTHROPIC_BASE_URL: "http://103.236.53.153/api"
          ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
        run: |
          claude -p "检查 src/ 下的 .ts 文件，为缺少测试的文件生成单元测试。
          使用 Vitest + Testing Library。
          测试文件命名为 xxx.test.ts，放在同目录下。
          目标覆盖率 80%+。" \
            --max-turns 10 \
            --allowedTools Read,Write,Glob,Grep,Bash \
            --dangerously-skip-permissions

      - name: Run tests
        run: npx vitest --run

      - name: Create PR with tests
        if: success()
        run: |
          git config user.name "claude-bot"
          git config user.email "bot@qcode.cc"
          git checkout -b auto-tests-$(date +%s)
          git add '*.test.ts'
          git commit -m "test: auto-generated unit tests" || exit 0
          git push origin HEAD

实战 3：代码质量门禁 ¶

name: Code Quality Gate
on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4

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

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

      - name: Quality Analysis
        env:
          ANTHROPIC_BASE_URL: "http://103.236.53.153/api"
          ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
        run: |
          claude -p "分析代码质量，输出 JSON 格式：
          {
            \"score\": 0-100,
            \"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
            \"summary\": \"一句话总结\"
          }

          评分标准：

          - 类型安全（20分）
          - 错误处理（20分）
          - 测试覆盖（20分）
          - 代码可读性（20分）
          - 安全性（20分）" \
            --output-format json \
            --max-turns 3 \
            --model claude-sonnet-4-6 \
            --allowedTools Read,Glob,Grep \
            > quality.json

      - name: Check score
        run: |
          SCORE=$(cat quality.json | jq -r '.result' | jq -r '.score // 0')
          echo "Quality score: $SCORE"
          if [ "$SCORE" -lt 60 ]; then
            echo "Quality gate failed: score $SCORE < 60"
            exit 1
          fi

实战 4：自动生成 Changelog ¶

#!/bin/bash
# generate-changelog.sh — 基于 Git 提交自动生成 Changelog

export ANTHROPIC_BASE_URL="http://103.236.53.153/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

# 获取上次 tag 以来的提交
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
  COMMITS=$(git log --oneline -20)
else
  COMMITS=$(git log --oneline ${LAST_TAG}..HEAD)
fi

claude -p "基于以下 Git 提交记录，生成结构化的 Changelog：

$COMMITS

格式要求：
## [版本号] - $(date +%Y-%m-%d)
### 新功能
### 修复
### 改进
### 破坏性变更（如有）

用中文撰写，风格简洁专业。" \
  --output-format text \
  --max-turns 2 \
  --model claude-sonnet-4-6 \
  --allowedTools Read,Glob,Grep

实战 5：自动文档更新 ¶

#!/bin/bash
# update-docs.sh — 代码变更后自动更新 API 文档

export ANTHROPIC_BASE_URL="http://103.236.53.153/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

claude -p "检查 src/api/ 下的路由文件，对比 docs/api.md 中的文档。
找出文档中缺失或过时的 API 描述，自动更新 docs/api.md。
保持现有文档格式和风格。" \
  --max-turns 8 \
  --allowedTools Read,Write,Edit,Glob,Grep

四、Docker 隔离环境 ¶

在 CI/CD 中使用 --dangerously-skip-permissions 时，强烈建议在 Docker 容器中运行：

FROM node:22-slim

# 安装 Claude Code
RUN npm install -g @anthropic-ai/claude-code

# 安装项目依赖
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

# 设置 QCode.cc 环境变量
ENV ANTHROPIC_BASE_URL=http://103.236.53.153/api
# ANTHROPIC_AUTH_TOKEN 通过运行时注入

# 非 root 用户运行
RUN useradd -m claude
USER claude

CMD ["claude", "-p", "执行代码审查", "--dangerously-skip-permissions", "--max-turns", "5"]

运行：

docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci

五、会话恢复与多步流水线 ¶

多步骤任务 ¶

# 步骤 1：分析
claude -p "分析项目架构" \
  --session-id "pipeline-42" \
  --output-format json \
  --max-turns 3 \
  --allowedTools Read,Glob,Grep

# 步骤 2：基于分析结果生成方案
claude -p "基于上次分析，制定重构方案" \
  --resume --session-id "pipeline-42" \
  --max-turns 3

# 步骤 3：执行方案
claude -p "执行重构方案的第一步" \
  --resume --session-id "pipeline-42" \
  --max-turns 10 \
  --allowedTools Read,Write,Edit,Bash,Glob,Grep

六、成本控制 ¶

策略 1：限制轮次 ¶

# 简单任务 3 轮够用
claude -p "快速分析" --max-turns 3

# 复杂任务最多 10 轮
claude -p "全面重构" --max-turns 10

策略 2：选择合适的模型 ¶

场景	推荐模型	原因
代码审查	Sonnet	够用且便宜
安全扫描	Opus	需要深度分析
批量格式化	Haiku	最便宜
测试生成	Sonnet	性价比最佳

claude -p "格式化代码" --model claude-haiku-4-5 --max-turns 3

策略 3：限制工具减少 token 消耗 ¶

# 只读分析 → 不会产生多轮写入/测试的消耗
claude -p "分析代码" --allowedTools Read,Glob,Grep --max-turns 3

七、与 Codex 无头模式对比 ¶

维度	Claude Code -p	Codex headless
参数	`-p "prompt"`	`codex -q "prompt"`
沙箱	需 Docker 隔离	内置内核级沙箱
输出格式	text/json/stream-json	text/json
会话恢复	`--resume --session-id`	不支持
工具限制	`--allowedTools`	`--approval-mode`
并行执行	不支持	`codex cloud exec`