代码模式

• Codex Code Mode 在 Codex coding harness 内运行。它的 exec 工具是一个 freeform-grammar 工具：模型编写原始 JavaScript 源码（可选地在前面加上一行 // @exec: {...} pragma 来提供执行选项），并在 Deno/V8 运行时中执行。
• OpenClaw 代码模式在通用 OpenClaw agent runtime 中运行，除非配置了 tools.codeMode.enabled: true，否则处于禁用状态。它的 exec 工具接受一个 JSON { code, language } 载荷，并在 QuickJS-WASI worker 中执行。

​

它的作用

• 模型可见的工具列表会精确变为 exec 和 wait。
• exec 会在隔离的 QuickJS-WASI worker 线程中求值模型生成的 JavaScript 或 TypeScript。
• 其他所有已启用工具（OpenClaw core、插件、MCP、客户端）都会从模型提示中隐藏，并通过 ALL_TOOLS 和 tools 暴露给 guest 程序内部。
• Guest 代码会搜索隐藏目录、描述某个工具的 schema，并通过普通 agent 轮次使用的同一执行路径调用工具（策略、审批、钩子、telemetry 仍然全部适用）。
• MCP 工具会归组到 MCP 命名空间下；在代码模式中，这是调用它们的唯一受支持方式。
• 当嵌套工具调用仍处于 pending 状态时，wait 会恢复一个已挂起的代码模式运行。

​

为什么使用它

• 更小的提示面：提供商只获得两个控制工具，而不是几十或上百个完整工具 schema。
• 更好的编排：模型可以在一个 code cell 内使用循环、join、小型转换、条件逻辑和并行嵌套工具调用。
• 提供商中立：适用于 OpenClaw、插件、MCP 和客户端工具，不依赖提供商原生代码执行。
• 失败关闭：如果启用了代码模式但 QuickJS-WASI 运行时不可用，运行会失败，而不是静默回退到宽泛的直接工具暴露。

​

启用它

{
  tools: {
    codeMode: {
      enabled: true,
    },
  },
}

{
  tools: {
    codeMode: true,
  },
}

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

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

​

技术导览

​

运行时状态

​

范围

​

术语

• 代码模式：OpenClaw 运行时模式，隐藏普通模型工具，只暴露 exec 和 wait。
• Guest 运行时：用于求值模型代码的 QuickJS-WASI JavaScript VM。
• Host bridge：从 guest 代码回到 OpenClaw 的窄 JSON 兼容回调表面。
• 目录：在正常工具策略、插件、MCP 和客户端工具解析之后，按运行作用域形成的有效工具列表。
• 嵌套工具调用：通过 host bridge 从 guest 代码发起的工具调用。
• Snapshot：序列化的 QuickJS-WASI VM 状态，用于让 wait 继续一个已挂起的代码模式运行。

​

配置

​

激活

1. 解析智能体、模型、提供商、沙箱、渠道、sender 和运行策略。
2. 构建有效 OpenClaw 工具列表，添加符合条件的插件、MCP 和客户端工具。
3. 应用 allow/deny 策略。
4. 如果 tools.codeMode.enabled 为 false，则继续使用普通工具暴露。
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、dynamic import 和 module-loader 模式。
• exec 绝不会递归暴露普通 shell exec 实现。
• 外层代码模式 exec 钩子事件携带 toolKind: "code_mode_exec" 和 toolInputKind: "javascript" | "typescript"（如已知），因此策略可以区分代码模式 cell 与共享同一工具名的 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。

​

客体运行时 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;
};

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

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

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

// If the hidden catalog has an unambiguous `web_search` entry:
const hits = await tools.web_search({ query: "OpenClaw code mode" });

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: "Investigate gateway logs",
});

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 {
  /** Return this TypeScript-style API header. */
  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;

  /**
   * Create a GitHub issue.
   * @param owner Repository owner
   * @param repo Repository name
   * @param title Issue title
   */
  function createIssue(input: {
    owner: string;
    repo: string;
    title: string;
    body?: string;
  }): Promise<McpToolResult>;
}

​

内部命名空间

const open = await Issues.list({ state: "open" });
const alsoOpen = await namespaces.Issues.list({ state: "open" });
return { count: open.length, alsoCount: alsoOpen.length };

​

注册表生命周期

1. 受信任的加载器调用 registerCodeModeNamespaceForPlugin(pluginId, registration)。
2. 代码模式为该运行创建隐藏的 ToolSearchRuntime，并读取其运行范围目录。
3. createCodeModeNamespaceRuntime(ctx, catalog) 只保留那些 requiredToolNames 全部可见且归同一个 pluginId 所有的注册。
4. 每个可见命名空间都会为当前运行调用 createScope(ctx)，接收 agentId、sessionKey、sessionId、runId、配置和中止状态等运行上下文。
5. 作用域数据会被序列化为普通描述符，并作为直接全局变量和 namespaces.<globalName> 注入 QuickJS。
6. 客体调用会通过 worker 桥接挂起，在主机上解析命名空间路径，将调用映射到已声明的、由插件拥有的目录工具，并通过 ToolSearchRuntime.callExactId 执行该工具。
7. 已就绪的命名空间桥接调用会在活跃的 exec/wait 调用内自动耗尽；如果命名空间工作在超时时仍然待处理，或客体显式让出控制权，则 wait 稍后会恢复同一个命名空间运行时。
8. 插件回滚或卸载会调用 clearCodeModeNamespacesForPlugin(pluginId)，使过期全局变量不会在插件加载失败后继续存在。

​

注册结构

import {
  createCodeModeNamespaceTool,
  registerCodeModeNamespaceForPlugin,
} from "../agents/code-mode-namespaces.js";

const pluginId = "github";

registerCodeModeNamespaceForPlugin(pluginId, {
  id: "github-issues",
  globalName: "Issues",
  description: "GitHub issue helpers for the current repository.",
  requiredToolNames: ["github_list_issues", "github_update_issue"],
  prompt: "Use Issues.list(params) and Issues.update(number, patch).",
  createScope: (ctx) => ({
    repository: ctx.config,
    list: createCodeModeNamespaceTool("github_list_issues", ([params]) => params ?? {}),
    update: createCodeModeNamespaceTool("github_update_issue", ([number, patch]) => ({
      number,
      patch,
    })),
  }),
});

createScope: () => ({
  // Wrong: this bypasses the catalog tool lifecycle and will be rejected.
  list: async () => githubClient.listIssues(),
});

​

所有权和可见性

• 每个必需工具都必须存在于运行目录中
• 每个必需工具都必须有 sourceName === pluginId
• 当任何必需工具缺失或归另一个插件所有时，该命名空间会被隐藏
• 每个可调用路径只能指向 requiredToolNames 中命名的工具

​

作用域序列化规则

• 原始函数
• 循环对象图
• 不安全的路径段：__proto__、constructor、prototype、空键，或包含内部路径分隔符的键
• 不是 JavaScript 标识符的 globalName 值
• 与内置代码模式全局变量发生冲突的 globalName，例如 tools、namespaces、text、json、yield_control、MCP、API、ALL_TOOLS 或 __openclaw*

​

提示词

{
  description: "Fiction production service helpers.",
  prompt:
    "Use Fictions.riskAudit(), Fictions.promoteIfReady(id, status), and Fictions.unpaidOver(amount).",
}

​

清理

clearCodeModeNamespacesForPlugin(pluginId);

​

测试检查清单

• 仅当后端工具可见时，命名空间提示文本才会出现
• 来自另一个 sourceName 的同名工具不会暴露该命名空间
• 原始作用域函数会被拒绝
• 伪造的命名空间 ID 和伪造路径会被拒绝
• 可调用路径不能指向未声明的工具
• 嵌套对象和共享引用能够正确序列化
• 命名空间调用通过目录工具执行，并返回 JSON 安全的详细信息
• 客体代码可以捕获失败
• 挂起的命名空间调用通过 wait 恢复
• 插件回滚会清除拥有方命名空间注册

​

输出 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 暴露为模型可见工具。
• 相同的目录化思路会移入客体运行时内部。
• 客体运行时会接收紧凑的 ALL_TOOLS 元数据，以及用于非 MCP 工具的搜索/描述/调用辅助函数。
• MCP 调用使用生成的 MCP 命名空间及其 $api() 标头，而不是 tools.call(...)。
• 嵌套调用通过工具搜索使用的同一个 OpenClaw 执行器路径分发。

​

工具名称和冲突

• 如果策略允许，tools.call("openclaw:core:exec", input) 可以调用 shell exec 工具。
• 仅当 shell exec 目录条目拥有明确的安全名称时，才会安装 tools.exec(...)。
• 代码模式 exec 工具永远不能通过 tools 递归访问。

​

嵌套工具执行

​

运行和快照生命周期

• waiting 结果会存储 QuickJS 快照、待处理桥接请求和作用域元数据（智能体运行 ID、会话 ID/密钥），直到 wait 恢复它或它过期。
• 过期、错误会话、错误运行，以及未知/已在恢复中的 runId 值不会产生单独的终端状态；它们会表现为 failed 结果（code: "invalid_input"），并带有类似 code mode run is unavailable or expired. 或 code mode run belongs to a different session. 的消息。
• 运行的快照会在它进入 completed 或 failed 后立即从映射中移除，或在 Gateway 网关关闭时丢弃（按设计，重启后不会保留任何内容：这是瞬态运行时状态）。
• OpenClaw 会限制每个进程中并发挂起运行的数量（64），并在超过该上限时拒绝新的挂起，错误为 too many suspended code mode runs.。

​

QuickJS-WASI 运行时

​

TypeScript

​

安全边界

• 在主事件循环之外、工作线程中运行 QuickJS-WASI
• 将 quickjs-wasi 作为直接依赖加载，而不是通过 Codex 或传递包加载
• 客体中没有文件系统、网络、子进程、模块导入、环境变量或主机全局对象
• 使用 QuickJS 内存和中断限制，以及父进程墙钟超时
• 强制执行输出、快照、日志和待处理调用上限
• 通过狭窄的 JSON 适配器序列化主机桥接值
• 将主机错误转换为普通客体错误，绝不转换为主机 realm 对象
• 在超时、中止、会话结束或过期时丢弃快照
• 拒绝递归访问 exec、wait 和工具搜索控制工具
• 防止便利名称冲突遮蔽目录辅助函数

​

错误码

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

​

遥测

​

调试

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

​

实现布局

• 配置契约：tools.codeMode
• 目录构建器：将有效工具转换为紧凑条目和 ID 映射
• 模型表面适配器：将可见工具替换为 exec 和 wait
• QuickJS-WASI 运行时适配器：加载、求值、快照、恢复、释放
• 工作线程监督器：超时、中止、崩溃隔离
• 桥接适配器：JSON 安全的主机回调和结果交付
• TypeScript 转换适配器
• 快照存储：TTL、大小上限、运行/会话作用域
• 嵌套工具调用的轨迹投影
• 遥测计数器和诊断

​

验证检查清单

• 禁用配置会让现有工具暴露保持不变
• 没有 enabled: true 的对象配置会让代码模式保持禁用
• 启用配置后，当工具在本次运行中处于活动状态时，只向模型暴露 exec 和 wait
• 原始无工具运行、disableTools 和空允许列表不会触发代码模式 payload 强制校验
• 所有实际生效的非 MCP 工具都会出现在 ALL_TOOLS 中
• 被拒绝的工具不会出现在 ALL_TOOLS 中
• tools.search、tools.describe 和 tools.call 可用于 OpenClaw 工具
• API.list("mcp") 和 API.read("mcp/<server>.d.ts") 会暴露 TypeScript 风格的 MCP 声明，无需 bridge/tool 调用
• MCP 命名空间 $api() 仍可作为 schema 的内联回退使用
• 对于可见 MCP 工具，MCP 命名空间调用可使用一个对象输入；同时，直接 MCP 目录条目不会出现在 tools.* 中
• Tool Search 控制工具同时从模型表面和隐藏目录中隐藏
• 嵌套调用会保留审批和钩子行为
• shell exec 对模型隐藏，但在被允许时可通过目录 id 调用
• 递归代码模式 exec 和 wait 无法从 guest code 调用
• TypeScript 输入会被转换并求值，且在禁用路径或仅 JavaScript 路径上不会加载 TypeScript
• import、require、文件系统、网络和环境访问都会失败
• 无限循环会超时，且无法阻塞 Gateway 网关
• 内存上限失败会终止 guest VM
• 对已完成和已挂起的调用都会强制执行输出和快照上限
• wait 会恢复已挂起的快照并返回最终值
• 过期、已中止、错误会话和未知的 runId 值都会失败
• transcript replay 和持久化会保留代码模式控制调用
• transcript 和 telemetry 会清晰显示嵌套工具调用

​

E2E 测试计划

1. 启动一个配置为 tools.codeMode.enabled: false 的 Gateway 网关。
2. 使用一个小型直接工具集发送一个 agent 轮次。
3. 断言模型可见工具保持不变。
4. 使用 tools.codeMode.enabled: true 重启。
5. 使用 OpenClaw、插件、MCP 和客户端测试工具发送一个 agent 轮次。
6. 断言模型可见工具列表正好是 exec、wait。
7. 在 exec 中读取 ALL_TOOLS，并断言实际生效的测试工具存在。
8. 在 exec 中，通过 tools.search、tools.describe 和 tools.call 调用 OpenClaw/插件/客户端工具。
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. 断言超时、中止和快照过期会清理运行时状态。
16. 导出 trajectory，并断言嵌套调用在父代码模式调用下可见。

​

相关

• 工具搜索
• Agent Runtimes
• Exec 工具
• 代码执行