Migración del SDK de plugins

OpenClaw sustituyó una amplia capa de compatibilidad con versiones anteriores por una arquitectura de plugins moderna construida a partir de 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ó

Anteriormente, varias superficies de importación muy abiertas permitían que los plugins accedieran a casi cualquier cosa desde un único punto de entrada:

• openclaw/plugin-sdk y openclaw/plugin-sdk/compat: reexportaban decenas de auxiliares mientras se desarrollaba el SDK específico. Ambas raíces se han eliminado; importe en su lugar una subruta documentada.
• openclaw/plugin-sdk/infra-runtime: un barrel amplio que mezclaba eventos del sistema, estado de Heartbeat, colas de entrega, auxiliares de obtención/proxy, auxiliares de archivos, tipos de aprobación y utilidades no relacionadas.
• openclaw/plugin-sdk/config-runtime: un barrel de configuración amplio conservado únicamente durante su ventana de compatibilidad posterior; se han eliminado los auxiliares directos de carga/escritura en tiempo de ejecución.
• openclaw/extension-api: un puente eliminado que proporcionaba a los plugins acceso directo a auxiliares del lado del host, como el ejecutor de agentes integrado.
• api.registerEmbeddedExtensionFactory(...): un hook eliminado exclusivo del ejecutor integrado que observaba eventos de dicho ejecutor, como tool_result. Use en su lugar middleware de resultados de herramientas del agente (consulte Migrar extensiones de resultados de herramientas integradas a middleware).

Se han eliminado el SDK raíz, el barrel de compatibilidad, el puente de extensiones y la fábrica de extensiones integradas. infra-runtime y config-runtime se mantienen únicamente durante sus ventanas posteriores registradas por separado; los plugins nuevos deben usar subrutas específicas.

OpenClaw no elimina ni reinterpreta el comportamiento documentado de los plugins en el mismo cambio que introduce un reemplazo. Los cambios incompatibles en los contratos 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 un auxiliar 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 antiguas interfaces auxiliares de proveedores para los canales incluidos: los atajos auxiliares específicos de cada canal eran recursos privados del monorrepositorio, no contratos estables para plugins. Use en su lugar subrutas genéricas y específicas del SDK. Dentro del espacio de trabajo de plugins incluidos, mantenga los auxiliares propiedad del proveedor en los api.ts o runtime-api.ts del propio plugin:

• Anthropic mantiene los auxiliares de flujos específicos de Claude en su propia interfaz api.ts / contract-api.ts.
• OpenAI mantiene los constructores de proveedores, los auxiliares de modelos predeterminados y los constructores de proveedores en tiempo real en su propio api.ts.
• OpenRouter mantiene el constructor de proveedores y los auxiliares de incorporación/configuración en su propio api.ts.

Política de compatibilidad

El trabajo de compatibilidad de plugins externos sigue este orden:

1. Añadir el nuevo contrato.
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 reemplazo.
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, siga utilizándolo hasta que la documentación y los diagnósticos indiquen lo contrario. El código nuevo debe preferir el reemplazo documentado; los plugins existentes no deben dejar de funcionar durante actualizaciones menores ordinarias.

Compatibilidad de la configuración de canales publicados

Los paquetes de Slack, Discord, Signal y Microsoft Teams publicados mediante 2026.7.1 importan esquemas de configuración específicos del canal desde openclaw/plugin-sdk/bundled-channel-config-schema. Los paquetes publicados de Slack y Discord también importan createLegacyCompatChannelDmPolicy y promptLegacyChannelAllowFromForAccount desde openclaw/plugin-sdk/setup-runtime.

Esas exportaciones siguen disponibles como adaptadores de compatibilidad en tiempo de ejecución obsoletos. Los plugins nuevos y republicados deben gestionar localmente sus propios esquemas de configuración y su política de configuración mediante primitivas genéricas de channel-config-schema y setup-runtime. Las exportaciones de compatibilidad solo pueden eliminarse cuando las versiones mínimas admitidas de los paquetes publicados ya no las importen.

Compatibilidad de campos de entrada de configuración de canales

ChannelSetupInput ahora mantiene tipado permanentemente solo el contenedor de configuración común a todos los canales. Los campos específicos de cada canal permanecen tipados en un nivel de compatibilidad obsoleto para que los plugins externos existentes sigan compilándose mientras sus autores trasladan esos campos a tipos de entrada de configuración locales del plugin.

OpenClaw no publica versiones principales. Un análisis del registro realizado el 2026-07-22 inspeccionó 426 plugins de canal externos publicados y eliminó 21 campos sin lectores. Cada uno de los 22 campos conservados tiene un lector publicado conocido. Cada campo adicional se elimina en cuanto ningún plugin publicado lo lee; el conjunto conservado se reduce a medida que los autores de plugins migran a tipos de entrada de configuración locales del plugin.

El mismo análisis eliminó 23 claves heredadas de promoción de adaptadores no declaradas sin dependientes publicados. Permanecen seis claves comunes y la clave exclusiva de configuración rooms. Ese conjunto también se reduce a medida que los plugins publicados declaran singleAccountKeysToMove.

El tipo compartido no tiene firma de índice. Las claves propiedad del plugin pueden seguir presentes en los objetos de entrada en tiempo de ejecución; declárelas en una intersección local del plugin o redúzcalas mediante el esquema de configuración del plugin propietario.

El nivel heredado de promoción de adaptadores no declarados sigue la misma política basada en lectores. Declare singleAccountKeysToMove, incluido un array vacío cuando el plugin no necesite claves de promoción adicionales, para que el recurso compartido alternativo pueda retirarse clave por clave.

Verificación de lectores

1. Recorra por páginas https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 con cada nextCursor y conserve los paquetes cuyos categories incluyan channels.
2. Añada candidatos de npm desde npm search --json --searchlimit=1000 "openclaw channel plugin". Añada candidatos disponibles solo como código fuente a partir de búsquedas de código de GitHub para openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup y openclaw/plugin-sdk/core.
3. Determine la última versión publicada de cada candidato. Ejecute npm pack <package>@<version> --json --pack-destination <temp-dir>, desempaquétela e inspeccione el JavaScript y las declaraciones distribuidos en dist para detectar lecturas directas o desestructuradas de campos. Descargue el artefacto de ClawHub cuando un paquete no tenga una versión en npm.
4. Registre el paquete, la versión, el campo o la clave de promoción y el archivo coincidente. Un campo o una clave solo puede eliminarse cuando ningún artefacto publicado de un plugin lo lea. Mantenga sincronizados con el análisis los nombres de los lectores en los comentarios del código junto a las listas de campos y claves conservados.

Este es únicamente un registro de compatibilidad de código fuente/tipos. No tiene ningún adaptador en tiempo de ejecución ni entrada en el registro de compatibilidad porque los objetos de entrada de configuración en tiempo de ejecución y el comportamiento de configuración no han cambiado.

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

pnpm plugins:boundary-report:ci se ejecuta con las tres opciones de error. Los registros obsoletos suelen tener una fecha removeAfter explícita en lugar de una imprecisa «próxima versión principal». Un registro cuyo propietario no haya aprobado una fecha deja removeAfter ausente, aparece como no-date y nunca puede eliminarse. El informe agrupa los registros obsoletos por fecha, cuenta las referencias locales de 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 deben eliminarse del SDK público.

Proyección heredada de medios

El registro de compatibilidad media-legacy-projection abarca los antiguos campos paralelos de medios, los constructores de payloads, los alias de metadatos de hooks y los nombres de plantillas de medios. Su fecha removeAfter aprobada es 2026-10-01 (dos ciclos de publicación después de que se distribuyeran los reemplazos basados primero en hechos). Además, su eliminación requiere en ese momento un análisis limpio de los artefactos de plugins publicados; migre antes de la fecha.

Para la entrada de canales, sustituya los valores singular/plural MediaPath, MediaUrl, MediaType, MediaPaths, MediaUrls, MediaTypes, MediaTranscribedIndexes, MediaWorkspaceDir y MediaStaged por hechos ordenados:

 const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

Use event.media en los hooks inbound_claim y message_received. Si los medios remotos no se han preparado localmente, use event.originalMedia para identidad/diagnósticos y espere a event.media; event.mediaStagingPending distingue ese estado. No lea las propiedades singular/plural obsoletas de event.metadata.

Para los modelos multimedia de la CLI, sustituya {{MediaPath}}, {{MediaUrl}}, {{MediaType}} y {{MediaDir}} por {{AttachmentPath}}, {{AttachmentUrl}}, {{AttachmentContentType}} y {{AttachmentDir}}. Use {{AttachmentIndex}} cuando la posición de los archivos adjuntos sea importante.

Para la política de lectura de medios locales, importe getAgentScopedMediaLocalRoots(...) o getAgentScopedMediaLocalRootsForSources(...) desde openclaw/plugin-sdk/media-local-roots. La fachada openclaw/plugin-sdk/agent-media-payload y su proyección buildAgentMediaPayload(...) están obsoletas.

Cómo migrar

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

// Herramientas del entorno de ejecución de OpenClaw y herramientas dinámicas del entorno de ejecución de Codex (el resultado puede// transformarse). Los resultados de herramientas nativas de Codex también se retransmiten para su observación,// pero su salida transformada nunca llega al modelo: el contrato del hook// PostToolUse de Codex no puede reemplazar una respuesta de herramienta nativa.api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Antesconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Despuésconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Establezca esto únicamente para llamadores de compatibilidad de confianza que acepten  // deliberadamente el respaldo mediado 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 retrocompatibilidad)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

El mapa de exportaciones del paquete público es la fuente de verdad de las subrutas importables del SDK. Use las guías temáticas del SDK enlazadas desde la descripción general del SDK y prefiera la subruta pública documentada más específica. El inventario del compilador en scripts/lib/plugin-sdk-entrypoints.json también contiene entradas locales privadas utilizadas para compilar plugins incluidos; su presencia allí no las convierte en exportaciones públicas del paquete.

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 del paquete 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, conservado para plugins externos que todavía importan directamente el paquete publicado @openclaw/discord. Los asistentes específicos de cada propietario residen 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 la API del plugin inyectada.

Use 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 asumirla.

Superficies de compatibilidad eliminadas

La revisión de julio de 2026 eliminó los barrels raíz y de compatibilidad del SDK, el puente de la API de extensiones, los alias caducados de subrutas del SDK, las subrutas del SDK sin uso y las exportaciones públicas de módulos del SDK exclusivos de plugins incluidos. Los módulos exclusivos de plugins incluidos siguen disponibles para sus propietarios del repositorio mediante asignaciones de compilación locales privadas; no pueden importarse desde el paquete publicado.

Publicación global del proceso de proveedores de API

registerApiProvider(...) y unregisterApiProviders(...) se eliminaron de openclaw/plugin-sdk/llm. Publicaban transportes de API en el estado global del proceso, que los entornos de ejecución de modelos administrados por el ciclo de vida debían copiar después en cada registro preparado.

Los plugins de proveedores deben registrar los proveedores de inferencia de texto mediante api.registerProvider(...). El código y las pruebas propiedad del host que construyan un ApiRegistry deben registrarse directamente en ese registro para que la propiedad del proveedor y su desmontaje permanezcan limitados al entorno de ejecución preparado.

Barrel privado de pruebas

openclaw/plugin-sdk/testing era local del repositorio y estaba excluido de los artefactos del paquete distribuido, por lo que se eliminó antes de su fecha removeAfter de 2026-07-28. Las pruebas del repositorio usan subrutas específicas como plugin-sdk/plugin-test-runtime, plugin-sdk/channel-test-helpers, plugin-sdk/channel-target-testing, plugin-sdk/test-env y plugin-sdk/test-fixtures.

Referencia de migración

Estas correspondencias abarcan tanto las superficies eliminadas en julio de 2026 como las desaprobaciones activas de periodos posteriores. Una correspondencia es una guía de migración, no una prueba de que la superficie anterior siga disponible; consulte el registro de compatibilidad y el calendario de eliminación para conocer el estado actual.

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

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 sobre 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 proveedor gestionan las sesiones en tiempo real específicas del proveedor. Los plugins de reuniones en el navegador utilizan openclaw/plugin-sdk/meeting-runtime para los mecanismos de sesión, navegador, audio, host de Node, consulta con el agente y llamada de voz, y luego implementan MeetingPlatformAdapter para las reglas de URL, los scripts del DOM, la asignación de acciones manuales, los subtítulos, la creación y los planes de acceso telefónico. Las API REST de la plataforma, OAuth, los artefactos, los selectores y los nombres del protocolo permanecen en el plugin. Los planes de permisos del navegador reciben la URL de reunión solicitada para que cada plataforma pueda conceder únicamente sus orígenes compatibles exactos. Los entornos de ejecución de sesión también deben normalizar el estado de funcionamiento en directo específico de la plataforma tras confirmarse la salida del navegador; los campos históricos de la transcripción pueden permanecer, pero la disponibilidad de subtítulos y audio no debe seguir activa después de salir.

Todas las superficies incluidas se ejecutan en el controlador compartido: relay del navegador, transferencia de sala gestionada, llamada de voz en tiempo real, STT de transmisión de llamadas de voz, Google Meet en tiempo real y pulsar para hablar nativo. El Gateway anuncia un único canal de eventos de Talk en directo 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 fixture de prueba. Utilice el controlador compartido para que los eventos limitados a un turno no puedan emitirse sin un identificador de turno, las llamadas obsoletas turnEnd / turnCancel no puedan borrar un turno activo más reciente y los eventos del ciclo de vida del audio de salida permanezcan coherentes entre la telefonía, las reuniones, el relay del navegador, la transferencia de sala gestionada y los clientes nativos de Talk.

La forma de la API pública:

// API de sesiones de Talk gestionada por el 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 sesiones de 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 de WebRTC/websocket de proveedor gestionadas por el navegador utilizan talk.client.create, porque el navegador gestiona la negociación con el proveedor y el transporte multimedia, mientras que el Gateway gestiona las credenciales, las instrucciones y la política de herramientas. talk.session.* es la superficie común gestionada por el Gateway para las sesiones en tiempo real mediante relay del Gateway, la transcripción mediante relay del Gateway y las sesiones nativas de STT/TTS de salas gestionadas.

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 reducidas:

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 reducido:

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 proveedor gestionan la configuración de las sesiones del proveedor. Las llamadas de voz y Google Meet gestionan los adaptadores de telefonía/reuniones. Las aplicaciones web y nativas gestionan la experiencia de usuario de captura/reproducción del dispositivo.

Cronología de eliminación

Las subrutas públicas restantes del SDK que aparecen a continuación tienen periodos de eliminación respaldados por el registro. Las filas del 30 de julio se eliminaron tras su revisión anticipada autorizada por los mantenedores: se eliminaron las subrutas no utilizadas y los alias de compatibilidad anteriores, y los módulos exclusivos de los plugins incluidos se degradaron a asignaciones de compilación locales privadas.

Todos los plugins del núcleo ya han migrado. Los plugins externos deben migrar antes de la próxima versión principal. Ejecute pnpm plugins:boundary-report para ver qué registros de compatibilidad tienen las fechas más próximas para las superficies que utiliza su plugin.

Supresión temporal de 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 importación 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