コードモード

• Codex Code Mode は Codex コーディングハーネス内で実行されます。その exec ツールは freeform-grammar ツールです。モデルは生の JavaScript ソース（任意で実行オプション用の // @exec: {...} プラグマ行を前置）を書き、それが Deno/V8 ランタイムで実行されます。
• OpenClaw コードモードは汎用 OpenClaw エージェントランタイムで実行され、tools.codeMode.enabled: true が設定されていない限り無効です。その exec ツールは JSON の { code, language } ペイロードを受け取り、QuickJS-WASI ワーカーで実行されます。

​

何をするか

• モデルから見えるツール一覧は、正確に exec と wait になります。
• exec は、モデルが生成した JavaScript または TypeScript を、隔離された QuickJS-WASI ワーカースレッド内で評価します。
• それ以外の有効化されたすべてのツール（OpenClaw コア、Plugin、MCP、クライアント）はモデルプロンプトから隠され、ゲストプログラム内では ALL_TOOLS と tools を通じて公開されます。
• ゲストコードは隠されたカタログを検索し、ツールのスキーマを記述し、通常のエージェントターンで使われるものと同じ実行経路（ポリシー、承認、フック、テレメトリはすべて引き続き適用）を通じてツールを呼び出します。
• MCP ツールは MCP 名前空間の下にグループ化されます。コードモードでは、これがそれらを呼び出す唯一のサポートされた方法です。
• ネストされたツール呼び出しがまだ保留中の場合、wait は一時停止されたコードモード実行を再開します。

​

使用する理由

• 小さなプロンプトサーフェス: プロバイダーは、数十または数百の完全なツールスキーマではなく、2 つの制御ツールを受け取ります。
• よりよいオーケストレーション: モデルは 1 つのコードセル内で、ループ、結合、小さな変換、条件ロジック、並列のネストされたツール呼び出しを使用できます。
• プロバイダー中立: プロバイダー固有のコード実行に依存せず、OpenClaw、Plugin、MCP、クライアントツールで動作します。
• フェイルクローズ: コードモードが有効でも QuickJS-WASI ランタイムを利用できない場合、広い直接ツール公開へ暗黙にフォールバックするのではなく、実行は失敗します。

​

有効化する

{
  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

​

技術ツアー

​

ランタイム状態

​

スコープ

​

用語

• コードモード: 通常のモデルツールを隠し、exec と wait だけを公開する OpenClaw ランタイムモード。
• ゲストランタイム: モデルコードを評価する QuickJS-WASI JavaScript VM。
• ホストブリッジ: ゲストコードから OpenClaw へ戻る、狭い JSON 互換のコールバックサーフェス。
• カタログ: 通常のツールポリシー、Plugin、MCP、クライアントツールの解決後に有効となる、実行スコープのツール一覧。
• ネストされたツール呼び出し: ホストブリッジを通じてゲストコードから行われるツール呼び出し。
• スナップショット: wait が一時停止されたコードモード実行を継続できるように保存された、シリアライズ済み QuickJS-WASI VM 状態。

​

設定

​

アクティベーション

1. エージェント、モデル、プロバイダー、サンドボックス、チャネル、送信者、実行ポリシーを解決します。
2. 対象となる Plugin、MCP、クライアントツールを追加して、有効な OpenClaw ツール一覧を構築します。
3. 許可/拒否ポリシーを適用します。
4. tools.codeMode.enabled が false の場合、通常のツール公開を続行します。
5. 有効で、実行でツールがアクティブな場合、有効なツールをコードモードカタログに登録します。
6. モデルから見える一覧からすべての通常ツールを削除し、exec と wait を追加します。

​

モデルから見えるツール

​

exec

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

• code または command のどちらか一方は空でない必要があります。
• code はドキュメント化されたモデル向けフィールドです。
• command は、フックポリシーと信頼済みの書き換え用に exec 互換のエイリアスとして受け入れられます（通常の OpenClaw シェル exec ツールも command フィールドを使用します）。両方が存在する場合、値は一致している必要があります。
• language のデフォルトは "javascript" です。一部のプロバイダーはそれらの形状を拒否するため、スキーマでは oneOf/anyOf ユニオンではなく、フラットな文字列 enum（"javascript" | "typescript"）として公開されます。
• language が "typescript" の場合、OpenClaw は評価前にトランスパイルします。
• exec は import、require、動的 import、モジュールローダーパターンを拒否します。
• exec は通常のシェル exec 実装を再帰的に公開することはありません。
• 外側のコードモード exec フックイベントは toolKind: "code_mode_exec" と toolInputKind: "javascript" | "typescript"（既知の場合）を持つため、ポリシーは同じツール名を共有するシェル形式の exec 呼び出しとコードモードセルを区別できます。

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 は、完了、失敗、または中断までコードを評価します。
2. 中断時に、OpenClaw は QuickJS VM のスナップショットを取得し、保留中のホスト作業を記録します。
3. 保留中の作業が確定すると、wait は VM スナップショットを復元し、安定した名前でホストコールバックを再登録します。
4. OpenClaw はネストされたツール結果を復元された VM に届け、QuickJS の保留中ジョブをドレインします。
5. wait は completed、failed、または別の waiting 結果を返します。

• runId が不明、またはそのスナップショットがすでに期限切れである。
• 呼び出し元が、中断された実行と同じ実行/セッションスコープ内にいない。
• その runId に対して wait がすでに実行中である。
• QuickJS-WASI の復元に失敗する。
• 再開すると maxOutputBytes または maxSnapshotBytes を超える。

​

ゲストランタイム 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;
};

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

​

内部名前空間

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

​

レジストリライフサイクル

1. 信頼済みローダーが registerCodeModeNamespaceForPlugin(pluginId, registration) を呼び出します。
2. コードモードは、実行用の隠し ToolSearchRuntime を作成し、その実行スコープのカタログを読み取ります。
3. createCodeModeNamespaceRuntime(ctx, catalog) は、requiredToolNames がすべて表示可能で、同じ pluginId に所有されている登録だけを保持します。
4. 表示可能な各名前空間は、現在の実行に対して createScope(ctx) を呼び出し、agentId、sessionKey、sessionId、runId、config、中止状態などの実行コンテキストを受け取ります。
5. スコープデータはプレーンな記述子にシリアライズされ、直接のグローバルおよび namespaces.<globalName> として QuickJS に注入されます。
6. ゲスト呼び出しはワーカーブリッジを通じて中断し、ホスト上で名前空間パスを解決し、その呼び出しを宣言済みの Plugin 所有カタログツールにマップし、ToolSearchRuntime.callExactId を通じてそのツールを実行します。
7. 準備ができている名前空間ブリッジ呼び出しは、アクティブな exec/wait 呼び出し内で自動的にドレインされます。タイムアウト時に名前空間作業がまだ保留中の場合、またはゲストが明示的に yield した場合、wait が後で同じ名前空間ランタイムを再開します。
8. Plugin のロールバックまたはアンインストールは clearCodeModeNamespacesForPlugin(pluginId) を呼び出し、失敗した Plugin ロード後に古いグローバルが残らないようにします。

​

登録形状

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

​

所有権と可視性

• 必須ツールはすべて実行カタログ内に存在しなければならない
• 必須ツールはすべて sourceName === pluginId でなければならない
• 必須ツールが存在しない、または別の Plugin に所有されている場合、名前空間は非表示になる
• 各呼び出し可能パスは、requiredToolNames に含まれる名前のツールのみを対象にできる

​

スコープシリアライズルール

• 生の関数
• 循環オブジェクトグラフ
• 安全でないパスセグメント: __proto__、constructor、prototype、空キー、または内部パス区切り文字を含むキー
• JavaScript 識別子ではない globalName 値
• tools、namespaces、text、json、yield_control、MCP、API、ALL_TOOLS、__openclaw* などの組み込みコードモードグローバルとの globalName 衝突

​

プロンプト

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

​

クリーンアップ

clearCodeModeNamespacesForPlugin(pluginId);

​

テストチェックリスト

• 名前空間のプロンプトテキストは、裏付けとなるツールが表示されている場合にのみ現れる
• 別の sourceName にある同名ツールは名前空間を公開しない
• 生のスコープ関数は拒否される
• 偽造された名前空間 ID と偽造されたパスは拒否される
• 呼び出し可能なパスは未宣言のツールを対象にできない
• ネストされたオブジェクトと共有参照が正しくシリアライズされる
• 名前空間呼び出しはカタログツールを通じて実行され、JSON セーフな詳細を返す
• 失敗はゲストコードで捕捉できる
• 中断された名前空間呼び出しは wait を通じて再開される
• Pluginのロールバックは所有元の名前空間登録をクリアする

​

出力 API

• text(value) は人間が読める出力を output 配列に追加します。
• json(value) は JSON 互換のシリアライズ後に構造化された出力項目を追加します。
• ゲストコードの最終戻り値は、completed 結果内の value になります。

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

​

ツールカタログ

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

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

​

ツール検索との相互作用

• OpenClaw は tool_search_code、tool_search、tool_describe、または tool_call をモデルに表示されるツールとして公開しない。
• 同じカタログ化の考え方がゲストランタイム内へ移る。
• ゲストランタイムは、非 MCP ツール向けにコンパクトな ALL_TOOLS メタデータと検索/説明/呼び出しヘルパーを受け取る。
• MCP 呼び出しは、tools.call(...) ではなく、生成された MCP 名前空間とその $api() ヘッダーを使う。
• ネストされた呼び出しは、ツール検索が使うのと同じOpenClawエグゼキュータパスを通じてディスパッチされる。

​

ツール名と衝突

• ポリシーで許可されていれば、tools.call("openclaw:core:exec", input) はシェル exec ツールを呼び出せる。
• tools.exec(...) は、シェル exec カタログエントリに曖昧でない安全な名前がある場合にのみインストールされる。
• コードモードの exec ツールは、tools を通じて再帰的に利用できない。

​

ネストされたツール実行

​

実行とスナップショットのライフサイクル

• waiting 結果は、wait が再開するか期限切れになるまで、QuickJS スナップショット、保留中のブリッジリクエスト、スコープメタデータ（エージェント実行 ID、セッション ID/キー）を保存する。
• 期限切れ、セッション違い、実行違い、不明/すでに再開中の runId 値は、個別の終端ステータスを生成しない。code mode run is unavailable or expired. や code mode run belongs to a different session. のようなメッセージを伴う failed 結果（code: "invalid_input"）として表面化する。
• 実行のスナップショットは、completed または failed に落ち着いた時点でマップから削除されるか、Gateway シャットダウン時に破棄される（再起動後には設計上何も残らない。これは一時的なランタイム状態）。
• OpenClaw はプロセスごとの同時中断実行数を 64 に制限し、その上限を超える新しい中断を too many suspended code mode runs. で拒否する。

​

QuickJS-WASI ランタイム

​

TypeScript

​

セキュリティ境界

• メインイベントループの外側、ワーカースレッド内で QuickJS-WASI を実行する
• Codex や推移的パッケージ経由ではなく、直接依存関係として quickjs-wasi を読み込む
• ゲスト内にファイルシステム、ネットワーク、サブプロセス、モジュール import、環境変数、ホストグローバルオブジェクトはない
• QuickJS のメモリ制限と割り込み制限に加え、親プロセスの実時間タイムアウトを使う
• 出力、スナップショット、ログ、保留中呼び出しの上限を強制する
• 狭い JSON アダプターを通じてホストブリッジ値をシリアライズする
• ホストエラーをプレーンなゲストエラーに変換し、ホストレルムのオブジェクトは渡さない
• タイムアウト、中止、セッション終了、期限切れ時にスナップショットを破棄する
• exec、wait、ツール検索制御ツールへの再帰アクセスを拒否する
• 利便名の衝突がカタログヘルパーをシャドーイングするのを防ぐ

​

エラーコード

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

​

テレメトリ

​

デバッグ

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

​

実装レイアウト

• config 契約: tools.codeMode
• カタログビルダー: 有効なツールをコンパクトエントリと ID マップへ
• モデルサーフェスアダプター: 表示ツールを exec と wait に置き換える
• QuickJS-WASI ランタイムアダプター: 読み込み、eval、スナップショット、復元、破棄
• ワーカースーパーバイザー: タイムアウト、中止、クラッシュ分離
• ブリッジアダプター: JSON セーフなホストコールバックと結果配信
• TypeScript 変換アダプター
• スナップショットストア: TTL、サイズ上限、実行/セッションスコープ
• ネストされたツール呼び出しの軌跡投影
• テレメトリカウンターと診断

​

検証チェックリスト

• 無効な設定では、既存のツール公開は変更されない
• enabled: true のないオブジェクト設定では、コードモードは無効のままになる
• 有効な設定では、実行中にツールがアクティブな場合、モデルには exec と wait のみが公開される
• 生のツールなし実行、disableTools、空の許可リストは、コードモードのペイロード強制をトリガーしない
• 有効な非 MCP ツールはすべて ALL_TOOLS に表示される
• 拒否されたツールは ALL_TOOLS に表示されない
• tools.search、tools.describe、tools.call は OpenClaw ツールで動作する
• API.list("mcp") と API.read("mcp/<server>.d.ts") は、ブリッジやツール呼び出しなしで TypeScript 形式の MCP 宣言を公開する
• MCP 名前空間 $api() は、スキーマ用のインラインフォールバックとして引き続き利用できる
• MCP 名前空間呼び出しは、1 つのオブジェクト入力を持つ可視 MCP ツールで動作する一方、直接の MCP カタログエントリは tools.* には存在しない
• ツール検索の制御ツールは、モデルサーフェスと非表示カタログの両方から隠される
• ネストされた呼び出しは承認とフックの動作を保持する
• シェル exec はモデルからは隠されるが、許可されている場合はカタログ ID で呼び出せる
• 再帰的なコードモードの exec と wait はゲストコードから呼び出せない
• TypeScript 入力は、無効なパスまたは JavaScript のみのパスで TypeScript を読み込まずに変換および評価される
• import、require、ファイルシステム、ネットワーク、環境へのアクセスは失敗する
• 無限ループはタイムアウトし、Gateway をブロックできない
• メモリ上限の失敗はゲスト VM を終了する
• 完了した呼び出しと一時停止された呼び出しの両方で、出力とスナップショットの上限が強制される
• wait は一時停止されたスナップショットを再開し、最終値を返す
• 期限切れ、中止済み、セッション違い、不明な runId 値は失敗する
• トランスクリプトのリプレイと永続化は、コードモードの制御呼び出しを保持する
• トランスクリプトとテレメトリには、ネストされたツール呼び出しが明確に表示される

​

E2E テスト計画

1. tools.codeMode.enabled: false で Gateway を起動する。
2. 小さな直接ツールセットを含むエージェントターンを送信する。
3. モデルに表示されるツールが変更されていないことをアサートする。
4. tools.codeMode.enabled: true で再起動する。
5. OpenClaw、Plugin、MCP、クライアントテストツールを含むエージェントターンを送信する。
6. モデルに表示されるツールリストが正確に exec、wait であることをアサートする。
7. exec 内で ALL_TOOLS を読み取り、有効なテストツールが存在することをアサートする。
8. exec 内で、tools.search、tools.describe、tools.call を通じて OpenClaw/Plugin/クライアントツールを呼び出す。
9. exec 内で API.list("mcp") と API.read("mcp/<server>.d.ts") を呼び出し、宣言ファイルが可視 MCP ツールを記述していることをアサートする。
10. exec 内で MCP.<server>.<tool>({ ...input }) を通じて MCP ツールを呼び出し、直接の MCP カタログエントリが ALL_TOOLS と tools.* に存在しないことをアサートする。
11. 拒否されたツールが存在せず、推測した ID では呼び出せないことをアサートする。
12. exec が waiting を返した後に解決されるネストされたツール呼び出しを開始する。
13. wait を呼び出し、復元された VM がツール結果を受け取ることをアサートする。
14. 最終回答に、復元後に生成された出力が含まれることをアサートする。
15. タイムアウト、中止、スナップショット期限切れがランタイム状態をクリーンアップすることをアサートする。
16. 軌跡をエクスポートし、ネストされた呼び出しが親のコードモード呼び出しの下に表示されることをアサートする。

​

関連

• ツール検索
• エージェントランタイム
• Exec ツール
• コード実行