Code Mode configuration

Configuration

tools.codeMode.enabled sets the global activation default. It defaults to false, including when the Code Mode object configures other fields. Set true or "auto" explicitly, or use an agent or model override.

timeoutMs is a wall-clock budget per exec or wait call. Worker preparation, guest computation, and inline tool waits share that budget; approval waits pause it. The model-facing exec description includes the effective limit. Blocking guest computation that exhausts the budget fails with timeout. Unfinished tool calls can instead return waiting, so a later wait can resume them with a fresh call budget. Headless continuations also honor the exact worker-admission budget after queueing and initialization, alongside their configured slice limit and single headless wall-clock deadline. A checkpoint does not reset that wall deadline. When the shell exec tool is available, use it for heavier computation and keep guest JavaScript focused on coordinating tools and processing results.

If code mode is enabled but QuickJS-WASI cannot load, OpenClaw fails closed for that run; it does not silently expose normal tools as a fallback. This holds for true and for "auto" runs where the model resolves as preferred: an engaged run never silently falls back to broad direct tool exposure.

Automatic per-model activation

tools.codeMode.enabled accepts three values:

• false (default): code mode is off unless an agent or model override enables it.
• true: code mode engages for tool-capable runs unless an override disables it.
• "auto": code mode engages only when the run's model is flagged as a preferred code-mode performer in its provider catalog.

These values supply the default when no agent or model override takes precedence. "auto" uses catalog capability; an explicit per-model boolean bypasses that capability preference.

The compat.codeMode catalog flag

Provider catalogs can tier a model with compat.codeMode on its model entry, next to flags like compat.supportsTools:

• "preferred": the model reliably writes short orchestration programs and benefits from the compact code-mode surface; "auto" engages code mode.
• "capable" (or absent): the model can run code mode when forced with enabled: true, but "auto" keeps normal tool exposure.

Models without tool support cannot use code mode at all; there is no separate "unsupported" tier. The flag is capability metadata owned by the provider plugin's catalog; core only reads the generic compat field.

Shipped preferred models

Bundled provider catalogs currently flag these models as "preferred":

Everything else, including all Ollama-served local models, stays unflagged and keeps normal tool exposure under "auto".

Models shipped by more than one provider

Several vendors are reachable through more than one provider id: a subscription endpoint next to an API endpoint, or a gateway that resells another vendor's model. Because "auto" resolves the tier from whichever catalog served the run, two catalogs describing the same upstream model must not disagree by accident.

Every catalog row for a shared model therefore states its tier explicitly once any sibling row states one. Rows are matched on the vendor's own name for the weights, so a catalog that republishes a model under a namespaced id or different casing is matched automatically: novita/moonshotai/kimi-k3, nvidia/z-ai/glm-5.2, and together/deepseek-ai/DeepSeek-V4-Pro all group with the first-party rows without anyone declaring anything. Only genuinely different names need the manifest's upstreamModel marker, as the kimi catalog uses for moonshot/kimi-k3.

Reseller and aggregator catalogs such as baseten, deepinfra, github-copilot, gmi, novita, nvidia, ollama-cloud, opencode, opencode-go, qianfan, together, venice, and volcengine-plan currently declare "capable" for the models first-party catalogs flag "preferred": the preferred tier came from evaluations on the first-party endpoints, and those runs have not been repeated per reseller. Promoting one of those rows is a deliberate, evidence-backed change rather than an oversight.

For OpenAI models, the flag matters only when the run resolves to the OpenClaw embedded agent runtime. Default OpenAI routing uses the Codex-style harness surface, where OpenClaw code mode does not apply; the catalog flag never changes that routing decision.

Choosing when to enable

In A/B evaluations on the preferred models above, code mode reduced total token usage by roughly 30-50% at equal-or-better task pass rates, mostly by replacing many full tool schemas and per-tool round trips with one compact program surface. Models below the preferred tier showed no consistent win and sometimes regressed, which is why "auto" leaves them on direct tools.

Use "auto" when agents switch between models: strong models get the compact surface, weaker or local ones keep the exposure they handle best. Use true on an exact model entry when you have verified an unflagged model performs well with code mode. For open-weight or uncached serving where every prompt token is billed or recomputed, prefer enabling per model (via "auto" or an explicit model override) rather than globally, since the token savings depend on the model actually using the program surface well.

Activation

Code mode is evaluated after the effective tool policy is known and before the final model request is assembled:

1. Resolve the agent, model, provider, sandbox, channel, sender, and run policy.
2. Build the effective OpenClaw tool list, adding eligible plugin, MCP, and client tools.
3. Apply allow/deny policy.
4. Resolve activation using the agent and model precedence. If it is false, or "auto" and the run's model is not catalog-preferred, continue with normal tool exposure.
5. If enabled and tools are active for the run, retain required direct-only tools and register every catalog-eligible effective tool in the code-mode catalog.
6. Remove the cataloged tools from the model-visible list; add exec and wait alongside the retained direct-only tools.

Runs that intentionally have no tools (raw model calls, disableTools: true, or an empty tools.allow list) do not activate the code-mode surface even when tools.codeMode.enabled: true is configured. Code mode and OpenClaw Tool Search are mutually exclusive for a run; if code mode activates, Tool Search's compaction does not.

The code-mode catalog is run-scoped and must not leak tools from another agent, session, sender, or run.