SDK 运行排障

先判断失败发生在 runtime 启动、认证、会话恢复、模型调用还是工具执行。只提高日志级别而不区分层次，容易把环境问题误认为模型没有响应。

开启日志

const client = new CopilotClient({ logLevel: "debug" });

官方列出的级别为 none、error、warning、info、debug、all。启动 CLI 子进程时可通过 cliArgs: ["--log-dir", "/path/to/logs"] 指定日志目录；外部 runtime 的启动参数需在服务端设置，进程内模式另有选项范围，不能把所有 CLI 参数照搬过去。

日志可能包含工具参数或内容，提交 issue 前去除凭据和不需要公开的数据。

CLI 找不到或进程无法启动

按所选运行方式检查 bundled runtime 或本地 CLI，而不是一律再安装一份。可用 copilot --version 查看独立 CLI，或在客户端指定已经存在的 cliPath。

macOS GUI 应用可能没有 shell 的 PATH，使用已确认的绝对可执行路径；Linux 可检查执行权限与 ldd /path/to/copilot 所列依赖；Windows 核对 .exe 路径、反斜杠字符串写法及 JSON 的 UTF-8 编码。

官方还列出 Gatekeeper quarantine 处理命令，但它不是路径配置问题的通用修复。先核实实际阻止原因和二进制来源，不为所有启动失败统一移除系统标记。

认证与连接

未认证时核对用户认证来源，BYOK 则按其独立规则检查。旧排障示例采用 copilot auth login，当前 CLI 认证文档的入口见CLI 认证；不要混用登录命令与 token 类型。

连接拒绝时先确认 runtime 已启动。官方独立 stdio 测试命令为：

copilot --server --stdio

这是启动协议服务，不是普通交互聊天；终端等待输入不代表失败。TCP 模式可使用随机可用端口 0，连接已有服务器时检查 cliUrl 或 RuntimeConnection 的实际目标。状态与版本用 getStatus，连通性可用 ping。

旧排障表只分 stdio/TCP，新增进程内模式还有原生库与宿主进程约束，不能从该旧表推断它不受支持。

恢复与工具故障

Session not found 时，用 listSessions 确认 ID 和存储位置；已 disconnect 的对象不要继续调用，应按持久化流程恢复。disconnect 释放资源与 deleteSession 删除存储不同。

自定义工具检查注册、JSON Schema、description、权限策略，以及 handler 是否返回可序列化结果。不要只因工具未被调用就判定 handler 坏了：任务可能不需要该工具，也可能在执行前被权限处理拒绝。

采用当前事件参考

旧排障示例订阅 tool.execution_error 和 error，但当前事件参考使用 tool.execution_complete 的失败结果及 session.error 等事件。本页按当前事件说明定位；不复制未经当前 Schema 确认的旧事件名。成功与失败 Hooks 也分别处理，见结果 Hook。

准备最小复现

记录 SDK 语言与版本、CLI/runtime 版本、协议版本、操作系统、出错步骤和已脱敏日志。缩减到一次启动、创建和发送，区分是所有请求都失败还是特定工具配置失败。MCP 服务问题继续按MCP 排障独立测试。