---
read_when:
    - Quieres instalar un paquete compatible con Codex, Claude o Cursor
    - Necesitas entender cómo OpenClaw asigna el contenido del paquete a funciones nativas
    - Estás depurando la detección del paquete o capacidades faltantes
summary: Instalar y usar paquetes de Codex, Claude y Cursor como plugins de OpenClaw
title: Paquetes de plugins
x-i18n:
    generated_at: "2026-04-05T12:49:28Z"
    model: gpt-5.4
    provider: openai
    source_hash: a8b1eb4633bdff75425d8c2e29be352e11a4cdad7f420c0c66ae5ef07bf9bdcc
    source_path: plugins/bundles.md
    workflow: 15
---

# 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.

<Info>
  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.
</Info>

## 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

<Steps>
  <Step title="Instalar desde un directorio, archivo o marketplace">
    ```bash
    # 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>
    ```

  </Step>

  <Step title="Verificar la detección">
    ```bash
    openclaw plugins list
    openclaw plugins inspect <id>
    ```

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

  </Step>

  <Step title="Reiniciar y usar">
    ```bash
    openclaw gateway restart
    ```

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

  </Step>
</Steps>

## 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ón       | Cómo se asigna                                                                               | Se aplica a     |
| ------------- | -------------------------------------------------------------------------------------------- | ----------------|
| Contenido de Skills | Las raíces de Skills del paquete se cargan como Skills normales de OpenClaw           | Todos los formatos |
| Comandos      | `commands/` y `.cursor/commands/` se tratan como raíces de Skills                            | Claude, Cursor |
| Paquetes de hooks | Diseños de estilo OpenClaw con `HOOK.md` + `handler.ts`                                  | Codex          |
| Herramientas MCP | La configuración MCP del paquete se fusiona en la configuración de Pi integrado; se cargan servidores compatibles stdio y HTTP | Todos los formatos |
| Servidores LSP | `.lsp.json` de Claude y `lspServers` declarados en el manifiesto se fusionan en los valores predeterminados de LSP de Pi integrado | Claude |
| Configuración | `settings.json` de Claude se importa como valores predeterminados de Pi integrado           | Claude         |

#### 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:

```json
{
  "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:

```json
{
  "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

<AccordionGroup>
  <Accordion title="Paquetes Codex">
    Marcadores: `.codex-plugin/plugin.json`

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

    Los 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`).

  </Accordion>

  <Accordion title="Paquetes 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 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)

  </Accordion>

  <Accordion title="Paquetes 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 Skills
    - `.cursor/rules/`, `.cursor/agents/` y `.cursor/hooks.json` son solo de detección

  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="El paquete se detecta pero las capacidades no se ejecutan">
    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.
  </Accordion>

  <Accordion title="No aparecen archivos de comandos de Claude">
    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/`.
  </Accordion>

  <Accordion title="La configuración de Claude no se aplica">
    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.
  </Accordion>

  <Accordion title="Los hooks de Claude no se ejecutan">
    `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.
  </Accordion>
</AccordionGroup>

## Relacionado

- [Instalar y configurar plugins](/tools/plugin)
- [Crear plugins](/plugins/building-plugins) — crea un plugin nativo
- [Manifiesto de plugins](/plugins/manifest) — esquema del manifiesto nativo
