[Claude Code #14] claude -p 无头模式：将 AI 接入管道

claude -p 无头模式可以像使用 Unix 工具一样使用 Claude Code。本篇总结了 stdin 管道、--output-format json 与 jq、--allowedTools 权限，以及 CI 中的 --bare 模式。

SeokWoo Lee资深 iOS 软件工程师发布 2026年8月20日4 分钟阅读

如果你只通过对话窗口使用 Claude Code，就只用到了它一半的能力。把它接入终端管道后，就能像 grep 或 jq 这样的 Unix 工具一样使用。

关键是 -p（或 --print）标志。它无需交互界面即可处理一条提示，只输出结果后退出。

claude -p "auth 请解释这个模块的作用"

如果说 Claude Code 第 13 篇讲的是会话内的使用方式，那么这次介绍的就是如何在会话外使用它。

通过管道输入，写入文件接收结果

按照官方文档，-p 模式会读取标准输入。通过管道传入数据，再重定向结果，和其他 CLI 工具完全一样。

cat build-error.txt | claude -p '请简洁说明这个构建错误的根本原因' > output.txt

根据官方文档，成功时以退出码 0 结束，失败时以非 0 退出，因此脚本可以据此分支。管道输入上限为 10MB；如果更大，就在提示中写入文件路径来绕过。

将它加入 package.json 脚本后，还可以创建项目专用的检查器。例如把 diff 通过管道传入，只让它报告拼写错误。

加上 --output-format json 后，结果会与会话 ID、费用等元数据一起以结构化形式返回。

claude -p "请总结这个项目" --output-format json | jq -r '.result'

如果需要符合特定 schema 的输出，请在 --output-format json 中加入 --json-schema。响应会以经过验证的结构放在 structured_output 字段中。

如需按 token 实时流式传输，请使用 --output-format stream-json --verbose --include-partial-messages 组合。

在 -p 模式下，没有人可以点击批准按钮。必须提前允许所需工具。

claude -p "运行测试并修复失败" --allowedTools "Bash,Read,Edit"

--allowedTools 直接使用权限规则语法。可以像 Bash(git diff *) 一样缩小范围。星号前的空格很重要；没有空格时，匹配会一直扩展到 git diff-index。

提供 --permission-mode acceptEdits 后，文件写入以及 mkdir、mv 等常见文件系统命令会自动获批。其他 Shell 命令和网络请求仍需要 --allowedTools。

对于一次调用无法完成的任务，可以继续使用该会话。

claude -p "请检查这个代码库中的性能问题"
claude -p "现在 DB 请专注于查询" --continue

如果同时进行多个对话，请保存 JSON 输出中的 session_id，并使用 --resume 指定并继续某个对话。

用于脚本和 CI 时，建议同时使用 --bare。它会跳过 hook、skill、plugin、MCP 和 CLAUDE.md 的自动加载，加快启动，并在任何机器上产生相同结果。

这也出于安全考虑。-p会话无法显示工作区信任确认窗口，因此没有 --bare 时，陌生仓库中的 hook 和 MCP 服务器也会被直接执行。官方文档明确建议脚本调用使用 --bare，并表示未来计划将 -p 设为默认值。

在 --bare 中，请记住要使用 ANTHROPIC_API_KEY 环境变量，而不是订阅登录。

claude -p将 Claude Code 变成 Unix 工具。通过管道传入、以 JSON 接收，再根据退出码分支。

使用 --allowedTools 提前开放权限，并在 CI 中通过 --bare 以确定且安全的方式运行。

下一篇将回到交互界面，全面介绍 ! Shell 模式，以及 Ctrl+O 等特殊输入和快捷键。