代码模式

• Codex Code Mode 运行在 Codex 编码框架内。它的 exec 工具是一种自由形式语法工具：模型编写原始 JavaScript 源码（可选地在前面加上 // @exec: {...} pragma 行以指定执行选项），并在 Codex 的进程内 V8 Code Mode 运行时中执行。
• OpenClaw 代码模式运行在通用 OpenClaw 代理运行时中，由 tools.codeMode.enabled（默认 "auto"，按模型激活）控制。它的 exec 工具接受一个 JSON { code, language } 载荷，并在 QuickJS-WASI worker 中执行。

​

它的作用

• 面向模型可见的工具列表会变为 exec、wait，再加上任何仅直接可用的工具
  例如 computer，或原生视觉 image 加载器，其图像结果
  无法通过访客桥接继续传递。
• exec 会在隔离的 QuickJS-WASI 工作线程中执行模型生成的 JavaScript 或 TypeScript。
• 每个符合目录条件且已启用的工具（OpenClaw 核心工具、插件、MCP、客户端）都会从
  独立的模型工具中隐藏，并通过 ALL_TOOLS
  和 tools 暴露给访客程序。
• exec 的描述包含一个受限的快速索引，列出精确的 OpenClaw/插件
  目录 ID、简洁的输入提示，以及在受信任工具提供输出 schema 时的简洁声明输出提示。它省略了描述、完整 schema、
  MCP 条目和溢出条目；访客侧的目录查找仍然是回退方案。
• 访客代码会搜索隐藏目录，描述工具的 schema，并通过与普通 agent 回合
  相同的执行路径调用工具（策略、审批、hooks、遥测仍然全部适用）。
• MCP 工具会按 MCP 命名空间分组；在代码模式中，这是调用它们的唯一支持方式。
• 当嵌套工具调用仍在等待时，wait 会恢复一个已挂起的代码模式运行。

​

为什么使用它

• 更小的提示面：提供方只获得两个控制工具、一个有界的原生工具索引，以及少量必需的直接工具，而不是几十或几百个完整的工具模式。
• 更好的编排：模型可以在一个代码单元中使用循环、连接、小型转换、条件逻辑以及并行嵌套工具调用。
• 更少的模型往返：声明式输出契约让模型能够在一次 exec 中调用并转换工具结果；未知输出仍保持原始优先。
• 提供方无关：可用于 OpenClaw、插件、MCP 和客户端工具，而不依赖提供方原生代码执行。
• 失败即关闭：如果启用了代码模式但 QuickJS-WASI 运行时不可用，运行将失败，而不是悄悄回退到广泛的直接工具暴露。

​

快速开始

​

默认值和覆盖

{
  tools: {
    codeMode: false,
  },
}

{
  tools: {
    codeMode: true,
  },
}

{
  tools: {
    codeMode: {
      enabled: true,
      timeoutMs: 10000,
      memoryLimitBytes: 67108864,
      maxOutputBytes: 65536,
      maxSnapshotBytes: 10485760,
      maxPendingToolCalls: 16,
      snapshotTtlSeconds: 900,
      searchDefaultLimit: 8,
      maxSearchLimit: 50,
    },
  },
}

​

模型会做什么

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

​

验证活动表面

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

​

使用 Swarm 进行代理分发

​

技术导览

​

运行状态

​

范围

​

术语

• Code mode：OpenClaw 运行时模式，会隐藏与目录兼容的模型 工具，并暴露 exec、wait，以及必需的仅直接使用工具。
• Guest runtime：执行模型代码的 QuickJS-WASI JavaScript VM。
• Host bridge：从 guest 代码返回到 OpenClaw 的狭窄、兼容 JSON 的回调接口。
• Catalog：在常规工具 策略、插件、MCP 和客户端工具解析之后，按运行范围确定的有效工具列表。
• Nested tool call：通过主机 桥从 guest 代码发起的工具调用。
• Snapshot：保存的 QuickJS-WASI VM 序列化状态，使 wait 能够继续一个已挂起的 code-mode 运行。

​

配置

​

自动按模型启用

• "auto"（默认）：仅当运行所用模型在其提供方目录中被标记为首选代码模式执行者时，代码模式才会启用。
• false：所有运行都关闭代码模式。
• true：无论模型如何，所有支持工具的运行都会启用代码模式。

​

compat.codeMode 目录标志

• "preferred"：该模型能够稳定编写简短的编排程序，并受益于紧凑的代码模式界面；"auto" 会启用代码模式。
• "capable"（或缺省）：该模型在强制设置 enabled: true 时可以运行代码模式，但 "auto" 会保留普通工具暴露方式。

​

已随版本发布的首选模型

​

由多个提供方同时提供的模型

​

何时选择启用

​

激活

1. 解析 agent、模型、provider、sandbox、channel、sender 和 run policy。
2. 构建有效的 OpenClaw 工具列表，添加符合条件的插件、MCP 和 客户端工具。
3. 应用允许/拒绝策略。
4. 如果 tools.codeMode.enabled 为 false，或者其值为 "auto" 且该运行的模型 不是目录首选，则继续按正常方式暴露工具。
5. 如果已启用且该运行的工具处于活动状态，则保留必需的仅直连工具，并将每个目录中符合条件的有效工具注册到代码模式目录中。
6. 从模型可见列表中移除已编目工具；将 exec 和 wait 与保留的仅直连工具一并添加。

​

模型可见工具

​

exec

type CodeModeExecInput = {
  code?: string;
  command?: string;
  language?: "javascript" | "typescript";
};

• code 或 command 中必须有一个非空。
• code 是文档中面向模型的字段。
• command 作为 exec 兼容别名被接受，用于钩子策略和受信任的重写（OpenClaw 的正常 shell exec 工具也使用 command 字段）；当两者都存在时，值必须一致。
• language 默认为 "javascript"；schema 将其暴露为一个扁平字符串枚举（"javascript" | "typescript"），而不是 oneOf/anyOf 联合，因为某些提供方会拒绝这些结构。
• 如果 language 是 "typescript"，OpenClaw 会在执行前进行转译。
• exec 会拒绝 import、require、动态 import 以及模块加载器模式。
• exec 从不递归暴露普通 shell exec 实现。
• 外层代码模式 exec 钩子事件携带 toolKind: "code_mode_exec" 和 toolInputKind: "javascript" | "typescript"（在已知时），因此策略可以区分代码模式单元与共享同名工具的 shell 风格 exec 调用。

type CodeModeResult = CodeModeCompletedResult | CodeModeWaitingResult | CodeModeFailedResult;

type CodeModeCompletedResult = {
  status: "completed";
  value: unknown;
  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;
};

​

wait

type CodeModeWaitInput = {
  runId: string;
};

1. exec 会执行代码，直到完成、失败或挂起。
2. 在挂起时，OpenClaw 会为 QuickJS VM 生成快照，并记录待处理的主机工作。
3. 当待处理工作结束后，wait 会恢复 VM 快照，并通过稳定名称重新注册主机回调。
4. OpenClaw 会将嵌套工具结果送入恢复后的 VM，并清空 QuickJS 待处理任务。
5. wait 返回 completed、failed 或另一个 waiting 结果。

• runId 未知，或者其快照已经过期。
• 调用方不在与该挂起运行相同的运行/会话范围内。
• 对该 runId 已经有一个 wait 正在进行中。
• QuickJS-WASI 恢复失败。
• 继续执行将超过 maxOutputBytes 或 maxSnapshotBytes。

​

Guest 运行时 API

declare const ALL_TOOLS: ToolCatalogEntry[];
declare const tools: ToolCatalog;
declare const MCP: Record<string, unknown>;
declare const namespaces: Record<string, unknown>;

declare function text(value: unknown): void;
declare function json(value: unknown): void;
declare function yield_control(reason?: string): Promise<void>;

type ToolCatalogEntry = {
  id: string;
  name: string;
  label?: string;
  description: string;
  source: "openclaw" | "mcp" | "client";
  sourceName?: string;
  input: string;
  output?: string;
};

type ToolCatalogEntryWithSchema = ToolCatalogEntry & {
  parameters: unknown;
  outputSchema?: unknown;
};

type ToolCatalog = {
  search(query: string, options?: { limit?: number }): Promise<ToolCatalogEntry[]>;
  describe(id: string): Promise<ToolCatalogEntryWithSchema>;
  callValue(id: string, input?: unknown): Promise<unknown>;
  call(id: string, input?: unknown): Promise<unknown>;
  [safeToolName: string]: unknown;
};

const available = await nodes.list();
const node = await nodes.get(available[0].id);
const status = await node.invoke("device.status");

const files = await tools.search("read local file");
const fileRead = await tools.describe(files[0].id);
const content = await tools.callValue(fileRead.id, { path: "README.md" });

// 如果隐藏目录中有一个无歧义的 `web_search` 条目：
const hits = await tools.web_search({ query: "OpenClaw 代码模式" });

​

已声明的输出契约

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

const Shipment = Type.Object(
  {
    id: Type.String(),
    paid: Type.Boolean(),
    tons: Type.Number(),
  },
  { additionalProperties: false },
);

export default defineToolPlugin({
  id: "shipping",
  name: "Shipping",
  description: "Shipment tools.",
  tools: (tool) => [
    tool({
      name: "shipping_list",
      description: "List shipments.",
      parameters: Type.Object({}),
      outputSchema: Type.Array(Shipment),
      execute: async () => loadShipments(),
    }),
  ],
});

const listed = await tools.conversations_list({ query: "build bot" });
const target = listed.conversations.find((item) => item.label === "Build bot");
if (!target) throw new Error("conversation not found");
return await tools.conversations_send({
  conversationRef: target.conversationRef,
  message: "Build finished.",
});

• 描述的是精确的、与 JSON 兼容的 details 值，而不是渲染后的 content 块或提供方信封。
• 包含每一种不抛异常的成功或错误变体。如果工具没有稳定的结构化结果，则省略 outputSchema。
• 对于完整的快速索引提示，请用 { additionalProperties: false } 关闭对象层级。开放式、过大或其他部分 schema 仍可通过 tools.describe(...) 获得，但不会启用单轮字段使用。
• OpenClaw 会先在运行工具前编译 schema，然后在正常工具钩子之后、目录调用返回之前验证最终的 details。无效 schema 不能运行工具；不匹配会失败且不会打印该值。
• 紧凑提示是确定性的且有界的。当紧凑提示不足时，tools.describe(...) 会暴露完整且可信的 schema。
• 已安装的插件代码本身就是受信任的本地代码。远程 MCP 和客户端元数据仍然是不受信任的，不能选择加入这些快速索引提示。

const files = await API.list("mcp");
const githubApi = await API.read("mcp/github.d.ts");

const issue = await MCP.github.createIssue({
  owner: "openclaw",
  repo: "openclaw",
  title: "调查网关日志",
});

const snapshot = await MCP.chromeDevtools.takeSnapshot({ output: "markdown" });
const resource = await MCP.docs.resources.read({ uri: "memo://one" });
const prompt = await MCP.docs.prompts.get({
  name: "brief",
  arguments: { topic: "release" },
});

type McpToolResult = {
  content?: unknown[];
  structuredContent?: unknown;
  isError?: boolean;
  [key: string]: unknown;
};

declare namespace MCP.github {
  /** 返回这个 TypeScript 风格的 API 头。 */
  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;

  /**
   * 创建一个 GitHub issue。
   * @param owner 仓库所有者
   * @param repo 仓库名称
   * @param title issue 标题
   */
  function createIssue(input: {
    owner: string;
    repo: string;
    title: string;
    body?: string;
  }): Promise<McpToolResult>;
}

​

输出 API

• text(value) 将人类可读的输出追加到 output 数组中。
• json(value) 在进行 JSON 兼容 序列化后追加一个结构化输出项。
• 来宾代码最终返回的值会在 completed 结果中成为 value。

type CodeModeOutput = { type: "text"; text: string } | { type: "json"; value: unknown };

​

工具目录

<source>:<owner>:<tool-name>

openclaw:core:message
openclaw:browser:browser_request
mcp:github:create_issue
client:app:select_file

​

工具搜索交互

• OpenClaw 不会将 tool_search_code、tool_search、tool_describe 或 tool_call 暴露为模型可见工具。
• 相同的目录编制思路会移入 guest 运行时内部。
• guest 运行时会接收紧凑的 ALL_TOOLS 元数据，以及用于非 MCP 工具的 search/describe/call 辅助函数。
• MCP 调用使用生成的 MCP 命名空间及其 $api() 标头，而不是 tools.call(...)。
• 嵌套调用会通过与 Tool Search 相同的 OpenClaw 执行器路径进行分发。

​

工具名称和冲突

• 如果策略允许，tools.call("openclaw:core:exec", input) 可以调用 shell exec 工具。
• 只有当 shell exec 目录条目有一个无歧义的安全名称时，才会安装 tools.exec(...)。
• code-mode 的 exec 工具绝不会通过 tools 递归可用。

​

嵌套工具执行

​

运行和快照生命周期

• waiting 结果会存储 QuickJS 快照、待处理的桥接请求，以及 作用域元数据（代理运行 id、会话 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 关闭时被丢弃（没有任何内容会在重启后保留：这是短暂的运行时状态）。
• 对于只读工作，exec 可以设置 restartSafe: true。随后 OpenClaw 会在执行前拒绝任何会产生副作用的目录和命名空间工具调用，并 将挂起结果标记为可重放安全。如果重启中断了 wait， 重启恢复 会从转录内容而不是从 进程本地快照重建该轮执行。恢复轮本身仍然仅限于经过审计的只读核心工具和明确可重放安全的插件工具。
• OpenClaw 会限制每个进程中同时挂起的运行数量（64），并且会拒绝超过该上限的新挂起，提示 too many suspended code mode runs.。

​

QuickJS-WASI 运行时

​

TypeScript

​

安全边界

• 在主事件循环之外、于 worker 线程中运行 QuickJS-WASI
• 将 quickjs-wasi 作为直接依赖加载，而不是通过 Codex 或传递依赖加载
• 访客环境中不提供文件系统、网络、子进程、模块导入、环境变量或宿主全局对象
• 使用 QuickJS 内存和中断限制，以及父进程级别的墙钟超时
• 强制执行输出、快照、日志和待调用次数上限
• 通过窄 JSON 适配器序列化宿主桥接值
• 将宿主错误转换为普通的访客错误，绝不返回宿主运行域对象
• 在超时、中止、会话结束或过期时删除快照
• 拒绝对 exec、wait 和 Tool Search 控制工具的递归访问
• 防止便利名称冲突覆盖目录助手

​

错误代码

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

​

遥测

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

​

调试

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

​

实现布局

• 配置契约：tools.codeMode
• 目录构建器：有效工具，用于压缩条目和 id 映射
• 模型表面适配器：用控制／直接工具替换可见工具
• QuickJS-WASI 运行时适配器：加载、求值、快照、恢复、释放
• 工作线程监管器：超时、终止、崩溃隔离
• 桥接适配器：JSON 安全的宿主回调和结果传递
• TypeScript 转换适配器
• 快照存储：TTL、大小上限、运行／会话作用域
• 嵌套工具调用的轨迹投影
• 遥测计数器和诊断

​

验证清单

• disabled 配置不会改变现有工具暴露
• 不带 enabled: true 的对象配置会使代码模式保持禁用
• 启用的配置在运行期间工具处于激活状态时，会向模型暴露 exec、wait，以及仅必需的 direct-only 工具
• 原始无工具运行、disableTools 和空允许列表不会触发代码模式载荷强制
• 所有目录中符合条件的有效非 MCP 工具都出现在 ALL_TOOLS 中
• direct-only 工具保持对模型可见，但不会出现在 ALL_TOOLS 中
• 被拒绝的工具不会出现在 ALL_TOOLS 中
• tools.search、tools.describe、tools.callValue 和 tools.call 能用于 OpenClaw 工具
• API.list("mcp") 和 API.read("mcp/<server>.d.ts") 在没有桥接/工具调用的情况下暴露 TypeScript 风格的 MCP 声明
• MCP 命名空间 $api() 作为架构的内联回退仍然可用
• 对于可见的 MCP 工具，MCP 命名空间调用可以使用一个对象输入正常工作，而直接的 MCP 目录项不会出现在 tools.* 中
• Tool Search 控制工具对模型表面和隐藏目录都不可见
• 嵌套调用会保留审批和钩子行为
• shell exec 对模型隐藏，但在允许时可按目录 id 调用
• 递归的代码模式 exec 和 wait 不能从 guest 代码中调用
• TypeScript 输入会被转换并求值，而在禁用或仅 JavaScript 路径上不会加载 TypeScript
• import、require、文件系统、网络和环境访问会失败
• 无限循环会超时，且不能阻塞 Gateway
• 内存上限失败会终止 guest VM
• 对于已完成和已挂起的调用，输出和快照上限都会被强制执行
• wait 会恢复一个挂起的快照并返回最终值
• 过期、已中止、错误会话和未知的 runId 值会失败
• 转录回放和持久化会保留代码模式控制调用
• 转录和遥测会清晰显示嵌套工具调用

​

端到端测试计划

1. 启动一个 tools.codeMode.enabled: false 的 Gateway。
2. 使用一个小型直接工具集发送一次 agent turn。
3. 断言模型可见的工具未发生变化。
4. 以 tools.codeMode.enabled: true 重启。
5. 使用 OpenClaw、plugin、MCP 和 client 测试工具发送一次 agent turn。
6. 断言模型可见的工具列表为 exec、wait，外加仅配置的 direct-only 工具。
7. 在 exec 中，读取 ALL_TOOLS 并断言目录可用的有效测试 工具存在，而 direct-only 工具不存在。
8. 在 exec 中，通过 tools.search、tools.describe 和 tools.callValue （或原始 tools.call）调用 OpenClaw/plugin/client 工具。
9. 在 exec 中，调用 API.list("mcp") 和 API.read("mcp/<server>.d.ts")， 并断言声明文件描述了可见的 MCP 工具。
10. 在 exec 中，通过 MCP.<server>.<tool>({ ...input }) 调用 MCP 工具，并 断言直接 MCP 目录条目不出现在 ALL_TOOLS 和 tools.* 中。
11. 断言被拒绝的工具不存在，并且无法通过猜测 id 来调用。
12. 启动一个嵌套工具调用，该调用在 exec 返回 waiting 后才解析完成。
13. 调用 wait，并断言恢复的 VM 收到了工具结果。
14. 断言最终答案包含在恢复后生成的输出。
15. 断言超时、abort 和快照过期会清理运行时状态。
16. 导出轨迹，并断言嵌套调用在父级代码模式调用下可见。

​

相关内容

• Swarm 用于从 Code Mode 脚本进行扇出式代理编排
• 工具搜索
• 代理运行时
• Exec 工具
• 代码执行