Migração do SDK de Plugin

OpenClaw mudou de uma ampla camada de compatibilidade retroativa para uma arquitetura moderna de plugins com importações focadas e documentadas. Se 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 aos plugins importar 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 diretos obsoletos de carregamento/gravação 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 exclusivo do Pi que podia observar eventos do executor incorporado, como tool_result.

As superfícies amplas 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 incorporada exclusiva do Pi 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 devem primeiro passar por um adaptador de compatibilidade, diagnósticos, documentação e uma janela de descontinuação. 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 exports eram estáveis ou internos

O SDK moderno de plugins corrige isso: cada caminho de importação (openclaw/plugin-sdk/\<subpath\>) é um módulo pequeno, autocontido, com um 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 builders de provedor, auxiliares de modelo padrão e builders de provedor realtime em seu próprio api.ts
• OpenRouter mantém builder de provedor e auxiliares de onboarding/configuração em seu próprio api.ts

Plano de migração de voz Talk e realtime

Código de voz realtime, telefonia, reuniões e Talk no navegador está migrando do bookkeeping local de 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 do fornecedor; plugins de superfície devem continuar sendo responsáveis por captura, reprodução, telefonia e particularidades de reuniões.

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

1. Mantenha os primitivos compartilhados de controlador/runtime em plugin-sdk/realtime-voice.
2. Migre as superfícies empacotadas para o controlador compartilhado: relay do navegador, handoff de sala gerenciada, realtime de chamada de voz, STT streaming de chamada de voz, Google Meet realtime e push-to-talk nativo.
3. Substitua as famílias antigas de RPC 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 endpoint HTTP realtime antigo e qualquer caminho de substituição de instruções em tempo de requisição.

Código novo 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 de ciclo de vida de áudio de saída permaneçam consistentes entre telefonia, reuniões, relay 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 });

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 sessões realtime por gateway-relay, transcrição por gateway-relay e STT/TTS nativo 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 é dono da semântica da sessão Talk. Plugins de provedor são donos da configuração de sessão do fornecedor. Chamadas de voz e Google Meet são donos dos adaptadores de telefonia/reunião. Navegador e aplicativos nativos são donos da 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 descontinuaçã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 dono de compatibilidade, e pnpm plugins:boundary-report:ci quando um gate de CI deve falhar em registros de compatibilidade vencidos, imports de SDK reservados entre donos ou subpaths de SDK reservados não usados. O relatório agrupa registros de compatibilidade descontinuados por data de remoção, conta referências locais em código/docs, expõe imports de SDK reservados entre donos e resume a ponte privada de SDK do host de memória para que a limpeza de compatibilidade permaneça explícita em vez de depender de buscas ad hoc. Subpaths de SDK reservados devem ter uso de dono rastreado; exports de helpers reservados não usados 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 secundárias comuns.

Como migrar

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

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Referência de caminho de importação

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

As interfaces auxiliares reservadas dos plugins empacotados foram retiradas do mapa de exportações público do SDK, exceto por facades de compatibilidade explicitamente documentadas, como o shim obsoleto plugin-sdk/discord mantido para o pacote publicado @openclaw/[email protected]. 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 restrita que corresponda ao trabalho. 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.

Depreciações ativas

Depreciações mais restritas que se aplicam ao SDK de Plugin, 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";

{  "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 principal.

Suprimindo temporariamente os avisos

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

• Introdução - crie seu primeiro plugin
• Visão geral do SDK - referência completa de importação por subcaminho
• Plugins de canal - criação de plugins de canal
• Plugins de provedor - criação de plugins de provedor
• Internos do Plugin - aprofundamento na arquitetura
• Manifesto do Plugin - referência do esquema do manifesto