Saltar al contenido principal
Los plugins amplían OpenClaw con canales, proveedores de modelos, arneses de agentes, herramientas, Skills, voz, transcripción en tiempo real, voz sintética, comprensión de medios, generación, obtención web, búsqueda web y otras capacidades de runtime. Usa esta página para instalar un plugin, reiniciar el Gateway, verificar que el runtime lo cargó y resolver fallos comunes de configuración. Para ejemplos solo con comandos, consulta Gestionar plugins. Para el inventario generado de plugins incluidos, oficiales externos y solo de código fuente, consulta Inventario de plugins.

​
Requisitos

  • un checkout o una instalación de OpenClaw con la CLI openclaw disponible
  • acceso de red a la fuente seleccionada (ClawHub, npm o un host git)
  • cualquier credencial, clave de configuración o herramienta del SO específica del plugin indicada 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

1

Encontrar el plugin

Busca paquetes de plugins públicos en ClawHub:
openclaw plugins search "calendar"
ClawHub es la superficie principal de descubrimiento para plugins de la comunidad. Durante el cambio de lanzamiento, las especificaciones ordinarias de paquetes sin prefijo aún se instalan desde npm salvo que coincidan con un id de plugin oficial. Las especificaciones @openclaw/* sin procesar que coincidan con un plugin incluido se resuelven a esa copia incluida. Usa un prefijo de fuente explícito cuando necesites específicamente una fuente.
2

Instalar el plugin

# 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-plugin
openclaw plugins install --link ./my-plugin
Trata las instalaciones de plugins como ejecutar código. Prefiere versiones fijadas para instalaciones de producción reproducibles.
3

Configurar y habilitarlo

Configura los ajustes específicos del plugin en plugins.entries.<id>.config. Habilita el plugin si aún no está habilitado:
openclaw plugins enable <plugin-id>
Si plugins.allow está definido, el id del plugin instalado debe estar en esa lista antes de que el plugin pueda cargarse. openclaw plugins install añade el id instalado a una lista plugins.allow existente y elimina el mismo id de plugins.deny para que la instalación explícita pueda cargarse tras reiniciar.
4

Permitir que el Gateway se recargue

Instalar, actualizar o desinstalar código de plugin requiere reiniciar el Gateway. Un Gateway gestionado con recarga de configuración habilitada detecta el registro de instalación de plugin cambiado y se reinicia automáticamente. De lo contrario, reinícialo tú:
openclaw gateway restart
La configuración de actualización habilita/deshabilita y el registro en frío. Una inspección del runtime sigue siendo la prueba más clara de superficies de runtime activas.
5

Verificar el registro en runtime

openclaw plugins inspect <plugin-id> --runtime --json
Usa --runtime para probar herramientas registradas, hooks, servicios, métodos de Gateway o comandos de CLI propiedad del plugin. inspect sin opciones es solo una comprobación en frío del manifiesto y el registro.

​
Configuración

​
Elegir una fuente de instalación

FuenteÚsala cuandoEjemplo
ClawHubQuieres descubrimiento nativo de OpenClaw, escaneos, metadatos de versión e indicaciones de instalaciónopenclaw plugins install clawhub:<package>
npmNecesitas flujos directos del registro npm o dist-tagopenclaw plugins install npm:<package>
gitNecesitas una rama, etiqueta o commit de un repositorioopenclaw plugins install git:github.com/<owner>/<repo>@<ref>
ruta localEstás desarrollando o probando un plugin en la misma máquinaopenclaw plugins install --link ./my-plugin
marketplaceEstás instalando un plugin de marketplace compatible con Claudeopenclaw plugins install <plugin> --marketplace <source>
Las especificaciones de paquetes sin prefijo tienen un comportamiento de compatibilidad especial: un nombre sin prefijo que coincide con un id de plugin incluido usa esa fuente incluida; un nombre sin prefijo que coincide con un id de plugin oficial externo usa el catálogo oficial de paquetes; cualquier otra especificación sin prefijo se instala mediante npm durante el cambio de lanzamiento. Las especificaciones @openclaw/* sin procesar que coincidan con plugins incluidos también se resuelven a la copia incluida antes del fallback de npm. Usa npm:@openclaw/<plugin>@<version> para instalar deliberadamente el paquete npm externo en lugar de la copia incluida. Usa clawhub:, npm:, git: o npm-pack: para una selección determinista de la fuente. Consulta openclaw plugins para el contrato completo del comando. Para instalaciones npm, las especificaciones 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 reciente que lo admitido por esta compilación, OpenClaw escanea versiones estables anteriores 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 una instalación o actualización de plugin. La política recibe metadatos más la ruta de origen preparada y puede permitir o bloquear la instalación. Cubre tanto rutas de instalación/actualización por CLI como respaldadas por Gateway. Los hooks before_install del plugin se ejecutan después, y solo en procesos de OpenClaw donde los hooks de plugin están cargados, 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 hace nada: 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. Las referencias de plugins obsoletas permanecen inertes mientras esto está activo; vuelve a habilitar los plugins antes de ejecutar la limpieza de doctor si quieres eliminar ids obsoletos.
  • plugins.deny prevalece sobre allow y la habilitación por plugin.
  • plugins.allow es una allowlist exclusiva. Las herramientas propiedad del plugin fuera de la allowlist 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 de plugins locales explícitos. Las rutas locales gestionadas por plugins install 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 por defecto; habilítalos o añádelos explícitamente a la allowlist antes de usar código de workspace local.
  • Los plugins incluidos siguen sus metadatos integrados de activado/desactivado por defecto salvo que la configuración los sobrescriba explícitamente.
  • plugins.slots.<slot> (memory o contextEngine) elige un plugin para una categoría exclusiva. La selección de slot cuenta como activación explícita y fuerza la habilitación del plugin seleccionado para ese slot, incluso si de otro modo sería opt-in. plugins.deny y plugins.entries.<id>.enabled: false aún 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 que doctor repara, mientras que el plugin codex incluido posee el runtime del servidor de aplicación Codex para referencias canónicas de agentes openai/*, agentRuntime.id: "codex" explícito y referencias heredadas codex/*.
Cuando plugins.allow no está definido y se descubren automáticamente plugins no incluidos desde el workspace o raíces globales de plugins, los registros de inicio muestran plugins.allow is empty; discovered non-bundled plugins may auto-load: ... con los 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> sobre el id de plugin listado antes de copiar plugins de confianza en openclaw.json. La misma fijación de confianza aplica cuando los diagnósticos dicen que un plugin se cargó without install/load-path provenance: inspecciona ese id de plugin y luego fíjalo en plugins.allow o reinstálalo desde una fuente de confianza para que OpenClaw registre la procedencia de instalación. Ejecuta openclaw doctor o openclaw doctor --fix cuando la validación de configuración informe ids de plugins obsoletos, incompatibilidades de allowlist/herramientas o rutas heredadas de plugins incluidos.

​
Comprender los formatos de plugins

OpenClaw reconoce dos formatos de plugin:
FormatoCómo se cargaÚsalo cuando
Plugin nativo de OpenClawopenclaw.plugin.json más un módulo de runtime cargado en el procesoEstás instalando o creando capacidades de runtime específicas de OpenClaw
Paquete compatibleDiseño de plugin de Codex, Claude o Cursor mapeado al inventario de plugins de OpenClawEstás reutilizando Skills, comandos, hooks o metadatos de paquete compatibles
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 plugins

Los plugins pueden registrar hooks en runtime mediante dos APIs diferentes:
  • hooks tipados api.on(...) para eventos de ciclo de vida del runtime. Esta es la superficie preferida para middleware, política, reescritura de mensajes, conformación de prompts y control de herramientas.
  • api.registerHook(...) para el sistema interno de hooks descrito en Hooks. Esto es principalmente para efectos secundarios generales de comandos/ciclo de vida y compatibilidad con automatización existente de estilo HOOK.
Regla rápida: si el handler necesita prioridad, semántica de combinación o comportamiento de bloqueo/cancelación, usa hooks tipados. Si 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, el manifiesto y el estado del registro en frío. No prueban que un Gateway ya en ejecución haya importado el mismo código de plugin. Cuando un plugin aparece instalado pero el tráfico de chat en vivo no lo usa: 
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart
Los Gateways administrados se reinician automáticamente después de cambios de instalación, actualización y desinstalación de Plugins que alteran la fuente del Plugin. En instalaciones VPS o de contenedor, asegúrate de que cualquier reinicio manual apunte al proceso hijo real openclaw gateway run que sirve tus canales, no solo a un contenedor o supervisor.

​
Solución de problemas

SíntomaComprobaciónCorrección
El Plugin aparece en plugins list pero los hooks de runtime no se ejecutanUsa openclaw plugins inspect <id> --runtime --json y confirma el Gateway activo con gateway status --deep --require-rpcReinicia el Gateway en vivo después de cambios de instalación, actualización, configuración o fuente
Aparecen diagnósticos de propiedad duplicada de canal o herramientaEjecuta openclaw plugins list --enabled --verbose, inspecciona cada Plugin sospechoso con --runtime --json y compara la propiedad de canales/herramientasDeshabilita un propietario, elimina instalaciones obsoletas o usa el manifiesto preferOver para un reemplazo intencional
La configuración indica que falta un PluginConsulta Inventario de Plugins para saber si está incluido, es externo oficial o solo de fuenteInstala el paquete externo, habilita el Plugin incluido o elimina la configuración obsoleta
La configuración no es válida durante la instalaciónLee el mensaje de validación y ejecuta openclaw doctor --fix si apunta a estado obsoleto de PluginsDoctor puede poner en cuarentena la configuración no válida del Plugin deshabilitando la entrada y eliminando la carga útil no válida
La ruta del Plugin está bloqueada por propiedad o permisos sospechososInspecciona el diagnóstico antes del error de configuraciónCorrige la propiedad/permisos del sistema de archivos y luego ejecuta openclaw plugins registry --refresh
OPENCLAW_NIX_MODE=1 bloquea comandos de ciclo de vidaConfirma que la instalación está gestionada por NixCambia la selección de Plugins en la fuente de Nix en lugar de usar comandos mutadores de Plugins
La importación de dependencias falla en runtimeComprueba si el Plugin se instaló mediante npm/git/ClawHub o se cargó desde una ruta localEjecuta openclaw plugins update <id>, reinstala la fuente o instala tú mismo las dependencias locales del Plugin
Cuando la configuración obsoleta de Plugins todavía nombra un Plugin de canal que ya no es detectable, la validación de configuración degrada esa clave de canal a una advertencia en lugar de un fallo duro, para que el inicio del Gateway pueda seguir sirviendo 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 canales/herramientas 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 publicador envíe JavaScript compilado, o deshabilita/desinstala el Plugin hasta entonces.

​
Propiedad de ruta de Plugin bloqueada

Si los diagnósticos dicen blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) y la validación continúa con plugin present but blocked, OpenClaw encontró archivos de Plugin propiedad de un usuario Unix distinto al proceso que los carga. 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 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 de 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 Plugin

Si los turnos del agente parecen detenerse al preparar herramientas, habilita el registro de trazas y comprueba las líneas de tiempos de fábrica de herramientas de Plugin: 
openclaw config set logging.level trace
openclaw logs --follow
Busca: 
[trace:plugin-tools] factory timings ...
El resumen enumera el tiempo total de fábrica y las fábricas de herramientas de Plugin más lentas, incluido el id del Plugin, los nombres de herramientas declarados, la forma del resultado y si la herramienta es opcional. Las líneas lentas se promueven a advertencias cuando una sola fábrica tarda al menos 1s o la preparación total de fábricas de herramientas de Plugin tarda al menos 5s. OpenClaw almacena en caché los resultados correctos de fábricas de herramientas de Plugin para resoluciones repetidas con el mismo contexto de solicitud efectivo. La clave de caché incluye la configuración efectiva de runtime, el espacio de trabajo y el id del agente, 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 el contexto cambia. 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 el tiempo, inspecciona sus registros de runtime: 
openclaw plugins inspect <plugin-id> --runtime --json
Luego actualiza, reinstala o deshabilita 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 registry, comportamiento de recarga de inicio y limpieza heredada, consulta Resolución de dependencias de Plugin.

​
Relacionado