Compatibilidad de plugins

OpenClaw mantiene los contratos de complementos antiguos conectados a través de adaptadores de compatibilidad con nombre antes de eliminarlos. Esto protege los complementos integrados y externos existentes mientras evolucionan los contratos del SDK, manifiesto, configuración y tiempo de ejecución del agente.

Registro de compatibilidad

Los contratos de compatibilidad de plugins se rastrean en el registro central en src/plugins/compat/registry.ts.

Cada registro tiene:

un código de compatibilidad estable
estado: active, deprecated, removal-pending o removed
propietario: SDK, configuración, configuración inicial, canal, proveedor, ejecución de complementos, tiempo de ejecución del agente, o núcleo
fechas de introducción y obsolescencia cuando corresponda
orientación de reemplazo
documentos, diagnósticos y pruebas que cubran el comportamiento antiguo y nuevo

El registro es la fuente para la planificación del mantenedor y las verificaciones futuras del inspector de complementos. Si cambia un comportamiento orientado al complemento, agregue o actualice el registro de compatibilidad en el mismo cambio que agrega el adaptador.

La compatibilidad de reparación y migración de Doctor se rastrea por separado en src/commands/doctor/shared/deprecation-compat.ts. Esos registros cubren viejas estructuras de configuración, diseños de registro de instalación y shims de reparación que pueden necesitar mantenerse disponibles después de que se elimine la ruta de compatibilidad del tiempo de ejecución.

Las barridas de lanzamiento deben verificar ambos registros. No elimine una migración de doctor solo porque el registro de compatibilidad de tiempo de ejecución o configuración correspondiente haya caducado; primero verifique que no haya una ruta de actualización compatible que aún necesite la reparación. Además vuelva a validar cada anotación de reemplazo durante la planificación del lanzamiento porque la propiedad del complemento y la huella de configuración pueden cambiar a medida que los proveedores y canales salen del núcleo.

Paquete del inspector de complementos

El inspector de complementos debe residir fuera del repositorio central de OpenClaw como un paquete/repositorio separado respaldado por los contratos de compatibilidad y manifiesto con versiones.

La CLI del primer día debe ser:

openclaw-plugin-inspector ./my-plugin

Debe emitir:

validación de manifiesto/esquema
la versión de compatibilidad del contrato que se está verificando
verificaciones de metadatos de instalación/fuente
verificaciones de importación de ruta en frío
advertencias de obsolescencia y compatibilidad

Use --json para una salida estable legible por máquina en anotaciones de CI. El núcleo de OpenClaw debería exponer contratos y dispositivos que el inspector pueda consumir, pero no debería publicar el binario del inspector desde el paquete principal openclaw.

Carril de aceptación del mantenedor

Use Crabbox-backed Blacksmith Testbox para el carril de aceptación de paquetes instalables al validar el inspector externo contra los paquetes de complementos de OpenClaw. Ejecute el código desde una copia limpia de OpenClaw después de que se haya construido el paquete:

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/[email protected] -- ./extensions/telegram --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"

Mantenga este carril opcional para los mantenedores porque instala un paquete npm externo y puede inspeccionar paquetes de plugins clonados fuera del repositorio. Los guardias del repositorio local cubren el mapa de exportación del SDK, los metadatos del registro de compatibilidad, la reducción de la importación del SDK en desuso y los límites de importación de extensiones agrupadas; la prueba del inspector Testbox cubre el paquete tal como lo consumen los autores de plugins externos.

Política de desuso

OpenClaw no debe eliminar un contrato de plugin documentado en la misma versión que introduce su reemplazo.

La secuencia de migración es:

Añadir el nuevo contrato.
Mantener el comportamiento antiguo conectado a través de un adaptador de compatibilidad con nombre.
Emitir diagnósticos o advertencias cuando los autores de los plugins puedan actuar.
Documentar el reemplazo y el cronograma.
Probar tanto las rutas antiguas como las nuevas.
Esperar durante la ventana de migración anunciada.
Eliminar solo con la aprobación explícita de la versión de interrupción (breaking release).

Los registros obsoletos deben incluir una fecha de inicio de la advertencia, un reemplazo, un enlace a la documentación y una fecha de eliminación final no más de tres meses después de que comience la advertencia. No añada una ruta de compatibilidad obsoleta con una ventana de eliminación abierta a menos que los mantenedores decidan explícitamente que es una compatibilidad permanente y la marquen active en su lugar.

Áreas de compatibilidad actuales

Los registros de compatibilidad actuales incluyen:

importaciones del SDK amplias heredadas como openclaw/plugin-sdk/compat
formas de complemento heredadas solo de gancho y before_agent_start
nombres de gancho de limpieza legacy api.on("deactivate", ...) mientras los complementos migran a gateway_stop
puntos de entrada de complementos legacy activate(api) mientras los complementos migran a register(api)
alias de SDK heredados como openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, openclaw/plugin-sdk/command-auth constructores de estado, openclaw/plugin-sdk/test-utils (reemplazados por subrutas de prueba enfocadas openclaw/plugin-sdk/*), y los ClawdbotConfig / OpenClawSchemaType type aliases
lista de permitidos y comportamiento de habilitación de complementos incluidos
metadatos de manifiesto de variables de entorno de proveedor/canal heredados
ganchos y alias de tipo de complementos de proveedor heredados mientras los proveedores pasan a ganchos explícitos de catálogo, autenticación, pensamiento, repetición y transporte
alias de tiempo de ejecución heredados como api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt, y api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...) en desuso
registro dividido de complementos de memoria heredados mientras los complementos de memoria pasan a registerMemoryCapability
registro heredado de proveedores de incrustación específicos de la memoria mientras los proveedores de incrustación pasan a api.registerEmbeddingProvider(...) y contracts.embeddingProviders
asistentes heredados del SDK de canales para esquemas de mensajes nativos, filtrado de menciones, formato de sobre entrante y anidamiento de capacidades de aprobación
alias heredados de clave de ruta de canal y asistentes de destino comparable mientras los complementos pasan a openclaw/plugin-sdk/channel-route
sugerencias de activación que están siendo reemplazadas por la propiedad de las contribuciones del manifiesto
reserva de ejecución de setup-api mientras los descriptores de configuración pasan a metadatos en frío setup.requiresRuntime: false
ganchos discovery del proveedor mientras los ganchos del catálogo de proveedores pasan a catalog.run(...)
metadatos showConfigured / showInSetup del canal mientras los paquetes de canal pasan a openclaw.channel.exposure
claves de configuración heredadas de políticas de tiempo de ejecución mientras el doctor migra los operadores a agentRuntime
reserva de metadatos de configuración de canal agrupados generados mientras aterrizan los metadatos channelConfigs primero en el registro
indicadores de entorno de desactivación del registro de complementos y migración de instalación persistidos mientras los flujos de reparación migran los operadores a openclaw plugins registry --refresh y openclaw doctor --fix
rutas de configuración heredadas de búsqueda web, recuperación web y x_search propiedad de complementos mientras el doctor los migra a plugins.entries.<plugin>.config
configuración creada por plugins.installs heredada y alias de ruta de carga de complementos agrupados mientras los metadatos de instalación pasan al libro mayor de complementos administrados por estado

El nuevo código de complementos debe preferir el reemplazo que figura en el registro y en la guía de migración específica. Los complementos existentes pueden seguir utilizando una ruta de compatibilidad hasta que la documentación, los diagnósticos y las notas de la versión anuncien un período de eliminación.

Notas de la versión

Las notas de la versión deben incluir las futuras obsolescencias de complementos con fechas objetivo y enlaces a la documentación de migración. Esa advertencia debe producirse antes de que una ruta de compatibilidad pase a removal-pending o removed.