Claude Code的工程化落地-Headless

Claude Code 的 Headless 模式：把 AI 塞进 CI/CD 管道

想把 Claude Code 跑在 CI/CD 里，或者写个脚本让它在服务器上自动干活？那你绕不开 Headless 模式。这篇文章从 -p 开始，讲清楚参数怎么配、输出怎么选、管道怎么接，最后给你一套能在 GitLab CI / GitHub Actions 里直接用的实例子。

非交互形式：无对话，无 UI，但功能完整。

核心概念

Headless 模式的官方定义一句话就能说清楚：Agent SDK 提供与 Claude Code 相同的工具、代理循环和上下文管理功能，以非交互模式运行 Claude Code。

说白了，就是不弹对话窗口，用一条命令完成分析、修复、报告，跑完即停。

基本用法与参数

在任何 claude 命令前加 -p（或 --print），就切到了 Headless 模式：

bash 复制代码

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

allowedTools 限制了可用工具的范围，防止 Headless 模式无节制操作。核心参数如下：

参数	说明	示例
`-p, --print`	启用 Headless 模式	`claude -p "任务"`
`--output-format`	输出格式：text / json / stream-json	`--output-format json`
`--max-turns`	限制最大执行轮次	`--max-turns 5`
`--allowedTools`	只允许特定工具	`--allowedTools Read,Grep`
`--disallowedTools`	禁用特定工具	`--disallowedTools Bash`
`--continue`	继续上一个会话	`--continue`
`--session-id`	指定会话 ID	`--session-id livo123`
`--bare`	裸机模式	`claude --bare -p "任务"`

裸机模式会忽略自动发现的钩子、技能、插件、MCP 服务器、自动内存和 CLAUDE.md------上下文越少，执行越快。

常用的三种输出格式

text 格式

bash 复制代码

claude -p "Find and fix the bug in auth.py" --output-format text

默认格式，适合日志记录。

json 格式

bash 复制代码

claude -p "列出当前目录文件" --output-format json

适合元数据输出监控，返回结构化 JSON，包含会话 ID、耗时、token 用量等：

json 复制代码

{
    "type": "result",
    "subtype": "success",
    "is_error": false,
    "duration_ms": 15778,
    "num_turns": 2,
    "session_id": "66828176-2652-43f0-992f-cd538d25e3f9",
    "total_cost_usd": 0,
    "usage": {
        "input_tokens": 19747,
        "output_tokens": 0,
        "service_tier": "standard"
    },
    "terminal_reason": "completed"
}

上方仅展示核心字段，完整 JSON 还包含 cache_creation、permission_denials、iterations 等元数据。

stream-json 格式

bash 复制代码

claude -p "列出当前目录文件" --output-format stream-json --verbose

以换行分隔的 JSON 流实时输出，适合长时间任务。这里有个坑：必须加 --verbose，否则底层可能捕获不到完整的 JSON 流片段，拿不到思考过程、工具调用细节等中间态数据。

Unix 管道：把 AI 串进命令行

官方解释很直白：非交互模式读取标准输入，因此你可以像对待任何命令行工具一样，用管道喂数据、用重定向接输出。

bash 复制代码

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

本质就是「前一个命令的输出 → Claude 分析 → 结果落盘」，一条线串起来。数据获取 · AI 分析 · 结果处理 · 通知存储，四步自动化链路就搭好了。

CI/CD 集成实战

用例1：Shell 脚本直连

把 claude -p 写进 .sh，挂在 CI pipeline 里执行。下面这个例子会拉取最近 N 条 git 提交，交给 Claude 生成中文分析报告：

bash 复制代码

#!/bin/bash
# git-report: 使用 Claude 分析 git 提交记录并生成报告
# Usage: ./auto-commit.sh [N]

set -e

N=${1:-10}
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
OUTPUT="git-report_${TIMESTAMP}.txt"

echo "正在获取最近 $N 条提交记录..."

# 获取 git log
GIT_LOG=$(git log --no-merges -n "$N" --format="---%ncommit: %H%nauthor: %an <%ae>%ndate: %ad%n%n    %s%n%b" --date=short)

# Claude 分析并生成报告
echo "Claude 正在分析提交历史..."
echo "$GIT_LOG" | claude -p \
  "你是一名代码变更分析师。根据下面的 git 提交历史，生成一份简洁的中文分析报告，包含：
1. 提交数量、时间跨度概述
2. 按 feat/fix/refactor/docs/chore 分类统计
3. 3-5 个关键变更摘要
4. 需要关注的风险点（如有回滚、紧急修复等）
5. 各作者贡献方向

直接输出报告内容，不要额外说明。" 2>&1 | tee "$OUTPUT"

echo ""
echo "报告已保存: $OUTPUT"

用例2：GitHub Actions

Anthropic 提供了官方 Action ------ claude-code-action，Star 8k+，直接把 Claude Code 接进 GitHub PR/Issue 工作流，自动做代码审查、Issue 分类等。

用例3：GitLab CI

GitLab 没有官方 Action，但通过自定义 .gitlab-ci.yml 调用 claude -p 一样能跑：

gitlab-ci

bash 复制代码

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

在项目根目录并创建.gitlab-ci.yml文件

yaml 复制代码

claude-review:
  image: node:20
  script:
    - npm install -g @anthropic-ai/claude-code
    - claude -p "Review the changes in this MR" --output-format text
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  only:
    - merge_requests

Circle-CI 在项目根目录并创建.circleci/config.yml文件

yaml 复制代码

version: 2.1
jobs:
  claude-review:
    docker:
      - image: cimg/node:20
    steps:
      - run:
          name: Install Claude Code
          command: npm install -g @anthropic-ai/claude-code
      - run:
          name: Run Claude Code
          command: claude -p "Review the changes in this MR" --output-format text
    environment:
      ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
workflows:
  version: 2.1
  workflow:
    jobs:
      - claude-review

Jenkins 在项目根目录并创建Jenkinsfile文件(Groovy DSL 定义 Pipeline)

scss 复制代码

pipeline {
    agent any
    environment {
        ANTHROPIC_API_KEY = credentials('ANTHROPIC_API_KEY')
    }
    stages {
        stage('Claude Review') {
            steps {
                sh 'npm install -g @anthropic-ai/claude-code'
                sh 'claude -p "Review the changes in this MR" --output-format text'
            }
        }
    }
}

虽然没有像 GitHub Actions 有官方支持，但 Headless 模式可以在其他 CI 平台上工作，因为 Headless 模式的本质就是命令行调用------只要平台能运行 npm install 和 claude -p，就能集成

总结

Headless 模式的本质其实就一句话：让 Claude Code 从对话工具变成命令行工具。一旦完成这个切换，CI/CD、定时任务、自动化脚本，全都能接进来。配好参数、选对输出格式、管住权限，它就稳稳地跑在你自己的cmd 命令里。