Migración del SDK de Plugin

OpenClaw ha pasado de una capa amplia de compatibilidad con versiones anteriores a una arquitectura moderna de plugins con importaciones enfocadas y documentadas. Si tu plugin se creó antes de la nueva arquitectura, esta guía te ayuda a migrarlo.

Qué está cambiando

El sistema de plugins anterior proporcionaba dos superficies totalmente abiertas que permitían a los plugins importar todo lo que necesitaban desde un único punto de entrada:

• openclaw/plugin-sdk/compat - una única importación que reexportaba decenas de helpers. Se introdujo para mantener funcionando los plugins antiguos basados en hooks mientras se construía la nueva arquitectura de plugins.
• openclaw/plugin-sdk/infra-runtime - un barrel amplio de helpers de runtime que mezclaba eventos del sistema, estado de Heartbeat, colas de entrega, helpers de fetch/proxy, helpers de archivos, tipos de aprobación y utilidades no relacionadas.
• openclaw/plugin-sdk/config-runtime - un barrel amplio de compatibilidad de configuración que todavía conserva helpers directos de carga/escritura obsoletos durante la ventana de migración.
• openclaw/extension-api - un puente que daba a los plugins acceso directo a helpers del host, como el ejecutor de agente integrado.
• api.registerEmbeddedExtensionFactory(...) - un hook de extensión empaquetada, exclusivo del ejecutor integrado y eliminado, que podía observar eventos del ejecutor integrado como tool_result.

Las superficies de importación amplias ahora están obsoletas. Todavía funcionan en runtime, pero los plugins nuevos no deben usarlas, y los plugins existentes deberían migrar antes de que la próxima versión mayor las elimine. La API de registro de fábricas de extensión exclusiva del ejecutor integrado se eliminó; usa middleware de resultados de herramientas en su lugar.

OpenClaw no elimina ni reinterpreta comportamiento documentado de plugins en el mismo cambio que introduce un reemplazo. Los cambios que rompen contratos deben pasar primero por un adaptador de compatibilidad, diagnósticos, documentación y una ventana de obsolescencia. Eso aplica a importaciones del SDK, campos de manifiesto, APIs de configuración, hooks y comportamiento de registro en runtime.

Por qué cambió esto

El enfoque anterior causaba problemas:

• Inicio lento - importar un helper cargaba decenas de módulos no relacionados
• Dependencias circulares - las reexportaciones amplias facilitaban crear ciclos de importación
• Superficie de API poco clara - no había forma de saber qué exportaciones eran estables frente a internas

El SDK moderno de plugins soluciona esto: cada ruta de importación (openclaw/plugin-sdk/\<subpath\>) es un módulo pequeño, autónomo, con un propósito claro y un contrato documentado.

Las superficies heredadas de conveniencia de proveedores para canales empaquetados también desaparecieron. Las superficies helper con marca de canal eran atajos privados del monorepo, no contratos estables de plugins. Usa subrutas genéricas y estrechas del SDK en su lugar. Dentro del workspace de plugins empaquetados, mantén los helpers propiedad del proveedor en el propio api.ts o runtime-api.ts de ese plugin.

Ejemplos actuales de proveedores empaquetados:

• Anthropic mantiene helpers de streaming específicos de Claude en su propia superficie api.ts / contract-api.ts
• OpenAI mantiene constructores de proveedor, helpers de modelo predeterminado y constructores de proveedor en tiempo real en su propio api.ts
• OpenRouter mantiene el constructor de proveedor y los helpers de onboarding/configuración en su propio api.ts

Plan de migración de Talk y voz en tiempo real

El código de Talk para voz en tiempo real, telefonía, reuniones y navegador se está moviendo desde la contabilidad de turnos local de cada superficie a un controlador compartido de sesiones Talk exportado por openclaw/plugin-sdk/realtime-voice. El nuevo controlador posee el sobre común de eventos Talk, el estado del turno activo, el estado de captura, el estado de audio de salida, el historial reciente de eventos y el rechazo de turnos obsoletos. Los plugins de proveedor deben seguir siendo dueños de las sesiones en tiempo real específicas del proveedor; los plugins de superficie deben seguir siendo dueños de las particularidades de captura, reproducción, telefonía y reuniones.

Esta migración de Talk es intencionalmente una ruptura limpia:

1. Mantén las primitivas compartidas de controlador/runtime en plugin-sdk/realtime-voice.
2. Mueve las superficies empaquetadas al controlador compartido: relay de navegador, handoff de sala administrada, tiempo real de llamada de voz, STT en streaming de llamada de voz, Google Meet en tiempo real y push-to-talk nativo.
3. Reemplaza las antiguas familias RPC de Talk con la API final talk.session.* y talk.client.*.
4. Anuncia un único canal de eventos Talk en vivo en Gateway hello-ok.features.events: talk.event.
5. Elimina el antiguo endpoint HTTP de tiempo real y cualquier ruta de sobrescritura de instrucciones en tiempo de solicitud.

El código nuevo no debería llamar directamente a createTalkEventSequencer(...) salvo que esté implementando un adaptador de bajo nivel o un fixture de prueba. Prefiere el controlador compartido para que los eventos con alcance de turno no puedan emitirse sin un id de turno, las llamadas obsoletas turnEnd / turnCancel no puedan borrar un turno activo más nuevo, y los eventos del ciclo de vida del audio de salida se mantengan consistentes entre telefonía, reuniones, relay de navegador, handoff de sala administrada y clientes Talk nativos.

La forma objetivo de la API pública es:

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

Las sesiones WebRTC/websocket de proveedor propiedad del navegador usan talk.client.create, porque el navegador posee la negociación con el proveedor y el transporte de medios mientras el Gateway posee las credenciales, instrucciones y política de herramientas. talk.session.* es la superficie común administrada por Gateway para tiempo real con gateway-relay, transcripción con gateway-relay y sesiones nativas STT/TTS de sala administrada.

Las configuraciones heredadas que colocaban selectores de tiempo real junto a talk.provider / talk.providers deben repararse con openclaw doctor --fix; el runtime de Talk no reinterpreta la configuración de proveedor de voz/TTS como configuración de proveedor de tiempo real.

Las combinaciones admitidas de talk.session.create son intencionalmente pequeñas:

Mapa de métodos eliminados:

El vocabulario de control unificado también es deliberadamente estrecho:

No introduzcas casos especiales de proveedor o plataforma en core para que esto funcione. Core posee la semántica de las sesiones de Talk. Los plugins de proveedor poseen la configuración de sesiones de proveedor. Las llamadas de voz y Google Meet poseen los adaptadores de telefonía/reuniones. Las apps de navegador y nativas poseen la UX de captura/reproducción del dispositivo.

Política de compatibilidad

Para plugins externos, el trabajo de compatibilidad sigue este orden:

1. añadir el contrato nuevo
2. mantener el comportamiento antiguo conectado mediante un adaptador de compatibilidad
3. emitir un diagnóstico o advertencia que nombre la ruta antigua y el reemplazo
4. cubrir ambas rutas en pruebas
5. documentar la obsolescencia y la ruta de migración
6. eliminar solo después de la ventana de migración anunciada, normalmente en una versión mayor

Los mantenedores pueden auditar la cola de migración actual con pnpm plugins:boundary-report. Usa pnpm plugins:boundary-report:summary para recuentos compactos, --owner <id> para un plugin o propietario de compatibilidad, y pnpm plugins:boundary-report:ci cuando una puerta de CI deba fallar por registros de compatibilidad vencidos, importaciones reservadas del SDK entre propietarios o subrutas reservadas del SDK sin usar. El informe agrupa los registros de compatibilidad obsoletos por fecha de eliminación, cuenta referencias locales de código/docs, expone importaciones reservadas del SDK entre propietarios y resume el puente privado del SDK del host de memoria para que la limpieza de compatibilidad siga siendo explícita en lugar de depender de búsquedas ad hoc. Las subrutas reservadas del SDK deben tener uso de propietario rastreado; las exportaciones de helpers reservados sin uso deben eliminarse del SDK público.

Si un campo del manifiesto todavía se acepta, los autores de plugins pueden seguir usándolo hasta que la documentación y los diagnósticos indiquen lo contrario. El código nuevo debe preferir el reemplazo documentado, pero los plugins existentes no deben romperse durante versiones menores ordinarias.

Cómo 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/

Referencia de rutas de importación

Esta tabla es intencionalmente el subconjunto común de migración, no toda la superficie del SDK. El inventario de puntos de entrada del compilador vive en scripts/lib/plugin-sdk-entrypoints.json; las exportaciones del paquete se generan desde el subconjunto público.

Las costuras auxiliares reservadas para plugins incluidos se han retirado del mapa de exportación público del SDK, salvo fachadas de compatibilidad documentadas explícitamente, como el shim obsoleto plugin-sdk/discord conservado para el paquete publicado @openclaw/discord@2026.3.13. Los auxiliares específicos del propietario viven dentro del paquete del plugin propietario; el comportamiento compartido del host debe moverse mediante contratos genéricos del SDK como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime y plugin-sdk/plugin-config-runtime.

Usa la importación más estrecha que coincida con el trabajo. Si no encuentras una exportación, revisa la fuente en src/plugin-sdk/ o pregunta a los mantenedores qué contrato genérico debería poseerla.

Obsolescencias activas

Obsolescencias más estrechas que se aplican en todo el SDK de plugins, el contrato de proveedor, la superficie de runtime y el manifiesto. Cada una sigue funcionando hoy, pero se eliminará en una versión mayor futura. La entrada debajo de cada elemento asigna la API antigua a su reemplazo canónico.

// 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";

Cronología de eliminación

Todos los plugins principales ya se han migrado. Los plugins externos deben migrar antes de la próxima versión mayor.

Suprimir temporalmente las advertencias

Define estas variables de entorno mientras trabajas en la migración:

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

Esta es una vía de escape temporal, no una solución permanente.

Relacionado

• Primeros pasos - crea tu primer plugin
• Descripción general del SDK - referencia completa de importaciones de subrutas
• Plugins de canal - crear plugins de canal
• Plugins de proveedor - crear plugins de proveedor
• Internals de Plugin - análisis profundo de la arquitectura
• Manifiesto de Plugin - referencia del esquema del manifiesto