Plugins

Los Plugins amplían OpenClaw con canales, proveedores de modelos, arneses de agente, herramientas, Skills, voz sintetizada, transcripción en tiempo real, voz, comprensión de medios, generación, obtención web, búsqueda web y otras capacidades de runtime.

Usa esta página cuando quieras instalar un Plugin, reiniciar el Gateway, verificar que el runtime lo cargó y resolver fallos comunes de configuración. Para ejemplos solo de comandos, consulta Gestionar Plugins. Para el inventario generado completo de Plugins incluidos, externos oficiales y solo de código fuente, consulta Inventario de Plugins.

Requisitos

Antes de instalar un Plugin, asegúrate de tener:

• un checkout o una instalación de OpenClaw con la CLI openclaw disponible
• acceso de red a la fuente seleccionada, como ClawHub, npm o un host git
• cualquier credencial específica del Plugin, claves de configuración o herramientas del sistema operativo nombradas por la documentación de configuración de ese Plugin
• permiso para que el Gateway que sirve tus canales se recargue o reinicie

Inicio rápido

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

Configuración

Elegir una fuente de instalación

Las especificaciones de paquetes sin prefijo tienen un comportamiento especial de compatibilidad. Si el nombre sin prefijo coincide con un id de Plugin incluido, OpenClaw usa esa fuente incluida. Si coincide con un id de Plugin externo oficial, OpenClaw usa el catálogo oficial de paquetes. Otras especificaciones ordinarias de paquetes sin prefijo se instalan mediante npm durante el cambio de lanzamiento. Las especificaciones de paquetes @openclaw/* sin procesar que coincidan con Plugins incluidos también se resuelven a la copia incluida antes de recurrir a npm. Usa npm:@openclaw/<plugin>@<version> cuando quieras deliberadamente el paquete npm externo en lugar de la copia incluida propiedad de la imagen. Usa clawhub:, npm:, git: o npm-pack: cuando necesites selección determinista de fuente. Consulta openclaw plugins para el contrato completo del comando.

Para instalaciones npm, las especificaciones de paquete sin fijar y @latest eligen el paquete estable más reciente que anuncia compatibilidad con esta compilación de OpenClaw. Si la versión latest actual de npm declara un openclaw.compat.pluginApi o openclaw.install.minHostVersion más nuevo, OpenClaw analiza versiones estables anteriores del paquete e instala la más reciente que encaje. Las versiones exactas y las etiquetas de canal explícitas como @beta permanecen fijadas al paquete seleccionado y fallan cuando son incompatibles.

Política de instalación del operador

Configura security.installPolicy para ejecutar un comando de política local de confianza antes de que continúe la instalación o actualización de Plugins. La política recibe metadatos más la ruta de origen preparada y puede permitir o bloquear la instalación. Cubre las rutas de instalación/actualización de Plugins respaldadas por CLI y Gateway. Los hooks before_install de Plugin se ejecutan más tarde solo en procesos de OpenClaw donde se cargan los hooks de Plugin, así que usa security.installPolicy para decisiones de instalación propiedad del operador. La bandera obsoleta --dangerously-force-unsafe-install se acepta por compatibilidad, pero no omite la política de instalación ni la lista de denegación integrada de dependencias de Plugins de OpenClaw.

Consulta Configuración de Skills para el esquema exec compartido de security.installPolicy usado tanto por Skills como por Plugins.

Configurar la política de Plugins

La forma común de configuración de Plugins es:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

Reglas clave de política:

• plugins.enabled: false deshabilita todos los Plugins y omite el trabajo de descubrimiento/carga de Plugins. Las referencias obsoletas a Plugins quedan inertes mientras esto está activo; vuelve a habilitar Plugins antes de ejecutar la limpieza de doctor cuando quieras eliminar ids obsoletos.
• plugins.deny prevalece sobre allow y sobre la habilitación por Plugin.
• plugins.allow es una lista de permitidos exclusiva. Las herramientas propiedad de Plugins fuera de la lista de permitidos permanecen no disponibles, incluso cuando tools.allow incluye "*".
• plugins.entries.<id>.enabled: false deshabilita un Plugin y conserva su configuración.
• plugins.load.paths añade archivos o directorios locales explícitos de Plugin. Las rutas locales de plugins install gestionadas deben ser directorios o archivos comprimidos de Plugin; usa plugins.load.paths para archivos de Plugin independientes.
• Los Plugins originados en workspace están deshabilitados de forma predeterminada; habilítalos explícitamente o añádelos a la lista de permitidos antes de usar código del workspace local.
• Los Plugins incluidos siguen sus metadatos integrados de activado/desactivado predeterminado a menos que la configuración los anule explícitamente.
• plugins.slots.<slot> elige un Plugin para categorías exclusivas como motores de memoria y contexto. La selección de slot fuerza la habilitación del Plugin seleccionado para ese slot al contar como activación explícita; puede cargarse incluso cuando de otro modo sería opt-in. plugins.deny y plugins.entries.<id>.enabled: false todavía lo bloquean.
• Los Plugins incluidos opt-in pueden autoactivarse cuando la configuración nombra una de sus superficies propias, como una referencia de proveedor/modelo, configuración de canal, backend de CLI o runtime de arnés de agente.
• El enrutamiento Codex de la familia OpenAI mantiene separados los límites de proveedor y Plugin de runtime: las referencias de modelos Codex heredadas son configuración heredada reparada por doctor, mientras que el Plugin incluido codex posee el runtime de servidor de aplicación Codex para referencias de agente canónicas openai/*, agentRuntime.id: "codex" explícito y referencias heredadas codex/*.

Cuando plugins.allow no está definido y Plugins no incluidos se descubren automáticamente desde el workspace o raíces globales de Plugins, los logs de inicio muestran plugins.allow is empty; discovered non-bundled plugins may auto-load: .... La advertencia incluye ids de Plugins descubiertos y, para listas cortas, un fragmento mínimo de plugins.allow. Ejecuta openclaw plugins list --enabled --verbose o openclaw plugins inspect <id> con el id de Plugin listado antes de copiar Plugins de confianza a openclaw.json. La misma guía de fijación de confianza se aplica cuando los diagnósticos dicen que un Plugin se cargó without install/load-path provenance: inspecciona ese id de Plugin y luego fija el id de confianza en plugins.allow o reinstálalo desde una fuente de confianza para que OpenClaw registre la procedencia de la instalación.

Ejecuta openclaw doctor o openclaw doctor --fix cuando la validación de configuración informe ids de Plugins obsoletos, desajustes de lista de permitidos/herramientas o rutas heredadas de Plugins incluidos.

Entender los formatos de Plugins

OpenClaw reconoce dos formatos de Plugin:

Ambos formatos aparecen en openclaw plugins list, openclaw plugins inspect, openclaw plugins enable y openclaw plugins disable. Consulta Paquetes de Plugins para el límite de compatibilidad de paquetes y Crear Plugins para la autoría de Plugins nativos.

Hooks de Plugin

Los Plugins pueden registrar hooks en runtime, pero hay dos API diferentes con trabajos distintos.

• Usa hooks tipados mediante api.on(...) para hooks del ciclo de vida de runtime. Esta es la superficie preferida para middleware, política, reescritura de mensajes, conformación de prompts y control de herramientas.
• Usa api.registerHook(...) solo cuando quieras participar en el sistema interno de hooks descrito en Hooks. Esto es principalmente para efectos secundarios generales de comandos/ciclo de vida y compatibilidad con la automatización existente de estilo HOOK.

Regla rápida:

• Si el manejador necesita prioridad, semántica de combinación o comportamiento de bloquear/cancelar, usa hooks tipados de Plugin.
• Si el manejador solo reacciona a command:new, command:reset, message:sent o eventos generales similares, api.registerHook(...) está bien.

Los hooks internos gestionados por Plugins aparecen en openclaw hooks list con plugin:<id>. No puedes habilitarlos ni deshabilitarlos mediante openclaw hooks; habilita o deshabilita el Plugin en su lugar.

Verificar el Gateway activo

openclaw plugins list y openclaw plugins inspect sin opciones leen la configuración en frío, el manifiesto y el estado del registro. No demuestran que un Gateway que ya está en ejecución haya importado el mismo código del plugin.

Cuando un plugin aparece como instalado, pero el tráfico de chat en vivo no lo usa:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Los Gateway gestionados se reinician automáticamente después de cambios de instalación, actualización y desinstalación de plugins que alteran el código fuente del plugin. En instalaciones en VPS o contenedores, asegúrate de que cualquier reinicio manual apunte al proceso hijo real de openclaw gateway run que atiende tus canales, no solo a un contenedor o supervisor.

Solución de problemas

Cuando la configuración obsoleta de plugins todavía nombra un plugin de canal que ya no se puede descubrir, el inicio de Gateway omite ese canal respaldado por plugin en lugar de bloquear todos los demás canales. Ejecuta openclaw doctor --fix para eliminar entradas obsoletas de plugins y canales. Las claves de canal desconocidas sin evidencia de plugin obsoleto siguen fallando la validación para que los errores tipográficos permanezcan visibles.

Para el reemplazo intencional de canales, el plugin preferido debe declarar channelConfigs.<channel-id>.preferOver con el id del plugin heredado o de menor prioridad. Si ambos plugins están habilitados explícitamente, OpenClaw conserva esa solicitud e informa diagnósticos de canal o herramienta duplicados en lugar de elegir silenciosamente un propietario.

Si un paquete instalado informa que requires compiled runtime output for TypeScript entry ..., el paquete se publicó sin los archivos JavaScript que OpenClaw necesita en runtime. Actualiza o reinstala después de que el editor publique JavaScript compilado, o desactiva/desinstala el plugin hasta entonces.

Propiedad de ruta de plugin bloqueada

Si los diagnósticos de plugins dicen blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) y la validación de configuración continúa con plugin present but blocked, OpenClaw encontró archivos de plugin propiedad de un usuario Unix distinto al proceso que los está cargando. Mantén la configuración del plugin en su lugar; corrige la propiedad del sistema de archivos o ejecuta OpenClaw como el mismo usuario que posee el directorio de estado.

Para instalaciones con Docker, la imagen oficial se ejecuta como node (uid 1000), por lo que los directorios de configuración y espacio de trabajo de OpenClaw montados desde el host normalmente deben ser propiedad del uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Si ejecutas OpenClaw intencionalmente como root, repara la raíz de plugins gestionados para que sea propiedad de root:

sudo chown -R root:root /path/to/openclaw-config/npm

Después de corregir la propiedad, vuelve a ejecutar openclaw doctor --fix o openclaw plugins registry --refresh para que el registro persistido de plugins coincida con los archivos reparados.

Configuración lenta de herramientas de plugins

Si los turnos del agente parecen quedarse detenidos mientras preparan herramientas, habilita el registro de trazas y comprueba las líneas de tiempos de fábricas de herramientas de plugins:

openclaw config set logging.level traceopenclaw logs --follow

Busca:

[trace:plugin-tools] factory timings ...

El resumen enumera el tiempo total de fábrica y las fábricas de herramientas de plugins más lentas, incluido el id del plugin, los nombres declarados de herramientas, la forma del resultado y si la herramienta es opcional. Las líneas lentas se elevan a advertencias cuando una sola fábrica tarda al menos 1s o la preparación total de fábricas de herramientas de plugins tarda al menos 5s.

OpenClaw almacena en caché los resultados exitosos de fábricas de herramientas de plugins para resoluciones repetidas con el mismo contexto efectivo de solicitud. La clave de caché incluye la configuración efectiva de runtime, el espacio de trabajo, los id de agente/sesión, la política de sandbox, la configuración del navegador, el contexto de entrega, la identidad del solicitante y el estado de propiedad, por lo que las fábricas que dependen de esos campos de confianza se vuelven a ejecutar cuando cambia el contexto. Si los tiempos siguen siendo altos, es posible que el plugin esté haciendo trabajo costoso antes de devolver sus definiciones de herramientas.

Si un plugin domina los tiempos, inspecciona sus registros de runtime:

openclaw plugins inspect <plugin-id> --runtime --json

Luego actualiza, reinstala o desactiva ese plugin. Los autores de plugins deben mover la carga costosa de dependencias detrás de la ruta de ejecución de la herramienta en lugar de hacerla dentro de la fábrica de herramientas.

Para raíces de dependencias, validación de metadatos de paquetes, registros de registro, comportamiento de recarga al iniciar y limpieza heredada, consulta Resolución de dependencias de plugins.

Relacionado

• Gestionar plugins - ejemplos de comandos para listar, instalar, actualizar, desinstalar y publicar
• openclaw plugins - referencia completa de la CLI
• Inventario de Plugin - lista generada de plugins incluidos y externos
• Referencia de Plugin - páginas de referencia generadas por plugin
• Plugins de la comunidad - descubrimiento en ClawHub y política de PR de documentación
• Resolución de dependencias de plugins - raíces de instalación, registros de registro y límites de runtime
• Crear plugins - guía de autoría de plugins nativos
• Descripción general del SDK de Plugin - registro en runtime, hooks y campos de API
• Manifiesto de Plugin - metadatos de manifiesto y paquete