Skip to main content
Справочник по упаковке плагинов (метаданные package.json), манифестам (openclaw.plugin.json), точкам входа настройки и схемам конфигурации.
Ищете пошаговое руководство? Практические руководства рассматривают упаковку в контексте: Плагины каналов и Плагины провайдеров.

Метаданные пакета

Вашему package.json требуется поле openclaw, которое сообщает системе плагинов, какие возможности предоставляет ваш плагин:
Для внешней публикации в ClawHub требуются compat и build. Канонические примеры команд публикации находятся в docs/snippets/plugin-publish/.

Поля openclaw

string[]
Файлы точек входа (относительно корня пакета). Допустимые исходные точки входа для разработки в рабочей области и Git-репозитории.
string[]
Собранные аналоги на JavaScript для extensions, которым отдаётся предпочтение, когда OpenClaw загружает установленный npm-пакет. Порядок разрешения исходных и собранных файлов описан в разделе Точки входа SDK.
string
Облегчённая точка входа только для настройки (необязательно).
string
Собранный аналог на JavaScript для setupEntry. Также требуется задать setupEntry.
object
Резервные идентификационные данные плагина { id, label }, используемые, когда у плагина нет метаданных канала или провайдера, из которых можно получить идентификатор или название.
object
Метаданные каталога каналов для настройки, средства выбора, быстрого старта и отображения состояния.
object
Параметры установки: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.
object
Флаги поведения при запуске.
object
Диапазон версий pluginApi, поддерживаемый этим плагином. Обязателен для внешних публикаций в ClawHub.
Идентификаторы провайдеров (providers: string[]) относятся к метаданным манифеста, а не пакета. Объявляйте их в openclaw.plugin.json, а не здесь — см. раздел Манифест плагина.

openclaw.channel

openclaw.channel — это легковесные метаданные пакета для обнаружения каналов и интерфейсов настройки до загрузки среды выполнения. Пример:
exposure поддерживает:
  • configured: включать канал в интерфейсы списков настроенных каналов и состояния
  • setup: включать канал в интерактивные средства выбора при настройке и конфигурировании
  • docs: помечать канал как общедоступный в документации и интерфейсах навигации
showConfigured и showInSetup по-прежнему поддерживаются как устаревшие псевдонимы. Предпочтительно использовать exposure.

openclaw.install

openclaw.install относится к метаданным пакета, а не манифеста.
Интерактивная первоначальная настройка использует openclaw.install для интерфейсов установки по требованию: если ваш плагин предоставляет варианты аутентификации провайдера или метаданные настройки и каталога каналов до загрузки среды выполнения, первоначальная настройка может предложить установку из ClawHub, npm или локального источника, установить или включить плагин, а затем продолжить выбранный процесс. Варианты ClawHub используют clawhubSpec, и им отдаётся предпочтение при наличии; для вариантов npm требуются доверенные метаданные каталога со значением реестра npmSpec (точные версии и expectedIntegrity являются необязательными закреплениями, которые применяются при установке или обновлении, если заданы). Храните сведения о том, «что показывать», в openclaw.plugin.json, а о том, «как это установить», — в package.json.
Если задано minHostVersion, оно проверяется как при установке, так и при загрузке реестра манифестов для невстроенных плагинов. Более старые хосты пропускают внешние плагины; недопустимые строки версий отклоняются. Предполагается, что версии встроенных исходных плагинов совпадают с версией рабочей копии хоста.
Для установок npm с закреплённой версией укажите точную версию в npmSpec и добавьте ожидаемое значение целостности артефакта:
allowInvalidConfigRecovery не является универсальным способом обхода ошибок в конфигурации. Он предназначен только для узкого сценария восстановления встроенного плагина, позволяя переустановке или настройке исправлять известные последствия обновления, например отсутствующий путь к встроенному плагину или устаревшую запись channels.<id> для того же плагина. Если конфигурация нарушена по несвязанным причинам, установка всё равно завершается с запретом по умолчанию и предлагает оператору выполнить openclaw doctor --fix.

Отложенная полная загрузка

Плагины каналов могут включить отложенную загрузку с помощью:
Когда эта возможность включена, OpenClaw загружает только setupEntry на этапе запуска до начала прослушивания, даже для уже настроенных каналов. Полная точка входа загружается после того, как Gateway начинает прослушивание.
Включайте отложенную загрузку, только если ваш setupEntry регистрирует всё необходимое Gateway до начала прослушивания (регистрацию канала, HTTP-маршруты, методы Gateway). Если полная точка входа предоставляет обязательные возможности запуска, сохраняйте поведение по умолчанию.
Если ваша установочная/полная точка входа регистрирует RPC-методы Gateway, используйте для них префикс конкретного плагина. Зарезервированные пространства имён администрирования ядра (config.*, exec.approvals.*, wizard.*, update.*) остаются под управлением ядра и всегда нормализуются в operator.admin.

Манифест плагина

Каждый нативный плагин должен содержать openclaw.plugin.json в корне пакета. OpenClaw использует его для проверки конфигурации без выполнения кода плагина.
Для плагинов каналов добавьте channels (а для плагинов провайдеров — providers):
Даже плагины без конфигурации должны содержать схему. Допускается пустая схема:
Полное описание схемы см. в разделе Манифест плагина.

Публикация в ClawHub

Для пакетов Skills и плагинов используются разные команды публикации в ClawHub. Для пакетов плагинов используйте специальную команду пакета:
clawhub skill publish <path> — это другая команда, предназначенная для публикации папки навыка, а не пакета плагина. См. раздел Публикация в ClawHub.

Установочная точка входа

setup-entry.ts — облегчённая альтернатива index.ts, которую OpenClaw загружает, когда требуются только установочные поверхности (первоначальная настройка, исправление конфигурации, проверка отключённого канала):
Это позволяет не загружать тяжёлый код среды выполнения (криптографические библиотеки, регистрации CLI, фоновые службы) во время процессов установки. Встроенные каналы рабочей области, хранящие безопасные для установки экспорты во вспомогательных модулях, могут использовать defineBundledChannelSetupEntry(...) из openclaw/plugin-sdk/channel-entry-contract вместо defineSetupPluginEntry(...). Этот контракт для встроенных компонентов также поддерживает необязательный экспорт runtime, благодаря чему связывание среды выполнения на этапе установки остаётся облегчённым и явным.
  • Канал отключён, но ему требуются поверхности установки/первоначальной настройки.
  • Канал включён, но не настроен.
  • Включена отложенная загрузка (deferConfiguredChannelFullLoadUntilAfterListen).
  • Объект плагина канала (через defineSetupPluginEntry).
  • Все HTTP-маршруты, необходимые до начала прослушивания Gateway.
  • Все методы Gateway, необходимые во время запуска.
Эти методы Gateway, необходимые при запуске, всё равно не должны использовать зарезервированные пространства имён администрирования ядра, такие как config.* или update.*.
  • Регистрации CLI.
  • Фоновые службы.
  • Тяжёлые импорты среды выполнения (криптографию, SDK).
  • Методы Gateway, необходимые только после запуска.

Узкие импорты вспомогательных функций установки

Для часто вызываемых путей, используемых только при установке, предпочитайте узкие интерфейсы вспомогательных функций установки более широкому универсальному интерфейсу plugin-sdk/setup, если вам нужна только часть установочной поверхности: Используйте более широкий интерфейс plugin-sdk/setup, когда требуется полный общий набор инструментов установки, включая вспомогательные функции изменения конфигурации, такие как moveSingleAccountChannelSectionToDefaultAccount(...). Используйте createSetupTranslator(...) для фиксированных текстов мастера установки. Он учитывает локаль мастера CLI (OPENCLAW_LOCALE, затем системные переменные локали) и при невозможности её определить использует английский язык. Храните текст установки, относящийся к конкретному плагину, в коде этого плагина, а общие ключи каталога используйте только для общих меток установки, текста состояния и установочных текстов официальных встроенных плагинов. Импорт адаптеров изменений установки остаётся безопасным для часто вызываемых путей. Поиск поверхности контракта повышения встроенной конфигурации с одной учётной записью выполняется лениво, поэтому импорт plugin-sdk/setup-runtime не приводит к немедленной загрузке механизма обнаружения поверхности встроенного контракта до фактического использования адаптера.

Управляемое каналом повышение конфигурации с одной учётной записью

Когда канал переходит от конфигурации одной учётной записи верхнего уровня к channels.<id>.accounts.*, общее поведение по умолчанию перемещает повышаемые значения, относящиеся к учётной записи, в accounts.default. Встроенные каналы могут сузить или переопределить это повышение через свою поверхность установочного контракта:
  • singleAccountKeysToMove: дополнительные ключи верхнего уровня, которые следует переместить в повышаемую учётную запись
  • namedAccountPromotionKeys: если именованные учётные записи уже существуют, в повышаемую учётную запись перемещаются только эти ключи; общие ключи политики/доставки остаются в корне канала
  • resolveSingleAccountPromotionTarget(...): выбор существующей учётной записи, которая получит повышаемые значения
Matrix — текущий встроенный пример. Если уже существует ровно одна именованная учётная запись Matrix или если defaultAccount указывает на существующий неканонический ключ, такой как Ops, повышение сохраняет эту учётную запись вместо создания новой записи accounts.default.

Схема конфигурации

Конфигурация плагина проверяется по JSON Schema из вашего манифеста. Пользователи настраивают плагины следующим образом:
При регистрации ваш плагин получает эту конфигурацию как api.pluginConfig. Для конфигурации конкретного канала используйте вместо этого раздел конфигурации канала:

Создание схем конфигурации каналов

Используйте buildChannelConfigSchema, чтобы преобразовать схему Zod в обёртку ChannelConfigSchema, используемую артефактами конфигурации, принадлежащими плагину:
Если контракт уже описан в JSON Schema или TypeBox, используйте прямую вспомогательную функцию, чтобы OpenClaw мог пропустить преобразование Zod в JSON Schema на путях обработки метаданных:
Для сторонних плагинов контрактом для редко вызываемых путей по-прежнему служит манифест плагина: скопируйте созданную JSON Schema в openclaw.plugin.json#channelConfigs, чтобы поверхности конфигурации, установки и пользовательского интерфейса могли проверять channels.<id> без загрузки кода среды выполнения.

Мастера установки

Плагины каналов могут предоставлять интерактивные мастера установки для openclaw onboard. Мастер представляет собой объект ChannelSetupWizard в ChannelPlugin:
ChannelSetupWizard также поддерживает textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize и другие возможности. Полный пример встроенного плагина см. в src/setup-core.ts плагина Discord.
Для запросов списка разрешённых отправителей личных сообщений, которым требуется только стандартный процесс note -> prompt -> parse -> merge -> patch, предпочитайте общие вспомогательные функции установки из openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) и createNestedChannelParsedAllowFromPrompt(...).
Для блоков состояния установки канала, различающихся только метками, оценками и необязательными дополнительными строками, предпочитайте createStandardChannelSetupStatus(...) из openclaw/plugin-sdk/setup вместо ручного создания одного и того же объекта status в каждом плагине.
Для необязательных установочных поверхностей, которые должны отображаться только в определённых контекстах, используйте createOptionalChannelSetupSurface из openclaw/plugin-sdk/channel-setup:
plugin-sdk/channel-setup также предоставляет низкоуровневые конструкторы createOptionalChannelSetupAdapter(...) и createOptionalChannelSetupWizard(...), когда вам нужна только одна часть этой поверхности опциональной установки.Сгенерированные опциональные адаптер и мастер запрещают реальные записи конфигурации при ошибке. Они повторно используют одно сообщение о необходимости установки в validateInput, applyAccountConfig и finalize и добавляют ссылку на документацию, когда задано docsPath.
Для интерфейсов настройки на основе исполняемых файлов предпочитайте общие вспомогательные средства делегирования вместо копирования одинаковой связующей логики для исполняемых файлов и состояния в каждый канал:
  • createDetectedBinaryStatus(...) для блоков состояния, различающихся только метками, подсказками, оценками и обнаружением исполняемого файла
  • createCliPathTextInput(...) для текстовых полей ввода на основе пути
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) и createDelegatedResolveConfigured(...), когда setupEntry должен лениво перенаправлять управление более ресурсоёмкому полному мастеру
  • createDelegatedTextInputShouldPrompt(...), когда setupEntry должен только делегировать решение textInputs[*].shouldPrompt

Публикация и установка

Внешние плагины: опубликуйте в ClawHub, затем установите:
Простые спецификации пакетов устанавливаются из npm во время перехода при запуске, если имя не совпадает с идентификатором встроенного или официального плагина; в этом случае OpenClaw вместо этого использует соответствующую локальную или официальную копию. Для детерминированного выбора источника используйте clawhub:, npm:, git: или npm-pack: — см. Управление плагинами.
Плагины в репозитории: размещайте их в дереве рабочего пространства встроенных плагинов; они автоматически обнаруживаются во время сборки.
Для установок из npm openclaw plugins install устанавливает пакет в отдельный проект плагина в ~/.openclaw/npm/projects с отключёнными сценариями жизненного цикла (--ignore-scripts). Используйте для деревьев зависимостей плагинов только JS/TS и избегайте пакетов, требующих сборок postinstall.
При запуске Gateway зависимости плагинов не устанавливаются. За согласование зависимостей отвечают процессы установки из npm, git и ClawHub; зависимости локальных плагинов должны быть установлены заранее.
Метаданные встроенных пакетов задаются явно, а не выводятся из собранного JavaScript при запуске Gateway. Зависимости среды выполнения должны находиться в пакете плагина, которому они принадлежат; запуск упакованного OpenClaw никогда не восстанавливает и не зеркалирует зависимости плагинов.

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