Migração do SDK de Plugin

OpenClaw passou de uma ampla camada de compatibilidade retroativa para uma arquitetura moderna de Plugins com importações focadas e documentadas. Se o seu Plugin foi criado antes da nova arquitetura, este guia ajuda você a migrar.

O que está mudando

O sistema antigo de Plugins fornecia duas superfícies totalmente abertas que permitiam que Plugins importassem qualquer coisa de que precisassem a partir de um único ponto de entrada:

• openclaw/plugin-sdk/compat - uma única importação que reexportava dezenas de auxiliares. Ela foi introduzida para manter Plugins mais antigos baseados em hooks funcionando enquanto a nova arquitetura de Plugins estava sendo criada.
• openclaw/plugin-sdk/infra-runtime - um amplo barrel de auxiliares de runtime que misturava eventos do sistema, estado de Heartbeat, filas de entrega, auxiliares de fetch/proxy, auxiliares de arquivos, tipos de aprovação e utilitários não relacionados.
• openclaw/plugin-sdk/config-runtime - um amplo barrel de compatibilidade de configuração que ainda carrega auxiliares obsoletos de carregamento/gravação direta durante a janela de migração.
• openclaw/extension-api - uma ponte que dava aos Plugins acesso direto a auxiliares do lado do host, como o executor de agente incorporado.
• api.registerEmbeddedExtensionFactory(...) - um hook removido de extensão empacotada somente do executor incorporado que podia observar eventos do executor incorporado, como tool_result.

As amplas superfícies de importação agora estão obsoletas. Elas ainda funcionam em runtime, mas novos Plugins não devem usá-las, e Plugins existentes devem migrar antes que a próxima versão principal as remova. A API de registro de fábrica de extensão somente do executor incorporado foi removida; use middleware de resultado de ferramenta em vez disso.

OpenClaw não remove nem reinterpreta comportamento documentado de Plugins na mesma alteração que introduz uma substituição. Alterações de contrato incompatíveis precisam primeiro passar por um adaptador de compatibilidade, diagnósticos, documentação e uma janela de obsolescência. Isso se aplica a importações do SDK, campos de manifesto, APIs de configuração, hooks e comportamento de registro em runtime.

Por que isso mudou

A abordagem antiga causava problemas:

• Inicialização lenta - importar um auxiliar carregava dezenas de módulos não relacionados
• Dependências circulares - reexportações amplas facilitavam a criação de ciclos de importação
• Superfície de API pouco clara - não havia como saber quais exportações eram estáveis versus internas

O SDK moderno de Plugins corrige isso: cada caminho de importação (openclaw/plugin-sdk/\<subpath\>) é um módulo pequeno e autocontido, com propósito claro e contrato documentado.

Seams legados de conveniência de provedor para canais empacotados também foram removidos. Seams auxiliares com marca de canal eram atalhos privados do monorepo, não contratos estáveis de Plugins. Use subcaminhos genéricos e estreitos do SDK em vez disso. Dentro do workspace de Plugins empacotados, mantenha auxiliares pertencentes ao provedor no próprio api.ts ou runtime-api.ts desse Plugin.

Exemplos atuais de provedores empacotados:

• Anthropic mantém auxiliares de stream específicos do Claude em seu próprio seam api.ts / contract-api.ts
• OpenAI mantém construtores de provedor, auxiliares de modelo padrão e construtores de provedor realtime em seu próprio api.ts
• OpenRouter mantém o construtor de provedor e auxiliares de onboarding/configuração em seu próprio api.ts

Plano de migração do Talk e voz realtime

O código de voz realtime, telefonia, reunião e Talk no navegador está mudando de contabilidade de turnos local à superfície para um controlador compartilhado de sessão Talk exportado por openclaw/plugin-sdk/realtime-voice. O novo controlador é responsável pelo envelope comum de eventos Talk, estado de turno ativo, estado de captura, estado de áudio de saída, histórico recente de eventos e rejeição de turnos obsoletos. Plugins de provedor devem continuar sendo responsáveis por sessões realtime específicas de fornecedor; Plugins de superfície devem continuar sendo responsáveis por captura, reprodução, telefonia e particularidades de reunião.

Esta migração do Talk é intencionalmente limpa e incompatível:

1. Mantenha o controlador compartilhado e as primitivas de runtime em plugin-sdk/realtime-voice.
2. Mova as superfícies empacotadas para o controlador compartilhado: retransmissão do navegador, handoff de sala gerenciada, realtime de chamada de voz, STT por streaming de chamada de voz, Google Meet realtime e push-to-talk nativo.
3. Substitua as antigas famílias de RPC do Talk pela API final talk.session.* e talk.client.*.
4. Anuncie um canal de eventos Talk ao vivo no Gateway hello-ok.features.events: talk.event.
5. Exclua o antigo endpoint HTTP realtime e qualquer caminho de substituição de instruções em tempo de solicitação.

Novo código não deve chamar createTalkEventSequencer(...) diretamente, a menos que esteja implementando um adaptador de baixo nível ou fixture de teste. Prefira o controlador compartilhado para que eventos com escopo de turno não possam ser emitidos sem um id de turno, chamadas obsoletas de turnEnd / turnCancel não possam limpar um turno ativo mais recente, e eventos do ciclo de vida de áudio de saída permaneçam consistentes entre telefonia, reuniões, retransmissão do navegador, handoff de sala gerenciada e clientes Talk nativos.

O formato alvo da API pública é:

// Gateway-owned Talk session API.await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // Client-owned provider session API.await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

Sessões WebRTC/websocket de provedor pertencentes ao navegador usam talk.client.create, porque o navegador é responsável pela negociação do provedor e pelo transporte de mídia, enquanto o Gateway é responsável por credenciais, instruções e política de ferramentas. talk.session.* é a superfície comum gerenciada pelo Gateway para realtime via gateway-relay, transcrição via gateway-relay e sessões STT/TTS nativas de sala gerenciada.

Configurações legadas que colocavam seletores realtime ao lado de talk.provider / talk.providers devem ser reparadas com openclaw doctor --fix; o Talk em runtime não reinterpreta configuração de provedor de fala/TTS como configuração de provedor realtime.

As combinações compatíveis de talk.session.create são intencionalmente pequenas:

Mapa de métodos removidos:

O vocabulário de controle unificado também é deliberadamente estreito:

Não introduza casos especiais de provedor ou plataforma no core para fazer isso funcionar. O core é responsável pela semântica de sessão Talk. Os Plugins de provedor são responsáveis pela configuração de sessão do fornecedor. Chamadas de voz e Google Meet são responsáveis por adaptadores de telefonia/reunião. Navegador e aplicativos nativos são responsáveis pela UX de captura/reprodução do dispositivo.

Política de compatibilidade

Para Plugins externos, o trabalho de compatibilidade segue esta ordem:

1. adicionar o novo contrato
2. manter o comportamento antigo conectado por meio de um adaptador de compatibilidade
3. emitir um diagnóstico ou aviso que nomeie o caminho antigo e a substituição
4. cobrir ambos os caminhos em testes
5. documentar a depreciação e o caminho de migração
6. remover somente após a janela de migração anunciada, geralmente em uma versão principal

Mantenedores podem auditar a fila de migração atual com pnpm plugins:boundary-report. Use pnpm plugins:boundary-report:summary para contagens compactas, --owner <id> para um Plugin ou proprietário de compatibilidade, e pnpm plugins:boundary-report:ci quando um gate de CI deve falhar em registros de compatibilidade vencidos, importações reservadas do SDK entre proprietários ou subcaminhos reservados do SDK não utilizados. O relatório agrupa registros de compatibilidade obsoletos por data de remoção, conta referências locais de código/docs, expõe importações reservadas do SDK entre proprietários e resume a ponte privada do SDK do host de memória para que a limpeza de compatibilidade permaneça explícita em vez de depender de buscas ad hoc. Subcaminhos reservados do SDK devem ter uso de proprietário rastreado; exports reservados de auxiliares não utilizados devem ser removidos do SDK público.

Se um campo de manifesto ainda for aceito, autores de Plugins podem continuar usando-o até que a documentação e os diagnósticos digam o contrário. Código novo deve preferir a substituição documentada, mas Plugins existentes não devem quebrar durante versões menores ordinárias.

Como migrar

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Referência de caminhos de importação

Esta tabela é intencionalmente o subconjunto comum de migração, não a superfície completa do SDK. O inventário do ponto de entrada do compilador fica em scripts/lib/plugin-sdk-entrypoints.json; as exportações de pacote são geradas a partir do subconjunto público.

Seams auxiliares reservados de plugins empacotados foram removidos do mapa de exportações do SDK público, exceto por fachadas de compatibilidade documentadas explicitamente, como o shim obsoleto plugin-sdk/discord mantido para o pacote publicado @openclaw/discord@2026.3.13. Auxiliares específicos do proprietário ficam dentro do pacote do plugin proprietário; o comportamento compartilhado do host deve passar por contratos genéricos do SDK, como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime e plugin-sdk/plugin-config-runtime.

Use a importação mais estreita que corresponda à tarefa. Se você não encontrar uma exportação, verifique o código-fonte em src/plugin-sdk/ ou pergunte aos mantenedores qual contrato genérico deve ser o proprietário dela.

Descontinuações ativas

Descontinuações mais estreitas que se aplicam ao SDK de plugins, ao contrato de provedor, à superfície de runtime e ao manifesto. Cada uma ainda funciona hoje, mas será removida em uma futura versão principal. A entrada abaixo de cada item mapeia a API antiga para sua substituição canônica.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Cronograma de remoção

Todos os plugins principais já foram migrados. Plugins externos devem migrar antes da próxima versão major.

Suprimindo os avisos temporariamente

Defina estas variáveis de ambiente enquanto trabalha na migração:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Esta é uma saída temporária, não uma solução permanente.

Relacionados

• Primeiros passos - crie seu primeiro plugin
• Visão geral do SDK - referência completa de imports por subcaminho
• Plugins de canal - criação de plugins de canal
• Plugins de provedor - criação de plugins de provedor
• Aspectos internos do Plugin - análise aprofundada da arquitetura
• Manifesto do Plugin - referência do esquema do manifesto