# 自动化与 CI/CD

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

---

## 一、基本用法

### 单次执行（-p 模式）

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

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

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

# 指定模型（日常可用 claude-sonnet-5；4.x 仍在售）
claude -p "审查代码安全" --model claude-opus-5
```

### 限制可用工具

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

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

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

### 跳过权限提示

```bash
# 仅在安全的隔离环境中使用！
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-5` |
| `--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: `https://api.qcode.cc/api`） |
| `ANTHROPIC_AUTH_TOKEN` | API 密钥（`cr_` 开头） |
| `CLAUDE_CODE_MAX_TURNS` | 默认最大轮次 |
| `CLAUDE_CODE_OUTPUT_FORMAT` | 默认输出格式 |
| `CLAUDE_MODEL` | 默认模型 |

---

## 三、CI/CD 实战

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

```yaml
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: "https://api.qcode.cc/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-5 \
            --allowedTools Read,Glob,Grep \
            > review.json

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

### 实战 2：自动生成测试

```yaml
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: "https://api.qcode.cc/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：代码质量门禁

```yaml
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: "https://api.qcode.cc/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-5 \
            --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

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

export ANTHROPIC_BASE_URL="https://api.qcode.cc/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-5 \
  --allowedTools Read,Glob,Grep
```

### 实战 5：自动文档更新

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

export ANTHROPIC_BASE_URL="https://api.qcode.cc/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 容器中运行：

```dockerfile
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=https://api.qcode.cc/api
# ANTHROPIC_AUTH_TOKEN 通过运行时注入

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

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

运行：

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

---

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

### 多步骤任务

```bash
# 步骤 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：限制轮次

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

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

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

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

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

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

```bash
# 只读分析 → 不会产生多轮写入/测试的消耗
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` |

**配合使用**：Claude Code 做分析和规划（只读），Codex 做执行（全自动）。

> QCode.cc 套餐共享配额，两个工具在 CI 中切换零成本。

---

## 八、最佳实践清单

1. **始终限制轮次**：CI 中用 `--max-turns` 防止无限执行
2. **限制工具**：用 `--allowedTools` 只开放必要的工具
3. **Docker 隔离**：使用 `--dangerously-skip-permissions` 时必须在容器中
4. **JSON 输出**：自动化场景推荐 `--output-format json` 方便解析
5. **成本控制**：分析用 Sonnet，简单任务用 Haiku
6. **幂等性**：确保任务可重复执行不会产生副作用
7. **超时保护**：CI 管线设置 job timeout（如 10 分钟）
8. **密钥管理**：API 密钥用 CI secrets，不硬编码

---

## 下一步

- [Hooks 系统](/docs/advanced/hooks) — 自动触发操作
- [CLI 技巧](/docs/usage/cli-tips) — 更多命令行用法
- [费用优化](/docs/usage/cost-optimization) — 控制成本技巧
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — 从零到精通