Headless 模式：不需要交互运行 agent

在 headless（无头）或 non-interactive（非交互）模式下，AI agent 在没有聊天窗口的情况下运行——很适合脚本和 CI，但没法向你反过来提问。

Headless 是什么意思

通常你会和 agent 实时聊天：它提问，你回答，它继续做事。在 headless 或 non-interactive 模式下，这种对话就没有了。你把一个 prompt 作为参数传入，或者通过管道（pipe）输入，agent 处理完之后在最后给出一个答案——中间没有追问，也没有聊天窗口。

在 Claude Code 里是什么样的

命令 claude -p "找出并修复 auth.py 里的这个 bug" 会以非交互方式启动 Claude Code。你也可以把数据通过管道传入：cat error.log | claude -p "解释这个错误的根本原因"。输出结果既可以取纯文本，也可以取结构化的 JSON（--output-format json），很适合嵌入脚本里使用。

用途

批处理：自动处理大量文件或工单
CI/CD：比如自动检查每个 pull request 里的拼写错误或安全问题
定时任务（cron job）和无需人工介入的计划自动化

风险：无法反问

和交互模式最大的区别是：agent 没法向你请求许可或澄清问题。如果它遇到一个通常会追问的情况，就只能自己做决定，或者直接中止。所以在 headless 运行时，选对权限模式（见对应词条）特别重要：没有清楚的规则，agent 要么做得太少（一直中止），要么做得太多（不打招呼就执行有风险的操作）。

示例

# CI 脚本：对每个 PR diff 做拼写检查 git diff main | claude -p "找出这个 diff 里的拼写错误。每找到一处，就输出 'file:line' 和错误内容，其他什么都不要输出。" --output-format json

🛠️ 练习——自己动手试试

构建一个简单的 headless 调用来总结一个文件，观察它在无法反问的情况下会怎么处理。

在终端里执行：claude -p "用 3 句话总结这个文件" --allowedTools "Read"，用你项目里一个真实存在的文件来测试。
再执行一次，但这次指向一个不存在的文件——观察 agent 在无法反问的情况下会怎么反应（是报错，而不是追问）。
试试 --output-format json，看看返回的 JSON：除了正文之外，它还包含哪些字段？

✅ 自查清单

☐ 你能不能解释清楚，为什么文件不存在时 agent 没有直接追问？
☐ 你理解 --allowedTools 在这里是用来做什么的吗？
☐ 你知道这一章提到的哪两种场景（批处理、CI）最适合用 headless 运行吗？

小测验

在 headless / non-interactive 模式下运行 agent，最大的风险是什么？