Code Mode 故障排除

错误代码¶

type CodeModeErrorCode =
  | "invalid_input"
  | "runtime_unavailable"
  | "aborted"
  | "timeout"
  | "output_limit_exceeded"
  | "snapshot_limit_exceeded"
  | "internal_error";

invalid_input 涵盖无效的 exec/wait 参数，包括已弃用的 language 和 typecheck 字段、被拒绝的模块访问、JavaScript 语法错误、未知/过期/ 作用域错误的 runId 值，以及过多挂起的运行。runtime_unavailable 涵盖执行器不可用，或工作进程启动失败或意外退出。检查所选的 tools.codeMode.executor 及其插件可用性；quickjs 执行器需要捆绑的 code-mode-quickjs 运行时。显式选择会激活该捆绑包，即使存在通用插件禁用 或允许列表设置；但显式拒绝或禁用条目仍会阻止它。 OpenClaw 不会自动切换执行器。 aborted 表示调用方取消了活动的 exec 或 wait；OpenClaw 会终止工作进程或丢弃挂起的运行，因此该 runId 无法恢复。它与 timeout 不同，后者表示执行截止时间已超时。 output_limit_exceeded 保留给无法序列化到有界投影中的结果；普通超大的成功结果会被截断，并仍保持成功。

JavaScript 语法错误会在源准备期间被拒绝，早于任何嵌套工具分发。有界诊断信息包含从 1 开始的源行号和列号。格式错误的 JavaScript 会在模块访问检查之前报告其语法错误。请修正源代码并提交新的 exec；OpenClaw 不会自动修复或重放它。这种未分发结果不会启用 restartSafe，也不会更改结果的 replaySafe 标志。由有效来宾代码抛出的异常（包括 SyntaxError）仍属于运行时失败。

当前解析器存在一个已知限制：在可选的关键字命名属性之后立即进行除法，例如 value?.return / 2 / 3。这是有效的 JavaScript，但源准备会在工具分发之前拒绝它。请为属性访问添加括号：(value?.return) / 2 / 3。

返回给来宾的错误是纯数据；宿主 Error 实例、堆栈对象和原型不会通过 JSON 结果桥传递。此桥接契约不会使 Node 执行器成为安全边界；参见 Code Mode 执行器。

failurePhase 标识终止错误的来源。未捕获的被拒绝工具调用会报告 "bridge"；成功调用之后出现的新 JavaScript 错误，或已捕获的工具拒绝，会报告 "guest"。重新抛出原始工具错误会保留 "bridge"，包括在 wait 之后。

失败来源与重放安全性是分开的。当 bridgeDispatchStarted 为 true 且 replaySafe 为 false 时，在重复发送或执行其他会改变状态的操作之前，请检查目标——即使是来宾错误也是如此。exec 失败本身并不能证明消息未被投递。

遥测¶

每个结果的 telemetry 字段报告：隐藏目录大小以及来源细分（openclaw/mcp/client 计数）、该运行目录的累计 search/describe/call 计数，以及代码模式控制工具名称（exec 和 wait）。 counterScope 标识一个计数器生命周期，在目录被替换或恢复时改变，但在追加工具或提示策略缩小该目录时保持稳定。

目录拆除仅保留这些最终聚合诊断信息，而不保留可执行工具或 VM 状态。如果拆除在 wait 正在观察待处理工作时关闭了一个挂起的运行，则该 wait 会返回 failed，并带有 code: "aborted" 和最终遥测；待处理调用会被取消，延续会被释放。保留的诊断信息不授予恢复或修复已关闭运行的权限。

运行元数据（openclaw agent --json 中的 meta.agentMeta，并镜像在 agent exec --json 信封上）会添加每次运行的统计信息：

• codeModeEngaged：仅当代码模式实际拥有模型工具表面时为 true。这是可靠的启用信号——不要根据配置或工具名称推断启用状态：shell 工具也称为 exec，并且 "auto" 级别会根据模型能力启用。桥接 OpenClaw 工具表面的框架（Copilot）会报告其已解析的门控，因此当 tools.codeMode.enabled=true 时 codeModeEngaged: false 可让静默无操作可被观察到。运行自身原生工具表面的框架（Codex）从不启用 OpenClaw 代码模式，因此它们始终读取 false；未报告任何内容的尝试出于同样原因会被规范化为 false。Codex 自身的 codeModeOnly 是一个独立的原生功能，此字段不跟踪它。
• assistantTurns：整个运行中完成的助手/提供方往返次数。
• bridgeCalls：该运行的累计内部桥接计数（{ search, describe, call }）。这些调用永远不会到达提供方；提供方可见的外部工具调用仍保留在 meta.toolSummary.calls 中。
• costUsd：根据运行累计用量和模型成本配置估算的美元成本（包括缓存读/写层级）；当模型没有成本数据时省略。

遥测不得包含机密、原始环境值，或超出现有 OpenClaw 轨迹策略的未脱敏工具输入。

调试¶

标记为 openclaw-code-mode:user.js 的 JavaScript 失败帧使用所提交 JavaScript 的行号，排除内部包装器和无头设置，包括在 wait 之后。内部包装器和控制器帧会从新单元格的失败中省略；错误消息仍共享现有输出预算。Code Mode 不接受 TypeScript 源，也不生成编译器诊断。

当代码模式的行为与普通工具运行不同时，请使用有针对性的模型传输日志：

OPENCLAW_DEBUG_CODE_MODE=1 \
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 \
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools \
OPENCLAW_DEBUG_SSE=events \
openclaw gateway

对于负载形状调试，请使用 OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted。 这会记录模型请求的有上限、已脱敏的 JSON 快照；仅在调试时使用它，因为提示和消息文本仍可能出现。

用于流调试时，使用 OPENCLAW_DEBUG_SSE=peek 记录前五个已脱敏的 SSE 事件。代码模式同样采用失败关闭策略：在代码模式界面激活后，如果最终提供商负载中未恰好包含一个 exec、一个 wait，且仅包含已批准的仅限直接使用的工具，则也会失败关闭。