Claude Agent SDK 开发指南本文档基于 Anthropic 官方claude-agent-sdk-python完整能力整理覆盖从安装、基础调用、架构原理到高级扩展、安全与工程化最佳实践适合用于学习、开发与团队培训。目录概述安装与环境配置核心架构基础使用高级功能MCP 服务器与自定义工具Hooks 系统错误处理最佳实践常见问题与调试附录术语表1. 概述1.1 什么是 Claude Agent SDKClaude Agent SDK for Python 是 Anthropic 官方推出的 Python 软件开发工具包用于程序化与 Claude Code 进行交互实现自动化代码生成、文件操作、命令执行、交互式智能代理等能力。SDK 提供两种核心交互模式查询模式query()一次性、无状态、单向对话客户端模式ClaudeSDKClient长连接、有状态、交互式会话支持中断、流式消息、动态控制1.2 核心特性简洁直观 API原生支持async/await异步编程内置文件读写、编辑、Bash、网页获取等系统工具多级权限控制支持自定义工具使用策略内置进程内 MCP 服务器性能优于外部进程方案6 种事件钩子支持细粒度控制对话流程支持 JSON Schema 验证的结构化输出实时 API 调用成本追踪可选命令执行沙箱环境1.3 应用场景自动化脚本CI/CD 流水线、代码生成、批量处理开发工具IDE 插件、代码审查、智能重构交互式应用聊天机器人、REPL 环境、调试助手数据处理文件转换、数据提取、报告生成2. 安装与环境配置2.1 系统要求Python 版本≥ 3.10推荐 3.10~3.12操作系统macOS、Linux、WindowsWSL2 推荐2.2 安装方式标准安装推荐pipinstallclaude-agent-sdk开发环境安装gitclone https://github.com/anthropics/claude-agent-sdk-python.gitcdclaude-agent-sdk-python pipinstall-e.[dev]pytest2.3 Claude Code CLISDK 0.1.8 及以上版本已自动捆绑 CLI无需单独安装。如需手动指定 CLI 路径fromclaude_agent_sdkimportClaudeAgentOptions optionsClaudeAgentOptions(cli_path/path/to/claude)手动安装 CLI可选curl-fsSLhttps://claude.ai/install.sh|bash2.4 环境变量环境变量说明默认值ANTHROPIC_API_KEYAPI 密钥-CLAUDE_CODE_ENTRYPOINTSDK 入口标识sdk-py / sdk-py-clientCLAUDE_CODE_STREAM_CLOSE_TIMEOUT流关闭超时毫秒600003. 核心架构3.1 架构概览你的应用 ┌─────────────────────────────────────────┐ │ query() 函数 │ ClaudeSDKClient 类 │ ├─────────────────────────────────────────┤ │ InternalClient │ Query 引擎 │ ├─────────────────────────────────────────┤ │ Transport 层 │ │ (SubprocessCLITransport) │ └─────────────────────────────────────────┘3.2 核心组件Transport 层负责与 Claude Code CLI 底层通信默认通过子进程实现。Query 引擎处理异步消息流、工具权限回调、MCP 服务器协调、Hooks 执行。Message Parser将 CLI 原始输出解析为类型安全的 Python 对象支持文本、思考、工具调用等多种内容块。3.3 数据流应用调用query()或ClaudeSDKClient配置验证与初始化Transport 建立与 CLI 的连接Query 引擎启动控制协议双向消息流通信实时解析消息并返回应用层4. 基础使用4.1 最简示例importanyiofromclaude_agent_sdkimportqueryasyncdefmain():asyncformessageinquery(prompt2 2 等于多少):print(message)anyio.run(main)4.2 带系统提示与选项fromclaude_agent_sdkimportquery,ClaudeAgentOptionsasyncdefmain():optionsClaudeAgentOptions(system_prompt你是一个专业的 Python 编程助手,max_turns1)asyncformsginquery(写一个斐波那契函数,optionsoptions):print(msg)4.3 消息类型系统核心消息类型fromclaude_agent_sdkimport(UserMessage,AssistantMessage,SystemMessage,ResultMessage,StreamEvent)内容块类型fromclaude_agent_sdkimport(TextBlock,ThinkingBlock,ToolUseBlock,ToolResultBlock)4.4 完整消息解析示例fromclaude_agent_sdkimportquery,ClaudeAgentOptionsfromclaude_agent_sdk.typesimport(AssistantMessage,ResultMessage,TextBlock,ToolUseBlock)asyncdefparse_demo():optionsClaudeAgentOptions(allowed_tools[Read,Write],system_prompt你是一个文件助手)asyncformsginquery(创建 hello.txt 并写入 Hello World,optionsoptions):ifisinstance(msg,AssistantMessage):forblockinmsg.content:ifisinstance(block,TextBlock):print(文本:,block.text)elifisinstance(block,ToolUseBlock):print(工具:,block.name,block.input)elifisinstance(msg,ResultMessage):print(f本次成本: ${msg.total_cost_usd})4.5 内置工具与权限内置工具列表工具名功能权限等级Read读取文件低Write写入文件中Edit多行编辑中Bash执行 Shell 命令高WebFetch获取网页内容中StrReplace字符串替换低权限模式fromtypingimportLiteral PermissionMode:Literal[default,# 危险操作需确认acceptEdits,# 自动接受文件编辑plan,# 计划模式bypassPermissions# 绕过所有权限慎用]工具配置示例optionsClaudeAgentOptions(allowed_tools[Read,Write],permission_modeacceptEdits,cwd./my_project)5. 高级功能5.1 ClaudeSDKClient 交互式客户端适合多轮对话、动态输入、中断控制、长连接会话。上下文管理器写法推荐importasynciofromclaude_agent_sdkimportClaudeSDKClient,ClaudeAgentOptionsasyncdefclient_demo():optionsClaudeAgentOptions(system_prompt你是编码助手,allowed_tools[Read,Write,Bash])asyncwithClaudeSDKClient(optionsoptions)asclient:awaitclient.query(列出当前目录文件)asyncformsginclient.receive_response():print(msg)消息接收方式# 接收单次完整响应自动在 ResultMessage 停止asyncformsginclient.receive_response():pass# 持续监听所有消息asyncformsginclient.receive_messages():pass会话控制awaitclient.interrupt()# 中断当前执行awaitclient.set_permission_mode(acceptEdits)awaitclient.set_model(claude-sonnet-4-5)infoawaitclient.get_server_info()# 获取服务信息5.2 流式输入asyncdefstream_prompts():asyncdefgen():yield{type:user,message:{role:user,content:你好}}yield{type:user,message:{role:user,content:讲个笑话}}asyncformsginquery(promptgen()):print(msg)5.3 自定义工具权限回调fromclaude_agent_sdk.typesimport(PermissionResultAllow,PermissionResultDeny)asyncdefcustom_permission(tool_name,tool_input,context):iftool_nameWriteandsensitiveintool_input.get(file_path,):returnPermissionResultDeny(message禁止写入敏感文件)iftool_nameBashandrm -rfintool_input.get(command,):returnPermissionResultDeny(message危险命令已拦截,interruptTrue)returnPermissionResultAllow()optionsClaudeAgentOptions(can_use_toolcustom_permission)5.4 文件检查点与回滚optionsClaudeAgentOptions(enable_file_checkpointingTrue)asyncwithClaudeSDKClient(optionsoptions)asclient:awaitclient.query(创建 file1.txt)checkpoint_idNoneasyncformsginclient.receive_response():ifhasattr(msg,uuid):checkpoint_idmsg.uuidbreak# 修改后回滚awaitclient.rewind_files(checkpoint_id)5.5 结构化输出JSON Schemaschema{type:object,properties:{name:{type:string},age:{type:integer,minimum:0}},required:[name]}optionsClaudeAgentOptions(output_format{type:json_schema,schema:schema})结果在ResultMessage.structured_output中获取。5.6 沙箱配置fromclaude_agent_sdk.typesimportSandboxSettings sandbox:SandboxSettings{enabled:True,autoAllowBashIfSandboxed:True,excludedCommands:[docker,git],network:{allowLocalBinding:True}}optionsClaudeAgentOptions(sandboxsandbox)6. MCP 服务器与自定义工具6.1 MCP 简介MCPModel Context Protocol是 Claude 的插件工具协议允许模型调用外部能力。SDK 支持进程内 MCP性能高、无 IPC 开销外部 stdio / SSE / HTTP MCP6.2 使用 tool 定义自定义工具fromclaude_agent_sdkimporttool,create_sdk_mcp_servertool(add,两数相加,{a:float,b:float})asyncdefadd_numbers(args):resargs[a]args[b]return{content:[{type:text,text:f结果{res}}]}tool(divide,两数相除,{a:float,b:float})asyncdefdivide(args):ifargs[b]0:return{content:[{type:text,text:除零错误}],is_error:True}return{content:[{type:text,text:f{args[a]/args[b]}}]}6.3 创建并使用 MCP 服务器servercreate_sdk_mcp_server(namecalculator,version1.0.0,tools[add_numbers,divide])optionsClaudeAgentOptions(mcp_servers{calc:server},allowed_tools[mcp__calc__add,mcp__calc__divide])工具命名规则mcp__{服务器名}__{工具名}6.4 混合多种 MCP 服务器optionsClaudeAgentOptions(mcp_servers{internal:my_sdk_server,external:{type:stdio,command:python,args:[external_server.py]},sse:{type:sse,url:http://localhost:8080/sse}})7. Hooks 系统Hooks 允许在代理执行生命周期中插入自定义逻辑实现权限控制、审计、日志、拦截等能力。7.1 支持的 Hook 事件Hook 名称触发时机典型用途PreToolUse工具执行前权限拦截、参数修改、安全检查PostToolUse工具执行后结果校验、错误处理、添加上下文UserPromptSubmit用户提示提交时注入系统信息、预处理提示Stop会话停止时资源清理、日志记录SubagentStop子代理停止时子代理生命周期管理PreCompact会话压缩前控制历史压缩策略7.2 Hook 配置示例fromclaude_agent_sdkimportHookMatcherasyncdefbash_audit(input_data,tool_use_id,context):cmdinput_data[tool_input].get(command,)ifrm -rfincmd:return{hookSpecificOutput:{hookEventName:PreToolUse,permissionDecision:deny}}return{}optionsClaudeAgentOptions(allowed_tools[Bash],hooks{PreToolUse:[HookMatcher(matcherBash,hooks[bash_audit])]})7.3 常用 Hook 模式PreToolUse拦截危险命令、保护系统目录、路径遍历防护PostToolUse识别错误输出、自动补充提示信息UserPromptSubmit注入时间、会话 ID、环境信息Stop错误次数超限自动终止会话8. 错误处理8.1 错误类型体系ClaudeSDKError基类 ├── CLIConnectionError │ └── CLINotFoundError ├── ProcessError └── CLIJSONDecodeError8.2 典型异常捕获fromclaude_agent_sdkimport(CLINotFoundError,CLIConnectionError,ProcessError)asyncdefdemo():try:asyncformsginquery(你好):passexceptCLINotFoundError:print(错误未找到 Claude CLI)exceptCLIConnectionError:print(错误CLI 连接失败)exceptProcessErrorase:print(f进程异常{e.exit_code}:{e.stderr})8.3 重试机制指数退避asyncdefquery_with_retry(prompt,max_retries3,delay1):foriinrange(max_retries):try:asyncformsginquery(prompt):yieldmsgreturnexceptCLIConnectionError:ifimax_retries-1:awaitasyncio.sleep(delay)delay*28.4 超时控制asyncdefquery_with_timeout(prompt,timeout30):asyncdefcollect():msgs[]asyncformsginquery(prompt):msgs.append(msg)returnmsgs taskasyncio.create_task(collect())returnawaitasyncio.wait_for(task,timeout)8.5 日志与调试importlogging logging.basicConfig(levellogging.DEBUG)optionsClaudeAgentOptions(stderrlambdaline:logging.debug(fCLI:{line.strip()}))9. 最佳实践9.1 推荐项目结构my_claude_app/ ├── src/ │ ├── main.py │ ├── agents/ # 代理配置与系统提示 │ ├── tools/ # 自定义 MCP 工具 │ ├── hooks/ # 安全、审计、拦截钩子 │ └── utils/ # 配置、日志、工具函数 ├── tests/ ├── config/ └── requirements.txt9.2 性能优化复用ClaudeSDKClient避免频繁新建连接流式处理消息不全部存入内存使用信号量控制并发批量任务使用max_turns1减少不必要多轮交互9.3 安全最佳实践遵循最小权限原则仅开放必要工具严禁使用allowed_tools[*]生产环境必须启用沙箱使用 PreToolUse 拦截路径遍历、系统文件操作审计所有 Bash 命令禁止高危操作9.4 可观测性监听ResultMessage统计 Token 与成本记录工具调用日志与用户操作审计监控响应耗时、消息数、错误率10. 常见问题与调试10.1 安装与 CLI 问题提示找不到 Claude CLI手动指定cli_path权限不足检查工作目录与沙箱配置10.2 连接问题确保设置ANTHROPIC_API_KEY代理环境配置optionsClaudeAgentOptions(env{HTTP_PROXY:http://proxy:port})延长超时时间os.environ[CLAUDE_CODE_STREAM_CLOSE_TIMEOUT]12000010.3 工具不执行检查allowed_tools是否包含对应工具确认权限模式为acceptEdits或bypassPermissionsMCP 工具必须使用mcp__服务器名__工具名格式10.4 调试技巧# 打印完整消息流asyncdefdebug_flow():asyncformsginquery(Hello):print(type(msg).__name__,getattr(msg,content,))11. 附录术语表术语全称与说明MCPModel Context ProtocolClaude 插件工具协议SDKSoftware Development Kit软件开发工具包CLICommand Line Interface命令行界面Hook事件钩子在执行关键点插入回调Transport与 CLI 通信的底层传输层Streaming流式消息实时增量输出Structured Output基于 JSON Schema 的结构化返回Sandbox命令执行沙箱用于安全隔离
Claude Agent SDK 开发指南
发布时间：2026/5/28 14:35:57
Claude Agent SDK 开发指南本文档基于 Anthropic 官方claude-agent-sdk-python完整能力整理覆盖从安装、基础调用、架构原理到高级扩展、安全与工程化最佳实践适合用于学习、开发与团队培训。目录概述安装与环境配置核心架构基础使用高级功能MCP 服务器与自定义工具Hooks 系统错误处理最佳实践常见问题与调试附录术语表1. 概述1.1 什么是 Claude Agent SDKClaude Agent SDK for Python 是 Anthropic 官方推出的 Python 软件开发工具包用于程序化与 Claude Code 进行交互实现自动化代码生成、文件操作、命令执行、交互式智能代理等能力。SDK 提供两种核心交互模式查询模式query()一次性、无状态、单向对话客户端模式ClaudeSDKClient长连接、有状态、交互式会话支持中断、流式消息、动态控制1.2 核心特性简洁直观 API原生支持async/await异步编程内置文件读写、编辑、Bash、网页获取等系统工具多级权限控制支持自定义工具使用策略内置进程内 MCP 服务器性能优于外部进程方案6 种事件钩子支持细粒度控制对话流程支持 JSON Schema 验证的结构化输出实时 API 调用成本追踪可选命令执行沙箱环境1.3 应用场景自动化脚本CI/CD 流水线、代码生成、批量处理开发工具IDE 插件、代码审查、智能重构交互式应用聊天机器人、REPL 环境、调试助手数据处理文件转换、数据提取、报告生成2. 安装与环境配置2.1 系统要求Python 版本≥ 3.10推荐 3.10~3.12操作系统macOS、Linux、WindowsWSL2 推荐2.2 安装方式标准安装推荐pipinstallclaude-agent-sdk开发环境安装gitclone https://github.com/anthropics/claude-agent-sdk-python.gitcdclaude-agent-sdk-python pipinstall-e.[dev]pytest2.3 Claude Code CLISDK 0.1.8 及以上版本已自动捆绑 CLI无需单独安装。如需手动指定 CLI 路径fromclaude_agent_sdkimportClaudeAgentOptions optionsClaudeAgentOptions(cli_path/path/to/claude)手动安装 CLI可选curl-fsSLhttps://claude.ai/install.sh|bash2.4 环境变量环境变量说明默认值ANTHROPIC_API_KEYAPI 密钥-CLAUDE_CODE_ENTRYPOINTSDK 入口标识sdk-py / sdk-py-clientCLAUDE_CODE_STREAM_CLOSE_TIMEOUT流关闭超时毫秒600003. 核心架构3.1 架构概览你的应用 ┌─────────────────────────────────────────┐ │ query() 函数 │ ClaudeSDKClient 类 │ ├─────────────────────────────────────────┤ │ InternalClient │ Query 引擎 │ ├─────────────────────────────────────────┤ │ Transport 层 │ │ (SubprocessCLITransport) │ └─────────────────────────────────────────┘3.2 核心组件Transport 层负责与 Claude Code CLI 底层通信默认通过子进程实现。Query 引擎处理异步消息流、工具权限回调、MCP 服务器协调、Hooks 执行。Message Parser将 CLI 原始输出解析为类型安全的 Python 对象支持文本、思考、工具调用等多种内容块。3.3 数据流应用调用query()或ClaudeSDKClient配置验证与初始化Transport 建立与 CLI 的连接Query 引擎启动控制协议双向消息流通信实时解析消息并返回应用层4. 基础使用4.1 最简示例importanyiofromclaude_agent_sdkimportqueryasyncdefmain():asyncformessageinquery(prompt2 2 等于多少):print(message)anyio.run(main)4.2 带系统提示与选项fromclaude_agent_sdkimportquery,ClaudeAgentOptionsasyncdefmain():optionsClaudeAgentOptions(system_prompt你是一个专业的 Python 编程助手,max_turns1)asyncformsginquery(写一个斐波那契函数,optionsoptions):print(msg)4.3 消息类型系统核心消息类型fromclaude_agent_sdkimport(UserMessage,AssistantMessage,SystemMessage,ResultMessage,StreamEvent)内容块类型fromclaude_agent_sdkimport(TextBlock,ThinkingBlock,ToolUseBlock,ToolResultBlock)4.4 完整消息解析示例fromclaude_agent_sdkimportquery,ClaudeAgentOptionsfromclaude_agent_sdk.typesimport(AssistantMessage,ResultMessage,TextBlock,ToolUseBlock)asyncdefparse_demo():optionsClaudeAgentOptions(allowed_tools[Read,Write],system_prompt你是一个文件助手)asyncformsginquery(创建 hello.txt 并写入 Hello World,optionsoptions):ifisinstance(msg,AssistantMessage):forblockinmsg.content:ifisinstance(block,TextBlock):print(文本:,block.text)elifisinstance(block,ToolUseBlock):print(工具:,block.name,block.input)elifisinstance(msg,ResultMessage):print(f本次成本: ${msg.total_cost_usd})4.5 内置工具与权限内置工具列表工具名功能权限等级Read读取文件低Write写入文件中Edit多行编辑中Bash执行 Shell 命令高WebFetch获取网页内容中StrReplace字符串替换低权限模式fromtypingimportLiteral PermissionMode:Literal[default,# 危险操作需确认acceptEdits,# 自动接受文件编辑plan,# 计划模式bypassPermissions# 绕过所有权限慎用]工具配置示例optionsClaudeAgentOptions(allowed_tools[Read,Write],permission_modeacceptEdits,cwd./my_project)5. 高级功能5.1 ClaudeSDKClient 交互式客户端适合多轮对话、动态输入、中断控制、长连接会话。上下文管理器写法推荐importasynciofromclaude_agent_sdkimportClaudeSDKClient,ClaudeAgentOptionsasyncdefclient_demo():optionsClaudeAgentOptions(system_prompt你是编码助手,allowed_tools[Read,Write,Bash])asyncwithClaudeSDKClient(optionsoptions)asclient:awaitclient.query(列出当前目录文件)asyncformsginclient.receive_response():print(msg)消息接收方式# 接收单次完整响应自动在 ResultMessage 停止asyncformsginclient.receive_response():pass# 持续监听所有消息asyncformsginclient.receive_messages():pass会话控制awaitclient.interrupt()# 中断当前执行awaitclient.set_permission_mode(acceptEdits)awaitclient.set_model(claude-sonnet-4-5)infoawaitclient.get_server_info()# 获取服务信息5.2 流式输入asyncdefstream_prompts():asyncdefgen():yield{type:user,message:{role:user,content:你好}}yield{type:user,message:{role:user,content:讲个笑话}}asyncformsginquery(promptgen()):print(msg)5.3 自定义工具权限回调fromclaude_agent_sdk.typesimport(PermissionResultAllow,PermissionResultDeny)asyncdefcustom_permission(tool_name,tool_input,context):iftool_nameWriteandsensitiveintool_input.get(file_path,):returnPermissionResultDeny(message禁止写入敏感文件)iftool_nameBashandrm -rfintool_input.get(command,):returnPermissionResultDeny(message危险命令已拦截,interruptTrue)returnPermissionResultAllow()optionsClaudeAgentOptions(can_use_toolcustom_permission)5.4 文件检查点与回滚optionsClaudeAgentOptions(enable_file_checkpointingTrue)asyncwithClaudeSDKClient(optionsoptions)asclient:awaitclient.query(创建 file1.txt)checkpoint_idNoneasyncformsginclient.receive_response():ifhasattr(msg,uuid):checkpoint_idmsg.uuidbreak# 修改后回滚awaitclient.rewind_files(checkpoint_id)5.5 结构化输出JSON Schemaschema{type:object,properties:{name:{type:string},age:{type:integer,minimum:0}},required:[name]}optionsClaudeAgentOptions(output_format{type:json_schema,schema:schema})结果在ResultMessage.structured_output中获取。5.6 沙箱配置fromclaude_agent_sdk.typesimportSandboxSettings sandbox:SandboxSettings{enabled:True,autoAllowBashIfSandboxed:True,excludedCommands:[docker,git],network:{allowLocalBinding:True}}optionsClaudeAgentOptions(sandboxsandbox)6. MCP 服务器与自定义工具6.1 MCP 简介MCPModel Context Protocol是 Claude 的插件工具协议允许模型调用外部能力。SDK 支持进程内 MCP性能高、无 IPC 开销外部 stdio / SSE / HTTP MCP6.2 使用 tool 定义自定义工具fromclaude_agent_sdkimporttool,create_sdk_mcp_servertool(add,两数相加,{a:float,b:float})asyncdefadd_numbers(args):resargs[a]args[b]return{content:[{type:text,text:f结果{res}}]}tool(divide,两数相除,{a:float,b:float})asyncdefdivide(args):ifargs[b]0:return{content:[{type:text,text:除零错误}],is_error:True}return{content:[{type:text,text:f{args[a]/args[b]}}]}6.3 创建并使用 MCP 服务器servercreate_sdk_mcp_server(namecalculator,version1.0.0,tools[add_numbers,divide])optionsClaudeAgentOptions(mcp_servers{calc:server},allowed_tools[mcp__calc__add,mcp__calc__divide])工具命名规则mcp__{服务器名}__{工具名}6.4 混合多种 MCP 服务器optionsClaudeAgentOptions(mcp_servers{internal:my_sdk_server,external:{type:stdio,command:python,args:[external_server.py]},sse:{type:sse,url:http://localhost:8080/sse}})7. Hooks 系统Hooks 允许在代理执行生命周期中插入自定义逻辑实现权限控制、审计、日志、拦截等能力。7.1 支持的 Hook 事件Hook 名称触发时机典型用途PreToolUse工具执行前权限拦截、参数修改、安全检查PostToolUse工具执行后结果校验、错误处理、添加上下文UserPromptSubmit用户提示提交时注入系统信息、预处理提示Stop会话停止时资源清理、日志记录SubagentStop子代理停止时子代理生命周期管理PreCompact会话压缩前控制历史压缩策略7.2 Hook 配置示例fromclaude_agent_sdkimportHookMatcherasyncdefbash_audit(input_data,tool_use_id,context):cmdinput_data[tool_input].get(command,)ifrm -rfincmd:return{hookSpecificOutput:{hookEventName:PreToolUse,permissionDecision:deny}}return{}optionsClaudeAgentOptions(allowed_tools[Bash],hooks{PreToolUse:[HookMatcher(matcherBash,hooks[bash_audit])]})7.3 常用 Hook 模式PreToolUse拦截危险命令、保护系统目录、路径遍历防护PostToolUse识别错误输出、自动补充提示信息UserPromptSubmit注入时间、会话 ID、环境信息Stop错误次数超限自动终止会话8. 错误处理8.1 错误类型体系ClaudeSDKError基类 ├── CLIConnectionError │ └── CLINotFoundError ├── ProcessError └── CLIJSONDecodeError8.2 典型异常捕获fromclaude_agent_sdkimport(CLINotFoundError,CLIConnectionError,ProcessError)asyncdefdemo():try:asyncformsginquery(你好):passexceptCLINotFoundError:print(错误未找到 Claude CLI)exceptCLIConnectionError:print(错误CLI 连接失败)exceptProcessErrorase:print(f进程异常{e.exit_code}:{e.stderr})8.3 重试机制指数退避asyncdefquery_with_retry(prompt,max_retries3,delay1):foriinrange(max_retries):try:asyncformsginquery(prompt):yieldmsgreturnexceptCLIConnectionError:ifimax_retries-1:awaitasyncio.sleep(delay)delay*28.4 超时控制asyncdefquery_with_timeout(prompt,timeout30):asyncdefcollect():msgs[]asyncformsginquery(prompt):msgs.append(msg)returnmsgs taskasyncio.create_task(collect())returnawaitasyncio.wait_for(task,timeout)8.5 日志与调试importlogging logging.basicConfig(levellogging.DEBUG)optionsClaudeAgentOptions(stderrlambdaline:logging.debug(fCLI:{line.strip()}))9. 最佳实践9.1 推荐项目结构my_claude_app/ ├── src/ │ ├── main.py │ ├── agents/ # 代理配置与系统提示 │ ├── tools/ # 自定义 MCP 工具 │ ├── hooks/ # 安全、审计、拦截钩子 │ └── utils/ # 配置、日志、工具函数 ├── tests/ ├── config/ └── requirements.txt9.2 性能优化复用ClaudeSDKClient避免频繁新建连接流式处理消息不全部存入内存使用信号量控制并发批量任务使用max_turns1减少不必要多轮交互9.3 安全最佳实践遵循最小权限原则仅开放必要工具严禁使用allowed_tools[*]生产环境必须启用沙箱使用 PreToolUse 拦截路径遍历、系统文件操作审计所有 Bash 命令禁止高危操作9.4 可观测性监听ResultMessage统计 Token 与成本记录工具调用日志与用户操作审计监控响应耗时、消息数、错误率10. 常见问题与调试10.1 安装与 CLI 问题提示找不到 Claude CLI手动指定cli_path权限不足检查工作目录与沙箱配置10.2 连接问题确保设置ANTHROPIC_API_KEY代理环境配置optionsClaudeAgentOptions(env{HTTP_PROXY:http://proxy:port})延长超时时间os.environ[CLAUDE_CODE_STREAM_CLOSE_TIMEOUT]12000010.3 工具不执行检查allowed_tools是否包含对应工具确认权限模式为acceptEdits或bypassPermissionsMCP 工具必须使用mcp__服务器名__工具名格式10.4 调试技巧# 打印完整消息流asyncdefdebug_flow():asyncformsginquery(Hello):print(type(msg).__name__,getattr(msg,content,))11. 附录术语表术语全称与说明MCPModel Context ProtocolClaude 插件工具协议SDKSoftware Development Kit软件开发工具包CLICommand Line Interface命令行界面Hook事件钩子在执行关键点插入回调Transport与 CLI 通信的底层传输层Streaming流式消息实时增量输出Structured Output基于 JSON Schema 的结构化返回Sandbox命令执行沙箱用于安全隔离
