OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugins

Плагины

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

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

Требования

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

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

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

    Найдите общедоступные пакеты плагинов в ClawHub:

    bash
    openclaw plugins search "calendar"

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

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

    bash
    # Из 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

    Относитесь к установке плагинов как к запуску кода. Для воспроизводимой установки в рабочей среде предпочитайте фиксированные версии.

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

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

    bash
    openclaw plugins enable <plugin-id>

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

  • Дождитесь перезагрузки Gateway

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

    bash
    openclaw gateway restart

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

  • Проверьте регистрацию в среде выполнения

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

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

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

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

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

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

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

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

    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, если хотите удалить устаревшие идентификаторы.
    • 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.json выполните openclaw plugins list --enabled --verbose или openclaw plugins inspect <id> для указанного идентификатора плагина. Такая же фиксация доверия применяется, когда диагностика сообщает, что плагин загрузился without install/load-path provenance: проверьте этот идентификатор плагина, затем закрепите его в plugins.allow или переустановите из доверенного источника, чтобы OpenClaw записал происхождение установки.

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

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

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

    Формат Как загружается Когда использовать
    Нативный плагин OpenClaw openclaw.plugin.json и модуль среды выполнения, загружаемый в процесс Вы устанавливаете или создаёте возможности среды выполнения специально для OpenClaw
    Совместимый пакет Структура плагина Codex, Claude или Cursor, сопоставленная с перечнем плагинов 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 импортировал тот же код плагина.

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

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

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

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

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

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

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

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

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

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

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

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

    bash
    openclaw config set logging.level traceopenclaw logs --follow

    Найдите:

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

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

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

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

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

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

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

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

    Was this useful?
    On this page

    On this page