Paquetes de complementos

OpenClaw puede instalar complementos de tres ecosistemas externos: Codex, Claude y Cursor. Estos se denominan paquetes (bundles): paquetes de contenido y metadatos que OpenClaw asigna a características nativas como habilidades, enlaces y herramientas de MCP.

Por qué existen los paquetes

Muchos complementos útiles se publican en formato Codex, Claude o Cursor. En lugar de requerir que los autores los reescriban como complementos nativos de OpenClaw, OpenClaw detecta estos formatos y asigna su contenido admitido al conjunto de características nativas. Esto significa que puede instalar un paquete de comandos de Claude o un paquete de habilidades de Codex y usarlo de inmediato.

Instalar un paquete

Instalar desde un directorio, archivo o mercado

# Local directory
openclaw plugins install ./my-bundle

# Archive
openclaw plugins install ./my-bundle.tgz

# Claude marketplace
openclaw plugins marketplace list

openclaw plugins install

Verificar detección

openclaw plugins list
openclaw plugins inspect

Los paquetes se muestran como `Format: bundle` con un subtipo de `codex`, `claude` o `cursor`.

Reinicia y usa
Ventana de terminal
```
openclaw gateway restart
```
Las características asignadas (habilidades, ganchos, herramientas MCP, valores predeterminados de LSP) están disponibles en la siguiente sesión.

Lo que OpenClaw asigna desde los bundles

Hoy en día, no todas las características de los bundles se ejecutan en OpenClaw. Esto es lo que funciona y lo que detecta pero aún no está conectado.

Compatible ahora

Característica	Cómo se asigna	Aplica a
Contenido de habilidades	Las raíces de habilidades del bundle se cargan como habilidades normales de OpenClaw	Todos los formatos
Comandos	`commands/` y `.cursor/commands/` tratados como raíces de habilidades	Claude, Cursor
Paquetes de enlaces	Diseños `HOOK.md` + `handler.ts` estilo OpenClaw	Codex
Herramientas MCP	Configuración MCP del paquete fusionada con la configuración integrada de Pi; servidores stdio y HTTP compatibles cargados	Todos los formatos
Servidores LSP	Claude `.lsp.json` y `lspServers` declarados en el manifiesto se fusionan en los valores predeterminados LSP de Pi integrados	Claude
Configuración	Claude `settings.json` importado como valores predeterminados de Pi integrados	Claude

Contenido de habilidades

las raíces de habilidades del paquete se cargan como raíces de habilidades normales de OpenClaw
las raíces commands de Claude se tratan como raíces de habilidades adicionales
las raíces .cursor/commands de Cursor se tratan como raíces de habilidades adicionales

Esto significa que los archivos de comandos de markdown de Claude funcionan a través del cargador de habilidades normal de OpenClaw. Los comandos de markdown de Cursor funcionan a través de la misma ruta.

Paquetes de ganchos

las raíces de ganchos del paquete funcionan solo cuando usan el diseño normal de paquete de ganchos de OpenClaw. Hoy en día, este es principalmente el caso compatible con Codex:
- HOOK.md
- handler.ts o handler.js

MCP para Pi

los paquetes habilitados pueden contribuir con la configuración del servidor MCP
OpenClaw fusiona la configuración MCP del paquete en la configuración efectiva de Pi integrada como mcpServers
OpenClaw expone las herramientas MCP de paquetes compatibles durante los turnos del agente Pi integrado al iniciar servidores stdio o conectarse a servidores HTTP
los perfiles de herramientas coding y messaging incluyen herramientas MCP de paquetes por defecto; use tools.deny: ["bundle-mcp"] para optar por no participar para un agente o puerta de enlace
la configuración de Pi local al proyecto todavía se aplica después de los valores predeterminados del paquete, por lo que la configuración del espacio de trabajo puede anular las entradas MCP del paquete cuando sea necesario
los catálogos de herramientas MCP de paquetes se ordenan de forma determinista antes del registro, por lo que los cambios en el orden listTools() aguas arriba no alteran los bloques de herramientas de caché de aviso

Transportes

Los servidores MCP pueden usar transporte stdio o HTTP:

Stdio inicia un proceso secundario:

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

HTTP se conecta a un servidor MCP en ejecución a través de sse de forma predeterminada, o streamable-http cuando se solicita:

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

transport puede configurarse como "streamable-http" o "sse"; cuando se omite, OpenClaw usa sse
type: "http" es una forma descendente nativa de CLI; use transport: "streamable-http" en la configuración de OpenClaw. openclaw mcp set y openclaw doctor --fix normalizan el alias común.
solo se permiten los esquemas de URL http: y https:
los valores headers admiten la interpolación ${ENV_VAR}
se rechaza una entrada de servidor con ambos command y url
las credenciales de URL (información de usuario y parámetros de consulta) se redactan de las descripciones de herramientas y los registros
connectionTimeoutMs anula el tiempo de espera de conexión predeterminado de 30 segundos tanto para transportes stdio como HTTP

Nomenclatura de herramientas

OpenClaw registra las herramientas MCP de los paquetes con nombres seguros para el proveedor en el formato serverName__toolName. Por ejemplo, un servidor con clave "vigil-harbor" que exponga una herramienta memory_search se registra como vigil-harbor__memory_search.

los caracteres fuera de A-Za-z0-9_- se reemplazan por -
los fragmentos que comenzarían con una letra que no es una letra reciben un prefijo de letra, por lo que las claves de servidor numéricas como 12306 se convierten en prefijos de herramientas seguros para el proveedor
los prefijos de servidor tienen un límite de 30 caracteres
los nombres completos de las herramientas tienen un límite de 64 caracteres
los nombres de servidor vacíos vuelven a mcp
los nombres saneados que colisionan se desambiguan con sufijos numéricos
el orden final de las herramientas expuestas es determinista por nombre seguro para mantener los turnos de Pi repetidos estables en caché
el filtrado de perfiles trata todas las herramientas de un servidor MCP de un paquete como propiedad del complemento bundle-mcp, por lo que las listas de permitidos y denegados del perfil pueden incluir nombres de herramientas expuestas individuales o la clave del complemento bundle-mcp

Configuración Pi integrada

Claude settings.json se importa como configuración Pi integrada predeterminada cuando el paquete está habilitado
OpenClaw sanea las claves de anulación de shell antes de aplicarlas

Claves saneadas:

shellPath
shellCommandPrefix

LSP Pi integrado

los paquetes Claude habilitados pueden contribuir con la configuración del servidor LSP
OpenClaw carga .lsp.json más cualquier ruta lspServers declarada en el manifiesto
la configuración LSP del paquete se fusiona con los valores predeterminados efectivos del LSP Pi integrado
solo los servidores LSP compatibles con stdio son ejecutables hoy; los transportes no compatibles aún aparecen en openclaw plugins inspect <id>

Detectado pero no ejecutado

Estos se reconocen y muestran en los diagnósticos, pero OpenClaw no los ejecuta:

Claude agents, automatización hooks.json, outputStyles
Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
metadatos en línea/aplicación de Codex más allá del informe de capacidades

Formatos de paquete

Paquetes de Codex

Marcadores: .codex-plugin/plugin.json

Contenido opcional: skills/, hooks/, .mcp.json, .app.json

Los paquetes de Codex se adaptan mejor a OpenClaw cuando utilizan raíces de habilidades y directorios de paquetes de enganches (hook packs) al estilo de OpenClaw (HOOK.md + handler.ts).

Paquetes de Claude

Dos modos de detección:

Basado en manifiesto: .claude-plugin/plugin.json
Sin manifiesto: diseño predeterminado de Claude (skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json)

Comportamiento específico de Claude:

commands/ se trata como contenido de habilidad
settings.json se importa a la configuración de Pi integrada (las claves de anulación de shell se depuran)
.mcp.json expone las herramientas stdio admitidas a Pi integrada
.lsp.json más las rutas lspServers declaradas en el manifiesto se cargan en los valores predeterminados de LSP de Pi integrada
hooks/hooks.json se detecta pero no se ejecuta
Las rutas de componentes personalizados en el manifiesto son aditivas (amplían los valores predeterminados, no los reemplazan)

Paquetes de Cursor

Marcadores: .cursor-plugin/plugin.json

Contenido opcional: skills/, .cursor/commands/, .cursor/agents/, .cursor/rules/, .cursor/hooks.json, .mcp.json

.cursor/commands/ se trata como contenido de habilidad
.cursor/rules/, .cursor/agents/ y .cursor/hooks.json son solo de detección

Precedencia de detección

OpenClaw comprueba primero el formato de complemento nativo:

openclaw.plugin.json o package.json válido con openclaw.extensions — tratado como plugin nativo
Marcadores de paquete (.codex-plugin/, .claude-plugin/, o diseño predeterminado de Claude/Cursor) — tratado como paquete

Si un directorio contiene ambos, OpenClaw utiliza la ruta nativa. Esto evita que los paquetes de doble formato se instalen parcialmente como paquetes.

Dependencias de tiempo de ejecución y limpieza

Los paquetes compatibles de terceros no reciben reparación de npm install al inicio. Deben instalarse a través de openclaw plugins install e incluir todo lo que necesitan en el directorio del plugin instalado.
Los plugins empaquetados propiedad de OpenClaw se envían de forma ligera en el núcleo o se pueden descargar a través del instalador de plugins. El inicio de Gateway nunca ejecuta un gestor de paquetes para ellos.
openclaw doctor --fix elimina los directorios de dependencias preparados heredados y puede recuperar plugins descargables que faltan en el índice de plugins local cuando la configuración los referencia.

Seguridad

Los paquetes tienen un límite de confianza más estrecho que los plugins nativos:

OpenClaw no carga módulos de tiempo de ejecución de paquetes arbitrarios dentro del proceso
Las rutas de habilidades y paquetes de hooks deben permanecer dentro de la raíz del plugin (verificadas por límites)
Los archivos de configuración se leen con las mismas comprobaciones de límites
Los servidores MCP stdio compatibles pueden lanzarse como subprocesos

Esto hace que los paquetes sean más seguros por defecto, pero aún debe tratar los paquetes de terceros como contenido de confianza para las características que exponen.

Solución de problemas

Se detecta el paquete pero las capacidades no se ejecutan

Ejecute `openclaw plugins inspect

`. Si una capacidad está listada pero marcada como no conectada, es un límite del producto — no una instalación rota.

Los archivos de comandos de Claude no aparecen

Asegúrese de que el paquete esté habilitado y que los archivos markdown estén dentro de una raíz commands/ o skills/ detectada.

La configuración de Claude no se aplica

Solo se admiten la configuración integrada de Pi de settings.json. OpenClaw no trata la configuración del paquete como parches de configuración sin procesar.

Los hooks de Claude no se ejecutan

hooks/hooks.json es solo de detección. Si necesita hooks ejecutables, use el diseño de paquete de hooks de OpenClaw o envíe un complemento nativo.

Relacionado

Instalar y configurar complementos
Construcción de complementos — crear un complemento nativo
Manifiesto de complementos — esquema de manifiesto nativo