Code mode

Documentation Index

Fetch the complete documentation index at: https://openclaw.ai2me.io/llms.txt

Use this file to discover all available pages before exploring further.

• Codex Code Mode is enabled for Codex app-server threads unless restricted tool policy disables native code mode. It runs in the Codex coding harness, where the model writes shell commands through an exec.command contract.
• OpenClaw code mode is disabled unless tools.codeMode.enabled: true is configured. It runs in the OpenClaw generic agent runtime, where the model writes JavaScript or TypeScript programs through an exec.code contract.

​

What is this?

• The model-visible tool list is exactly exec and wait.
• exec evaluates model-generated JavaScript or TypeScript in a constrained QuickJS-WASI worker.
• Normal OpenClaw tools are hidden from the model prompt and exposed inside the guest program through ALL_TOOLS and tools.
• Guest code can search the hidden catalog, describe a tool, and call a tool through the same OpenClaw execution path used by normal agent turns.
• MCP tools are grouped under the MCP namespace. In code mode, this namespace is the only supported way to call MCP tools.
• wait resumes a suspended code-mode run when nested tool calls are still pending.

​

Why is this good?

• Smaller prompt surface: providers receive two control 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.
• Provider neutral: it works for OpenClaw, plugin, MCP, and client tools without depending on provider-native code execution.
• Existing policy stays in force: nested tool calls still go through OpenClaw policy, approvals, hooks, session context, and audit paths.
• Clear failure mode: when code mode is explicitly enabled and the runtime is unavailable, OpenClaw fails closed instead of falling back to broad direct tool exposure.

​

How to enable it

{
  tools: {
    codeMode: {
      enabled: true,
    },
  },
}

{
  tools: {
    codeMode: true,
  },
}

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

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

​

Technical tour

​

Runtime status

• Runtime: quickjs-wasi.
• Default state: disabled.
• Stability: experimental OpenClaw surface; Codex Code mode is a separate stable Codex harness surface.
• Target surface: generic OpenClaw agent runs.
• Security posture: model code is hostile.
• User-facing promise: enabling code mode never silently falls back to broad direct tool exposure.

​

Scope

• model-visible exec and wait tool definitions
• hidden tool catalog construction
• JavaScript and TypeScript guest execution
• QuickJS-WASI worker runtime
• host callbacks for catalog search, schema describe, and tool call
• resumable state for suspended guest programs
• output, timeout, memory, pending-call, and snapshot limits
• telemetry and trajectory projection for nested tool calls

• provider-native remote code execution
• shell execution semantics
• changing existing tool authorization
• persistent user-authored scripts
• package manager, file, network, or module access in guest code
• direct reuse of Codex Code mode internals

​

Terms

​

Configuration

• enabled: boolean. Default false. Enables code mode only when true.
• runtime: "quickjs-wasi". Only supported runtime.
• mode: "only". Exposes exec and wait, hides normal model tools.
• languages: array of "javascript" and "typescript". Default includes both.
• timeoutMs: wall-clock cap for one exec or wait. Default 10000. Runtime clamp: 100 to 60000.
• memoryLimitBytes: QuickJS heap cap. Default 67108864. Runtime clamp: 1048576 to 1073741824.
• maxOutputBytes: cap for returned text, JSON, and logs. Default 65536. Runtime clamp: 1024 to 10485760.
• maxSnapshotBytes: cap for serialized VM snapshots. Default 10485760. Runtime clamp: 1024 to 268435456.
• maxPendingToolCalls: cap for concurrent nested tool calls. Default 16. Runtime clamp: 1 to 128.
• snapshotTtlSeconds: how long a suspended VM can be resumed. Default 900. Runtime clamp: 1 to 86400.
• searchDefaultLimit: default hidden-catalog search result count. Default 8. Runtime clamps this to maxSearchLimit.
• maxSearchLimit: maximum hidden-catalog search result count. Default 50. Runtime clamp: 1 to 50.

​

Activation

1. Resolve the agent, model, provider, sandbox, channel, sender, and run policy.
2. Build the effective OpenClaw tool list.
3. Add eligible plugin, MCP, and client tools.
4. Apply allow and deny policy.
5. If tools.codeMode.enabled is false, continue with normal tool exposure.
6. If enabled and tools are active for the run, register the effective tools in the code-mode catalog.
7. Remove all normal tools from the model-visible tool list.
8. Add code-mode exec and wait.

​

Model-visible tools

• exec
• wait

​

exec

type CodeModeExecInput = {
  code?: string;
  command?: string;
  language?: "javascript" | "typescript";
};

• One of code or command must be non-empty.
• code is the documented model-facing field.
• command is accepted as an exec-compatible alias for hook policies and trusted rewrites; when both are present, the values must match.
• Outer code-mode exec hook events include toolKind: "code_mode_exec" and include toolInputKind: "javascript" | "typescript" when the input language is known, so policies can distinguish code-mode cells from shell-style exec calls that share the same tool name.
• language defaults to "javascript".
• If language is "typescript", OpenClaw transpiles before evaluation.
• exec rejects import, require, dynamic import, and module-loader patterns in v1.
• exec does not expose the normal shell exec implementation recursively.

type CodeModeResult = CodeModeCompletedResult | CodeModeWaitingResult | CodeModeFailedResult;

type CodeModeCompletedResult = {
  status: "completed";
  value: unknown;
  output?: CodeModeOutput[];
  telemetry: CodeModeTelemetry;
};

type CodeModeWaitingResult = {
  status: "waiting";
  runId: string;
  reason: "pending_tools" | "yield";
  pendingToolCalls?: CodeModePendingToolCall[];
  output?: CodeModeOutput[];
  telemetry: CodeModeTelemetry;
};

type CodeModeFailedResult = {
  status: "failed";
  error: string;
  code?: CodeModeErrorCode;
  output?: CodeModeOutput[];
  telemetry: CodeModeTelemetry;
};

​

wait

type CodeModeWaitInput = {
  runId: string;
};

1. exec evaluates code until completion, failure, or suspension.
2. On suspension, OpenClaw snapshots the QuickJS VM and records pending host work.
3. When pending work settles, wait restores the VM snapshot.
4. OpenClaw re-registers host callbacks by stable names.
5. OpenClaw delivers nested tool results into the restored VM.
6. OpenClaw drains QuickJS pending jobs.
7. wait returns completed, failed, or another waiting result.

• runId is unknown.
• the snapshot expired.
• the parent run or session was aborted.
• the caller is not in the same run/session scope.
• QuickJS-WASI restore fails.
• restoring would exceed configured limits.

​

Guest runtime API

declare const ALL_TOOLS: ToolCatalogEntry[];
declare const tools: ToolCatalog;
declare const MCP: Record<string, unknown>;
declare const namespaces: Record<string, unknown>;

declare function text(value: unknown): void;
declare function json(value: unknown): void;
declare function yield_control(reason?: string): Promise<void>;

type ToolCatalogEntry = {
  id: string;
  name: string;
  label?: string;
  description: string;
  source: "openclaw" | "plugin" | "mcp" | "client";
  sourceName?: string;
};

type ToolCatalogEntryWithSchema = ToolCatalogEntry & {
  parameters: unknown;
};

type ToolCatalog = {
  search(query: string, options?: { limit?: number }): Promise<ToolCatalogEntry[]>;
  describe(id: string): Promise<ToolCatalogEntryWithSchema>;
  call(id: string, input?: unknown): Promise<unknown>;
  [safeToolName: string]: unknown;
};

const files = await tools.search("read local file");
const fileRead = await tools.describe(files[0].id);
const content = await tools.call(fileRead.id, { path: "README.md" });

// If the hidden catalog has an unambiguous `web_search` entry:
const hits = await tools.web_search({ query: "OpenClaw code mode" });

const files = await API.list("mcp");
const githubApi = await API.read("mcp/github.d.ts");

const issue = await MCP.github.createIssue({
  owner: "openclaw",
  repo: "openclaw",
  title: "Investigate gateway logs",
});

const snapshot = await MCP.chromeDevtools.takeSnapshot({ output: "markdown" });
const resource = await MCP.docs.resources.read({ uri: "memo://one" });
const prompt = await MCP.docs.prompts.get({
  name: "brief",
  arguments: { topic: "release" },
});

type McpToolResult = {
  content?: unknown[];
  structuredContent?: unknown;
  isError?: boolean;
  [key: string]: unknown;
};

declare namespace MCP.github {
  /** Return this TypeScript-style API header. */
  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;

  /**
   * Create a GitHub issue.
   * @param owner Repository owner
   * @param repo Repository name
   * @param title Issue title
   */
  function createIssue(input: {
    owner: string;
    repo: string;
    title: string;
    body?: string;
  }): Promise<McpToolResult>;
}

​

Internal namespaces

const open = await Issues.list({ state: "open" });
const alsoOpen = await namespaces.Issues.list({ state: "open" });
return { count: open.length, alsoCount: alsoOpen.length };

​

Registry lifecycle

1. A trusted loader calls registerCodeModeNamespaceForPlugin(pluginId, registration).
2. Code mode creates the hidden ToolSearchRuntime for the run and reads its run-scoped catalog.
3. createCodeModeNamespaceRuntime(ctx, catalog) keeps only registrations whose requiredToolNames are all visible and owned by the same pluginId.
4. Each visible namespace calls createScope(ctx) for the current run. The scope receives run context such as agentId, sessionKey, sessionId, runId, config, and abort state.
5. Scope data is serialized into a plain descriptor and injected into QuickJS as direct globals and namespaces.<globalName>.
6. Guest calls suspend through the worker bridge, resolve the namespace path on the host, map the call to a declared plugin-owned catalog tool, and execute that tool through ToolSearchRuntime.call.
7. OpenClaw auto-drains ready namespace bridge calls inside the active exec/wait tool call. If namespace work is still pending at the timeout or the guest yields explicitly, wait resumes the same namespace runtime later.
8. Plugin rollback or uninstall calls clearCodeModeNamespacesForPlugin(pluginId) so stale globals do not survive a failed plugin load.

​

Registration shape

import {
  createCodeModeNamespaceTool,
  registerCodeModeNamespaceForPlugin,
} from "../agents/code-mode-namespaces.js";

const pluginId = "github";

registerCodeModeNamespaceForPlugin(pluginId, {
  id: "github-issues",
  globalName: "Issues",
  description: "GitHub issue helpers for the current repository.",
  requiredToolNames: ["github_list_issues", "github_update_issue"],
  prompt: "Use Issues.list(params) and Issues.update(number, patch).",
  createScope: (ctx) => ({
    repository: ctx.config,
    list: createCodeModeNamespaceTool("github_list_issues", ([params]) => params ?? {}),
    update: createCodeModeNamespaceTool("github_update_issue", ([number, patch]) => ({
      number,
      patch,
    })),
  }),
});

createScope: () => ({
  // Wrong: this bypasses the catalog tool lifecycle and will be rejected.
  list: async () => githubClient.listIssues(),
});

​

Ownership and visibility

• every required tool must exist in the run catalog
• every required tool must have sourceName === pluginId
• the namespace is hidden when any required tool is absent or owned by another plugin
• each callable path may target only a tool named in requiredToolNames

​

Scope serialization rules

• raw functions
• circular object graphs
• unsafe path segments: __proto__, constructor, prototype, empty keys, or keys containing the internal path separator
• globalName values that are not JavaScript identifiers
• globalName collisions with built-in code-mode globals such as tools, namespaces, text, json, yield_control, or __openclaw*

​

Prompts

{
  description: "Fiction production service helpers.",
  prompt:
    "Use Fictions.riskAudit(), Fictions.promoteIfReady(id, status), and Fictions.unpaidOver(amount).",
}

​

Cleanup

clearCodeModeNamespacesForPlugin(pluginId);

​

Test checklist

• namespace prompt text appears only when backing tools are visible
• same-named tools from another sourceName do not expose the namespace
• raw scope functions are rejected
• forged namespace ids and forged paths are rejected
• callable paths cannot target undeclared tools
• nested objects and shared references serialize correctly
• namespace calls execute through catalog tools and return JSON-safe details
• failures can be caught by guest code
• suspended namespace calls resume through wait
• plugin rollback clears the owning namespace registrations

​

Output API

type CodeModeOutput = { type: "text"; text: string } | { type: "json"; value: unknown };

• output order matches guest calls
• output is capped by maxOutputBytes
• non-serializable values are converted to plain strings or errors
• binary values are not supported in v1
• images and files travel through ordinary OpenClaw tools, not through the code-mode bridge

​

Tool catalog

1. OpenClaw core tools.
2. Bundled plugin tools.
3. External plugin tools.
4. MCP tools.
5. Client-provided tools for the current run.

<source>:<owner>:<tool-name>

openclaw:core:message
plugin:browser:browser_request
mcp:github:create_issue
client:app:select_file

• exec
• wait
• tool_search_code
• tool_search
• tool_describe
• tool_call

​

Tool Search interaction

• OpenClaw does not expose tool_search_code, tool_search, tool_describe, or tool_call as model-visible tools.
• The same cataloging idea moves inside the guest runtime.
• The guest runtime receives compact ALL_TOOLS metadata and search, describe, and call helpers for non-MCP tools.
• MCP calls use the generated MCP namespace and its $api() headers instead of tools.call(...).
• Nested calls dispatch through the same OpenClaw executor path that Tool Search uses.

​

Tool names and collisions

• tools.call("openclaw:core:exec", input) can call the shell exec tool if policy allows it.
• tools.exec(...) is installed only if the shell exec catalog entry has an unambiguous safe name.
• the code-mode exec tool is never recursively available through tools.

​

Nested tool execution

• active agent id
• session id and session key
• sender and channel context
• sandbox policy
• approval policy
• plugin before_tool_call hooks
• abort signal
• streaming updates where available
• trajectory and audit events

​

Runtime state

• running: VM is executing or nested calls are in flight.
• waiting: VM snapshot exists and can be resumed with wait.
• completed: final value returned; snapshot deleted.
• failed: error returned; snapshot deleted.
• expired: snapshot or pending state exceeded retention; cannot resume.
• aborted: parent run/session cancelled; snapshot deleted.

• maximum snapshot bytes per run
• maximum live snapshots per process
• snapshot TTL
• cleanup on run end
• cleanup on Gateway shutdown where persistence is not supported

​

QuickJS-WASI runtime

• compile or load the QuickJS-WASI WebAssembly module
• create one isolated VM per code-mode run or resume
• register host callbacks by stable names
• set memory and interrupt limits
• evaluate JavaScript
• drain pending jobs
• snapshot suspended VM state
• restore snapshots for wait
• dispose VM handles and snapshots after terminal states

​

TypeScript

• accepted input: one TypeScript code string
• output: JavaScript string evaluated by QuickJS-WASI
• no typechecking
• no module resolution
• no import or require in v1
• diagnostics are returned as failed results

​

Security boundary

• run QuickJS-WASI outside the main event loop
• load quickjs-wasi as a direct dependency, not through Codex or a transitive package
• no filesystem, network, subprocess, module import, environment variables, or host global objects in the guest
• use QuickJS memory and interrupt limits
• enforce parent-process wall-clock timeout
• enforce output, snapshot, log, and pending-call caps
• serialize host bridge values through a narrow JSON adapter
• convert host errors into plain guest errors, never host realm objects
• drop snapshots on timeout, abort, session end, or expiry
• reject recursive access to exec, wait, and Tool Search control tools
• prevent convenience-name collisions from shadowing catalog helpers

​

Error codes

type CodeModeErrorCode =
  | "runtime_unavailable"
  | "invalid_config"
  | "invalid_input"
  | "unsupported_language"
  | "typescript_transform_failed"
  | "module_access_denied"
  | "timeout"
  | "memory_limit_exceeded"
  | "output_limit_exceeded"
  | "snapshot_limit_exceeded"
  | "snapshot_expired"
  | "snapshot_restore_failed"
  | "too_many_pending_tool_calls"
  | "nested_tool_failed"
  | "aborted"
  | "internal_error";

​

Telemetry

• visible tool names sent to the model
• hidden catalog size and source breakdown
• exec and wait counts
• nested search, describe, and call counts
• nested tool ids called
• timeout, memory, snapshot, and output cap failures
• snapshot lifecycle events

​

Debugging

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

​

Implementation layout

• config contract: tools.codeMode
• catalog builder: effective tools to compact entries and id map
• model-surface adapter: replace visible tools with exec and wait
• QuickJS-WASI runtime adapter: load, eval, snapshot, restore, dispose
• worker supervisor: timeout, abort, crash isolation
• bridge adapter: JSON-safe host callbacks and result delivery
• TypeScript transform adapter
• snapshot store: TTL, size caps, run/session scoping
• trajectory projection for nested tool calls
• telemetry counters and diagnostics

​

Validation checklist

• disabled config leaves existing tool exposure unchanged
• object config without enabled: true leaves code mode disabled
• enabled config exposes only exec and wait to the model when tools are active for the run
• raw no-tool runs, disableTools, and empty allowlists do not trigger code-mode payload enforcement
• all effective non-MCP tools appear in ALL_TOOLS
• denied tools do not appear in ALL_TOOLS
• tools.search, tools.describe, and tools.call work for OpenClaw tools
• API.list("mcp") and API.read("mcp/<server>.d.ts") expose TypeScript-style MCP declarations without a bridge/tool call
• MCP namespace $api() remains available as an inline fallback for schemas
• MCP namespace calls work for visible MCP tools with one object input, while direct MCP catalog entries are absent from tools.*
• Tool Search control tools are hidden from both the model surface and the hidden catalog
• nested calls preserve approval and hook behavior
• shell exec is hidden from the model but callable by catalog id when allowed
• recursive code-mode exec and wait are not callable from guest code
• TypeScript input is transformed and evaluated without loading TypeScript on disabled or JavaScript-only paths
• import, require, filesystem, network, and environment access fail
• infinite loops time out and cannot block the Gateway
• memory cap failures terminate the guest VM
• output and snapshot caps are enforced for completed and suspended calls
• wait resumes a suspended snapshot and returns the final value
• expired, aborted, wrong-session, and unknown runId values fail
• transcript replay and persistence preserve code-mode control calls
• transcript and telemetry show nested tool calls clearly

​

E2E test plan

1. Start a Gateway with tools.codeMode.enabled: false.
2. Send an agent turn with a small direct tool set.
3. Assert the model-visible tools are unchanged.
4. Restart with tools.codeMode.enabled: true.
5. Send an agent turn with OpenClaw, plugin, MCP, and client test tools.
6. Assert the model-visible tool list is exactly exec, wait.
7. In exec, read ALL_TOOLS and assert the effective test tools are present.
8. In exec, call OpenClaw/plugin/client tools through tools.search, tools.describe, and tools.call.
9. In exec, call API.list("mcp") and API.read("mcp/<server>.d.ts") and assert the declaration files describe visible MCP tools.
10. In exec, call MCP tools through MCP.<server>.<tool>({ ...input }) and assert direct MCP catalog entries are absent from ALL_TOOLS and tools.*.
11. Assert denied tools are absent and cannot be called by guessed id.
12. Start a nested tool call that resolves after exec returns waiting.
13. Call wait and assert the restored VM receives the tool result.
14. Assert the final answer contains output produced after restore.
15. Assert timeout, abort, and snapshot expiry clean up runtime state.
16. Export trajectory and assert nested calls are visible under the parent code-mode call.

​

Related

• Tool Search
• Agent runtimes
• Exec tool
• Code execution