---
doc-schema-version: 1
read_when:
    - Установка или настройка Plugin
    - Понимание правил обнаружения и загрузки Plugin
    - Работа с пакетами Plugin, совместимыми с Codex/Claude
sidebarTitle: Getting Started
summary: Устанавливайте, настраивайте и управляйте Plugin OpenClaw
title: Plugin
x-i18n:
    generated_at: "2026-06-28T23:54:39Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: c61e0ddb164baba368fbf57883e7a72eddadc28cb100ed6c4f11977c55576513
    source_path: tools/plugin.md
    workflow: 16
---

Плагины расширяют OpenClaw каналами, поставщиками моделей, средами выполнения агентов, инструментами,
Skills, речью, транскрипцией в реальном времени, голосом, пониманием медиа, генерацией,
получением веб-ресурсов, веб-поиском и другими возможностями runtime.

Используйте эту страницу, когда нужно установить плагин, перезапустить Gateway, проверить,
что runtime загрузил его, и разобраться с типичными сбоями настройки. Примеры только с командами
см. в разделе [Управление плагинами](/ru/plugins/manage-plugins). Полный сгенерированный
перечень встроенных, официальных внешних и доступных только из исходников плагинов см. в
[Инвентаре плагинов](/ru/plugins/plugin-inventory).

## Требования

Перед установкой плагина убедитесь, что у вас есть:

- checkout или установка OpenClaw с доступной CLI `openclaw`
- сетевой доступ к выбранному источнику, например ClawHub, npm или git-хосту
- любые учетные данные, ключи конфигурации или инструменты операционной системы, специфичные для плагина и указанные
  в документации по настройке этого плагина
- разрешение для Gateway, который обслуживает ваши каналы, на перезагрузку или перезапуск

## Быстрый старт

<Steps>
  <Step title="Найдите плагин">
    Ищите публичные пакеты плагинов в [ClawHub](/ru/clawhub):

    ```bash
    openclaw plugins search "calendar"
    ```

    ClawHub — основной интерфейс обнаружения для плагинов сообщества. Во время
    переходного периода запуска обычные спецификации пакетов без префикса по-прежнему устанавливаются из npm, если
    не совпадают с официальным id плагина. Необработанные спецификации пакетов `@openclaw/*`, которые совпадают
    со встроенными плагинами, используют встроенную копию из текущей сборки OpenClaw. Используйте
    явный префикс, когда нужен конкретный источник.

  </Step>

  <Step title="Установите плагин">
    ```bash
    # From ClawHub.
    openclaw plugins install clawhub:<package>

    # From npm.
    openclaw plugins install npm:<package>

    # From git.
    openclaw plugins install git:github.com/<owner>/<repo>@<ref>

    # From a local development checkout.
    openclaw plugins install ./my-plugin
    openclaw plugins install --link ./my-plugin
    ```

    Относитесь к установке плагинов как к запуску кода. Предпочитайте закрепленные версии, когда
    вам нужны воспроизводимые производственные установки.

  </Step>

  <Step title="Настройте и включите его">
    Настраивайте специфичные для плагина параметры в `plugins.entries.<id>.config`.
    Включите плагин, если он еще не включен:

    ```bash
    openclaw plugins enable <plugin-id>
    ```

    Если ваша конфигурация использует ограничительный список `plugins.allow`, id установленного плагина
    должен присутствовать в нем, прежде чем плагин сможет загрузиться.
    `openclaw plugins install` добавляет установленный id в существующий
    список `plugins.allow` и удаляет тот же id из `plugins.deny`, чтобы
    явно установленный плагин мог загрузиться после перезапуска.

  </Step>

  <Step title="Дайте Gateway перезагрузиться">
    Установка, обновление или удаление кода плагина требует перезапуска Gateway.
    Когда управляемый Gateway уже запущен с включенной перезагрузкой конфигурации,
    OpenClaw обнаруживает измененную запись об установленном плагине и перезапускает
    Gateway автоматически. Если Gateway не управляется или перезагрузка отключена,
    перезапустите его самостоятельно:

    ```bash
    openclaw gateway restart
    ```

    Операции включения и отключения обновляют конфигурацию и обновляют холодный реестр.
    Проверка runtime по-прежнему остается самым понятным путем верификации активных поверхностей
    runtime.

  </Step>

  <Step title="Проверьте регистрацию в runtime">
    ```bash
    openclaw plugins inspect <plugin-id> --runtime --json
    ```

    Используйте `--runtime`, когда нужно подтвердить зарегистрированные инструменты, хуки, сервисы,
    методы Gateway или принадлежащие плагину команды CLI. Обычный `inspect` — это холодная
    проверка манифеста и реестра.

  </Step>
</Steps>

## Конфигурация

### Выберите источник установки

| Источник    | Используйте, когда                                                              | Пример                                                         |
| ----------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| ClawHub     | Вам нужны нативное для OpenClaw обнаружение, сканирования, метаданные версий и подсказки по установке | `openclaw plugins install clawhub:<package>`                   |
| npm         | Вам нужны прямые workflows реестра npm или dist-tag                            | `openclaw plugins install npm:<package>`                       |
| git         | Вам нужна ветка, тег или коммит из репозитория                                 | `openclaw plugins install git:github.com/<owner>/<repo>@<ref>` |
| локальный путь | Вы разрабатываете или тестируете плагин на той же машине                    | `openclaw plugins install --link ./my-plugin`                  |
| marketplace | Вы устанавливаете совместимый с Claude плагин marketplace                      | `openclaw plugins install <plugin> --marketplace <source>`     |

Спецификации пакетов без префикса имеют особое поведение совместимости. Если имя без префикса совпадает
с id встроенного плагина, OpenClaw использует этот встроенный источник. Если оно совпадает с
id официального внешнего плагина, OpenClaw использует официальный каталог пакетов. Другие
обычные спецификации пакетов без префикса устанавливаются через npm во время переходного периода запуска. Необработанные
спецификации пакетов `@openclaw/*`, которые совпадают со встроенными плагинами, также разрешаются в
встроенную копию перед fallback на npm. Используйте `npm:@openclaw/<plugin>@<version>`, когда
вы намеренно хотите внешний пакет npm вместо принадлежащей образу
встроенной копии. Используйте `clawhub:`, `npm:`, `git:` или `npm-pack:`, когда нужен
детерминированный выбор источника. Полный контракт команды см. в [`openclaw plugins`](/ru/cli/plugins#install).

Для установок из npm незакрепленные спецификации пакетов и `@latest` выбирают самый новый стабильный
пакет, который объявляет совместимость с этой сборкой OpenClaw. Если текущий
latest-релиз npm объявляет более новый `openclaw.compat.pluginApi` или
`openclaw.install.minHostVersion`, OpenClaw сканирует более старые стабильные версии пакета
и устанавливает самую новую подходящую. Точные версии и явные теги каналов,
например `@beta`, остаются закрепленными за выбранным пакетом и завершаются ошибкой при несовместимости.

### Политика установки оператора

Настройте `security.installPolicy`, чтобы запускать доверенную локальную команду политики перед тем,
как продолжится установка или обновление плагина. Политика получает метаданные плюс подготовленный
путь к источнику и может разрешить или заблокировать установку. Она покрывает пути установки и обновления
плагинов через CLI и Gateway. Хуки плагина `before_install` запускаются позже только в
процессах OpenClaw, где хуки плагинов загружены, поэтому используйте `security.installPolicy`
для решений об установке, принадлежащих оператору. Устаревший
флаг `--dangerously-force-unsafe-install` принимается для совместимости, но не
обходит политику установки или встроенный в OpenClaw denylist зависимостей плагинов.

Общую exec-схему `security.installPolicy`, используемую как Skills, так и
плагинами, см. в [Конфигурации Skills](/ru/tools/skills-config#operator-install-policy-securityinstallpolicy).

### Настройте политику плагинов

Общая форма конфигурации плагинов:

```json5
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
```

Основные правила политики:

- `plugins.enabled: false` отключает все плагины и пропускает работу обнаружения и загрузки
  плагинов. Устаревшие ссылки на плагины неактивны, пока это включено; повторно включите
  плагины перед запуском очистки doctor, если хотите удалить устаревшие id.
- `plugins.deny` имеет приоритет над allow и включением отдельного плагина.
- `plugins.allow` — это исключительный allowlist. Инструменты, принадлежащие плагинам, вне
  allowlist остаются недоступными, даже когда `tools.allow` включает `"*"`.
- `plugins.entries.<id>.enabled: false` отключает один плагин, сохраняя его
  конфигурацию.
- `plugins.load.paths` добавляет явные локальные файлы или каталоги плагинов. Управляемые
  локальные пути `plugins install` должны быть каталогами или архивами плагинов; используйте
  `plugins.load.paths` для отдельных файлов плагинов.
- Плагины из workspace по умолчанию отключены; явно включите их или
  добавьте в allowlist перед использованием локального кода workspace.
- Встроенные плагины следуют своим встроенным метаданным default-on/default-off, если
  конфигурация явно не переопределяет их.
- `plugins.slots.<slot>` выбирает один плагин для эксклюзивных категорий, таких как
  движки памяти и контекста. Выбор слота принудительно включает выбранный плагин
  для этого слота, считаясь явной активацией; он может загрузиться даже тогда, когда
  иначе требовал бы opt-in. `plugins.deny` и
  `plugins.entries.<id>.enabled: false` все равно блокируют его.
- Встроенные плагины opt-in могут автоматически активироваться, когда конфигурация называет одну из принадлежащих им
  поверхностей, например ссылку provider/model, конфигурацию канала, backend CLI или runtime
  среды выполнения агента.
- Маршрутизация Codex семейства OpenAI держит границы поставщика и runtime-плагина
  раздельными: устаревшие ссылки на модели Codex — это устаревшая конфигурация, исправляемая doctor, а встроенный
  плагин `codex` владеет runtime сервера приложения Codex для канонических ссылок агентов `openai/*`,
  явного `agentRuntime.id: "codex"` и устаревших ссылок `codex/*`.

Когда `plugins.allow` не задан и невстроенные плагины автоматически обнаруживаются из
workspace или глобальных корней плагинов, при запуске выводится лог
`plugins.allow is empty; discovered non-bundled plugins may auto-load: ...`.
Предупреждение включает обнаруженные id плагинов и, для коротких списков, минимальный
фрагмент `plugins.allow`. Запустите
[`openclaw plugins list --enabled --verbose`](/ru/cli/plugins#list) или
[`openclaw plugins inspect <id>`](/ru/cli/plugins#inspect) с указанным id плагина,
прежде чем копировать доверенные плагины в `openclaw.json`. Та же рекомендация по закреплению доверия
применяется, когда диагностика сообщает, что плагин загрузился
`without install/load-path provenance`: проверьте этот id плагина, затем закрепите
доверенный id в `plugins.allow` или переустановите из доверенного источника, чтобы OpenClaw
записал происхождение установки.

Запускайте `openclaw doctor` или `openclaw doctor --fix`, когда проверка конфигурации сообщает
об устаревших id плагинов, несоответствиях allowlist/tools или устаревших путях встроенных плагинов.

## Разберитесь с форматами плагинов

OpenClaw распознает два формата плагинов:

| Формат                 | Как он загружается                                                            | Используйте, когда                                                       |
| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Нативный плагин OpenClaw | `openclaw.plugin.json` плюс модуль runtime, загруженный в процессе          | Вы устанавливаете или создаете специфичные для OpenClaw возможности runtime |
| Совместимый bundle     | Структура плагина Codex, Claude или Cursor, сопоставленная с инвентарем плагинов OpenClaw | Вы повторно используете совместимые Skills, команды, хуки или метаданные bundle |

Оба формата отображаются в `openclaw plugins list`, `openclaw plugins inspect`,
`openclaw plugins enable` и `openclaw plugins disable`. Границу совместимости bundle см. в
[Bundle плагинов](/ru/plugins/bundles), а создание нативных плагинов — в
[Создании плагинов](/ru/plugins/building-plugins).

## Хуки плагинов

Плагины могут регистрировать хуки во время runtime, но есть два разных API с
разными задачами.

- Используйте типизированные хуки через `api.on(...)` для хуков жизненного цикла runtime. Это
  предпочтительная поверхность для middleware, политики, переписывания сообщений, формирования prompt
  и управления инструментами.
- Используйте `api.registerHook(...)` только когда хотите участвовать во внутренней
  системе хуков, описанной в [Хуках](/ru/automation/hooks). Это в основном нужно для грубых
  побочных эффектов команд/жизненного цикла и совместимости с существующей автоматизацией в стиле HOOK.

Краткое правило:

- Если обработчику нужны приоритет, семантика слияния или поведение блокировки/отмены, используйте
  типизированные хуки плагинов.
- Если обработчик просто реагирует на `command:new`, `command:reset`, `message:sent`
  или похожие грубые события, `api.registerHook(...)` подходит.

Внутренние хуки, управляемые плагинами, отображаются в `openclaw hooks list` с
`plugin:<id>`. Их нельзя включить или отключить через `openclaw hooks`;
вместо этого включите или отключите плагин.

## Проверьте активный Gateway

`openclaw plugins list` и простой `openclaw plugins inspect` читают холодное состояние
конфигурации, манифеста и реестра. Они не доказывают, что уже запущенный Gateway
импортировал тот же код Plugin.

Когда Plugin выглядит установленным, но живой трафик чата его не использует:

```bash
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart
```

Управляемые Gateway автоматически перезапускаются после установки, обновления и
удаления Plugin, если эти изменения затрагивают исходный код Plugin. В установках
на VPS или в контейнере убедитесь, что ручной перезапуск нацелен на фактический
дочерний процесс `openclaw gateway run`, который обслуживает ваши каналы, а не
только на обертку или супервизор.

## Устранение неполадок

| Симптом                                                        | Проверка                                                                                                                                      | Исправление                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Plugin отображается в `plugins list`, но runtime-хуки не выполняются  | Используйте `openclaw plugins inspect <id> --runtime --json` и подтвердите активный Gateway с помощью `gateway status --deep --require-rpc`             | Перезапустите живой Gateway после установки, обновления, изменения конфигурации или исходного кода                               |
| Появляются диагностические сообщения о дублирующемся владельце канала или инструмента         | Запустите `openclaw plugins list --enabled --verbose`, проверьте каждый подозрительный Plugin с `--runtime --json` и сравните владение каналами/инструментами | Отключите одного владельца, удалите устаревшие установки или используйте `preferOver` в манифесте для намеренной замены      |
| Конфигурация сообщает, что Plugin отсутствует                                | Проверьте [инвентарь Plugin](/ru/plugins/plugin-inventory), чтобы понять, является ли он встроенным, официальным внешним или доступным только из исходного кода                           | Установите внешний пакет, включите встроенный Plugin или удалите устаревшую конфигурацию                         |
| Конфигурация недействительна во время установки                               | Прочитайте сообщение проверки и запустите `openclaw doctor --fix`, если оно указывает на устаревшее состояние Plugin                                           | Doctor может поместить недействительную конфигурацию Plugin в карантин, отключив запись и удалив недействительную полезную нагрузку     |
| Путь Plugin заблокирован из-за подозрительного владельца или разрешений | Проверьте диагностическое сообщение перед ошибкой конфигурации                                                                                             | Исправьте владельца/разрешения файловой системы, затем запустите `openclaw plugins registry --refresh`                    |
| `OPENCLAW_NIX_MODE=1` блокирует команды жизненного цикла                | Подтвердите, что установка управляется Nix                                                                                                      | Измените выбор Plugin в исходном коде Nix вместо использования команд изменения Plugin                      |
| Импорт зависимости завершается ошибкой во время выполнения                             | Проверьте, был ли Plugin установлен через npm/git/ClawHub или загружен из локального пути                                                 | Запустите `openclaw plugins update <id>`, переустановите исходный код или самостоятельно установите зависимости локального Plugin |

Когда устаревшая конфигурация Plugin все еще называет уже не обнаруживаемый
канальный Plugin, запуск Gateway пропускает этот канал, поддерживаемый Plugin,
вместо блокировки всех остальных каналов. Запустите `openclaw doctor --fix`,
чтобы удалить устаревшие записи Plugin и каналов. Неизвестные ключи каналов без
признаков устаревшего Plugin по-прежнему не проходят проверку, чтобы опечатки
оставались видимыми.

Для намеренной замены канала предпочтительный Plugin должен объявить
`channelConfigs.<channel-id>.preferOver` с идентификатором устаревшего или менее
приоритетного Plugin. Если оба Plugin явно включены, OpenClaw сохраняет этот
запрос и сообщает диагностические данные о дублирующемся канале или инструменте,
а не молча выбирает одного владельца.

Если установленный пакет сообщает, что он `requires compiled runtime output for
TypeScript entry ...`, пакет был опубликован без файлов JavaScript, необходимых
OpenClaw во время выполнения. Обновите или переустановите его после того, как
издатель выпустит скомпилированный JavaScript, либо отключите/удалите Plugin до
тех пор.

### Заблокированный владелец пути Plugin

Если диагностика Plugin сообщает
`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
и затем проверка конфигурации показывает `plugin present but blocked`, OpenClaw
нашел файлы Plugin, принадлежащие другому пользователю Unix, а не процессу,
который их загружает. Оставьте конфигурацию Plugin на месте; исправьте владельца
файловой системы или запускайте OpenClaw от имени того же пользователя, которому
принадлежит каталог состояния.

Для установок Docker официальный образ запускается как `node` (uid `1000`), поэтому
каталоги конфигурации OpenClaw и рабочей области, примонтированные с хоста, обычно
должны принадлежать uid `1000`:

```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
```

Если вы намеренно запускаете OpenClaw от root, вместо этого исправьте управляемый
корень Plugin на владение root:

```bash
sudo chown -R root:root /path/to/openclaw-config/npm
```

После исправления владельца повторно запустите `openclaw doctor --fix` или
`openclaw plugins registry --refresh`, чтобы сохраненный реестр Plugin
соответствовал исправленным файлам.

### Медленная настройка инструментов Plugin

Если ходы агента выглядят зависшими при подготовке инструментов, включите
журналирование трассировки и проверьте строки времени фабрик инструментов Plugin:

```bash
openclaw config set logging.level trace
openclaw logs --follow
```

Ищите:

```text
[trace:plugin-tools] factory timings ...
```

Сводка перечисляет общее время фабрик и самые медленные фабрики инструментов
Plugin, включая идентификатор Plugin, объявленные имена инструментов, форму
результата и является ли инструмент необязательным. Медленные строки повышаются
до предупреждений, когда одна фабрика занимает не менее 1 с или общая подготовка
фабрик инструментов Plugin занимает не менее 5 с.

OpenClaw кэширует успешные результаты фабрик инструментов Plugin для повторных
разрешений с тем же эффективным контекстом запроса. Ключ кэша включает
эффективную runtime-конфигурацию, рабочую область, идентификаторы агента/сеанса,
политику песочницы, настройки браузера, контекст доставки, личность запрашивающего
и состояние владения, поэтому фабрики, зависящие от этих доверенных полей,
запускаются повторно при изменении контекста. Если время остается высоким,
Plugin может выполнять дорогую работу до возврата определений инструментов.

Если один Plugin доминирует по времени, проверьте его runtime-регистрации:

```bash
openclaw plugins inspect <plugin-id> --runtime --json
```

Затем обновите, переустановите или отключите этот Plugin. Авторам Plugin следует
перенести дорогую загрузку зависимостей за путь выполнения инструмента, а не
делать ее внутри фабрики инструмента.

О корнях зависимостей, проверке метаданных пакета, записях реестра, поведении
перезагрузки при запуске и очистке legacy-состояния см.
[разрешение зависимостей Plugin](/ru/plugins/dependency-resolution).

## См. также

- [Управление Plugin](/ru/plugins/manage-plugins) - примеры команд для просмотра списка, установки, обновления, удаления и публикации
- [`openclaw plugins`](/ru/cli/plugins) - полный справочник CLI
- [Инвентарь Plugin](/ru/plugins/plugin-inventory) - сгенерированный список встроенных и внешних Plugin
- [Справочник Plugin](/ru/plugins/reference) - сгенерированные справочные страницы по каждому Plugin
- [Сообщественные Plugin](/ru/plugins/community) - обнаружение ClawHub и политика PR для документации
- [Разрешение зависимостей Plugin](/ru/plugins/dependency-resolution) - корни установки, записи реестра и границы времени выполнения
- [Создание Plugin](/ru/plugins/building-plugins) - руководство по созданию нативных Plugin
- [Обзор Plugin SDK](/ru/plugins/sdk-overview) - runtime-регистрация, хуки и поля API
- [Манифест Plugin](/ru/plugins/manifest) - манифест и метаданные пакета