Claude Agent SDK 开发指南：从环境搭建到自动化代码审查与重构-代码聚汇网

Claude Agent SDK 开发指南：从环境搭建到自动化代码审查与重构

Claude Agent SDKAgent开发Claude Code

|难度：普通|阅读约 14 分钟

如果你试过在终端里把 Claude Code 当成一个"高级下手"来用，大概会有这种感觉：每做一步都要亲手敲提示词、确认权限、把上一轮的输出粘到下一轮，几轮下来人比机器还累。我今年把自己团队里的一批代码审查和批量重构任务，从"人肉调度 Claude Code"改成了基于 Claude Agent SDK 托管，最大的感受是：以前我是那个负责复制粘贴、确认权限、拼接上下文的工具人，现在这些事终于可以交给代码了。

Claude Agent SDK 不是又一个聊天客户端，它把 Claude Code 的完整 Agent 能力——工具调用、文件读写、命令执行、多轮任务规划——封装成一套 TypeScript 编程接口。不管你是正在做 Agent 开发、想给内部工具加一个"能自己跑代码的 AI 助手"，还是单纯想搞懂 Agent 框架到底怎么把大模型和操作系统串起来，这篇文章都值得你花十分钟读完。我会从环境搭建讲到最后上线踩坑，全程按我实际走过的路来写。

1. 先搞清楚 Agent SDK 和"装了个 Claude Code"到底有什么区别

1.1 它解决的是"人肉调度"问题

很多人第一次接触 Claude Agent SDK 时会有一个困惑：我明明已经在终端里装好了 Claude Code，也用得很顺手，为什么还要多学一个 SDK？这个问题我一开始也没想明白，直到我在自动化场景里连续吃了几次亏。

手动操作 Claude Code 的时候，整个流程是这样的：你输入一个目标，它自己规划、调用工具、读文件、跑命令，遇到危险操作会弹权限确认，你点头它继续。这个过程本身很顺畅，问题出在"人"这个环节。如果你只有三五次对话，手动完全没问题；但如果你的任务是每天批量处理几十个仓库的代码迁移、每周在 CI 里跑一轮全量依赖升级，或者想把它嵌进自己的 Web 服务里给用户用，那你不可能坐在终端前面一条条地敲提示词、一遍遍地确认权限。

Claude Agent SDK 就是把这个"人肉调度"过程程序化：你在代码里用 query() 发一个目标，它会自动拉起一个完整的 Claude Code 会话，Agent 自己规划步骤、调用工具、处理错误，最后把结果以结构化消息流的形式返回给你。中间那些权限判断、会话管理、工具调用细节，都被 SDK 的选项参数接管了。

1.2 它在整套技术栈里的位置

我在给团队做技术选型的时候，习惯性地把方案分成了三层，这样跟人解释最清楚：

方案	控制方式	适合场景	开发成本
Claude Code CLI	终端里人机对话	临时任务、个人辅助、探索性开发	极低
Claude Agent SDK	代码里发起 Agent 会话	自动化流水线、服务化 Agent、批量任务	中等
Anthropic Messages API	自己写完整 Agent 循环	需要完全掌控推理链路和工具调度的定制系统	高

CLI 和 SDK 底层用的是同一个 Agent 引擎，区别在于谁在"驾驶"。CLI 的驾驶位是终端用户，SDK 的驾驶位是你的代码。而 Messages API 更底层，它只给你模型能力，工具调用、上下文管理、多轮规划全得自己写，相当于你不仅要会开车，还得自己造发动机。

对大多数团队来说，如果想快速把 Agent 能力接入业务，SDK 是性价比最高的一层：你不用重新发明 Agent 循环，也不用放弃 Claude Code 已有的工具生态，只需要把"目标"和"约束"通过参数传进去。

1.3 什么项目才值得上 SDK

结合我自己的实践，下面这几类场景用 SDK 收益非常明显：

批量代码审查：每次 PR 自动拉起一个 Agent，带着 diff 上下文跑一轮审查，输出结构化问题清单。
自动化重构：比如把项目里所有的 moment 调用迁移到 dayjs，这类重复性高、需要读代码改代码的活，Agent 比人耐心得多。
CI / CD 集成：在流水线里加一个"智能修复"步骤，lint 报错了让 Agent 自动改，改完再跑测试。
知识库问答：让 Agent 带着用户的自然语言问题去检索代码库、读文档、最后返回答案，包成 API 给前端用。

但也有不适合的情况。如果你的任务只是偶尔问一句"这个函数是干嘛的"，那直接用 CLI 就行，上 SDK 反而多一层维护成本。如果你需要的是对模型输出格式做极其严格的控制、整个推理过程都要自己编排，那不如直接用 Messages API。SDK 适合的是"标准 Agent 行为 + 少量定制"的中间地带。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与安装：把"claude 不是内部或外部命令"这类问题一次解决

2.1 安装前要准备好的三件事

SDK 的安装本身不复杂，但我在帮同事排查环境的时候发现，大部分人卡住不是因为 SDK 装不上，而是前置条件没准备好。总结下来就三件事。

第一，Node.js 版本。Claude Agent SDK 是 TypeScript 写的，要求 Node.js 18 及以上。如果你机器上还是 Node 16，先升级，不然后面跑 npm install 就会报引擎版本不兼容。用 node -v 看一眼，低于 18 就先处理这个。

第二，Claude Code 本体。SDK 并不是完全独立的运行时，它内部会调用本机安装的 Claude Code CLI 来驱动 Agent 会话。所以装 SDK 之前，必须先把 Claude Code 装好并且完成认证。命令行工具装的是 @anthropic-ai/claude-code，SDK 装的是 @anthropic-ai/claude-agent-sdk，两个包都要有，缺一个都会在运行时出各种奇怪问题。

第三，认证方式。Claude Code 首次运行需要登录，要么用账号走 OAuth 流程，要么配 API Key。这一步如果没做，SDK 调用时会在初始化阶段就报认证失败，而且报错信息有时候很隐晦，容易让人误以为是 SDK 的问题。

2.2 安装与验证

前置条件满足后，安装流程其实就两条命令：

bash复制# 全局安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 在项目里安装 Agent SDK
npm install @anthropic-ai/claude-agent-sdk

安装完先验证 CLI 是否正常：

bash复制claude --version

能输出版本号就说明 CLI 可用。然后跑一次 claude 进入交互界面完成登录认证，认证书面上会引导你走完。认证完成后，退出交互界面，再写一个最简单的 SDK 脚本验证链路是不是通的。

这里我特别提醒一句：如果你用的是公司代理或自定义 npm 镜像，装完包之后一定要在项目里实际跑一次再继续，别以为 npm install 没报错就万事大吉。SDK 和 CLI 之间的双向通信很敏感，镜像源装出来的包偶尔会有二进制路径问题，只有跑到真实调用才能暴露出来。

2.3 Windows 下最常见的一个坑：命令找不到

我估计不少人搜"Claude Agent SDK 开发指南"的时候，其实是被这个报错逼来的：

code复制claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

这个报错在 Windows 的 PowerShell 里特别常见，英文环境对应的是 claude is not recognized as the name of a cmdlet, function, script file, or operable program。原因很简单：npm 全局包的安装目录没有加到系统的 PATH 环境变量里，PowerShell 找不到 claude 这个命令。

排查和修复步骤如下：

先确认 npm 全局目录在哪：npm config get prefix，输出一般是 C:\Users\你的用户名\AppData\Roaming\npm 或者你自己指定的路径。
打开系统环境变量设置，在 Path 里加上这个目录（注意是 prefix 指向的目录本身，不是里面的 node_modules）。
开一个新的 PowerShell 窗口（必须新开，旧窗口不会刷新环境变量），再执行 claude --version。

如果你是用 nvm-windows 管理的 Node，还要特别注意：每次切换 Node 版本后，npm 全局目录的 PATH 可能指向旧版本的位置，这时候同样会报"命令找不到"。遇到这种，直接重新执行 npm config get prefix 确认当前路径。

另外，VSCode 里"claude 不是内部或外部命令"这类问题，大概率也是同一个原因。VSCode 的集成终端继承的是打开 VSCode 时的环境变量，改完 PATH 之后要完全关闭 VSCode 再重开，不要只刷新终端窗口。

2.4 第一个 Hello Agent

环境通了之后，先跑一个最小例子。我建议用 query() 而不是 task() 来入门，因为你能看到完整的消息流，对理解 SDK 的工作方式有好处。

typescript复制import { query } from "@anthropic-ai/claude-agent-sdk";

const response = query({
  prompt: "当前目录下有哪些文件？",
  options: {
    cwd: "./",
    permissionMode: "bypassPermissions",
  },
});

for await (const message of response) {
  if (message.type === "result") {
    console.log("最终结果：", message.result);
    console.log("总轮数：", message.numTurns);
    console.log("估算成本：", message.totalCostUsd);
  }
}

把这个脚本保存成 hello-agent.ts，用 tsx 或 ts-node 运行。如果你看到控制台输出了文件清单和成本估算，说明 SDK 到 CLI 到模型服务的整条链路已经打通了。我第一次跑通的时候，看到 totalCostUsd 那一行数字，才真正意识到以后每次调用都是真金白银，这也促使我后来在做长任务时特别在意 maxTurns 和超时控制。