Code Mode 快速入门
启用 Code Mode¶
当 tools.codeMode 缺失时,OpenClaw 会为未来的智能体运行使用 "auto" 层级。它仅对提供商目录中标记为首选的模型启用 Code Mode。此默认值无需配置。
使用 设置 → 智能体与工具 → 实验室 → Code Mode 修改全局设置。更改将应用于未来的智能体运行,无需重启 Gateway。
若要在不使用 Control UI 的情况下启用相同层级,请在配置中设置:
若要为每个支持工具的运行默认开启 Code Mode,无论模型如何:
对象形式也可以:tools.codeMode.enabled 接受相同的 false、true 和 "auto" 值。对于 false 或未显式提供 enabled 值的手动编写对象,Code Mode 保持关闭,除非智能体或模型覆盖启用了它。配置限制或其他 Code Mode 选项不会启用它。
启用后,Code Mode 默认使用 Node 的 node:vm 执行器进行可信执行。在同一设置面板中选择 QuickJS,或设置 tools.codeMode.executor: "quickjs" 以启用强化的来宾隔离。选择前请阅读 Code Mode 执行器:node:vm 不是安全边界。
有关确切语义和随附模型列表,请参阅 按模型自动激活。
如果使用配置了 MCP 服务器的沙箱智能体,还请在沙箱工具策略中允许捆绑的 MCP 插件,例如 tools.sandbox.tools.alsoAllow: ["bundle-mcp"]。请参阅 配置 - 工具和自定义提供商。
设置显式限制以获得更严格的边界:
{
tools: {
codeMode: {
enabled: true,
executor: "quickjs",
timeoutMs: 10000,
memoryLimitBytes: 67108864,
maxOutputBytes: 65536,
maxSnapshotBytes: 10485760,
maxPendingToolCalls: 16,
snapshotTtlSeconds: 900,
searchDefaultLimit: 8,
maxSearchLimit: 50,
},
},
}
覆盖单个模型¶
在 agents.defaults.models 中的精确 provider/model 条目上设置 codeMode: true 或 codeMode: false。省略 codeMode 以继承父级激活设置,包括其 "auto" 行为。模型字段仅接受布尔值;"auto" 应放在全局或按智能体的 tools.codeMode 设置中。诸如 "openai/*" 的通配符行可以配置运行时策略,但不能设置 codeMode;配置验证会拒绝它们,而不是忽略该覆盖。
{
tools: { codeMode: "auto" },
agents: {
defaults: {
models: {
"openai/gpt-5.6-luna": {
agentRuntime: { id: "openclaw" },
codeMode: true,
},
},
},
entries: {
research: {
models: {
"openai/gpt-5.6-luna": { codeMode: false },
},
},
},
},
}
该示例为此模型启用 Code Mode,但在 research 智能体上除外。激活按以下顺序从第一个显式设置解析:
agents.entries.<agent>.models["provider/model"].codeMode。agents.entries.<agent>.tools.codeMode.enabled(或其布尔值/"auto"简写)。agents.defaults.models["provider/model"].codeMode。tools.codeMode.enabled(或其简写);完全缺失的全局设置默认为"auto",而缺少enabled的手动编写对象默认为false。
在 Control UI 中,打开 设置 → 智能体 → 智能体默认值,显示 高级 设置,并在 智能体默认值 下找到 模型。每个模型在其运行时旁边都有一个 Code Mode 选择器:默认 会移除覆盖,开 保存 true,关 保存 false。对于特定智能体的覆盖,展开 智能体列表,然后展开该智能体的 智能体模型覆盖。不支持的字段仍会标记为 原始 编辑,而不会隐藏旁边的受支持设置。
覆盖会影响未来运行中选择的模型,包括回退模型;它们不会在无工具运行中启用工具,也不会更改运行时选择。该示例单独选择 agentRuntime.id: "openclaw",因为否则 OpenAI 路由可能会使用 Codex。这些设置不会控制 Codex 原生 Code Mode。模型覆盖仅更改激活;限制仍来自全局和按智能体的 tools.codeMode 选项。
模型会做什么¶
每个 exec 都会启动一个新的 JavaScript 上下文。变量和函数不会在单元格之间延续;wait 会恢复同一单元格。对于本会话中跨轮次需要的小型 JSON 值(包括重启后),请使用 await store(key, value) 和 await load(key)。有关其提交规则和限制,请参阅 会话存储。
对于具有声明输出的工具,例如 Array<{ id: string; paid: boolean; tons: number }>,一个来宾程序可以选择、调用并转换它:
const [shipmentTool] = await catalog.search("list shipments");
const shipments = await shipmentTool({});
return shipments.filter((shipment) => !shipment.paid && shipment.tons > 10);
声明的输出字段可用于同一 exec 中的后续调用;不要仅为了检查它们而花费第二个 exec。
当快速索引行以 -> ? 结尾时,输出形状未知。第一个 exec 必须原样返回最终的异步工具调用,或保存其值以进行有界预览。不要在同一程序中将未知值输入到猜测的字段依赖逻辑中。检查原始值或已保存的预览,然后使用后续的 exec 进行依赖组合。
跨单元格复用数据¶
正常返回不熟悉的结果。当最终对象或数组将超出输出或模型结果预算时,交互式 exec 和 wait 会在容量允许时自动保存它。已完成的结果包含 value: { truncated: true, reference: { id, bytes, count, shape, preview, previewTruncated }, guidance }。在另一个单元格中使用该引用的 id 和 results.load(id)。小型返回值保持其普通形状;发出的 text 和 json 输出不会自动保存。
当后续步骤需要检查并转换获取的结果时,请保存该结果:
const [shipmentTool] = await catalog.search("list shipments");
return await results.save(await shipmentTool({}));
直接将该描述符作为单元格的输出返回。其预览、形状和计数已准备就绪;完整获取的值保留在保存的存储中。
返回的引用包含一个 id、编码后的 JSON bytes、count、采样的 shape 以及有界的字符串 preview。count 是顶层数组长度、对象键数量,对于标量则为 1。嵌套数组长度以路径和采样项索引的形式出现在采样视图中。第一个、中间和最后一个条目提供观察到的形状,包括观察到的异构值;这些不是模式或验证保证。发现过程最多访问 128 个节点、五个层级和每个对象 16 个键,并优先处理它找到的八个最大的数组。有限的遍历会被明确标注。紧凑的标量封装字段与数组采样一起提供上下文。
小型预览包含完整的 JSON。较大的预览描述采样数据,并且其本身可能被截断为 JSON 前缀。previewTruncated: true 始终表示预览不完整。描述符可容纳在 768 个编码后的 JSON 字节以内;输出和模型预算可能会进一步缩短其描述性字段,同时保留其标识。在处理完整数据前,请先加载原始 JSON。
检查这些字段后,后续单元格可以复用原始结果:
const shipments = await results.load("result_<id from the previous cell>");
return shipments.filter((shipment) => !shipment.paid).length;
每次加载都会返回独立的 JSON 副本。修改它不会改变已保存的值。使用 await results.delete(id) 释放容量。缺失或过期的引用会以可捕获的错误拒绝。API.read("results.d.ts") 提供 TypeScript 风格的文档;加载的数据被声明为 unknown,因此在组合它之前请检查其形状。
引用在当前回复结束时过期;绝不重用之前轮次中的 id。对于稍后需要的小型 JSON 值,请使用 store。引用在单元格完成和 wait 期间仍然有效,但在回复结束、中止、目录替换、权限更改或 Gateway 重启时失效。它们是快照:如果当前外部状态很关键,请重新获取。结果存储最多保存 64 个值,总编码 JSON 配额为 min(memoryLimitBytes, maxSnapshotBytes)(默认 10 MiB),与单元格收件箱分开。存储已满时,新的保存会失败;现有引用永远不会被自动驱逐。不会保存函数、工具句柄或权限。结果操作在 restartSafe 单元格中不可用,因为引用是瞬态的,且删除无法安全重放。在无头执行中,自动保留也被禁用。如果容量、数据配额或输出预算阻止交付引用,原始调用仍然完成并返回一个普通的截断标记,说明完整结果未被保留。现有引用保持不变;不会公布部分保存的值。
从工具错误中恢复¶
嵌套的工具失败是普通的 JavaScript 错误。客端代码可以捕获它们并检查诊断字段:code 标识 input_contract、output_contract、invalid_contract、invalid_input 或 tool_error;location 在可用时包含原始客端调用点帧。effectStatus 保持为 "unknown":分类不是分派所有者的回执,也绝不授予重试权限。特别是,工具可能在开始工作后抛出输入错误。客端代码可以返回选择下一步操作所需的信息:
try {
return await terminal({ action: "list" });
} catch (error) {
return { status: "unavailable", error: error.message };
}
对于 output_contract,工具返回的响应未通过其声明的输出模式。错误包含最多五条验证详情,每条限制为 256 个 UTF-8 字节并附截断标记,包含字段路径和期望的约束。响应体被省略。例如,receipt.count: must be number 标识了格式错误的计数,而不打印返回的值。在重试之前检查当前状态:结果验证不会撤销先前的影响,且 effectStatus 保持为 "unknown"。
等待每个工具调用或显式处理其拒绝。OpenClaw 在完成单元格之前会排空已分派的调用;未处理的拒绝(包括来自未等待的调用或定时器回调的拒绝)会使单元格失败,而不是静默报告成功。在挂起之后附加的处理器仍然处理其原始 promise。
JavaScript 语法错误和未捕获的嵌套工具失败会成为失败的 exec 或 wait 结果。模型可以读取错误、修正代码、检查当前状态并继续使用正常的工具界面。失败的单元格不会强加单独的恢复模式或变更预算。
OpenClaw 不会自动重放失败的程序。之前的调用可能已更改状态,而失败的调用可能已部分应用。在决定剩余操作之前检查权威状态,并且不要重复已完成的操作。这也适用于 wait 恢复挂起单元格的情况:其先前的调用属于同一个程序。
每个后续调用都会再次运行常规钩子和审批。已消耗的语音确认保持已消耗状态;出错后继续不会恢复授权。取消、明确的终止性工具结果、沙箱限制、审批要求和工具策略拒绝都保持其现有行为。
验证活动表面¶
要在调试时确认模型负载的形状,请使用定向日志运行 Gateway:
OPENCLAW_DEBUG_CODE_MODE=1 \
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 \
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools \
openclaw gateway
启用代码模式后,记录的面向模型的工具名称应为 exec 和 wait。如需完整的脱敏提供方负载,可在短时调试会话中添加 OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted。
使用 Swarm 进行代理扇出¶
Swarm 添加了 agents.run()、phase() 和 log() 访客全局变量,
用于在 Code Mode 脚本中编排并发子代理。Swarm 默认启用;Code Mode 激活仍然独立。
使用常规 JavaScript 控制流进行扇出、决策门控和结构化收集。
Swarm 全局变量、API.read("agents.d.ts") 以及 Swarm 提示线索仅在以下情况下出现:
Swarm 已启用,且原生 OpenClaw sessions_spawn 工具存在于 Code Mode 目录中,
并获得运行的执行允许列表的许可。同名 MCP 工具不符合条件。Code Mode 在内部
等待收集器结果,因此 agents.run() 不需要独立的 agents_wait 工具。
直接低层使用 Swarm 需要两个工具均被允许。
设置 tools.swarm: false 或 tools.swarm.enabled: false 可选择退出,全局或
在某个代理的 tools 下。启动 Code Mode 不会覆盖该退出选择,也不会授予对
策略拒绝工具的访问权限。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw