openclaw
Version:
Multi-channel AI gateway with extensible messaging integrations
196 lines (170 loc) • 12.9 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.
- 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)