Modo de código

• O Codex Code Mode é executado dentro do ambiente de programação do Codex. Sua ferramenta exec é uma ferramenta de gramática livre: o modelo escreve código-fonte JavaScript bruto (opcionalmente prefixado por uma linha de pragma // @exec: {...} para opções de execução), executado em um runtime Deno/V8.
• O modo de código do OpenClaw é executado no runtime genérico de agentes do OpenClaw e fica desativado, a menos que tools.codeMode.enabled: true esteja configurado. Sua ferramenta exec recebe um payload JSON { code, language }, executado em um worker QuickJS-WASI.

​

O que ele faz

• A lista de ferramentas visível ao modelo passa a ser exec, wait e qualquer ferramenta exclusivamente direta, como computer, cujo resultado de imagem não possa atravessar a ponte do guest.
• exec avalia JavaScript ou TypeScript gerado pelo modelo em uma thread de worker QuickJS-WASI isolada.
• Todas as ferramentas habilitadas elegíveis para o catálogo (núcleo do OpenClaw, Plugin, MCP, cliente) são ocultadas do prompt do modelo e expostas dentro do programa guest por meio de ALL_TOOLS e tools.
• O código guest pesquisa o catálogo oculto, descreve o esquema de uma ferramenta e chama uma ferramenta pelo mesmo caminho de execução usado em turnos normais do agente (políticas, aprovações, hooks e telemetria continuam sendo aplicados).
• As ferramentas MCP são agrupadas no namespace MCP; no modo de código, essa é a única maneira compatível de chamá-las.
• wait retoma uma execução suspensa do modo de código quando chamadas de ferramentas aninhadas ainda estão pendentes.

​

Por que usá-lo

• Superfície de prompt menor: os provedores recebem duas ferramentas de controle e apenas as poucas ferramentas diretas necessárias, em vez de dezenas ou centenas de esquemas completos de ferramentas.
• Melhor orquestração: o modelo pode usar loops, junções, pequenas transformações, lógica condicional e chamadas paralelas de ferramentas aninhadas dentro de uma única célula de código.
• Neutro em relação ao provedor: funciona com ferramentas do OpenClaw, de Plugins, MCP e de clientes sem depender da execução de código nativa do provedor.
• Falha de forma fechada: se o modo de código estiver ativado, mas o runtime QuickJS-WASI estiver indisponível, a execução falha em vez de recorrer silenciosamente à exposição direta ampla de ferramentas.

​

Ativá-lo

{
  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

​

Visão geral técnica

​

Status do runtime

​

Escopo

​

Termos

• Modo de código: o modo de runtime do OpenClaw que oculta ferramentas do modelo compatíveis com o catálogo e expõe exec, wait e as ferramentas exclusivamente diretas necessárias.
• Runtime guest: a VM JavaScript QuickJS-WASI que avalia o código do modelo.
• Ponte do host: a superfície restrita de callbacks compatíveis com JSON, do código guest de volta ao OpenClaw.
• Catálogo: a lista de ferramentas efetivas no escopo da execução após a resolução normal de políticas de ferramentas, Plugins, MCP e ferramentas de clientes.
• Chamada de ferramenta aninhada: uma chamada de ferramenta feita pelo código guest por meio da ponte do host.
• Snapshot: estado serializado da VM QuickJS-WASI salvo para que wait possa continuar uma execução suspensa do modo de código.

​

Configuração

​

Ativação

1. Resolva o agente, o modelo, o provedor, a sandbox, o canal, o remetente e a política da execução.
2. Construa a lista efetiva de ferramentas do OpenClaw, adicionando Plugins, ferramentas MCP e ferramentas de clientes elegíveis.
3. Aplique a política de permissão/negação.
4. Se tools.codeMode.enabled for falso, prossiga com a exposição normal das ferramentas.
5. Se estiver ativado e as ferramentas estiverem ativas para a execução, mantenha as ferramentas exclusivamente diretas necessárias e registre no catálogo do modo de código todas as ferramentas efetivas elegíveis para o catálogo.
6. Remova as ferramentas catalogadas da lista visível ao modelo; adicione exec e wait junto às ferramentas exclusivamente diretas mantidas.

​

Ferramentas visíveis ao modelo

​

exec

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

• Um dos campos code ou command deve conter um valor não vazio.
• code é o campo documentado voltado ao modelo.
• command é aceito como um alias compatível com exec para políticas de hooks e reescritas confiáveis (a ferramenta normal de execução de shell do OpenClaw também usa um campo command); quando ambos estão presentes, os valores devem ser iguais.
• O padrão de language é "javascript"; o esquema o expõe como uma enumeração simples de strings ("javascript" | "typescript"), não como uma união oneOf/anyOf, pois alguns provedores rejeitam esses formatos.
• Se language for "typescript", o OpenClaw transpila o código antes da avaliação.
• exec rejeita import, require, importação dinâmica e padrões de carregadores de módulos.
• exec nunca expõe recursivamente a implementação normal de exec do shell.
• Eventos de hook do exec externo do modo de código incluem toolKind: "code_mode_exec" e toolInputKind: "javascript" | "typescript" (quando conhecido), para que as políticas possam distinguir células do modo de código de chamadas de exec no estilo shell que compartilham o mesmo nome de ferramenta.

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 avalia o código até a conclusão, falha ou suspensão.
2. Na suspensão, o OpenClaw cria um snapshot da VM do QuickJS e registra o trabalho pendente do host.
3. Quando o trabalho pendente é concluído, wait restaura o snapshot da VM e registra novamente os callbacks do host usando nomes estáveis.
4. O OpenClaw entrega os resultados das ferramentas aninhadas à VM restaurada e processa os trabalhos pendentes do QuickJS.
5. wait retorna completed, failed ou outro resultado waiting.

• runId é desconhecido ou seu snapshot já expirou.
• o chamador não está no mesmo escopo de execução/sessão que a execução suspensa.
• um wait já está em andamento para esse runId.
• a restauração do QuickJS-WASI falha.
• a retomada excederia maxOutputBytes ou maxSnapshotBytes.

​

API do runtime convidado

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

// Se o catálogo oculto tiver uma entrada `web_search` inequívoca:
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: "Investigue os logs do Gateway",
});

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 {
  /** Retorna este cabeçalho de API no estilo TypeScript. */
  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;

  /**
   * Cria uma issue no GitHub.
   * @param owner Proprietário do repositório
   * @param repo Nome do repositório
   * @param title Título da issue
   */
  function createIssue(input: {
    owner: string;
    repo: string;
    title: string;
    body?: string;
  }): Promise<McpToolResult>;
}

​

Namespaces 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 do registro

1. Um loader confiável chama registerCodeModeNamespaceForPlugin(pluginId, registration).
2. O modo de código cria o ToolSearchRuntime oculto para a execução e lê seu catálogo com escopo da execução.
3. createCodeModeNamespaceRuntime(ctx, catalog) mantém apenas os registros cujos requiredToolNames estão todos visíveis e pertencem ao mesmo pluginId.
4. Cada namespace visível chama createScope(ctx) para a execução atual, recebendo contexto de execução como agentId, sessionKey, sessionId, runId, configuração e estado de cancelamento.
5. Os dados do escopo são serializados em um descritor simples e injetados no QuickJS como globais diretos e namespaces.<globalName>.
6. As chamadas do código convidado são suspensas pela ponte do worker, resolvem o caminho do namespace no host, mapeiam a chamada para uma ferramenta declarada do catálogo pertencente ao plugin e executam essa ferramenta por meio de ToolSearchRuntime.callExactId.
7. As chamadas prontas da ponte de namespaces são drenadas automaticamente dentro da chamada ativa exec/wait; se ainda houver trabalho de namespace pendente ao atingir o tempo limite ou se o código convidado ceder explicitamente, wait retoma posteriormente o mesmo runtime de namespace.
8. O rollback ou a desinstalação do plugin chama clearCodeModeNamespacesForPlugin(pluginId) para que globais obsoletos não sobrevivam a uma falha no carregamento do plugin.

​

Formato do registro

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

const pluginId = "github";

registerCodeModeNamespaceForPlugin(pluginId, {
  id: "github-issues",
  globalName: "Issues",
  description: "Auxiliares de issues do GitHub para o repositório atual.",
  requiredToolNames: ["github_list_issues", "github_update_issue"],
  prompt: "Use Issues.list(params) e 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: () => ({
  // Incorreto: isso ignora o ciclo de vida da ferramenta de catálogo e será rejeitado.
  list: async () => githubClient.listIssues(),
});

​

Propriedade e visibilidade

• toda ferramenta obrigatória deve existir no catálogo da execução
• toda ferramenta obrigatória deve ter sourceName === pluginId
• o namespace fica oculto quando qualquer ferramenta obrigatória está ausente ou pertence a outro plugin
• cada caminho chamável pode direcionar somente para uma ferramenta mencionada em requiredToolNames

​

Regras de serialização do escopo

• funções brutas
• grafos de objetos circulares
• segmentos de caminho não seguros: __proto__, constructor, prototype, chaves vazias ou chaves contendo o separador de caminho interno
• valores de globalName que não são identificadores JavaScript
• colisões de globalName com globais integradas do modo de código, como tools, namespaces, text, json, yield_control, MCP, API, ALL_TOOLS ou __openclaw*

​

Prompts

{
  description: "Auxiliares do serviço de produção de ficção.",
  prompt:
    "Use Fictions.riskAudit(), Fictions.promoteIfReady(id, status) e Fictions.unpaidOver(amount).",
}

​

Limpeza

clearCodeModeNamespacesForPlugin(pluginId);

​

Lista de verificação de testes

• o texto do prompt do namespace aparece somente quando as ferramentas subjacentes estão visíveis
• ferramentas com o mesmo nome provenientes de outro sourceName não expõem o namespace
• funções de escopo brutas são rejeitadas
• IDs de namespace forjados e caminhos forjados são rejeitados
• caminhos invocáveis não podem apontar para ferramentas não declaradas
• objetos aninhados e referências compartilhadas são serializados corretamente
• as chamadas de namespace são executadas por meio das ferramentas do catálogo e retornam detalhes seguros para JSON
• as falhas podem ser capturadas pelo código convidado
• chamadas de namespace suspensas são retomadas por meio de wait
• a reversão do plugin limpa os registros de namespace pertencentes a ele

​

API de saída

• text(value) acrescenta uma saída legível por humanos ao array output.
• json(value) acrescenta um item de saída estruturado após a serialização compatível com JSON.
• O valor final retornado pelo código convidado torna-se value em um resultado completed.

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

​

Catálogo de ferramentas

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

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

​

Interação com a Pesquisa de Ferramentas

• O OpenClaw não expõe tool_search_code, tool_search, tool_describe nem tool_call como ferramentas visíveis para o modelo.
• O mesmo conceito de catalogação é transferido para o runtime do guest.
• O runtime do guest recebe metadados compactos de ALL_TOOLS e auxiliares de pesquisa/descrição/ chamada para ferramentas que não são MCP.
• As chamadas MCP usam o namespace MCP gerado e seus cabeçalhos $api() em vez de tools.call(...).
• As chamadas aninhadas são despachadas pelo mesmo caminho do executor do OpenClaw usado pela Pesquisa de Ferramentas.

​

Nomes de ferramentas e colisões

• tools.call("openclaw:core:exec", input) pode chamar a ferramenta de execução do shell se a política permitir.
• tools.exec(...) é instalado somente se a entrada do catálogo de execução do shell tiver um nome seguro inequívoco.
• a ferramenta exec do modo de código nunca fica disponível recursivamente por meio de tools.

​

Execução aninhada de ferramentas

​

Ciclo de vida da execução e do snapshot

• Um resultado waiting armazena o snapshot do QuickJS, as solicitações pendentes da ponte e os metadados de escopo (id da execução do agente, id/chave da sessão) até que wait o retome ou ele expire.
• Valores de runId expirados, de sessão incorreta, de execução incorreta e desconhecidos/já em retomada não produzem um estado terminal distinto; eles aparecem como um resultado failed (code: "invalid_input") com uma mensagem como code mode run is unavailable or expired. ou code mode run belongs to a different session..
• O snapshot de uma execução é removido do mapa assim que ela termina como completed ou failed, ou é descartado no encerramento do Gateway (nada sobrevive a uma reinicialização: este é um estado transitório do runtime).
• Para trabalho somente leitura, exec pode definir restartSafe: true. O OpenClaw então rejeita chamadas de catálogo com efeitos colaterais e namespaces de plugins antes da execução e marca resultados suspensos como seguros para reprodução. Se uma reinicialização interromper wait, a recuperação após reinicialização reconstruirá o turno a partir da transcrição em vez de restaurar o snapshot local do processo. O próprio turno de recuperação permanece limitado a ferramentas principais auditadas somente leitura e ferramentas de plugins explicitamente seguras para reprodução.
• O OpenClaw limita o número de execuções suspensas simultaneamente por processo (64) e rejeita novas suspensões além desse limite com too many suspended code mode runs..

​

Runtime QuickJS-WASI

​

TypeScript

​

Limite de segurança

• executa o QuickJS-WASI fora do loop de eventos principal, em uma thread de trabalho
• carrega quickjs-wasi como uma dependência direta, não por meio do Codex nem de um pacote transitivo
• não há sistema de arquivos, rede, subprocessos, importação de módulos, variáveis de ambiente nem objetos globais do host no ambiente convidado
• usa limites de memória e de interrupção do QuickJS, além de um tempo limite de relógio de parede no processo pai
• impõe limites de saída, snapshots, logs e chamadas pendentes
• serializa os valores da ponte do host por meio de um adaptador JSON restrito
• converte erros do host em erros simples no ambiente convidado, nunca em objetos do realm do host
• descarta snapshots em caso de tempo limite, cancelamento, encerramento da sessão ou expiração
• rejeita acesso recursivo a exec, wait e às ferramentas de controle do Tool Search
• impede que colisões de nomes de conveniência ocultem os auxiliares do catálogo

​

Códigos de erro

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

​

Telemetria

​

Depuração

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

​

Estrutura da implementação

• contrato de configuração: tools.codeMode
• construtor de catálogo: ferramentas efetivas convertidas em entradas compactas e mapa de IDs
• adaptador da superfície do modelo: substitui as ferramentas visíveis por ferramentas de controle/direct-only
• adaptador de runtime QuickJS-WASI: carregar, avaliar, criar snapshot, restaurar, descartar
• supervisor de workers: tempo limite, cancelamento, isolamento de falhas
• adaptador da ponte: callbacks do host compatíveis com JSON e entrega de resultados
• adaptador de transformação TypeScript
• armazenamento de snapshots: TTL, limites de tamanho, escopo de execução/sessão
• projeção de trajetória para chamadas de ferramentas aninhadas
• contadores de telemetria e diagnósticos

​

Lista de verificação de validação

• a configuração desabilitada mantém inalterada a exposição existente de ferramentas
• a configuração como objeto sem enabled: true mantém o modo de código desabilitado
• a configuração habilitada expõe exec, wait e somente as ferramentas direct-only necessárias ao modelo quando as ferramentas estão ativas para a execução
• execuções brutas sem ferramentas, disableTools e listas de permissões vazias não acionam a imposição do payload do modo de código
• todas as ferramentas efetivas não MCP elegíveis para o catálogo aparecem em ALL_TOOLS
• as ferramentas direct-only permanecem visíveis ao modelo e não aparecem em ALL_TOOLS
• as ferramentas negadas não aparecem em ALL_TOOLS
• tools.search, tools.describe e tools.call funcionam para ferramentas do OpenClaw
• API.list("mcp") e API.read("mcp/<server>.d.ts") expõem declarações MCP no estilo TypeScript sem uma chamada de ponte/ferramenta
• o $api() do namespace MCP permanece disponível como fallback inline para esquemas
• as chamadas do namespace MCP funcionam para ferramentas MCP visíveis com uma entrada de objeto, enquanto as entradas diretas do catálogo MCP não aparecem em tools.*
• as ferramentas de controle da Busca de Ferramentas ficam ocultas tanto da superfície do modelo quanto do catálogo oculto
• as chamadas aninhadas preservam o comportamento de aprovação e dos hooks
• o exec do shell fica oculto do modelo, mas pode ser chamado pelo ID do catálogo quando permitido
• exec e wait recursivos do modo de código não podem ser chamados pelo código convidado
• a entrada TypeScript é transformada e avaliada sem carregar o TypeScript nos caminhos desabilitados ou exclusivos de JavaScript
• o acesso a import, require, sistema de arquivos, rede e ambiente falha
• loops infinitos atingem o tempo limite e não podem bloquear o Gateway
• falhas no limite de memória encerram a VM convidada
• os limites de saída e snapshot são aplicados a chamadas concluídas e suspensas
• wait retoma um snapshot suspenso e retorna o valor final
• valores runId expirados, cancelados, de sessão incorreta e desconhecidos falham
• a reprodução e a persistência da transcrição preservam as chamadas de controle do modo de código
• a transcrição e a telemetria mostram claramente as chamadas de ferramentas aninhadas

​

Plano de testes E2E

1. Inicie um Gateway com tools.codeMode.enabled: false.
2. Envie um turno do agente com um pequeno conjunto de ferramentas diretas.
3. Verifique se as ferramentas visíveis ao modelo permanecem inalteradas.
4. Reinicie com tools.codeMode.enabled: true.
5. Envie um turno do agente com ferramentas de teste do OpenClaw, de plugins, MCP e do cliente.
6. Verifique se a lista de ferramentas visíveis ao modelo é composta por exec, wait e somente pelas ferramentas direct-only configuradas.
7. Em exec, leia ALL_TOOLS e verifique se as ferramentas de teste efetivas elegíveis para o catálogo estão presentes, enquanto as ferramentas direct-only estão ausentes.
8. Em exec, chame ferramentas do OpenClaw/de plugins/do cliente por meio de tools.search, tools.describe e tools.call.
9. Em exec, chame API.list("mcp") e API.read("mcp/<server>.d.ts") e verifique se os arquivos de declaração descrevem as ferramentas MCP visíveis.
10. Em exec, chame ferramentas MCP por meio de MCP.<server>.<tool>({ ...input }) e verifique se as entradas diretas do catálogo MCP estão ausentes de ALL_TOOLS e tools.*.
11. Verifique se as ferramentas negadas estão ausentes e não podem ser chamadas por um ID presumido.
12. Inicie uma chamada de ferramenta aninhada que seja resolvida depois que exec retornar waiting.
13. Chame wait e verifique se a VM restaurada recebe o resultado da ferramenta.
14. Verifique se a resposta final contém a saída produzida após a restauração.
15. Verifique se o tempo limite, o cancelamento e a expiração do snapshot limpam o estado do runtime.
16. Exporte a trajetória e verifique se as chamadas aninhadas estão visíveis sob a chamada pai do modo de código.

​

Relacionado

• Busca de Ferramentas
• Runtimes de agentes
• Ferramenta Exec
• Execução de código