Claude Code 无头模式

要解决什么问题

在终端里用 Claude Code 做修 bug、改代码、跑工具链时，默认是交互式会话：权限确认、多轮对话、会话持久化都面向「人坐在键盘前」。一旦要把同一套能力接到 GitHub Actions、定时任务或其它编排器里，就需要进程跑完即退出、stdout 可被脚本解析，并且能明确限制工具与花费。

本技能围绕 Claude Code 的无头（Headless）模式：通过 -p / --print 单次下发任务、输出结果后退出，而不是长期挂着一个 TUI。

核心能力与用法要点

非交互执行是入口：claude -p "fix bug" 会在 print 模式下完成任务并打印最终结果。输出侧可用 --output-format 在 text、json、stream-json 间切换；需要结构化下游处理时，json 便于字段抽取，stream-json 则对应 message_start、tool_use_start 等流式事件，适合实时日志或代理编排。

权限与安全在自动化里往往比本地开发更硬：--allowedTools / --disallowedTools 做白名单与黑名单（例如只允许 Bash(git *)）；--permission-mode 可取 dontAsk 等以减少阻塞。--dangerously-skip-permissions 仅应在沙箱环境考虑。--add-dir 可扩展工具可读写的目录范围。

成本与模型：print 模式支持 --max-budget-usd 封顶 API 费用、--fallback-model 在过载时降级；--model 与 --effort 控制模型与推理强度。会话相关参数包括 --resume、--session-id、--continue，以及 --no-session-persistence 避免在 CI 磁盘上留会话；--bare 可跳过 hooks、LSP、插件等以缩短冷启动。

进阶项含 --json-schema 约束结构化输出、--mcp-config 加载 MCP、自定义 --agents 等。文档还整理了退出码（如 124 超时、2 鉴权失败）与常见错误对照（401、超预算、工具未允许、会话未找到等），便于在流水线里做分支处理。

适用边界与注意点

无头模式适合单次或有限多轮的自动化，而不是替代完整的本地结对编程体验；复杂任务仍可能触达 token 上限，需缩短 prompt、利用 CLAUDE.md 或 --resume 拆分。--max-budget-usd 等部分开关仅在 print 模式生效。生产环境应优先收紧 --allowedTools，慎用跳过权限；鉴权依赖 ANTHROPIC_API_KEY 或 claude login，401 时先查密钥与会话状态。