Claude Code Headless Mode
解释 Claude Code headless / non-interactive 运行方式，包括 -p、JSON 输出、权限、凭据、CI 工作流和安全边界。
Headless mode 指不通过普通交互聊天运行 Claude Code。最常见形式是 print mode：
claude -p "summarize the current diff"它适合脚本、CI 检查、结构化输出和可重复自动化，但不适合无控制地让 agent 循环执行。
最后核查：2026 年 5 月 24 日。CLI flags 和自动化行为可能变化，生产 CI 前请核对当前 CLI reference。
短答案
一次性自动化用 claude -p。进入 CI 前，一定要明确输出格式、权限、凭据和失败处理。
常用参数
| 参数 | 用途 |
|---|---|
-p, --print | 非交互运行一个 prompt 并输出结果。 |
--output-format text | 人读输出。 |
--output-format json | 单次机器可读输出。 |
--output-format stream-json | 流式机器可读事件。 |
--permission-mode plan | 只分析，不编辑源码。 |
--allowedTools | 给非交互任务预批准特定工具。 |
--disallowedTools | 拒绝工具或危险工具模式。 |
--bare | 跳过 hooks、skills、plugins、MCP、auto memory 和 CLAUDE.md 等自动发现。 |
--fallback-model | print 或 background run 中默认模型不可用时使用备用模型。 |
适合场景
- PR diff 摘要。
- 根据 commits 生成 release notes。
- 检查迁移计划是否触碰禁区。
- 给内部 review pipeline 产出 JSON。
- 只读仓库审计。
风险场景
- CI 中给写权限但没有 review。
- 同时开放 MCP、生产凭据和宽权限。
- 失败后无限 retry。
- 混淆订阅 OAuth 和 API key 计费。
- 对不可信 PR 运行强权限工具。
更安全的 CI 形态
claude -p "Review this diff for risky changes. Do not edit files." \
--permission-mode plan \
--output-format json \
--allowedTools "Read" "Grep" "Glob"脚本里要明确认证方式。ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、云厂商变量和 OAuth token 都会影响授权和计费。
什么时候用 Agent SDK
如果你需要长生命周期进程、结构化 session、自定义工具编排、审批流或产品化服务边界，用 Agent SDK。只是一个 shell 任务时，claude -p 就够了。