第3章：环境准备 —— 把工具都装好

一句话：搭好开发环境，跑通你人生中的第一个 Agent 程序。

本章目标

安装所有必要的开发工具（Node.js、Python、Git 等）
获取并配置 API Key
安装 Claude Code CLI 和 Agent SDK
成功运行第一个 Agent 程序，亲眼看到 Agent 自主行动

前置知识

会基本的命令行操作（打开终端、输入命令、回车）
会写基础的 TypeScript 或 Python（哪怕是 Hello World 级别的也行）
已经读完了前两章，知道 Agent 是什么、怎么工作的

3.1 必备软件安装

在开始写 Agent 代码之前，我们需要先把"工具箱"准备好。就像你要做木工活，得先有锤子、锯子、尺子一样，写代码也需要一套基础工具。

3.1.1 Node.js 18+（推荐 20 LTS）

Node.js 是运行 JavaScript/TypeScript 的环境。Claude Agent SDK 的 TypeScript 版本就跑在 Node.js 上面。

为什么推荐 20 LTS？

LTS 的意思是"长期支持版"（Long Term Support），意味着这个版本会被官方维护很长时间，Bug 少、稳定。20 是目前最推荐的 LTS 版本。

macOS 安装：

如果你用 Mac，最简单的方式是用 Homebrew（Mac 上的"应用商店"式的包管理工具）：

# 如果你还没装 Homebrew，先装它（一行命令搞定）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 然后用 Homebrew 安装 Node.js
brew install node@20

# 或者直接装最新 LTS
brew install node

Windows 安装：

Windows 用户直接去官网下载安装包：

打开浏览器，访问 https://nodejs.org
首页会显示两个大按钮，选左边那个（LTS 版本）
下载后双击安装，一路 "Next" 就行
安装过程中，记得勾选 "Add to PATH"（一般默认就是勾选的）

Linux 安装：

# Ubuntu / Debian
sudo apt update
sudo apt install -y nodejs npm

# 如果版本太旧，用 NodeSource 的仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# CentOS / RHEL / Fedora
sudo yum install -y nodejs npm
# 或者
sudo dnf install -y nodejs npm

验证安装：

不管你用哪个系统，装完之后打开终端，输入以下命令验证：

node --version
# 应该输出类似：v20.11.0

npm --version
# 应该输出类似：10.2.4

如果两个命令都输出了版本号，恭喜你，Node.js 安装成功了！

小贴士： 如果你需要在多个 Node.js 版本之间切换，推荐安装 nvm（Node Version Manager）。它可以让你在同一台电脑上安装多个 Node.js 版本，随时切换：
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装 Node.js 20
nvm install 20

# 切换到 Node.js 20
nvm use 20

3.1.2 Python 3.10+（如果你偏好 Python）

如果你更喜欢用 Python 写代码，那就需要安装 Python。Claude Agent SDK 也有 Python 版本。

macOS 安装：

# 用 Homebrew 安装
brew install python@3.12

# 验证
python3 --version
# 应该输出类似：Python 3.12.x

Windows 安装：

访问 https://www.python.org/downloads/
下载最新的 Python 3.12.x 版本
双击安装，注意！一定要勾选 "Add Python to PATH"（这一步非常重要，不勾选的话后面会遇到一堆问题）
然后点 "Install Now"

Linux 安装：

# Ubuntu / Debian
sudo apt update
sudo apt install -y python3 python3-pip python3-venv

# CentOS / RHEL
sudo yum install -y python3 python3-pip

# Fedora
sudo dnf install -y python3 python3-pip

验证安装：

python3 --version
# 应该输出类似：Python 3.12.x

pip3 --version
# 应该输出类似：pip 24.0 from ... (python 3.12)

注意： 在 Windows 上，命令可能是 python 而不是 python3，pip 而不是 pip3。

3.1.3 Git

Git 是版本控制工具，管理代码用的。后面的章节里 Agent 经常会用到 Git 命令。

macOS：

# Mac 自带 Git，但版本可能比较旧，用 Homebrew 更新
brew install git

Windows：

去 https://git-scm.com/download/win 下载安装。安装时一路 Next 即可，默认选项就行。

Linux：

sudo apt install -y git   # Ubuntu/Debian
sudo yum install -y git   # CentOS/RHEL

验证：

git --version
# 应该输出类似：git version 2.43.0

3.1.4 代码编辑器

你需要一个趁手的代码编辑器。推荐 VS Code，因为：

免费
插件超多
对 TypeScript 和 Python 支持都很好
有集成终端，写代码和运行命令在一个窗口里搞定

下载地址：https://code.visualstudio.com/

当然，如果你已经有自己喜欢的编辑器（WebStorm、Vim、Cursor 等），用你自己的就行，不影响后面的学习。

3.1.5 Docker（后面章节需要）

Docker 是容器化工具，后面讲到安全部署和实战项目时会用到。现在可以先装上，也可以等用到的时候再装。

macOS：

# 用 Homebrew 安装 Docker Desktop
brew install --cask docker
# 安装完后打开 Docker Desktop 应用

Windows：

去 https://www.docker.com/products/docker-desktop/ 下载 Docker Desktop，安装后启动。

Linux：

# Ubuntu
sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

# 让当前用户可以不用 sudo 就运行 docker
sudo usermod -aG docker $USER
# 然后重新登录终端

验证：

docker --version
# 应该输出类似：Docker version 24.0.7

docker run hello-world
# 应该看到 "Hello from Docker!" 的欢迎信息

3.1.6 检查清单

到这里，让我们确认一下所有工具都装好了。在终端里依次运行：

echo "=== 环境检查 ==="
node --version      # 期望：v18.x.x 或更高
npm --version       # 期望：9.x.x 或更高
python3 --version   # 期望：Python 3.10.x 或更高（如果你用 Python 的话）
git --version       # 期望：git version 2.x.x
docker --version    # 期望：Docker version 24.x.x（可选）
echo "=== 检查完成 ==="

全部都输出了版本号？太好了，我们继续。

3.2 获取 API Key

Agent 的"大脑"是 Claude 大语言模型，要调用它需要一个 API Key。API Key 就像一把钥匙，有了它你才能打开 Claude 这扇门。

有三种方式可以获取 API Key，我们一个一个来说。

3.2.1 方式一：Anthropic 官方 API Key（推荐，最简单）

这是最直接的方式，适合个人开发者和学习阶段。

第一步：注册账号

打开浏览器，访问 https://console.anthropic.com
点击 "Sign Up"（注册）
用邮箱注册一个账号，验证邮箱
登录进去

第二步：充值（按量付费）

登录后，点左侧导航的 "Billing"（账单）
添加信用卡（支持 Visa、MasterCard 等国际信用卡）
充值一些钱进去，学习阶段充 5 美元足够你玩很久了

关于费用： Claude Sonnet 模型的定价大约是每百万 Token 输入 3 美元、输出 15 美元。一个简单的 Agent 任务大约消耗几千到几万个 Token，也就是几分钱到几毛钱。5 美元可以跑很多次了，别担心。

第三步：生成 API Key

点左侧导航的 "API Keys"
点 "Create Key"（创建密钥）
给密钥起个名字，比如 "my-agent-learning"
点 "Create"
复制生成的密钥，它长这样：sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

非常重要：这个密钥只显示一次！复制好之后存到安全的地方。如果丢了，只能重新生成一个。

第四步：配置环境变量

拿到 API Key 后，我们要把它设置成环境变量，这样你的代码就能自动读取到它。

macOS / Linux：

# 临时设置（关掉终端就没了）
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

# 永久设置（推荐）—— 写入 shell 配置文件
# 如果你用的是 zsh（macOS 默认）：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"' >> ~/.zshrc
source ~/.zshrc

# 如果你用的是 bash：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"' >> ~/.bashrc
source ~/.bashrc

Windows（PowerShell）：

# 临时设置
$env:ANTHROPIC_API_KEY = "sk-ant-api03-你的密钥"

# 永久设置
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-你的密钥", "User")

Windows（命令提示符 CMD）：

# 临时设置
set ANTHROPIC_API_KEY=sk-ant-api03-你的密钥

# 永久设置
setx ANTHROPIC_API_KEY "sk-ant-api03-你的密钥"

验证环境变量是否设置成功：

# macOS / Linux
echo $ANTHROPIC_API_KEY
# 应该输出你的 API Key

# Windows PowerShell
echo $env:ANTHROPIC_API_KEY

3.2.2 方式二：AWS Bedrock

如果你在公司里，公司用的是 AWS 云服务，那可以通过 AWS Bedrock 来访问 Claude。Bedrock 是 AWS 提供的托管 AI 模型服务。

什么时候用 Bedrock？

你的公司已经有 AWS 账号
公司有合规要求，数据不能出 AWS
公司已经在用 Bedrock 了

怎么配置？

# 先确保你配置好了 AWS 凭证
aws configure
# 输入 Access Key ID、Secret Access Key、Region 等

# 然后设置环境变量，告诉 Claude Code 用 Bedrock
export CLAUDE_CODE_USE_BEDROCK=1

你还需要确保你的 AWS 账号已经在 Bedrock 控制台启用了 Claude 模型的访问权限。具体步骤：

登录 AWS Console
搜索 "Bedrock"
进入 Model Access
找到 Anthropic 的 Claude 模型，申请开通

注意： Bedrock 的计费走 AWS 账单，不需要单独充值给 Anthropic。

3.2.3 方式三：Google Vertex AI

如果你的公司用的是 Google Cloud，可以通过 Vertex AI 来访问 Claude。

怎么配置？

# 先用 gcloud 登录
gcloud auth application-default login

# 设置项目 ID 和区域
export ANTHROPIC_VERTEX_PROJECT_ID="你的GCP项目ID"
export CLOUD_ML_REGION="us-east5"  # 或者其他支持 Claude 的区域

# 告诉 Claude Code 用 Vertex AI
export CLAUDE_CODE_USE_VERTEX=1

3.2.4 安全提醒：API Key 的保护

千万、千万、千万不要这样做：

// 错误示范！！！永远不要把 API Key 硬编码在代码里！
const apiKey = "sk-ant-api03-xxxxxxxx";  // 大错特错！

为什么？因为：

如果你把代码推到 GitHub，全世界都能看到你的 Key
别人用你的 Key 调用 API，花的是你的钱
Anthropic 检测到 Key 泄露会自动禁用它

正确做法：

用环境变量（我们上面已经设置了）
用 .env 文件（但要加到 .gitignore 里，不要提交到代码仓库）
用密钥管理服务（AWS Secrets Manager、Google Secret Manager 等）

# 创建 .env 文件（仅供本地使用）
echo 'ANTHROPIC_API_KEY=sk-ant-api03-你的密钥' > .env

# 把 .env 加入 .gitignore，防止被提交到 Git
echo '.env' >> .gitignore

3.3 安装 Claude Code CLI

Claude Code CLI 是 Anthropic 官方的命令行工具。它本身就是一个强大的 AI Agent，可以帮你写代码、改文件、执行命令。更重要的是，Claude Agent SDK 依赖 Claude Code 作为底层引擎来运行。

3.3.1 安装

一条命令搞定：

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

这里的 -g 表示全局安装，装完之后你在任何目录下都能用 claude 命令。

验证安装：

claude --version
# 应该输出类似：1.0.x

如果提示 "command not found"，可能是因为 npm 的全局安装目录不在 PATH 里。试试这样：

# 查看 npm 全局安装目录
npm config get prefix

# 确保这个目录的 bin 子目录在 PATH 里
# 比如如果输出 /usr/local，那 /usr/local/bin 应该在 PATH 里
echo $PATH

3.3.2 第一次运行

安装好之后，让我们跑一下看看：

# 进入你的项目目录（或者任意一个目录）
cd ~/Desktop

# 启动 Claude Code 交互式会话
claude

第一次运行时，Claude Code 会：

检测你的环境变量，找到 API Key
进入一个交互式命令行界面
你可以在里面直接和 Claude 对话

试试输入一些东西：

> 你好，请告诉我当前目录下有哪些文件

你会看到 Claude 不只是"说"答案，而是会真的去执行 ls 命令，然后根据结果来回答你。这就是 Agent 的魅力 —— 说到做到。

输入 /exit 或者按 Ctrl+C 退出交互式会话。

3.3.3 CLI 常用功能速览

# 交互式对话（最常用）
claude

# 直接执行一个任务（非交互式）
claude -p "帮我创建一个 .gitignore 文件"

# 恢复上一次的对话
claude --resume

# 查看帮助
claude --help

现在你已经有了一个能用的 Claude Code CLI。不过在这个教程里，我们主要不是直接用 CLI，而是用 Claude Agent SDK 在代码里调用 Agent。CLI 只是帮助你快速验证环境是否正常。

3.4 安装 Claude Agent SDK

SDK（Software Development Kit，软件开发工具包）是让你在自己的代码里调用 Agent 的库。Claude Agent SDK 提供了 TypeScript 和 Python 两个版本，选你熟悉的语言就行。

3.4.1 TypeScript 版本（推荐）

Claude Agent SDK 是用 TypeScript 写的，TypeScript 版本的功能最全、更新最快。推荐用它。

创建项目：

# 创建项目目录
mkdir my-first-agent
cd my-first-agent

# 初始化 Node.js 项目
npm init -y

npm init -y 会自动生成一个 package.json 文件，它是 Node.js 项目的"身份证"，记录了项目信息和依赖关系。

安装 SDK 和相关依赖：

# 安装 Claude Agent SDK
npm install @anthropic-ai/claude-code

# 安装 TypeScript 开发工具
npm install -D typescript @types/node tsx

解释一下每个包是干什么的：

包名	作用
`@anthropic-ai/claude-code`	Claude Agent SDK 本体，提供 `query()` 函数
`typescript`	TypeScript 编译器
`@types/node`	Node.js 的 TypeScript 类型定义
`tsx`	TypeScript 执行器，不需要编译就能直接运行 .ts 文件

创建 TypeScript 配置文件：

在项目根目录创建一个 tsconfig.json 文件：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*", "*.ts"],
  "exclude": ["node_modules", "dist"]
}

别被这堆配置吓到，大部分都是"最佳实践"的默认配置。你现在不用完全理解它们，先用着就行。

更新 package.json：

打开 package.json，确保里面有 "type": "module" 这一行（支持 ES Module 的 import 语法）：

{
  "name": "my-first-agent",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "tsx hello-agent.ts"
  }
}

3.4.2 Python 版本

如果你更喜欢 Python，也没问题。

创建项目：

# 创建项目目录
mkdir my-first-agent
cd my-first-agent

# 创建 Python 虚拟环境（推荐，避免包冲突）
python3 -m venv venv

# 激活虚拟环境
# macOS / Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 激活后你的终端提示符前面会出现 (venv)

安装 SDK：

pip install claude-code-sdk

验证安装：

python3 -c "import claude_code_sdk; print('SDK 安装成功!')"
# 应该输出：SDK 安装成功!

注意： Python 版本的 SDK 底层还是依赖 Node.js 和 @anthropic-ai/claude-code。所以即使你用 Python，也需要先安装 Node.js 和 Claude Code CLI。这是因为 Agent 的执行引擎是用 Node.js 写的，Python SDK 只是一个调用层。

3.5 Hello Agent —— 你的第一个 Agent 程序

终于到了最激动人心的时刻！我们要写一个真正的 Agent 程序了。

这个 Agent 很简单：让它查看当前目录下有哪些文件，然后告诉我们这个项目是做什么的。

3.5.1 TypeScript 版本

在项目根目录创建文件 hello-agent.ts：

import { query, type Message } from "@anthropic-ai/claude-code";

async function main() {
  console.log("启动你的第一个 Agent...\n");

  // 调用 query() 函数，启动一个 Agent 循环
  // query() 返回一个异步迭代器，每次迭代都会产出一条消息
  const messages: Message[] = [];

  for await (const message of query({
    // prompt: 你要 Agent 做什么——用自然语言描述任务
    prompt: "请查看当前目录下有哪些文件，然后告诉我这个项目是做什么的",

    // options: Agent 的配置选项
    options: {
      // allowedTools: 允许 Agent 使用哪些工具
      // Bash: 执行命令（比如 ls）
      // Read: 读取文件内容
      // Glob: 按模式查找文件
      allowedTools: ["Bash", "Read", "Glob"],

      // permissionMode: 权限模式
      // "bypassPermissions" 表示不需要人工确认，Agent 可以自由执行
      // 注意：仅在学习和测试时用，生产环境千万别这么设！
      permissionMode: "bypassPermissions",
    },
  })) {
    // message 是 Agent 每一步产出的消息
    // 不同类型的消息代表不同的事件
    messages.push(message);

    if (message.type === "assistant") {
      // AssistantMessage: Claude 的回复
      // content 是一个数组，里面可能有文字（text）或工具调用（tool_use）
      for (const block of message.content) {
        if (block.type === "text") {
          // Agent 说了一段话，打印出来
          process.stdout.write(block.text);
        } else if (block.type === "tool_use") {
          // Agent 决定调用一个工具
          console.log(`\n[工具调用] ${block.name}`);
          console.log(`[工具参数] ${JSON.stringify(block.input).slice(0, 200)}`);
        }
      }
    } else if (message.type === "result") {
      // ResultMessage: Agent 完成了任务
      console.log("\n\n--- Agent 完成任务 ---");
      console.log(`状态: ${message.subtype}`);
      // subtype 可能是 "success"（成功）或 "error_max_turns"（超过最大轮次）等
    }
  }

  console.log(`\n总共产出了 ${messages.length} 条消息`);
}

// 运行主函数，如果出错就打印错误信息
main().catch((error) => {
  console.error("出错了:", error.message);
  process.exit(1);
});

运行：

npx tsx hello-agent.ts

3.5.2 Python 版本

在项目根目录创建文件 hello-agent.py：

import asyncio
from claude_code_sdk import query, ClaudeCodeOptions, Message


async def main():
    print("启动你的第一个 Agent...\n")

    # 收集所有消息
    messages: list[Message] = []

    # 调用 query() 函数，启动一个 Agent 循环
    # 它是一个异步生成器，每次迭代产出一条消息
    async for message in query(
        # prompt: 你要 Agent 做什么——用自然语言描述任务
        prompt="请查看当前目录下有哪些文件，然后告诉我这个项目是做什么的",
        options=ClaudeCodeOptions(
            # allowed_tools: 允许 Agent 使用哪些工具
            allowed_tools=["Bash", "Read", "Glob"],
            # permission_mode: 权限模式
            # "bypassPermissions" 表示 Agent 可以自由执行，不需要人工确认
            permission_mode="bypassPermissions",
        ),
    ):
        messages.append(message)

        if message.type == "assistant":
            # AssistantMessage: Claude 的回复
            for block in message.content:
                if block.type == "text":
                    # Agent 说了一段话
                    print(block.text, end="")
                elif block.type == "tool_use":
                    # Agent 决定调用一个工具
                    print(f"\n[工具调用] {block.name}")

        elif message.type == "result":
            # ResultMessage: Agent 完成了任务
            print("\n\n--- Agent 完成任务 ---")
            print(f"状态: {message.subtype}")

    print(f"\n总共产出了 {len(messages)} 条消息")


if __name__ == "__main__":
    asyncio.run(main())

运行：

python3 hello-agent.py

3.5.3 运行你的 Agent

确保你在项目目录（my-first-agent）下，然后运行：

# TypeScript 版本
npx tsx hello-agent.ts

# 或者 Python 版本
python3 hello-agent.py

你应该会看到类似这样的输出（具体内容取决于你的项目目录里有什么文件）：

启动你的第一个 Agent...

[工具调用] Bash
[工具参数] {"command":"ls -la"}

当前目录下有以下文件：

- package.json —— Node.js 项目的配置文件
- node_modules/ —— 依赖包目录
- hello-agent.ts —— 你的第一个 Agent 程序
- tsconfig.json —— TypeScript 配置文件

[工具调用] Read
[工具参数] {"file_path":"package.json"}

根据 package.json 的内容，这个项目叫 "my-first-agent"，
它安装了 Claude Agent SDK，看起来是一个用来学习 AI Agent 开发的项目。

--- Agent 完成任务 ---
状态: success

总共产出了 3 条消息

看到了吗？ Agent 不是在那里瞎编，它是真的执行了 ls 命令，读取了 package.json 文件，然后根据真实的信息来回答你的问题。这就是 Agent 和普通聊天机器人的根本区别。

3.6 理解输出 —— Agent 到底干了什么？

让我们仔细拆解一下 Agent 的运行过程，理解每一步到底发生了什么。

3.6.1 消息流程

一次完整的 Agent 运行会产出以下类型的消息：

┌─────────────────────────────────────────────┐
│ 1. SystemMessage (type: "system")           │
│    Agent 初始化完成，告诉你 session_id       │
│    这是 Agent 的"开机"信号                   │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│ 2. AssistantMessage (type: "assistant")     │
│    Claude 的第一次回复                       │
│    可能包含：文字 + 工具调用                  │
│    比如："让我先看看目录" + 调用 Bash(ls)     │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│ 3. AssistantMessage (type: "assistant")     │
│    Claude 拿到工具结果后的回复               │
│    可能包含：分析结果的文字 + 更多工具调用    │
│    比如："我看到有 package.json" + 调用 Read  │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│ 4. AssistantMessage (type: "assistant")     │
│    Claude 读完文件后的最终分析               │
│    不再调用工具了，纯文字回复                │
│    "这个项目是一个 Agent 学习项目..."        │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│ 5. ResultMessage (type: "result")           │
│    Agent 认为任务完成了                      │
│    subtype: "success" 表示成功完成           │
└─────────────────────────────────────────────┘

3.6.2 消息类型详解

SystemMessage（初始化消息）：

{
  type: "system",
  subtype: "init",
  session_id: "abc123-def456-...",  // 会话 ID，后面恢复会话时要用
  tools: ["Bash", "Read", "Glob"],  // Agent 可用的工具列表
  model: "claude-sonnet-4-20250514" // 使用的模型
}

AssistantMessage（助手消息）：

{
  type: "assistant",
  content: [
    // 文字内容
    { type: "text", text: "让我来看看当前目录有什么..." },
    // 工具调用
    {
      type: "tool_use",
      id: "tool_abc123",
      name: "Bash",
      input: { command: "ls -la" }
    }
  ],
  stop_reason: "tool_use"  // 停下来是因为要调用工具
}

ResultMessage（结果消息）：

{
  type: "result",
  subtype: "success",       // 成功完成
  cost_usd: 0.003,          // 本次调用花了多少钱（美元）
  duration_ms: 5200,         // 耗时多少毫秒
  duration_api_ms: 4800,     // API 调用耗时
  num_turns: 3,              // Agent 循环了几轮
  session_id: "abc123..."    // 会话 ID
}

3.6.3 Agentic Loop（代理循环）可视化

回顾第2章讲的"代理循环"，在这个 Hello Agent 例子里，Agent 实际的循环过程是这样的：

第1轮循环：
  思考："用户让我查看文件，我应该用 Bash 执行 ls 命令"
  行动：调用 Bash("ls -la")
  观察：得到文件列表 → package.json, node_modules/, hello-agent.ts...
  判断："我看到了 package.json，应该读一下它的内容来了解项目"

第2轮循环：
  思考："我来读取 package.json 看看项目信息"
  行动：调用 Read("package.json")
  观察：得到 package.json 的内容
  判断："现在我有足够的信息来回答用户了"

第3轮循环：
  思考："让我整理一下信息，给用户一个完整的回答"
  行动：输出最终回复（纯文字，不再调用工具）
  判断："任务完成！"

看，这就是 Agent 的核心逻辑 —— 不断地 "想→做→看→再想"，直到任务完成。

3.7 常见问题排查

新手在搭环境的时候难免会遇到各种问题。别慌，这里列出了最常见的几个问题和解决方法。

3.7.1 API Key 没有配置对

错误信息：

Error: ANTHROPIC_API_KEY environment variable is not set

或者：

Error: Invalid API Key

解决方法：

检查环境变量是否设置了：

echo $ANTHROPIC_API_KEY

如果输出为空，说明没设置。回到 3.2 节重新设置。
如果输出了值但还报错，检查一下：
- Key 有没有复制全？（不要有多余的空格或换行）
- Key 是不是以 sk-ant- 开头？
- Key 有没有过期或被禁用？去 https://console.anthropic.com/api-keys 看看
检查是不是在当前终端窗口设置的。环境变量只在当前终端有效，如果你新开了一个终端窗口，需要重新设置（或者写入 shell 配置文件）。

3.7.2 网络问题

错误信息：

Error: connect ETIMEDOUT

或者：

Error: fetch failed

解决方法：

如果你在中国大陆，可能需要配置代理才能访问 Anthropic 的 API。

# 设置 HTTP 代理
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

# 7890 是常见的代理端口，换成你自己的代理地址和端口

如果你用的是 VPN 或者其他代理工具，确保它是开着的，并且终端里的代理变量设置正确。

你也可以在 shell 配置文件中永久设置代理：

# 写入 ~/.zshrc 或 ~/.bashrc
echo 'export HTTP_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
source ~/.zshrc

3.7.3 Permission Denied（权限被拒绝）

错误信息：

Error: EACCES: permission denied

解决方法：

这通常是 npm 全局安装时的权限问题。

# 方法1：用 sudo（不太推荐，但最快）
sudo npm install -g @anthropic-ai/claude-code

# 方法2：修改 npm 全局安装目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 把新目录加入 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 然后重新安装
npm install -g @anthropic-ai/claude-code

3.7.4 Module not found（找不到模块）

错误信息：

Error: Cannot find module '@anthropic-ai/claude-code'

解决方法：

确认你在项目目录里运行了 npm install：

cd my-first-agent
npm install

检查 node_modules 目录是否存在：

ls node_modules/@anthropic-ai/

如果还不行，删除 node_modules 重新装：

rm -rf node_modules package-lock.json
npm install

3.7.5 Python 版本太旧

错误信息：

SyntaxError: invalid syntax

或者：

ModuleNotFoundError: No module named 'claude_code_sdk'

解决方法：

检查 Python 版本：

python3 --version

如果低于 3.10，需要升级。Python SDK 需要 Python 3.10 或更高版本，因为它用到了一些新语法特性（比如 match 语句和类型联合 X | Y）。

# macOS
brew install python@3.12

# Ubuntu
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv

3.7.6 Claude Code CLI 找不到

错误信息：

zsh: command not found: claude

解决方法：

# 检查 claude 装到哪里了
npm list -g @anthropic-ai/claude-code

# 查看 npm 全局 bin 目录
npm config get prefix
# 假设输出 /usr/local，那 claude 应该在 /usr/local/bin/claude

# 检查 PATH
echo $PATH

# 如果 npm 的 bin 目录不在 PATH 里，手动添加
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3.7.7 TypeScript 执行报错

错误信息：

TypeError: Unknown file extension ".ts"

解决方法：

确保你用的是 tsx 来运行 .ts 文件，而不是直接用 node：

# 错误的方式
node hello-agent.ts  # 不行！Node.js 不能直接运行 .ts 文件

# 正确的方式
npx tsx hello-agent.ts  # 用 tsx 运行

动手练习

理论说了一大堆，现在是你动手的时间了。

练习1：运行 Hello Agent，观察输出

任务： 按照 3.5 节的步骤，创建并运行 Hello Agent 程序。

要求：

观察 Agent 调用了哪些工具
观察每次工具调用的参数是什么
观察最终的回复内容
记录下 Agent 总共循环了几轮

练习2：修改 Prompt，让 Agent 做不同的事

任务： 修改 hello-agent.ts（或 hello-agent.py）里的 prompt，尝试让 Agent 做以下事情：

// 试试这些 prompt：
prompt: "请帮我创建一个名为 test.txt 的文件，内容是'Hello from Agent!'"

prompt: "请查看当前系统的 Node.js 版本、npm 版本和操作系统信息"

prompt: "请创建一个简单的 HTML 文件，包含一个标题和一个段落"

观察 Agent 是如何理解你的需求、选择工具、执行任务的。

练习3：限制工具，观察 Agent 的行为变化

任务： 试着把 allowedTools 里的 "Bash" 去掉：

allowedTools: ["Read", "Glob"],  // 注意：没有 Bash 了！

然后重新运行，观察 Agent 的行为有什么变化。

思考题：

没有了 Bash 工具，Agent 还能查看目录下有什么文件吗？（提示：它还有 Glob 工具）
Agent 的行为和之前有什么不同？
从这个实验你能得出什么结论？

本章小结

这一章我们做了很多事情，让我们回顾一下：

安装了开发工具：Node.js、Python（可选）、Git、VS Code、Docker（可选）
获取了 API Key：从 Anthropic 官网拿到了 API Key，配置成了环境变量
安装了 Claude Code CLI：用 npm install -g @anthropic-ai/claude-code 一条命令搞定
安装了 Agent SDK：创建了项目，安装了 @anthropic-ai/claude-code 包
跑通了第一个 Agent 程序：亲眼看到 Agent 自主查看文件、分析内容、给出回答
理解了 Agent 的消息流：SystemMessage、AssistantMessage、ResultMessage
掌握了常见问题的排查方法：API Key、网络、权限、模块等

最重要的一点： 你已经亲手让一个 AI Agent 跑起来了！它不只是"回答问题"，而是真的去执行命令、读取文件、然后给你分析结果。这就是 Agent 和普通聊天机器人的本质区别。

下一章预告

环境搭好了，第一个 Agent 也跑通了。但你可能已经注意到了，我们的 hello-agent.ts 里用到了 query() 函数，传了 prompt、options 等参数。这些到底是什么意思？有哪些参数可以配置？

下一章 《第4章：query() —— Agent 的启动按钮》，我们会深入学习 query() 函数的所有参数和用法。它是整个 Claude Agent SDK 的核心，掌握了它，你就掌握了 Agent 开发的基本功。

到时候见！