Code Mode 工具界面
模型可见工具¶
当代码模式激活时,模型可以看到 exec、wait 以及任何必需的仅直接访问工具。所有其他已启用的工具都会从模型可见的工具列表中隐藏,并注册到代码模式目录中。
使用 exec 进行工具编排、数据连接、循环、并行嵌套调用和结构化转换。仅当 exec 返回可恢复的 waiting 结果时,才使用 wait。
exec¶
exec 在一个全新的 JavaScript 上下文中启动一个代码模式单元格,并返回一个结果。变量、函数和导入永远不会在单元格之间保留。await store(key, value) 和 await load(key) 可跨单元格和轮次在同一个会话中保留小型 JSON 值,包括重启之后。有关限制和提交规则,请参阅会话存储。输入代码由模型生成,必须视为不可信内容。
面向模型的输入:
type CodeModeExecInput = {
title: string;
code: string;
restartSafe?: boolean;
awaitResults?: boolean;
};
规则:
- 每个新单元格都需要一个非空
title,最多 120 个字符。使用简短的目的描述,通常为 3–7 个词,例如“检查依赖关系图”。描述预期工作,不要声称成功或包含机密信息。Control UI 会在执行行上显示该标题。嵌套工具保留各自的摘要;wait不需要标题,并在原始单元格下恢复活动。 code是必需的面向模型的 JavaScript 字段,且必须非空。command作为 exec 兼容的别名被接受,用于钩子策略和可信重写(普通的 OpenClaw shell exec 工具也使用command字段)。空白的调用方别名视为不存在;如果钩子或可信策略使一个已填充的别名(空白或非字符串)失效,则两个别名都会失效,从而使执行以安全失败方式结束。当两个别名均非空时,它们的值必须匹配。- 编写纯 JavaScript。不接受 TypeScript 注解、接口和其他 TypeScript 专用语法。工具签名和
API.read声明仍作为编写调用的文档提供。 API.read(path)返回{ path, description, content, bytes },而不是字符串。使用(await API.read(path)).content获取声明文本。- 已废弃的
language和typecheck字段会被拒绝并返回invalid_input。工具参数在每次调用到达其正常执行所有者时进行验证;代码模式不会在执行前对整个程序进行类型检查。 - 不要在新的
exec上设置restartSafe。仅当 OpenClaw 在网关重启后明确请求重放时才将其设置为true,且切勿在write、edit、exec或任何变更操作上设置。每个目录调用都必须明确具备重放安全性。OpenClaw 会拒绝未标记的目录工具和未被证明具备重放安全性的命名空间表面。仅仅因为某个命令看起来是只读的,泛型 exec 表面并不具备重放安全性;请使用经过审计的 read、grep 或 find 工具。挂起的结果会被标记为具备重放安全性,以便重启恢复可以从其记录中重建中断的轮次,而不是恢复进程本地的续延状态。恢复仍仅限于经过审计的只读核心工具和明确具备重放安全性的插件工具。store和load在restartSafe单元格中不可用。普通调用请省略该字段。 exec拒绝import、require、动态导入和模块加载器模式。exec永远不会递归地暴露普通的 shellexec实现。- 外层代码模式
exec钩子事件携带toolKind: "code_mode_exec"和toolInputKind: "javascript",因此策略可以区分代码模式单元格与共享相同工具名称的 shell 风格exec调用。
结果:
type CodeModeResult = CodeModeCompletedResult | CodeModeWaitingResult | CodeModeFailedResult;
type CodeModeCompletedResult = {
status: "completed";
value: unknown;
warnings?: string[];
output?: CodeModeOutput[];
telemetry: CodeModeTelemetry;
};
type CodeModeWaitingResult = {
status: "waiting";
runId: string;
reason: "pending_tools" | "yield";
pendingToolCalls?: CodeModePendingToolCall[];
output?: CodeModeOutput[];
telemetry: CodeModeTelemetry;
};
type CodeModeFailedResult = {
status: "failed";
error: string;
code?: CodeModeErrorCode;
output?: CodeModeOutput[];
telemetry: CodeModeTelemetry;
};
当访客以可恢复状态挂起但仍需要面向模型的续延(continuation)时,exec 返回 waiting —— 即显式的 yield_control(...) 调用,或在 exec 截止时间内尚未解析的桥接工具调用。结果中包含供 wait 使用的 runId。原生通道 exec 审批有所不同:在操作员决策待定期间,OpenClaw 会同时挂起代码模式执行预算和所属的 agent 运行预算。原始的 exec 保持进行中状态,待审批解决后以精确未使用的预算恢复;它不会返回 pending_tools,也不需要模型通过 wait 进行轮询。如果访客在兄弟调用等待审批时显式让出,单元格在停放期间会继续观察该审批。其下一次 wait 也会暂停以等待该待定决策。每次调用仅获得其自身未使用的执行预算;停放时间和先前调用的审批暂停不会累加执行信用。取消、所有者检查和续延期满保持不变。桥接请求 —— catalog.search、句柄 describe()、可调用工具句柄以及包括 MCP 在内的命名空间调用 —— 会在同一个 exec/wait 调用内自动排空,只要它们在截止时间内解析,因此一个紧凑的代码块可以在一个模型轮次内等待多个工具并运行完成,而无需强制每次 await 都进行一次模型工具调用。没有 yieldMs 或 background: true 的桥接 shell exec 会等待剩余调用预算(tools.codeMode.timeoutMs,默认 10 秒)减去恢复余量后才转入后台,因此在该时间窗口内完成的命令会在同一轮次中以内联方式返回。较晚的顺序调用会更早转入后台,但仍会返回其进程句柄,以便访客可以内联恢复。
exec 仅在来宾 VM 没有待处理工作,并且在 OpenClaw 的输出适配器运行后最终值兼容 JSON 时,才返回 completed。
新的 exec 和 wait 结果文本使用紧凑 JSON,以便为工具数据保留更多上下文预算。状态、延续、重放安全性、遥测以及结构化 details 字段均会保留。JSON 字符串内的文本保留其原始空白。TUI 将这些结果作为字面文本显示,因此 Markdown 语法和长 token 格式化不会改变其值。URL 仍作为可见文本显示,而不会变成 Markdown 链接。
必需结果¶
当当前任务需要该程序的结果才能完成时,使用 awaitResults: true。现有 cell 所有者会在 VM 被停放期间保持工具调用打开,然后在待处理工具结果结算时恢复该确切延续。它不会返回 waiting 句柄,也不会发起模型轮询调用。已完成的操作不会被重放。失败、Stop、所有者替换以及现有 run 和工具截止时间仍会结束该操作。
awaitResults 仅暂停 VM 外部的工具等待。准备、来宾执行、检查点和恢复共享原始执行额度;每次结算都不授予新的额度。输出、内存、待处理调用和活跃 cell 限制保持不变。yield_control 不能放弃一个未完成的必需程序;请完成该程序或取消所属 run。普通 cell 保留其现有的显式 yield 行为。
必需 cell 会将普通 shell 命令收集至完成。显式 background: true 仍然是有意分离服务器的选择退出方式。在普通 cell 内的 shell exec({awaitResults: true, ...}) 或 agents_wait({awaitResults: true, ...}) 也会使该 cell 成为必需 cell。这些声明不会启用 tools.exec.notifyOnExit。
对于必需收集器结果,请在必需 cell 中等待 agents.run(...),或调用 agents_wait({ids, awaitResults: true})。普通通告子项仍使用其现有的 sessions_yield 交接。已接受的 background 句柄不是终端结果:此功能不会从计划文本推断义务,也不会静默地将每个异步服务变成必需工作。
会话历史中的源代码¶
在内置 OpenClaw 运行时中,JSON Code Mode 工具执行原始输入。会话历史会保留外层调用 JavaScript code 和 command 字段中的计算,例如 const API_TOKEN = computeToken();,以及布尔值或 null 初始化器,同时掩码凭据字面量、可识别 token、已注册 secret 和已配置脱敏模式。凭据赋值使用完整掩码,以便重复存储脱敏保持稳定。
此处理不适用于 shell 命令、嵌套工具调用、无关参数字符串或助手文本。大型或无法识别的源代码语法仍受诊断掩码处理。存储的源代码是脱敏记录,不是恢复凭据的地方;无需额外设置。 这适用于新调用;已脱敏的源代码无法重建。 Copilot 运行时的独立转录日志尚未保留此源代码结构。Native Codex 使用独立的自由格式源代码路径;此行为不描述其存储。
wait¶
wait 继续一个已挂起的 code-mode VM。
输入:
输出是与 exec 返回的相同的 CodeModeResult 联合类型。
wait 存在是因为嵌套 OpenClaw 工具可能缓慢、交互式或流式传输部分更新;模型不应需要在宿主等待普通外部工作时保持一个长时间 exec 调用打开。原生通道 exec 审批是例外:它们保留在原始 exec 内,以便审批权限仍绑定到已准入的 run。
快速内联宿主交换保留相同的执行上下文。显式 yield 或耗尽的调用预算可以挂起它,而不会重放工具。Node 保留活动 worker 上下文;QuickJS 对其 VM 进行快照,并可以释放 worker。QuickJS worker 池压力也可能在同一调用内部停放一个 cell。实际的 QuickJS 检查点会强制 maxSnapshotBytes,因此大型活动堆可能内联完成,但在必须真正停放时失败。
两个执行器使用相同的 wait 契约:
exec评估代码,直到完成、失败或挂起。- 挂起时,所选执行器保留其延续,OpenClaw 记录待处理宿主工作。
- 当待处理工作结算时,
wait恢复同一执行器。Node 继续其活动上下文;QuickJS 恢复其快照并重新注册回调。 - OpenClaw 传递嵌套工具结果,并让 JavaScript 延续运行。
wait返回completed、failed或另一个waiting结果。
延续是运行时状态,而不是用户工件:其所有权仅存在于进程内映射中(无数据库或磁盘写入),它们会过期,并且其作用域限定为创建它们的 run 和 session。QuickJS 快照有大小限制;Node 则保留活动 worker 内存。参见
Code Mode 执行器。
一个 cell 所有者跨越初始执行、挂起和每次恢复。取消所属 run 或当前工具调用,或在尝试拆卸时关闭其工具目录,会取消活动 worker 和待处理宿主工作,并释放已停放的延续,即使之后没有 wait 调用。目录描述刷新和客户端工具添加不会关闭所有者。忽略取消的外部操作可能仍会完成,但无法恢复已关闭的来宾、发出后续来宾输出或启动另一个来宾工具调用。
进程范围的 64 个槽位限制适用于已挂起的 cell 及其保留的恢复槽位。恢复会保留其槽位,直到完成或再次停放;初始执行在分发宿主工作之前保留一个槽位,并在活动执行和内部停放期间保留它。没有宿主工作的 cell 不消耗槽位。
快照 TTL 衡量单元处于停放状态时的空闲时间。被接受的 wait 会在其调用截止时间之内保持单元存活,同时等待中的工具完成处理。如果该调用再次返回 waiting,停放会启动一个新的快照 TTL。
wait 在以下情况下会失败(作为 failed 结果):
runId未知,或其续接已过期。- 调用方与挂起的运行不在同一运行/会话作用域中。
- 该
runId已有一个wait正在处理中。 - 所选执行器无法恢复(例如,其 worker 已退出或 QuickJS 恢复失败)。
- QuickJS 检查点将超过
maxSnapshotBytes。普通的超大成功输出会被截断,但仍保持成功。
工具目录¶
隐藏目录包含经过有效策略过滤后的工具,顺序如下:OpenClaw 核心工具、捆绑插件工具、外部插件工具、MCP 工具,然后是当前运行中由客户端提供的工具。
目录 ID 仍然是不透明的、仅限宿主的路由标识。它们在单次运行内保持稳定,并在可能的情况下在等效工具集之间保持确定性,但永远不会包含在 prompt、guest 元数据、handle 描述或错误中。策略、审批、遥测、重放安全性和命名空间分发仍会在内部继续使用它们。
在 worker 启动之前,OpenClaw 会为每个精确工具名称投影出一个有效胜出者,并计算其最终的 guest 可调用名称。这与直接模式优先级一致:较晚的客户端工具会赢得精确名称遮蔽,而插件冲突执行保持不变。最终确定的投影会随 bridge 调用和续接恢复传递;消费者不会从目录中重建它。
目录会省略代码模式控制工具(exec、wait、tool_search、tool_describe、tool_call)和仅限直接的工具。控制工具不得通过目录递归;仅限直接的工具保持模型可见,因为其结构化结果无法跨越 JSON guest 桥。
MCP 条目保留在运行作用域目录中,以便策略、审批、hooks、遥测、transcript 投影和精确工具 ID 与正常工具执行保持共享。catalog.search(...) 会一起搜索原生和 MCP 能力,并返回可调用 handle。MCP 匹配项会标识其最终 MCP.<server>.<tool> 路径和声明文件;调用 handle 会使用同一个命名空间分发器。catalog.all() 仅列出原生和客户端 handle。远程描述和 schema 不会进入受信任的快速索引。
Tool Search 交互¶
对于代码模式处于活动状态的运行,代码模式会取代 OpenClaw Tool Search 模型表面。
当代码模式通过强制 true 或 "auto" 激活时:
- OpenClaw 不会将
tool_search、tool_describe或tool_call暴露为模型可见工具。 - 相同的目录化思路移入 guest 运行时内部。
- guest 运行时会接收裸 async 全局变量,以及用于原生工具的可调用 search/describe handle,外加按需的 MCP search handle。
- MCP 调用使用生成的
MCP命名空间,直接调用或通过 search handle 调用;handle 的describe()会请求精确的$api()头和 schema。 - 嵌套调用通过 Tool Search 使用的同一 OpenClaw 执行器路径进行分发。
有关代码模式在活动运行中取代的 OpenClaw 结构化目录表面,请参阅 Tool Search。
工具名称与冲突¶
模型可见的 exec 工具是代码模式工具。如果启用了普通 OpenClaw shell exec 工具,它会从模型中隐藏,并像任何其他工具一样编入目录。
在 guest 运行时内部:
- 精确的 JavaScript 安全工具名称保持精确:
web_search(...)和sessions_spawn(...)。 - 无效标识符字符会变成
_;仍然无效的首字符会获得tool_前缀。例如,当该名称可用时,llm-task会变成llm_task。 - JavaScript 保留字、专用全局变量和规范化冲突会获得一个从仅限宿主标识派生的确定性短后缀。
- 精确安全名称会赢得其无后缀拼写。原始工具永远不会覆盖
catalog、MCP、API、nodes、skills、namespaces、results、store、load、输出/计时器辅助函数,或可选的 Swarm 全局变量。 - 当策略允许时,普通 shell
exec工具可以作为exec(...)guest 全局变量调用。代码模式控制exec在 guest 内部不可递归使用。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw