- 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 reviewing the exec/wait contract, QuickJS-WASI sandbox, TypeScript transform, or hidden tool-catalog bridge

- You are adding or reviewing an internal code-mode namespace registry integration

---

Code mode is an experimental OpenClaw agent-runtime feature. It is off by

```typescript

declare const ALL_TOOLS: ToolCatalogEntry[];

declare const tools: ToolCatalog;

declare const namespaces: Record<string, unknown>;

declare function text(value: unknown): void;

declare function json(value: unknown): void;

The guest runtime must not expose host objects directly. Inputs and outputs cross

the bridge as JSON-compatible values with explicit size caps.

## Internal namespaces

Internal namespaces give code mode a concise domain API without adding more

model-visible tools. A loader-owned integration can register a namespace such

as `Issues`, `Fictions`, or `Calendar`; guest code then calls that namespace

inside the QuickJS program while OpenClaw still shows only `exec` and `wait` to

the model.

Namespaces are internal for now. There is no public plugin SDK namespace API:

external plugin namespaces need a loader-owned contract so plugin identity,

installed manifests, auth state, and cached catalog descriptors cannot drift

from the plugin tools that back the namespace. Core code mode owns only the

sandbox, serialization, catalog gating, and bridge dispatch.

Guest code can then use either the direct global or the `namespaces` map:

```javascript

const open = await Issues.list({ state: "open" });

const alsoOpen = await namespaces.Issues.list({ state: "open" });

return { count: open.length, alsoCount: alsoOpen.length };

```

### Registry lifecycle

The namespace registry is process-local and keyed by namespace id. A typical

run follows this path:

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. `wait` resumes the same namespace runtime when a code-mode run suspended on

nested tool work.

8. Plugin rollback or uninstall calls `clearCodeModeNamespacesForPlugin(pluginId)`

so stale globals do not survive a failed plugin load.

The important invariant: namespace calls are catalog tool calls. They use the

same policy hooks, approvals, abort handling, telemetry, transcript projection,

and suspend/resume behavior as `tools.call(...)`.

### Registration shape

Register namespaces from the integration that owns the backing tools. Keep the

scope small and only expose domain verbs that map to declared catalog tools.

```typescript

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,

})),

}),

});

```

`createCodeModeNamespaceTool(toolName, inputMapper)` marks a scope member as a

callable namespace function. The optional `inputMapper` receives the guest

arguments and returns the input object for the backing catalog tool. Without an

input mapper, the first guest argument is used, or `{}` when omitted.

Raw host functions are rejected before guest code runs:

```typescript

createScope: () => ({

// Wrong: this bypasses the catalog tool lifecycle and will be rejected.

list: async () => githubClient.listIssues(),

});

```

### Ownership and visibility

Namespace ownership is bound to the registration caller's `pluginId`.

`requiredToolNames` is both a visibility gate and an ownership check:

- 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`

This prevents another plugin from exposing a namespace by registering a

same-named tool. It also keeps namespaces aligned with ordinary agent policy:

if the run cannot see the backing tools, it cannot see the namespace.

For example, a GitHub namespace should live behind a GitHub-owned extension that

owns GitHub auth, REST or GraphQL clients, rate limits, write approvals, and

tests. Core code mode should not embed GitHub-specific APIs, token handling, or

provider policy.

### Scope serialization rules

`createScope(ctx)` may return a plain object containing JSON-compatible values,

arrays, nested objects, and `createCodeModeNamespaceTool(...)` call markers.

Host objects never enter QuickJS directly.

The serializer rejects:

- 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*`

Values that cannot be JSON-serialized are converted to JSON-safe fallback

values before crossing the bridge. Binary data, handles, sockets, clients, and

class instances should stay behind ordinary catalog tools.

### Prompts

The namespace `description` and optional `prompt` are appended to the model

visible `exec` schema only when the namespace is visible for that run. Use them

to teach the smallest useful surface:

```typescript

{

description: "Fiction production service helpers.",

prompt:

"Use Fictions.riskAudit(), Fictions.promoteIfReady(id, status), and Fictions.unpaidOver(amount).",

}

```

Keep prompts about the namespace contract, not auth setup, implementation

history, or unrelated plugin behavior.

### Cleanup

Namespaces are process-local registrations. Remove them when the owning plugin

is disabled, uninstalled, or rolled back:

```typescript

clearCodeModeNamespacesForPlugin(pluginId);

```

Use `unregisterCodeModeNamespace(namespaceId)` only when removing one known

namespace. Tests can call `clearCodeModeNamespacesForTest()` to avoid leaking

registrations across cases.

### Test checklist

Namespace changes should cover the security boundary and the guest behavior:

- 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

Namespaces complement the generic `tools.search` / `tools.call` catalog. Use

the catalog for arbitrary enabled tools; use namespaces for plugin-owned,

documented domain APIs where concise code is more reliable than repeated schema

lookups.

## Output API

`text(value)` appends human-readable output to the `output` array.