
一、环境准备
1. 前置依赖要求
使用 Claude Code SDK 需满足以下环境条件:
- Python 版本:3.10 及以上
- 必须安装 Node.js(用于运行 Claude Code 核心 CLI 工具)
- Claude Code CLI 工具:通过 npm 全局安装
2. 安装步骤
(1)安装 Node.js(略)
根据操作系统(Windows/macOS/Linux)从 Node.js 官网 下载并安装,验证安装成功:
node -v # 输出 Node.js 版本号
npm -v # 输出 npm 版本号
(2)安装 Claude Code CLI 工具
npm install -g @anthropic-ai/claude-code
(3)安装 Python SDK
pip install claude-code-sdk
二、核心概念与基础用法
1. 核心功能概述
Claude Code SDK 是 Anthropic 推出的 Python 客户端,用于与 Claude Code 交互,核心能力包括:
- 异步查询 Claude Code,支持流式响应
- 配置对话参数(系统提示、工作目录、允许的工具等)
- 集成内置工具(Read/Write/Bash 等)
- 自定义工具(基于 MCP 协议的进程内工具)
- 钩子函数(Hook):在工具调用等环节插入自定义逻辑
2. 快速入门:最简示例
以下示例实现最基础的 Claude Code 调用,获取 “2 + 2” 的计算结果:
# 导入必要的库:anyio 用于运行异步函数,query 是核心查询函数
import anyio
from claude_code_sdk import query
# 定义异步主函数
async def main():
"""
快速入门示例:调用 Claude Code 计算 2 + 2
query 函数返回异步迭代器,逐行接收响应
"""
# 调用 query 函数,传入提示词,异步遍历响应消息
async for message in query(prompt="What is 2 + 2?"):
# 打印每一条响应消息(流式输出)
print(message)
# 使用 anyio 运行异步函数(asyncio 也可,但 anyio 是 SDK 推荐方式)
if __name__ == "__main__":
anyio.run(main)
代码说明:
- query() 是 SDK 核心异步函数,返回 AsyncIterator(异步迭代器),支持流式接收 Claude 的响应;
- anyio.run() 用于运行异步主函数,是 Python 异步编程的常用方式;
- 运行结果会逐行打印 Claude 的响应(如 “2 + 2 = 4”)。
3. 基础用法:解析响应内容
query() 返回的消息包含不同类型(如助手消息、工具调用消息),需解析后提取有效内容:
from claude_code_sdk import query, AssistantMessage, TextBlock
async def parse_response_example():
"""
基础用法:解析 Claude Code 的响应,提取纯文本内容
"""
# 简单查询:向 Claude 发送问候
async for message in query(prompt="Hello Claude, introduce yourself briefly"):
# 过滤出助手消息(AssistantMessage)
if isinstance(message, AssistantMessage):
# 遍历消息内容块(可能包含文本、工具调用等)
for block in message.content:
# 过滤出文本块(TextBlock),提取纯文本
if isinstance(block, TextBlock):
print("Claude 响应:", block.text)
# 运行函数
if __name__ == "__main__":
anyio.run(parse_response_example)
代码说明:
- AssistantMessage:表示 Claude 发送的助手消息(核心响应类型);
- TextBlock:表示消息中的纯文本内容块(另有 ToolUseBlock/ToolResultBlock 等类型);
- 通过类型判断可精准提取所需内容,避免打印无关元数据。
4. 配置 ClaudeCodeOptions
ClaudeCodeOptions 用于自定义对话参数,如系统提示、最大轮数、工作目录等:
from claude_code_sdk import query, ClaudeCodeOptions
from pathlib import Path
async def with_options_example():
"""
带配置项的查询示例:自定义系统提示、工作目录、允许的工具
"""
# 定义配置项
options = ClaudeCodeOptions(
# 系统提示:定义 Claude 的角色和行为
system_prompt="你是一个专业的 Python 开发者,回答简洁且准确",
# 最大对话轮数
max_turns=1,
# 工作目录:Claude 执行文件操作(Read/Write)时的根目录
cwd=Path("./my_project"), # 支持字符串或 Path 对象
# 允许使用的工具:Bash(执行命令)、Read(读取文件)、Write(写入文件)
allowed_tools=["Bash", "Read", "Write"],
# 权限模式:自动接受文件编辑(无需人工确认)
permission_mode='acceptEdits'
)
# 传入配置项进行查询
async for message in query(
prompt="在当前工作目录创建一个 hello.py 文件,内容为打印 'Hello Claude Code'",
options=options
):
# 解析并打印响应
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(block.text)
if __name__ == "__main__":
anyio.run(with_options_example)
关键配置项说明:
| system_prompt | 定义 Claude 的角色和行为准则 | “你是一个严谨的代码审核专家” |
| max_turns | 限制对话最大轮数 | 3 |
| cwd | 指定 Claude 执行文件/命令的工作目录 | Path(“./project”) |
| allowed_tools | 允许 Claude 使用的工具列表 | [“Read”, “Write”, “Bash”] |
| permission_mode | 工具权限模式(如自动接受文件编辑) | “acceptEdits” |
三、高级功能:ClaudeSDKClient
ClaudeSDKClient 是比 query() 更强大的客户端,支持双向交互式对话、自定义工具、钩子函数,适合复杂场景。
1. 基本使用方式
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
async def client_basic_example():
"""
ClaudeSDKClient 基础示例:交互式对话
"""
# 定义配置项
options = ClaudeCodeOptions(
system_prompt="你是一个友好的助手,回答简洁",
allowed_tools=["Bash"]
)
# 使用 async with 管理客户端(自动释放资源)
async with ClaudeSDKClient(options=options) as client:
# 发送查询
await client.query("执行 bash 命令:echo 'Hello from ClaudeSDKClient'")
# 接收并打印响应
async for msg in client.receive_response():
if isinstance(msg, AssistantMessage):
for block in msg.content:
if isinstance(block, TextBlock):
print(block.text)
if __name__ == "__main__":
anyio.run(client_basic_example)
2. 自定义工具(In-Process MCP 服务器)
自定义工具是运行在 Python 进程内的 MCP(Model Context Protocol)服务,相比外部 MCP 服务器,无需跨进程通信,性能更高、调试更简单。
2.1 实现自定义工具的完整示例
from claude_code_sdk import tool, create_sdk_mcp_server, ClaudeCodeOptions, ClaudeSDKClient, AssistantMessage, TextBlock
# ———————- 步骤1:定义自定义工具 ———————-
@tool(
name="greet", # 工具名称(需唯一)
description="向用户发送问候语", # 工具描述(Claude 用于理解工具用途)
parameters={"name": str} # 工具参数:name 为字符串类型
)
async def greet_user(args):
"""
自定义工具实现:接收用户名,返回问候语
:param args: 包含工具参数的字典,如 {"name": "Alice"}
:return: 符合 MCP 协议的响应格式
"""
# 提取参数
username = args.get("name", "未知用户")
# 构造响应(必须遵循该格式)
return {
"content": [
{"type": "text", "text": f"你好,{username}!👋"}
]
}
# ———————- 步骤2:创建 MCP 服务器 ———————-
# 将自定义工具注册到 MCP 服务器
my_tools_server = create_sdk_mcp_server(
name="my-custom-tools", # 服务器名称(需唯一)
version="1.0.0", # 版本号(可选)
tools=[greet_user] # 注册的工具列表
)
# ———————- 步骤3:使用客户端调用工具 ———————-
async def custom_tool_example():
"""
调用自定义工具的完整示例
"""
# 配置项:指定 MCP 服务器,并允许使用自定义工具
options = ClaudeCodeOptions(
# 注册 MCP 服务器:键为服务器别名,值为服务器实例
mcp_servers={"tools": my_tools_server},
# 允许使用的工具:格式为 "mcp__{服务器别名}__{工具名称}"
allowed_tools=["mcp__tools__greet"]
)
# 创建客户端并发送查询
async with ClaudeSDKClient(options=options) as client:
# 发送查询:要求 Claude 调用 greet 工具问候 Alice
await client.query("使用 greet 工具向 Alice 发送问候")
# 解析响应
async for msg in client.receive_response():
if isinstance(msg, AssistantMessage):
for block in msg.content:
if isinstance(block, TextBlock):
print("Claude 响应:", block.text)
# 运行示例
if __name__ == "__main__":
anyio.run(custom_tool_example)
2.2 外部 MCP 服务器迁移至进程内
若之前使用外部 MCP 服务器(独立进程),可按以下方式迁移至进程内(推荐):
# 【迁移前】:外部 MCP 服务器(独立进程)
old_options = ClaudeCodeOptions(
mcp_servers={
"calculator": {
"type": "stdio",
"command": "python",
"args": ["-m", "calculator_server"] # 外部进程命令
}
}
)
# 【迁移后】:进程内 MCP 服务器(推荐)
from my_custom_tools import add, subtract # 导入自定义工具函数
# 创建进程内 MCP 服务器
calculator_server = create_sdk_mcp_server(
name="calculator",
tools=[add, subtract] # 注册工具函数
)
new_options = ClaudeCodeOptions(
mcp_servers={"calculator": calculator_server} # 直接注册服务器实例
)
2.3 混合使用进程内/外部 MCP 服务器
支持同时使用进程内和外部 MCP 服务器,满足复杂场景需求:
# 假设已创建进程内服务器 sdk_server
mixed_options = ClaudeCodeOptions(
mcp_servers={
"internal-tools": sdk_server, # 进程内服务器
"external-tools": { # 外部服务器
"type": "stdio",
"command": "node",
"args": ["external-server.js"]
}
}
)
3. 钩子函数(Hooks)
钩子函数是 Claude Code 在执行特定环节(如工具调用前)触发的自定义逻辑,可用于权限控制、参数校验、结果修正等。
3.1 钩子函数完整示例(禁止执行特定 Bash 命令)
from claude_code_sdk import ClaudeCodeOptions, ClaudeSDKClient, HookMatcher, AssistantMessage, TextBlock
async def check_bash_command(input_data, tool_use_id, context):
"""
钩子函数:工具调用前校验 Bash 命令,禁止执行包含 foo.sh 的命令
:param input_data: 工具调用的输入数据(包含工具名称、参数等)
:param tool_use_id: 工具调用 ID(唯一标识)
:param context: 上下文信息(包含对话 ID、工作目录等)
:return: 钩子响应(控制工具调用权限)
"""
# 提取工具名称和参数
tool_name = input_data.get("tool_name")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")
# 仅校验 Bash 工具
if tool_name != "Bash":
return {}
# 禁止执行包含 foo.sh 的命令
forbidden_pattern = "foo.sh"
if forbidden_pattern in command:
return {
"hookSpecificOutput": {
"hookEventName": "PreToolUse", # 钩子触发时机
"permissionDecision": "deny", # 权限决策:拒绝执行
"permissionDecisionReason": f"禁止执行包含 {forbidden_pattern} 的 Bash 命令", # 拒绝原因
}
}
# 允许执行其他命令
return {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "allow", # 权限决策:允许执行
}
}
async def hooks_example():
"""
钩子函数使用示例:校验 Bash 命令
"""
# 配置项:注册钩子函数
options = ClaudeCodeOptions(
allowed_tools=["Bash"], # 允许使用 Bash 工具
hooks={
# 钩子触发时机:PreToolUse(工具调用前)
"PreToolUse": [
# 匹配器:仅对 Bash 工具触发该钩子
HookMatcher(matcher="Bash", hooks=[check_bash_command]),
],
}
)
# 创建客户端测试
async with ClaudeSDKClient(options=options) as client:
# 测试1:执行禁止的命令(包含 foo.sh)
print("=== 测试1:执行禁止的命令 ===")
await client.query("Run the bash command: ./foo.sh –help")
async for msg in client.receive_response():
if isinstance(msg, AssistantMessage):
for block in msg.content:
if isinstance(block, TextBlock):
print(block.text)
# 测试2:执行允许的命令(echo)
print("\\n=== 测试2:执行允许的命令 ===")
await client.query("Run the bash command: echo 'Hello from hooks!'")
async for msg in client.receive_response():
if isinstance(msg, AssistantMessage):
for block in msg.content:
if isinstance(block, TextBlock):
print(block.text)
# 运行示例
if __name__ == "__main__":
anyio.run(hooks_example)
钩子函数关键说明:
- 触发时机:PreToolUse(工具调用前)是最常用的钩子,还有 PostToolUse(工具调用后)等;
- HookMatcher:用于匹配特定工具(如仅对 Bash 工具触发);
- 返回值:通过 permissionDecision 控制工具执行权限(allow/deny),并可返回拒绝原因。
四、错误处理
SDK 分层异常体系,精准捕获故障、便于排错:
| ClaudeSDKError | 所有异常基类 | 兜底捕获 |
| CLINotFoundError | 找不到 Claude Code CLI | 重装:npm install -g @anthropic-ai/claude-code |
| CLIConnectionError | 连接子进程失败 | 端口/环境/权限检查 |
| ProcessError | 进程异常退出 | 查看 exit_code、日志 |
| CLIJSONDecodeError | 流式 JSON 解析失败 | 版本不匹配、网络截断 |
带完整异常捕获的代码示例
import anyio
from claude_code_sdk import (
query,
ClaudeSDKError,
CLINotFoundError,
CLIConnectionError,
ProcessError,
CLIJSONDecodeError,
AssistantMessage,
TextBlock
)
async def safe_query(prompt: str):
"""封装安全调用:全局异常捕获 + 响应解析"""
try:
async for msg in query(prompt=prompt):
if isinstance(msg, AssistantMessage):
for block in msg.content:
if isinstance(block, TextBlock):
print("Claude:", block.text)
except CLINotFoundError:
print("❌ 致命错误:未安装 Claude Code CLI")
print("修复:npm install -g @anthropic-ai/claude-code")
except CLIConnectionError:
print("❌ 连接失败:无法与 Claude Code 建立通信")
except ProcessError as e:
print(f"❌ 进程崩溃,退出码:{e.exit_code}")
except CLIJSONDecodeError:
print("❌ 数据解析错误:返回格式异常(版本不兼容)")
except ClaudeSDKError as e:
print(f"❌ SDK 通用异常:{str(e)}")
except Exception as e:
print(f"❌ 未知异常:{str(e)}")
if __name__ == "__main__":
anyio.run(safe_query, "简单介绍 Python 异步编程")
五、核心类型总览(Types)
所有结构体定义在 src/claude_code_sdk/types.py,开发时强类型约束、减少报错。
1. 配置类型:ClaudeCodeOptions
常用字段汇总
from claude_code_sdk import ClaudeCodeOptions
from pathlib import Path
opts = ClaudeCodeOptions(
system_prompt="你是资深 Python 工程师,回答精简", # 人设
max_turns=3, # 最大推理轮数
cwd=Path("./workspace"), # 工作目录
allowed_tools=["Read", "Write", "Bash"], # 允许工具
permission_mode="acceptEdits", # 自动同意文件修改
mcp_servers={}, # MCP 自定义服务
hooks={} # 钩子拦截逻辑
)
2. 消息结构类型
- AssistantMessage:模型输出消息
- UserMessage:用户输入消息
- SystemMessage:系统指令消息
- ResultMessage:工具执行结果
3. 内容块类型
- TextBlock:纯文本
- ToolUseBlock:模型调用工具
- ToolResultBlock:工具返回结果
六、可用内置工具清单
Claude Code 原生内置能力,通过 allowed_tools 开启
- Read:读取本地文件
- Write:写入/生成文件
- Bash:执行 Shell 命令
- Search:项目内检索代码
- Edit:增量修改文件
安全最佳实践:
- 生产环境不要全开工具
- 限制 Bash + 目录白名单 + 钩子拦截高危命令
七、完整实战案例合集
案例 1:一键生成 Python 项目脚手架(工具 + 工作目录)
import anyio
from pathlib import Path
from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, TextBlock
async def create_python_project():
options = ClaudeCodeOptions(
system_prompt="你是后端脚手架生成器,生成规范 Python 项目结构",
cwd=Path("./demo_project"),
allowed_tools=["Read", "Write"],
permission_mode="acceptEdits",
max_turns=2
)
prompt = """
生成标准 Python 项目:
1. 创建 src/、tests/、README.md、requirements.txt
2. 写入基础 hello 模块
"""
async for msg in query(prompt, options=options):
if isinstance(msg, AssistantMessage):
for b in msg.content:
if isinstance(b, TextBlock):
print(b.text)
if __name__ == "__main__":
anyio.run(create_python_project)
案例 2:进程内自定义计算器 MCP(替代外部服务)
import anyio
from claude_code_sdk import (
tool, create_sdk_mcp_server,
ClaudeCodeOptions, ClaudeSDKClient,
AssistantMessage, TextBlock
)
# 1. 定义工具
@tool("add", "加法计算", {"a": float, "b": float})
async def add_func(args):
res = args["a"] + args["b"]
return {"content": [{"type": "text", "text": f"结果:{res}"}]}
@tool("subtract", "减法计算", {"a": float, "b": float})
async def sub_func(args):
res = args["a"] – args["b"]
return {"content": [{"type": "text", "text": f"结果:{res}"}]}
# 2. 注册进程内 MCP
calc_server = create_sdk_mcp_server(
name="calc", version="1.0.0", tools=[add_func, sub_func]
)
# 3. 调用
async def run_calc():
opts = ClaudeCodeOptions(
mcp_servers={"calc": calc_server},
allowed_tools=["mcp__calc__add", "mcp__calc__subtract"]
)
async with ClaudeSDKClient(options=opts) as client:
await client.query("计算 99.5 + 0.8,再减去 10")
async for msg in client.receive_response():
if isinstance(msg, AssistantMessage):
for b in msg.content:
if isinstance(b, TextBlock):
print(b.text)
if __name__ == "__main__":
anyio.run(run_calc)
案例 3:安全风控钩子——拦截 rm / sudo
import anyio
from claude_code_sdk import (
ClaudeCodeOptions, ClaudeSDKClient, HookMatcher
)
async def safety_check(input_data, tool_use_id, ctx):
tool = input_data["tool_name"]
cmd = input_data["tool_input"].get("command", "")
if tool == "Bash":
if "rm -rf" in cmd or "sudo " in cmd:
return {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "禁止高危 rm / sudo 命令"
}
}
return {}
async def safe_bash_demo():
opts = ClaudeCodeOptions(
allowed_tools=["Bash"],
hooks={
"PreToolUse": [HookMatcher(matcher="Bash", hooks=[safety_check])]
}
)
async with ClaudeSDKClient(options=opts) as client:
print("尝试高危命令:")
await client.query("执行 rm -rf /tmp/test")
async for msg in client.receive_response():
print(msg)
if __name__ == "__main__":
anyio.run(safe_bash_demo)
八、废弃迁移指南(重点 ⚠️)
1. 现状
claude-code-sdk 已废弃、不再维护 迁移目标:claude-agent-sdk
2. 迁移对照表
| query() 流式入口 | Agent 原生会话入口 |
| ClaudeSDKClient | Agent Runtime |
| In-process MCP | 原生 Tool 装饰器更简洁 |
| Hooks | Lifecycle Callbacks 生命周期回调 |
3. 迁移收益
- 架构更轻、更少依赖
- 原生 Agent 推理链路
- 更好类型提示、更少 Node 耦合
- 官方长期迭代维护
九、安装 & 运行排错速查
python –version # >=3.10
node –version
claude-code –version




