Migración del SDK de Plugin

OpenClaw sustituyó una amplia capa de compatibilidad con versiones anteriores por una arquitectura moderna de plugins basada en importaciones pequeñas y específicas. Si el plugin es anterior a ese cambio, esta guía permite adaptarlo a los contratos actuales.

Qué cambió

Dos superficies de importación totalmente abiertas permitían que los plugins accedieran a casi cualquier elemento desde un único punto de entrada:

• openclaw/plugin-sdk/compat - reexportaba decenas de utilidades para mantener operativos los plugins antiguos basados en hooks mientras se desarrollaba la nueva arquitectura.
• openclaw/plugin-sdk/infra-runtime - un barrel amplio que combinaba eventos del sistema, estado de Heartbeat, colas de entrega, utilidades de obtención/proxy, utilidades de archivos, tipos de aprobación y utilidades no relacionadas.
• openclaw/plugin-sdk/config-runtime - un barrel de configuración amplio que aún incluía utilidades directas de carga/escritura obsoletas durante el periodo de migración.
• openclaw/extension-api - un puente que proporcionaba a los plugins acceso directo a utilidades del lado del host, como el ejecutor de agentes integrado.
• api.registerEmbeddedExtensionFactory(...) - un hook eliminado y exclusivo del ejecutor integrado que observaba eventos de este, como tool_result. En su lugar, use middleware de resultados de herramientas del agente (consulte Migrar extensiones de resultados de herramientas integradas a middleware).

Estas superficies están obsoletas: todavía funcionan, pero los plugins nuevos no deben usarlas y los existentes deberían migrar antes de que la próxima versión principal las elimine. registerEmbeddedExtensionFactory ya se ha eliminado; los registros heredados ya no se cargan.

OpenClaw no elimina ni reinterpreta el comportamiento documentado de los plugins en el mismo cambio que introduce un sustituto. Los cambios de contrato incompatibles pasan primero por un adaptador de compatibilidad, diagnósticos, documentación y un periodo de obsolescencia. Esto se aplica a las importaciones del SDK, los campos del manifiesto, las API de configuración, los hooks y el comportamiento de registro en tiempo de ejecución.

Motivos

• Inicio lento - importar una utilidad cargaba decenas de módulos no relacionados.
• Dependencias circulares - las reexportaciones amplias facilitaban la creación de ciclos de importación.
• Superficie de API poco clara - no había forma de distinguir las exportaciones estables de las internas.

Ahora, cada openclaw/plugin-sdk/<subpath> es un módulo pequeño y autónomo con un contrato documentado.

También se han eliminado las interfaces heredadas de conveniencia de proveedores para los canales incluidos: los accesos directos a utilidades asociados a canales eran comodidades privadas del monorrepositorio, no contratos estables de plugins. En su lugar, use subrutas genéricas y específicas del SDK. Dentro del espacio de trabajo de plugins incluidos, mantenga las utilidades propiedad del proveedor en los propios api.ts o runtime-api.ts de ese plugin:

• Anthropic mantiene las utilidades de transmisión específicas de Claude en su propia interfaz api.ts / contract-api.ts.
• OpenAI mantiene los constructores de proveedores, las utilidades del modelo predeterminado y los constructores de proveedores en tiempo real en su propio api.ts.
• OpenRouter mantiene el constructor de proveedores y las utilidades de incorporación/configuración en su propio api.ts.

Política de compatibilidad

El trabajo de compatibilidad para plugins externos sigue este orden:

1. Añadir el contrato nuevo.
2. Mantener el comportamiento anterior conectado mediante un adaptador de compatibilidad.
3. Emitir un diagnóstico o una advertencia que indique la ruta anterior y su sustituta.
4. Cubrir ambas rutas en las pruebas.
5. Documentar la obsolescencia y la ruta de migración.
6. Eliminar únicamente después del periodo de migración anunciado, normalmente en una versión principal.

Si todavía se acepta un campo del manifiesto, continúe usándolo hasta que la documentación y los diagnósticos indiquen lo contrario. El código nuevo debería preferir el sustituto documentado; los plugins existentes no deberían dejar de funcionar durante las versiones secundarias ordinarias.

Audite la cola de migración actual con pnpm plugins:boundary-report:

pnpm plugins:boundary-report:ci se ejecuta con las tres opciones de fallo. Cada registro de compatibilidad tiene una fecha removeAfter explícita (no una imprecisa «próxima versión principal»): el informe agrupa los registros obsoletos por esa fecha, cuenta las referencias locales en código/documentación, muestra las importaciones reservadas del SDK entre propietarios y resume el puente privado del SDK del host de memoria. Las subrutas reservadas del SDK deben tener un uso registrado por parte del propietario; las exportaciones reservadas sin usar deberían eliminarse del SDK público.

Cómo migrar

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

// Herramientas dinámicas de los entornos de ejecución OpenClaw y Codexapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Antesconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Despuésconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Establezca esta opción únicamente para llamadores de compatibilidad de confianza que acepten  // deliberadamente la alternativa mediada por el 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 (capa obsoleta de compatibilidad con versiones anteriores)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // Después (importaciones modernas 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 (puente extension-api obsoleto)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // Después (entorno de ejecución inyectado)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

Referencia de rutas de importación

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

Las interfaces auxiliares reservadas para plugins incluidos se han retirado del mapa de exportaciones del SDK público, salvo las fachadas de compatibilidad documentadas explícitamente, como el shim obsoleto plugin-sdk/discord, que se conserva para los plugins externos que todavía importan directamente el paquete publicado @openclaw/discord. Los auxiliares específicos de cada propietario se encuentran dentro del paquete del plugin correspondiente; el comportamiento compartido del host se canaliza mediante contratos genéricos del SDK, como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime y plugin-sdk/plugin-config-runtime.

Utilice la importación más específica que corresponda a la tarea. Si no encuentra una exportación, consulte el código fuente en src/plugin-sdk/ o pregunte a los responsables qué contrato genérico debe hacerse cargo de ella.

Obsolescencias activas

Obsolescencias más específicas en el SDK de plugins, el contrato de proveedores, la superficie de ejecución y el manifiesto. Todas siguen funcionando actualmente, pero se eliminarán en una futura versión principal. Cada entrada asigna la API antigua a su reemplazo canónico.

// Antesimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Despuésimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Antesapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Despuésapi.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" },})); // Despuésapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

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

// Antesconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Despuésconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

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

Migración de Talk y voz en tiempo real

El código de voz en tiempo real, telefonía, reuniones y Talk en el navegador comparte un único controlador de sesiones de Talk exportado por openclaw/plugin-sdk/realtime-voice. El controlador gestiona el contenedor común de eventos de Talk, el estado del turno activo, el estado de captura, el estado del audio de salida, el historial de eventos recientes y el rechazo de turnos obsoletos. Los plugins de proveedores gestionan las sesiones en tiempo real específicas de cada proveedor; los plugins de superficie gestionan las particularidades de la captura, la reproducción, la telefonía y las reuniones.

Todas las superficies incluidas se ejecutan en el controlador compartido: retransmisión del navegador, transferencia a salas administradas, llamadas de voz en tiempo real, STT en streaming para llamadas de voz, Google Meet en tiempo real y pulsar para hablar nativo. Gateway anuncia un único canal activo de eventos de Talk en hello-ok.features.events: talk.event.

El código nuevo no debe llamar directamente a createTalkEventSequencer(...), salvo que implemente un adaptador de bajo nivel o un accesorio de prueba. Use el controlador compartido para que no puedan emitirse eventos delimitados por turno sin un identificador de turno, las llamadas obsoletas a turnEnd / turnCancel no puedan borrar un turno activo más reciente y los eventos del ciclo de vida del audio de salida sean coherentes entre telefonía, reuniones, retransmisión del navegador, transferencia a salas administradas y clientes nativos de Talk.

La forma de la API pública:

// API de sesión de Talk gestionada por 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 sesión del proveedor gestionada por el 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" });

Las sesiones WebRTC/websocket del proveedor gestionadas por el navegador usan talk.client.create, porque el navegador gestiona la negociación con el proveedor y el transporte multimedia, mientras que Gateway gestiona las credenciales, las instrucciones y la política de herramientas. talk.session.* es la superficie común administrada por Gateway para tiempo real mediante retransmisión de Gateway, transcripción mediante retransmisión de Gateway y sesiones nativas de STT/TTS en salas administradas.

Las configuraciones heredadas que sitúan selectores de tiempo real junto a talk.provider / talk.providers deben repararse con openclaw doctor --fix; Talk en tiempo de ejecución no reinterpreta la configuración del proveedor de voz/TTS como configuración del proveedor en tiempo real.

Las combinaciones compatibles de talk.session.create son intencionadamente limitadas:

Mapa de métodos para quienes migren desde las familias anteriores talk.realtime.* / talk.transcription.* / talk.handoff.* (todas eliminadas):

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

No introduzca casos especiales de proveedores o plataformas en el núcleo para que esto funcione. El núcleo gestiona la semántica de las sesiones de Talk. Los plugins de proveedores gestionan la configuración de sesiones de cada proveedor. Las llamadas de voz y Google Meet gestionan los adaptadores de telefonía/reuniones. El navegador y las aplicaciones nativas gestionan la experiencia de usuario de captura/reproducción del dispositivo.

Cronología de eliminación

Todos los plugins principales ya se han migrado. Los plugins externos deben migrarse antes de la próxima versión principal. Ejecute pnpm plugins:boundary-report para consultar qué registros de compatibilidad vencerán antes para las superficies que utiliza su plugin.

Suprimir temporalmente las advertencias

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.

Contenido relacionado

• Primeros pasos - cree su primer plugin
• Descripción general del SDK - referencia completa de importaciones de subrutas
• Plugins de canal - creación de plugins de canal
• Plugins de proveedor - creación de plugins de proveedor
• Aspectos internos de los plugins - análisis detallado de la arquitectura
• Manifiesto del plugin - referencia del esquema del manifiesto