---
read_when:
    - Você quer instalar um bundle compatível com Codex, Claude ou Cursor
    - Você precisa entender como o OpenClaw mapeia o conteúdo do bundle para recursos nativos
    - Você está depurando detecção de bundle ou capacidades ausentes
summary: Instalar e usar bundles do Codex, Claude e Cursor como plugins do OpenClaw
title: Bundles de plugin
x-i18n:
    generated_at: "2026-04-23T14:04:30Z"
    model: gpt-5.4
    provider: openai
    source_hash: dd5ac067546429412f8f4fd2c0da22005686c2d4377944ecd078f56054223f9b
    source_path: plugins/bundles.md
    workflow: 15
---

# Bundles de plugin

O OpenClaw pode instalar plugins de três ecossistemas externos: **Codex**, **Claude**
e **Cursor**. Eles são chamados de **bundles** — pacotes de conteúdo e metadados que
o OpenClaw mapeia para recursos nativos, como Skills, hooks e ferramentas MCP.

<Info>
  Bundles **não** são a mesma coisa que plugins nativos do OpenClaw. Plugins nativos são executados
  in-process e podem registrar qualquer capacidade. Bundles são pacotes de conteúdo com
  mapeamento seletivo de recursos e um limite de confiança mais restrito.
</Info>

## Por que bundles existem

Muitos plugins úteis são publicados no formato Codex, Claude ou Cursor. Em vez
de exigir que os autores os reescrevam como plugins nativos do OpenClaw, o OpenClaw
detecta esses formatos e mapeia o conteúdo compatível para o conjunto de recursos nativos.
Isso significa que você pode instalar um pacote de comandos do Claude ou um bundle de Skills do Codex
e usá-lo imediatamente.

## Instalar um bundle

<Steps>
  <Step title="Instalar a partir de um diretório, arquivo compactado ou marketplace">
    ```bash
    # Diretório local
    openclaw plugins install ./my-bundle

    # Arquivo compactado
    openclaw plugins install ./my-bundle.tgz

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

  </Step>

  <Step title="Verificar a detecção">
    ```bash
    openclaw plugins list
    openclaw plugins inspect <id>
    ```

    Bundles aparecem como `Format: bundle` com subtipo `codex`, `claude` ou `cursor`.

  </Step>

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

    Recursos mapeados (Skills, hooks, ferramentas MCP, padrões LSP) ficam disponíveis na próxima sessão.

  </Step>
</Steps>

## O que o OpenClaw mapeia a partir de bundles

Nem todo recurso de bundle é executado no OpenClaw atualmente. Veja o que
funciona e o que é detectado, mas ainda não está conectado.

### Compatível agora

| Recurso        | Como é mapeado                                                                             | Aplica-se a    |
| -------------- | ------------------------------------------------------------------------------------------ | -------------- |
| Conteúdo de Skill | Raízes de Skill do bundle são carregadas como Skills normais do OpenClaw                | Todos os formatos |
| Comandos       | `commands/` e `.cursor/commands/` tratados como raízes de Skill                            | Claude, Cursor |
| Pacotes de hooks | Layouts no estilo OpenClaw `HOOK.md` + `handler.ts`                                      | Codex          |
| Ferramentas MCP | Configuração MCP do bundle é mesclada nas configurações do Pi incorporado; servidores stdio e HTTP compatíveis são carregados | Todos os formatos |
| Servidores LSP | `.lsp.json` do Claude e `lspServers` declarados no manifesto são mesclados nos padrões LSP do Pi incorporado | Claude         |
| Configurações  | `settings.json` do Claude é importado como padrões do Pi incorporado                       | Claude         |

#### Conteúdo de Skill

- raízes de Skill do bundle são carregadas como raízes normais de Skill do OpenClaw
- raízes `commands` do Claude são tratadas como raízes adicionais de Skill
- raízes `.cursor/commands` do Cursor são tratadas como raízes adicionais de Skill

Isso significa que arquivos de comando markdown do Claude funcionam pelo carregador normal de Skills do OpenClaw.
O markdown de comando do Cursor funciona pelo mesmo caminho.

#### Pacotes de hooks

- raízes de hook do bundle funcionam **apenas** quando usam o layout normal
  de pacote de hooks do OpenClaw. Hoje, isso ocorre principalmente no caso compatível com Codex:
  - `HOOK.md`
  - `handler.ts` ou `handler.js`

#### MCP para Pi

- bundles habilitados podem contribuir com configuração de servidor MCP
- o OpenClaw mescla a configuração MCP do bundle nas configurações efetivas do Pi incorporado como
  `mcpServers`
- o OpenClaw expõe ferramentas MCP de bundle compatíveis durante turnos do agent Pi incorporado ao
  iniciar servidores stdio ou conectar-se a servidores HTTP
- os perfis de ferramentas `coding` e `messaging` incluem ferramentas MCP de bundle por
  padrão; use `tools.deny: ["bundle-mcp"]` para desabilitar para um agent ou Gateway
- configurações locais de Pi do projeto continuam valendo após os padrões do bundle, então
  configurações do espaço de trabalho podem substituir entradas MCP do bundle quando necessário
- catálogos de ferramentas MCP de bundle são ordenados deterministicamente antes do registro, para
  que mudanças upstream na ordem de `listTools()` não desestabilizem blocos de ferramenta do prompt-cache

##### Transportes

Servidores MCP podem usar transporte stdio ou HTTP:

**Stdio** inicia um processo filho:

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

**HTTP** conecta-se a um servidor MCP em execução usando `sse` por padrão, ou `streamable-http` quando solicitado:

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

- `transport` pode ser definido como `"streamable-http"` ou `"sse"`; quando omitido, o OpenClaw usa `sse`
- apenas esquemas de URL `http:` e `https:` são permitidos
- valores de `headers` suportam interpolação `${ENV_VAR}`
- uma entrada de servidor com `command` e `url` ao mesmo tempo é rejeitada
- credenciais em URL (userinfo e query params) são redigidas de descrições de
  ferramenta e logs
- `connectionTimeoutMs` substitui o timeout padrão de 30 segundos de conexão para
  transportes stdio e HTTP

##### Nomenclatura de ferramentas

O OpenClaw registra ferramentas MCP de bundle com nomes seguros para provedores no formato
`serverName__toolName`. Por exemplo, um servidor com chave `"vigil-harbor"` expondo uma
ferramenta `memory_search` é registrado como `vigil-harbor__memory_search`.

- caracteres fora de `A-Za-z0-9_-` são substituídos por `-`
- prefixos de servidor são limitados a 30 caracteres
- nomes completos de ferramenta são limitados a 64 caracteres
- nomes de servidor vazios usam `mcp` como fallback
- nomes saneados que colidem são desambiguados com sufixos numéricos
- a ordem final exposta das ferramentas é determinística por nome seguro para manter turnos repetidos do Pi estáveis para cache
- a filtragem por perfil trata todas as ferramentas de um servidor MCP de bundle como pertencentes ao plugin
  `bundle-mcp`, então listas de permissão e negação de perfil podem incluir
  nomes individuais de ferramentas expostas ou a chave de plugin `bundle-mcp`

#### Configurações do Pi incorporado

- `settings.json` do Claude é importado como configuração padrão do Pi incorporado quando o
  bundle está habilitado
- o OpenClaw sanitiza chaves de substituição de shell antes de aplicá-las

Chaves saneadas:

- `shellPath`
- `shellCommandPrefix`

#### LSP do Pi incorporado

- bundles Claude habilitados podem contribuir com configuração de servidor LSP
- o OpenClaw carrega `.lsp.json` mais quaisquer caminhos `lspServers` declarados no manifesto
- a configuração LSP do bundle é mesclada nos padrões efetivos de LSP do Pi incorporado
- atualmente, apenas servidores LSP compatíveis com stdio podem ser executados; transportes não compatíveis
  ainda aparecem em `openclaw plugins inspect <id>`

### Detectado, mas não executado

Estes são reconhecidos e mostrados em diagnostics, mas o OpenClaw não os executa:

- `agents`, automação `hooks.json`, `outputStyles` do Claude
- `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` do Cursor
- Metadados inline/app do Codex além do relatório de capacidade

## Formatos de bundle

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

    Conteúdo opcional: `skills/`, `hooks/`, `.mcp.json`, `.app.json`

    Bundles Codex se encaixam melhor no OpenClaw quando usam raízes de Skill e diretórios
    de pacote de hooks no estilo OpenClaw (`HOOK.md` + `handler.ts`).

  </Accordion>

  <Accordion title="Bundles Claude">
    Dois modos de detecção:

    - **Baseado em manifesto:** `.claude-plugin/plugin.json`
    - **Sem manifesto:** layout padrão do Claude (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)

    Comportamento específico do Claude:

    - `commands/` é tratado como conteúdo de Skill
    - `settings.json` é importado para as configurações do Pi incorporado (chaves de substituição de shell são saneadas)
    - `.mcp.json` expõe ferramentas stdio compatíveis ao Pi incorporado
    - `.lsp.json` mais caminhos `lspServers` declarados no manifesto são carregados nos padrões LSP do Pi incorporado
    - `hooks/hooks.json` é detectado, mas não executado
    - Caminhos de componente personalizados no manifesto são aditivos (eles estendem os padrões, não os substituem)

  </Accordion>

  <Accordion title="Bundles Cursor">
    Marcadores: `.cursor-plugin/plugin.json`

    Conteúdo opcional: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`

    - `.cursor/commands/` é tratado como conteúdo de Skill
    - `.cursor/rules/`, `.cursor/agents/` e `.cursor/hooks.json` são apenas detectados

  </Accordion>
</AccordionGroup>

## Precedência de detecção

O OpenClaw verifica primeiro o formato de plugin nativo:

1. `openclaw.plugin.json` ou `package.json` válido com `openclaw.extensions` — tratado como **plugin nativo**
2. Marcadores de bundle (`.codex-plugin/`, `.claude-plugin/` ou layout padrão Claude/Cursor) — tratado como **bundle**

Se um diretório contiver ambos, o OpenClaw usa o caminho nativo. Isso evita
que pacotes de formato duplo sejam parcialmente instalados como bundles.

## Dependências de runtime e limpeza

- Dependências de runtime de plugins integrados acompanham o pacote OpenClaw em
  `dist/*`. O OpenClaw **não** executa `npm install` na inicialização para plugins
  integrados; o pipeline de release é responsável por enviar uma carga completa
  de dependências integradas (consulte a regra de verificação pós-publicação em
  [Releasing](/pt-BR/reference/RELEASING)).

## Segurança

Bundles têm um limite de confiança mais restrito do que plugins nativos:

- O OpenClaw **não** carrega módulos de runtime arbitrários do bundle in-process
- Caminhos de Skills e pacotes de hooks devem permanecer dentro da raiz do plugin (verificação de limite)
- Arquivos de configuração são lidos com as mesmas verificações de limite
- Servidores MCP stdio compatíveis podem ser iniciados como subprocessos

Isso torna bundles mais seguros por padrão, mas você ainda deve tratar bundles de terceiros
como conteúdo confiável para os recursos que eles expõem.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O bundle é detectado, mas as capacidades não são executadas">
    Execute `openclaw plugins inspect <id>`. Se uma capacidade estiver listada, mas marcada como
    não conectada, isso é um limite do produto — não uma instalação quebrada.
  </Accordion>

  <Accordion title="Arquivos de comando do Claude não aparecem">
    Confirme que o bundle está habilitado e que os arquivos markdown estão dentro de uma
    raiz `commands/` ou `skills/` detectada.
  </Accordion>

  <Accordion title="As configurações do Claude não são aplicadas">
    Apenas configurações do Pi incorporado vindas de `settings.json` são compatíveis. O OpenClaw não
    trata configurações de bundle como patches brutos de configuração.
  </Accordion>

  <Accordion title="Os hooks do Claude não são executados">
    `hooks/hooks.json` é apenas detectado. Se você precisar de hooks executáveis, use o
    layout de pacote de hooks do OpenClaw ou distribua um plugin nativo.
  </Accordion>
</AccordionGroup>

## Relacionado

- [Instalar e configurar Plugins](/pt-BR/tools/plugin)
- [Criando Plugins](/pt-BR/plugins/building-plugins) — criar um plugin nativo
- [Manifesto de plugin](/pt-BR/plugins/manifest) — schema de manifesto nativo
