Saltar al contenido principal

​
Paquetes de plugins

OpenClaw puede instalar plugins de tres ecosistemas externos: Codex, Claude y Cursor. Se llaman paquetes: conjuntos de contenido y metadatos que OpenClaw asigna a funciones nativas como Skills, hooks y herramientas MCP.
Los paquetes no son lo mismo que los plugins nativos de OpenClaw. Los plugins nativos se ejecutan dentro del proceso y pueden registrar cualquier capacidad. Los paquetes son conjuntos de contenido con asignación selectiva de funciones y un límite de confianza más estrecho.

​
Por qué existen los paquetes

Muchos plugins útiles se publican en formato Codex, Claude o Cursor. En lugar de exigir a quienes los crean que los reescriban como plugins nativos de OpenClaw, OpenClaw detecta esos formatos y asigna su contenido compatible al conjunto de funciones nativas. Esto significa que puedes instalar un paquete de comandos de Claude o un paquete de Skills de Codex y usarlo inmediatamente.

​
Instalar un paquete

1

Instalar desde un directorio, archivo o marketplace

# Local directory
openclaw plugins install ./my-bundle

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

# Claude marketplace
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
2

Verificar la detección

openclaw plugins list
openclaw plugins inspect <id>
Los paquetes aparecen como Format: bundle con un subtipo de codex, claude o cursor.
3

Reiniciar y usar

openclaw gateway restart
Las funciones asignadas (Skills, hooks, herramientas MCP, valores predeterminados de LSP) estarán disponibles en la siguiente sesión.

​
Qué asigna OpenClaw desde los paquetes

No todas las funciones de los paquetes se ejecutan hoy en OpenClaw. Aquí está lo que funciona y lo que se detecta pero todavía no está conectado.

​
Compatible ahora

FunciónCómo se asignaSe aplica a
Contenido de SkillsLas raíces de Skills del paquete se cargan como Skills normales de OpenClawTodos los formatos
Comandoscommands/ y .cursor/commands/ se tratan como raíces de SkillsClaude, Cursor
Paquetes de hooksDiseños de estilo OpenClaw con HOOK.md + handler.tsCodex
Herramientas MCPLa configuración MCP del paquete se fusiona en la configuración de Pi integrado; se cargan servidores compatibles stdio y HTTPTodos los formatos
Servidores LSP.lsp.json de Claude y lspServers declarados en el manifiesto se fusionan en los valores predeterminados de LSP de Pi integradoClaude
Configuraciónsettings.json de Claude se importa como valores predeterminados de Pi integradoClaude

​
Contenido de Skills

  • las raíces de Skills del paquete se cargan como raíces normales de Skills de OpenClaw
  • las raíces commands de Claude se tratan como raíces adicionales de Skills
  • las raíces .cursor/commands de Cursor se tratan como raíces adicionales de Skills
Esto significa que los archivos markdown de comandos de Claude funcionan mediante el cargador normal de Skills de OpenClaw. Los comandos markdown de Cursor funcionan por la misma ruta.

​
Paquetes de hooks

  • las raíces de hooks del paquete funcionan solo cuando usan el diseño normal de paquete de hooks de OpenClaw. Hoy esto es principalmente el caso compatible con Codex:
    • HOOK.md
    • handler.ts o handler.js

​
MCP para Pi

  • los paquetes habilitados pueden aportar configuración de servidor MCP
  • OpenClaw fusiona la configuración MCP del paquete en la configuración efectiva de Pi integrado como mcpServers
  • OpenClaw expone las herramientas MCP compatibles del paquete durante los turnos del agente Pi integrado lanzando servidores stdio o conectándose a servidores HTTP
  • la configuración local del proyecto para Pi sigue aplicándose después de los valores predeterminados del paquete, por lo que la configuración del espacio de trabajo puede anular entradas MCP del paquete cuando sea necesario
  • los catálogos de herramientas MCP del paquete se ordenan de forma determinista antes del registro, para que los cambios upstream en el orden de listTools() no alteren los bloques de herramientas de la caché de prompts
Transportes
Los servidores MCP pueden usar transporte stdio o HTTP: Stdio lanza un proceso hijo: 
{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}
HTTP se conecta a un servidor MCP en ejecución mediante 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 establecerse en "streamable-http" o "sse"; si se omite, OpenClaw usa sse
  • solo se permiten esquemas de URL http: y https:
  • los valores de headers admiten interpolación ${ENV_VAR}
  • se rechaza una entrada de servidor que tenga tanto command como url
  • las credenciales de URL (userinfo y parámetros de consulta) se redactan de las descripciones de herramientas y los registros
  • connectionTimeoutMs anula el tiempo de espera predeterminado de 30 segundos para conexiones tanto stdio como HTTP
Nombres de herramientas
OpenClaw registra las herramientas MCP del paquete con nombres seguros para el proveedor con el formato serverName__toolName. Por ejemplo, un servidor con la clave "vigil-harbor" que expone una herramienta memory_search se registra como vigil-harbor__memory_search.
  • los caracteres fuera de A-Za-z0-9_- se sustituyen por -
  • los prefijos de servidor tienen un límite de 30 caracteres
  • los nombres completos de herramientas tienen un límite de 64 caracteres
  • los nombres de servidor vacíos recurren a mcp
  • los nombres saneados que colisionan se distinguen con sufijos numéricos
  • el orden final de herramientas expuestas es determinista por nombre seguro para mantener estables en caché los turnos repetidos de Pi

​
Configuración de Pi integrado

  • settings.json de Claude se importa como configuración predeterminada de Pi integrado cuando el paquete está habilitado
  • OpenClaw sanea las claves de anulación de shell antes de aplicarlas
Claves saneadas:
  • shellPath
  • shellCommandPrefix

​
LSP de Pi integrado

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

​
Detectado pero no ejecutado

Estos se reconocen y se muestran en diagnósticos, pero OpenClaw no los ejecuta:
  • agents, automatización hooks.json, outputStyles de Claude
  • .cursor/agents, .cursor/hooks.json, .cursor/rules de Cursor
  • metadatos inline/de app de Codex más allá del informe de capacidades

​
Formatos de paquetes

Marcadores: .codex-plugin/plugin.jsonContenido opcional: skills/, hooks/, .mcp.json, .app.jsonLos paquetes Codex encajan mejor con OpenClaw cuando usan raíces de Skills y directorios de paquete de hooks de estilo OpenClaw (HOOK.md + handler.ts).
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 Skills
  • settings.json se importa en la configuración de Pi integrado (las claves de anulación de shell se sanean)
  • .mcp.json expone herramientas stdio compatibles a Pi integrado
  • .lsp.json más las rutas lspServers declaradas en el manifiesto se cargan en los valores predeterminados de LSP de Pi integrado
  • hooks/hooks.json se detecta pero no se ejecuta
  • las rutas de componentes personalizados del manifiesto son aditivas (amplían los valores predeterminados, no los sustituyen)
Marcadores: .cursor-plugin/plugin.jsonContenido opcional: skills/, .cursor/commands/, .cursor/agents/, .cursor/rules/, .cursor/hooks.json, .mcp.json
  • .cursor/commands/ se trata como contenido de Skills
  • .cursor/rules/, .cursor/agents/ y .cursor/hooks.json son solo de detección

​
Precedencia de detección

OpenClaw comprueba primero el formato de plugin nativo:
  1. openclaw.plugin.json o un package.json válido con openclaw.extensions: se trata como plugin nativo
  2. Marcadores de paquete (.codex-plugin/, .claude-plugin/ o diseño predeterminado de Claude/Cursor): se trata como paquete
Si un directorio contiene ambos, OpenClaw usa la ruta nativa. Esto evita que los paquetes de doble formato se instalen parcialmente como paquetes.

​
Seguridad

Los paquetes tienen un límite de confianza más estrecho que los plugins nativos:
  • OpenClaw no carga módulos arbitrarios de tiempo de ejecución del paquete dentro del proceso
  • Las rutas de Skills y paquetes de hooks deben permanecer dentro de la raíz del plugin (comprobación de límites)
  • Los archivos de configuración se leen con las mismas comprobaciones de límites
  • Se pueden lanzar servidores MCP stdio compatibles como subprocesos
Esto hace que los paquetes sean más seguros de forma predeterminada, pero aun así debes tratar los paquetes de terceros como contenido de confianza para las funciones que sí exponen.

​
Solución de problemas

Ejecuta openclaw plugins inspect <id>. Si una capacidad aparece pero está marcada como no conectada, eso es un límite del producto, no una instalación rota.
Asegúrate de que el paquete esté habilitado y de que los archivos markdown estén dentro de una raíz detectada commands/ o skills/.
Solo se admiten configuraciones de Pi integrado de settings.json. OpenClaw no trata la configuración del paquete como parches de configuración sin procesar.
hooks/hooks.json es solo de detección. Si necesitas hooks ejecutables, usa el diseño de paquete de hooks de OpenClaw o distribuye un plugin nativo.

​
Relacionado