程式碼模式

• Codex 程式碼模式在 Codex coding harness 內執行。它的 exec 工具是 freeform-grammar 工具：模型撰寫原始 JavaScript 原始碼（可選擇在前面加上 // @exec: {...} pragma 行作為執行選項），並在 Deno/V8 runtime 中執行。
• OpenClaw 程式碼模式在通用 OpenClaw agent runtime 中執行，除非設定 tools.codeMode.enabled: true，否則會停用。它的 exec 工具接受 JSON { code, language } payload，並在 QuickJS-WASI worker 中執行。

​

功能

• 模型可見工具清單會精確變成 exec 和 wait。
• exec 會在隔離的 QuickJS-WASI worker thread 中評估模型產生的 JavaScript 或 TypeScript。
• 其他所有已啟用工具（OpenClaw core、外掛、MCP、client）都會從模型 prompt 中隱藏，並透過 ALL_TOOLS 和 tools 在 guest 程式內公開。
• Guest 程式碼會搜尋隱藏目錄、描述工具的結構描述，並透過一般 agent turns 所使用的相同執行路徑呼叫工具（policy、 approvals、hooks、telemetry 仍都會套用）。
• MCP 工具會分組在 MCP namespace 下；在程式碼模式中，這是呼叫它們唯一支援的方式。
• 當巢狀工具呼叫仍在等待時，wait 會恢復已暫停的 code-mode run。

​

使用原因

• 更小的 prompt 介面：providers 取得兩個 control tools，而不是數十或數百個完整 tool schemas。
• 更好的 orchestration：模型可以在單一 code cell 內使用 loops、joins、小型 transforms、conditional logic，以及 parallel nested tool calls。
• Provider 中立：適用於 OpenClaw、外掛、MCP 和 client tools，不依賴 provider-native code execution。
• 失敗關閉：如果已啟用程式碼模式但 QuickJS-WASI runtime 不可用，該次執行會失敗，而不是靜默退回到廣泛的直接工具公開。

​

啟用

{
  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

​

技術導覽

​

Runtime 狀態

​

範圍

​

詞彙

• 程式碼模式：OpenClaw runtime mode，會隱藏一般模型 tools，且只公開 exec 和 wait。
• Guest runtime：評估模型程式碼的 QuickJS-WASI JavaScript VM。
• Host bridge：從 guest code 回到 OpenClaw 的窄版 JSON-compatible callback surface。
• Catalog：在一般 tool policy、外掛、MCP 和 client-tool resolution 後，run-scoped 的有效工具清單。
• Nested tool call：從 guest code 透過 host bridge 發出的 tool call。
• Snapshot：序列化的 QuickJS-WASI VM state，會儲存起來，讓 wait 可以繼續 suspended code-mode run。

​

設定

​

啟用流程

1. 解析 agent、model、provider、sandbox、channel、sender 和 run policy。
2. 建立有效的 OpenClaw tool list，加入符合資格的外掛、MCP 和 client tools。
3. 套用 allow/deny policy。
4. 如果 tools.codeMode.enabled 為 false，繼續使用一般工具公開。
5. 如果已啟用，且該次執行 tools 啟用，則在 code-mode catalog 中註冊有效工具。
6. 從模型可見清單移除所有一般 tools；加入 exec 和 wait。

​

模型可見工具

​

exec

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

• code 或 command 其中之一必須為非空。
• code 是文件記載的模型面向欄位。
• command 作為 hook policies 與 trusted rewrites 的 exec-compatible alias 被接受（一般 OpenClaw shell exec tool 也使用 command 欄位）；兩者同時存在時，值必須相符。
• language 預設為 "javascript"；schema 會把它公開為 flat string enum（"javascript" | "typescript"），而不是 oneOf/anyOf union， 因為有些 providers 會拒絕那些 shapes。
• 如果 language 是 "typescript"，OpenClaw 會先 transpile 再評估。
• exec 會拒絕 import、require、dynamic import，以及 module-loader patterns。
• exec 絕不會遞迴公開一般 shell exec implementation。
• 外層 code-mode exec hook events 會帶有 toolKind: "code_mode_exec" 和 toolInputKind: "javascript" | "typescript"（已知時），讓 policies 可以區分 code-mode cells 與共用相同 tool name 的 shell-style exec calls。

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、設定與中止狀態等執行內容。
5. 作用範圍資料會被序列化為一般描述元，並以直接全域與 namespaces.<globalName> 注入 QuickJS。
6. 客體呼叫會透過 worker 橋接暫停，在主機解析命名空間路徑，將呼叫映射到宣告的外掛擁有目錄工具，並透過 ToolSearchRuntime.callExactId 執行該工具。
7. 就緒的命名空間橋接呼叫會在作用中的 exec/wait 呼叫內自動清空；如果命名空間工作在逾時時仍待處理，或客體明確讓出，wait 之後會恢復同一個命名空間執行階段。
8. 外掛回復或解除安裝會呼叫 clearCodeModeNamespacesForPlugin(pluginId)，讓過時的全域不會在外掛載入失敗後殘留。

​

註冊形狀

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
• 當任何必要工具不存在或由另一個外掛擁有時，命名空間會被隱藏
• 每個可呼叫路徑只能以 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 恢復
• 外掛回滾會清除擁有者的命名空間註冊

​

輸出 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 作為模型可見工具公開。
• 相同的目錄化概念會移入客體執行階段。
• 客體執行階段會接收精簡的 ALL_TOOLS 中繼資料，以及非 MCP 工具的搜尋/描述/呼叫輔助函式。
• MCP 呼叫會使用產生的 MCP 命名空間及其 $api() 標頭，而不是 tools.call(...)。
• 巢狀呼叫會透過工具搜尋所使用的相同 OpenClaw 執行器路徑分派。

​

工具名稱與衝突

• 如果政策允許，tools.call("openclaw:core:exec", input) 可以呼叫 shell exec 工具。
• 只有在 shell exec 目錄項目具有明確安全名稱時，才會安裝 tools.exec(...)。
• 程式碼模式的 exec 工具永遠不會透過 tools 遞迴可用。

​

巢狀工具執行

​

執行與快照生命週期

• waiting 結果會儲存 QuickJS 快照、待處理橋接請求和作用域中繼資料（代理執行 ID、工作階段 ID/金鑰），直到 wait 恢復它或它過期。
• 過期、錯誤工作階段、錯誤執行，以及未知/已在恢復中的 runId 值不會產生不同的終端狀態；它們會呈現為 failed 結果（code: "invalid_input"），並帶有像是 code mode run is unavailable or expired. 或 code mode run belongs to a different session. 的訊息。
• 執行的快照一旦穩定為 completed 或 failed，就會從映射中移除；或在 Gateway 關閉時被丟棄（依設計，沒有任何內容會在重新啟動後保留：這是暫態執行階段狀態）。
• OpenClaw 會限制每個程序可同時暫停的執行數量（64），並在超過該上限時以 too many suspended code mode runs. 拒絕新的暫停。

​

QuickJS-WASI 執行階段

​

TypeScript

​

安全邊界

• 在主事件迴圈之外的 worker 執行緒中執行 QuickJS-WASI
• 將 quickjs-wasi 載入為直接相依項，而不是透過 Codex 或傳遞套件
• 客體中沒有檔案系統、網路、子程序、模組匯入、環境變數或主機全域物件
• 使用 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

​

實作配置

• 設定合約：tools.codeMode
• 目錄建構器：將有效工具轉為精簡項目與 ID 映射
• 模型介面轉接器：以 exec 和 wait 取代可見工具
• QuickJS-WASI 執行階段轉接器：載入、評估、快照、還原、釋放
• worker 監督器：逾時、中止、當機隔離
• 橋接轉接器：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 命名空間呼叫可用於具有一個物件輸入的可見 MCP 工具，而直接 MCP 目錄項目不會出現在 tools.*
• Tool Search 控制工具會同時從模型表面與隱藏目錄中隱藏
• 巢狀呼叫會保留核准與 hook 行為
• shell exec 會從模型中隱藏，但在允許時可透過目錄 id 呼叫
• 遞迴的程式碼模式 exec 和 wait 無法從客體程式碼呼叫
• TypeScript 輸入會被轉換並評估，而不會在停用或僅 JavaScript 的路徑上載入 TypeScript
• import、require、檔案系統、網路和環境存取會失敗
• 無限迴圈會逾時，且無法阻塞閘道
• 記憶體上限失敗會終止客體 VM
• 輸出與快照上限會套用於已完成與已暫停的呼叫
• wait 會恢復已暫停的快照並回傳最終值
• 已過期、已中止、錯誤工作階段和未知的 runId 值會失敗
• 轉錄重播與持久化會保留程式碼模式控制呼叫
• 轉錄與遙測會清楚顯示巢狀工具呼叫

​

E2E 測試計畫

1. 以 tools.codeMode.enabled: false 啟動閘道。
2. 以一組小型直接工具傳送代理回合。
3. 斷言模型可見工具保持不變。
4. 以 tools.codeMode.enabled: true 重新啟動。
5. 以 OpenClaw、外掛、MCP 和用戶端測試工具傳送代理回合。
6. 斷言模型可見工具清單正好是 exec、wait。
7. 在 exec 中讀取 ALL_TOOLS，並斷言有效的測試工具存在。
8. 在 exec 中透過 tools.search、tools.describe 和 tools.call 呼叫 OpenClaw／外掛／用戶端工具。
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. 匯出軌跡，並斷言巢狀呼叫在父層程式碼模式呼叫下可見。

​

相關

• Tool Search
• 代理執行階段
• Exec 工具
• 程式碼執行