From 50f27ee91dff9cf274d5b59d288d48e92af9f11e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 31 May 2026 22:32:57 +0100
Subject: [PATCH] docs: document code-mode MCP API files

---
 docs/gateway/config-tools.md | 31 +++++++++++++++++++++++++++++++
 docs/reference/code-mode.md  | 19 +++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/gateway/config-tools.md b/docs/gateway/config-tools.md
index 76e447e4f07a..1dadc87d1d4e 100644
--- a/docs/gateway/config-tools.md
+++ b/docs/gateway/config-tools.md
@@ -76,6 +76,37 @@ Server globs use the provider-safe MCP server prefix, not necessarily the raw `m
 
 Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use `openclaw doctor` to catch this shape for OpenClaw-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
 
+### `tools.codeMode`
+
+`tools.codeMode` enables the generic OpenClaw code-mode surface. When enabled
+for a run with tools, the model sees only `exec` and `wait`; normal OpenClaw
+tools move behind the in-sandbox `tools.*` catalog bridge, and MCP tools are
+available through the generated `MCP` namespace.
+
+```json5
+{
+  tools: {
+    codeMode: {
+      enabled: true,
+    },
+  },
+}
+```
+
+The shorthand is also accepted:
+
+```json5
+{
+  tools: { codeMode: true },
+}
+```
+
+MCP declarations are exposed through the read-only virtual API file surface in
+code mode. Guest code can call `API.list("mcp")` and
+`API.read("mcp/<server>.d.ts")` to inspect TypeScript-style signatures before
+calling `MCP.<server>.<tool>()`. See [Code mode](/reference/code-mode) for the
+runtime contract, limits, and debugging steps.
+
 ### `tools.allow` / `tools.deny`
 
 Global tool allow/deny policy (deny wins). Case-insensitive, supports `*` wildcards. Applied even when Docker sandbox is off.
diff --git a/docs/reference/code-mode.md b/docs/reference/code-mode.md
index 3809538f5c1d..c47faaa54176 100644
--- a/docs/reference/code-mode.md
+++ b/docs/reference/code-mode.md
@@ -100,6 +100,11 @@ The shorthand is also accepted:
 Code mode remains off when `tools.codeMode` is omitted, `false`, or an object
 without `enabled: true`.
 
+When you use sandboxed agents with configured MCP servers, also make sure the
+sandbox tool policy allows the bundled MCP plugin, for example with
+`tools.sandbox.tools.alsoAllow: ["bundle-mcp"]`. See
+[Configuration - tools and custom providers](/gateway/config-tools#mcp-and-plugin-tools-inside-sandbox-tool-policy).
+
 Use explicit limits when you want tighter bounds:
 
 ```json5
@@ -493,6 +498,20 @@ declare namespace MCP.github {
 }
 ```
 
+The declaration files are virtual, not files written under the workspace or
+state directory. For each code-mode `exec` call, OpenClaw builds the run-scoped
+tool catalog, keeps the visible MCP entries, renders `mcp/index.d.ts` plus one
+`mcp/<server>.d.ts` declaration per visible server, and injects that small
+read-only table into the QuickJS worker. Guest code sees only the `API` object:
+`API.list(prefix?)` returns file metadata and `API.read(path)` returns the
+selected declaration content. Unknown paths and `.` / `..` segments are rejected.
+
+This keeps large MCP schemas out of the model prompt. The agent learns that the
+virtual API exists from the `exec` tool description, reads only the needed
+declaration file, and then calls `MCP.<server>.<tool>()` with one object argument.
+`MCP.<server>.$api()` remains available as an inline fallback when the agent
+needs a single-tool schema response inside the program.
+
 The guest runtime must not expose host objects directly. Inputs and outputs cross
 the bridge as JSON-compatible values with explicit size caps.