欢迎光临
我们一直在努力

Claude Code SDK for Python(旧版本) 完全指南

在这里插入图片描述

一、环境准备

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. 迁移对照表

旧(废弃)新(claude-agent-sdk)
query() 流式入口 Agent 原生会话入口
ClaudeSDKClient Agent Runtime
In-process MCP 原生 Tool 装饰器更简洁
Hooks Lifecycle Callbacks 生命周期回调

3. 迁移收益

  • 架构更轻、更少依赖
  • 原生 Agent 推理链路
  • 更好类型提示、更少 Node 耦合
  • 官方长期迭代维护

九、安装 & 运行排错速查

  • 依赖检查
  • python –version # >=3.10
    node –version
    claude-code –version

  • 权限问题 Windows:开启开发者模式 Mac/Linux:npm 全局安装加权限或 npx 替代
  • 端口/进程冲突 关闭其他 Claude Code 进程,重启终端重试

  • 十、文档总结

  • 两层调用:轻量 query() / 高阶 ClaudeSDKClient
  • 三大核心能力:内置工具、进程内 MCP 自定义工具、Hook 安全拦截
  • 强类型 + 分层异常,企业级可用
  • 务必规划:从 claude-code-sdk 迁移到 claude-agent-sdk
  • 赞(0)
    未经允许不得转载:171主机测评 » Claude Code SDK for Python(旧版本) 完全指南
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址