Detalles internos del Plugin

Esta es la referencia detallada de arquitectura del sistema de plugins de OpenClaw. Para consultar guías prácticas, se recomienda comenzar con una de las páginas específicas siguientes.

Modelo público de capacidades

Las capacidades constituyen el modelo público de plugins nativos en OpenClaw. Cada plugin nativo de OpenClaw se registra con uno o más tipos de capacidad:

Postura sobre la compatibilidad externa

Actualmente, el modelo de capacidades está integrado en el núcleo y lo utilizan los plugins incluidos y nativos, pero la compatibilidad de los plugins externos aún exige un criterio más estricto que «se exporta, por lo tanto está congelado».

El registro de capacidades es la dirección prevista. Durante la transición, los hooks heredados siguen siendo la vía más segura para evitar incompatibilidades en los plugins externos. No todas las subrutas auxiliares exportadas son equivalentes; se deben preferir los contratos específicos documentados frente a exportaciones auxiliares circunstanciales.

Formas de los plugins

OpenClaw clasifica cada plugin cargado en una forma según su comportamiento real de registro, no solo según los metadatos estáticos:

Se puede usar openclaw plugins inspect <id> para consultar la forma y el desglose de capacidades de un plugin. Para obtener más información, véase la referencia de la CLI.

Señales de compatibilidad

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all y openclaw plugins doctor muestran estos avisos de compatibilidad:

Actualmente, ninguna de las señales informativas o de advertencia impide que el plugin funcione. Estas señales también aparecen en openclaw status --all y openclaw plugins doctor.

Descripción general de la arquitectura

El sistema de plugins de OpenClaw tiene cuatro capas:

En el caso específico de la CLI de plugins, la detección de comandos raíz se divide en dos fases:

• los metadatos del momento del análisis proceden de registerCli(..., { descriptors: [...] })
• el módulo real de la CLI del plugin puede permanecer en carga diferida y registrarse en la primera invocación

Esto mantiene el código de la CLI propiedad del plugin dentro del propio plugin, a la vez que permite que OpenClaw reserve los nombres de los comandos raíz antes del análisis.

El límite de diseño importante es el siguiente:

• la validación del manifiesto y la configuración debe funcionar a partir de los metadatos del manifiesto y del esquema sin ejecutar el código del plugin
• la detección de capacidades nativas puede cargar código de entrada de plugins de confianza para crear una instantánea del registro que no active nada
• el comportamiento nativo en tiempo de ejecución procede de la ruta register(api) del módulo del plugin con api.registrationMode === "full"

Esta separación permite que OpenClaw valide la configuración, explique la ausencia o deshabilitación de plugins y genere indicaciones para la interfaz de usuario y el esquema antes de que se active el entorno de ejecución completo.

Instantánea de metadatos de plugins y tabla de búsqueda

Al iniciarse, el Gateway crea una instancia de PluginMetadataSnapshot para la instantánea de configuración actual. La instantánea solo contiene metadatos: almacena el índice de plugins instalados, el registro de manifiestos, los diagnósticos de manifiestos, los mapas de propietarios, un normalizador de identificadores de plugins y los registros de manifiestos. No contiene módulos de plugins cargados, SDK de proveedores, contenido de paquetes ni exportaciones del entorno de ejecución.

La validación de la configuración compatible con plugins, la habilitación automática al inicio y el arranque de plugins del Gateway utilizan esta instantánea en lugar de reconstruir por separado los metadatos de manifiestos e índices. PluginLookUpTable se deriva de la misma instantánea y añade el plan de plugins de inicio correspondiente a la configuración actual del entorno de ejecución.

Tras el inicio, el Gateway conserva la instantánea actual de metadatos como un producto reemplazable del entorno de ejecución. La detección repetida de proveedores en tiempo de ejecución puede reutilizar esa instantánea, en lugar de reconstruir el índice de instalaciones y el registro de manifiestos en cada pasada por el catálogo de proveedores. La instantánea se elimina o se sustituye cuando se apaga el Gateway, cambia la configuración o el inventario de plugins, o se escribe en el índice de instalaciones; cuando no existe una instantánea actual compatible, las llamadas recurren a la ruta en frío de manifiestos e índices. Las comprobaciones de compatibilidad deben incluir las raíces de detección de plugins, como plugins.load.paths, y el espacio de trabajo predeterminado del agente, porque los plugins del espacio de trabajo forman parte del alcance de los metadatos.

La instantánea y la tabla de búsqueda mantienen en la ruta rápida las decisiones repetidas del inicio:

• propiedad de los canales
• inicio diferido de los canales
• identificadores de los plugins de inicio
• propiedad de los proveedores y los backends de la CLI
• propiedad del proveedor de configuración, los alias de comandos, el proveedor del catálogo de modelos y los contratos de manifiesto
• validación del esquema de configuración de plugins y del esquema de configuración de canales
• decisiones de habilitación automática al inicio

El límite de seguridad es la sustitución de la instantánea, no su mutación. La instantánea debe reconstruirse cuando cambien la configuración, el inventario de plugins, los registros de instalación o la política persistente del índice. No debe tratarse como un registro global mutable de uso general ni se deben conservar instantáneas históricas sin límite. La carga de plugins en tiempo de ejecución permanece separada de las instantáneas de metadatos para evitar que un estado obsoleto del entorno de ejecución quede oculto tras una caché de metadatos.

La regla de caché se documenta en Aspectos internos de la arquitectura de plugins: los metadatos de manifiestos y detección se mantienen actualizados, salvo que una llamada conserve una instantánea, una tabla de búsqueda o un registro de manifiestos explícitos para el flujo actual. Las cachés ocultas de metadatos y los TTL basados en el tiempo de reloj no forman parte de la carga de plugins. Solo pueden conservarse las cachés del cargador del entorno de ejecución, de módulos y de artefactos de dependencias después de que se hayan cargado realmente el código o los artefactos instalados.

Algunos llamadores de rutas frías todavía reconstruyen los registros de manifiestos directamente a partir del índice persistente de plugins instalados, en lugar de recibir un Gateway PluginLookUpTable. Esa ruta ahora reconstruye el registro bajo demanda; cuando un llamador ya disponga de ella, es preferible pasar la tabla de consulta actual o un registro de manifiestos explícito a través de los flujos de ejecución.

Planificación de la activación

La planificación de la activación forma parte del plano de control. Los llamadores pueden consultar qué plugins son pertinentes para un comando, proveedor, canal, ruta, arnés de agente o capacidad concretos antes de cargar registros de ejecución más amplios.

El planificador mantiene la compatibilidad con el comportamiento actual de los manifiestos:

• activation.* los campos son indicaciones explícitas para el planificador
• providers, channels, commandAliases, setup.providers, contracts.tools y los hooks siguen siendo el mecanismo alternativo de propiedad del manifiesto
• la API del planificador que solo devuelve identificadores sigue disponible para los llamadores existentes
• la API del plan informa de etiquetas de motivo para que los diagnósticos puedan distinguir las indicaciones explícitas del mecanismo alternativo de propiedad

Plugins de canal y la herramienta de mensajes compartida

Los plugins de canal no necesitan registrar una herramienta independiente para enviar, editar o reaccionar en las acciones normales de chat. OpenClaw mantiene una única herramienta compartida message en el núcleo, y los plugins de canal se encargan de la detección y ejecución específicas del canal que hay detrás de ella.

El límite actual es el siguiente:

• el núcleo se encarga del host de la herramienta compartida message, la conexión con los prompts, el registro de sesiones e hilos y el despacho de la ejecución
• los plugins de canal se encargan de la detección de acciones dentro del ámbito, la detección de capacidades y cualquier fragmento de esquema específico del canal
• los plugins de canal se encargan de la gramática de conversación de sesión específica del proveedor, como la forma en que los identificadores de conversación codifican los identificadores de hilo o se heredan de las conversaciones principales
• los plugins de canal ejecutan la acción final mediante su adaptador de acciones

Para los plugins de canal, la superficie del SDK es ChannelMessageActionAdapter.describeMessageTool(...). Esa llamada de detección unificada permite que un plugin devuelva conjuntamente sus acciones visibles, capacidades y contribuciones al esquema, de modo que esas partes no pierdan coherencia entre sí.

Los nombres de las acciones de mensajes utilizan deliberadamente un vocabulario cerrado y controlado por el núcleo para que todos los transportes puedan representar todas las acciones. Los plugins añaden nombres de acciones mediante un pull request al núcleo; el registro durante la ejecución no se admite de forma intencionada.

Cuando un parámetro específico de un canal de la herramienta de mensajes contiene una fuente multimedia, como una ruta local o una URL multimedia remota, el plugin también debe devolver mediaSourceParams desde describeMessageTool(...). El núcleo utiliza esa lista explícita para aplicar la normalización de rutas del entorno aislado y las indicaciones de acceso a contenido multimedia saliente sin codificar de forma rígida los nombres de parámetros que pertenecen al plugin. En este punto, es preferible usar mapas limitados por acción y no una única lista plana para todo el canal, de modo que un parámetro multimedia exclusivo del perfil no se normalice en acciones no relacionadas como send.

El núcleo pasa el ámbito de ejecución a ese paso de detección. Los campos importantes incluyen:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• entrada de confianza requesterSenderId

Esto es importante para los plugins sensibles al contexto. Un canal puede ocultar o mostrar acciones de mensajes en función de la cuenta activa, la sala, el hilo o el mensaje actuales, o la identidad de confianza del solicitante, sin codificar de forma rígida bifurcaciones específicas del canal en la herramienta principal message.

Por este motivo, los cambios de enrutamiento del ejecutor integrado siguen siendo trabajo del plugin: el ejecutor es responsable de reenviar la identidad actual del chat y de la sesión al límite de detección del plugin para que la herramienta compartida message exponga la superficie correcta, propiedad del canal, durante el turno actual.

Para los auxiliares de ejecución que pertenecen al canal, los plugins de canal deben mantener el entorno de ejecución dentro de sus propios módulos de plugin. El núcleo ya no se encarga de los entornos de ejecución de acciones de mensajes de Discord, Slack, Telegram o WhatsApp en src/agents/tools. No se publican subrutas independientes plugin-sdk/*-action-runtime, y esos plugins deben importar directamente su propio código de ejecución local desde los módulos que les pertenecen.

El mismo límite se aplica en general a los puntos de integración del SDK que llevan el nombre de un proveedor: el núcleo no debe importar módulos de conveniencia específicos de canales para Discord, Signal, Slack, WhatsApp ni plugins similares. Si el núcleo necesita un comportamiento, debe consumir el módulo api.ts / runtime-api.ts del propio plugin incluido o convertir la necesidad en una capacidad genérica y limitada del SDK compartido.

Los plugins incluidos siguen la misma regla. El runtime-api.ts de un plugin incluido no debe volver a exportar su propia fachada de marca openclaw/plugin-sdk/<plugin-id>. Esas fachadas de marca siguen siendo capas de compatibilidad para plugins externos y consumidores antiguos, pero los plugins incluidos deben usar exportaciones locales junto con subrutas genéricas y limitadas del SDK, como openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store o openclaw/plugin-sdk/webhook-ingress. El código nuevo no debe añadir fachadas del SDK específicas de un identificador de plugin, salvo que lo exija el límite de compatibilidad de un ecosistema externo existente.

En el caso específico de las encuestas, existen dos rutas de ejecución:

• outbound.sendPoll es la base compartida para los canales que se ajustan al modelo común de encuestas
• actions.handleAction("poll") es la ruta preferida para la semántica de encuestas específica de un canal o para parámetros de encuesta adicionales

El núcleo ahora pospone el análisis compartido de encuestas hasta que el despacho de encuestas del plugin rechaza la acción, de modo que los controladores de encuestas pertenecientes al plugin puedan aceptar campos de encuesta específicos del canal sin que el analizador genérico de encuestas los bloquee primero.

Consulte Detalles internos de la arquitectura de plugins para conocer la secuencia de inicio completa.

Modelo de propiedad de capacidades

OpenClaw trata un plugin nativo como el límite de propiedad de una empresa o una funcionalidad, no como una colección indiscriminada de integraciones no relacionadas.

Esto significa lo siguiente:

• por lo general, un plugin de empresa debe encargarse de todas las superficies de esa empresa orientadas a OpenClaw
• por lo general, un plugin de funcionalidad debe encargarse de toda la superficie de la funcionalidad que introduce
• los canales deben consumir capacidades compartidas del núcleo en lugar de volver a implementar de forma improvisada el comportamiento de los proveedores

El estado final previsto es el siguiente:

• la superficie de un proveedor orientada a OpenClaw reside en un solo plugin, aunque abarque modelos de texto, voz, imágenes y vídeo
• otros proveedores pueden hacer lo mismo con su propia superficie
• a los canales no les importa qué plugin de proveedor se encarga del proveedor; consumen el contrato de capacidad compartido que expone el núcleo

Esta es la distinción fundamental:

• plugin = límite de propiedad
• capacidad = contrato del núcleo que varios plugins pueden implementar o consumir

Por tanto, si OpenClaw añade un dominio nuevo, como el vídeo, la primera pregunta no es «¿qué proveedor debe codificar de forma rígida el manejo del vídeo?». La primera pregunta es «¿cuál es el contrato de capacidad de vídeo del núcleo?». Una vez que exista ese contrato, los plugins de proveedores pueden registrarse en él y los plugins de canales o funcionalidades pueden consumirlo.

Si la capacidad todavía no existe, lo adecuado suele ser:

Esto mantiene explícita la propiedad y evita, al mismo tiempo, que el comportamiento del núcleo dependa de un único proveedor o de una ruta de código específica de un plugin creada para un caso aislado.

Capas de capacidades

Utilice este modelo mental para decidir dónde debe residir el código:

Por ejemplo, la conversión de texto a voz sigue esta estructura:

• el núcleo se encarga de la política de conversión de texto a voz en el momento de responder, el orden de los mecanismos alternativos, las preferencias y la entrega al canal
• elevenlabs, google, microsoft y openai se encargan de las implementaciones de síntesis
• voice-call consume el auxiliar de ejecución de conversión de texto a voz para telefonía

Debe preferirse este mismo patrón para capacidades futuras.

Ejemplo de plugin de empresa con múltiples capacidades

Un plugin de empresa debe percibirse como una unidad coherente desde el exterior. Si OpenClaw dispone de contratos compartidos para modelos, voz, transcripción en tiempo real, voz en tiempo real, comprensión multimedia, generación de imágenes, generación de vídeo, obtención de contenido web y búsqueda web, un proveedor puede encargarse de todas sus superficies en un único lugar:

  export default definePluginEntry({  id: "exampleai",  name: "ExampleAI",  description: "Modelos y capacidades multimedia de ExampleAI.",  register(api) {    api.registerProvider({      id: "exampleai",      // hooks de autenticación, catálogo de modelos y entorno de ejecución    });     api.registerSpeechProvider({      id: "exampleai",      // configuración de voz del proveedor — implementar directamente la interfaz SpeechProviderPlugin    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      describeImage: (req) => exampleAiMedia.describeImage(req),      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),      describeVideo: (req) => exampleAiMedia.describeVideo(req),    });     api.registerWebSearchProvider({      id: "exampleai-search",      createTool() {        // Devolver la herramienta de búsqueda web que pertenece al proveedor.      },    });  },});

Lo importante no son los nombres exactos de los auxiliares. Lo importante es la estructura:

• un solo plugin se encarga de la superficie del proveedor
• el núcleo sigue encargándose de los contratos de capacidades
• la traducción de solicitudes del proveedor y los auxiliares HTTP permanecen en el plugin del proveedor
• los canales y los plugins de funcionalidades consumen auxiliares api.runtime.*, no código del proveedor
• las pruebas de contrato pueden verificar que el plugin haya registrado las capacidades de las que afirma encargarse

Ejemplo de capacidad: comprensión de vídeo

OpenClaw ya trata la comprensión de imágenes, audio y vídeo como una única capacidad compartida. Allí se aplica el mismo modelo de propiedad:

Esto evita incorporar en Core las suposiciones sobre vídeo de un único proveedor. El plugin es responsable de la superficie del proveedor; Core es responsable del contrato de capacidad y del comportamiento de respaldo.

La generación de vídeo ya utiliza esa misma secuencia: Core es responsable del contrato de capacidad tipado y del asistente de tiempo de ejecución, y los plugins de proveedores registran implementaciones de api.registerVideoGenerationProvider(...) conforme a él.

¿Se necesita una lista de verificación concreta para el despliegue? Consulte el Recetario de capacidades.

Contratos y aplicación

La superficie de la API de plugins está tipada y centralizada de forma intencionada en OpenClawPluginApi. Ese contrato define los puntos de registro compatibles y los asistentes de tiempo de ejecución en los que puede apoyarse un plugin.

Por qué es importante:

• los autores de plugins disponen de un único estándar interno estable
• Core puede rechazar la propiedad duplicada, como cuando dos plugins registran el mismo id de proveedor
• el inicio puede mostrar diagnósticos procesables para registros con formato incorrecto
• las pruebas de contrato pueden hacer cumplir la propiedad de los plugins incluidos y evitar divergencias silenciosas

Hay dos niveles de aplicación:

El efecto práctico es que OpenClaw sabe de antemano qué plugin es responsable de cada superficie. Esto permite que Core y los canales se compongan sin problemas, porque la propiedad se declara, se tipa y se puede probar, en lugar de ser implícita.

Qué debe incluirse en un contrato

En caso de duda, eleve el nivel de abstracción: defina primero la capacidad y, después, permita que los plugins se conecten a ella.

Modelo de ejecución

Los plugins nativos de OpenClaw se ejecutan dentro del proceso junto con el Gateway. No están aislados. Un plugin nativo cargado tiene el mismo límite de confianza a nivel de proceso que el código de Core.

Los paquetes compatibles son más seguros de forma predeterminada porque OpenClaw los trata actualmente como paquetes de metadatos o contenido. En las versiones actuales, esto se refiere principalmente a Skills incluidas.

Utilice listas de permitidos y rutas explícitas de instalación y carga para los plugins no incluidos. Trate los plugins del espacio de trabajo como código para la fase de desarrollo, no como valores predeterminados de producción.

Para los nombres de paquetes incluidos en el espacio de trabajo, mantenga el id del plugin anclado al nombre de npm: @openclaw/<id> de forma predeterminada, o un sufijo tipado aprobado como -provider, -plugin, -speech, -sandbox o -media-understanding cuando el paquete exponga intencionadamente una función de plugin más limitada.

Límite de exportación

OpenClaw exporta capacidades, no facilidades de implementación.

Mantenga público el registro de capacidades. Reduzca las exportaciones de asistentes que no formen parte del contrato:

• subrutas de asistentes específicas de plugins incluidos
• subrutas de infraestructura de tiempo de ejecución no destinadas a ser una API pública
• asistentes de conveniencia específicos de proveedores
• asistentes de configuración e incorporación que son detalles de implementación

Las subrutas reservadas de asistentes para plugins incluidos se han retirado del mapa de exportaciones generado del SDK. Mantenga los asistentes específicos de cada responsable dentro del paquete del plugin correspondiente; promueva únicamente el comportamiento reutilizable del host a contratos genéricos del SDK, como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime y las capacidades inyectadas de la API de plugins.

Detalles internos y referencia

Para consultar el pipeline de carga, el modelo de registro, los hooks de tiempo de ejecución de proveedores, las rutas HTTP del Gateway, los esquemas de herramientas de mensajes, la resolución de destinos de canales, los catálogos de proveedores, los plugins del motor de contexto y la guía para añadir una capacidad nueva, consulte los Detalles internos de la arquitectura de plugins.

Temas relacionados

• Creación de plugins
• Manifiesto de plugins
• Configuración del SDK de plugins