Claude Code 的交互式界面固然好用，但它有一个根本限制：需要一个人坐在终端前。当你想把 AI 编程能力嵌入脚本、CI/CD 流水线、定时任务中时，交互模式就成了障碍。
无头模式（Headless Mode）正是为此而生。一个 -p 标志，就能将 Claude Code 从交互式助手转变为标准的 Unix 命令行工具——接受输入、处理任务、输出结果、退出进程，不需要任何人工干预。
Anthropic 官方文档现已将这一功能纳入 Agent SDK 体系，但 -p 标志和所有 CLI 选项的使用方式保持不变。本文将从基础用法到实战场景，系统介绍无头模式的工作方式和典型应用。
什么是无头模式
在默认的交互模式下，Claude Code 以对话形式运行：你输入指令，它执行操作，遇到需要权限的动作会暂停等你确认。这种模式适合开发者坐在电脑前逐步调试。
无头模式的逻辑完全不同。你通过 -p（即 --print）标志传入一个提示词，Claude Code 处理这个提示词，将结果输出到标准输出（stdout），然后进程自动终止。整个过程没有交互界面，没有权限弹窗，没有等待输入。
一条最简单的无头模式命令如下：
claude -p "这个项目有多少个文件？"
Claude Code 会分析当前项目结构，返回一个数字（比如"834 个文件"），然后退出。它的行为和 grep、wc 这类传统命令行工具一致：输入、处理、输出、结束。
这意味着无头模式天然兼容 Unix 的管道哲学。你可以用管道将其他命令的输出送入 Claude Code，也可以将 Claude Code 的输出传给下游工具处理。
核心参数详解
无头模式的灵活性来自几个关键参数的组合。
输出格式控制
--output-format 决定了返回结果的形式，支持三种格式：
# 纯文本，适合人类直接阅读claude -p "列出所有 TODO 注释" --output-format text
# JSON 格式，适合程序解析，包含 result 字段和会话元数据claude -p "总结这个项目" --output-format json
# 流式 JSON，逐行输出，适合实时处理claude -p "分析代码质量" --output-format stream-json
在自动化场景中，JSON 格式最为常用。返回的 JSON 对象中包含 result 字段（任务结果）和 cost_usd 字段（本次调用的费用），方便脚本进行后续处理和成本监控。
工具权限控制
--allowedTools 是无头模式下最重要的安全参数。它精确定义了 Claude Code 在本次运行中可以使用哪些工具，支持通配符匹配：
# 只读模式：只能读取文件和搜索，不能修改任何内容claude -p "审计这个代码库" --allowedTools "Read""Glob""Grep"
# 读取 + HTTP：可以分析和发送通知，但不能修改文件claude -p "检查服务健康状态" --allowedTools "Read""Bash(curl *)"
# 读写模式：可以读取和编辑文件claude -p "修复代码中的拼写错误" --allowedTools "Read""Write"
注意 Bash() 中的通配符规则：Bash(git diff *) 允许所有以 git diff 开头的命令（* 前有空格），而 Bash(git diff*) 则会额外匹配 git diff-index 等命令。这个细节在生产环境中需要特别注意。
执行限制
两个参数用于控制资源消耗：
claude -p "重构认证模块" \ --max-turns 15 \ --max-budget-usd 1.00
--max-turns 限制 Agent 的最大迭代轮次，--max-budget-usd 设定本次调用的费用上限。在 CI/CD 环境中，这两个参数是防止任务失控的必要保障。
实战场景一：管道组合与数据分析
无头模式最直接的用法是与其他命令行工具组合。
分析 CSV 数据：
cat sales_data.csv | claude -p "哪个地区的销售额最高？给出具体数字"
分析错误日志：
tail -n 200 /var/log/app/error.log | claude -p "归纳这些错误的主要类型，按频率排序"
审查 Git 提交差异：
git diff HEAD~3..HEAD | claude -p "审查这些变更，指出潜在的 bug 和安全隐患"
这些场景的共同特点是：将一个命令的输出通过管道传给 Claude Code，由它完成需要"理解力"的分析工作。传统工具能做的是文本匹配和统计，Claude Code 能做的是语义理解和推理判断。
实战场景二：CI/CD 自动化代码审查
无头模式最具生产价值的应用场景是嵌入 CI/CD 流水线。以下是一个完整的 GitHub Actions 配置示例，每当有 Pull Request 提交时自动触发 Claude Code 进行代码审查：
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Get Changed Files
id: changed
run: |
echo "files=$(git diff --name-only origin/main...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT
- name: Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "审查以下修改的文件，识别潜在问题：${{ steps.changed.outputs.files }}" \
--output-format json > review.json
- name: Post Review Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: `## Claude Code Review\n\n${review.result}`
});
这个流水线做了三件事：获取本次 PR 修改的文件列表，将文件列表传给 Claude Code 进行审查，最后将审查结果作为评论发布到 PR 页面上。整个过程无需人工参与。
实战场景三：定时任务与自主 Agent
结合 cron 定时任务，无头模式可以实现"AI 在你睡觉时干活"的效果。
每晚自动审查 staging 环境日志：
crontab -e0 3 * * * cd /home/deploy/app && claude -p \"审查 logs/staging.log 中最近 24 小时的内容，识别异常模式并生成报告" \ --allowedTools "Read""Bash(curl *)" \ --output-format json > /home/deploy/reports/daily-review.json
每周一凌晨执行安全扫描：
# crontab -e
0 3 * * * cd /home/deploy/app && claude -p \
"审查 logs/staging.log 中最近 24 小时的内容，识别异常模式并生成报告" \
--allowedTools "Read" "Bash(curl *)" \
--output-format json > /home/deploy/reports/daily-review.json
需要注意的是，这里的 --allowedTools 被严格限制为只读权限。在无人值守的定时任务中，绝对不应该赋予 Claude Code 修改文件或执行任意命令的能力。
实战场景四：批量文件处理
无头模式支持在 Shell 循环中反复调用，适合批量迁移或转换类任务：
# 将项目中的 JavaScript 文件逐个转换为 TypeScript
for file in src/**/*.js; do
claude -p "将这个 JavaScript 文件转换为 TypeScript，使用严格类型：@$file" \
--allowedTools "Read" "Write"
done
每次调用是一个独立的会话，不会在调用之间保留上下文。如果需要跨文件保持一致性，建议先用一次调用生成迁移计划，再在循环中逐个执行。
使用建议与注意事项
在生产环境中使用无头模式，有几点值得关注。
始终限制工具权限。 在 CI/CD 和定时任务中，--allowedTools 不是可选项，而是必选项。明确指定 Claude Code 能做什么，比事后处理它不该做的事要高效得多。
处理错误返回码。 无头模式在成功时返回退出码 0，失败时返回非零值。在脚本中务必检查 $?，避免静默忽略错误。使用 JSON 输出格式时，检查返回对象中的 error 字段。
控制成本。 每次无头模式调用都会消耗 Token。Anthropic 的数据显示，一次针对 200 行代码的审查，使用 Sonnet 4.6 的费用大约在 0.02 到 0.08 美元之间。在高频调用场景中，务必设置 --max-budget-usd 作为安全阀。
善用 --bare 模式。 在脚本和 SDK 调用中，加上 --bare 可以跳过 OAuth 和本地密钥链读取，避免受到本地配置的影响。认证信息通过 ANTHROPIC_API_KEY 环境变量传入即可。
总结
无头模式的本质是一次角色转换：Claude Code 不再是一个需要你坐在旁边的助手，而是一个可以嵌入任何自动化流程的 AI 组件。管道组合、CI/CD 集成、定时任务、批量处理——这些场景的共同点是"不需要人在场"，而无头模式恰好填补了这个空缺。
对于已经在使用 Claude Code 进行日常开发的团队来说，无头模式是将 AI 编程能力从"个人工具"扩展到"基础设施"的关键一步。
