Code Mode 快速入门

启用代码模式¶

当 tools.codeMode 不存在时，OpenClaw 会在未来的 agent 运行中使用 "auto" 层级。它仅对提供商目录中标记为首选的模型启用代码模式。此默认行为无需任何配置。

使用 Settings → Agents & Tools → Labs → Code Mode 更改全局设置。更改将应用于未来的 agent 运行，无需重启 Gateway。

要在不使用 Control UI 的情况下启用相同层级，请在配置中进行设置：

{
  tools: {
    codeMode: "auto",
  },
}

要为每次支持工具的运行默认开启代码模式（无论使用何种模型）：

{
  tools: {
    codeMode: true,
  },
}

对象形式同样有效：tools.codeMode.enabled 接受相同的 false、true 和 "auto" 值。对于 false 或未显式提供 enabled 值的已编写对象，代码模式保持关闭，除非 agent 或模型覆盖将其启用。配置限制或其他代码模式选项不会启用它。

启用后，代码模式默认使用 Node 的 node:vm 执行器进行可信执行。在同一设置面板中选择 QuickJS，或设置 tools.codeMode.executor: "quickjs" 以获得强化的 guest 隔离。在选择之前，请先阅读代码模式执行器：node:vm 不是安全边界。

有关精确语义和随附的模型列表，请参阅按模型自动激活。

如果使用配置了 MCP 服务器的沙箱 agent，请同时在沙箱工具策略中允许随附的 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" 应设置在全局或每个 agent 的 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 },
        },
      },
    },
  },
}

该示例为此模型启用代码模式，但 research agent 除外。激活按以下顺序从第一个显式设置开始解析：

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 中，打开 Settings → Agents → Agent defaults，显示 Advanced 设置，并在 Agent Defaults 下找到 Models。每个模型在其运行时旁边都有一个 Code Mode 选择器：Default 移除覆盖，On 保存 true，Off 保存 false。对于 agent 专属覆盖，展开 Agent List，然后是该 agent 的 Agent Model Overrides。不支持的字段仍会被标记为需要 Raw 编辑，而不会隐藏旁边的受支持设置。

覆盖会影响所选模型在未来的运行（包括备用模型）；它们不会在无工具运行中启用工具，也不会改变运行时选择。该示例单独选择 agentRuntime.id: "openclaw"，因为 OpenAI 路由否则可能会使用 Codex。这些设置不会控制 Codex 原生的 Code Mode。模型覆盖仅改变激活状态；限制仍来自全局和每个 agent 的 tools.codeMode 选项。

模型的行为¶

对于具有声明输出的工具，例如 Array<{ id: string; paid: boolean; tons: number }>，一个 guest 程序可以选择、调用并转换它：

const [shipmentTool] = await catalog.search("list shipments");
const shipments = await shipmentTool({});
return shipments.filter((shipment) => !shipment.paid && shipment.tons > 10);

声明的输出字段可以在同一个 exec 中供后续调用使用；不要仅仅为了检查它们而再花费一次 exec。

当 quick-index 行以 -> ? 结尾时，输出形状是未知的。第一次 exec 必须原样返回最终的异步工具调用，或将其值保存为有界预览。不要在同一程序中将未知值输入到猜测的字段相关逻辑中。先检查原始值或已保存的预览，然后在后续的 exec 中进行依赖组合。

跨单元格复用数据¶

正常返回不熟悉的结果。当最终对象或数组超出输出或模型结果预算时，交互式 exec 和 wait 会在容量允许时自动保存它。完成的结果包含 value: { truncated: true, reference: { id, bytes, count, shape, preview, previewTruncated }, guidance }。在另一个单元格中，使用该 reference 的 id 配合 results.load(id)。较小的返回值保持其普通形状；发出的 text 和 json 输出不会自动保存。

当后续步骤需要检查和转换某个获取的结果时，请保存它：

const [shipmentTool] = await catalog.search("list shipments");
return await results.save(await shipmentTool({}));

直接将该 descriptor 作为单元格的输出返回。其 preview、shape 和 count 已准备就绪；完整的获取值保留在已保存的存储中。

返回的引用包含 id、编码后的 JSON bytes、count、采样得到的 shape，以及一个受限长度的字符串 preview。count 为顶层数组长度、对象键数量，对于标量则为 1。嵌套数组长度以路径和采样项索引的形式出现在采样视图中。首项、中间项和末项提供观测到的形状，包括观测到的异构值；这些并非模式（schema）或校验保证。发现过程最多访问 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，因此在组合使用前请检查其形状。

引用仅对当前 agent 运行和 catalog 有效。它们能在单元格完成和 wait 后继续存在，但无法跨越运行结束、中止、catalog 替换、权限变更或 Gateway 重启。它们是快照：当当前外部状态变得重要时，请重新获取。该存储最多持有 64 个值，编码后 JSON 的总配额为 min(memoryLimitBytes, maxSnapshotBytes)（默认 10 MiB），与单元格收件箱分开。存储满时，新的保存会失败；现有引用永远不会被自动驱逐。不会保存任何函数、工具句柄或权限。在 restartSafe 单元格中，结果操作不可用，因为引用是瞬态的，且删除操作无法被安全重放。

在 headless 执行中，自动保留也被禁用。如果容量、数据配额或输出预算阻止了引用的交付，原始调用仍保持完成状态，并返回一个普通的截断标记，说明完整结果未被保留。现有引用保持不变；不会公布任何部分保存的值。

从工具错误中恢复¶

嵌套工具失败是普通的 JavaScript 错误。Guest 代码可以捕获它们并检查诊断字段：code 标识 input_contract、output_contract、invalid_contract、invalid_input 或 tool_error；location 在可用时包含原始的 guest 调用点帧。effectStatus 保持为 "unknown"：分类并不是分派所有者的回执，也绝不会授予重试权限。特别是，工具可能在开始工作后抛出输入错误。Guest 代码可以返回选择下一步所需的信息：

try {
  return await terminal({ action: "list" });
} catch (error) {
  return { status: "unavailable", error: error.message };
}

对于 output_contract，工具返回的响应未通过其声明的输出模式。该错误包含最多五条验证详情，每条限制为 256 个 UTF-8 字节并附带截断标记，同时提供字段路径和预期约束。响应体被省略。例如，receipt.count: must be number 标识了格式错误的 count，而不会打印返回的值。重试前请检查当前状态：结果验证不会撤销之前的效果，且 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。如需完整的脱敏 provider 载荷，请在短时调试会话中添加 OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted。

使用 Swarm 进行 agent 扇出¶

Swarm 添加了 agents.run()、phase() 和 log() 这些 guest 全局函数，用于从 Code Mode 脚本编排并发的子 agent。Swarm 默认启用；Code Mode 的激活保持独立。使用常规 JavaScript 控制流进行扇出、决策门和结构化收集。

Swarm 全局对象、API.read("agents.d.ts") 以及 Swarm 的 prompt 提示仅在 Swarm 启用、原生 OpenClaw sessions_spawn 工具存在于 Code Mode catalog 中且被运行的执行允许列表许可时才会出现。同名的 MCP 工具不符合条件。Code Mode 会在内部等待收集器结果，因此 agents.run() 不需要独立的 agents_wait 工具。直接进行底层 Swarm 使用需要同时允许这两个工具。

设置 tools.swarm: false 或 tools.swarm.enabled: false 以选择退出，可全局设置，或在某个 agent 的 tools 下设置。启用 Code Mode 不会覆盖该退出设置，也不会授予访问被策略拒绝的工具的权限。

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