openclaw
Version:
Multi-channel AI gateway with extensible messaging integrations
198 lines (172 loc) • 13.1 kB
Markdown
---
summary: "Index of the OpenClaw Code Mode documentation, one page per reader job"
title: "Code Mode"
sidebarTitle: "Code Mode"
doc-schema-version: 1
read_when:
- You want to enable OpenClaw Code Mode for an agent run
- You need to explain why Code Mode is different from Codex Code Mode
- You are looking for the Code Mode page that matches your task
---
Code mode is an experimental OpenClaw agent-runtime feature. When
enabled, the model no longer sees every enabled tool schema. Instead, it sees
`exec`, `wait`, and any direct-only tool whose structured result cannot cross
the JSON-only guest bridge. The model writes a small JavaScript
program that searches, describes, and calls the hidden tool catalog.
TypeScript-style signatures describe the available tools; executable cells use
plain JavaScript without type annotations.
<Note>
When `tools.codeMode` is absent, OpenClaw uses the `"auto"` tier and engages
Code Mode only for models marked as preferred Code Mode performers. An authored
object without `enabled` remains off, as do `false` and `{ enabled: false }`.
Agent and model overrides take precedence. Use **Settings → Agents & Tools →
Labs → Code Mode** to choose the global setting.
</Note>
This page documents OpenClaw Code Mode, not Codex Code Mode. The two features
share a name and the same control-tool names (`exec`, `wait`), but they are
separate implementations:
- Codex Code Mode runs inside the Codex coding harness. Its `exec` tool is a
freeform-grammar tool: the model writes raw JavaScript source (optionally
prefixed by a `// @exec: {...}` pragma line for execution options), executed
in Codex's in-process V8 Code Mode runtime.
- OpenClaw Code Mode runs in the generic OpenClaw agent runtime and is
enabled through global, agent, or model activation settings. Its `exec`
tool takes a JSON `{ title, code }` payload, executed by the selected Node or
QuickJS executor.
Both are JavaScript execution surfaces, not shell-command surfaces. Treat them
as independent, differently-implemented features that happen to expose
identically-named `exec`/`wait` tools.
In OpenClaw Code Mode, `command` is a JavaScript alias for
`code`, not a shell command. For shell or file operations, call the appropriate
async tool global from guest JavaScript. Recognizable shell
commands are rejected before guest execution with actionable
`invalid_input` guidance.
JavaScript executes outside the Gateway's main event loop. Node is the default
executor and uses `node:vm` in a worker thread for trusted execution; it is not
a security boundary. The bundled QuickJS executor provides hardened guest
isolation. Both use the same tool bridge, where permissions, approvals, and
session ownership remain with the Gateway. See
[Code Mode executors](/tools/code-mode/executors) before enabling it.
This page is an index. Code Mode is documented on nine pages, one per reader
job. Open the page that matches your task.
| Page | Read it when |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [Code Mode quickstart](/tools/code-mode/quickstart) | You want to turn Code Mode on, override one model, and recover from tool errors. |
| [Code Mode executors](/tools/code-mode/executors) | You want to choose Node or QuickJS and understand their security boundaries. |
| [Code Mode configuration](/tools/code-mode/configuration) | You need the configuration fields, the preferred-model list, and activation order. |
## What it does
- The model-visible tool list becomes `exec`, `wait`, plus any direct-only tool
such as `computer` or the native-vision `view_image` loader whose image result
cannot survive the guest bridge.
- `exec` evaluates model-generated JavaScript in the selected executor's worker
thread.
- Every catalog-eligible enabled non-MCP tool (OpenClaw core, plugin, client) is
hidden as a standalone model tool and exposed inside the guest program as an
async global function. MCP stays under the `MCP` namespace.
- The `exec` description carries a bounded quick index of final callable names,
compact input hints, and compact declared output hints when a
trusted tool provides an output schema. It omits descriptions, full schemas,
MCP entries, and overflow entries. Callable `catalog.search(...)` results are
the fallback. Input hints retain integer and numeric bounds as comments, such
as `offset?: number /* integer, >= 1 */`. Other validation details remain in
the full schema available through `describe()`. These hints do not change
tool validation or output contracts. Core file and shell tool signatures stay
first in the bounded index, followed by tools with declared output hints, so
catalog growth does not hide their input argument names.
- Guest code calls globals directly or searches the hidden catalog for callable
handles. A handle exposes bounded metadata and `describe()`, but never the
exact internal catalog id. Calls use the same execution path as normal agent
turns (policy, approvals, hooks, telemetry all still apply).
- MCP tools are grouped under the `MCP` namespace and discoverable by task
through `catalog.search(...)`. MCP search handles call the same namespace
path and point to its exact declarations.
- `wait` resumes a suspended Code Mode run when nested tool calls are still
pending.
Call `wait` only when the outer Code Mode result has `status: "waiting"`, using
its top-level `runId`. A completed cell can return a background shell operation
with its own `sessionId` inside `value`. Use the enabled process-control tool
inside a new `exec` to poll that operation. Its `sessionId` is not a Code Mode
run ID.
Code mode changes the model-facing orchestration surface only. It does not
replace tools, plugin tools, MCP tools, auth, approval policy, channel
behavior, or model selection.
## Why use it
- Smaller prompt surface: providers get two control tools, a bounded native-tool
index, and only the few required direct tools instead of dozens or hundreds
of full tool schemas.
- Better orchestration: the model can use loops, joins, small transforms,
conditional logic, and parallel nested tool calls inside one code cell.
- Fewer model round trips: a declared output contract lets the model call and
transform a tool result in one `exec`. Unknown outputs remain raw-first.
- Provider neutral: works for OpenClaw, plugin, MCP, and client tools without
depending on provider-native code execution.
- Fails closed: if Code Mode is enabled but the selected executor is
unavailable, the run fails instead of silently falling back to broad direct
tool exposure.
Most useful for agents with a large enabled tool catalog, or workflows where
the model needs to search, combine, and call several tools before answering.
Keep direct tool exposure for a small catalog or a model that does not reliably
write short programs. Use [Tool Search](/tools/tool-search) when you want a
compact catalog but prefer structured search/describe/call controls instead of
JavaScript cells.
## Technical tour
These pages cover the runtime contract and implementation details,
for maintainers, plugin authors debugging tool exposure, and operators
validating high-risk deployments.
| Page | Read it when |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [Code Mode tool surface](/tools/code-mode/tool-surface) | You need the `exec` and `wait` contracts, the hidden catalog, and collisions. |
| [Code Mode guest API](/tools/code-mode/guest-api) | You are writing guest code and need its globals, handles, and MCP namespaces. |
| [Code Mode output](/tools/code-mode/output) | You need declared output contracts or the guest output API. |
| [Code Mode internals](/tools/code-mode/internals) | You need scope, terms, nested execution, snapshots, or the security boundary. |
| [Code Mode troubleshooting](/tools/code-mode/troubleshooting) | You need error codes, telemetry fields, or the debug environment variables. |
| [Code Mode maintainer notes](/tools/code-mode/maintainers) | You are changing Code Mode source, validating it, or writing E2E coverage. |
## Where each section moved
Every section heading from the previous single-page version keeps its anchor
here, so an existing link such as `/tools/code-mode#guest-runtime-api` still
resolves. Each entry points at the page that now holds the content.
- <a id="quickstart" />[Quickstart](/tools/code-mode/quickstart)
- <a id="enable-code-mode" />[Enable code mode](/tools/code-mode/quickstart#enable-code-mode)
- <a id="override-one-model" />[Override one model](/tools/code-mode/quickstart#override-one-model)
- <a id="what-the-model-does" />[What the model does](/tools/code-mode/quickstart#what-the-model-does)
- <a id="recover-from-tool-errors" />[Recover from tool errors](/tools/code-mode/quickstart#recover-from-tool-errors)
- <a id="verify-the-active-surface" />[Verify the active surface](/tools/code-mode/quickstart#verify-the-active-surface)
- <a id="use-swarm-for-agent-fan-out" />[Use Swarm for agent fan-out](/tools/code-mode/quickstart#use-swarm-for-agent-fan-out)
- <a id="configuration" />[Configuration](/tools/code-mode/configuration#configuration)
- <a id="automatic-per-model-activation" />[Automatic per-model activation](/tools/code-mode/configuration#automatic-per-model-activation)
- <a id="the-compat.codemode-catalog-flag" /><a id="the-compat-codemode-catalog-flag" />[The compat catalog flag](/tools/code-mode/configuration#the-compat-codemode-catalog-flag)
- <a id="shipped-preferred-models" />[Shipped preferred models](/tools/code-mode/configuration#shipped-preferred-models)
- <a id="models-shipped-by-more-than-one-provider" />[Models shipped by more than one provider](/tools/code-mode/configuration#models-shipped-by-more-than-one-provider)
- <a id="choosing-when-to-enable" />[Choosing when to enable](/tools/code-mode/configuration#choosing-when-to-enable)
- <a id="activation" />[Activation](/tools/code-mode/configuration#activation)
- <a id="model-visible-tools" />[Model-visible tools](/tools/code-mode/tool-surface#model-visible-tools)
- <a id="exec" />[The exec tool](/tools/code-mode/tool-surface#exec)
- <a id="source-in-session-history" />[Source in session history](/tools/code-mode/tool-surface#source-in-session-history)
- <a id="wait" />[The wait tool](/tools/code-mode/tool-surface#wait)
- <a id="tool-catalog" />[Tool catalog](/tools/code-mode/tool-surface#tool-catalog)
- <a id="tool-search-interaction" />[Tool Search interaction](/tools/code-mode/tool-surface#tool-search-interaction)
- <a id="tool-names-and-collisions" />[Tool names and collisions](/tools/code-mode/tool-surface#tool-names-and-collisions)
- <a id="guest-runtime-api" />[Guest runtime API](/tools/code-mode/guest-api#guest-runtime-api)
- <a id="reading-paginated-file-data" />[Reading paginated file data](/tools/code-mode/guest-api#reading-paginated-file-data)
- <a id="declared-output-contracts" />[Declared output contracts](/tools/code-mode/output#declared-output-contracts)
- <a id="output-api" />[Output API](/tools/code-mode/output#output-api)
- <a id="runtime-status" />[Runtime status](/tools/code-mode/internals#runtime-status)
- <a id="scope" />[Scope](/tools/code-mode/internals#scope)
- <a id="terms" />[Terms](/tools/code-mode/internals#terms)
- <a id="nested-tool-execution" />[Nested tool execution](/tools/code-mode/internals#nested-tool-execution)
- <a id="run-and-snapshot-lifecycle" />[Run and snapshot lifecycle](/tools/code-mode/internals#run-and-snapshot-lifecycle)
- <a id="quickjs-wasi-runtime" />[QuickJS-WASI runtime](/tools/code-mode/internals#quickjs-wasi-runtime)
- <a id="typescript" />[TypeScript](/tools/code-mode/internals#typescript)
- <a id="security-boundary" />[Security boundary](/tools/code-mode/internals#security-boundary)
- <a id="error-codes" />[Error codes](/tools/code-mode/troubleshooting#error-codes)
- <a id="telemetry" />[Telemetry](/tools/code-mode/troubleshooting#telemetry)
- <a id="debugging" />[Debugging](/tools/code-mode/troubleshooting#debugging)
- <a id="implementation-layout" />[Implementation layout](/tools/code-mode/maintainers#implementation-layout)
- <a id="validation-checklist" />[Validation checklist](/tools/code-mode/maintainers#validation-checklist)
- <a id="e2e-test-plan" />[E2E test plan](/tools/code-mode/maintainers#e2e-test-plan)
## Related
- [Swarm](/tools/swarm) for fan-out agent orchestration from Code Mode scripts
- [Tool Search](/tools/tool-search)
- [Agent runtimes](/concepts/agent-runtimes)
- [Exec tool](/tools/exec)
- [Code execution](/tools/code-execution)