Migração do SDK de Plugin

O OpenClaw substituiu uma ampla camada de compatibilidade retroativa por uma arquitetura moderna de plugins construída com importações pequenas e específicas. Se o seu plugin for anterior a essa mudança, este guia o adapta aos contratos atuais.

O que mudou

Duas superfícies de importação totalmente abertas permitiam que os plugins acessassem quase qualquer coisa por um único ponto de entrada:

• openclaw/plugin-sdk/compat - reexportava dezenas de auxiliares para manter plugins antigos baseados em hooks funcionando enquanto a nova arquitetura era desenvolvida.
• openclaw/plugin-sdk/infra-runtime - um barrel amplo que combinava eventos do sistema, estado de heartbeat, filas de entrega, auxiliares de fetch/proxy, auxiliares de arquivos, tipos de aprovação e utilitários sem relação entre si.
• openclaw/plugin-sdk/config-runtime - um barrel amplo de configuração que ainda mantinha auxiliares diretos obsoletos de carregamento/gravação durante o período de migração.
• openclaw/extension-api - uma ponte que dava aos plugins acesso direto a auxiliares do host, como o executor de agente incorporado.
• api.registerEmbeddedExtensionFactory(...) - um hook removido, exclusivo do executor incorporado, que observava eventos desse executor, como tool_result. Em vez disso, use middleware de resultados de ferramentas do agente (consulte Migrar extensões de resultados de ferramentas incorporadas para middleware).

Essas superfícies estão obsoletas: elas ainda funcionam, mas novos plugins não devem usá-las, e os plugins existentes devem migrar antes que a próxima versão principal as remova. registerEmbeddedExtensionFactory já foi removido; registros legados não são mais carregados.

O OpenClaw não remove nem reinterpreta comportamentos documentados de plugins na mesma alteração que introduz uma substituição. Alterações incompatíveis de contrato passam primeiro por um adaptador de compatibilidade, diagnósticos, documentação e um período de descontinuação. Isso se aplica a importações do SDK, campos de manifesto, APIs de configuração, hooks e comportamento de registro em tempo de execução.

Por quê

• 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 distinguir exportações estáveis das internas.

Agora, cada openclaw/plugin-sdk/<subpath> é um módulo pequeno e independente com um contrato documentado.

As interfaces legadas de conveniência de provedores para canais integrados também foram removidas - os atalhos de auxiliares específicos de canais eram conveniências privadas do monorepo, não contratos estáveis de plugins. Em vez disso, use subcaminhos genéricos e específicos do SDK. No workspace de plugins integrados, mantenha os auxiliares pertencentes ao provedor no api.ts ou runtime-api.ts do próprio plugin:

• A Anthropic mantém auxiliares de stream específicos do Claude em sua própria interface api.ts / contract-api.ts.
• A OpenAI mantém construtores de provedores, auxiliares de modelo padrão e construtores de provedores em tempo real em seu próprio api.ts.
• A OpenRouter mantém o construtor de provedor e os auxiliares de integração/configuração em seu próprio api.ts.

Política de compatibilidade

O trabalho de compatibilidade de plugins externos 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 indique o caminho antigo e seu substituto.
4. Abranger ambos os caminhos em testes.
5. Documentar a descontinuação e o caminho de migração.
6. Remover somente após o período de migração anunciado, geralmente em uma versão principal.

Se um campo de manifesto ainda for aceito, continue usando-o até que a documentação e os diagnósticos indiquem o contrário. Código novo deve preferir a substituição documentada; plugins existentes não devem deixar de funcionar durante versões secundárias comuns.

Audite a fila de migração atual com pnpm plugins:boundary-report:

pnpm plugins:boundary-report:ci é executado com os três sinalizadores de falha. Cada registro de compatibilidade tem uma data removeAfter explícita (não uma vaga "próxima versão principal") - o relatório agrupa registros obsoletos por essa data, conta referências locais no código/documentação, revela importações reservadas do SDK entre proprietários e resume a ponte privada do SDK do host de memória. Subcaminhos reservados do SDK devem ter o uso do proprietário rastreado; exportações reservadas não utilizadas devem ser removidas do SDK público.

Como migrar

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

// Ferramentas dinâmicas dos ambientes de execução OpenClaw e Codexapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Antesconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Depoisconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Defina isto somente para chamadores de compatibilidade confiáveis que aceitem  // intencionalmente o fallback intermediado pelo shell.  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/

// Antes (camada de compatibilidade retroativa obsoleta)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // Depois (importações modernas e específicas)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";

// Antes (ponte extension-api obsoleta)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // Depois (runtime injetado)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

Referência de caminhos de importação

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

Os pontos de integração auxiliares reservados para plugins incluídos foram removidos do mapa de exportações do SDK público, exceto por fachadas de compatibilidade explicitamente documentadas, como o shim obsoleto plugin-sdk/discord, mantido para plugins externos que ainda importam diretamente o pacote publicado @openclaw/discord. Auxiliares específicos do proprietário ficam dentro do pacote do plugin proprietário; comportamentos compartilhados do host passam 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 específica 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 responsável por ela.

Descontinuações ativas

Descontinuações mais específicas no SDK de plugins, no contrato de provedores, na superfície de runtime e no manifesto. Cada uma ainda funciona atualmente, mas será removida em uma futura versão principal. Cada entrada mapeia a API antiga para sua substituição canônica.

// Antesimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Depoisimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

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

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

// Antesconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Depoisconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Antesimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Depoisimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

Migração do Talk e de voz em tempo real

O código de voz em tempo real, telefonia, reuniões e Talk no navegador compartilha um único controlador de sessão do Talk exportado por openclaw/plugin-sdk/realtime-voice. O controlador é responsável pelo envelope comum de eventos do Talk, pelo estado do turno ativo, pelo estado de captura, pelo estado do áudio de saída, pelo histórico de eventos recentes e pela rejeição de turnos obsoletos. Os plugins de provedor são responsáveis pelas sessões em tempo real específicas de cada fornecedor; os plugins de superfície são responsáveis pelas particularidades de captura, reprodução, telefonia e reuniões.

Todas as superfícies integradas são executadas no controlador compartilhado: retransmissão do navegador, transferência para sala gerenciada, chamada de voz em tempo real, STT de chamada de voz por streaming, Google Meet em tempo real e pressionar para falar nativo. O Gateway anuncia um único canal de eventos do Talk ao vivo em hello-ok.features.events: talk.event.

O novo código não deve chamar createTalkEventSequencer(...) diretamente, a menos que esteja implementando um adaptador de baixo nível ou um fixture de teste. Use o controlador compartilhado para impedir que eventos com escopo de turno sejam emitidos sem um ID de turno, que chamadas obsoletas de turnEnd / turnCancel apaguem um turno ativo mais recente e para manter os eventos do ciclo de vida do áudio de saída consistentes entre telefonia, reuniões, retransmissão do navegador, transferência para sala gerenciada e clientes nativos do Talk.

O formato da API pública:

// API de sessão do Talk pertencente ao Gateway.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 }); // API de sessão de provedor pertencente ao cliente.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" });

As sessões WebRTC/websocket de provedor pertencentes ao navegador usam talk.client.create, pois o navegador é responsável pela negociação com o provedor e pelo transporte de mídia, enquanto o Gateway é responsável pelas credenciais, instruções e políticas de ferramentas. talk.session.* é a superfície comum gerenciada pelo Gateway para tempo real com retransmissão pelo Gateway, transcrição com retransmissão pelo Gateway e sessões nativas de STT/TTS em salas gerenciadas.

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

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

Mapa de métodos para leitores que estão migrando das famílias antigas talk.realtime.* / talk.transcription.* / talk.handoff.* (todas removidas):

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

Não introduza casos especiais de provedor ou plataforma no núcleo para fazer isso funcionar. O núcleo é responsável pela semântica das sessões do Talk. Os plugins de provedor são responsáveis pela configuração das sessões dos fornecedores. Chamadas de voz e Google Meet são responsáveis pelos adaptadores de telefonia/reunião. Navegadores e aplicativos nativos são responsáveis pela experiência de captura/reprodução nos dispositivos.

Cronograma de remoção

Todos os plugins do núcleo já foram migrados. Os plugins externos devem ser migrados antes da próxima versão principal. Execute pnpm plugins:boundary-report para verificar quais registros de compatibilidade das superfícies usadas pelo seu plugin vencerão primeiro.

Suprimir temporariamente os avisos

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

Relacionados

• Primeiros passos - crie seu primeiro plugin
• Visão geral do SDK - referência completa de importação de subcaminhos
• Plugins de canal - criação de plugins de canal
• Plugins de provedor - criação de plugins de provedor
• Detalhes internos dos plugins - análise aprofundada da arquitetura
• Manifesto do plugin - referência do esquema do manifesto