Skip to main content
参考

问题排查

按观察到的现象或报错原文定位原因与解决办法。

本页按观察到的现象索引。如果已经拿到错误码、异常类名或进程退出码，请直接查阅错误与错误码，该页按错误身份索引。

会话始终无法启动

现象： query() 没有产出任何消息，或首个 await 长时间挂起后抛出异常。
原因如何确认解决办法
qodercli 可执行文件不在 PATH 中异常为 QoderCliProcessError，且提示信息中包含可执行文件设置 pathToQoderCLIExecutable，或导出 QODERCLI_PATH
启动超出加载超时每次都在固定时长后失败提高 loadTimeoutMs；磁盘较慢时的冷启动可能超过默认值
未配置凭证异常带有 code: 'auth_not_configured'传入 auth，参见认证
凭证环境变量未设置code: 'auth_access_token_env_var_not_configured' 或 ..._service_account_...导出认证辅助函数读取的那个变量
排查启动问题时建议捕获 stderr，其中通常直接指明了真实原因： 
options: {
  stderr: (data) => process.stderr.write(data),
}

选项在进程启动前即被拒绝

部分选项会在前置阶段校验，因此拼写错误会立即失败，而非让某项功能被静默关闭。以下异常在 Qoder CLI 启动之前同步抛出。
报错信息原因解决办法
securityScan contains unknown option: <key>
security_scan contains unknown option: <key>.		开关名拼写错误TypeScript 使用 l1StaticCheck / l2LightweightScan / l3DeepScan；Python 使用 l1_static_check / l2_lightweight_scan / l3_deep_scan
securityScan.<key> must be a boolean
security_scan.<key> must be a bool.		传入了 'yes' 之类的字符串传入 true 或 false
security_scan must be a dict.Python 侧传入了非映射类型传入开关组成的 dict
native mode requires at least one enabled scope; use memory: {} to disable SDK memoryprojectScope 与 userScope 同时设为 false（仅 TypeScript）保留一个作用域，或用 memory: {} 关闭记忆
[createSdkMcpServer] Server name must be a non-empty string.name 缺失或为空为服务指定名称
[createSdkMcpServer] Tool name must be a non-empty string in server "<server>".定义工具时未提供名称为每个工具命名
[createSdkMcpServer] Tool "<tool>" must have a non-empty description string.缺少 description补充描述；模型依赖它判断何时调用该工具

SDK 与运行时版本不匹配

现象： ProtocolVersionMismatchError 或 UnsupportedCliCapabilityError。 这表示 SDK 与 Qoder CLI 来自不兼容的版本，通常出现在运行时由使用方单独管理、而非使用包内自带运行时的情况下。 
try {
  for await (const message of query({ prompt: 'ping' })) { /* ... */ }
} catch (error) {
  if (error instanceof UnsupportedCliCapabilityError) {
    console.error(`runtime lacks capability: ${error.capability}`);
  }
}
UnsupportedCliCapabilityError.capability 会指明缺失的具体能力，据此可判断应升级运行时还是停用该选项。解决办法是升级 Qoder CLI，或移除 pathToQoderCLIExecutable 覆盖，改用包内自带的运行时。

Agent 始终不调用自定义工具

现象： 工具已注册、会话正常启动，但 Agent 绕过该工具完成了任务。 按以下顺序排查：
  1. 确认完整工具名。 服务名为 my_tools、工具名为 greet 时，模型看到的是 mcp__my_tools__greet。白名单必须使用完整名称。
  2. 确认未被白名单排除。 若设置了 tools 或 allowedTools 但未包含该工具，模型不会看到它。参见工具命名与白名单。
  3. 确认懒加载影响。 启用 MCP 懒加载后，工具不会全部常驻。对必须始终可用的工具做标记：
tool('greet', 'Say hello', { name: z.string() }, handler, { alwaysLoad: true })
  1. 检查工具描述。 描述是模型判断该工具适用场景的唯一依据。「做某件事」这类描述会被忽略，应明确写出触发条件。

Agent 在本应有权限的操作上停住

现象： 工具调用被拒绝，或运行停滞在一个永不到来的审批上。
原因解决办法
disallowedTools 覆盖了该工具disallowedTools 的优先级高于 allowedTools 和 permissionMode
非交互任务中缺少审批处理设置不需要交互提示的 permissionMode，或提供 canUseTool
同时设置了 canUseTool 与 permissionPromptToolName两者互斥，只能择一
完整的优先级顺序参见权限控制。

模型选择回调超时

现象： ModelPolicyTimeoutError。 resolveModel 位于每次请求的关键路径上，默认预算为 500 毫秒。若回调中查询数据库或调用 HTTP 服务，将超出该预算。 
options: {
  resolveModel: async (context) => ({ model: pickModel(context) }), // 保持本地计算
  resolveModelTimeoutMs: 1_500,                                     // 或提高预算
}
建议在回调之外缓存决策结果，而非反复提高超时时间。这里的每一毫秒都会叠加到每一轮请求上。

记忆未被写入

仅适用于 TypeScript —— Python SDK 未提供 memory 选项。 现象： Agent 已获得新知识，运行结束后却没有任何内容被保存。 生成在轮次结束之后由后台 Agent 执行。若进程在收到最终 result 消息后立即退出，可能中断正在进行的写入。 
// 退出前等待未完成的生成
await q.flushMemory();
若 flushMemory() 已返回而文件仍无变化，请检查生成结果：no_change 和 skipped 属于正常结果，并非失败。参见查看记忆的执行结果。

在设置中开启的功能未生效

现象： 设置文件中已开启某项功能，但会话表现为未开启。 部分查询选项具有最终决定权：一旦传入，它会替换而非合并对应的设置块，未显式列出的开关全部按 false 处理。 securityScan 即属于此类。若 settings.json 开启了 l1StaticCheck，而查询传入 securityScan: { l3DeepScan: true }，则本次会话的 l1StaticCheck 为关闭状态。需要保留的开关必须逐个重新声明。参见该选项覆盖设置，而非合并。

Agent 遵守了未曾设置的规则

现象： Agent 遵循了提示词中并不存在的约定。 运行 Qoder CLI 的机器上的指令文件默认会被加载，且这些文件可以引入其他文件。可通过日志确认实际加载了什么： 
options: {
  hooks: {
    InstructionsLoaded: [{ hooks: [async (input) => {
      console.log(input.memory_type, input.file_path, input.load_reason);
      return {};
    }] }],
  },
}
若需在不同主机上获得可复现的运行结果，使用 settingSources: [] 不从磁盘加载任何文件。参见从文件系统加载指令。

收集可用于上报的诊断信息

需要升级排查时，请在现场信息丢失前收集以下内容： 
options: {
  debug: true,
  debugFile: '/tmp/qoder-sdk-debug.ndjson',
  stderr: (data) => process.stderr.write(data),
}
同时记录 SDK 版本、system/init 消息中的 Qoder CLI 版本、session_id，以及 Result 的 subtype 和可能存在的 error_code。除诊断流程明确需要，凭证、提示词和源码内容应做脱敏处理，参见日志与问题反馈。

下一步

快速开始
核心概念
对话与会话
工具与扩展
控制与安全
参考