跳转至

Code Mode 内部实现

运行时状态

方面 值
执行器 Node(node:vm,默认),QuickJS-WASI(内置插件)
默认状态 已禁用
稳定性 实验性 OpenClaw 表面(Codex Code Mode 是独立的、稳定的 Codex 框架表面)
目标表面 通用 OpenClaw 智能体运行
安全态势 Node 为受信任的主机执行环境;QuickJS 提供强化的来宾隔离
面向用户的承诺 启用代码模式时绝不会静默回退到广泛的直接工具暴露

范围

代码模式负责为准备就绪的运行提供面向模型的编排形态。它不负责模型选择、渠道行为、认证、工具策略或工具实现。

范围内:模型可见的控制/直接工具定义、隐藏工具目录构建、执行器选择、用于 search/describe/call 和会话 JSON 存储的主机回调、暂停来宾程序的可恢复状态、输出/超时/内存/挂起调用/快照限制,以及嵌套工具调用的遥测/轨迹投影。

范围外:提供商原生远程代码执行、Shell 执行语义、更改现有工具授权、用户编写的持久化脚本、来宾代码中的包管理器/文件/网络/模块访问,以及直接复用 Codex Code Mode 内部实现。

提供商拥有的工具(如远程 Python 沙箱)是独立的工具。参见代码执行。

术语

  • 代码模式(Code mode):OpenClaw 运行时模式,隐藏与目录兼容的模型工具,并暴露 exec、wait 以及必需的仅限直接调用的工具。
  • 执行器(Executor):负责 JavaScript 求值及其延续的实现。Node 为内置;QuickJS 是内置插件。核心负责目录、工具授权和运行生命周期。
  • 来宾运行时(Guest runtime):评估模型代码的 Node VM 上下文或 QuickJS-WASI VM。
  • 主机桥接(Host bridge):从来宾代码返回 OpenClaw 的窄 JSON 兼容回调表面。
  • 目录(Catalog):在正常工具策略、插件、MCP 和客户端工具解析之后,运行范围内有效工具的列表。
  • 嵌套工具调用(Nested tool call):来宾代码通过主机桥接发出的工具调用。
  • 快照(Snapshot):序列化的 QuickJS-WASI VM 状态,保存后 wait 可以继续已暂停的代码模式运行。
  • 延续(Continuation):执行器为暂停单元持有的状态。Node 保留活动的 worker 上下文;QuickJS 保留快照。

嵌套工具执行

每次嵌套工具调用都会跨过主机桥接并重新进入 OpenClaw,同时保留:活动智能体 ID、会话 ID 和密钥、发送者与渠道上下文、沙箱策略、审批策略、插件 before_tool_call 钩子、中止信号、可用的流式更新,以及轨迹/审计事件。

已完成的嵌套调用会作为有限的、脱敏的仅展示活动持久化,并在历史记录重新加载时保留其原始父 ID 和调用 ID。提供商回放仅包含实际的模型调用;子活动不会添加合成的模型轮次。嵌套调用 ID 包含单元的回放标识,因此提供商可以在后续的助手响应中重用某个工具调用 ID,而不会与较早的活动冲突。在同一运行和同一助手响应中重放相同的调用会保留其嵌套 ID。

运行时转录视图会省略这些持久化的有效载荷。终结(finalization)与智能体结束(agent-end)钩子在需要时从转录中读取其尝试的已接受活动。如果某个 before_message_write 钩子抑制了嵌套活动行,终结与智能体结束钩子也会省略该活动。该成功工具在回合结算中仍计入已完成;抑制其显示历史并不会撤销其执行。开始事件和部分更新保持瞬时性。较早缺失的子历史无法从源代码或外部结果重建。

嵌套工具失败会作为可捕获的 JavaScript 错误传入来宾。如果来宾代码未捕获错误,exec 或 wait 将返回失败的工具结果,智能体可以继续正常运行。请遵循工具错误指南,在选择其他操作之前检查可能的部分影响。网络控制的工具输出和错误保留其现有的不可信内容封装与净化;失败后继续运行不会授予新的权限,也不会重放已完成的副作用。

嵌套调用遵循每个工具的 executionMode。"sequential"(顺序)工具会等待较早的目录调用完成,并阻塞后续调用,直到其结果被接受。支持并行的调用可以在下一个顺序调用之前重叠执行。使用同一运行目录的单元共享调度;不同目录保持相互独立。排队的调用会在其调用方或目录关闭时被取消。

maxPendingToolCalls 限定在途桥接请求的数量上限,而非普通 Promise.all 批次的大小。超出该上限的调用和定时器会在来宾中与 Swarm 请求一起等待。最多可排队 128 个普通请求,与配置的在途上限无关,并沿用现有已接受的桥接限制上限。Swarm 启动、笔记和结果等待不消耗此普通配额;其现有的分组、内存和延续限制仍然适用。排队的输入和请求标识在 wait 之后仍然保留;clearTimeout 会移除已排队的定时器,而不会启动主机定时器。排队定时器的延迟从获得桥接槽位时开始计算。来宾延续会在等待中的请求重新填充可用槽位之前运行,快速的请求仍然会在同一个 exec 或 wait 内被处理完毕。

当创建的普通请求超过其队列配额时,worker 分支会以 invalid_input 失败,并提示等待更小的批次。捕获即时的 JavaScript 错误并不表示接受了部分批次:不会派发来自该同步前沿的任何新调用。较早的 worker 分支可能已经运行过工具;请检查其效果,而不是重放该单元。排队不会提高内存、快照、时间或无头模式下的总工具调用限制,也不会绕过取消和策略检查。

运行与快照生命周期

每个新的 exec 都会启动一个全新的 JavaScript 上下文。变量、函数和导入项不会在单元格之间延续;wait 会继续原始单元格。

每个 code-mode 运行都在进程内的映射中按 runId 跟踪(不会持久化到磁盘或数据库)。exec/wait 返回三种结果状态之一:completed、waiting 或 failed。

  • waiting 结果会保留执行器续延、待处理的桥接请求以及作用域元数据(agent run id、session id/key),直到 wait 恢复它或它过期。
  • 过期、错误会话、错误运行以及未知/正在恢复的 runId 值不会产生独立的终态状态;它们会以 failed 结果(code: "invalid_input")呈现,并带有类似 code mode run is unavailable or expired. 或 code mode run belongs to a different session. 的消息。
  • 运行的续延一旦稳定为 completed 或 failed,或在 Gateway 关闭时被丢弃,就会释放。续延不会在重启后保留;已提交的 session-store 值会保留。
  • OpenClaw 限制每个进程中并发挂起运行的数量(64),超过该上限的新挂起请求会被拒绝,并返回 too many suspended code mode runs.。

所选执行器在单元格生命周期内保持固定。挂起状态受上述每进程上限和 snapshotTtlSeconds 约束。QuickJS 还会在将待处理工作交给 Gateway 之前,检查序列化 VM 大小(包括引擎元数据)是否超过 maxSnapshotBytes。Node 会保留一个活动 worker,没有可测量的序列化快照。这些限制和 memoryLimitBytes 不是 Gateway 的总 RSS 限制;worker 开销和主机侧工具值也会消耗内存。Node 的 memoryLimitBytes 配置一个尽力而为的 V8 worker 堆预算,覆盖老年代和新生代,并受引擎最小值约束。它包括 worker 运行时分配,不包括外部缓冲区。续延报告的保留字节数是诊断估计值,不是强制预留或聚合内存配额。Node 的活动上下文可能比大小受限的 QuickJS 快照使用更多总主机内存。参见 Code Mode 执行器。

显式的 results.save(value) 引用会在现有已接纳目录的生命周期内保留规范化 JSON,独立于每个单元格的 VM 和输出预算。该存储最多接纳 64 个条目以及 min(memoryLimitBytes, maxSnapshotBytes) 编码 JSON 字节(默认 10 MiB),此外还有单元格的程序数据收件箱。这是一种逻辑数据配额,不是进程 RSS 限制。容量错误会保留现有条目;删除会释放其容量。加载返回分离副本,并将网络内容来源信息带入接收单元格的常规不可信输出包装器。

交互式单元格还会自动保留最终结构化 JSON,以避免字节或模型结果适配导致其被截断。worker 会一次性序列化最终值,并最多保留显示配额与现有内存/快照数据配额中较大者;只有符合条件的交互式单元格会请求此捕获。目录接纳会在为有界预览构造解析另一份完整 JSON 副本之前,检查剩余字节和条目数。规范化字符串会移入同一存储。最终投影会在将剩余显示空间分配给采样描述和输出之前,保留一个可用引用;无法显示的引用会被释放。接纳失败仍是一个成功的部分结果,并带有精确的未保留原因。无头执行和重启安全执行不会分配自动引用。

目录拆除、替换、限制以及已接纳运行的中止会清除已保存的数据。追加的客户端工具保留相同的结果存储生命周期,包括已经停在 wait 中的单元格。每个单元格在执行前都会捕获该存储,因此过期单元格不能采用替换存储,也不能在权限变更后保留引用。已保存的引用是数据快照,绝不是执行权限。它们在当前回复结束时过期,并且不会在 Gateway 重启后保留。切勿复用之前轮次中的引用 id;对于稍后需要的小值,请使用 session store。

会话存储持久化

await store(key, value) 和 await load(key) 在两种执行器下使用与 results 相同的异步主机桥接和共享 guest 控制器。Core 会在按 runId 键控的单元格状态中保留待处理写入,因此它们可以在不扩展执行器协议的情况下,存活于 Node 的活动续延和 QuickJS 快照/恢复。加载会将单元格缓冲的集合和删除操作叠加到该运行已提交的 session-store 投影上。

投影会在第一次存储操作时延迟初始化,并共享已接纳目录/结果存储的生命周期。对于已持久化的会话,core 会使用现有的线程外 SessionManager.openAsync API 读取以活动会话当前叶节点结尾的完整分支。这包括比活动管理器的有界水合窗口更早的自定义条目。不匹配的叶节点会使操作失败,而不是暴露另一个分支。后续操作使用投影,应用本次运行自身的提交,而无需重新扫描分支。

只有稳定为 completed 的单元格才会提交其非空写入集。Core 会通过 appendCustomEntryAsync 追加一个类型为 openclaw.code-mode-store 的 custom 条目,然后更新投影。该条目记录设置、删除以及按键划分的网络内容来源信息。失败、超时、中止、过期和已处置的单元格会丢弃其缓冲区。如果追加失败,已完成的结果会携带警告,并且投影保持不变。

转录是持久化所有者:不会创建单独的数据库表、sidecar 或磁盘缓存。重放遵循分支祖先关系,可存活于压缩,并排除其他分支的写入。自定义条目保持在模型上下文之外。加载被标记的值会将接收单元格的运行时标记为包含网络内容,从而在轮次之间保留常规的不可信内容包装器。在无头执行或 restartSafe 执行中,或者在没有绑定会话管理器时,存储操作不可用。数据限制参见 guest 存储契约。

QuickJS-WASI 运行时

捆绑的 code-mode-quickjs 执行器插件拥有其 quickjs-wasi 依赖项和 worker 实现。选择 Node 不需要加载 WASM 运行时。

运行时职责:编译/加载 QuickJS-WASI WebAssembly 模块; 为每次 code-mode 运行或恢复创建一个隔离的 VM; 通过稳定名称注册宿主回调; 设置内存和中断限制; 求值 JavaScript; 排空待处理任务; 快照挂起的 VM 状态; 为 wait 恢复快照; 在终态后释放 VM 句柄和快照。 快照缓冲区在 workers 和 Gateway 之间直接传输, 无需通过存储序列化格式复制 VM 堆。

运行时在 Node.js worker 线程中执行,位于 OpenClaw 主 事件循环之外。来宾无限循环不得无限期阻塞 Gateway 进程; worker 的中断处理程序强制实施墙钟超时, 独立于来宾代码是否配合。

Node 运行时

Node 执行器在 Gateway 主事件循环之外的全新 node:vm 上下文中求值 JavaScript。 它使用与 QuickJS 相同的来宾控制器和 JSON 工具桥接。 挂起会保留 worker、上下文和待处理的 promises; wait 继续该上下文,而不重放源代码。 取消、 过期、终态结果和关闭会释放保留的执行。

成功完成后,Node 最多保持四个空闲 worker 各预热五分钟, 仅复用具有相同运行时入口和堆限制的 worker。 复用保持在创建它的 Gateway 或 CLI 命令生命周期内;关闭该 宿主会触发 worker 退役。没有宿主的独立执行器调用会立即 关闭其已完成的 worker。每个新 cell 仍会获得全新的 VM 上下文。 运行时入口变更和严重内存压力会使空闲 worker 退役;内存压力不会丢弃挂起的 continuations。失败、超时或中止的 cell 会使它们的 worker 退役。

Worker 监督将失控计算排除在主事件循环之外。 worker 线程和 node:vm 均不提供操作系统安全 边界。使用执行器指南选择 适当的信任模型。

TypeScript

TypeScript 风格的签名通过快速索引、目录句柄和 API.read 声明文件向模型描述工具输入和输出。 未知输出保持为 unknown,声明不会授予对额外工具的访问权限。

可执行 cell 是普通 JavaScript。Code Mode 不会加载 TypeScript 编译器、剥离类型注释或类型检查程序。所选引擎直接解析并运行 JavaScript。工具调用仍使用现有的运行时输入和 输出验证、策略和审批所有者。后续调用可能在 先前调用已产生效果后失败,因此在 重试失败的 cell 之前,请遵循 恢复指南。

安全边界

Node 是可信执行的默认执行器。其预期的全局变量和 模块守卫不会使 node:vm 成为安全边界。模型输出可能 受提示注入影响;当来宾必须与宿主隔离时, 选择捆绑的 QuickJS 执行器。

QuickJS 在一个 WASM 来宾中执行,没有环境文件系统、网络、 子进程、环境或模块访问。它使用引擎内存和中断 限制、父级墙钟截止时间和有界序列化快照。

两个执行器都在主事件循环之外运行,使用相同的 JSON 工具桥接, 强制输出和待处理调用上限,并在超时、 中止、会话结束或过期时释放 continuations。Core 保留工具策略、审批、钩子和 会话所有权。对 Code Mode 和 Tool Search 控制工具的递归访问 被排除在来宾目录之外。这些共享工具检查无法阻止 Node VM 逃逸,并且授予一个强大工具仍会将其能力授予 QuickJS 来宾。参见Code Mode 执行器了解 面向操作员的选择和操作系统隔离指南。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw