Claude Agent SDK 的报错怎么查：官方 troubleshooting 页的分支
把 Claude Agent SDK 接进自己的服务里，最先撞上的往往不是模型效果问题，而是进程起不来、或者跑完了拿不到东西。这时候翻文档的姿势很重要：Claude Code 官方文档的 code.claude.com/docs/en/agent-sdk/troubleshooting 这一页，编排方式和多数「常见问题」不一样——它开篇就写明，本页的条目是按你看到的那条报错来编排的，每条给出成因和该做什么。也就是说，你手上有报错原文时它最好用；你只有「感觉不太对」时它帮不上忙。
还有一件事得先讲清楚，免得白翻：这一页目前的覆盖面很窄。 全页分两个大类，一共三条条目——CLI startup 下面两条，Structured outputs 下面一条。剩下的情况，官方文档把你引向 SDK 仓库的 issue 列表。所以如果你的报错不在这三条里，别在这页上耗时间。
下面逐条拆。每条按五步走：现象、怎么确认是这个问题、文档语义给出的处置、处置后怎么验证、什么情况说明不是这个原因。
一、CLINotFoundError：Python SDK 找不到 claude
现象。 文档写明，Python SDK 是把 Claude Code CLI 作为子进程拉起来的。当它找不到 claude 可执行文件时，连接会以 CLINotFoundError 失败，消息形如：
Claude Code not found at: /your/configured/path
怎么确认是这个问题。 有个很实用的分岔判据，来自文档对这条消息本身的描述：如果你设置了 ClaudeAgentOptions(cli_path=...) 而它指向一个不存在的文件，消息里会带上你配置的那个路径；如果你没设 cli_path，SDK 会去搜 PATH 和常见安装位置，此时消息里带的是针对你所在平台的安装说明。所以先看报错里出现的是「你自己写的路径」还是「安装说明」，就能判断问题出在配置项还是出在环境发现。
第二个可执行的判定动作，文档写得很直白：在你的应用实际运行的那个环境里执行
claude --version
注意「同一环境」这四个字是文档强调的重点。它明确提到，你从 shell 之外拉起来的进程——比如从 IDE 里启动的，或者由服务管理器托管的——常常带着一份不同的 PATH。所以在自己的终端里敲一遍成功，不代表被 systemd、Windows 服务或者 IDE 拉起来的那个进程也能找到。判定动作应该是在与应用同源的上下文里跑这条命令，而不是在你顺手的那个终端里。
文档给出的处置。 三条，按上面的分岔选：如果压根没装，就装 Claude Code（安装命令按平台不同，官方文档把这部分放在 code.claude.com/docs/en/setup 的 install 一节）；如果设了 cli_path，确认那个文件确实存在、并且确实是 claude 可执行文件；如果依赖 PATH 解析，就把 claude --version 在应用运行环境里跑通。
处置后怎么验证。 验证点和判定点是同一个：在应用运行的那个环境里 claude --version 有正常输出，再重跑一次连接。如果你走的是 cli_path 这条路，验证的是路径指向的文件存在且是可执行文件本体。
什么情况说明不是这个原因。 如果报错类型不是 CLINotFoundError，就别往这条上套。尤其是 Windows 上另一条长得也像「起不来」的报错，类型是 CLIConnectionError，成因完全不同，见下一节——两者都发生在连接阶段，但一个是「找不到」，一个是「找到了但拒绝执行」。另外，这条条目在文档里明确是讲 Python SDK 的子进程启动方式；TypeScript 侧文档在这一页没有给出对应条目，我们也不替它推断。
二、CLIConnectionError：Windows 上拒绝执行批处理脚本
这条对本站读者最要紧，因为它是 Windows 专属的。
现象。 文档写明，在 Windows 上，当 Python SDK 用到的 CLI 路径是 .bat 或 .cmd 批处理脚本时（包括 npm 安装生成的 claude.cmd shim），连接会以 CLIConnectionError 失败。报错正文里会直接给出三条替代路线，并把拒绝的理由写在消息里：Windows 通过 cmd.exe 运行 .bat/.cmd，而 cmd.exe 可能执行经由 CLI 参数注入的命令，且不存在可靠的转义方式。
怎么确认是这个问题。 判定动作是看SDK 实际用到的那个路径的后缀名：如果它以 .bat 或 .cmd 结尾，就是这一条。文档进一步把触发场景收敛成两种情况：
- 你把
ClaudeAgentOptions(cli_path=...)设成了.bat或.cmd文件，比如 npm 的claude.cmdshim； - 你的安装里没有 bundled 或原生的
claude.exe——文档举的例子是 ARM64 Windows 上的源码安装，PATH上唯一的claude就是 npm 的那个 shim。
文档还写明了多数 Windows 安装碰不到这条报错的原因：claude-agent-sdk 的 Windows x64 wheel 里打包了 claude.exe，SDK 会优先用 bundled 的那个 CLI，其次是它能发现的原生 claude.exe，最后才回落到批处理 shim。所以你如果撞上了，多半是你的场景落在了上面两种之一。
文档给出的处置。 一句话概括：给 SDK 一个原生可执行文件，而不是批处理脚本。具体三条——
- 如果你设了
ClaudeAgentOptions(cli_path=...)，把它指向一个claude.exe，或者干脆把这个选项去掉。这里有个容易踩的坑，文档专门点出来了：只要cli_path有值，SDK 就跳过自动发现；也就是说，你在旁边装了个原生版本，只要cli_path还指着 shim，那个原生安装单独是不会生效的。 - 在 PowerShell 里原生安装 Claude Code：
irm https://claude.ai/install.ps1 | iex
- 在 x64 Windows 上，安装
claude-agent-sdk的 wheel，它捆绑了claude.exe。
（以上命令与选项均照抄官方文档原文；该产品迭代频繁，以官方文档最新内容为准。）
这条拒绝是有意为之，不是安装坏了。 这是文档自述的定性，原文把它称作刻意的安全加固，理由如前所述：Windows 运行批处理脚本时会把 spawn 改写成 cmd.exe /c 调用，而 cmd.exe 在执行时会重新解析整条命令行，于是一个参数值就可能执行被注入的命令。这层机制我们只转述文档写明的部分，不推断 SDK 内部是怎么判断路径类型的。
处置后怎么验证。 验证的是「SDK 拿到的是不是原生可执行文件」：要么 cli_path 指向 claude.exe，要么把 cli_path 拿掉、让发现逻辑去找 bundled 或原生的 claude.exe，然后重跑连接。
什么情况说明不是这个原因。 三种：其一，你不在 Windows 上——Linux/macOS 没有 cmd.exe 这一层，这条条目从头到尾是 Windows 语境，那边连不上要回到第一节的 CLINotFoundError 去查；其二，报错类型是 CLINotFoundError 而不是 CLIConnectionError，那是「找不到」不是「拒绝执行」；其三，版本太旧。文档写明，在 claude-agent-sdk 0.2.124 之前，Python SDK 是直接通过 cmd.exe 拉起批处理脚本的，没有这道检查——也就是说更早的版本上你根本看不到这条报错，那时候的连接失败得另找原因。这个版本号是既成事实，可以拿来对照你手上的版本。
三、structured_output 是空的，但结果说 success
前两条是起不来，这条相反：跑完了，还标着成功。
现象。 文档写明，一条 result message 可以以 subtype: "success" 结束，同时 structured_output 在 Python 里是 None、在 TypeScript 里是 undefined。运行确实完成了，但不存在经过校验的输出。文档给的一种成因是schema 本身没有任何输出能满足，例如互相冲突的长度约束；这种情况下运行不会抛校验错误，唯一的信号就是那个缺失的 structured_output。
怎么确认是这个问题。 判定动作就是把两个字段一起看：subtype 是否为 success，以及 structured_output 是否存在。只要出现「success 且为空」的组合，就落在这一条里。文档给的处理原则很明确——在应用代码里把这种结果当失败处理，两个条件都满足了才使用输出。官方文档的 code.claude.com/docs/en/agent-sdk/structured-outputs 页的 Error handling 一节给出了两种 SDK 各自的写法，需要照抄模式的话去那里取，本文不复述那段代码。
处置。 如果这件事在你认为正确的 schema 上反复出现，文档给的动作是：先确认 schema 是可满足的，然后把它简化到输出能通过校验为止，再把约束一条一条加回去。「一条一条加回去」是文档原文的措辞，它的作用就是让你能定位到具体是哪一条约束把输出卡死：加回某一条之后 structured_output 重新变空，问题就在那一条上。文档没有进一步说明该怎么判断一个 schema 是否可满足，这部分要靠你自己对着 schema 的约束逐条看。
处置后怎么验证。 验证不在于「这次跑通了」，而在于你的判断逻辑改没改：调用方是否已经同时检查 subtype 与 structured_output 的存在性。只判断 success 的代码在这条上是会被骗过去的。
什么情况说明不是这个原因。 如果 subtype 不是 success，那就是另一类失败，走各自的错误路径，不属于这一条；如果 structured_output 有值但内容不合你的预期，那也不是这一条——这一条讲的是空，不是不对。文档在这页没有讨论内容质量问题，我们不替它补。
三条之外：官方给的下一步
这页最后写明，如果你的报错不在上面的条目里，去 SDK 仓库看已有 issue 或者提一个新的，仓库分别是 claude-agent-sdk-typescript 和 claude-agent-sdk-python（都在 GitHub 的 anthropics 组织下）。提的时候文档要求带两样东西：完整的报错原文和你的 SDK 版本。
这个要求值得当成习惯：这页本身就是按报错原文组织的，你把原文截断成「大概是找不到 CLI」，就等于把最有分辨力的那部分信息扔了——第一节里「消息带路径」还是「消息带安装说明」的分岔，正是从原文里读出来的。
最后提一句范围：这三条条目是我们在这一页文档里能核到的全部，不代表 SDK 只会出这三类问题。文档没有覆盖的错误，本文也不猜。涉及在本机拉起外部进程与传参的部分，请按你自己的环境评估。
本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。
该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现；
我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。
该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。
本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。
安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。