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 官方文档