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

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

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

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

Подход к внешней совместимости

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

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

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

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

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

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

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

Направление развития:

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

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

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all и openclaw plugins doctor отображают следующие уведомления о совместимости:

Ни один из информационных или предупреждающих сигналов сейчас не нарушает работу вашего плагина. Эти сигналы также отображаются в openclaw status --all и openclaw plugins doctor.

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

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

В частности, обнаружение корневых команд CLI плагинов разделено на два этапа:

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

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

Важная архитектурная граница:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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: ядро не должно импортировать специфичные для канала вспомогательные агрегирующие модули для Discord, Signal, Slack, 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") — предпочтительный путь для специфичной для канала семантики опросов или дополнительных параметров опроса

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

Полную последовательность запуска см. в разделе Внутреннее устройство архитектуры плагинов.

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

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

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

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

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

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

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

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

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

Если возможность ещё не существует, обычно следует:

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

Уровни возможностей

При определении места для кода используйте следующую мысленную модель:

Например, TTS соответствует этой структуре:

• ядро отвечает за политику TTS при ответе, порядок резервных механизмов, настройки и доставку в канал
• elevenlabs, google, microsoft и openai отвечают за реализации синтеза
• 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",      // хуки аутентификации, каталога моделей и среды выполнения    });     api.registerSpeechProvider({      id: "exampleai",      // конфигурация речи поставщика — реализуйте интерфейс SpeechProviderPlugin напрямую    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // логика учётных данных и получения данных      }),    );  },}; export default plugin;

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

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

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

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

Это позволяет не встраивать в ядро предположения одного провайдера о видео. Плагин отвечает за интерфейс поставщика, а ядро — за контракт возможностей и резервное поведение.

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

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

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

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

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

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

Предусмотрено два уровня контроля:

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

Что должно входить в контракт

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

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

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

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

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

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

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

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

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

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

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

Внутреннее устройство и справочные материалы

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

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

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