Modo de código

• Codex Code Mode se ejecuta dentro del arnés de programación de Codex. Su herramienta exec es una herramienta de gramática libre: el modelo escribe código fuente JavaScript sin procesar (opcionalmente precedido por una línea pragma // @exec: {...} para opciones de ejecución), ejecutado en un runtime Deno/V8.
• El modo de código de OpenClaw se ejecuta en el runtime genérico de agentes de OpenClaw y está deshabilitado salvo que se configure tools.codeMode.enabled: true. Su herramienta exec recibe una carga JSON { code, language }, ejecutada en un worker QuickJS-WASI.

​

Qué hace

• La lista de herramientas visible para el modelo pasa a ser exactamente exec y wait.
• exec evalúa JavaScript o TypeScript generado por el modelo en un hilo worker QuickJS-WASI aislado.
• Todas las demás herramientas habilitadas (núcleo de OpenClaw, Plugin, MCP, cliente) se ocultan del prompt del modelo y se exponen dentro del programa invitado mediante ALL_TOOLS y tools.
• El código invitado busca en el catálogo oculto, describe el esquema de una herramienta y llama a una herramienta a través de la misma ruta de ejecución usada por los turnos normales del agente (política, aprobaciones, hooks y telemetría siguen aplicándose).
• Las herramientas MCP se agrupan bajo el espacio de nombres MCP; en modo de código, esta es la única forma admitida de llamarlas.
• wait reanuda una ejecución suspendida en modo de código cuando todavía hay llamadas a herramientas anidadas pendientes.

​

Por qué usarlo

• Superficie de prompt más pequeña: los proveedores reciben dos herramientas de control en lugar de docenas o cientos de esquemas completos de herramientas.
• Mejor orquestación: el modelo puede usar bucles, uniones, pequeñas transformaciones, lógica condicional y llamadas a herramientas anidadas en paralelo dentro de una celda de código.
• Neutral respecto al proveedor: funciona con herramientas de OpenClaw, Plugin, MCP y cliente sin depender de ejecución de código nativa del proveedor.
• Falla de forma cerrada: si el modo de código está habilitado pero el runtime QuickJS-WASI no está disponible, la ejecución falla en lugar de volver silenciosamente a una exposición directa amplia de herramientas.

​

Habilitarlo

{
  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

​

Recorrido técnico

​

Estado del runtime

​

Alcance

​

Términos

• Modo de código: el modo de runtime de OpenClaw que oculta las herramientas normales del modelo y expone solo exec y wait.
• Runtime invitado: la VM JavaScript QuickJS-WASI que evalúa el código del modelo.
• Puente de host: la superficie estrecha de callbacks compatible con JSON desde el código invitado de vuelta a OpenClaw.
• Catálogo: la lista con alcance de ejecución de herramientas efectivas después de la resolución normal de política de herramientas, Plugin, MCP y herramientas de cliente.
• Llamada a herramienta anidada: una llamada a herramienta hecha desde código invitado a través del puente de host.
• Snapshot: estado serializado de la VM QuickJS-WASI guardado para que wait pueda continuar una ejecución suspendida en modo de código.

​

Configuración

​

Activación

1. Resolver el agente, modelo, proveedor, sandbox, canal, remitente y política de ejecución.
2. Crear la lista efectiva de herramientas de OpenClaw, añadiendo herramientas elegibles de Plugin, MCP y cliente.
3. Aplicar la política de permitir/denegar.
4. Si tools.codeMode.enabled es falso, continuar con la exposición normal de herramientas.
5. Si está habilitado y las herramientas están activas para la ejecución, registrar las herramientas efectivas en el catálogo de modo de código.
6. Eliminar todas las herramientas normales de la lista visible para el modelo; añadir exec y wait.

​

Herramientas visibles para el modelo

​

exec

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

• Uno de code o command debe no estar vacío.
• code es el campo documentado orientado al modelo.
• command se acepta como un alias compatible con exec para políticas de hooks y reescrituras de confianza (la herramienta normal exec de shell de OpenClaw también usa un campo command); cuando ambos están presentes, los valores deben coincidir.
• language toma "javascript" como valor predeterminado; el esquema lo expone como un enum de cadena plano ("javascript" | "typescript"), no como una unión oneOf/anyOf, ya que algunos proveedores rechazan esas formas.
• Si language es "typescript", OpenClaw transpila antes de evaluar.
• exec rechaza import, require, importación dinámica y patrones de cargador de módulos.
• exec nunca expone recursivamente la implementación normal de shell exec.
• Los eventos de hook externos de exec en modo de código llevan toolKind: "code_mode_exec" y toolInputKind: "javascript" | "typescript" (cuando se conoce), para que las políticas puedan distinguir celdas de modo de código de llamadas exec de estilo shell que comparten el mismo nombre de herramienta.

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 evalúa el código hasta completarse, fallar o suspenderse.
2. Al suspenderse, OpenClaw toma una instantánea de la VM de QuickJS y registra el trabajo pendiente del anfitrión.
3. Cuando el trabajo pendiente se resuelve, wait restaura la instantánea de la VM y vuelve a registrar las devoluciones de llamada del anfitrión mediante nombres estables.
4. OpenClaw entrega resultados de herramientas anidadas en la VM restaurada y drena los trabajos pendientes de QuickJS.
5. wait devuelve completed, failed u otro resultado waiting.

• runId es desconocido o su instantánea ya caducó.
• el llamador no está en el mismo ámbito de ejecución/sesión que la ejecución suspendida.
• ya hay un wait en curso para ese runId.
• falla la restauración de QuickJS-WASI.
• la reanudación superaría maxOutputBytes o maxSnapshotBytes.

​

API del entorno de ejecución invitado

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

​

Espacios de nombres internos

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

​

Ciclo de vida del registro

1. Un cargador de confianza llama a registerCodeModeNamespaceForPlugin(pluginId, registration).
2. El modo código crea el ToolSearchRuntime oculto para la ejecución y lee su catálogo con ámbito de ejecución.
3. createCodeModeNamespaceRuntime(ctx, catalog) conserva solo los registros cuyos requiredToolNames son todos visibles y propiedad del mismo pluginId.
4. Cada espacio de nombres visible llama a createScope(ctx) para la ejecución actual, y recibe contexto de ejecución como agentId, sessionKey, sessionId, runId, configuración y estado de aborto.
5. Los datos de ámbito se serializan en un descriptor plano y se inyectan en QuickJS como globales directos y namespaces.<globalName>.
6. Las llamadas invitadas se suspenden a través del puente del worker, resuelven la ruta del espacio de nombres en el anfitrión, asignan la llamada a una herramienta de catálogo declarada propiedad del Plugin y ejecutan esa herramienta mediante ToolSearchRuntime.callExactId.
7. Las llamadas de puente de espacio de nombres listas se drenan automáticamente dentro de la llamada exec/wait activa; si el trabajo del espacio de nombres sigue pendiente al agotarse el tiempo de espera o el invitado cede explícitamente, wait reanuda el mismo entorno de ejecución de espacio de nombres más tarde.
8. La reversión o desinstalación del Plugin llama a clearCodeModeNamespacesForPlugin(pluginId) para que los globales obsoletos no sobrevivan a una carga fallida del Plugin.

​

Forma del registro

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

​

Propiedad y visibilidad

• cada herramienta requerida debe existir en el catálogo de ejecución
• cada herramienta requerida debe tener sourceName === pluginId
• el espacio de nombres se oculta cuando falta alguna herramienta requerida o pertenece a otro Plugin
• cada ruta invocable solo puede apuntar a una herramienta nombrada en requiredToolNames

​

Reglas de serialización de ámbito

• funciones sin procesar
• grafos de objetos circulares
• segmentos de ruta inseguros: __proto__, constructor, prototype, claves vacías, o claves que contengan el separador interno de ruta
• valores de globalName que no son identificadores de JavaScript
• colisiones de globalName con globales integrados de modo código como tools, namespaces, text, json, yield_control, MCP, API, ALL_TOOLS o __openclaw*

​

Prompts

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

​

Limpieza

clearCodeModeNamespacesForPlugin(pluginId);

​

Lista de comprobación de pruebas

• el texto del prompt del espacio de nombres aparece solo cuando las herramientas de respaldo son visibles
• las herramientas con el mismo nombre de otro sourceName no exponen el espacio de nombres
• se rechazan las funciones de alcance sin procesar
• se rechazan los ids de espacios de nombres falsificados y las rutas falsificadas
• las rutas invocables no pueden apuntar a herramientas no declaradas
• los objetos anidados y las referencias compartidas se serializan correctamente
• las llamadas al espacio de nombres se ejecutan mediante herramientas del catálogo y devuelven detalles seguros para JSON
• el código invitado puede capturar los fallos
• las llamadas suspendidas al espacio de nombres se reanudan mediante wait
• la reversión del plugin borra los registros de espacios de nombres propietarios

​

API de salida

• text(value) anexa salida legible por humanos al array output.
• json(value) anexa un elemento de salida estructurado después de una serialización compatible con JSON.
• El valor devuelto final del código invitado se convierte en value en un resultado completed.

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

​

Catálogo de herramientas

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

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

​

Interacción con Búsqueda de herramientas

• OpenClaw no expone tool_search_code, tool_search, tool_describe ni tool_call como herramientas visibles para el modelo.
• La misma idea de catalogación se mueve dentro del runtime invitado.
• El runtime invitado recibe metadatos compactos de ALL_TOOLS y helpers de búsqueda/descripción/ llamada para herramientas que no son MCP.
• Las llamadas MCP usan el espacio de nombres generado MCP y sus encabezados $api() en lugar de tools.call(...).
• Las llamadas anidadas se despachan mediante la misma ruta de ejecutor de OpenClaw que usa Búsqueda de herramientas.

​

Nombres de herramientas y colisiones

• tools.call("openclaw:core:exec", input) puede llamar a la herramienta shell exec si la política lo permite.
• tools.exec(...) se instala solo si la entrada de catálogo shell exec tiene un nombre seguro no ambiguo.
• la herramienta exec de modo de código nunca está disponible recursivamente mediante tools.

​

Ejecución de herramientas anidadas

​

Ciclo de vida de ejecución e instantánea

• Un resultado waiting almacena la instantánea de QuickJS, las solicitudes pendientes del puente y metadatos de alcance (id de ejecución del agente, id/clave de sesión) hasta que wait lo reanuda o caduca.
• Los valores de runId caducados, de sesión incorrecta, de ejecución incorrecta y desconocidos/ya en reanudación no producen un estado terminal distinto; emergen como un resultado failed (code: "invalid_input") con un mensaje como code mode run is unavailable or expired. o code mode run belongs to a different session..
• La instantánea de una ejecución se elimina del mapa tan pronto como se resuelve como completed o failed, o se descarta al apagar el Gateway (nada sobrevive a un reinicio, por diseño: esto es estado transitorio del runtime).
• OpenClaw limita el número de ejecuciones suspendidas simultáneamente por proceso (64) y rechaza nuevas suspensiones por encima de ese límite con too many suspended code mode runs..

​

Runtime QuickJS-WASI

​

TypeScript

​

Límite de seguridad

• ejecuta QuickJS-WASI fuera del bucle de eventos principal, en un hilo worker
• carga quickjs-wasi como dependencia directa, no mediante Codex ni un paquete transitivo
• sin sistema de archivos, red, subprocesos, importación de módulos, variables de entorno ni objetos globales del host en el invitado
• usa límites de memoria e interrupción de QuickJS más un tiempo límite de reloj de pared del proceso padre
• aplica límites de salida, instantánea, registro y llamadas pendientes
• serializa los valores del puente del host mediante un adaptador JSON estrecho
• convierte errores del host en errores simples del invitado, nunca en objetos del ámbito del host
• descarta instantáneas por timeout, cancelación, fin de sesión o caducidad
• rechaza acceso recursivo a exec, wait y herramientas de control de Búsqueda de herramientas
• evita que las colisiones de nombres de conveniencia oculten helpers del catálogo

​

Códigos de error

type CodeModeErrorCode =
  | "invalid_input"
  | "runtime_unavailable"
  | "timeout"
  | "output_limit_exceeded"
  | "snapshot_limit_exceeded"
  | "internal_error";

​

Telemetría

​

Depuración

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

​

Diseño de implementación

• contrato de configuración: tools.codeMode
• constructor de catálogo: herramientas efectivas a entradas compactas y mapa de ids
• adaptador de superficie del modelo: reemplazar herramientas visibles por exec y wait
• adaptador de runtime QuickJS-WASI: cargar, evaluar, crear instantánea, restaurar, desechar
• supervisor de worker: timeout, cancelación, aislamiento de fallos
• adaptador de puente: callbacks del host seguros para JSON y entrega de resultados
• adaptador de transformación de TypeScript
• almacén de instantáneas: TTL, límites de tamaño, alcance de ejecución/sesión
• proyección de trayectoria para llamadas de herramientas anidadas
• contadores de telemetría y diagnósticos

​

Lista de comprobación de validación

• la configuración deshabilitada deja sin cambios la exposición existente de herramientas
• la configuración de objeto sin enabled: true deja deshabilitado el modo código
• la configuración habilitada expone solo exec y wait al modelo cuando las herramientas están activas para la ejecución
• las ejecuciones sin herramientas en bruto, disableTools y las listas de permitidos vacías no activan la aplicación de la carga útil del modo código
• todas las herramientas no MCP efectivas aparecen en ALL_TOOLS
• las herramientas denegadas no aparecen en ALL_TOOLS
• tools.search, tools.describe y tools.call funcionan para las herramientas de OpenClaw
• API.list("mcp") y API.read("mcp/<server>.d.ts") exponen declaraciones MCP de estilo TypeScript sin una llamada de puente/herramienta
• el espacio de nombres MCP $api() sigue disponible como alternativa en línea para esquemas
• las llamadas al espacio de nombres MCP funcionan para herramientas MCP visibles con una entrada de objeto, mientras las entradas directas del catálogo MCP están ausentes de tools.*
• las herramientas de control de Búsqueda de herramientas están ocultas tanto de la superficie del modelo como del catálogo oculto
• las llamadas anidadas conservan el comportamiento de aprobación y hooks
• exec de shell está oculto para el modelo, pero se puede llamar por id de catálogo cuando está permitido
• exec y wait recursivos en modo código no se pueden llamar desde código invitado
• la entrada TypeScript se transforma y evalúa sin cargar TypeScript en rutas deshabilitadas o solo JavaScript
• import, require, el sistema de archivos, la red y el acceso al entorno fallan
• los bucles infinitos agotan el tiempo de espera y no pueden bloquear el Gateway
• los fallos del límite de memoria terminan la VM invitada
• los límites de salida e instantánea se aplican para llamadas completadas y suspendidas
• wait reanuda una instantánea suspendida y devuelve el valor final
• los valores de runId expirados, cancelados, de sesión incorrecta y desconocidos fallan
• la reproducción y persistencia de la transcripción conservan las llamadas de control del modo código
• la transcripción y la telemetría muestran claramente las llamadas a herramientas anidadas

​

Plan de pruebas E2E

1. Inicia un Gateway con tools.codeMode.enabled: false.
2. Envía un turno de agente con un pequeño conjunto directo de herramientas.
3. Afirma que las herramientas visibles para el modelo no han cambiado.
4. Reinicia con tools.codeMode.enabled: true.
5. Envía un turno de agente con herramientas de prueba de OpenClaw, plugin, MCP y cliente.
6. Afirma que la lista de herramientas visibles para el modelo es exactamente exec, wait.
7. En exec, lee ALL_TOOLS y afirma que las herramientas de prueba efectivas están presentes.
8. En exec, llama a herramientas de OpenClaw/plugin/cliente mediante tools.search, tools.describe y tools.call.
9. En exec, llama a API.list("mcp") y API.read("mcp/<server>.d.ts") y afirma que los archivos de declaración describen herramientas MCP visibles.
10. En exec, llama a herramientas MCP mediante MCP.<server>.<tool>({ ...input }) y afirma que las entradas directas del catálogo MCP están ausentes de ALL_TOOLS y tools.*.
11. Afirma que las herramientas denegadas están ausentes y no pueden llamarse mediante un id adivinado.
12. Inicia una llamada a herramienta anidada que se resuelve después de que exec devuelva waiting.
13. Llama a wait y afirma que la VM restaurada recibe el resultado de la herramienta.
14. Afirma que la respuesta final contiene la salida producida después de la restauración.
15. Afirma que el tiempo de espera agotado, la cancelación y la expiración de instantáneas limpian el estado del runtime.
16. Exporta la trayectoria y afirma que las llamadas anidadas son visibles bajo la llamada principal de modo código.

​

Relacionado

• Búsqueda de herramientas
• Runtimes de agentes
• Herramienta Exec
• Ejecución de código