Migração do SDK de Plugin

O OpenClaw passou 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 amplamente abertas que permitiam aos plugins importar tudo de que precisavam 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 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 exclusiva 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.

O OpenClaw não remove nem reinterpreta comportamento documentado de plugins na mesma alteração que introduz uma substituição. Alterações incompatíveis de contrato 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 exportações eram estáveis vs. internas

O SDK moderno de plugins corrige isso: cada caminho de importação (openclaw/plugin-sdk/\<subpath\>) é um módulo pequeno e 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 restritos do SDK em vez disso. Dentro do workspace de plugins empacotados, mantenha auxiliares de propriedade do 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 em tempo real 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 do Talk e voz em tempo real

O código de voz em tempo real, telefonia, reuniões e Talk no navegador está migrando de controle de turnos local à superfície para um controlador compartilhado de sessão do Talk exportado por openclaw/plugin-sdk/realtime-voice. O novo controlador é responsável pelo envelope comum de eventos do 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 em tempo real específicas do 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 incompatível e limpa:

1. Mantenha o controlador compartilhado/primitivos de runtime em plugin-sdk/realtime-voice.
2. Migre superfícies empacotadas para o controlador compartilhado: relay do navegador, handoff de sala gerenciada, chamada de voz em tempo real, STT por streaming em chamada de voz, Google Meet em tempo real e push-to-talk nativo.
3. Substitua as famílias antigas de RPC do Talk pela API final talk.session.* e talk.client.*.
4. Anuncie um único canal de eventos ao vivo do Talk em hello-ok.features.events do Gateway: talk.event.
5. Exclua o endpoint HTTP antigo de tempo real 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 novo, 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 nativos do Talk.

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 });
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 tempo real via gateway-relay, transcrição via gateway-relay e sessões nativas gerenciadas de STT/TTS em sala.

Configurações legadas que colocavam seletores em tempo real 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 em tempo real.

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

Mapa de métodos removidos:

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

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 do Talk. Plugins de provedor são responsáveis pela configuração de sessão do fornecedor. Chamada de voz e Google Meet são responsáveis por adaptadores de telefonia/reunião. Navegador e apps 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. adicione o novo contrato
2. mantenha o comportamento antigo conectado por meio de um adaptador de compatibilidade
3. emita um diagnóstico ou aviso que nomeie o caminho antigo e a substituição
4. cubra ambos os caminhos em testes
5. documente a descontinuação e o caminho de migração
6. remova somente após a janela de migração anunciada, geralmente em uma versão principal

Os 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 em código/docs, expõe importações reservadas do SDK entre proprietários e resume a ponte privada do SDK de 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 precisam ter uso de proprietário rastreado; exports auxiliares reservados não utilizados devem ser removidos do SDK público.

Se um campo de manifesto ainda é aceito, os 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 minor comuns.

# Como migrar

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

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

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm 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. A lista completa de mais de 200 pontos de entrada fica em scripts/lib/plugin-sdk-entrypoints.json.

As interfaces auxiliares reservadas de plugins incluídos foram removidas do mapa de exportação público do SDK, exceto 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 possuí-la.

# Descontinuações ativas

Descontinuações mais restritas 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.

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import 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 run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

# Relacionado

• Primeiros passos - 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 de plugins - análise detalhada da arquitetura
• Manifesto de plugin - referência do esquema de manifesto