---
read_when:
    - Ви хочете встановити пакет, сумісний із Codex, Claude або Cursor
    - Вам потрібно зрозуміти, як OpenClaw зіставляє вміст пакета з нативними можливостями
    - Ви налагоджуєте виявлення бандла або відсутні можливості
summary: Встановлення та використання пакетів Codex, Claude і Cursor як плагінів OpenClaw
title: Пакети Plugin
x-i18n:
    generated_at: "2026-05-01T20:39:39Z"
    model: gpt-5.5
    provider: openai
    source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4
    source_path: plugins/bundles.md
    workflow: 16
---

OpenClaw може встановлювати плагіни з трьох зовнішніх екосистем: **Codex**, **Claude**
і **Cursor**. Вони називаються **пакетами** — наборами вмісту та метаданих, які
OpenClaw відображає на нативні функції, як-от Skills, хуки та MCP-інструменти.

<Info>
  Пакети — це **не** те саме, що нативні плагіни OpenClaw. Нативні плагіни працюють
  у процесі й можуть реєструвати будь-яку можливість. Пакети — це набори вмісту з
  вибірковим відображенням функцій і вужчою межею довіри.
</Info>

## Навіщо існують пакети

Багато корисних плагінів публікуються у форматі Codex, Claude або Cursor. Замість
того щоб вимагати від авторів переписувати їх як нативні плагіни OpenClaw, OpenClaw
виявляє ці формати й відображає їхній підтримуваний вміст на нативний набір
функцій. Це означає, що ви можете встановити пакет команд Claude або пакет Skills
Codex і одразу використовувати його.

## Встановлення пакета

<Steps>
  <Step title="Встановіть із каталогу, архіву або маркетплейсу">
    ```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="Перевірте виявлення">
    ```bash
    openclaw plugins list
    openclaw plugins inspect <id>
    ```

    Пакети відображаються як `Format: bundle` із підтипом `codex`, `claude` або `cursor`.

  </Step>

  <Step title="Перезапустіть і використовуйте">
    ```bash
    openclaw gateway restart
    ```

    Відображені функції (Skills, хуки, MCP-інструменти, стандартні налаштування LSP) доступні в наступному сеансі.

  </Step>
</Steps>

## Що OpenClaw відображає з пакетів

Сьогодні не кожна функція пакета запускається в OpenClaw. Ось що працює та що
виявляється, але ще не підключене.

### Підтримується зараз

| Функція       | Як вона відображається                                                                                 | Застосовується до |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Вміст Skills | Кореневі каталоги Skills пакета завантажуються як звичайні Skills OpenClaw                                           | Усі формати    |
| Команди      | `commands/` і `.cursor/commands/` обробляються як кореневі каталоги Skills                                  | Claude, Cursor |
| Пакети хуків    | OpenClaw-стиль макетів `HOOK.md` + `handler.ts`                                             | Codex          |
| MCP-інструменти     | MCP-конфігурація пакета об’єднується з вбудованими налаштуваннями Pi; підтримувані stdio та HTTP-сервери завантажуються | Усі формати    |
| LSP-сервери   | Claude `.lsp.json` і оголошені в маніфесті `lspServers` об’єднуються зі стандартними налаштуваннями LSP вбудованого Pi  | Claude         |
| Налаштування      | Claude `settings.json` імпортується як стандартні налаштування вбудованого Pi                                     | Claude         |

#### Вміст Skills

- кореневі каталоги Skills пакета завантажуються як звичайні корені Skills OpenClaw
- корені Claude `commands` обробляються як додаткові корені Skills
- корені Cursor `.cursor/commands` обробляються як додаткові корені Skills

Це означає, що markdown-файли команд Claude працюють через звичайний завантажувач
Skills OpenClaw. Markdown-команди Cursor працюють через той самий шлях.

#### Пакети хуків

- корені хуків пакета працюють **лише** тоді, коли вони використовують звичайний
  макет пакета хуків OpenClaw. Сьогодні це насамперед сумісний із Codex випадок:
  - `HOOK.md`
  - `handler.ts` або `handler.js`

#### MCP для Pi

- увімкнені пакети можуть додавати конфігурацію MCP-сервера
- OpenClaw об’єднує MCP-конфігурацію пакета з ефективними вбудованими налаштуваннями Pi як
  `mcpServers`
- OpenClaw надає підтримувані MCP-інструменти пакета під час ходів вбудованого агента Pi,
  запускаючи stdio-сервери або підключаючись до HTTP-серверів
- профілі інструментів `coding` і `messaging` за замовчуванням включають MCP-інструменти пакета;
  використовуйте `tools.deny: ["bundle-mcp"]`, щоб вимкнути їх для агента або Gateway
- локальні налаштування Pi проєкту все одно застосовуються після стандартних налаштувань пакета, тому налаштування
  робочого простору можуть перевизначати записи MCP пакета за потреби
- каталоги MCP-інструментів пакета детерміновано сортуються перед реєстрацією, тому
  зміни порядку upstream `listTools()` не порушують блоки інструментів prompt-cache

##### Транспорти

MCP-сервери можуть використовувати stdio або HTTP-транспорт:

**Stdio** запускає дочірній процес:

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

**HTTP** підключається до запущеного MCP-сервера через `sse` за замовчуванням або через `streamable-http`, коли це запитано:

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

- `transport` можна встановити як `"streamable-http"` або `"sse"`; якщо його пропущено, OpenClaw використовує `sse`
- `type: "http"` — це downstream-форма, нативна для CLI; використовуйте `transport: "streamable-http"` у конфігурації OpenClaw. `openclaw mcp set` і `openclaw doctor --fix` нормалізують поширений псевдонім.
- дозволені лише URL-схеми `http:` і `https:`
- значення `headers` підтримують інтерполяцію `${ENV_VAR}`
- запис сервера з одночасно `command` і `url` відхиляється
- облікові дані URL (userinfo та параметри запиту) редагуються в описах інструментів
  і журналах
- `connectionTimeoutMs` перевизначає стандартний 30-секундний тайм-аут підключення для
  stdio та HTTP-транспортів

##### Іменування інструментів

OpenClaw реєструє MCP-інструменти пакета з безпечними для провайдера іменами у формі
`serverName__toolName`. Наприклад, сервер із ключем `"vigil-harbor"`, який надає
інструмент `memory_search`, реєструється як `vigil-harbor__memory_search`.

- символи поза `A-Za-z0-9_-` замінюються на `-`
- префікси серверів обмежені 30 символами
- повні імена інструментів обмежені 64 символами
- порожні імена серверів замінюються на `mcp`
- конфліктні санітизовані імена розрізняються числовими суфіксами
- фінальний порядок відкритих інструментів детермінований за безпечним іменем, щоб повторні ходи Pi
  залишалися стабільними для кешу
- фільтрація профілю розглядає всі інструменти з одного MCP-сервера пакета як такі, що належать плагіну
  `bundle-mcp`, тому allowlist і deny list профілю можуть включати або
  окремі відкриті імена інструментів, або ключ плагіна `bundle-mcp`

#### Налаштування вбудованого Pi

- Claude `settings.json` імпортується як стандартні налаштування вбудованого Pi, коли
  пакет увімкнено
- OpenClaw санітизує ключі перевизначення оболонки перед їх застосуванням

Санітизовані ключі:

- `shellPath`
- `shellCommandPrefix`

#### LSP вбудованого Pi

- увімкнені пакети Claude можуть додавати конфігурацію LSP-сервера
- OpenClaw завантажує `.lsp.json` плюс будь-які оголошені в маніфесті шляхи `lspServers`
- LSP-конфігурація пакета об’єднується з ефективними стандартними налаштуваннями LSP вбудованого Pi
- сьогодні можна запускати лише підтримувані LSP-сервери на основі stdio; непідтримувані
  транспорти все одно відображаються в `openclaw plugins inspect <id>`

### Виявляється, але не виконується

Вони розпізнаються та відображаються в діагностиці, але OpenClaw їх не запускає:

- Claude `agents`, автоматизація `hooks.json`, `outputStyles`
- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
- Вбудовані метадані Codex/app поза звітуванням про можливості

## Формати пакетів

<AccordionGroup>
  <Accordion title="Пакети Codex">
    Маркери: `.codex-plugin/plugin.json`

    Необов’язковий вміст: `skills/`, `hooks/`, `.mcp.json`, `.app.json`

    Пакети Codex найкраще підходять OpenClaw, коли вони використовують корені Skills і каталоги
    пакетів хуків у стилі OpenClaw (`HOOK.md` + `handler.ts`).

  </Accordion>

  <Accordion title="Пакети Claude">
    Два режими виявлення:

    - **На основі маніфесту:** `.claude-plugin/plugin.json`
    - **Без маніфесту:** стандартний макет Claude (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)

    Поведінка, специфічна для Claude:

    - `commands/` обробляється як вміст Skills
    - `settings.json` імпортується в налаштування вбудованого Pi (ключі перевизначення оболонки санітизуються)
    - `.mcp.json` надає підтримувані stdio-інструменти вбудованому Pi
    - `.lsp.json` плюс оголошені в маніфесті шляхи `lspServers` завантажуються у стандартні налаштування LSP вбудованого Pi
    - `hooks/hooks.json` виявляється, але не виконується
    - користувацькі шляхи компонентів у маніфесті є додатковими (вони розширюють стандартні, а не замінюють їх)

  </Accordion>

  <Accordion title="Пакети Cursor">
    Маркери: `.cursor-plugin/plugin.json`

    Необов’язковий вміст: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`

    - `.cursor/commands/` обробляється як вміст Skills
    - `.cursor/rules/`, `.cursor/agents/` і `.cursor/hooks.json` призначені лише для виявлення

  </Accordion>
</AccordionGroup>

## Пріоритет виявлення

OpenClaw спочатку перевіряє нативний формат плагіна:

1. `openclaw.plugin.json` або дійсний `package.json` з `openclaw.extensions` — обробляється як **нативний плагін**
2. Маркери пакетів (`.codex-plugin/`, `.claude-plugin/` або стандартний макет Claude/Cursor) — обробляються як **пакет**

Якщо каталог містить обидва варіанти, OpenClaw використовує нативний шлях. Це запобігає
частковому встановленню пакетів із двома форматами як пакетів.

## Залежності середовища виконання та очищення

- Сумісні сторонні пакети не отримують startup-ремонт `npm install`. Їх
  слід встановлювати через `openclaw plugins install`, і вони мають постачати все,
  що їм потрібно, у встановленому каталозі плагіна.
- Пакети плагінів, що належать OpenClaw, або постачаються легкими в core, або
  завантажуються через інсталятор плагінів. Запуск Gateway ніколи не запускає для них
  менеджер пакетів.
- `openclaw doctor --fix` видаляє застарілі staged-каталоги залежностей і може
  встановлювати налаштовані завантажувані плагіни, яких немає в локальному
  індексі плагінів.

## Безпека

Пакети мають вужчу межу довіри, ніж нативні плагіни:

- OpenClaw **не** завантажує довільні модулі середовища виконання пакета в процес
- Шляхи Skills і пакетів хуків мають залишатися всередині кореня плагіна (з перевіркою меж)
- Файли налаштувань читаються з тими самими перевірками меж
- Підтримувані stdio MCP-сервери можуть запускатися як підпроцеси

Це робить пакети безпечнішими за замовчуванням, але все одно слід вважати сторонні
пакети довіреним вмістом для функцій, які вони надають.

## Усунення неполадок

<AccordionGroup>
  <Accordion title="Пакет виявлено, але можливості не запускаються">
    Виконайте `openclaw plugins inspect <id>`. Якщо можливість зазначена, але позначена як
    непідключена, це обмеження продукту, а не пошкоджене встановлення.
  </Accordion>

  <Accordion title="Файли команд Claude не з’являються">
    Переконайтеся, що пакет увімкнено, а markdown-файли розташовані всередині виявленого
    кореня `commands/` або `skills/`.
  </Accordion>

  <Accordion title="Налаштування Claude не застосовуються">
    Підтримуються лише налаштування вбудованого Pi з `settings.json`. OpenClaw не
    розглядає налаштування пакета як сирі патчі конфігурації.
  </Accordion>

  <Accordion title="Хуки Claude не виконуються">
    `hooks/hooks.json` призначений лише для виявлення. Якщо вам потрібні виконувані хуки, використовуйте
    макет пакета хуків OpenClaw або постачайте нативний плагін.
  </Accordion>
</AccordionGroup>

## Пов’язане

- [Встановлення та налаштування плагінів](/uk/tools/plugin)
- [Створення плагінів](/uk/plugins/building-plugins) — створення нативного плагіна
- [Маніфест Plugin](/uk/plugins/manifest) — схема нативного маніфесту
