Плагины

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

На этой странице описано, как установить плагин, перезапустить Gateway, проверить, что среда выполнения загрузила его, и устранить распространённые ошибки настройки. Примеры только с командами см. в разделе Управление плагинами. Сгенерированный перечень встроенных, официальных внешних и доступных только в исходном коде плагинов см. в разделе Перечень плагинов.

Требования

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

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

openclaw plugins search "calendar"

# Из ClawHub.openclaw plugins install clawhub:<package> # Из npm.openclaw plugins install npm:<package> # Из git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # Из локальной копии исходного кода для разработки.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

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

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

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

Спецификации пакетов без префикса обрабатываются особым образом для совместимости: имя без префикса, которое соответствует идентификатору встроенного плагина, использует этот встроенный источник; имя без префикса, которое соответствует идентификатору официального внешнего плагина, использует официальный каталог пакетов; любая другая спецификация без префикса во время переходного периода запуска устанавливается через npm. Необработанные спецификации @openclaw/*, соответствующие встроенным плагинам, также разрешаются во встроенную копию до перехода к npm. Используйте npm:@openclaw/<plugin>@<version>, чтобы намеренно установить внешний пакет npm вместо встроенной копии. Для детерминированного выбора источника используйте clawhub:, npm:, git: или npm-pack:. Полный контракт команды см. в разделе openclaw plugins.

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

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

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

Общую схему выполнения security.installPolicy, используемую навыками и плагинами, см. в разделе Конфигурация 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, если хотите удалить устаревшие идентификаторы.
• plugins.deny имеет приоритет над списком разрешений и включением отдельных плагинов.
• plugins.allow — исключительный список разрешений. Инструменты, принадлежащие плагинам и отсутствующие в списке разрешений, остаются недоступными, даже если tools.allow содержит "*".
• plugins.entries.<id>.enabled: false отключает один плагин, сохраняя его конфигурацию.
• plugins.load.paths добавляет явно указанные локальные файлы или каталоги плагинов. Управляемые локальные пути plugins install должны указывать на каталоги или архивы плагинов; для отдельных файлов плагинов используйте plugins.load.paths.
• Плагины из рабочей области по умолчанию отключены; явно включите их или добавьте в список разрешений перед использованием локального кода рабочей области.
• Встроенные плагины следуют встроенным метаданным о включении или отключении по умолчанию, если конфигурация явно не переопределяет их.
• plugins.slots.<slot> (memory или contextEngine) выбирает один плагин для исключительной категории. Выбор слота считается явной активацией и принудительно включает выбранный плагин для этого слота, даже если в других условиях его нужно было бы включить вручную. plugins.deny и plugins.entries.<id>.enabled: false по-прежнему блокируют его.
• Встроенные плагины с ручным включением могут активироваться автоматически, когда в конфигурации указана одна из принадлежащих им поверхностей, например ссылка на провайдера/модель, конфигурация канала, серверная часть CLI или среда выполнения агента.
• Маршрутизация Codex семейства OpenAI сохраняет раздельные границы провайдера и плагина среды выполнения: устаревшие ссылки на модели Codex являются устаревшей конфигурацией, которую исправляет doctor, а встроенный плагин codex управляет средой выполнения сервера приложений Codex для канонических ссылок на агентов openai/*, явного agentRuntime.id: "codex" и устаревших ссылок codex/*.

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

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

Форматы плагинов

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

Оба формата отображаются в openclaw plugins list, openclaw plugins inspect, openclaw plugins enable и openclaw plugins disable. Границы совместимости пакетов см. в разделе Пакеты плагинов, а сведения о создании нативных плагинов — в разделе Создание плагинов.

Перехватчики плагинов

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

• Типизированные перехватчики api.on(...) для событий жизненного цикла среды выполнения. Это предпочтительный интерфейс для промежуточного ПО, политик, перезаписи сообщений, формирования запросов и управления инструментами.
• 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 импортировал тот же код плагина.

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

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openclaw config set logging.level traceopenclaw logs --follow

Найдите:

[trace:plugin-tools] длительность работы фабрик ...

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

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

Если один плагин занимает основную часть времени, проверьте его регистрации в среде выполнения:

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

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

Сведения о корневых каталогах зависимостей, проверке метаданных пакетов, записях реестра, перезагрузке при запуске и удалении устаревших данных см. в разделе Разрешение зависимостей плагинов.

Связанные материалы

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