Code Mode 配置

配置¶

缺失的全局 tools.codeMode 设置默认为 "auto"。如果你编写一个代码模式对象，除非该对象显式设置 enabled，否则其激活状态保持关闭；这允许你在不启用该功能的情况下预配置执行器或限制设置。简写 false 也会禁用它。代理和模型覆盖保留其现有优先级。

代码模式仅执行 JavaScript。Doctor 和符合条件的 Gateway 启动迁移会从全局和按代理的代码模式配置中移除已弃用的 languages 设置，同时保留激活状态和限制。

默认 Node 执行器使用 node:vm 进行可信执行，而非安全隔离。选择 executor: "quickjs" 以使用内置的加固来宾运行时。代理级执行器设置会覆盖全局选择。有关安全、内存、等待和升级行为，请参阅 代码模式执行器。maxSnapshotBytes 限制 QuickJS VM 快照和共享的已保存结果配额；它不限制 Node 保留的活动上下文。

timeoutMs 是每次 exec 或 wait 调用的挂钟时间预算。工作进程准备、来宾计算和行内工具等待共享该预算；审批等待会暂停它。面向模型的 exec 描述包含有效限制。耗尽预算的阻塞式来宾计算会以 timeout 失败。未完成的工具调用也可以返回 waiting，因此后续的 wait 可以使用新的调用预算恢复它们。无头续接在排队和初始化之后也会遵守精确的工作进程准入预算，同时遵守其配置的切片限制和单个无头挂钟截止时间。检查点不会重置该挂钟截止时间。当 shell exec 工具可用时，请使用它执行更重的计算，并让来宾 JavaScript 专注于协调工具和处理结果。

如果代码模式已启用，但所选执行器无法加载，OpenClaw 会针对该运行失败关闭；它不会静默地暴露常规工具作为回退。这适用于 true 以及模型解析为优先的 "auto" 运行：已启用的运行绝不会静默回退到另一个执行器或广泛的直接工具暴露。

按模型自动启用¶

tools.codeMode.enabled 接受三个值：

• false：除非代理或模型覆盖启用它，否则代码模式关闭。
• true：对于具备工具能力的运行，除非覆盖禁用它，否则代码模式会启用。
• "auto"：仅当运行的模型在其提供商目录中被标记为优先代码模式表现者时，代码模式才会启用。

当全局设置完全缺失时，OpenClaw 的行为如同设置为 "auto"。未包含 enabled 的已编写对象行为如同 false。当没有代理或模型覆盖优先时，这些值提供默认值。"auto" 使用目录能力；显式的按模型布尔值会绕过该能力偏好。

compat.codeMode 目录标志¶

提供商目录可以在其模型条目上使用 compat.codeMode 对模型进行分级，位于 compat.supportsTools 等标志旁边：

• "preferred"：该模型能够可靠地编写简短的编排程序，并从紧凑的代码模式界面中受益；"auto" 会启用代码模式。
• "capable"（或缺失）：当通过 enabled: true 强制时，该模型可以运行代码模式，但 "auto" 保持常规工具暴露。

不支持工具的模型完全无法使用代码模式；没有单独的 “unsupported” 级别。该标志是由提供商插件目录拥有的能力元数据；核心只读取通用的 compat 字段。

内置优先模型¶

内置提供商目录当前将这些模型标记为 "preferred"：

claude-haiku-4-5 被标记为 "capable"：它仍然可以通过显式的 true 代理或模型设置保持可用，但 "auto" 不会启用它。

其他所有内容，包括所有由 Ollama 提供的本地模型，都保持未标记状态，并在 "auto" 下保持正常的工具暴露。

由多个提供商提供的模型¶

多个供应商可以通过多个提供商 ID 访问：一个订阅端点与一个 API 端点并列，或一个转售其他供应商模型的网关。由于 "auto" 会从提供该次运行的目录中解析层级，描述同一上游模型的两个目录不得意外不一致。

因此，对于共享模型，一旦任何同级行明确声明其层级，该共享模型的每个目录行都必须明确声明其层级。行根据供应商对权重使用的自身名称进行匹配，因此，以命名空间 ID 或不同大小写重新发布模型的目录会自动匹配：novita/moonshotai/kimi-k3、nvidia/z-ai/glm-5.2 和 together/deepseek-ai/DeepSeek-V4-Pro 都会与第一方行分组，而无需任何人声明任何内容。只有真正不同的名称才需要清单中的 upstreamModel 标记，正如 kimi 目录对 moonshot/kimi-k3 所做的那样。

诸如 baseten、deepinfra、github-copilot、gmi、novita、nvidia、ollama-cloud、opencode、opencode-go、qianfan、together、venice 和 volcengine-plan 之类的转售商和聚合器目录目前对第一方目录标记为 "preferred" 的模型声明 "capable"：首选层级来自第一方端点上的评估，并且这些运行未按每个转售商重复。提升其中一行是一个有意的、有证据支持的变化，而不是疏忽。

对于 OpenAI 模型，该标记仅在运行解析到 OpenClaw 嵌入式代理运行时时才重要。默认 OpenAI 路由使用 Codex 风格的 harness 界面，其中 OpenClaw 代码模式不适用；目录标记永远不会改变该路由决策。

选择何时启用¶

代码模式可以通过用紧凑目录和一个程序替换重复的完整工具架构和中间模型轮次来减少 token 使用。结果取决于模型和工作负载。在广泛强制启用之前，请在代表性任务上比较正确性以及完整的根及后代 token 使用量。

当代理在模型之间切换时，使用 "auto"：首选模型获得紧凑界面，而其他模型保持正常的工具暴露。当已验证某个未标记模型在代码模式下表现良好时，在精确的模型条目上使用 true。对于开放权重或未缓存的服务，其中每个 prompt token 都会被计费或重新计算，建议按模型启用（通过 "auto" 或显式模型覆盖），而不是全局启用，因为 token 节省取决于模型是否真正很好地使用了程序界面。

激活¶

代码模式在已知有效工具策略之后、组装最终模型请求之前进行评估：

1. 解析代理、模型、提供商、沙箱、通道、发送者和运行策略。
2. 构建有效的 OpenClaw 工具列表，添加符合条件的插件、MCP 和客户端工具。
3. 应用允许/拒绝策略。
4. 使用 代理和模型优先级 解析激活。如果为 false，或为 "auto" 且该次运行的模型不是目录首选，则继续正常的工具暴露。
5. 如果已启用且该次运行有活动工具，则保留必需的仅限直接工具，并将每个符合目录条件的有效工具注册到代码模式目录中。
6. 从模型可见列表中移除已编目工具；在保留的仅限直接工具旁边添加 exec 和 wait。

故意没有工具的运行（原始模型调用、disableTools: true 或空的 tools.allow 列表）即使配置了 tools.codeMode.enabled: true，也不会激活代码模式界面。代码模式和 OpenClaw Tool Search 对于一次运行是互斥的；如果代码模式激活，Tool Search 的压缩不会激活。

代码模式目录是运行范围的，并且不得泄露来自其他代理、会话、发送者或运行的工具。