Code Mode quickstart

Enable code mode

The recommended path is Settings → Agents & Tools → Labs → Code Mode. The switch takes effect for future agent runs without restarting the Gateway and selects the "auto" tier.

To enable the same tier without the Control UI, set it in config:

{  tools: {    codeMode: "auto",  },}

To default code mode on for every tool-capable run, regardless of model:

{  tools: {    codeMode: true,  },}

Object form works too: tools.codeMode.enabled accepts the same false, true, and "auto" values. Code mode stays off when tools.codeMode is omitted, false, or an object without an explicit enabled value, unless an agent or model override enables it. Configuring limits or other Code Mode options does not enable it.

See Automatic per-model activation for the exact semantics and the shipped model list.

If you use sandboxed agents with configured MCP servers, also allow the bundled MCP plugin in the sandbox tool policy, for example tools.sandbox.tools.alsoAllow: ["bundle-mcp"]. See Configuration - tools and custom providers.

Set explicit limits for tighter bounds:

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

Override one model

Set codeMode: true or codeMode: false on an exact provider/model entry in agents.defaults.models. Omit codeMode to inherit the parent activation setting, including its "auto" behavior. The model field accepts only a boolean; "auto" belongs on the global or per-agent tools.codeMode setting. Wildcard rows such as "openai/*" may configure runtime policy, but cannot set codeMode; config validation rejects them instead of ignoring the override.

{  tools: { codeMode: "auto" },  agents: {    defaults: {      models: {        "openai/gpt-5.6-luna": {          agentRuntime: { id: "openclaw" },          codeMode: true,        },      },    },    entries: {      research: {        models: {          "openai/gpt-5.6-luna": { codeMode: false },        },      },    },  },}

The example enables Code Mode for this model except on the research agent. Activation resolves from the first explicit setting in this order:

1. agents.entries.<agent>.models["provider/model"].codeMode.
2. agents.entries.<agent>.tools.codeMode.enabled (or its boolean/"auto" shorthand).
3. agents.defaults.models["provider/model"].codeMode.
4. tools.codeMode.enabled (or its shorthand), defaulting to false.

In the Control UI, open Settings → Agents → Agent defaults, show Advanced settings, and find Models under Agent Defaults. Each model has a Code Mode selector beside its runtime: Default removes the override, On saves true, and Off saves false. For agent-specific overrides, expand Agent List, then the agent's Agent Model Overrides. Unsupported fields remain marked for Raw editing without hiding the supported settings beside them.

Overrides affect the selected model on future runs, including fallback models; they do not enable tools on a tool-free run or change runtime selection. The example separately selects agentRuntime.id: "openclaw" because OpenAI routes may otherwise use Codex. These settings do not control Codex native Code Mode. Model overrides change activation only; limits still come from the global and per-agent tools.codeMode options.

What the model does

For a tool with a declared output such as Array<{ id: string; paid: boolean; tons: number }>, one guest program can select, call, and transform it:

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

Declared output fields may feed later calls in that same exec; do not spend a second exec merely inspecting them.

When a quick-index line ends in -> ?, the output shape is unknown. The first exec must return the final async tool call unchanged. Do not feed the unknown value into guessed field-dependent logic in the same program. Observe the raw value, then use a later exec for dependent composition. This costs an extra model turn, but prevents the model from guessing field names.

Recover from tool errors

Nested tool failures are ordinary JavaScript errors. Guest code can catch them and inspect diagnostic fields: code identifies input_contract, output_contract, invalid_contract, invalid_input, or tool_error; location contains the original guest call-site frames when available. effectStatus remains "unknown": classification is not a dispatch-owner receipt and never grants retry permission. In particular, a tool can throw an input error after starting work. Guest code can return the information needed to choose the next action:

try {  return await terminal({ action: "list" });} catch (error) {  return { status: "unavailable", error: error.message };}

Await every tool call or handle its rejection explicitly. OpenClaw drains dispatched calls before completing a cell; an unhandled rejection, including one from an unawaited call or timer callback, fails the cell instead of silently reporting success. Handlers attached after a suspension still handle their original promises.

JavaScript syntax errors, TypeScript transform errors, and uncaught nested tool failures become failed exec or wait results. The model can read the error, correct its code, inspect the current state, and continue with the normal tool surface. A failed cell does not impose a separate recovery mode or mutation budget.

OpenClaw does not automatically replay a failed program. Earlier calls may have changed state, and a failed call may have partially applied. Inspect authoritative state before deciding what remains, and do not repeat completed actions. This also applies when wait resumes a suspended cell: its earlier calls belong to the same program.

Every subsequent call runs the ordinary hooks and approvals again. Consumed voice confirmations stay consumed; continuing after an error does not restore a grant. Cancellation, explicitly terminal tool outcomes, sandbox restrictions, approval requirements, and tool-policy denials retain their existing behavior.

Verify the active surface

To confirm the model payload shape while debugging, run the Gateway with targeted logging:

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

With code mode active, the logged model-facing tool names should be exec and wait. For the full redacted provider payload, add OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted for a short debugging session.

Use Swarm for agent fan-out

Swarm adds agents.run(), phase(), and log() guest globals for orchestrating concurrent sub-agents from Code Mode scripts. Swarm is enabled by default; Code Mode remains separately opt-in through "auto" or true. Use normal JavaScript control flow for fan-out, decision gates, and structured collection.

The Swarm globals, API.read("agents.d.ts"), and Swarm prompt hints appear only when Swarm is enabled and the native OpenClaw sessions_spawn tool is present in the Code Mode catalog and permitted by the run's execution allowlist. An MCP tool with the same name does not qualify. Code Mode waits for collector results internally, so agents.run() does not require the standalone agents_wait tool. Direct low-level Swarm use requires both tools allowed.

Set tools.swarm: false or tools.swarm.enabled: false to opt out, globally or under an agent's tools. Engaging Code Mode does not override that opt-out or grant access to tools denied by policy.