一分钟看懂
- claude -p "prompt" 跑一次就输出结果——没有交互会话。它和任何 Unix 工具一样可组合：管道进、管道出、串进脚本和 CI 步骤。
- --output-format json 返回结果外加 session_id、开销和元数据；stream-json 给实时消费者输出按行分隔的事件。用 jq 解析，然后在上面搭东西。
- 无头运行默认没有任何编辑或破坏性权限。用 --allowedTools "Bash(git diff *),Edit" 精确授予所需——权限规则语法，前缀匹配。
- @claude GitHub Action 就是带前端的无头模式：在 issue 或 PR 里 @claude，它就读代码、开 PR、加提交、回答问题、审代码——跑在你自己的 GitHub runner 上。
Building headless automation with Claude Code | Code w/ Claude
频道：Anthropic20:59
Headless mode — official documentation
官方文档：code.claude.com/docs
Claude Code GitHub Action — official docs
官方文档：code.claude.com/docs
本页的参数、限制和行为均已对照官方无头模式文档核实；上面的演讲是 Anthropic 官方自己的演示，也是截图的画面来源。
截图版权归各自创作者所有，并深链到对应时间点；未使用演讲者和观众镜头。
无头运行 Claude Code，一步一步来
第 1 部分 — 无头基础
- 1
什么是无头模式
无头模式就是去掉交互 UI 的 Claude Code：同一个智能体，改用程序驱动。Anthropic 把它定位成智能体应用的简单积木——在脚本和管道里当 Unix 工具使，做 CI 自动化、远程环境，或者充当网页聊天界面的引擎。
Anthropic 的原话：SDK 是对无头环境下 Claude Code 的程序化访问。跳到 2:10 观看 - 2
用 claude -p 单发执行
-p(--print)参数执行单条提示后即退出：claude -p "Write me a function that calculates the Fibonacci sequence"。没有任何东西被挂起——你从 stdout 拿到输出，还有一个脚本可以检查的退出码。写权限用 --allowedTools 提前授予。
一次单发请求：claude -p 生成斐波那契函数然后退出——没有 TUI，没有追问。跳到 3:30 观看 - 3
把文件直接管道进 Claude
stdin 的用法和任何 CLI 工具一样：cat app.log | claude -p "summarize the most common error logs"。Anthropic 的演示里，2000 行日志进去，出来一份大白话错误总结——构建失败、堆栈跟踪、导出文件都能用这一招。管道输入的 stdin 上限 10MB。
cat 加管道符加 claude -p：两千行日志变成三句话的诊断。跳到 3:55 观看 - 4
让人读不下去的输出变成答案
同一个套路能把硬核输出变成答案：ifconfig | claude -p "what interfaces do I have configured? don't include lo"。命令打印的任何东西——网络状态、编译器报错、terraform plan——都可以过一遍 Claude，换回人类可读的摘要。
管道进 claude -p 的 ifconfig：每个接口都有解释，环回口按要求排除。跳到 4:15 观看 - 5
拿到结构化 JSON
加上 --output-format json，响应就变成可解析的对象：结果文本、session_id、耗时和 total_cost_usd。要实时消费，--output-format stream-json 会随事件发生逐行输出——最后一行就是最终结果。
JSON 模式：一个数据块里装着结果、一个以后能恢复的会话 id，还有这次运行的开销。跳到 4:35 观看
第 2 部分 — 像工程师一样写脚本
- 6
有意识地授予工具
无头启动时没有任何编辑或破坏性权限。--allowedTools 按权限规则语法预批任务所需：--allowedTools "Bash(npm run build),Bash(npm test:*),Write"。MCP 工具也能这样加进允许列表——给完成任务所需的最小集合就好。
SDK 深潜：工具权限、结构化输出模式和自定义系统提示词，一页幻灯片讲完。跳到 11:00 观看 - 7
跨运行保持上下文
JSON 模式会返回 session_id——用 --resume "$session_id" 传回去，之后的运行或另一个进程就能接着同一份会话状态。在它上面搭交互式产品就是这么做的：用户说一句，Claude 答一句，你把会话留到下一轮。
- 8
不需要人类也能过权限关
如果预测不了 Claude 会用到哪些工具，--permission-prompt-tool 可以在运行时把审批决定交给一个 MCP 服务器——由它去问你的服务（或经由你的应用问用户）每个操作放不放行，而不用你提前列全。
- 9
CI 里用 --bare
--bare 跳过 hooks、skills、自定义命令、子智能体、插件、MCP 服务器和 CLAUDE.md 的自动发现，换来最快的启动——脚本和 CI 推荐使用，而且即将成为 -p 的默认行为。它要求 ANTHROPIC_API_KEY，上下文用参数显式传入。
第 3 部分 — @claude GitHub Action
- 10
认识 @claude GitHub Action
GitHub Action 就是在 SDK 上包了前端的无头模式。在任何 PR 或 issue 里 @claude，它就能读你的代码、开 PR、给已有 PR 追加提交、回答问题、审改动——跑在你现有的 GitHub runner 上，没有任何需要你伺候的基础设施。
Action 的契约：打上 @claude，写清需求，它就在你自己的 runner 上打理仓库。跳到 17:10 观看 - 11
把 issue 指派给 Claude
在 Anthropic 的现场演示里，一条「@claude please implement this feature and comment on it」的评论让机器人先回了一份划定范围的计划——列明它要做什么——然后才创建分支、提交和拉取请求，全程都能在 Action 日志里追溯。
真实 issue 上的 @claude 评论：动任何代码之前，Claude 先回一份划定范围的计划。跳到 7:50 观看 - 12
装到你自己的仓库
最终成果是 issue 上一份逐项打勾的实现清单——功能加上了，todo 关掉了。到达这一步：在你的仓库里打开 Claude Code 运行 /install-github-action：交互流程会开一个带 workflow YAML 的 PR，然后把 API key 配成仓库 secret，合并即可。
跑完的样子：一份逐项打勾的实现清单，列着 Action 给演示应用添加的每个功能。跳到 13:30 观看
无头 vs 交互 vs SDK vs GitHub Action
驱动同一个智能体的四种方式——按提问的是谁（或什么）来选：
- 1交互 CLI——TUI 会话：权限弹窗、plan 模式、/命令。适合此刻亲手推进任务的人类。
- 2无头 claude -p——一次程序化调用：stdin 和 stdout、退出码、没有 UI。适合脚本、cron 任务和其他工具发来的快问快答。
- 3Agent SDK——同样无头能力，打包成带类型的库：多轮会话、自定义工具、流式输出。适合 Claude 作为你应用里的一个组件。
- 4@claude GitHub Action——跑在 GitHub 事件模型上的无头：在你自己的 runner 上处理 issue、PR 和评审。适合全团队都能触发的仓库级自动化。
- 5--bare 无头——给 CI 的精简启动：不加载 CLAUDE.md、hooks、skills、插件和 MCP 自动发现，上下文用参数显式传，冷启动最快。
它们共享同一套模型访问和权限系统——给无头授的权限规则处处生效，这正是 --allowedTools 纪律重要的原因。
无头模式闹脾气？急救手册
五个无头特有的坑，和每个的解法：
- 1Claude 还没跑完脚本就退出了。检查退出码：0 是成功，其余都是失败。SIGTERM 以 143 退出并留下没跑完的回合——必须中途停止时，用 SIGINT 或 SDK 的 interrupt() 收尾。
- 2管道输入被悄悄截断。stdin 上限 10MB——更大的载荷写进文件，在提示里引用路径。
- 3「--bg rejected」或 --cloud 报错。仅限交互模式的参数对 -p 无效：--bg 会被直接拒绝；--cloud 需要配合会话 id 来排队消息，而不是任务描述。
- 4CI 运行无视你的 CLAUDE.md 和 hooks。那是 --bare 在尽职：跳过自动发现。用 --settings、--mcp-config、--agents 或 --plugin-dir 显式传上下文。
- 5后台 bash 任务中途夭折。后台 shell 会在结果落地约 5 秒后被杀；子智能体和工作流最多把进程维持到 10 分钟的空闲上限。CI 里要显式等待它们。
其他情况，加上 --verbose 去读 stream-json 事件——system/init 会报出实际加载的模型、工具和 MCP 服务器。