跳转至

代码模式

Code Mode 是 OpenClaw 代理运行时的一个实验性功能。启用后，模型不再看到每个已启用工具的模式，取而代之的是 exec、wait，以及任何结构化结果无法穿越仅限 JSON 的访客桥接的 direct-only 工具。模型编写一个小型 JavaScript 程序，用于搜索、描述和调用隐藏的工具目录。TypeScript 风格的签名描述可用工具；可执行单元格使用不带类型注解的纯 JavaScript。

Note

当 tools.codeMode 缺失时，OpenClaw 使用 "auto" 级别，并仅对标记为首选 Code Mode 执行者的模型启用 Code Mode。 用户编写的对象如果未包含 enabled，则保持关闭；false 和 { enabled: false } 也是如此。 代理和模型级别的覆盖设置优先。使用 设置 → 代理与工具 → 实验室 → Code Mode 来选择全局设置。

本页介绍的是 OpenClaw Code Mode，而不是 Codex Code Mode。这两个功能同名，并使用相同的控制工具名称（exec、wait），但它们是独立的实现：

  • Codex Code Mode 在 Codex 编码框架内运行。其 exec 工具是一个自由格式语法工具：模型编写原始 JavaScript 源代码（可选地以 // @exec: {...} pragma 行开头，以指定执行选项），并在 Codex 的进程内 V8 Code Mode 运行时中执行。
  • OpenClaw Code Mode 在通用的 OpenClaw 代理运行时中运行，并通过全局、代理或模型激活设置启用。其 exec 工具接收 JSON { title, code } 负载，由所选的 Node 或 QuickJS 执行器执行。

两者都是 JavaScript 执行面，而不是 shell 命令面。请将它们视为独立的、实现方式不同的功能，它们只是恰好暴露了同名的 exec/wait 工具。

在 OpenClaw Code Mode 中，command 是 code 的 JavaScript 别名，而不是 shell 命令。对于 shell 或文件操作，请从访客 JavaScript 中调用适当的异步工具全局函数。可识别的 shell 命令会在访客执行之前被拒绝，并附上可操作的 invalid_input 指导。

JavaScript 在 Gateway 的主事件循环之外执行。Node 是默认执行器，在工作线程中使用 node:vm 进行可信执行；它不是安全边界。随附的 QuickJS 执行器提供强化的访客隔离。两者使用相同的工具桥接，其中权限、审批和会话所有权仍归 Gateway 所有。在启用之前，请参阅 Code Mode 执行器。

本页是一个索引。Code Mode 在九个页面中均有文档，每个页面针对一种读者任务。打开与你任务匹配的页面。

页面 阅读时机
Code Mode 快速入门 你想启用 Code Mode、覆盖单个模型，并从工具错误中恢复。
Code Mode 执行器 你想选择 Node 或 QuickJS，并了解它们的安全边界。
Code Mode 配置 你需要配置字段、首选模型列表和激活顺序。

功能说明

  • 模型可见的工具列表变为 exec、wait，再加上任何 direct-only 工具，例如 computer 或原生视觉 view_image 加载器——其图像结果无法在访客桥接中存续。
  • exec 在所选执行器的工作线程中执行模型生成的 JavaScript。
  • 每个符合目录收录条件的已启用非 MCP 工具（OpenClaw 核心、插件、客户端）都会作为独立的模型工具被隐藏，并在访客程序内部以异步全局函数的形式暴露。MCP 仍位于 MCP 命名空间下。
  • exec 的描述带有最终可调用名称的受限快速索引、紧凑的输入提示，以及紧凑的声明输出提示（当受信任工具提供输出模式时）。它省略描述、完整模式、MCP 条目和溢出条目。可调用的 catalog.search(...) 结果是后备方案。输入提示以注释形式保留整数和数值边界，例如 offset?: number /* integer, >= 1 */。其他验证细节保留在通过 describe() 可用的完整模式中。这些提示不会改变工具验证或输出契约。
  • 访客代码直接调用全局函数，或在隐藏目录中搜索可调用的句柄。句柄暴露受限的元数据和 describe()，但绝不暴露确切的内部目录 ID。调用使用与正常代理回合相同的执行路径（策略、审批、钩子、遥测仍然全部生效）。
  • MCP 工具分组在 MCP 命名空间下，可通过 catalog.search(...) 按任务发现。MCP 搜索句柄调用相同的命名空间路径，并指向 MCP 的确切声明。
  • 当嵌套工具调用仍处于挂起状态时，wait 会恢复被暂停的 Code Mode 运行。

仅当外部 Code Mode 结果的 status 为 "waiting" 时才调用 wait，并使用其顶层 runId。已完成的单元格可以在 value 内返回带有自身 sessionId 的后台 shell 操作。在新的 exec 中使用已启用的进程控制工具来轮询该操作。其 sessionId 不是 Code Mode 运行 ID。

Code Mode 仅改变面向模型的编排表面。它不会取代工具、插件工具、MCP 工具、认证、审批策略、频道行为或模型选择。

为什么使用它

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

对于拥有大量已启用工具目录的智能体，或模型在回答前需要搜索、组合并调用多个工具的工作流，最为有用。

对于小型目录，或无法可靠地编写短程序的模型，请保留直接工具暴露。当你希望拥有紧凑目录，但更倾向于使用结构化的 search/describe/call 控制而非 JavaScript 单元格时，请使用 Tool Search。

技术导览

这些页面涵盖运行时契约和实现细节，面向维护者、调试工具暴露的插件作者，以及验证高风险部署的运维人员。

页面 阅读时机
Code Mode 工具表面 你需要 exec 和 wait 契约、隐藏目录以及冲突。
Code Mode 来宾 API 你正在编写来宾代码，并需要其全局变量、句柄和 MCP 命名空间。
Code Mode 输出 你需要声明的输出契约或来宾输出 API。
Code Mode 内部机制 你需要作用域、术语、嵌套执行、快照或安全边界。
Code Mode 故障排查 你需要错误代码、遥测字段或调试环境变量。
Code Mode 维护者说明 你正在修改 Code Mode 源代码、验证它，或编写 E2E 覆盖。

各章节迁移位置

上一版单页版本中的每个章节标题都会在此保留其锚点，因此诸如 /tools/code-mode#guest-runtime-api 的现有链接仍然可以解析。每个条目都指向现在承载该内容的页面。

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