package.json), манифестам (openclaw.plugin.json), точкам входа настройки и схемам конфигурации.
Метаданные пакета
Вашемуpackage.json требуется поле openclaw, которое сообщает системе плагинов, какие возможности предоставляет ваш плагин:
- Плагин канала
- Плагин провайдера / базовая конфигурация ClawHub
Для внешней публикации в 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
Проверка minHostVersion
Если задано
minHostVersion, оно проверяется как при установке, так и при загрузке реестра манифестов для невстроенных плагинов. Более старые хосты пропускают внешние плагины; недопустимые строки версий отклоняются. Предполагается, что версии встроенных исходных плагинов совпадают с версией рабочей копии хоста.Установки npm с закреплённой версией
Установки npm с закреплённой версией
Для установок npm с закреплённой версией укажите точную версию в
npmSpec и добавьте ожидаемое значение целостности артефакта:Область действия allowInvalidConfigRecovery
Область действия allowInvalidConfigRecovery
allowInvalidConfigRecovery не является универсальным способом обхода ошибок в конфигурации. Он предназначен только для узкого сценария восстановления встроенного плагина, позволяя переустановке или настройке исправлять известные последствия обновления, например отсутствующий путь к встроенному плагину или устаревшую запись channels.<id> для того же плагина. Если конфигурация нарушена по несвязанным причинам, установка всё равно завершается с запретом по умолчанию и предлагает оператору выполнить openclaw doctor --fix.Отложенная полная загрузка
Плагины каналов могут включить отложенную загрузку с помощью:setupEntry на этапе запуска до начала прослушивания, даже для уже настроенных каналов. Полная точка входа загружается после того, как 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 загружает, когда требуются только установочные поверхности (первоначальная настройка, исправление конфигурации, проверка отключённого канала):
defineBundledChannelSetupEntry(...) из openclaw/plugin-sdk/channel-entry-contract вместо defineSetupPluginEntry(...). Этот контракт для встроенных компонентов также поддерживает необязательный экспорт runtime, благодаря чему связывание среды выполнения на этапе установки остаётся облегчённым и явным.
Когда OpenClaw использует setupEntry вместо полной точки входа
Когда OpenClaw использует setupEntry вместо полной точки входа
- Канал отключён, но ему требуются поверхности установки/первоначальной настройки.
- Канал включён, но не настроен.
- Включена отложенная загрузка (
deferConfiguredChannelFullLoadUntilAfterListen).
Что должен регистрировать setupEntry
Что должен регистрировать setupEntry
- Объект плагина канала (через
defineSetupPluginEntry). - Все HTTP-маршруты, необходимые до начала прослушивания Gateway.
- Все методы Gateway, необходимые во время запуска.
config.* или update.*.Что setupEntry НЕ должен включать
Что setupEntry НЕ должен включать
- Регистрации 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, используемую артефактами конфигурации, принадлежащими плагину:
openclaw.plugin.json#channelConfigs, чтобы поверхности конфигурации, установки и пользовательского интерфейса могли проверять channels.<id> без загрузки кода среды выполнения.
Мастера установки
Плагины каналов могут предоставлять интерактивные мастера установки дляopenclaw onboard. Мастер представляет собой объект ChannelSetupWizard в ChannelPlugin:
ChannelSetupWizard также поддерживает textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize и другие возможности. Полный пример встроенного плагина см. в src/setup-core.ts плагина Discord.
Общие запросы allowFrom
Общие запросы allowFrom
Для запросов списка разрешённых отправителей личных сообщений, которым требуется только стандартный процесс
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
- Только ClawHub
- Спецификация пакета npm
clawhub:, npm:, git: или npm-pack: — см. Управление плагинами.Для установок из npm
openclaw plugins install устанавливает пакет в отдельный проект плагина в ~/.openclaw/npm/projects с отключёнными сценариями жизненного цикла (--ignore-scripts). Используйте для деревьев зависимостей плагинов только JS/TS и избегайте пакетов, требующих сборок postinstall.При запуске Gateway зависимости плагинов не устанавливаются. За согласование зависимостей отвечают процессы установки из npm, git и ClawHub; зависимости локальных плагинов должны быть установлены заранее.
Связанные материалы
- Создание плагинов — пошаговое руководство по началу работы
- Манифест плагина — полный справочник по схеме манифеста
- Точки входа SDK —
definePluginEntryиdefineChannelPluginEntry