Внутреннее устройство Plugin

Это подробный архитектурный справочник по системе плагинов OpenClaw. Для практических руководств начните с одной из специализированных страниц ниже.

Публичная модель возможностей

Возможности — это публичная модель нативных плагинов внутри OpenClaw. Каждый нативный плагин OpenClaw регистрируется для одного или нескольких типов возможностей:

Позиция по внешней совместимости

Модель возможностей уже включена в ядро и сегодня используется встроенными/нативными плагинами, но совместимость внешних плагинов всё еще требует более строгого критерия, чем «это экспортируется, значит, это заморожено».

Регистрация возможностей — предполагаемое направление развития. Устаревшие хуки остаются самым безопасным путем без поломок для внешних плагинов в переходный период. Не все экспортируемые вспомогательные подпути равнозначны — предпочитайте узкие документированные контракты случайным вспомогательным экспортам.

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

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

Используйте openclaw plugins inspect <id>, чтобы увидеть форму плагина и разбивку его возможностей. Подробности см. в справочнике CLI.

Устаревшие хуки

Хук before_agent_start остается поддерживаемым как путь совместимости для плагинов только с хуками. Устаревшие реальные плагины всё еще зависят от него.

Направление:

• поддерживать его работоспособность
• документировать его как устаревший
• предпочитать before_model_resolve для работы с переопределением модели/поставщика
• предпочитать before_prompt_build для работы с изменением промпта
• удалять только после снижения реального использования и подтверждения безопасности миграции покрытием фикстур

Сигналы совместимости

При запуске openclaw doctor или openclaw plugins inspect <id> вы можете увидеть одну из этих меток:

Ни hook-only, ни before_agent_start сегодня не сломают ваш плагин: hook-only носит рекомендательный характер, а before_agent_start только вызывает предупреждение. Эти сигналы также появляются в openclaw status --all и openclaw plugins doctor.

Обзор архитектуры

Система плагинов OpenClaw состоит из четырех уровней:

Именно для CLI плагинов обнаружение корневых команд разделено на две фазы:

• метаданные времени разбора поступают из registerCli(..., { descriptors: [...] })
• настоящий модуль CLI плагина может оставаться ленивым и регистрироваться при первом вызове

Это удерживает CLI-код, принадлежащий плагину, внутри плагина, но при этом позволяет OpenClaw резервировать имена корневых команд до разбора.

Важная граница проектирования:

• проверка манифеста/конфигурации должна работать на основе метаданных манифеста/схемы без выполнения кода плагина
• обнаружение нативных возможностей может загружать доверенный входной код плагина, чтобы построить неактивирующий снимок реестра
• нативное runtime-поведение поступает из пути register(api) модуля плагина с api.registrationMode === "full"

Такое разделение позволяет OpenClaw проверять конфигурацию, объяснять отсутствующие/отключенные плагины и строить подсказки UI/схемы до активации полного runtime.

Снимок метаданных плагинов и таблица поиска

При запуске Gateway строит один PluginMetadataSnapshot для текущего снимка конфигурации. Снимок содержит только метаданные: он хранит индекс установленных плагинов, реестр манифестов, диагностику манифестов, карты владельцев, нормализатор id плагинов и записи манифестов. Он не содержит загруженные модули плагинов, SDK поставщиков, содержимое пакетов или runtime-экспорты.

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

После запуска Gateway хранит текущий снимок метаданных как заменяемый runtime-продукт. Повторное runtime-обнаружение поставщиков может заимствовать этот снимок вместо реконструкции установленного индекса и реестра манифестов для каждого прохода каталога поставщиков. Снимок очищается или заменяется при завершении работы Gateway, изменениях конфигурации/инвентаря плагинов и записях установленного индекса; вызывающие стороны возвращаются к холодному пути манифеста/индекса, когда совместимого текущего снимка нет. Проверки совместимости должны включать корни обнаружения плагинов, такие как plugins.load.paths, и рабочую область агента по умолчанию, потому что плагины рабочей области входят в область метаданных.

Снимок и таблица поиска удерживают повторяющиеся решения запуска на быстром пути:

• владение каналом
• отложенный запуск канала
• id плагинов запуска
• владение поставщиком и бэкендом CLI
• владение поставщиком настройки, псевдонимом команды, поставщиком каталога моделей и контрактом манифеста
• проверка схемы конфигурации плагина и схемы конфигурации канала
• решения автоматического включения при запуске

Граница безопасности — замена снимка, а не мутация. Перестраивайте снимок при изменениях конфигурации, инвентаря плагинов, записей установки или политики сохраненного индекса. Не рассматривайте его как широкий изменяемый глобальный реестр и не храните неограниченные исторические снимки. Runtime-загрузка плагинов остается отдельной от снимков метаданных, чтобы устаревшее runtime-состояние нельзя было скрыть за кешем метаданных.

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

Некоторые вызывающие стороны холодного пути всё еще реконструируют реестры манифестов напрямую из сохраненного индекса установленных плагинов вместо получения PluginLookUpTable от Gateway. Теперь этот путь реконструирует реестр по требованию; предпочитайте передавать текущую таблицу поиска или явный реестр манифестов через runtime-потоки, когда вызывающая сторона уже располагает одним из них.

Планирование активации

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

Планировщик сохраняет совместимость с текущим поведением манифестов:

• поля activation.* являются явными подсказками планировщику
• providers, channels, commandAliases, setup.providers, contracts.tools и хуки остаются резервным механизмом владения на уровне манифеста
• API планировщика только с идентификаторами остается доступным для существующих вызывающих сторон
• API плана сообщает метки причин, чтобы диагностика могла отличать явные подсказки от резервного механизма владения

Канальные плагины и общий инструмент сообщений

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

Текущая граница такова:

• ядро владеет хостом общего инструмента message, подключением промпта, учетом сессий/тредов и диспетчеризацией выполнения
• канальные плагины владеют обнаружением действий в области видимости, обнаружением возможностей и любыми специфичными для канала фрагментами схемы
• канальные плагины владеют грамматикой разговоров сессий, специфичной для провайдера, например тем, как идентификаторы разговоров кодируют идентификаторы тредов или наследуются от родительских разговоров
• канальные плагины выполняют итоговое действие через свой адаптер действий

Для канальных плагинов поверхность SDK — ChannelMessageActionAdapter.describeMessageTool(...). Этот унифицированный вызов обнаружения позволяет плагину вернуть видимые действия, возможности и вклады в схему вместе, чтобы эти части не расходились.

Когда специфичный для канала параметр инструмента сообщений несет медиаисточник, например локальный путь или удаленный URL медиа, плагин также должен вернуть mediaSourceParams из describeMessageTool(...). Ядро использует этот явный список, чтобы применять нормализацию путей песочницы и подсказки для исходящего доступа к медиа без жестко заданных имен параметров, принадлежащих плагину. Предпочитайте там карты в области действия, а не один плоский список на весь канал, чтобы параметр медиа только для профиля не нормализовался в несвязанных действиях вроде send.

Ядро передает область видимости времени выполнения в этот шаг обнаружения. Важные поля включают:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• доверенный входящий requesterSenderId

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

Именно поэтому изменения маршрутизации встроенного раннера все еще являются работой плагина: раннер отвечает за передачу текущей идентичности чата/сессии в границу обнаружения плагина, чтобы общий инструмент message показывал правильную поверхность, принадлежащую каналу, для текущего хода.

Для принадлежащих каналу вспомогательных средств выполнения встроенные плагины должны держать среду выполнения внутри собственных модулей расширения. Ядро больше не владеет средами выполнения действий сообщений Discord, Slack, Telegram или WhatsApp в src/agents/tools. Мы не публикуем отдельные подпути plugin-sdk/*-action-runtime, и встроенные плагины должны импортировать собственный локальный код среды выполнения напрямую из модулей, принадлежащих их расширению.

Та же граница в целом применяется к именованным по провайдерам швам SDK: ядро не должно импортировать специфичные для канала вспомогательные баррели для Slack, Discord, Signal, WhatsApp или похожих расширений. Если ядру нужно поведение, оно должно либо использовать собственный баррель встроенного плагина api.ts / runtime-api.ts, либо продвинуть потребность в узкую универсальную возможность в общем SDK.

Встроенные плагины следуют тому же правилу. runtime-api.ts встроенного плагина не должен реэкспортировать собственный брендированный фасад openclaw/plugin-sdk/<plugin-id>. Эти брендированные фасады остаются совместимыми прокладками для внешних плагинов и старых потребителей, но встроенные плагины должны использовать локальные экспорты плюс узкие универсальные подпути SDK, такие как openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store или openclaw/plugin-sdk/webhook-ingress. Новый код не должен добавлять специфичные для идентификатора плагина фасады SDK, если этого не требует граница совместимости для существующей внешней экосистемы.

Для опросов конкретно есть два пути выполнения:

• outbound.sendPoll — общий базовый вариант для каналов, которые подходят под общую модель опросов
• actions.handleAction("poll") — предпочтительный путь для специфичной для канала семантики опросов или дополнительных параметров опроса

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

См. Внутреннее устройство архитектуры Plugin для полной последовательности запуска.

Модель владения возможностями

OpenClaw рассматривает нативный плагин как границу владения для компании или функции, а не как набор несвязанных интеграций.

Это означает:

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

Предполагаемое конечное состояние:

• OpenAI живет в одном плагине, даже если он охватывает текстовые модели, речь, изображения и будущее видео
• другой поставщик может сделать то же самое для собственной области поверхности
• каналам не важно, какой плагин поставщика владеет провайдером; они используют общий контракт возможности, предоставляемый ядром

Ключевое различие:

• плагин = граница владения
• возможность = контракт ядра, который несколько плагинов могут реализовывать или использовать

Поэтому если OpenClaw добавляет новый домен, например видео, первый вопрос не в том, «какой провайдер должен жестко закодировать обработку видео?» Первый вопрос: «каков базовый контракт возможности видео?» Когда этот контракт появляется, плагины поставщиков могут регистрироваться на него, а канальные/функциональные плагины — использовать его.

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

Это сохраняет явное владение и при этом избегает поведения ядра, зависящего от одного поставщика или разового специфичного для плагина пути кода.

Слоение возможностей

Используйте эту ментальную модель при решении, где должен находиться код:

Например, TTS следует этой форме:

• ядро владеет политикой TTS во время ответа, порядком резервирования, предпочтениями и доставкой канала
• openai, elevenlabs и microsoft владеют реализациями синтеза
• voice-call использует вспомогательное средство среды выполнения TTS для телефонии

Тот же шаблон следует предпочитать для будущих возможностей.

Пример плагина компании с несколькими возможностями

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

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          provider: "exampleai",          model: req.model,          input: req.input,        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          provider: "exampleai",          model: req.model,          input: req.input,        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

Важны не точные имена вспомогательных средств. Важна форма:

• один плагин владеет поверхностью поставщика
• ядро по-прежнему владеет контрактами возможностей
• каналы и функциональные плагины используют вспомогательные средства api.runtime.*, а не код поставщика
• контрактные тесты могут утверждать, что плагин зарегистрировал возможности, которыми заявляет, что владеет

Пример возможности: понимание видео

OpenClaw уже рассматривает понимание изображений/аудио/видео как одну общую возможность. Там применяется та же модель владения:

Это позволяет не встраивать предположения о видео одного провайдера в ядро. Плагин владеет поверхностью поставщика; ядро владеет контрактом возможности и резервным поведением.

Генерация видео уже использует ту же последовательность: ядро владеет типизированным контрактом возможности и вспомогательным средством среды выполнения, а плагины поставщиков регистрируют реализации api.registerVideoGenerationProvider(...) для него.

Нужен конкретный контрольный список внедрения? См. Кулинарную книгу возможностей.

Контракты и принудительное соблюдение

Поверхность API плагинов намеренно типизирована и централизована в OpenClawPluginApi. Этот контракт определяет поддерживаемые точки регистрации и вспомогательные средства среды выполнения, на которые может полагаться плагин.

Почему это важно:

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

Есть два уровня принудительного соблюдения:

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

Что входит в контракт

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

Модель выполнения

Нативные плагины OpenClaw выполняются внутри процесса вместе с Gateway. Они не изолированы в песочнице. Загруженный нативный плагин имеет ту же границу доверия на уровне процесса, что и код ядра.

Совместимые пакеты по умолчанию безопаснее, потому что OpenClaw сейчас рассматривает их как пакеты метаданных/контента. В текущих выпусках это в основном означает встроенные Skills.

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

Для имен встроенных пакетов рабочей области сохраняйте привязку идентификатора плагина к имени npm: @openclaw/<id> по умолчанию или утвержденный типизированный суффикс, например -provider, -plugin, -speech, -sandbox или -media-understanding, когда пакет намеренно предоставляет более узкую роль плагина.

Граница экспорта

OpenClaw экспортирует возможности, а не удобства реализации.

Сохраняйте регистрацию возможностей публичной. Убирайте вспомогательные экспорты, не являющиеся контрактами:

• вспомогательные подпути, специфичные для встроенного плагина
• подпути runtime-инфраструктуры, не предназначенные как публичный API
• вспомогательные функции для удобства, специфичные для поставщика
• вспомогательные функции настройки/онбординга, являющиеся деталями реализации

Зарезервированные вспомогательные подпути встроенных плагинов были удалены из сгенерированной карты экспортов SDK. Держите вспомогательные функции, специфичные для владельца, внутри пакета владеющего плагина; продвигайте только переиспользуемое поведение хоста в общие контракты SDK, такие как plugin-sdk/gateway-runtime, plugin-sdk/security-runtime и plugin-sdk/plugin-config-runtime.

Внутреннее устройство и справка

Сведения о конвейере загрузки, модели реестра, runtime-хуках провайдеров, HTTP-маршрутах Gateway, схемах инструментов сообщений, разрешении целей каналов, каталогах провайдеров, плагинах движка контекста и руководстве по добавлению новой возможности см. в Внутреннее устройство архитектуры плагинов.

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

• Создание плагинов
• Манифест плагина
• Настройка Plugin SDK