Claude Code Headless Mode 教程

Headless Mode 可以让 Claude Code 在没有完整交互式终端会话的情况下运行指定提示词。它适合可重复检查、CI 实验、PR 摘要、Issue 分流，以及输入输出边界清晰的结构化分析。

基础 Print Mode

用 -p 或 --print 执行非交互式提示：

claude -p "总结这个仓库的改动，并列出测试风险"

提示词要具体。让自动化在大仓库里执行模糊任务，很容易消耗不必要的用量，并产生噪声输出。

结构化输出

自动化场景应选择脚本容易解析的输出格式：

claude -p "Review this diff and return the top risks" \
  --output-format json

长任务可以使用流式输出：

claude -p "Analyze this pull request" \
  --output-format stream-json \
  --verbose

--verbose 适合调试。生产自动化中只有确实需要追踪时才保留详细日志。

Headless 工作流权限

Headless 工作流应显式声明工具和权限模式：

claude -p "只总结这个 PR，不修改文件" \
  --allowedTools "Read,Glob,Grep,LS,Bash(git diff:*)" \
  --permission-mode plan

不要给每次提交都会运行的脚本配置宽权限。写文件、安装依赖、部署和破坏性 Shell 命令都应该保留人工审查。

适合场景

• 总结 PR 并识别测试缺口。
• 把 Issue 转成可复现的排查清单。
• 检查文档中的过时命令或失效链接。
• 根据近期提交生成 release note 草稿。
• 在受控 CI 中运行固定代码质量提示词。

不适合场景

需求不清的架构决策、高风险迁移、支付/认证改动，以及需要产品讨论的任务，不适合直接用 Headless Mode。先用交互式会话和 Plan Mode。

成本和稳定性检查

1. 提示词保持聚焦。
2. 限制 Claude Code 可检查的文件和工具。
3. 自动化未验证前，优先只读。
4. 记录完整命令和输出格式。
5. 上 CI 前先在交互环境用 /status 确认凭证路径。

相关页面

• 工具权限管理
• Plan Mode
• Claude Code rate limit 错误
• 多 Claude 协作

官方来源

• Claude Code CLI reference
• Claude Code permissions