Code Mode output

Declared output contracts

OpenClaw tools can declare outputSchema for the structured value placed in AgentToolResult.details. This is useful for Code Mode and Tool Search; it is not a provider-native tool response schema and does not change direct tool exposure.

For a tool made with defineToolPlugin, declare the schema beside parameters:

import { Type } from "typebox";import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin"; const Shipment = Type.Object(  {    id: Type.String(),    paid: Type.Boolean(),    tons: Type.Number(),  },  { additionalProperties: false },); export default defineToolPlugin({  id: "shipping",  name: "Shipping",  description: "Shipment tools.",  tools: (tool) => [    tool({      name: "shipping_list",      description: "List shipments.",      parameters: Type.Object({}),      outputSchema: Type.Array(Shipment),      execute: async () => loadShipments(),    }),  ],});

For api.registerTool(...) or a factory tool, put the same outputSchema property on the returned AnyAgentTool object.

Current built-in contracts include agents_list, agents_wait, apply_patch, conversations_list, conversations_send, conversations_turn, edit, openclaw, read, screen, sessions_history, sessions_list, sessions_search, sessions_send, session_status, suggest_task, terminal, web_fetch, and web_search. Exact passthroughs can reuse their owning protocol schema instead of duplicating a model-only contract. For example, the conversation tools expose the same Gateway result schemas used by conversations.list, conversations.send, and conversations.turn; web_fetch owns a tool-local schema whose hint exposes stable metadata, text, cache state, and nested spill metadata; web_search declares its exact normalized results/answer/error/raw union as a complete quick-index hint. Filesystem contracts return structured read text, image, truncation, and optional-not-found outcomes; explicit edit change state plus diff/patch data; and apply-patch path summaries. Missing canonical daily notes (memory/YYYY-MM-DD.md) return an optional not_found result even when optional is omitted; other missing paths throw unless optional: true is explicitly supplied. When the quick index declares the fields, one cell can compose discovery and delivery without a separate inspection turn:

const listed = await conversations_list({ query: "build bot" });const target = listed.conversations.find((item) => item.label === "Build bot");if (!target) throw new Error("conversation not found");return await conversations_send({  conversationRef: target.conversationRef,  message: "Build finished.",});

The nested calls still use normal tool policy, hooks, and approvals. If a full contract is exact but too large for the bounded quick index, it remains available through the callable handle's describe() and the arrow stays -> ?.

Full native-tool declarations are also available on demand through API.list("tools") and API.read("tools/<callableName>.d.ts"), using the same final callable names as discovery. These declarations are generated from the effective input and trusted output schemas, not from the shortened quick index. Native listing entries contain paths; bytes is available after API.read generates the file. Files are not eagerly injected into every guest VM. Unknown outputs and unsupported schema leaves remain unknown; client schemas are not promoted into trusted declarations. Runtime validation remains the source of truth for constraints TypeScript cannot express. Native declarations allow omitting the input argument only when the effective schema accepts the empty object used by runtime normalization; genuinely required inputs remain required.

Known output declarations describe intact normalized tool values. Program-data admission rejects an oversized reply rather than substituting a successful truncation marker. Declarations have independent size, depth, and traversal bounds; use describe() for the original schema when those bounds require an unknown type. Reading declarations does not execute tools or automatically enable typechecking of cells.

The contract rules are strict:

• Describe the exact JSON-compatible details value, not rendered content blocks or a provider envelope.
• Include every non-throwing success or error variant. Omit outputSchema when the tool has no stable structured result.
• Close object layers with { additionalProperties: false } for a complete quick-index hint. Open, oversized, or otherwise partial schemas stay available through handle describe() but do not enable one-turn field use.
• OpenClaw compiles the schema before running the tool, then validates final details after normal tool hooks and before a catalog call returns. An invalid schema cannot run the tool; a mismatch fails without printing the value.
• Compact hints are deterministic and bounded. Handle describe() exposes the full trusted schema when the compact hint is insufficient.
• Installed plugin code is already trusted local code. Remote MCP and client metadata remains untrusted and cannot opt into these quick-index hints.

See Tool plugins for plugin authoring details.

MCP catalog entries are not exposed as bare globals or through generic catalog discovery; they are available only through the generated MCP namespace. TypeScript-style declaration files are available through the read-only API virtual file surface, so agents can inspect MCP signatures without adding MCP schemas to the prompt:

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" },});

API.read("mcp/<server>.d.ts") returns compact declarations inferred from MCP tool metadata:

interface McpToolResult {  content: unknown[];  structuredContent?: unknown;  isError?: boolean;} interface McpResourcesListResult {  resources: unknown[];  nextCursor?: string;}interface McpResourcesReadResult {  contents: unknown[];}interface McpPromptsListResult {  prompts: unknown[];  nextCursor?: string;}interface McpPromptsGetResult {  messages: unknown[];  description?: string;} 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>;}

Dictionary inputs retain their value types. Nullable enums and fields marked nullable: true include null, unless an explicit enum excludes it. Top-level fields with defaults may be omitted from calls. These declarations approximate JSON Schema; for constraints that TypeScript cannot express, inspect the original schema with MCP.<server>.$api("<tool>", { schema: true }).

MCP tool calls return their original JSON-safe content blocks, including block annotations and block-level _meta, plus top-level structuredContent and isError when provided. Top-level MCP _meta and private app metadata never enter the guest. An MCP application failure with isError: true still resolves as a result, so guest code can inspect and recover from it. Resource and prompt operations instead return their native MCP shapes: resources.list() returns resources, resources.read() returns contents, prompts.list() returns prompts, and prompts.get() returns messages with an optional description.

Declaration files are virtual, not 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 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 the virtual API exists from the exec tool description, reads only the needed declaration file, then calls MCP.<server>.<tool>() with one object argument. MCP.<server>.$api() remains available as an inline fallback for a single-tool schema response inside the program.

The guest runtime never sees host objects directly. Inputs and outputs cross the bridge as JSON-compatible values with explicit size caps.

Output API

• text(value) appends human-readable output to the output array.
• json(value) appends a structured output item after JSON-compatible serialization.
• The guest code's final returned value becomes value in a completed result.

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

Await async values before emitting them or returning arrays or plain objects that contain them. Unawaited Promises appear as a diagnostic string with await and Promise.all guidance. For example, use return await Promise.all(handles.map((tool) => tool.describe())); to return tool descriptions. Output serialization does not await nested Promises for you.

Handled Error values retain their name, message, and JSON-compatible enumerable custom fields in text(...), json(...), and returned arrays or plain objects. Error-specific toJSON methods are not invoked. This includes rejected reasons from Promise.allSettled(...). Handling an error does not fail the cell; uncaught errors still produce a failed result.

Nested tool data and model-visible output have separate limits. A successful bridge reply reaches the guest as its complete normalized JSON value, or its promise rejects with a catchable program-data resource error. The transport never substitutes a successful truncation marker. This also applies to catalog discovery and whole applicable skill instructions: intact or explicitly refused.

Each cell has an aggregate pending-reply inbox of min(memoryLimitBytes, maxSnapshotBytes) encoded UTF-8 bytes: 10 MiB by default, up to 256 MiB under the existing configuration clamps. Successful values and bounded tool errors consume this allowance when they settle, before retention. The allowance spans inline execution and every wait; it is reusable after the host and worker release delivered replies, not a cumulative pagination quota. On saturation, a fixed, bounded failure diagnostic remains available without retaining tool data; these control replies are bounded by pending-call slots. Cancellation and expiry close admission and release undelivered replies.

This is an additional logical host-data allowance, not a total RSS limit or a guarantee that large data can be suspended. Guest heap and whole-VM snapshot limits remain unchanged; worker handoff and JSON conversion can temporarily retain additional copies. Narrow or paginate requests after an admission error.

Output order matches guest calls. Cumulative guest output and the final value or failure diagnostic still share one maxOutputBytes serialized UTF-8 budget across all waits. Oversized errors retain their leading cause and end with [error truncated]; truncation does not turn a failure into success. For successful emitted or returned output that exceeds this budget, OpenClaw returns a bounded value with truncated: true, a UTF-8-safe prefix, omittedBytes, and guidance to rerun with narrower arguments. Treat that marker as a successful partial result: reduce the search scope, paginate, select fewer files, or return a smaller projection. Non-serializable values are converted to plain strings or errors; binary values are not supported. Images and files travel through ordinary OpenClaw tools, not through the code-mode bridge.

Marker prefixes and omitted-byte counts describe the original compact JSON after normalization, including array brackets, separators, and JSON escaping. Ordinary output is delivered incrementally. An unchanged cumulative summary is not repeated; new output or a changed final-value/error reservation can produce a replacement summary of that same original output.

Model-facing exec and wait results also fit the effective model's per-result context and persistence limits. OpenClaw reserves the complete result envelope, including status, continuation, diagnostics, telemetry, and JSON formatting, using the same compact representation for budget fitting and delivery before projecting output from its retained original source. Network-derived results retain the untrusted-content wrapper and its smaller content limit. These limits do not reduce the nested tool's byte allowance. Headless execution and low-level controls without model context retain their byte-only allowance (with the existing security wrapper limit for network-derived control output).

This protects fresh results; it is not an archival JSON guarantee. Later aggregate reduction, cache-TTL pruning, and replay into a smaller model may still shorten or replace historical tool text. Already-sent results stay unchanged during ordinary continuation. Conventional tools keep their own text and image formats: a declared output schema describes details, not model-visible text. The file-read producer reserves its exact paging footer within the same model limits, and oversized skill instructions are refused rather than silently served in part.