Migración del SDK de Plugin

OpenClaw ha pasado de una amplia capa 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 migrar.

Qué está cambiando

El sistema de plugins anterior proporcionaba dos superficies completamente 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 docenas 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 amplio barrel 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 amplio barrel de compatibilidad de configuración que aún 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 lado del host como el ejecutor de agente integrado.
• api.registerEmbeddedExtensionFactory(...) - un hook de extensión integrada eliminado, solo para Pi, 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 nuevos plugins no deben usarlas, y los plugins existentes deberían migrar antes de que la próxima versión principal las elimine. La API de registro de fábrica de extensión integrada solo para Pi se eliminó; usa middleware de resultado de herramienta en su lugar.

OpenClaw no elimina ni reinterpreta comportamiento de plugin documentado en el mismo cambio que introduce un reemplazo. Los cambios de contrato incompatibles primero deben pasar por un adaptador de compatibilidad, diagnósticos, documentación y una ventana de obsolescencia. Eso se aplica a importaciones del SDK, campos del manifiesto, API 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 docenas 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é exports eran estables frente a internos

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

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

Ejemplos actuales de providers integrados:

• Anthropic mantiene helpers de stream específicos de Claude en su propia costura api.ts / contract-api.ts
• OpenAI mantiene constructores de provider, helpers de modelo predeterminado y constructores de provider en tiempo real en su propio api.ts
• OpenRouter mantiene el constructor de provider 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 de la contabilidad de turnos local de la 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 de Talk, el estado de 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 provider deberían seguir siendo dueños de las sesiones en tiempo real específicas del proveedor; los plugins de superficie deberían 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 el controlador compartido y las primitivas de runtime en plugin-sdk/realtime-voice.
2. Migra las superficies integradas al controlador compartido: relay de navegador, handoff de sala gestionada, llamadas de voz en tiempo real, STT en streaming de llamadas de voz, Google Meet en tiempo real y push-to-talk nativo.
3. Sustituye las antiguas familias RPC de Talk por la API final talk.session.* y talk.client.*.
4. Anuncia un canal de eventos Talk en vivo en Gateway hello-ok.features.events: talk.event.
5. Elimina el antiguo endpoint HTTP en tiempo real y cualquier ruta de sobrescritura de instrucciones en tiempo de solicitud.

El código nuevo no debería llamar a createTalkEventSequencer(...) directamente salvo que esté implementando un adaptador de bajo nivel o una 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 turnEnd / turnCancel obsoletas no puedan borrar un turno activo más nuevo, y los eventos de ciclo de vida de audio de salida permanezcan coherentes entre telefonía, reuniones, relay de navegador, handoff de sala gestionada 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 });

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

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

Las combinaciones admitidas de talk.session.create son intencionalmente reducidas:

Mapa de métodos eliminados:

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

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

Política de compatibilidad

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

1. agregar el nuevo contrato
2. mantener el comportamiento anterior conectado mediante un adaptador de compatibilidad
3. emitir un diagnóstico o una advertencia que nombre la ruta anterior y su reemplazo
4. cubrir ambas rutas en las 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 conteos compactos, --owner <id> para un Plugin o propietario de compatibilidad, y pnpm plugins:boundary-report:ci cuando una puerta de CI deba fallar ante registros de compatibilidad vencidos, importaciones de SDK reservadas entre propietarios o subrutas de SDK reservadas sin usar. El informe agrupa los registros de compatibilidad obsoletos por fecha de eliminación, cuenta referencias locales de código/docs, muestra importaciones de SDK reservadas entre propietarios y resume el puente privado del SDK del host de memoria para que la limpieza de compatibilidad permanezca explícita en lugar de depender de búsquedas ad hoc. Las subrutas de SDK reservadas deben tener uso de propietario rastreado; las exportaciones de ayudantes reservados sin usar deben eliminarse del SDK público.

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

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

Referencia de rutas de importación

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

Las uniones auxiliares reservadas de plugins incluidos se han retirado del mapa de exportaciones públicas del SDK, excepto por las fachadas de compatibilidad documentadas explícitamente, como el shim obsoleto plugin-sdk/discord conservado para el paquete publicado @openclaw/[email protected]. Los auxiliares específicos del propietario viven dentro del paquete del plugin propietario; el comportamiento compartido del host debe pasar por 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 específica que coincida con la tarea. Si no encuentras una exportación, revisa el código fuente en src/plugin-sdk/ o pregunta a los mantenedores qué contrato genérico debería poseerla.

Obsolescencias activas

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

// 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 eliminación

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

Suprimir las advertencias temporalmente

Configura 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
• Resumen del SDK - referencia completa de importaciones por subruta
• Plugins de canal - crear plugins de canal
• Plugins de proveedor - crear plugins de proveedor
• Internos de Plugin - análisis profundo de la arquitectura
• Manifiesto de Plugin - referencia del esquema del manifiesto