实战

Claude Code 非交互模式(Headless):脚本自动化与 CI/CD 集成实战

Claude Code Headless 非交互模式完整实战:基础 -p 参数用法、三大自动化脚本(PR 摘要/安全扫描/Changelog 生成)、GitHub Actions 集成(每 PR 自动审查/每周技术债务扫描)、输出格式控制与批量任务成本优化。

2026/3/145分钟 阅读ClaudeEagle

Claude Code 不只是一个交互式聊天工具——它支持完全的非交互(Headless)模式,可以嵌入到脚本、定时任务、CI/CD 流水线中,实现真正的编程自动化。

什么是 Headless 模式?

正常使用 Claude Code 是交互的:你输入,它回复,来回对话。

Headless 模式是一次性执行:输入一个任务,Claude Code 完成后退出,输出结果到 stdout。适合:

  • Shell 脚本中调用
  • GitHub Actions / GitLab CI
  • 定时任务(cron job)
  • 与其他命令行工具管道组合

基础用法

bash
# -p 参数:非交互执行后退出
claude -p "解释这个函数做什么"

# 指定工作目录
claude -p "列出所有 TODO 注释" --cwd /path/to/project

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

# 组合管道
git diff main | claude -p "检查这些改动有没有安全问题,用 JSON 输出"

常用自动化脚本

脚本 1:PR 自动摘要

bash
#!/bin/bash
# pr-summary.sh - 生成 PR 描述草稿

BRANCH=$(git branch --show-current)
DIFF=$(git diff main)

SUMMARY=$(echo "$DIFF" | claude -p "
根据这个 diff,生成一个 PR 描述:
- 标题(50字以内)
- 改了什么(3-5 条要点)
- 为什么这样改
- 如何测试

用 Markdown 格式输出
")

echo "## 自动生成的 PR 描述"
echo ""
echo "$SUMMARY"

用法:

bash
bash pr-summary.sh

脚本 2:代码安全扫描

bash
#!/bin/bash
# security-scan.sh - 扫描最近改动的安全问题

CHANGED_FILES=$(git diff --name-only HEAD~1)

if [ -z "$CHANGED_FILES" ]; then
  echo "没有改动"
  exit 0
fi

echo "扫描以下文件:$CHANGED_FILES"

RESULT=$(git diff HEAD~1 | claude -p "
分析这些代码改动,检查安全问题:
1. SQL 注入风险
2. XSS 漏洞
3. 硬编码密钥
4. 不安全的反序列化

以 JSON 格式输出:
{
  "issues": [
    {"severity": "high/medium/low", "file": "文件名", "line": 行号, "description": "描述", "fix": "修复建议"}
  ],
  "summary": "总体评价"
}

如果没有问题,issues 数组为空
")

echo "$RESULT" | python3 -c "
import json, sys
data = json.load(sys.stdin)
issues = data.get('issues', [])
if not issues:
    print('✅ 未发现安全问题')
    sys.exit(0)
for issue in issues:
    severity_icon = {'high': '🔴', 'medium': '🟡', 'low': '🟢'}.get(issue['severity'], '⚪')
    print(f"{severity_icon} [{issue['severity'].upper()}] {issue['file']}:{issue.get('line','?')}")
    print(f"   {issue['description']}")
    print(f"   修复:{issue['fix']}")
    print()
if any(i['severity'] == 'high' for i in issues):
    sys.exit(1)  # 有高危问题时返回非0,CI 会失败
"

脚本 3:自动生成 Changelog

bash
#!/bin/bash
# generate-changelog.sh - 根据 commit 生成 Changelog

SINCE=${1:-"v1.0.0"}  # 从哪个版本开始
UNTIL=${2:-"HEAD"}

COMMITS=$(git log $SINCE..$UNTIL --oneline --no-merges)

if [ -z "$COMMITS" ]; then
  echo "没有新的提交"
  exit 0
fi

CHANGELOG=$(echo "$COMMITS" | claude -p "
根据这些 git commit 生成 Changelog 条目。

格式(Keep a Changelog 规范):
## [Unreleased]

### Added
- 新增的功能

### Changed
- 变更的功能

### Fixed
- 修复的 Bug

### Deprecated / Removed / Security(如果适用)

只输出 Markdown 内容,不要解释
")

# 插入到 CHANGELOG.md 头部
TEMP=$(mktemp)
echo "$CHANGELOG" > "$TEMP"
echo "" >> "$TEMP"
tail -n +1 CHANGELOG.md >> "$TEMP"
mv "$TEMP" CHANGELOG.md

echo "✅ Changelog 已更新"

GitHub Actions 集成

每 PR 自动代码审查

.github/workflows/ai-review.yml

yaml
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: Install Claude Code
        run: curl -fsSL https://claude.ai/install.sh | bash
      
      - name: Run AI Review
        id: review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          REVIEW=$(echo "$DIFF" | claude -p "
          审查这个 PR 的代码改动,检查:
          1. 潜在 Bug(空值、边界条件)
          2. 安全问题(注入、认证)
          3. 性能影响
          4. 代码可读性
          
          只报告真正值得关注的问题(忽略风格问题)。
          用 Markdown 输出,分级标注 🔴 高 🟡 中 🟢 低
          ")
          echo "review=$REVIEW" >> $GITHUB_OUTPUT
      
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 AI 代码审查

${process.env.REVIEW}`
            })
        env:
          REVIEW: ${{ steps.review.outputs.review }}

每日技术债务扫描

.github/workflows/daily-scan.yml

yaml
name: Daily Tech Debt Scan

on:
  schedule:
    - cron: '0 9 * * 1'  # 每周一早 9 点

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Scan and Create Issue
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REPORT=$(find src -name "*.ts" -exec cat {} \; |             claude -p "分析这些代码,找出 Top 5 技术债务,简要说明影响和改造建议")
          
          gh issue create             --title "每周技术债务扫描 $(date +%Y-%m-%d)"             --body "$REPORT"             --label "tech-debt"

输出格式控制

bash
# 要求 JSON 输出(方便脚本解析)
claude -p "分析这段代码,以 JSON 输出:{bugs: [], suggestions: []}"

# 要求纯文本(不要 Markdown)
claude -p "总结这个函数,只返回纯文本,不要格式"

# 限制输出长度
claude -p "一句话总结这个函数" --max-tokens 50

成本控制

非交互模式每次都消耗 Token,批量任务注意成本:

bash
# 用 Haiku 做简单任务(便宜 10 倍)
claude -p "检查这行代码有没有语法错误" --model claude-haiku-3-5

# 用 Sonnet 做复杂分析
git diff | claude -p "完整的安全审查" --model claude-sonnet-4-5

或用批量 API(省 50%)处理大量任务。


来源:Programmatic Usage - Claude Code Docs | Anthropic 官方文档

相关文章推荐

实战Claude Code CI/CD 完全集成指南:GitHub Actions 自动化代码审查与测试Claude Code 与 CI/CD 流水线完整集成教程:GitHub Actions 中非交互模式(claude -p)调用、PR 自动代码审查 Workflow、自动测试生成、构建失败时的 AI 诊断、安全扫描集成、Claude API Key 的 Secrets 管理、控制成本的模型选择策略(PR 审查用 Sonnet/失败诊断用 Haiku),以及 GitLab CI 和 Jenkins 的适配方案。2026/3/20实战Claude Code GitLab CI/CD 集成指南:@claude 触发 MR 自动化与 Bedrock/Vertex AI 企业配置Claude Code GitLab CI/CD 集成完整指南:事件驱动编排原理(@claude 触发/沙箱执行/MR 审批流)、两步快速配置(ANTHROPIC_API_KEY 掩码变量 + .gitlab-ci.yml Job)、AWS Bedrock OIDC 认证示例、Google Vertex AI Workload Identity 示例、CLAUDE.md CI 专用配置、安全最佳实践(掩码变量/分支保护/工具范围限制),以及三大常见问题排查。2026/3/5实战OpenClaw 与 Claude Code 协同使用实战:AI 聊天助手 + AI 编程助手的终极组合OpenClaw 与 Claude Code 协同使用的完整实战指南:两款工具的定位差异(OpenClaw=聊天AI助手框架,Claude Code=代码库直接操作的编程工具)、在 OpenClaw 中通过 exec 工具调用 Claude Code CLI(claude 命令)执行编程任务、把 OpenClaw 的 Telegram 消息转化为 Claude Code 任务(用自然语言描述→Claude Code执行→返回结果)、使用 OpenClaw Cron 定期触发 Claude Code 执行代码审查/依赖更新/测试/文档生成、CRS 代理在两者中的统一接入方案,以及常见的协同架构模式(主动触发/被动响应/定时执行)。2026/3/24实战Claude Code 自动生成 OpenAPI 文档:从代码到 Swagger UI 一键完成Claude Code 自动生成 OpenAPI(Swagger)文档完整教程:从现有代码逆向生成 OpenAPI 3.1 规范、为 FastAPI/Express/Gin 添加完整的 schema 注释、让 Claude 补全缺失的请求/响应 schema 定义、生成带真实示例值的 Swagger 文档、将 OpenAPI Spec 转为各语言客户端 SDK(openapi-generator)、保持文档与代码同步的 CI/CD 方案,以及从 Postman Collection 迁移到 OpenAPI 的方法。2026/3/20实战Claude Code Shell 脚本自动化实战:用 AI 编写和调试复杂 Bash/Zsh 脚本Claude Code 辅助 Shell 脚本开发的完整指南:让 Claude 生成 Bash/Zsh 脚本的高效提示词、复杂脚本的调试方法(set -x 逐行追踪)、常见运维场景脚本(日志清理/备份/监控告警/批量操作)、跨平台兼容性处理(macOS vs Linux 差异)、脚本安全性检查(避免注入/权限最小化)、让 Claude 解释复杂 awk/sed/find 命令,以及将一次性脚本重构为可复用工具库的方法。2026/3/20实战用 Claude Code 写 Python 脚本:自动化日常任务的 8 个实用场景用 Claude Code 编写 Python 自动化脚本实战:8 个高频场景(文件批处理/Excel 处理/API 调用/定时任务/数据清洗/发送通知/Web 爬取/PDF 处理),每个场景给出完整 Prompt 模板和代码结构。2026/3/14