SDK 与 Headless：把 Claude 变成你的自动化引擎

1. 软件开发行业的 AI 范式演进：从辅助工具到工程智能体
2. Claude Code 全景入门：装好、看懂、跑起来
3. 上下文注入：用 @ 和 ! 精准喂给 Claude 它需要的信息
4. 记忆系统：用 CLAUDE.md 告别每次对话都要”重新认识你”
5. 斜杠命令：把你的重复操作变成一个单词
6. Hooks 机制：让 AI 的每一步都在你的规则里
7. MCP：给 Claude Code 接上”外设”
8. Skills：让 Claude 按需加载你的领域知识
9. Sub-agents：给 Claude 分身，让专家各司其职
10. Agent Teams：组建你的 AI 开发小队
11. 安全与回退：给 AI 戴上”安全带”
12. SDK 与 Headless：把 Claude 变成你的自动化引擎
13. 上下文工程：从记忆文件到分层知识架构
14. 模型选择与成本控制：把每一分钱花在刀刃上

Agent 智能体

前面一直在讲怎么在终端里和 Claude Code 交互——打字、确认、看结果。这个模式适合探索性的开发工作，但软件工程里还有大量需要无人值守、重复执行的任务：

• 每次提 PR 自动跑一遍代码审查
• 每天凌晨分析前一天的错误日志
• 构建流水线里自动检查安全漏洞
• 批量处理几十个文件的格式统一

这些场景不需要人坐在终端前一问一答。需要的是把 Claude Code 的能力当成一个可编程的函数来调用——给输入，拿输出，自动退出。

Claude Code 提供了两种方式实现这个目标：Headless 模式（通过 CLI 的 参数）适合脚本和 CI/CD 集成；Claude Agent SDK（TypeScript / Python 库）适合在你的应用程序里编程调用。

名称变更说明：Anthropic 已将 “Claude Code SDK” 正式更名为 Claude Agent SDK（包名 / ）。如果你之前用的是旧包名，参考官方的 Migration Guide 迁移。

加上 （或 ），Claude Code 就从”交互式对话”变成了”执行任务然后退出”：

Claude 执行任务，把结果打印到 stdout，然后退出。没有交互式界面，没有等待输入——就像 或 一样，是一个标准的命令行工具。

当输入内容很大时（日志文件、代码片段、测试结果），通过管道传入：

管道传入的内容成为 Claude 的上下文，结合你的 prompt 一起处理。这让 Claude Code 像 、 一样嵌入你的 shell 工具链——只是这个”过滤器”具备语义理解能力。

纯文本输出对人友好，但对程序不友好。 解决这个问题：

（默认）：纯文本，直接给人看。

：任务完成后输出一个完整的 JSON 对象，包含结果、执行时间、token 消耗、成本等元数据。

输出的 JSON 结构：

在脚本里用 提取你要的字段：

：实时流式输出，每一步都立即输出一个 JSON 对象（JSONL 格式）。适合需要实时反馈的场景——比如 CI 日志里想看到 Claude 执行到了哪一步。

Headless 模式下没有人在终端前点”确认”，所以权限控制尤其重要。

推荐做法：通过 精确指定允许的工具，配合 ：

如果在严格沙箱环境（容器/VM）里运行，可以用 跳过所有权限检查，让 Claude 全速自动工作。但只在你确定环境隔离的情况下使用。

：限制 Agent 的执行轮次。防止 Claude 在某个任务上无限循环。

：设置花费上限。到了就停。

：指定模型。简单任务用 haiku 省钱，复杂任务用 opus。

：让输出严格匹配指定的 JSON Schema。适合需要机器解析的场景。

：在默认 system prompt 基础上追加指令，保留 Claude Code 的默认能力。

/ ：继续之前的会话。 继续最近一次， 指定会话 ID。

把 Headless 模式用在最典型的场景——GitHub Actions 里的 PR 自动审查。

这个流水线的关键：

• 通过管道把增量代码传给 Claude——精确的上下文
• 只给读权限——CI 里不需要 Claude 改文件
• 拿到结构化结果——可以提取字段、判断是否有高风险问题
• 设置花费上限——防止意外的高成本

你还可以更进一步：用 让 Claude 输出结构化的审查结果，然后在脚本里判断是否有高风险问题——有的话让 CI 流水线失败，强制修复后才能合入。

Headless 模式通过 CLI 调用，适合脚本和 CI。但如果你在开发一个应用程序——比如一个内部的代码审查平台、一个自动化运维工具——需要在代码里直接调用 Claude 的能力，就需要 Agent SDK。

Agent SDK 和 Anthropic 的 Client SDK（直接调 API 的 ）不是同一个东西。Client SDK 给你原始的 API 调用——你自己实现 tool loop。Agent SDK 给你完整的 Agent 引擎——内置工具执行、上下文管理、会话持久化，Claude 自己决定怎么用工具完成任务。

需要 Node.js 18+（TypeScript）或 Python 3.10+（Python）。认证方式： 环境变量，也支持 AWS Bedrock（）、Google Vertex AI（）和 Azure AI Foundry（）。

Agent SDK 自带一套开箱即用的工具，不需要你自己实现：

通过 控制 Agent 能用哪些工具——权限最小化原则。

给一个 prompt，Claude 自主决定使用工具完成任务，流式返回中间过程和最终结果。

TypeScript：

Python：

返回一个 async generator（TS）或 async iterator（Python），流式 yield 消息。消息类型包括：

• ：Claude 的推理和工具调用
• ：最终结果，包含 、、 等

维护会话状态，支持多次来回。适合交互式应用、需要上下文延续的场景。

Python（推荐用法——async context manager）：

TypeScript（使用 ）：

SDK 的会话管理比 CLI 的 更完整，提供三种模式：

Fork 是个特别有用的模式。比如 SCRM 里分析了一个客户转化漏斗，想同时尝试两种优化策略——fork 出一个新 session 试 A 方案，原始 session 继续 B 方案，两边互不影响：

Session 文件存在 。跨机器恢复需要把这个文件迁移过去，且 cwd 路径要一致。

SDK 支持四种权限模式，和 CLI 的权限体系对应：

SDK 的 Hooks 和 CLI 的 shell 命令 Hooks 不同——它是回调函数，直接在你的代码里定义，可以拦截、阻止、修改 Agent 的行为。

可用的 Hook 事件：

一个实际的例子——SCRM 系统里保护敏感文件：

Hook 回调的返回值决定 Agent 的行为：

• 空对象：放行，不干预
• ：阻止这次工具调用
• ：自动批准（跳过权限确认）
• ：修改工具输入参数（必须同时返回 ）
• ：注入一条消息到对话上下文（Agent 能看到）

优先级：deny > ask > allow。多个 Hook 只要有一个返回 deny，操作就被阻止。

SDK 支持连接外部 MCP 服务器，给 Agent 注入额外能力：

你还可以把自己的业务 API 包装成 MCP 工具。比如在 SCRM 系统里，把客户数据查询暴露给 Agent：

SDK 支持定义专门化的 Sub-agents，由主 Agent 按需委派任务。注意 必须包含 才能触发 Sub-agent 调用：

Sub-agent 内部的消息会带有 字段，方便追踪哪些消息属于哪个 Sub-agent 的执行上下文。

SDK 默认不加载 CLAUDE.md、Skills、斜杠命令等项目级配置。需要显式指定 ：

SDK 支持 JSON Schema 约束输出格式，确保结果可以直接被程序解析：

简单规则：能用 CLI 解决的用 Headless，需要嵌入应用程序的用 SDK。 两者底层引擎完全相同，SDK 额外提供了编程级的 Hooks 拦截和会话 fork 能力。

从只读开始。 自动化任务的第一版，只给 权限。确认效果后再逐步开放写权限。SDK 里用 ，CLI 里用 。

设置花费上限。 无人值守的任务一定要设 （CLI）或 （SDK）。CI 里一个 PR 审查 2-5 美元通常够了。忘了设上限可能因为死循环烧掉大量预算。

设置轮次上限。 / 防止 Agent 无限循环。大多数任务 10-20 轮足够。

用结构化输出做决策。 在 CI 里不要只打印文本——用 或 拿到结构化结果，程序判断是通过还是失败。

会话续接省成本。 多步骤的自动化流程，用 或 SDK 的 复用前一步的会话，避免重新加载上下文。

用 Hooks 做审计。 SDK 的 Hook 天然适合记录审计日志——每次工具调用都能拿到工具名、参数、结果。比在 CLI 的 输出里事后分析更实时。

敏感文件加 PreToolUse 守护。 在 SDK 里用 Hook 拦截对 、、 的写操作。这比只靠 更精细——你可以只阻止特定路径，而不是完全禁用 Write 工具。

项目配置别忘了显式加载。 SDK 默认不加载 和 Skills。如果你的项目依赖这些配置，记得加 。

到这里，系列的核心内容全部覆盖了。从第一篇的 CLAUDE.md 记忆系统，到这一篇的 SDK 和自动化集成——Claude Code 从一个交互式工具变成了一个完整的 AI 工程平台。

回顾整个体系：CLAUDE.md 管记忆，斜杠命令管流程复用，Hooks 管硬约束，MCP 管能力扩展，Skills 管按需知识，Sub-agents 管上下文隔离，Agent Teams 管多实例协作，权限 + 沙箱 + Checkpointing 管安全，Headless + SDK 管自动化集成。

不需要全部用上。从你的实际痛点出发——上下文被塞满了？用 Sub-agents。规范老是被遗忘？用 Skills。CI 里想加 AI 审查？用 Headless。按需取用，逐步深入。

下篇见。