---
read_when:
    - Вы хотите установить или управлять плагинами Gateway либо совместимыми пакетами
    - Вы хотите создать каркас или проверить простой плагин с инструментом
    - Вы хотите отладить сбои загрузки плагина
sidebarTitle: Plugins
summary: Справочник CLI для `openclaw plugins` (инициализация, сборка, проверка, вывод списка, установка, маркетплейс, удаление, включение/отключение, диагностика)
title: Плагины
x-i18n:
    generated_at: "2026-07-16T16:15:32Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: dadc182cd931672d98c3d1c6ddc1f1defdf0384b25feff7bd4b5324a7fc2e26c
    source_path: cli/plugins.md
    workflow: 16
---

Управление плагинами Gateway, пакетами хуков и совместимыми комплектами.

<CardGroup cols={2}>
  <Card title="Система плагинов" href="/ru/tools/plugin">
    Руководство для конечных пользователей по установке, включению и устранению неполадок плагинов.
  </Card>
  <Card title="Управление плагинами" href="/ru/plugins/manage-plugins">
    Краткие примеры установки, просмотра списка, обновления, удаления и публикации.
  </Card>
  <Card title="Комплекты плагинов" href="/ru/plugins/bundles">
    Модель совместимости комплектов.
  </Card>
  <Card title="Манифест плагина" href="/ru/plugins/manifest">
    Поля манифеста и схема конфигурации.
  </Card>
  <Card title="Безопасность" href="/ru/gateway/security">
    Усиление безопасности при установке плагинов.
  </Card>
</CardGroup>

## Команды

```bash
openclaw plugins list [--enabled] [--verbose] [--json]
openclaw plugins search <query> [--limit <n>] [--json]
openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]
openclaw plugins inspect <id> [--runtime] [--json]
openclaw plugins inspect --all [--runtime] [--json]
openclaw plugins info <id>                    # псевдоним для inspect
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]
openclaw plugins update <id-or-npm-spec> | --all [--dry-run]
openclaw plugins registry [--refresh] [--json]
openclaw plugins doctor
openclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]
openclaw plugins build [--entry <path>] [--check]
openclaw plugins validate [--entry <path>]
openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]
openclaw plugins marketplace list <source> [--json]
openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]
```

Для исследования медленной установки, проверки, удаления или обновления реестра запустите
команду с `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трассировка записывает длительность этапов
в stderr и сохраняет JSON-вывод пригодным для разбора. См. раздел [Отладка](/ru/help/debugging#plugin-lifecycle-trace).

<Note>
В режиме Nix (`OPENCLAW_NIX_MODE=1`) `openclaw.json` неизменяем. Команды `install`, `update`, `uninstall`, `enable` и `disable` отказываются выполняться. Вместо этого измените исходный код Nix для этой установки (`programs.openclaw.config` или `instances.<name>.config` для nix-openclaw), а затем пересоберите её. См. ориентированное на агента [Краткое руководство](https://github.com/openclaw/nix-openclaw#quick-start).
</Note>

<Note>
Встроенные плагины поставляются с OpenClaw. Некоторые включены по умолчанию (например, встроенные поставщики моделей, встроенные поставщики синтеза речи и встроенный браузерный плагин); для остальных требуется `plugins enable`.

Нативные плагины OpenClaw поставляют `openclaw.plugin.json` со встроенной JSON Schema (`configSchema`, даже если она пуста). Совместимые комплекты используют собственные манифесты комплектов.

`plugins list` показывает `Format: openclaw` или `Format: bundle`. Подробный вывод списка/информации также показывает подтип комплекта (`codex`, `claude` или `cursor`) и обнаруженные возможности комплекта.
</Note>

## Создание

```bash
openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate
```

По умолчанию `plugins init` создаёт минимальный плагин инструмента на TypeScript. Первый
аргумент — идентификатор плагина; `--name` задаёт отображаемое имя. OpenClaw использует
идентификатор для каталога вывода по умолчанию и именования пакета. Заготовки инструментов используют
`defineToolPlugin` и создают сценарии `package.json` `plugin:build` и
`plugin:validate`, которые выполняют сборку, а затем вызывают `openclaw plugins build`/`validate`.

`plugins build` импортирует собранную точку входа, считывает статические метаданные инструмента, записывает
`openclaw.plugin.json` и поддерживает `openclaw.extensions` из `package.json` в согласованном состоянии.
`plugins validate` проверяет, что сгенерированный манифест, метаданные пакета и
текущий экспорт точки входа по-прежнему согласованы. Полный процесс создания см. в разделе
[Плагины инструментов](/ru/plugins/tool-plugins).

Заготовка записывает исходный код TypeScript, но создаёт метаданные из собранной
точки входа `./dist/index.js`, поэтому этот процесс также работает с опубликованным CLI. Используйте
`--entry <path>`, если точка входа отличается от стандартной точки входа пакета. Используйте
`plugins build --check` в CI, чтобы завершать работу с ошибкой при устаревших сгенерированных метаданных,
не перезаписывая файлы.

### Заготовка поставщика

```bash
openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate
```

Заготовки поставщиков создают универсальный плагин поставщика моделей, совместимый с OpenAI,
с инфраструктурой аутентификации по API-ключу, сценарием `npm run validate`, который запускает
`clawhub package validate`, метаданными пакета ClawHub и запускаемым вручную
рабочим процессом GitHub Actions для будущей доверенной публикации через GitHub
OIDC. Заготовки поставщиков не создают Skills и не используют
`openclaw plugins build`/`validate`; эти команды предназначены для пути сгенерированных метаданных
заготовки инструмента.

Перед публикацией замените временный базовый URL API, каталог моделей, маршрут документации,
текст учётных данных и содержимое README реальными сведениями о поставщике. Используйте
сгенерированный README для первой публикации в ClawHub и настройки доверенного издателя.

## Установка

```bash
openclaw plugins search "calendar"                      # поиск плагинов ClawHub
openclaw plugins install @openclaw/<package>            # доверенный официальный каталог
openclaw plugins install <package>                       # произвольный пакет npm
openclaw plugins install clawhub:<package>                # только ClawHub
openclaw plugins install npm:<package>                    # только npm
openclaw plugins install npm-pack:<path.tgz>               # локальный tar-архив npm-pack
openclaw plugins install git:github.com/<owner>/<repo>     # репозиторий git
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <path>                            # локальный путь или архив
openclaw plugins install -l <path>                         # ссылка вместо копирования
openclaw plugins install <plugin>@<marketplace>             # сокращённая запись маркетплейса
openclaw plugins install <plugin> --marketplace <name>      # маркетплейс (явно)
openclaw plugins install <package> --force                  # подтверждение источника / перезапись существующего
openclaw plugins install <package> --pin                    # фиксация разрешённой версии npm
openclaw plugins install clawhub:<package> --acknowledge-clawhub-risk
openclaw plugins install <package> --dangerously-force-unsafe-install
```

Сопровождающие, тестирующие установку во время настройки, могут переопределить автоматические источники
установки плагинов с помощью защищённых переменных окружения. См.
[Переопределения установки плагинов](/ru/plugins/install-overrides).

<Warning>
Во время перехода при запуске пакеты с простыми именами по умолчанию устанавливаются из npm, если только их имена не совпадают с идентификатором встроенного или официального плагина; в этом случае OpenClaw использует соответствующую локальную/официальную копию вместо обращения к реестру npm. Используйте `npm:<package>`, если намеренно требуется внешний пакет npm. Для ClawHub используйте `clawhub:<package>`. Относитесь к установке плагинов как к запуску кода; предпочитайте зафиксированные версии.
</Warning>

<Warning>
Пакеты ClawHub и встроенный/официальный каталог OpenClaw являются доверенными источниками
установки. Новый произвольный источник npm, `npm-pack:`, git, локальный путь/архив или
маркетплейс выводит предупреждение и запрашивает подтверждение перед продолжением. Для неинтерактивной установки
из произвольных источников необходимо передать `--force` после проверки источника и установления доверия к нему. Тот же
флаг при необходимости перезаписывает существующий целевой объект установки. Для обычных обновлений
уже отслеживаемой установки он не требуется. Это подтверждение не связано с
`--acknowledge-clawhub-risk`, который применяется только к предупреждениям о доверии к рискованным выпускам
ClawHub. `--force` не обходит `security.installPolicy` или остальные
проверки безопасности установки.
</Warning>

`plugins search` запрашивает в ClawHub доступные для установки пакеты `code-plugin` и
`bundle-plugin` (не Skills; для них используйте `openclaw skills search`).
Значение `--limit` по умолчанию — 20, максимальное — 100. Команда только считывает удалённый каталог: без
проверки локального состояния, изменения конфигурации, установки пакетов или загрузки среды выполнения
плагина. Результаты содержат имя пакета ClawHub, семейство, канал, версию,
сводку и подсказку по установке, например `openclaw plugins install clawhub:<package>`.

<Note>
ClawHub — основная платформа распространения и обнаружения большинства плагинов. Npm
остаётся поддерживаемым резервным вариантом и способом прямой установки. Принадлежащие OpenClaw
пакеты плагинов `@openclaw/*` снова публикуются в npm; актуальный список см.
на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) или в
[перечне плагинов](/ru/plugins/plugin-inventory). Для стабильных установок используется `latest`.
При установке и обновлении из бета-канала предпочтение отдаётся dist-тегу npm `beta`, если он доступен,
с откатом на `latest`. В канале расширенной стабильности официальные плагины npm
с простым/стандартным намерением или намерением `latest` разрешаются в точную установленную версию ядра.
Точные фиксации и явные теги, отличные от `latest`, сторонние пакеты и
источники не из npm не переписываются.
</Note>

<AccordionGroup>
  <Accordion title="Включения конфигурации и исправление недопустимой конфигурации">
    Если раздел `plugins` основан на однофайловом `$include`, `plugins install/update/enable/disable/uninstall` записывают изменения непосредственно в этот включённый файл и не затрагивают `openclaw.json`. Корневые включения, массивы включений и включения с соседними переопределениями завершаются с отказом вместо выравнивания структуры. Поддерживаемые формы см. в разделе [Включения конфигурации](/ru/gateway/configuration).

    Если во время установки конфигурация недопустима, `plugins install` обычно завершается с отказом и предлагает сначала запустить `openclaw doctor --fix`. При запуске Gateway и горячей перезагрузке недопустимая конфигурация плагина приводит к отказу, как и любая другая недопустимая конфигурация; `openclaw doctor --fix` может поместить недопустимую запись плагина в карантин. Единственное документированное исключение во время установки — узкий путь восстановления встроенного плагина для плагинов, которые явно включают `openclaw.install.allowInvalidConfigRecovery`.

  </Accordion>
  <Accordion title="Подтверждение --force и переустановка в сравнении с обновлением">
    `--force` подтверждает источник, не относящийся к ClawHub, без запроса. Он не обходит `security.installPolicy` или остальные проверки безопасности установки. Если плагин или пакет хуков уже установлен, он также повторно использует существующий целевой объект и перезаписывает его на месте. Используйте его после проверки произвольного источника npm, локального источника, архива, git или маркетплейса либо при намеренной переустановке того же идентификатора. Для обычных обновлений уже отслеживаемого плагина npm предпочтительно использовать `openclaw plugins update <id-or-npm-spec>`.

    Если запустить `plugins install` для идентификатора уже установленного плагина, OpenClaw остановится и предложит использовать `plugins update <id-or-npm-spec>` для обычного обновления либо `plugins install <package> --force`, если действительно требуется перезаписать текущую установку из другого источника. Для произвольных источников по-прежнему выводится интерактивное предупреждение о происхождении; после проверки для неинтерактивной установки необходимо передать `--force`. Для доверенных источников ClawHub и каталога OpenClaw это не требуется. При `--link` параметр `--force` подтверждает источник, но не изменяет режим установки по связанному пути.

  </Accordion>
  <Accordion title="Область действия --pin">
    `--pin` применяется только к установкам npm и записывает точное разрешённое значение `<name>@<version>`. Он не поддерживается с установками `git:` (вместо этого зафиксируйте ссылку в спецификации, например `git:github.com/acme/plugin@v1.2.3`) или с `--marketplace` (установки из маркетплейса сохраняют метаданные источника маркетплейса вместо спецификации npm).
  </Accordion>
  <Accordion title="--dangerously-force-unsafe-install">
    `--dangerously-force-unsafe-install` устарел и теперь ничего не делает. OpenClaw больше не выполняет встроенную блокировку опасного кода во время установки плагинов.

    Используйте принадлежащую оператору поверхность `security.installPolicy`, когда требуется политика установки, специфичная для хоста. Хуки `before_install` плагина — это хуки жизненного цикла среды выполнения плагина, а не основная граница политики для установок через CLI.

    Если опубликованный вами в ClawHub плагин скрыт или заблокирован проверкой реестра, выполните действия для издателя из раздела [Публикация в ClawHub](/ru/clawhub/publishing). `--dangerously-force-unsafe-install` не запрашивает у ClawHub повторную проверку плагина и не делает заблокированный выпуск общедоступным.

  </Accordion>
  <Accordion title="--acknowledge-clawhub-risk">
    При установке пакетов сообщества из ClawHub перед скачиванием проверяются сведения о доверии для выбранного выпуска. Если ClawHub отключил скачивание выпуска, сообщил об обнаружении вредоносного содержимого при проверке или перевёл выпуск в блокирующее состояние модерации (карантин, отзыв), OpenClaw безусловно отклоняет его независимо от этого флага. При неблокирующих рискованных статусах проверки или состояниях модерации OpenClaw показывает сведения о доверии и запрашивает подтверждение перед продолжением.

    Используйте `--acknowledge-clawhub-risk` только после ознакомления с предупреждением ClawHub и принятия решения продолжить без интерактивного запроса. Ожидающие или устаревшие (ещё не признанные чистыми) результаты проверки вызывают предупреждение, но не требуют подтверждения. Официальные пакеты ClawHub и встроенные источники плагинов OpenClaw полностью обходят эту проверку доверия к выпуску.

  </Accordion>
  <Accordion title="Пакеты хуков и спецификации npm">
    `plugins install` также служит поверхностью установки для пакетов хуков, предоставляющих `openclaw.hooks` в `package.json`. Используйте `openclaw hooks` для фильтрации видимости хуков и включения отдельных хуков, а не для установки пакетов.

    Спецификации npm поддерживают **только реестр** (имя пакета и необязательная **точная версия** или **dist-тег**). Спецификации Git/URL/файлов и диапазоны semver отклоняются. Для безопасности зависимости устанавливаются в отдельном управляемом проекте npm для каждого плагина с `--ignore-scripts`, даже если в вашей оболочке настроены глобальные параметры установки npm. Управляемые проекты npm плагинов наследуют `overrides` уровня пакета npm из OpenClaw, поэтому ограничения безопасности хоста также применяются к поднятым зависимостям плагинов.

    Используйте `npm:<package>`, чтобы явно указать разрешение через npm. Во время перехода при запуске спецификации пакетов без префикса также устанавливаются непосредственно из npm, если они не соответствуют идентификатору официального плагина.

    Необработанные спецификации `@openclaw/*`, соответствующие встроенным плагинам, разрешаются во встроенную копию, принадлежащую образу, до перехода к npm. Например, `openclaw plugins install @openclaw/discord@2026.5.20 --pin` использует встроенный плагин Discord из текущей сборки OpenClaw вместо создания управляемого переопределения npm. Чтобы принудительно использовать внешний пакет npm, укажите `openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin`.

    Спецификации без префикса и `@latest` остаются в стабильном канале. Версии исправлений OpenClaw с датой, например `2026.5.3-1`, считаются стабильными при этой проверке. Если npm разрешает любую из этих форм в предварительную версию, OpenClaw останавливается и предлагает явно согласиться, указав тег предварительной версии (`@beta`/`@rc`) или точную предварительную версию (`@1.2.3-beta.4`).

    При установке из npm без точной версии (`npm:<package>` или `npm:<package>@latest`) OpenClaw перед установкой проверяет метаданные разрешённого пакета. Если последний стабильный пакет требует более новой версии API плагинов OpenClaw или более новой минимальной версии хоста, OpenClaw проверяет более ранние стабильные версии и устанавливает самый новый совместимый выпуск. Точные версии и явно указанные dist-теги обрабатываются строго: при выборе несовместимой версии операция завершается ошибкой с предложением обновить OpenClaw или выбрать совместимую версию.

    Если спецификация установки без префикса соответствует идентификатору официального плагина (например, `diffs`), OpenClaw устанавливает непосредственно запись каталога. Чтобы установить одноимённый пакет npm, используйте явную спецификацию с областью видимости (например, `@scope/diffs`).

  </Accordion>
  <Accordion title="Репозитории Git">
    Используйте `git:<repo>` для установки непосредственно из репозитория Git. Поддерживаемые формы: `git:github.com/owner/repo`, `git:owner/repo`, полный `https://`, `ssh://`, `git://`, `file://` и URL клонирования `git@host:owner/repo.git`. Добавьте `@<ref>` или `#<ref>`, чтобы перед установкой получить ветку, тег или коммит.

    При установке из Git репозиторий клонируется во временный каталог, при наличии запрошенной ссылки выполняется переход на неё, а затем используется обычный установщик плагинов из каталога. Поэтому проверка манифеста, операторская политика установки, установка через менеджер пакетов и записи об установке работают так же, как при установке из npm. Записанные установки из Git содержат URL и ссылку источника, а также разрешённый коммит, чтобы `openclaw plugins update` мог позднее повторно разрешить источник.

    После установки из Git используйте `openclaw plugins inspect <id> --runtime --json`, чтобы проверить регистрации в среде выполнения, например методы Gateway и команды CLI. Если плагин зарегистрировал корневую команду CLI через `api.registerCli`, запускайте её непосредственно через корневой CLI OpenClaw, например `openclaw demo-plugin ping`.

  </Accordion>
  <Accordion title="Архивы">
    Поддерживаемые архивы: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Нативные архивы плагинов OpenClaw должны содержать допустимый `openclaw.plugin.json` в корне извлечённого плагина; архивы, содержащие только `package.json`, отклоняются до записи сведений об установке в OpenClaw.

    Используйте `npm-pack:<path.tgz>`, если файл представляет собой tar-архив npm-pack и требуется
    тот же путь управляемого проекта npm для отдельного плагина, который используется при установке из реестра,
    включая проверку `package-lock.json`, сканирование поднятых зависимостей
    и записи установки npm. Обычные пути к архивам по-прежнему устанавливаются как локальные
    архивы в корне расширений плагинов.

    Также поддерживаются установки из маркетплейса Claude.

  </Accordion>
</AccordionGroup>

Для установок из ClawHub используется явный локатор `clawhub:<package>`:

```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```

Во время перехода при запуске безопасные для npm спецификации плагинов без префикса по умолчанию устанавливаются из npm, если они не соответствуют идентификатору официального плагина:

```bash
openclaw plugins install openclaw-codex-app-server
```

Используйте `npm:`, чтобы явно указать разрешение только через npm:

```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@openclaw/discord@2026.5.20
openclaw plugins install npm:@scope/plugin-name@1.0.1
```

Перед установкой OpenClaw проверяет заявленную совместимость API плагина и минимальной версии Gateway. Если выбранная версия ClawHub публикует артефакт ClawPack, OpenClaw скачивает версионированный npm-pack `.tgz`, проверяет заголовок дайджеста ClawHub и дайджест артефакта, а затем устанавливает его через обычный путь установки архива. Более старые версии ClawHub без метаданных ClawPack по-прежнему устанавливаются через устаревший путь проверки архива пакета. В записях установки сохраняются метаданные источника ClawHub, тип артефакта, целостность npm, контрольная сумма npm, имя tar-архива и сведения о дайджесте ClawPack для последующих обновлений.
Для установок ClawHub без версии сохраняется неверсионированная спецификация, чтобы `openclaw plugins update` мог отслеживать новые выпуски ClawHub; явно указанные селекторы версии или тега, например `clawhub:pkg@1.2.3` и `clawhub:pkg@beta`, остаются закреплёнными за этим селектором.

### Сокращённая запись маркетплейса

Используйте сокращённую запись `plugin@marketplace`, если имя маркетплейса присутствует в локальном кэше реестра Claude по адресу `~/.claude/plugins/known_marketplaces.json`:

```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```

Используйте `--marketplace`, чтобы явно передать источник маркетплейса:

```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```

<Tabs>
  <Tab title="Источники маркетплейса">
    - известное Claude имя маркетплейса из `~/.claude/plugins/known_marketplaces.json`
    - корень локального маркетплейса или путь `marketplace.json`
    - сокращённая запись репозитория GitHub, например `owner/repo`
    - URL репозитория GitHub, например `https://github.com/owner/repo`
    - URL Git

  </Tab>
  <Tab title="Правила удалённого маркетплейса">
    Для удалённых маркетплейсов, загруженных из GitHub или Git, записи плагинов должны оставаться внутри клонированного репозитория маркетплейса. OpenClaw принимает относительные пути к источникам из этого репозитория и отклоняет HTTP(S), абсолютные пути, Git, GitHub и другие источники плагинов, не являющиеся путями, из удалённых манифестов.
  </Tab>
</Tabs>

Для локальных путей и архивов OpenClaw автоматически определяет:

- нативные плагины OpenClaw (`openclaw.plugin.json`)
- пакеты, совместимые с Codex (`.codex-plugin/plugin.json`)
- пакеты, совместимые с Claude (`.claude-plugin/plugin.json`, либо стандартную структуру компонентов Claude при отсутствии этого файла манифеста)
- пакеты, совместимые с Cursor (`.cursor-plugin/plugin.json`)

Управляемые локальные установки должны представлять собой каталоги или архивы плагинов. Отдельные файлы плагинов `.js`,
`.mjs`, `.cjs` и `.ts` не копируются в управляемый корень
плагинов командой `plugins install` и не загружаются при непосредственном размещении в
`~/.openclaw/extensions` или `<workspace>/.openclaw/extensions`; эти
автоматически обнаруживаемые корни загружают каталоги пакетов или комплектов плагинов и пропускают
файлы скриптов верхнего уровня как локальные вспомогательные файлы. Вместо этого явно перечислите отдельные файлы в
`plugins.load.paths`.

<Note>
Совместимые пакеты устанавливаются в обычный корень плагинов и участвуют в том же процессе просмотра списка и сведений, включения и отключения. В настоящее время поддерживаются Skills пакетов, навыки-команды Claude, значения `settings.json` по умолчанию для Claude, значения `.lsp.json` / объявленные в манифесте значения `lspServers` по умолчанию для Claude, навыки-команды Cursor и каталоги хуков, совместимые с Codex; другие обнаруженные возможности пакетов отображаются в диагностике и сведениях, но пока не подключены к выполнению в среде выполнения.
</Note>

Используйте `-l`/`--link`, чтобы указать локальный каталог плагина без его копирования (добавляет
в `plugins.load.paths`):

```bash
openclaw plugins install -l ./my-plugin
```

`--link` не поддерживается при установках `--marketplace` или `git:` и
требует уже существующий локальный путь. Для неинтерактивного создания локальной ссылки
передайте `--force` после проверки источника; этот параметр подтверждает происхождение, но не
копирует и не перезаписывает связанный каталог.

<Note>
Плагины из рабочей области, обнаруженные в корне расширений рабочей области, не
импортируются и не выполняются до их явного включения. Для локальной разработки
запустите `openclaw plugins enable <plugin-id>` или задайте
`plugins.entries.<plugin-id>.enabled: true`; если в конфигурации используется
`plugins.allow`, также добавьте туда тот же идентификатор плагина. Это правило запрета по умолчанию
применяется и тогда, когда настройка канала явно указывает плагин из рабочей области для
загрузки только при настройке, поэтому код настройки локального плагина канала не будет выполняться, пока
этот плагин рабочей области остаётся отключённым или исключённым из списка разрешённых. Установки по ссылке
и явные записи `plugins.load.paths` следуют обычной политике для их
разрешённого источника плагина. См.
[Настройка политики плагинов](/ru/tools/plugin#configure-plugin-policy)
и [Справочник по конфигурации](/ru/gateway/configuration-reference#plugins).

Используйте `--pin` при установке из npm, чтобы сохранить разрешённую точную спецификацию (`name@version`) в управляемом индексе плагинов, сохранив при этом стандартное поведение без закрепления версии.
</Note>

## Список

```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
```

<ParamField path="--enabled" type="boolean">
  Показывать только включённые плагины.
</ParamField>
<ParamField path="--verbose" type="boolean">
  Переключиться с табличного представления на отдельные строки сведений о каждом плагине с метаданными формата, источника, происхождения, версии и активации.
</ParamField>
<ParamField path="--json" type="boolean">
  Машиночитаемый перечень, а также диагностика реестра и состояние установки зависимостей пакета.
</ParamField>

<Note>
`plugins list` сначала считывает сохранённый локальный реестр плагинов, а если реестр отсутствует или недействителен, использует резервный вариант, сформированный только на основе манифеста. Эта команда полезна для проверки того, установлен ли плагин, включён ли он и доступен ли при планировании холодного запуска, но она не выполняет оперативную проверку уже запущенного процесса Gateway. После изменения кода плагина, состояния его включения, политики хуков или `plugins.load.paths` перезапустите Gateway, обслуживающий канал, прежде чем ожидать выполнения нового кода или хуков `register(api)`. При удалённом развёртывании или развёртывании в контейнере убедитесь, что перезапускаете фактический дочерний процесс `openclaw gateway run`, а не только процесс-обёртку.

`plugins list --json` включает `dependencyStatus` каждого плагина из `package.json`
`dependencies` и `optionalDependencies`. OpenClaw проверяет наличие этих имён
пакетов в обычном пути поиска Node `node_modules` плагина; при этом
код среды выполнения плагина не импортируется, менеджер пакетов не запускается
и отсутствующие зависимости не восстанавливаются.
</Note>

Если при запуске в журнале появляется `plugins.allow is empty; discovered non-bundled plugins may auto-load: ...`,
выполните `openclaw plugins list --enabled --verbose` или
`openclaw plugins inspect <id>` с указанным идентификатором плагина, чтобы подтвердить
идентификаторы плагинов, и скопируйте доверенные идентификаторы в `plugins.allow` в `openclaw.json`. Если
предупреждение может перечислить все обнаруженные плагины, оно выводит готовый для вставки
фрагмент `plugins.allow`, уже содержащий эти идентификаторы. Если плагин загружается
без сведений о происхождении установки или пути загрузки, проверьте этот идентификатор плагина, а затем либо закрепите
доверенный идентификатор в `plugins.allow`, либо переустановите плагин из доверенного источника,
чтобы OpenClaw сохранил сведения о происхождении установки.

Для работы со встроенным плагином внутри упакованного образа Docker подключите исходный
каталог плагина как bind-монтирование поверх соответствующего пути к упакованным исходникам, например
`/app/extensions/synology-chat`. OpenClaw обнаруживает такое подключённое наложение исходников
раньше `/app/dist/extensions/synology-chat`; просто скопированный каталог исходников
остаётся неактивным, поэтому обычные упакованные установки продолжают использовать скомпилированный dist.

Для отладки хуков среды выполнения:

- `openclaw plugins inspect <id> --runtime --json` показывает зарегистрированные хуки и диагностику, полученные при проверке с загрузкой модуля. Проверка среды выполнения никогда не устанавливает зависимости; используйте `openclaw doctor --fix`, чтобы очистить устаревшее состояние зависимостей или восстановить отсутствующие загружаемые плагины, на которые ссылается конфигурация.
- `openclaw gateway status --deep --require-rpc` подтверждает доступные URL и профиль Gateway, сведения о службе и процессе, путь к конфигурации и работоспособность RPC.
- Невстроенным хукам диалогов (`llm_input`, `llm_output`, `before_model_resolve`, `before_agent_reply`, `before_agent_run`, `before_agent_finalize`, `agent_end`) требуется `plugins.entries.<id>.hooks.allowConversationAccess=true`.

### Индекс плагинов

Метаданные установки плагинов — это состояние, управляемое системой, а не пользовательская конфигурация. При установке и обновлении они записываются в общую базу данных состояния SQLite в активном каталоге состояния OpenClaw. Строка `installed_plugin_index` хранит постоянные метаданные `installRecords`, включая записи о повреждённых или отсутствующих манифестах плагинов, а также сформированный из манифестов кеш холодного реестра, используемый командами `openclaw plugins update`, удаления и диагностики, а также холодным реестром плагинов.

Когда OpenClaw обнаруживает в конфигурации поставлявшиеся устаревшие записи `plugins.installs`, среда выполнения рассматривает их как входные данные совместимости, не перезаписывая `openclaw.json`. Явные операции записи плагинов и `openclaw doctor --fix` перемещают эти записи в индекс плагинов и удаляют ключ конфигурации, если запись конфигурации разрешена; если любая из операций записи завершается сбоем, записи конфигурации сохраняются, чтобы метаданные установки не были потеряны.

## Удаление

```bash
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
openclaw plugins uninstall <id> --force
```

`uninstall` удаляет записи плагина из `plugins.entries`, сохранённого индекса плагинов, списков разрешённых и запрещённых плагинов, а также связанных записей `plugins.load.paths`, когда это применимо. Если не задан `--keep-files`, удаление также удаляет отслеживаемый каталог управляемой установки, но только если разрешённый путь находится внутри корневого каталога расширений плагинов OpenClaw. Если плагин в данный момент занимает слот `memory` или `contextEngine`, этот слот сбрасывается к значению по умолчанию (`memory-core` для памяти, `legacy` для движка контекста).

`uninstall` выводит предварительный список удаляемых элементов, а затем перед внесением изменений запрашивает `Uninstall plugin "<id>"?`. Передайте `--force`, чтобы пропустить запрос подтверждения (это удобно для скриптов и неинтерактивных запусков); без него для удаления требуется интерактивный TTY. `--dry-run` выводит тот же предварительный список и завершает работу без запроса подтверждения и внесения изменений.

<Note>
`--keep-config` поддерживается как устаревший псевдоним для `--keep-files`.
</Note>

## Обновление

```bash
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update @acme/demo
openclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-risk
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```

Обновления применяются к отслеживаемым установкам плагинов в управляемом индексе плагинов и отслеживаемым установкам пакетов хуков в `hooks.internal.installs`. Они повторно используют источник, уже выбранный пользователем при установке плагина, поэтому повторное подтверждение источника не требуется.

<AccordionGroup>
  <Accordion title="Разрешение идентификатора плагина и спецификации npm">
    При передаче идентификатора плагина OpenClaw повторно использует сохранённую спецификацию установки этого плагина. Это означает, что ранее сохранённые теги дистрибутива, такие как `@beta`, и точно закреплённые версии продолжают использоваться при последующих запусках `update <id>`.

    Во время `update <id> --dry-run` установки npm с точно закреплёнными версиями остаются закреплёнными. Если OpenClaw также может определить стандартную ветку пакета в реестре и она новее установленной закреплённой версии, пробный запуск сообщает о закреплении и выводит явную команду обновления пакета `@latest` для перехода на стандартную ветку реестра.

    Это правило целевого обновления отличается от пути массового обслуживания `openclaw plugins update --all`. Массовые обновления по-прежнему учитывают обычные отслеживаемые спецификации установки, но записи доверенных официальных плагинов OpenClaw могут синхронизироваться с текущей целевой версией официального каталога вместо сохранения устаревшего точного официального пакета. Используйте целевой `update <id>`, если намеренно хотите оставить точную или помеченную тегом официальную спецификацию без изменений.

    Для установок npm также можно передать явную спецификацию пакета npm с тегом дистрибутива или точной версией. OpenClaw сопоставляет имя пакета с отслеживаемой записью плагина, обновляет установленный плагин и сохраняет новую спецификацию npm для будущих обновлений по идентификатору.

    Передача имени пакета npm без версии или тега также сопоставляет его с отслеживаемой записью плагина. Используйте этот способ, если плагин был закреплён на точной версии и требуется вернуть его на стандартную ветку выпусков реестра.

  </Accordion>
  <Accordion title="Обновления бета-канала">
    Целевой `openclaw plugins update <id-or-npm-spec>` повторно использует отслеживаемую спецификацию плагина, если не передана новая спецификация. Массовый `openclaw plugins update --all` использует настроенный `update.channel` при синхронизации записей доверенных официальных плагинов с целевой версией официального каталога, поэтому установки из бета-канала могут оставаться в бета-ветке выпусков, а не незаметно приводиться к stable/latest.

    `openclaw update` также учитывает активный канал обновлений OpenClaw: в бета-канале записи плагинов npm и ClawHub со стандартной веткой сначала пытаются использовать `@beta`. Если бета-версия плагина отсутствует, они возвращаются к сохранённой спецификации default/latest; плагины npm также используют резервный вариант, если бета-пакет существует, но не проходит проверку установки. Об использовании резервного варианта сообщается предупреждением, и это не приводит к сбою обновления ядра. Точные версии и явно заданные теги при целевых обновлениях остаются закреплёнными за этим селектором.

  </Accordion>
  <Accordion title="Проверки версий и расхождение целостности">
    Перед фактическим обновлением npm OpenClaw сверяет версию установленного пакета с метаданными реестра npm. Если установленная версия и сохранённый идентификатор артефакта уже соответствуют разрешённой целевой версии, обновление пропускается без загрузки, переустановки или перезаписи `openclaw.json`.

    Если сохранён хеш целостности и хеш полученного артефакта изменился, OpenClaw расценивает это как изменение артефакта npm. Интерактивная команда `openclaw plugins update` выводит ожидаемый и фактический хеши и запрашивает подтверждение перед продолжением. Неинтерактивные средства обновления прекращают работу при такой ошибке, если вызывающая сторона не предоставляет явную политику продолжения.

  </Accordion>
  <Accordion title="--dangerously-force-unsafe-install при обновлении">
    `--dangerously-force-unsafe-install` также принимается командой `plugins update` для совместимости, но является устаревшим и больше не изменяет поведение обновления плагинов. Операторский `security.installPolicy` по-прежнему может блокировать обновления; хуки плагинов `before_install` применяются только в процессах, где загружены хуки плагинов.
  </Accordion>
  <Accordion title="--acknowledge-clawhub-risk при обновлении">
    Перед загрузкой заменяющего пакета обновления плагинов сообщества на основе ClawHub проходят ту же проверку доверия к конкретному выпуску, что и установки. Используйте `--acknowledge-clawhub-risk` для проверенной автоматизации, которая должна продолжать работу, когда для выбранного выпуска ClawHub отображается предупреждение о риске доверия. Официальные пакеты ClawHub и встроенные источники плагинов OpenClaw пропускают этот запрос подтверждения доверия к выпуску.
  </Accordion>
</AccordionGroup>

## Проверка

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

Проверка показывает идентификационные данные, состояние загрузки, источник, возможности манифеста, флаги политики, диагностику, метаданные установки, возможности пакета и обнаруженную поддержку серверов MCP или LSP, по умолчанию не импортируя код среды выполнения плагина. Вывод JSON содержит контракты манифеста плагина, такие как `contracts.agentToolResultMiddleware` и `contracts.trustedToolPolicies`, чтобы операторы могли проверить декларации доверенной поверхности перед включением или перезапуском плагина. Добавьте `--runtime`, чтобы загрузить модуль плагина и включить зарегистрированные хуки, инструменты, команды, службы, методы Gateway и маршруты HTTP. Проверка среды выполнения напрямую сообщает об отсутствующих зависимостях плагина; установка и восстановление выполняются командами `openclaw plugins install`, `openclaw plugins update` и `openclaw doctor --fix`.

Принадлежащие плагинам команды CLI обычно устанавливаются как корневые группы команд `openclaw`, но плагины также могут регистрировать вложенные команды под основной родительской командой, такой как `openclaw nodes`. После того как `inspect --runtime` покажет команду в `cliCommands`, запустите её по указанному пути; например, плагин, регистрирующий `demo-git`, можно проверить с помощью `openclaw demo-git ping`.

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

| Форма               | Значение                                                           |
| ------------------- | ----------------------------------------------------------------- |
| `plain-capability`  | ровно один тип возможности (например, плагин только для провайдера)         |
| `hybrid-capability` | более одного типа возможностей (например, текст + речь + изображения)       |
| `hook-only`         | только хуки, без возможностей, инструментов, команд, служб или маршрутов |
| `non-capability`    | инструменты/команды/службы, но без возможностей                       |

Дополнительные сведения о модели возможностей см. в разделе [Формы плагинов](/ru/plugins/architecture#plugin-shapes).

<Note>
Флаг `--json` выводит машиночитаемый отчёт, подходящий для использования в скриптах и аудита. `inspect --all` отображает общую для всего парка таблицу со столбцами формы, видов возможностей, уведомлений о совместимости, возможностей пакета и сводки хуков. `info` является псевдонимом для `inspect`.
</Note>

## Doctor

```bash
openclaw plugins doctor
```

`doctor` сообщает об ошибках загрузки плагинов, диагностике манифестов и обнаружения, уведомлениях о совместимости и устаревших ссылках в конфигурации плагинов, например на отсутствующие слоты плагинов. Когда дерево установки и конфигурация плагинов не содержат ошибок, выводится `No plugin issues detected.` Если устаревшая конфигурация сохраняется, но в остальном дерево установки исправно, это отражается в сводке без утверждения о полной исправности плагинов.

Если настроенный плагин присутствует на диске, но заблокирован проверками безопасности путей загрузчика, проверка конфигурации сохраняет запись плагина и сообщает о ней как `present but blocked`. Вместо удаления конфигурации `plugins.entries.<id>` или `plugins.allow` устраните указанную выше причину блокировки плагина, например неверного владельца пути или разрешений на запись для всех пользователей.

При ошибках структуры модуля, например отсутствии экспортов `register`/`activate`, повторите запуск с `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, чтобы включить в диагностический вывод компактную сводку структуры экспортов.

## Реестр

```bash
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json
```

Локальный реестр плагинов — это сохраняемая модель холодного чтения OpenClaw для идентификации установленных плагинов, состояния их включения, метаданных источников и принадлежности предоставляемых ими компонентов. Обычный запуск, поиск владельца провайдера, классификация настройки каналов и инвентаризация плагинов могут читать его без импорта модулей среды выполнения плагинов.

Используйте `plugins registry`, чтобы проверить, существует ли сохраняемый реестр, актуален ли он или устарел. Используйте `--refresh`, чтобы перестроить его на основе сохраняемого индекса плагинов, политики конфигурации и метаданных манифестов и пакетов. Это путь восстановления, а не активации среды выполнения.

`openclaw doctor --fix` также устраняет связанное с реестром рассогласование управляемых пакетов npm: если потерявший привязку или восстановленный пакет `@openclaw/*` в управляемом npm-проекте плагина либо в устаревшем плоском корне управляемых пакетов npm перекрывает встроенный плагин, doctor удаляет этот устаревший пакет и перестраивает реестр, чтобы при запуске выполнялась проверка по встроенному манифесту. Doctor также повторно связывает пакет хоста `openclaw` с управляемыми npm-плагинами, которые объявляют `peerDependencies.openclaw`, чтобы локальные для пакета импорты среды выполнения, такие как `openclaw/plugin-sdk/*`, разрешались после обновлений или восстановления npm.

<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — устаревший аварийный переключатель совместимости на случай ошибок чтения реестра. Предпочтительно использовать `plugins registry --refresh` или `openclaw doctor --fix`; резервный вариант через переменную окружения предназначен только для экстренного восстановления запуска на время развертывания миграции.
</Warning>

## Маркетплейс

```bash
openclaw plugins marketplace entries
openclaw plugins marketplace entries --offline
openclaw plugins marketplace entries --json
openclaw plugins marketplace entries --feed-profile <name>
openclaw plugins marketplace entries --feed-url <url>
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
openclaw plugins marketplace refresh
openclaw plugins marketplace refresh --feed-profile <name>
openclaw plugins marketplace refresh --feed-url <url>
openclaw plugins marketplace refresh --expected-sha256 <sha256> --json
```

`plugins marketplace entries` выводит записи из настроенного канала маркетплейса OpenClaw. По умолчанию команда пытается использовать размещенный канал и при неудаче обращается к последнему принятому снимку или встроенным данным. Используйте `--feed-profile <name>`, чтобы прочитать конкретный настроенный профиль, `--feed-url <url>` — чтобы прочитать явно указанный URL размещенного канала, а `--offline` — чтобы прочитать последний принятый снимок без получения канала.

`plugins marketplace refresh` обновляет настроенный снимок размещенного канала и сообщает, принял ли OpenClaw размещенные данные, снимок размещенного канала или встроенные резервные данные. Используйте `--expected-sha256`, когда вызывающей стороне требуется, чтобы команда завершалась ошибкой, если свежая размещенная полезная нагрузка не соответствует закрепленной контрольной сумме.

Команда маркетплейса `list` принимает локальный путь к маркетплейсу, путь `marketplace.json`, сокращенную запись GitHub, например `owner/repo`, URL репозитория GitHub или URL Git. `--json` выводит метку разрешенного источника, а также разобранный манифест маркетплейса и записи плагинов.

Обновление маркетплейса загружает размещенный канал маркетплейса OpenClaw и сохраняет
проверенный ответ как локальный снимок размещенного канала. Если параметры не указаны, используется
настроенный профиль канала по умолчанию. Используйте `--feed-profile <name>`, чтобы обновить
конкретный настроенный профиль, `--feed-url <url>` — чтобы обновить явно указанный URL
размещенного канала, `--expected-sha256 <sha256>` — чтобы потребовать совпадения контрольной суммы полезной нагрузки
(`sha256:<hex>` или 64-символьного шестнадцатеричного хеша без префикса), а `--json` — для
машиночитаемого вывода. Явно указанные URL размещенных каналов не должны содержать
учетные данные, строки запроса или фрагменты. При обновлении без закрепленной контрольной суммы команда может сообщить
о результате со снимком размещенного канала или встроенными резервными данными, не завершаясь ошибкой. Обновления
с закрепленной контрольной суммой завершаются ошибкой, если не принята свежая размещенная полезная нагрузка, а успешные
обновления размещенных данных завершаются ошибкой, если OpenClaw не может сохранить проверенный снимок.

## См. также

- [Создание плагинов](/ru/plugins/building-plugins)
- [Справочник CLI](/ru/cli)
- [ClawHub](/ru/clawhub)