本页目录6
- CLINotFoundError 表示 Python SDK 找不到 claude 可执行文件，需检查安装或 ClaudeAgentOptions(cli_path=...) 配置
- Windows 上若 cli_path 指向 .bat/.cmd（如 npm 的 claude.cmd），SDK 会因命令注入风险拒绝执行，应改用原生 claude.exe
- claude-agent-sdk 0.2.124 之前的 Python SDK 会通过 cmd.exe 执行批处理脚本，不含此项安全防护
- result 消息 subtype 为 success 不代表 structured_output 一定有效，需同时判断 subtype 和 structured_output 是否存在
- 未覆盖的报错应在对应 SDK 的 GitHub 仓库提交 issue，并附完整报错文本与 SDK 版本号
本文是对官方 Agent SDK 某页的中文整理，完整与最新内容以原文为准。原文链接：https://code.claude.com/docs/en/agent-sdk/troubleshooting
本页按实际出现的报错信息组织，每条错误给出原因与修复方法，覆盖 TypeScript 与 Python 两个 SDK。
CLI 启动（CLI startup）
CLINotFoundError: Claude Code not found
Python SDK 会把 Claude Code CLI 作为子进程启动。当它找不到 claude 可执行文件时，连接会失败并抛出 CLINotFoundError:
Claude Code not found at: /your/configured/path
- 如果设置了
ClaudeAgentOptions(cli_path=...)且该路径指向的文件不存在，报错信息中会包含这个配置路径。 - 如果没有设置
cli_path,SDK 会在PATH和常见安装位置中搜索，报错信息中会附带针对当前平台的安装说明。
修复方法：
- 如果尚未安装 Claude Code，先安装。安装命令参见「Install Claude Code」（/docs/en/setup#install-claude-code）。
- 如果设置了
cli_path，确认该文件存在且确实是claude可执行文件。 - 如果依赖
PATH解析，确认在与应用运行时相同的环境中执行claude --version能成功。从 IDE 或服务管理器等方式启动的进程，其PATH往往与你在终端中看到的不同。
CLIConnectionError: Refusing to execute batch script
在 Windows 上，如果 Python SDK 使用的 CLI 路径是一个 .bat 或 .cmd 批处理脚本（包括 npm 安装生成的 claude.cmd shim），连接会失败并抛出 CLIConnectionError:
Refusing to execute batch script 'C:\\Users\\you\\AppData\\Roaming\\npm\\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).
这个拒绝执行是有意的安全加固，不是安装损坏。Windows 运行批处理脚本时会把进程启动改写为 cmd.exe /c 调用，而 cmd.exe 在执行时会重新解析整条命令行，这意味着参数值有可能触发命令注入，且不存在可靠的转义方式。
大多数 Windows 安装不会遇到此报错。claude-agent-sdk 的 Windows x64 wheel 自带 claude.exe,SDK 会优先使用内置 CLI，其次是能发现的原生 claude.exe，最后才回退到批处理 shim。以下两种情况会触发该拒绝：
- 将
ClaudeAgentOptions(cli_path=...)设置为了.bat或.cmd文件，例如 npm 的claude.cmdshim。 - 安装环境中既没有内置也没有原生的
claude.exe，例如在 ARM64 Windows 上做源码安装、PATH中唯一可用的claude就是 npm shim。
修复方法（给 SDK 一个原生可执行文件，而不是批处理脚本）：
- 如果设置了
ClaudeAgentOptions(cli_path=...)，把它指向claude.exe，或者直接移除该选项。SDK 在设置了cli_path时会跳过自动发现流程，所以仅仅装好原生版本并不会自动生效。 - 在 PowerShell 中原生安装 Claude Code:
irm https://claude.ai/install.ps1 | iex - 在 x64 Windows 上安装
claude-agent-sdkwheel，它自带claude.exe。
在 claude-agent-sdk 0.2.124 版本之前，Python SDK 会在没有这项检查的情况下，直接通过 cmd.exe 执行批处理脚本。
涉及的相关配置项：
| 选项 | 说明 |
|---|---|
ClaudeAgentOptions(cli_path=...) | 指定 Python SDK 使用的 claude 可执行文件路径；设置后 SDK 会跳过自动发现逻辑，必须直接指向合法的原生可执行文件（不能是 .bat/.cmd） |
结构化输出（Structured outputs）
structured_output is None but the result says success
result 消息可能以 subtype: "success" 结束，但 Python 中 structured_output 为 None、TypeScript 中为 undefined。也就是说运行本身完成了，但没有产生任何通过校验的输出。
一种典型触发场景是：提供的 schema 本身没有任何输出能满足（例如长度约束互相冲突）。这种情况下运行不会报出校验错误，唯一的信号就是 structured_output 缺失。
处理建议：
- 在应用代码中把这种结果当作失败处理：使用前应同时检查
subtype是否为success，并且structured_output是否存在。具体写法参见「Error handling」（/docs/en/agent-sdk/structured-outputs#error-handling）一节中针对两种 SDK 给出的示例模式。 - 如果确信 schema 本身没问题却反复出现该情况，先验证 schema 是否可满足（satisfiable），然后逐步简化 schema 直到输出能通过校验，再逐条重新加回约束条件进行排查。
上报未覆盖的问题
如果遇到的报错本页未覆盖，可先查看现有 issue，或在对应 SDK 仓库中提交新 issue:
- TypeScript SDK:claude-agent-sdk-typescript
- Python SDK:claude-agent-sdk-python
提交时请附上完整的报错文本以及所使用的 SDK 版本号。