Code-Modus

• Codex Code Mode wird innerhalb der Codex-Coding-Umgebung ausgeführt. Sein Tool exec ist ein Tool mit Freiformgrammatik: Das Modell schreibt unverarbeiteten JavaScript-Quellcode (optional mit einer vorangestellten // @exec: {...}-Pragma-Zeile für Ausführungsoptionen), der in der prozessinternen V8-Code-Mode-Laufzeit von Codex ausgeführt wird.
• Der OpenClaw-Code-Modus wird in der generischen OpenClaw-Agent-Laufzeit ausgeführt und ist deaktiviert, sofern tools.codeMode.enabled: true nicht konfiguriert ist. Sein Tool exec akzeptiert eine JSON-Nutzlast { code, language }, die in einem QuickJS-WASI- Worker ausgeführt wird.

​

Funktionsweise

• Die für das Modell sichtbare Tool-Liste wird zu exec, wait sowie jedem ausschließlich direkten Tool wie computer oder dem nativen Bildverarbeitungs-Loader image, dessen Bildergebnis die Gast-Bridge nicht passieren kann.
• exec wertet vom Modell generiertes JavaScript oder TypeScript in einem isolierten QuickJS-WASI-Worker-Thread aus.
• Jedes aktivierte, für den Katalog geeignete Tool (OpenClaw-Kern, Plugin, MCP, Client) wird als eigenständiges Modell-Tool verborgen und innerhalb des Gastprogramms über ALL_TOOLS und tools bereitgestellt.
• Die Beschreibung von exec enthält einen begrenzten Schnellindex exakter OpenClaw-/Plugin- Katalog-IDs, kompakte Eingabehinweise und kompakte deklarierte Ausgabehinweise, wenn ein vertrauenswürdiges Tool ein Ausgabeschema bereitstellt. Beschreibungen, vollständige Schemas, MCP-Einträge und überzählige Einträge werden ausgelassen; die Katalogsuche auf Gastseite bleibt die Ausweichlösung.
• Gastcode durchsucht den verborgenen Katalog, beschreibt das Schema eines Tools und ruft ein Tool über denselben Ausführungspfad auf, den normale Agent-Durchläufe verwenden (Richtlinien, Genehmigungen, Hooks und Telemetrie gelten weiterhin).
• MCP-Tools werden unter dem Namensraum MCP gruppiert; im Code-Modus ist dies die einzige unterstützte Möglichkeit, sie aufzurufen.
• wait setzt einen angehaltenen Code-Modus-Durchlauf fort, wenn verschachtelte Tool-Aufrufe noch ausstehen.

​

Gründe für die Verwendung

• Kleinere Prompt-Oberfläche: Provider erhalten zwei Steuerungs-Tools, einen begrenzten Index nativer Tools und nur die wenigen erforderlichen direkten Tools anstelle von Dutzenden oder Hunderten vollständiger Tool-Schemas.
• Bessere Orchestrierung: Das Modell kann Schleifen, Verknüpfungen, kleine Transformationen, bedingte Logik und parallele verschachtelte Tool-Aufrufe innerhalb einer Codezelle verwenden.
• Weniger Modell-Roundtrips: Ein deklarierter Ausgabevertrag ermöglicht dem Modell, ein Tool-Ergebnis in einem einzigen exec aufzurufen und zu transformieren; unbekannte Ausgaben bleiben zunächst unverarbeitet.
• Provider-neutral: Funktioniert für OpenClaw-, Plugin-, MCP- und Client-Tools, ohne von der nativen Codeausführung eines Providers abhängig zu sein.
• Sicheres Fehlschlagen: Wenn der Code-Modus aktiviert, die QuickJS-WASI-Laufzeit jedoch nicht verfügbar ist, schlägt der Durchlauf fehl, statt stillschweigend auf die breite direkte Bereitstellung von Tools zurückzufallen.

​

Schnellstart

​

Code-Modus aktivieren

{
  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,
    },
  },
}

​

Vorgehen des Modells

const [shipmentTool] = await tools.search("list shipments");
const shipments = await tools.callValue(shipmentTool.id, {});
return shipments.filter((shipment) => !shipment.paid && shipment.tons > 10);

​

Aktive Oberfläche überprüfen

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

​

Swarm zur Agenten-Auffächerung verwenden

​

Technischer Überblick

​

Laufzeitstatus

​

Umfang

​

Begriffe

• Code-Modus: der OpenClaw-Laufzeitmodus, der katalogkompatible Modell- Tools verbirgt und exec, wait sowie erforderliche ausschließlich direkte Tools bereitstellt.
• Gastlaufzeit: die QuickJS-WASI-JavaScript-VM, die Modellcode auswertet.
• Host-Bridge: die schmale JSON-kompatible Callback-Oberfläche vom Gastcode zurück zu OpenClaw.
• Katalog: die auf den Durchlauf beschränkte Liste effektiver Tools nach der normalen Auflösung von Tool- Richtlinien, Plugins, MCP und Client-Tools.
• Verschachtelter Tool-Aufruf: ein Tool-Aufruf, der aus Gastcode über die Host- Bridge erfolgt.
• Snapshot: serialisierter Zustand der QuickJS-WASI-VM, der gespeichert wird, damit wait einen angehaltenen Code-Modus-Durchlauf fortsetzen kann.

​

Konfiguration

​

Aktivierung

1. Lösen Sie die Richtlinie für Agent, Modell, Provider, Sandbox, Kanal, Absender und Ausführung auf.
2. Erstellen Sie die effektive OpenClaw-Werkzeugliste und fügen Sie zulässige Plugin-, MCP- und Client-Werkzeuge hinzu.
3. Wenden Sie die Zulassungs-/Ablehnungsrichtlinie an.
4. Wenn tools.codeMode.enabled false ist, fahren Sie mit der normalen Werkzeugbereitstellung fort.
5. Wenn die Funktion aktiviert ist und Werkzeuge für die Ausführung aktiv sind, behalten Sie erforderliche, ausschließlich direkte Werkzeuge bei und registrieren Sie jedes katalogfähige effektive Werkzeug im Code-Mode- Katalog.
6. Entfernen Sie die katalogisierten Werkzeuge aus der für das Modell sichtbaren Liste; fügen Sie exec und wait neben den beibehaltenen, ausschließlich direkten Werkzeugen hinzu.

​

Für das Modell sichtbare Werkzeuge

​

exec

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

• Eines von code oder command darf nicht leer sein.
• code ist das dokumentierte, für das Modell sichtbare Feld.
• command wird als exec-kompatibler Alias für Hook-Richtlinien und vertrauenswürdige Umschreibungen akzeptiert (das normale OpenClaw-Shell-exec-Werkzeug verwendet ebenfalls ein command- Feld); wenn beide vorhanden sind, müssen die Werte übereinstimmen.
• language verwendet standardmäßig "javascript"; das Schema stellt es als flache String-Aufzählung ("javascript" | "typescript") bereit, nicht als oneOf- bzw. anyOf-Union, da einige Provider solche Strukturen ablehnen.
• Wenn language den Wert "typescript" hat, transpiliert OpenClaw vor der Auswertung.
• exec lehnt import, require, dynamische Importe und Module-Loader- Muster ab.
• exec stellt die normale Shell-Implementierung von exec niemals rekursiv bereit.
• Äußere Code-Mode-Hook-Ereignisse für exec enthalten toolKind: "code_mode_exec" und toolInputKind: "javascript" | "typescript" (sofern bekannt), damit Richtlinien Code-Mode-Zellen von Shell-artigen exec-Aufrufen unterscheiden können, die denselben Werkzeugnamen verwenden.

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 wertet Code bis zum Abschluss, Fehlschlag oder Anhalten aus.
2. Beim Anhalten erstellt OpenClaw einen Snapshot der QuickJS-VM und zeichnet ausstehende Host- Aufgaben auf.
3. Wenn ausstehende Aufgaben abgeschlossen sind, stellt wait den VM-Snapshot wieder her und registriert Host-Callbacks anhand stabiler Namen erneut.
4. OpenClaw übermittelt Ergebnisse verschachtelter Werkzeuge an die wiederhergestellte VM und arbeitet ausstehende QuickJS-Aufgaben ab.
5. wait gibt completed, failed oder ein weiteres waiting-Ergebnis zurück.

• runId unbekannt oder sein Snapshot bereits abgelaufen ist.
• sich der Aufrufer nicht im selben Ausführungs-/Sitzungsbereich wie die angehaltene Ausführung befindet.
• für diese runId bereits eine wait ausgeführt wird.
• die QuickJS-WASI-Wiederherstellung fehlschlägt.
• die Fortsetzung maxOutputBytes oder maxSnapshotBytes überschreiten würde.

​

Gast-Laufzeit-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" | "mcp" | "client";
  sourceName?: string;
  input: string;
  output?: string;
};

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

type ToolCatalog = {
  search(query: string, options?: { limit?: number }): Promise<ToolCatalogEntry[]>;
  describe(id: string): Promise<ToolCatalogEntryWithSchema>;
  callValue(id: string, input?: unknown): Promise<unknown>;
  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.callValue(fileRead.id, { path: "README.md" });

// Wenn der ausgeblendete Katalog einen eindeutigen `web_search`-Eintrag enthält:
const hits = await tools.web_search({ query: "OpenClaw code mode" });

​

Deklarierte Ausgabeverträge

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

const listed = await tools.conversations_list({ query: "build bot" });
const target = listed.conversations.find((item) => item.label === "Build bot");
if (!target) throw new Error("Konversation nicht gefunden");
return await tools.conversations_send({
  conversationRef: target.conversationRef,
  message: "Build abgeschlossen.",
});

• Beschreiben Sie den exakten JSON-kompatiblen Wert details, nicht gerenderte content-Blöcke oder eine Provider-Hülle.
• Nehmen Sie jede nicht auslösende Erfolgs- oder Fehlervariante auf. Lassen Sie outputSchema weg, wenn das Werkzeug kein stabiles strukturiertes Ergebnis besitzt.
• Schließen Sie Objektebenen mit { additionalProperties: false }, um einen vollständigen Schnellindex-Hinweis zu erhalten. Offene, übergroße oder anderweitig partielle Schemata bleiben über tools.describe(...) verfügbar, ermöglichen jedoch keine Feldverwendung in einem Durchlauf.
• OpenClaw kompiliert das Schema vor der Ausführung des Werkzeugs und validiert anschließend das endgültige details nach den normalen Werkzeug-Hooks und bevor ein Katalogaufruf zurückkehrt. Bei einem ungültigen Schema kann das Werkzeug nicht ausgeführt werden; eine Abweichung schlägt fehl, ohne den Wert auszugeben.
• Kompakte Hinweise sind deterministisch und begrenzt. tools.describe(...) stellt das vollständige vertrauenswürdige Schema bereit, wenn der kompakte Hinweis nicht ausreicht.
• Installierter Plugin-Code ist bereits vertrauenswürdiger lokaler Code. Metadaten von entfernten MCPs und Clients bleiben nicht vertrauenswürdig und können diese Schnellindex-Hinweise nicht aktivieren.

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: "Gateway-Protokolle untersuchen",
});

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 {
  /** Diesen API-Header im TypeScript-Stil zurückgeben. */
  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;

  /**
   * Ein GitHub-Issue erstellen.
   * @param owner Repository-Eigentümer
   * @param repo Repository-Name
   * @param title Issue-Titel
   */
  function createIssue(input: {
    owner: string;
    repo: string;
    title: string;
    body?: string;
  }): Promise<McpToolResult>;
}

​

Interne Namespaces

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

​

Lebenszyklus der Registry

1. Ein vertrauenswürdiger Loader ruft registerCodeModeNamespaceForPlugin(pluginId, registration) auf.
2. Der Codemodus erstellt das verborgene ToolSearchRuntime für den Lauf und liest dessen laufbezogenen Katalog.
3. createCodeModeNamespaceRuntime(ctx, catalog) behält nur Registrierungen bei, deren requiredToolNames sämtlich sichtbar sind und demselben pluginId gehören.
4. Jeder sichtbare Namespace ruft createScope(ctx) für den aktuellen Lauf auf und erhält dabei Laufkontext wie agentId, sessionKey, sessionId, runId, Konfiguration und Abbruchstatus.
5. Bereichsdaten werden in einen einfachen Deskriptor serialisiert und als direkte globale Variablen sowie als namespaces.<globalName> in QuickJS injiziert.
6. Gastaufrufe werden über die Worker-Brücke angehalten, lösen den Namespace-Pfad auf dem Host auf, ordnen den Aufruf einem deklarierten, dem Plugin gehörenden Katalogwerkzeug zu und führen dieses Werkzeug über ToolSearchRuntime.callExactId aus.
7. Bereite Namespace-Brückenaufrufe werden innerhalb des aktiven exec-/wait-Aufrufs automatisch abgearbeitet; wenn beim Timeout noch Namespace-Arbeit aussteht oder der Gast explizit abgibt, setzt wait dieselbe Namespace-Laufzeit später fort.
8. Beim Zurücksetzen oder Deinstallieren eines Plugins wird clearCodeModeNamespacesForPlugin(pluginId) aufgerufen, damit veraltete globale Variablen einen fehlgeschlagenen Plugin-Ladevorgang nicht überdauern.

​

Registrierungsstruktur

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

const pluginId = "github";

registerCodeModeNamespaceForPlugin(pluginId, {
  id: "github-issues",
  globalName: "Issues",
  description: "GitHub-Issue-Hilfsfunktionen für das aktuelle Repository.",
  requiredToolNames: ["github_list_issues", "github_update_issue"],
  prompt: "Verwenden Sie Issues.list(params) und 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: () => ({
  // Falsch: Dies umgeht den Lebenszyklus des Katalogwerkzeugs und wird abgelehnt.
  list: async () => githubClient.listIssues(),
});

​

Eigentümerschaft und Sichtbarkeit

• Jedes erforderliche Werkzeug muss im Laufkatalog vorhanden sein.
• Jedes erforderliche Werkzeug muss über sourceName === pluginId verfügen.
• Der Namespace wird ausgeblendet, wenn ein erforderliches Werkzeug fehlt oder einem anderen Plugin gehört.
• Jeder aufrufbare Pfad darf nur auf ein Werkzeug verweisen, das in requiredToolNames genannt ist.

​

Regeln für die Bereichsserialisierung

• unverarbeitete Funktionen
• zyklische Objektgraphen
• unsichere Pfadsegmente: __proto__, constructor, prototype, leere Schlüssel oder Schlüssel, die das interne Pfadtrennzeichen enthalten
• globalName-Werte, die keine JavaScript-Bezeichner sind
• globalName-Kollisionen mit integrierten globalen Variablen des Codemodus wie tools, namespaces, text, json, yield_control, MCP, API, ALL_TOOLS oder __openclaw*

​

Prompts

{
  description: "Hilfsfunktionen für den Dienst zur Produktion fiktionaler Inhalte.",
  prompt:
    "Verwenden Sie Fictions.riskAudit(), Fictions.promoteIfReady(id, status) und Fictions.unpaidOver(amount).",
}

​

Bereinigung

clearCodeModeNamespacesForPlugin(pluginId);

​

Testprüfliste

• Namespace-Prompttext wird nur angezeigt, wenn die zugrunde liegenden Tools sichtbar sind
• gleichnamige Tools aus einem anderen sourceName legen den Namespace nicht offen
• unverarbeitete Bereichsfunktionen werden abgelehnt
• gefälschte Namespace-IDs und gefälschte Pfade werden abgelehnt
• aufrufbare Pfade können nicht auf nicht deklarierte Tools verweisen
• verschachtelte Objekte und gemeinsam verwendete Referenzen werden korrekt serialisiert
• Namespace-Aufrufe werden über Katalog-Tools ausgeführt und geben JSON-sichere Details zurück
• Fehler können durch Gastcode abgefangen werden
• ausgesetzte Namespace-Aufrufe werden über wait fortgesetzt
• ein Plugin-Rollback löscht die zugehörigen Namespace-Registrierungen

​

Ausgabe-API

• text(value) fügt dem Array output eine menschenlesbare Ausgabe hinzu.
• json(value) fügt nach einer JSON-kompatiblen Serialisierung ein strukturiertes Ausgabeelement hinzu.
• Der endgültige Rückgabewert des Gastcodes wird in einem completed-Ergebnis zu value.

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

​

Tool-Katalog

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

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

​

Interaktion mit der Tool-Suche

• OpenClaw stellt tool_search_code, tool_search, tool_describe oder tool_call nicht als für das Modell sichtbare Tools bereit.
• Dasselbe Katalogisierungskonzept wird in die Gastlaufzeit verlagert.
• Die Gastlaufzeit erhält kompakte ALL_TOOLS-Metadaten sowie Hilfsfunktionen zum Suchen, Beschreiben und Aufrufen von Nicht-MCP-Tools.
• MCP-Aufrufe verwenden anstelle von tools.call(...) den generierten Namespace MCP und dessen $api()-Header.
• Verschachtelte Aufrufe werden über denselben OpenClaw-Ausführungspfad weitergeleitet, den die Tool-Suche verwendet.

​

Tool-Namen und Kollisionen

• tools.call("openclaw:core:exec", input) kann das Shell-Ausführungs-Tool aufrufen, wenn die Richtlinie dies zulässt.
• tools.exec(...) wird nur installiert, wenn der Shell-Ausführungs-Katalogeintrag einen eindeutigen sicheren Namen hat.
• das Codemodus-Tool exec ist niemals rekursiv über tools verfügbar.

​

Verschachtelte Tool-Ausführung

​

Lebenszyklus von Lauf und Snapshot

• Ein waiting-Ergebnis speichert den QuickJS-Snapshot, ausstehende Bridge-Anfragen und Bereichsmetadaten (Agentenlauf-ID, Sitzungs-ID/-Schlüssel), bis wait den Lauf fortsetzt oder er abläuft.
• Ablauf, eine falsche Sitzung, ein falscher Lauf und unbekannte/bereits in Fortsetzung befindliche runId-Werte erzeugen keinen eigenen terminalen Status; sie werden als failed-Ergebnis (code: "invalid_input") mit einer Meldung wie code mode run is unavailable or expired. oder code mode run belongs to a different session. ausgegeben.
• Der Snapshot eines Laufs wird aus der Map entfernt, sobald er den Status completed oder failed erreicht, oder beim Herunterfahren des Gateways verworfen (einen Neustart überlebt nichts: Dies ist flüchtiger Laufzeitzustand).
• Für schreibgeschützte Arbeit kann exec den Wert restartSafe: true festlegen. OpenClaw lehnt dann Katalogaufrufe mit Nebenwirkungen und Plugin-Namespaces vor der Ausführung ab und kennzeichnet ausgesetzte Ergebnisse als sicher wiederholbar. Wenn ein Neustart wait unterbricht, rekonstruiert die Neustartwiederherstellung den Turn aus dem Transkript, anstatt den prozesslokalen Snapshot wiederherzustellen. Der Wiederherstellungs-Turn selbst bleibt auf auditierte schreibgeschützte Kern-Tools und ausdrücklich als sicher wiederholbar gekennzeichnete Plugin-Tools beschränkt.
• OpenClaw begrenzt die Anzahl gleichzeitig ausgesetzter Läufe pro Prozess auf 64 und lehnt neue Aussetzungen über dieser Grenze mit too many suspended code mode runs. ab.

​

QuickJS-WASI-Laufzeit

​

TypeScript

​

Sicherheitsgrenze

• führt QuickJS-WASI außerhalb der Haupt-Ereignisschleife in einem Worker-Thread aus
• lädt quickjs-wasi als direkte Abhängigkeit, nicht über Codex oder ein transitives Paket
• kein Dateisystem, Netzwerk, Unterprozess, Modulimport, keine Umgebungsvariablen und keine globalen Hostobjekte im Gast
• verwendet QuickJS-Speicher- und Unterbrechungsgrenzen sowie ein von einem übergeordneten Prozess durchgesetztes Echtzeitlimit
• erzwingt Grenzwerte für Ausgabe, Snapshots, Protokolle und ausstehende Aufrufe
• serialisiert Host-Bridge-Werte über einen eng begrenzten JSON-Adapter
• wandelt Hostfehler in einfache Gastfehler um, niemals in Objekte aus dem Host-Realm
• verwirft Snapshots bei Zeitüberschreitung, Abbruch, Sitzungsende oder Ablauf
• lehnt rekursiven Zugriff auf exec, wait und Steuerungs-Tools der Tool-Suche ab
• verhindert, dass Kollisionen von Kurznamen Katalog-Hilfsfunktionen verdecken

​

Fehlercodes

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

​

Telemetrie

​

Fehlerbehebung

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

​

Implementierungsstruktur

• Konfigurationsvertrag: tools.codeMode
• Katalog-Builder: effektive Tools in kompakte Einträge und ID-Zuordnung überführen
• Modelloberflächen-Adapter: sichtbare Tools durch Steuerungs-/Direkt-Tools ersetzen
• QuickJS-WASI-Laufzeitadapter: laden, auswerten, Snapshot erstellen, wiederherstellen, freigeben
• Worker-Supervisor: Zeitüberschreitung, Abbruch, Absturzisolierung
• Bridge-Adapter: JSON-sichere Host-Callbacks und Ergebnisübermittlung
• TypeScript-Transformationsadapter
• Snapshot-Speicher: TTL, Größenbegrenzungen, Lauf-/Sitzungsbereich
• Trajektionsprojektion für verschachtelte Tool-Aufrufe
• Telemetriezähler und Diagnosefunktionen

​

Validierungscheckliste

• Eine deaktivierte Konfiguration lässt die bestehende Tool-Bereitstellung unverändert
• Eine Objektkonfiguration ohne enabled: true lässt den Code-Modus deaktiviert
• Eine aktivierte Konfiguration stellt dem Modell exec, wait und ausschließlich erforderliche Nur-Direkt-Tools bereit, wenn Tools für den Lauf aktiv sind
• Unverarbeitete Läufe ohne Tools, disableTools und leere Zulassungslisten lösen keine Erzwingung der Code-Modus-Payload aus
• Alle für den Katalog geeigneten effektiven Nicht-MCP-Tools erscheinen in ALL_TOOLS
• Nur-Direkt-Tools bleiben für das Modell sichtbar und erscheinen nicht in ALL_TOOLS
• Abgelehnte Tools erscheinen nicht in ALL_TOOLS
• tools.search, tools.describe, tools.callValue und tools.call funktionieren für OpenClaw-Tools
• API.list("mcp") und API.read("mcp/<server>.d.ts") stellen MCP-Deklarationen im TypeScript-Stil ohne Bridge-/Tool-Aufruf bereit
• Der MCP-Namespace $api() bleibt als Inline-Fallback für Schemas verfügbar
• MCP-Namespace-Aufrufe funktionieren für sichtbare MCP-Tools mit einer Objekteingabe, während direkte MCP-Katalogeinträge in tools.* fehlen
• Steuerungs-Tools von Tool Search sind sowohl auf der Modelloberfläche als auch im verborgenen Katalog ausgeblendet
• Verschachtelte Aufrufe bewahren das Genehmigungs- und Hook-Verhalten
• Shell-exec ist für das Modell ausgeblendet, kann jedoch bei entsprechender Zulassung über die Katalog-ID aufgerufen werden
• Rekursive Code-Modus-exec und wait können nicht aus Gastcode aufgerufen werden
• TypeScript-Eingaben werden transformiert und ausgewertet, ohne TypeScript in deaktivierten oder reinen JavaScript-Pfaden zu laden
• Zugriffe auf import, require, Dateisystem, Netzwerk und Umgebung schlagen fehl
• Endlosschleifen führen zu einer Zeitüberschreitung und können den Gateway nicht blockieren
• Fehler aufgrund der Speicherbegrenzung beenden die Gast-VM
• Ausgabe- und Snapshot-Begrenzungen werden für abgeschlossene und ausgesetzte Aufrufe durchgesetzt
• wait setzt einen ausgesetzten Snapshot fort und gibt den endgültigen Wert zurück
• Abgelaufene, abgebrochene, einer falschen Sitzung zugeordnete und unbekannte runId-Werte schlagen fehl
• Transkriptwiedergabe und -persistenz bewahren Steuerungsaufrufe des Code-Modus
• Transkript und Telemetrie stellen verschachtelte Tool-Aufrufe eindeutig dar

​

E2E-Testplan

1. Starten Sie einen Gateway mit tools.codeMode.enabled: false.
2. Senden Sie einen Agentendurchlauf mit einer kleinen Menge direkter Tools.
3. Stellen Sie sicher, dass die für das Modell sichtbaren Tools unverändert sind.
4. Starten Sie mit tools.codeMode.enabled: true neu.
5. Senden Sie einen Agentendurchlauf mit OpenClaw-, Plugin-, MCP- und Client-Test-Tools.
6. Stellen Sie sicher, dass die für das Modell sichtbare Tool-Liste aus exec, wait sowie ausschließlich den konfigurierten Nur-Direkt-Tools besteht.
7. Lesen Sie in exec den Wert ALL_TOOLS und stellen Sie sicher, dass die für den Katalog geeigneten effektiven Test- Tools vorhanden sind, während Nur-Direkt-Tools fehlen.
8. Rufen Sie in exec OpenClaw-/Plugin-/Client-Tools über tools.search, tools.describe und tools.callValue (oder unverarbeitetes tools.call) auf.
9. Rufen Sie in exec die Werte API.list("mcp") und API.read("mcp/<server>.d.ts") auf und stellen Sie sicher, dass die Deklarationsdateien sichtbare MCP-Tools beschreiben.
10. Rufen Sie in exec MCP-Tools über MCP.<server>.<tool>({ ...input }) auf und stellen Sie sicher, dass direkte MCP-Katalogeinträge in ALL_TOOLS und tools.* fehlen.
11. Stellen Sie sicher, dass abgelehnte Tools fehlen und nicht über eine erratene ID aufgerufen werden können.
12. Starten Sie einen verschachtelten Tool-Aufruf, der aufgelöst wird, nachdem exec den Wert waiting zurückgibt.
13. Rufen Sie wait auf und stellen Sie sicher, dass die wiederhergestellte VM das Tool-Ergebnis empfängt.
14. Stellen Sie sicher, dass die endgültige Antwort eine nach der Wiederherstellung erzeugte Ausgabe enthält.
15. Stellen Sie sicher, dass Zeitüberschreitung, Abbruch und Snapshot-Ablauf den Laufzeitstatus bereinigen.
16. Exportieren Sie die Trajektorie und stellen Sie sicher, dass verschachtelte Aufrufe unter dem übergeordneten Code-Modus-Aufruf sichtbar sind.

​

Verwandte Themen

• Swarm für die Agentenorchestrierung mit Auffächerung aus Code-Modus-Skripten
• Tool Search
• Agentenlaufzeiten
• Exec-Tool
• Codeausführung