# 无人值守 · Headless、SDK 与 CI · Claude Code · 终端里的编排台 **作者** Aklman · **章节** 08 / 11 · **首发** 2026.07 · **语言** 中文为主, 中英双语 **原文** https://library.aklman.com/books/claude-code/08-headless **全书 markdown** https://library.aklman.com/books/claude-code/llms.md **上一章** https://library.aklman.com/books/claude-code/07-hooks/llms.md **下一章** https://library.aklman.com/books/claude-code/09-review/llms.md > 本章来自 Aklman · Library, 完整免费阅读。允许 AI 摘读、引用、问答; 转载请保留作者署名与原文链接 (CC BY-NC-ND 4.0, https://library.aklman.com/license)。 --- > 到这里，Claude Code 还都在你眼前的终端里。但它也能离开终端：headless 模式（claude -p）让它无人值守地跑一次；Agent SDK 让你把它嵌进自己的脚本和服务；GitHub Actions 让它在每个 PR 上自动跑一遍。这是「派活」的极限形态 —— 活不在你这台机器、不在你盯着的时候完成。这一章讲哪类活适合无人值守（批处理、CI 检查、定时任务），怎么用 SDK 把它编排进流水线，以及无人时最该守住的那条：它跑得越自动，你越要在它动手的边界上设死规矩。 到这里,Claude Code 还都在你眼前:终端开着,活跑着,你在场。这一章拆掉最后一个前提。headless 让它无人值守跑一次,SDK 让它长进你的程序,GitHub Actions 让它守在每个 PR 上,Routines 让它半夜也上班 —— 派活的极限形态:活不在你这台机器、不在你醒着的时候完成。也因此,这一章的另一半讲规矩:它跑得越自动,边界越要在出发前写死。 ### I · headless:一条命令,进出都是管道 把交互会话变成一条 Unix 命令,只需要一个 `-p`:`claude -p "提示"` 跑完就退,stdin 能灌数据进去,stdout 能接进下一个程序。[^1]它把 Claude Code 从「一个你打开的应用」变成「一个脚本里的工序」: _三种管道姿势:灌日志、当 linter、出结构化结果_ ```text ```bash # 把构建日志灌进去,要一句根因 cat build-error.txt | claude -p "一句话解释这次构建失败的根因" # 当一个只报错字的 linter 用 git diff main | claude -p "你是错字检查器:每个错字报 文件:行 和问题,别的什么都不说" # 结构化输出,给脚本吃 claude -p "列出 src/api 里的全部路由" \ --output-format json \ --json-schema '{"type":"object","properties":{"routes":{"type":"array","items":{"type":"string"}}},"required":["routes"]}' \ | jq '.structured_output.routes' ``` ``` 第三条是无人化的关键零件:`--output-format json` 让结果带上元数据,`--json-schema` 更进一步 —— 按你给的 schema 约束输出,脚本直接消费 `structured_output` 字段,不用解析散文。[^1]第 9 章说的「回归集用 `claude -p` 重跑、拿 JSON 对一对」,零件就是这两个 flag。脚本化调用再加一个 `--bare`:跳过 hooks、skills、MCP、CLAUDE.md 的自动发现,保证同一条命令在每台机器行为一致 —— CI 里尤其该加。[^1] --- ### II · SDK:同一台引擎,做成库 脚本再长,也只是把命令串起来;要把它嵌进你自己的服务 —— 一个自动分诊 bug 的机器人、一个替客服读日志的后台 —— 用 Agent SDK。官方的定义一句话:给你的是**驱动 Claude Code 的同一套工具、agent 循环与上下文管理**,以 Python 和 TypeScript 可编程。[^2]包名 `claude-agent-sdk`(Python)和 `@anthropic-ai/claude-agent-sdk`(TypeScript),一个 `query(prompt, options)` 就是一个带全套工具的 agent;其他语言不用等移植,`claude -p --output-format json` 就是它的通用接口。[^2]CLI 和 SDK 怎么分工,官方表格说得干脆:交互开发、一次性任务用 CLI;CI/CD、定制应用、生产自动化用 SDK。[^2]这本书讲到这条线为止 —— 再往里,是《Agent 实战》整本书的地界。 --- ### III · 长在流水线里:每个 PR、每个整点 第三种形态不属于任何一台机器。装上 GitHub Actions 集成(交互式安装:`/install-github-app`),在任何 PR 或 issue 里 @claude,它就地分析代码、实现功能、修 bug,开出完整的 PR;`anthropics/claude-code-action@v1` 也能不等召唤、按你的 workflow 定时或按事件跑。[^3]记两笔账:CI 里它烧的是 GitHub runner 分钟加 API token —— 认证用的是你放进仓库 secrets 的 API key,按 token 计费。[^3]这套走的是 Console 的账,和 Pro/Max 订阅额度是两码事,自动化越勤越要单独盯。要「每个 PR 无须触发的自动底审」,那是另一条产品线(GitHub Code Review),配好即每 PR 一审。[^3]定时的活则交给 Routines:跑在 Anthropic 托管的基础设施上,你的电脑关了它照跑,CLI 里 `/schedule` 就能建 —— 夜间依赖巡检、晨会前的 PR 摘要,都是它的班次。[^5] --- ### IV · 无人时的规矩:边界先于出发 交互会话里,权限弹窗是最后的安全网;无人值守时没有这张网 —— 所以边界要前置。两种写法:`--allowedTools` 白名单,精确到 `"Bash(git diff *)"` 这样的规则,名单之外一律不许[^1];或者 `--permission-mode dontAsk`,把「没预批就拒绝」定为总则,专为锁死的 CI 而设。[^4]想要更多自主,`auto` 模式的分类器也能在无人时压阵 —— 但记住它的失败姿态:交互会话里连续拦截会退回问你,`-p` 里没有你,它直接中止。[^4]这是无人化的正确性质:**宁可停,不越界**。最后一层是第 7 章的 hooks:headless 照样触发,PreToolUse 安全闸在没有观众的地方一样否决。三层叠起来再出发 —— 活可以离开你,规矩不行。 动手 · 把一件活送出你的视线: - **把一个重复检查做成一行脚本**: 挑你每周手动做的一个检查(错字、日志异常、路由清单),照第 I 节写成 claude -p 一行,挂进 package.json 或 Makefile。 - **给团队仓库装上 @claude**: 跑 /install-github-app,然后在一个真实 issue 里 @claude 试一件小活 —— 看它从 issue 到 PR 走完全程。 - **设一个夜班 Routine**: 用 /schedule 给明早设一个巡检(昨日 CI 失败摘要、依赖告警),明天读它的班报,再决定要不要长期雇佣。 > 活可以不在你眼前跑, > 规矩必须先于它出发 ## 引用与参考 01 · Claude Code Docs · Run Claude Code programmatically —— claude -p(--print)非交互跑一次:读 stdin、可管道进出;--output-format 选 text / json / stream-json,--json-schema 按 JSON Schema 约束结构化输出(结果在 structured_output 字段);--allowedTools 按权限规则语法预批工具;--bare 跳过 hooks / skills / MCP / CLAUDE.md 的自动发现,保证脚本在每台机器行为一致,是脚本化调用的推荐模式;--no-session-persistence 不留会话;文档场景即 CI、构建脚本与管道。截至 2026-07-17。 (Claude Code Docs · Run programmatically) 02 · Claude Code Docs · Agent SDK overview —— 「Agent SDK 给你的,是驱动 Claude Code 的同一套工具、agent 循环与上下文管理,以 Python 和 TypeScript 可编程」;包名 claude-agent-sdk(Python)与 @anthropic-ai/claude-agent-sdk(TS,自带 Claude Code 二进制);query(prompt, options) 即起一个 agent;其他语言走 claude -p --output-format json。官方分工表:交互开发与一次性任务用 CLI,CI/CD、定制应用与生产自动化用 SDK。截至 2026-07-17。 (Claude Code Docs · Agent SDK) 03 · Claude Code Docs · GitHub Actions —— 在 PR 或 issue 里 @claude,它分析代码、实现功能、修 bug、开出完整 PR;动作为 anthropics/claude-code-action@v1,交互式安装跑 /install-github-app;API key 放仓库 secrets;成本两笔:GitHub runner 分钟 + API token。每个 PR 无须触发的自动审查是另一条产品线(GitHub Code Review)。截至 2026-07-17。 (Claude Code Docs · GitHub Actions) 04 · Claude Code Docs · Permission modes —— 无人场景的两档:dontAsk 自动拒绝一切未预批的调用,适合锁死的 CI;auto 由分类器把关,但在 -p 非交互模式下被连续拦截会直接中止会话 —— 没有人可以回退询问。截至 2026-07-17。 (Claude Code Docs · Permission modes) 05 · Claude Code Docs · Overview —— 定时的活交给 Routines:跑在 Anthropic 托管的基础设施上,你的电脑关了也继续,可由日程、API 调用或 GitHub 事件触发,CLI 里 /schedule 创建;本机定时任务归桌面端。截至 2026-07-17。 (Claude Code Docs · Overview) --- *无人值守 · Headless、SDK 与 CI · Claude Code · 终端里的编排台 · Aklman 著 · CC BY-NC-ND 4.0 · https://library.aklman.com/books/claude-code/08-headless*