第 0 章：前言与环境准备

在开始写代码之前，先搞清楚我们要干什么、需要什么。

1. Claude Agent SDK 是什么？

一句话解释

Claude Agent SDK 就是给 Claude 写的"遥控器"。

你可能已经用过 Claude 的网页版——打开浏览器，输入问题，等回答。这就像你站在电视机前面按按钮换台：能用，但只能一个人、手动操作。

而 Claude Agent SDK 做的事情，是让你 用 Python 代码来操控 Claude。就像给电视配了一个万能遥控器——你可以写个脚本，让它自动换台、定时录制、批量操作，甚至把好几台电视串起来一起管。

和网页聊天有什么不同？

简单说：网页版是人机对话，SDK 是机器对机器。

SDK 能做什么？5 个实际场景

别觉得这东西离你很远，看看这些例子：

场景 1：自动化代码审查

团队里每次提交 PR，自动让 Claude 审查代码，找出 Bug、安全隐患、代码风格问题，然后把审查意见自动贴到 PR 评论里。以前需要等同事有空才能审，现在秒出结果。

场景 2：批量文档处理

公司有 200 份技术文档需要翻译成中文？手动一个个在网页上粘贴、复制？用 SDK 写个脚本，一个 for 循环全搞定，该喝茶喝茶去。

场景 3：构建 AI 助手

想做一个能读写文件、执行命令的 AI 编程助手？SDK 让你完全控制 Claude 能用哪些工具、怎么用，搭建自己的专属 AI 助手。这也是我们这个教程系列后面要做的事。

场景 4：CI/CD 集成

在持续集成流水线里加一步——让 Claude 自动检查代码变更，判断有没有破坏性修改，自动生成 changelog。全程无需人工介入。

场景 5：数据分析自动化

每天早上自动拉取数据库报表，让 Claude 分析异常指标，生成摘要邮件发给团队。老板看了直呼专业。

2. 两种使用模式

SDK 支持两种认证方式来连接 Claude。你可以根据自己的情况选一种，不需要两种都配。

模式 A：API Key 模式（按量计费）

这种模式就像手机的流量套餐——用多少算多少钱。适合正式项目、自动化脚本、后端服务。

第一步：获取 API Key

1. 打开 console.anthropic.com
2. 注册或登录你的 Anthropic 账号
3. 在左侧菜单找到 "API Keys"
4. 点击 "Create Key"，起个名字（比如 "my-sdk-key"）
5. 复制生成的 Key——注意：这个 Key 只显示一次，复制好保存起来

第二步：配置环境变量

把 Key 设置为环境变量，这样 SDK 就能自动找到它：

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-api03-你的key内容..."

# 想让它永久生效？加到 shell 配置文件里：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的key内容..."' >> ~/.zshrc
# 或者如果你用 bash：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的key内容..."' >> ~/.bashrc

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-api03-你的key内容..."

# 想永久生效？设置系统环境变量：
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-你的key内容...", "User")

安全提醒：永远不要把 API Key 写进代码里提交到 Git！用环境变量或 .env 文件管理。

模式 B：订阅账号模式（Claude Pro / Max）

如果你已经在用 Claude Pro 或 Max 订阅，不用再花钱买 API Key，直接用你的订阅账号就行。这种模式就像包月不限量——适合个人学习、日常开发。

配置方式：

# 确保你已经安装了 Claude Code CLI（后面会讲怎么装）
claude login

运行后会弹出浏览器，用你的 Claude 订阅账号登录即可。登录一次，后续使用时 SDK 会自动用这个身份。

两种模式对比

我该选哪个？ 如果你只是跟着教程学习，用订阅账号模式最省事。如果你要部署到服务器或 CI/CD，那必须用 API Key 模式。

3. 环境搭建（手把手）

下面一步步来，跟着做就行。

3.1 安装 uv

我们用 uv 来管理 Python 环境和依赖。uv 是一个极速的 Python 包管理工具，比 pip 快 10-100 倍，而且自带虚拟环境管理，一个工具搞定所有事。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或者用 Homebrew（macOS）
brew install uv

安装完验证一下：

uv --version

小贴士：如果提示找不到 uv 命令，重新打开一个终端窗口再试。

3.2 创建项目和虚拟环境

用 uv 初始化项目，它会自动帮你创建虚拟环境：

# 创建项目目录并初始化
uv init claude-sdk-tutorial
cd claude-sdk-tutorial

这一步 uv 会自动帮你： - 创建 pyproject.toml（项目配置文件） - 创建 .venv 虚拟环境 - 如果系统没有合适的 Python 版本，uv 会自动下载安装

小贴士：uv 内置了 Python 版本管理，不需要提前装好 Python。如果你想指定 Python 版本，可以用 uv init --python 3.12 claude-sdk-tutorial。

如果你不想用 uv init，也可以手动创建虚拟环境：

mkdir claude-sdk-tutorial
cd claude-sdk-tutorial

# 创建虚拟环境（如果系统没有 Python 3.10+，uv 会自动下载）
uv venv

# 激活虚拟环境
# macOS / Linux：
source .venv/bin/activate

# Windows：
# .venv\Scripts\activate

3.3 安装 Claude Agent SDK

一条命令搞定：

uv add claude-agent-sdk

注意包名：PyPI 上的包名是 claude-agent-sdk（带横杠），但 import 的时候用 claude_agent_sdk（下划线）。别搞混了。

安装完可以快速验证一下：

uv run python -c "import claude_agent_sdk; print('SDK 版本:', claude_agent_sdk.__version__)"

3.4 安装 Claude Code CLI

SDK 在底层需要调用 Claude Code 命令行工具，所以还得装一个 CLI。它是通过 npm 安装的（Node.js 的包管理器）。

如果你还没装 Node.js：

# macOS（Homebrew）
brew install node

# 或者去 https://nodejs.org 下载安装包

安装 CLI：

npm install -g @anthropic-ai/claude-code

验证安装：

claude --version

看到版本号就说明装好了。

3.5 配置认证

根据你选的模式，二选一执行：

选了 API Key 模式的：

export ANTHROPIC_API_KEY="sk-ant-api03-你的key..."

选了订阅账号模式的：

claude login

3.6 验证一切就绪

我们准备了一个环境检查脚本，一键检测所有依赖是否安装正确。

把下面的命令复制到终端运行（假设你在项目根目录）：

# 下载检查脚本（如果你是跟着教程的 Git 仓库走的，文件已经在这里了）
python examples/check_setup.py

或者直接运行本章附带的脚本：

python tutorial-cc/00-前言与环境准备/examples/check_setup.py

如果一切顺利，你会看到这样的输出：

==================================================
  Claude Agent SDK 环境检查
==================================================

Python 版本:
  [OK] Python 3.12.4

SDK 安装:
  [OK] claude-agent-sdk 0.1.39

CLI 工具:
  [OK] Claude CLI 已安装: /usr/local/bin/claude

认证配置:
  [OK] API Key 模式: sk-ant-api03-...xxxx

==================================================
  所有检查通过！可以开始学习了。
==================================================

如果有 [FAIL] 项，按照提示信息修复后重新运行脚本即可。

4. 常见问题 FAQ

Q: 遇到 "Claude Code not found" 怎么办？

这说明 Claude Code CLI 没装好，或者 claude 命令不在系统 PATH 里。

排查步骤：

# 1. 确认 npm 装了没
npm --version

# 2. 确认 claude 装了没
npm list -g @anthropic-ai/claude-code

# 3. 如果装了但找不到，可能是 npm 全局路径不在 PATH 里
# 查看 npm 全局安装路径：
npm config get prefix

# 把输出的路径加到 PATH（以 macOS 为例）：
# 如果输出是 /usr/local，那 claude 应该在 /usr/local/bin/ 下
# 确认 /usr/local/bin 在你的 PATH 里：
echo $PATH | tr ':' '\n' | grep -i local

如果上面都不行，试试重新安装：

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Q: API Key 和订阅能不能同时用？

可以。如果你同时设置了 ANTHROPIC_API_KEY 环境变量和 claude login，API Key 会优先。

想切换到订阅模式？把环境变量删掉就行：

unset ANTHROPIC_API_KEY

Q: 国内网络访问有问题怎么办？

Anthropic 的 API 服务器在海外，如果你在国内直连可能会超时或者连不上。几个解决思路：

1. 使用代理：配置 HTTP 代理环境变量 bash export HTTP_PROXY="http://127.0.0.1:7890" export HTTPS_PROXY="http://127.0.0.1:7890"

2. 检查 DNS：有时候换个 DNS 就好了（比如 8.8.8.8 或 1.1.1.1）

3. 使用云服务器：在海外的云服务器（AWS、GCP 等）上运行你的代码

Q: uv add claude-agent-sdk 报错怎么办？

最常见的原因：

1. Python 版本太低：确认 python --version >= 3.10，或者用 uv init --python 3.12 让 uv 自动安装合适的版本
2. uv 版本太旧：升级 uv bash uv self update
3. 网络问题：试试用镜像源 bash UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv add claude-agent-sdk

Q: 虚拟环境有必要吗？

强烈建议用。虽然不是必须的，但虚拟环境能避免包版本冲突。不同项目可能需要不同版本的依赖，虚拟环境让它们互不干扰。

好消息是，如果你用了 uv init 或 uv venv，虚拟环境已经自动创建好了，不需要额外操作。

Q: Windows 用户有什么特别注意的？

Claude Code CLI 在 Windows 上需要通过 WSL（Windows Subsystem for Linux）运行。步骤：

1. 安装 WSL：在 PowerShell 中运行 wsl --install
2. 在 WSL 中安装 Node.js 和 Python
3. 在 WSL 环境里按照上面的 Linux 步骤操作

接下来

环境准备好了，下一章我们就正式写代码了。

下一章预告：第 1 章 - 第一次和 Claude 对话

我们会用不到 10 行 Python 代码，让 Claude 回答你的第一个问题，并且理解 SDK 的基本工作方式。

本章小结

• Claude Agent SDK 是用 Python 控制 Claude 的工具包，让你能编程式地使用 AI
• 两种认证模式：API Key（按量付费）和订阅账号（包月），选一种配好就行
• 环境依赖：uv、claude-agent-sdk（uv add）、Claude Code CLI（npm 包）
• 运行 check_setup.py 一键检查环境是否就绪