系列文章
本篇是 Claude Code 系列的第 7 篇。系列将从安装入门到高级实战,由浅入深地拆解这个终端原生 Coding Agent 的每一个能力。
入门篇
- Claude Code 是什么?从安装到第一次对话
- 日常开发工作流:用 Claude Code 重塑你的编码习惯
核心篇
3. 内置命令全解:从 /compact 到 /doctor 的实战指南
4. CLAUDE.md:项目上下文工程的艺术
进阶篇
5. 多文件重构与复杂任务实战
6. Hooks、MCP 与能力扩展
高级篇
7. Headless 模式与 CI/CD 集成(本文)
8. 多 Agent 协作:从 Claude Code 到 Codex
引言:当 AI Agent 走出终端
在前六篇文章中,我们一直在交互模式下使用 Claude Code——打开终端,输入 claude,然后和它对话。这种模式适合日常开发:你提问,它回答;你下指令,它执行。
但有一个场景,交互模式完全无法覆盖:自动化。
想象这些需求:
- 每次 PR 提交时,自动让 Claude Code 审查代码并生成评审意见
- 每天定时扫描项目依赖,检查是否有安全漏洞
- Issue 被创建时,自动分析问题描述并生成修复方案
- CI 流水线中,自动检查代码风格并生成改进建议
这些场景有一个共同特点:没有人类坐在终端前。Claude Code 需要以”无人值守”的方式运行——接收输入,处理任务,输出结果,然后退出。
这就是 Headless 模式(无头模式)的意义。
一、什么是 Headless 模式?
1.1 从交互到自动化的跨越
Headless 模式是 Claude Code 的非交互运行方式。它不需要你坐在终端前打字,而是通过命令行参数一次性传入任务,执行完毕后自动退出。
类比一下:如果交互模式是和 Claude 面对面聊天,那 Headless 模式就是给 Claude 留一张便签,它做完把结果放在桌上。
核心命令就一个:
-p 是 --print 的缩写,意思是”打印结果然后退出”。这个看似简单的标志,打开了一扇通往自动化的大门。
1.2 为什么需要 Headless 模式?
从工程角度看,Headless 模式解决的是 AI Agent 的可编程性 问题。
交互模式下,Claude Code 的输入输出是人类可读的自然语言。但在自动化场景中,你需要:
- 可管道化:输出可以被其他程序解析
- 可参数化:任务可以通过变量动态构造
- 可退出码:执行结果可以通过进程退出码判断
- 无状态化:每次调用是独立的,不依赖之前的对话
Headless 模式把这些需求全部满足了。
二、-p 标志:Headless 模式的核心
2.1 基本用法
最简单的用法——传入一个任务,拿到结果:
Claude Code 会读取当前目录的项目上下文,执行任务,把结果打印到 stdout,然后退出。
2.2 管道输入:处理外部数据
Headless 模式的强大之处在于它可以接收管道输入。这意味着你可以把任何程序的输出喂给 Claude Code:
1 2 3 4 5 6 7 8 9 10 11
| cat application.log | claude -p "找出最近 10 分钟内的所有 ERROR 日志,按模块分组"
git diff HEAD~1 | claude -p "审查这个 commit 的代码变更,指出潜在问题"
cat test-report.xml | claude -p "总结测试失败的原因,给出修复建议"
mvn clean compile 2>&1 | claude -p "分析编译错误,给出修复方案"
|
管道输入的本质是扩展了 Claude Code 的感知范围——它不再局限于项目文件,而是可以处理任何数据流。
2.3 输出格式:让机器可读
默认情况下,-p 输出的是人类可读的文本。但在自动化场景中,你需要机器可解析的格式。Claude Code 提供了三种输出格式:
1 2 3 4 5 6 7 8
| claude -p "列出所有 TODO 注释"
claude -p "列出所有 TODO 注释" --output-format json
claude -p "列出所有 TODO 注释" --output-format stream-json
|
JSON 输出结构:
1 2 3 4 5 6 7 8
| { "result": "项目中共有 12 个 TODO 注释...", "session_id": "abc123-def456", "duration_ms": 3420, "total_cost": 0.0023, "num_turns": 1, "tools_used": ["Read", "Grep"] }
|
这个结构包含了执行结果、会话 ID、耗时、成本、使用的工具等信息——这些都是自动化流水线需要的元数据。
流式 JSON 则更适合实时监控场景。它逐行输出每个事件(工具调用、中间结果、最终回答),你可以用 jq 实时解析:
1 2 3 4 5 6
| claude -p "分析代码" --output-format stream-json | while IFS= read -r line; do type=$(echo "$line" | jq -r '.type') if [ "$type" = "tool_use" ]; then echo "正在使用工具: $(echo "$line" | jq -r '.tool')" fi done
|
三、会话管理:多轮自动化的基石
3.1 单次调用 vs 多轮对话
大多数自动化场景是”一问一答”式的——传入任务,拿到结果,结束。但有些场景需要多轮交互:
- 先分析代码结构,再根据分析结果生成测试用例
- 先审查 PR,再根据审查意见生成修复补丁
- 先扫描依赖,再针对漏洞生成升级方案
Claude Code 通过 会话管理 机制支持这类场景。
3.2 --session-id:指定会话
1 2 3 4 5
| claude -p "分析 src/main/java 目录的代码结构" --session-id "code-review-123"
claude -p "根据上面的分析,生成重构建议" --session-id "code-review-123"
|
通过 --session-id,你可以让两次调用共享同一个会话上下文。Claude Code 会记住第一轮的分析结果,第二轮可以直接引用。
3.3 -c:继续最近的会话
1 2 3 4 5
| claude -p "分析这个项目的测试覆盖率"
claude -c -p "根据覆盖率报告,生成缺失的测试用例"
|
-c 是 --continue 的缩写,它会自动找到当前目录最近的会话并继续。
3.4 -r:恢复指定会话
1 2
| claude -r "auth-refactor" "继续完成认证模块的重构"
|
-r 是 --resume 的缩写,支持通过会话 ID 或名称恢复。这在长时间运行的自动化任务中特别有用。
4.1 为什么需要安全控制?
在交互模式下,Claude Code 每次执行危险操作(写文件、执行命令)前都会征求你的同意。但在 Headless 模式下,没有人在旁边确认。
如果 Claude Code 在 CI/CD 流水线中执行了 rm -rf /,后果不堪设想。
这就是 --allowedTools 存在的意义——限定 Claude Code 可以使用的工具范围。
4.2 工具白名单
1 2 3 4 5 6 7 8
| claude -p "分析代码" --allowedTools "Read,Grep,Glob"
claude -p "重构代码" --allowedTools "Read,Write,Edit,Grep,Glob"
claude -p "执行任务" --dangerously-skip-permissions
|
常用工具名称:
Read:读取文件
Write:写入文件
Edit:编辑文件(精确替换)
Grep:搜索文件内容
Glob:按模式查找文件
Bash:执行终端命令
WebFetch:获取网页内容
4.3 生产环境的安全实践
在 CI/CD 流水线中,推荐最小权限原则:
1 2 3 4 5 6
| - name: Code Review run: | claude -p "审查代码变更" \ --allowedTools "Read,Grep,Glob" \ --output-format json
|
只给读取权限,不给写入和执行权限。这样即使 Claude Code 的行为不符合预期,也不会对系统造成破坏。
五、GitHub Actions 集成:实战配置
5.1 基础配置:PR 自动审查
这是最常见的 CI/CD 集成场景——每次 PR 提交时,自动让 Claude Code 审查代码:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
| name: Claude Code Review
on: pull_request: types: [opened, synchronize]
jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write
steps: - name: Checkout code uses: actions/checkout@v4 with: fetch-depth: 0
- name: Install Claude Code run: | curl -fsSL https://claude.ai/install.sh | bash
- name: Get PR diff id: diff run: | git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr-diff.txt echo "diff_file=/tmp/pr-diff.txt" >> $GITHUB_OUTPUT
- name: Run Claude Code Review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | REVIEW=$(cat ${{ steps.diff.outputs.diff_file }} | claude -p " 审查这个 PR 的代码变更。 请关注: 1. 潜在的 bug 和逻辑错误 2. 代码风格和最佳实践 3. 性能问题 4. 安全漏洞 输出格式: ## 审查总结 [一句话总结] ## 问题列表 - [严重程度] 问题描述 - 文件:xxx - 行号:xxx - 建议:xxx " --allowedTools "Read,Grep,Glob" --output-format text) echo "review<<EOF" >> $GITHUB_OUTPUT echo "$REVIEW" >> $GITHUB_OUTPUT echo "EOF" >> $GITHUB_OUTPUT
- name: Post PR Comment uses: actions/github-script@v7 with: script: | const review = `${{ steps.review.outputs.review }}`; await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body: `## 🤖 Claude Code 自动审查\n\n${review}` });
|
5.2 进阶配置:多任务流水线
更复杂的场景——一个流水线中执行多个 Claude Code 任务:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
| name: Claude Code Pipeline
on: push: branches: [main, develop]
jobs: pipeline: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
- name: Install Claude Code run: curl -fsSL https://claude.ai/install.sh | bash
- name: Code Analysis env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | # 任务 1:代码质量分析 claude -p "分析 src/ 目录的代码质量,输出 JSON 格式的报告" \ --allowedTools "Read,Grep,Glob" \ --output-format json > reports/quality.json
- name: Security Scan env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | # 任务 2:安全扫描 claude -p "检查项目中是否有硬编码的密钥、密码或敏感信息" \ --allowedTools "Read,Grep,Glob" \ --output-format json > reports/security.json
- name: Generate Tests env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | # 任务 3:生成测试用例 claude -p "为 src/main/java/service/ 目录下的所有 Service 类生成单元测试" \ --allowedTools "Read,Write,Edit,Grep,Glob" \ --output-format text > reports/tests.md
- name: Upload Reports uses: actions/upload-artifact@v4 with: name: claude-reports path: reports/
|
5.3 环境变量配置
在 CI/CD 中使用 Claude Code,需要配置以下环境变量:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
| env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} CLAUDE_CODE_USE_BEDROCK: 1 AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} CLAUDE_CODE_USE_VERTEX: 1 CLOUD_ML_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }} ANTHROPIC_BASE_URL: https://your-proxy.example.com
|
六、GitLab CI 集成
6.1 基础配置
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
| stages: - review - test - deploy
claude-review: stage: review image: ubuntu:latest before_script: - apt-get update && apt-get install -y curl - curl -fsSL https://claude.ai/install.sh | bash script: - | git diff origin/main...HEAD > /tmp/diff.txt REVIEW=$(cat /tmp/diff.txt | claude -p " 审查代码变更,重点关注: 1. 逻辑错误和潜在 bug 2. 代码风格问题 3. 性能和安全问题 输出简洁的审查意见。 " --allowedTools "Read,Grep,Glob" --output-format text) echo "$REVIEW" variables: ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY only: - merge_requests
|
6.2 高级用法:MR 自动评论
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
| claude-comment: stage: review image: ubuntu:latest before_script: - apt-get update && apt-get install -y curl jq - curl -fsSL https://claude.ai/install.sh | bash script: - | # 获取 MR diff git diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME...HEAD > /tmp/diff.txt REVIEW=$(cat /tmp/diff.txt | claude -p "审查代码变更" \ --allowedTools "Read,Grep,Glob" \ --output-format json | jq -r '.result') curl --request POST \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ --data-urlencode "body=## 🤖 Claude Code 审查\n\n$REVIEW" \ "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" only: - merge_requests
|
七、自动化模式实战
7.1 PR 审查机器人
这是最实用的自动化模式。核心逻辑:
- 触发:PR 创建或更新时
- 获取变更:
git diff 获取代码差异
- 审查:Claude Code 分析变更并生成意见
- 反馈:将审查意见作为 PR 评论发表
关键点是提示词的设计。好的提示词应该:
- 明确审查维度(bug、风格、性能、安全)
- 指定输出格式(方便解析)
- 限制审查范围(只看变更,不看整个项目)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
| REVIEW_PROMPT=" 你是一个资深 Java 开发者,负责审查 Spring Boot 项目的代码变更。
审查维度: 1. **逻辑错误**:空指针、数组越界、并发问题 2. **代码风格**:命名规范、注释完整性、方法长度 3. **性能问题**:N+1 查询、不必要的对象创建、循环中的数据库操作 4. **安全漏洞**:SQL 注入、XSS、硬编码密钥
输出格式: ### 审查总结 [一句话总结变更的影响]
### 问题列表 | 严重程度 | 文件 | 行号 | 问题 | 建议 | |---------|------|------|------|------| | ... | ... | ... | ... | ... |
只列出真正需要修复的问题,不要吹毛求疵。 "
git diff HEAD~1 | claude -p "$REVIEW_PROMPT" \ --allowedTools "Read,Grep,Glob" \ --output-format text
|
7.2 Issue 分析与自动分配
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
| name: Issue Triage
on: issues: types: [opened]
jobs: triage: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Analyze Issue env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | ISSUE_BODY="${{ github.event.issue.body }}" ANALYSIS=$(claude -p " 分析这个 GitHub Issue: 标题:${{ github.event.issue.title }} 内容:$ISSUE_BODY 请判断: 1. 这是什么类型的问题?(bug/feature/question/documentation) 2. 涉及哪些模块? 3. 优先级如何?(P0/P1/P2/P3) 4. 建议分配给谁?(根据 CODEOWNERS 文件) 输出 JSON 格式。 " --allowedTools "Read,Grep,Glob" --output-format json) echo "$ANALYSIS" | jq -r '.result' > /tmp/triage.json - name: Apply Labels uses: actions/github-script@v7 with: script: | const fs = require('fs'); const triage = JSON.parse(fs.readFileSync('/tmp/triage.json', 'utf8')); // 根据分析结果添加标签 const labels = [triage.type, triage.priority]; await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, labels: labels });
|
7.3 定时依赖扫描
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
| name: Dependency Scan
on: schedule: - cron: '0 9 * * 1'
jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Scan Dependencies env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | # 生成依赖报告 mvn dependency:tree > /tmp/deps.txt REPORT=$(claude -p " 分析项目的 Maven 依赖树: $(cat /tmp/deps.txt) 请检查: 1. 是否有已知的安全漏洞版本? 2. 是否有过时的依赖可以升级? 3. 是否有不必要的依赖? 4. 依赖冲突风险? 输出结构化的安全报告。 " --allowedTools "Read,Grep,Glob" --output-format json) echo "$REPORT" | jq -r '.result' > /tmp/security-report.md - name: Create Issue if: contains(steps.scan.outputs.report, 'vulnerability') uses: actions/github-script@v7 with: script: | const fs = require('fs'); const report = fs.readFileSync('/tmp/security-report.md', 'utf8'); await github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: '🔒 依赖安全扫描报告', body: report, labels: ['security', 'dependencies'] });
|
八、Headless 模式的设计哲学
8.1 Unix 哲学的体现
Headless 模式的设计深受 Unix 哲学影响:
- 单一职责:
-p 只做一件事——执行任务并输出结果
- 可组合性:输出可以通过管道传递给其他程序
- 文本流:默认输出是纯文本,符合 Unix 工具的传统
- 退出码:通过进程退出码表示成功或失败
1 2 3 4 5
| git diff HEAD~1 \ | claude -p "审查代码" --allowedTools "Read,Grep,Glob" \ | tee review.txt \ | mail -s "Code Review" team@example.com
|
8.2 与传统 CI 工具的互补
Claude Code 不是要替代传统的 CI 工具(SonarQube、Checkmarx、Dependabot),而是补充它们无法覆盖的领域:
| 维度 |
传统工具 |
Claude Code |
| 代码风格 |
规则匹配 |
理解语义 |
| 逻辑错误 |
静态分析 |
上下文推理 |
| 架构问题 |
无法检测 |
可以分析 |
| 文档生成 |
模板化 |
智能生成 |
| 测试用例 |
覆盖率统计 |
自动生成 |
传统工具擅长确定性检查(规则明确、结果可预测),Claude Code 擅长模糊推理(需要理解上下文、业务逻辑)。
8.3 成本与效率的权衡
Headless 模式的一个重要考量是成本。每次调用 Claude Code 都会产生 API 费用。
优化策略:
- 限制上下文:用
--allowedTools 限制工具范围,减少不必要的文件读取
- 精简提示词:冗长的提示词会消耗更多 token
- 增量处理:只处理变更的部分(
git diff),而不是整个项目
- 缓存结果:相同代码的审查结果可以缓存,避免重复调用
1 2 3 4 5
| CHANGED_FILES=$(git diff --name-only HEAD~1) for file in $CHANGED_FILES; do cat "$file" | claude -p "审查这个文件" --allowedTools "Read" done
|
九、与其他工具的对比
9.1 GitHub Copilot CLI
GitHub Copilot CLI 也支持 CI/CD 集成,但定位不同:
| 特性 |
Claude Code |
Copilot CLI |
| 核心能力 |
自主 Agent |
代码补全 |
| 文件操作 |
完整支持 |
有限支持 |
| 命令执行 |
完整支持 |
有限支持 |
| 多文件编辑 |
原生支持 |
需要多轮 |
| 输出格式 |
text/json/stream-json |
有限 |
| 会话管理 |
完整支持 |
基础支持 |
Claude Code 的优势在于自主性——它可以独立完成复杂的多步骤任务,而不仅仅是补全代码。
9.2 Cursor Background Agent
Cursor 的 Background Agent 也能在 CI/CD 中运行,但它是绑定在 Cursor IDE 生态中的。Claude Code 是独立的 CLI 工具,可以在任何支持 Node.js 的环境中运行。
9.3 自建 AI 流水线
你也可以用 Anthropic API 直接构建 AI 流水线,但 Claude Code 提供了开箱即用的工具链——文件读写、命令执行、代码搜索、会话管理,这些都需要自己实现。
十、生产环境的最佳实践
10.1 错误处理
1 2 3 4 5 6 7 8 9 10
| if claude -p "执行任务" --allowedTools "Read,Grep,Glob" --output-format json > /tmp/result.json; then echo "任务成功" RESULT=$(cat /tmp/result.json | jq -r '.result') else echo "任务失败,退出码: $?" curl -X POST https://hooks.slack.com/xxx -d '{"text":"Claude Code 任务失败"}' exit 1 fi
|
10.2 超时控制
1 2 3 4 5
| timeout 300 claude -p "执行任务" --allowedTools "Read,Grep,Glob" if [ $? -eq 124 ]; then echo "任务超时(5 分钟)" fi
|
10.3 日志记录
1 2
| claude -p "执行任务" --output-format stream-json 2>&1 | tee /var/log/claude-code/$(date +%Y%m%d-%H%M%S).log
|
10.4 监控与告警
1 2 3 4 5 6 7 8 9 10
| - name: Collect Metrics run: | RESULT=$(claude -p "执行任务" --output-format json) DURATION=$(echo "$RESULT" | jq -r '.duration_ms') COST=$(echo "$RESULT" | jq -r '.total_cost') echo "claude_code_duration_ms $DURATION" | curl --data-binary @- http://pushgateway:9091/metrics/job/claude_review echo "claude_code_cost_usd $COST" | curl --data-binary @- http://pushgateway:9091/metrics/job/claude_review
|
十一、边界与局限
11.1 不适合的场景
Headless 模式不是万能的。以下场景它不适合:
- 实时交互:需要人类实时决策的场景(如紧急故障处理)
- 高频调用:每秒多次调用会触发 API 限流
- 大规模并行:同时运行数百个 Claude Code 实例会超出配额
- 确定性任务:规则明确的任务用传统工具更可靠
11.2 已知的坑
- 上下文窗口限制:大型项目可能超出上下文窗口,需要分块处理
- API 稳定性:依赖 Anthropic API 的可用性
- 成本不可预测:复杂任务的 token 消耗难以预估
- 输出不一致:相同输入可能产生略有不同的输出
十二、未来展望
12.1 Agent SDK
Anthropic 已经发布了 Claude Code 的 Agent SDK,允许开发者构建自定义的 Agent 应用。这意味着未来你可以:
- 用 Python/TypeScript 编写自定义的 Agent 逻辑
- 将 Claude Code 的能力嵌入到自己的应用中
- 构建更复杂的多 Agent 协作系统
12.2 与 GitOps 的深度融合
随着 GitOps 的普及,Claude Code 可以成为 GitOps 流水线中的重要一环:
- 自动分析 Git 变更并生成部署建议
- 根据监控数据自动调整配置
- 在 PR 中自动添加 Helm Chart 的变更说明
12.3 智能化的 CI/CD
未来的 CI/CD 流水线可能不再是固定的 YAML 配置,而是由 AI 动态编排的:
- 根据代码变更的复杂度自动选择审查策略
- 根据历史数据预测部署风险
- 自动优化流水线的执行顺序
总结
Headless 模式是 Claude Code 从”开发工具”升级为”自动化平台”的关键一步。通过 -p 标志、输出格式控制、会话管理和安全限制,你可以把 Claude Code 无缝集成到任何 CI/CD 流水线中。
核心要点:
-p 标志是 Headless 模式的入口,支持管道输入和多种输出格式
- 会话管理让多轮自动化成为可能
--allowedTools 是生产环境的安全保障
- GitHub Actions / GitLab CI 集成已经非常成熟
- 提示词设计决定了自动化任务的质量
在下一篇文章中,我们将探讨 Claude Code 的终极形态——多 Agent 协作。当多个 Claude Code 实例协同工作时,会发生什么?敬请期待。