Plugin - OpenClaw

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

Требования

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

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

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

Найдите плагин

Ищите публичные пакеты плагинов в ClawHub:

openclaw plugins search "calendar"

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

Установите плагин

# 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

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

Настройте и включите его

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

openclaw plugins enable <plugin-id>

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

Дайте Gateway перезагрузиться

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

openclaw gateway restart

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

Проверьте регистрацию в runtime

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

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

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

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

Источник	Используйте, когда	Пример
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. Для установок из 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.

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

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

{
  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 или openclaw plugins inspect <id> с указанным 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 плагинов, а создание нативных плагинов — в Создании плагинов.

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

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

Используйте типизированные хуки через api.on(...) для хуков жизненного цикла runtime. Это предпочтительная поверхность для middleware, политики, переписывания сообщений, формирования prompt и управления инструментами.
Используйте api.registerHook(...) только когда хотите участвовать во внутренней системе хуков, описанной в Хуках. Это в основном нужно для грубых побочных эффектов команд/жизненного цикла и совместимости с существующей автоматизацией в стиле 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 выглядит установленным, но живой трафик чата его не использует:

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, чтобы понять, является ли он встроенным, официальным внешним или доступным только из исходного кода	Установите внешний пакет, включите встроенный 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:

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

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

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

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

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

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

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

Ищите:

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

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

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

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

См. также

Управление Plugin - примеры команд для просмотра списка, установки, обновления, удаления и публикации
openclaw plugins - полный справочник CLI
Инвентарь Plugin - сгенерированный список встроенных и внешних Plugin
Справочник Plugin - сгенерированные справочные страницы по каждому Plugin
Сообщественные Plugin - обнаружение ClawHub и политика PR для документации
Разрешение зависимостей Plugin - корни установки, записи реестра и границы времени выполнения
Создание Plugin - руководство по созданию нативных Plugin
Обзор Plugin SDK - runtime-регистрация, хуки и поля API
Манифест Plugin - манифест и метаданные пакета

​Требования

​Быстрый старт

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

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

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

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

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

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

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

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

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

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

​См. также