--- read_when: - Создание или отладка нативных плагинов OpenClaw - Понимание модели возможностей плагинов и границ ответственности - Работа над конвейером загрузки плагинов или реестром - Реализация хуков среды выполнения провайдера или плагинов каналов sidebarTitle: Internals summary: 'Внутреннее устройство плагинов: модель возможностей, владение, контракты, конвейер загрузки и вспомогательные средства среды выполнения' title: Внутреннее устройство плагина x-i18n: generated_at: "2026-07-13T18:26:22Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 07ab077080285b5b7a93f58f71cd00be62cfd79cdc2cfa40f0e64cc91cc5ac46 source_path: plugins/architecture.md workflow: 16 --- Это **подробное справочное описание архитектуры** системы плагинов OpenClaw. Практическое изучение начните с одной из тематических страниц ниже. Руководство для конечных пользователей по добавлению, включению и устранению неполадок плагинов. Руководство по созданию первого плагина с минимальным рабочим манифестом. Создание плагина канала обмена сообщениями. Создание плагина провайдера моделей. Справочник по карте импорта и API регистрации. ## Публичная модель возможностей Возможности — это публичная модель **нативных плагинов** в OpenClaw. Каждый нативный плагин OpenClaw регистрирует один или несколько типов возможностей: | Возможность | Метод регистрации | Примеры плагинов | | ----------------------------- | ------------------------------------------------ | ---------------------------------- | | Генерация текста | `api.registerProvider(...)` | `anthropic`, `openai` | | Серверная часть CLI-генерации | `api.registerCliBackend(...)` | `anthropic`, `openai` | | Эмбеддинги | `api.registerEmbeddingProvider(...)` | Векторные плагины провайдеров | | Речь | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Транскрибирование в реальном времени | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | Голосовая связь в реальном времени | `api.registerRealtimeVoiceProvider(...)` | `google`, `openai` | | Анализ медиаданных | `api.registerMediaUnderstandingProvider(...)` | `google`, `openai` | | Источник транскрипций | `api.registerTranscriptSourceProvider(...)` | `discord` | | Генерация изображений | `api.registerImageGenerationProvider(...)` | `fal`, `google`, `openai` | | Генерация музыки | `api.registerMusicGenerationProvider(...)` | `fal`, `google`, `minimax` | | Генерация видео | `api.registerVideoGenerationProvider(...)` | `fal`, `google`, `qwen` | | Получение веб-ресурсов | `api.registerWebFetchProvider(...)` | `firecrawl` | | Веб-поиск | `api.registerWebSearchProvider(...)` | `brave`, `firecrawl`, `google` | | Канал / обмен сообщениями | `api.registerChannel(...)` | `matrix`, `msteams` | | Обнаружение Gateway | `api.registerGatewayDiscoveryService(...)` | `bonjour` | Плагин, который не регистрирует ни одной возможности, но предоставляет хуки, инструменты, службы обнаружения или фоновые службы, является **устаревшим плагином только с хуками**. Этот шаблон по-прежнему полностью поддерживается. ### Подход к внешней совместимости Модель возможностей уже внедрена в ядро и используется встроенными и нативными плагинами, однако для совместимости внешних плагинов требуется более строгий критерий, чем «экспортировано — значит зафиксировано». | Ситуация с плагином | Рекомендация | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Существующие внешние плагины | Сохраняйте работоспособность интеграций на основе хуков; это базовый уровень совместимости. | | Новые встроенные и нативные плагины | Предпочитайте явную регистрацию возможностей обращениям к внутренним компонентам конкретного поставщика или новым архитектурам только с хуками. | | Внешние плагины, внедряющие регистрацию возможностей | Допускается, но считайте специализированные вспомогательные интерфейсы возможностей развивающимися, если документация не помечает их как стабильные. | Регистрация возможностей — целевое направление развития. Во время перехода устаревшие хуки остаются наиболее безопасным для внешних плагинов способом избежать поломок. Не все экспортируемые вспомогательные подпути равноценны — предпочитайте узкие документированные контракты случайным вспомогательным экспортам. ### Формы плагинов OpenClaw классифицирует каждый загруженный плагин по форме на основании его фактического поведения при регистрации, а не только статических метаданных: Регистрирует ровно один тип возможностей (например, плагин только для провайдера, такой как `arcee` или `chutes`). Регистрирует несколько типов возможностей (например, `openai` отвечает за генерацию текста, речь, анализ медиаданных и генерацию изображений). Регистрирует только хуки (типизированные или пользовательские), без возможностей, инструментов, команд или служб. Регистрирует инструменты, команды, службы или маршруты, но не возможности. Используйте `openclaw plugins inspect `, чтобы просмотреть форму плагина и состав его возможностей. Подробнее см. в [справочнике по CLI](/ru/cli/plugins#inspect). ### Устаревшие хуки Хук `before_agent_start` продолжает поддерживаться как путь совместимости для плагинов только с хуками. От него по-прежнему зависят устаревшие плагины, используемые на практике. Направление развития: - сохранять его работоспособность - документировать его как устаревший - предпочитать `before_model_resolve` для переопределения модели или провайдера - предпочитать `before_prompt_build` для изменения промптов - удалять только после снижения реального использования и подтверждения безопасности миграции покрытием фикстурами ### Сигналы совместимости `openclaw doctor`, `openclaw plugins inspect `, `openclaw status --all` и `openclaw plugins doctor` отображают следующие уведомления о совместимости: | Сигнал | Значение | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | **конфигурация допустима** | Конфигурация успешно разбирается, а плагины разрешаются | | **только хуки** (информация) | Плагин регистрирует только хуки; этот путь поддерживается, но ещё не переведён на регистрацию возможностей | | **устаревший `before_agent_start`** (предупреждение) | Плагин использует устаревший хук `before_agent_start` вместо `before_model_resolve`/`before_prompt_build` | | **устаревший API эмбеддингов памяти** (предупреждение) | Невстроенный плагин использует старый API провайдера эмбеддингов для памяти вместо `registerEmbeddingProvider` | | **критическая ошибка** | Конфигурация недопустима или не удалось загрузить плагин | Ни один из информационных или предупреждающих сигналов сейчас не нарушает работу вашего плагина. Эти сигналы также отображаются в `openclaw status --all` и `openclaw plugins doctor`. ## Обзор архитектуры Система плагинов OpenClaw состоит из четырёх уровней: OpenClaw находит плагины-кандидаты по настроенным путям, корням рабочих пространств, глобальным корням плагинов и среди встроенных плагинов. При обнаружении сначала считываются нативные манифесты `openclaw.plugin.json` и поддерживаемые манифесты пакетов. Ядро определяет, включён ли обнаруженный плагин, отключён, заблокирован или выбран для эксклюзивной позиции, например памяти. Нативные плагины OpenClaw загружаются внутри процесса и регистрируют возможности в центральном реестре. Упакованный JavaScript загружается через нативный `require`; локальный исходный код сторонних плагинов на TypeScript использует Jiti как аварийный резервный вариант. Совместимые пакеты нормализуются в записи реестра без импорта кода среды выполнения. Остальная часть OpenClaw считывает реестр, чтобы предоставлять инструменты, каналы, настройку провайдеров, хуки, HTTP-маршруты, команды CLI и службы. В частности, обнаружение корневых команд CLI плагинов разделено на два этапа: - метаданные на этапе разбора поступают из `registerCli(..., { descriptors: [...] })` - фактический модуль CLI плагина может оставаться отложенным и регистрироваться при первом вызове Благодаря этому принадлежащий плагину код CLI остаётся внутри плагина, а OpenClaw всё равно может резервировать имена корневых команд до разбора. Важная архитектурная граница: - проверка манифеста и конфигурации должна выполняться по **метаданным манифеста и схемы** без выполнения кода плагина - обнаружение нативных возможностей может загружать код точки входа доверенного плагина для создания неактивирующего снимка реестра - нативное поведение среды выполнения определяется путём `register(api)` модуля плагина с `api.registrationMode === "full"` Такое разделение позволяет OpenClaw проверять конфигурацию, объяснять отсутствие или отключение плагинов и формировать подсказки для интерфейса и схемы до активации полной среды выполнения. ### Снимок метаданных плагинов и таблица поиска При запуске Gateway создаётся один `PluginMetadataSnapshot` для текущего снимка конфигурации. Снимок содержит только метаданные: индекс установленных плагинов, реестр манифестов, результаты диагностики манифестов, карты владельцев, нормализатор идентификаторов плагинов и записи манифестов. Он не содержит загруженные модули плагинов, SDK провайдеров, содержимое пакетов или экспорты среды выполнения. Проверка конфигурации с учётом плагинов, автоматическое включение при запуске и начальная загрузка плагинов Gateway используют этот снимок вместо независимого повторного построения метаданных манифестов и индекса. `PluginLookUpTable` формируется из того же снимка и дополняет его планом запуска плагинов для текущей конфигурации среды выполнения. После запуска Gateway хранит текущий снимок метаданных как заменяемый продукт среды выполнения. При повторном обнаружении провайдеров в среде выполнения этот снимок можно использовать вместо повторного построения индекса установленных компонентов и реестра манифестов при каждом проходе по каталогу провайдеров. Снимок очищается или заменяется при завершении работы Gateway, изменениях конфигурации или состава плагинов, а также при записи индекса установленных компонентов; если совместимого текущего снимка нет, вызывающий код возвращается к холодному пути манифеста и индекса. Проверки совместимости должны учитывать корни обнаружения плагинов, такие как `plugins.load.paths`, и рабочее пространство агента по умолчанию, поскольку плагины рабочего пространства входят в область метаданных. Снимок и таблица поиска обеспечивают быстрый путь для повторяющихся решений при запуске: - принадлежность каналов - отложенный запуск каналов - идентификаторы запускаемых плагинов - принадлежность провайдеров и серверных частей CLI - принадлежность провайдера настройки, псевдонима команды, провайдера каталога моделей и контракта манифеста - проверка схемы конфигурации плагина и схемы конфигурации канала - решения об автоматическом включении при запуске Границей безопасности является замена снимка, а не его изменение. Перестраивайте снимок при изменении конфигурации, состава плагинов, записей об установке или сохраняемой политики индекса. Не рассматривайте его как обширный изменяемый глобальный реестр и не храните неограниченное количество исторических снимков. Загрузка плагинов среды выполнения остаётся отделённой от снимков метаданных, чтобы устаревшее состояние среды выполнения нельзя было скрыть за кешем метаданных. Правило кеширования описано во [внутреннем устройстве архитектуры плагинов](/ru/plugins/architecture-internals#plugin-cache-boundary): метаданные манифеста и обнаружения актуальны, если только вызывающий код не хранит явный снимок, таблицу поиска или реестр манифестов для текущего процесса. Скрытые кеши метаданных и TTL на основе времени не являются частью загрузки плагинов. После фактической загрузки кода или установленных артефактов могут сохраняться только кеши загрузчика среды выполнения, модулей и артефактов зависимостей. Некоторые вызывающие стороны в редко используемых путях по-прежнему реконструируют реестры манифестов непосредственно из сохранённого индекса установленных плагинов вместо получения Gateway `PluginLookUpTable`. Теперь этот путь реконструирует реестр по требованию; если у вызывающей стороны уже есть текущая таблица поиска или явный реестр манифестов, предпочтительно передавать их через потоки выполнения. ### Планирование активации Планирование активации является частью плоскости управления. Вызывающие стороны могут до загрузки более широких реестров среды выполнения запросить, какие плагины относятся к конкретной команде, провайдеру, каналу, маршруту, среде агента или возможности. Планировщик сохраняет совместимость с текущим поведением манифеста: - `activation.*` — явные подсказки для планировщика - `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` и хуки остаются резервным механизмом определения принадлежности по манифесту - API планировщика, возвращающий только идентификаторы, остаётся доступным для существующих вызывающих сторон - API плана сообщает метки причин, чтобы диагностика могла отличать явные подсказки от резервного определения принадлежности Не рассматривайте `activation` как хук жизненного цикла или замену `register(...)`. Это метаданные, используемые для сужения загрузки. Если поля принадлежности уже описывают связь, отдавайте предпочтение им; используйте `activation` только для дополнительных подсказок планировщику. ### Плагины каналов и общий инструмент сообщений Плагинам каналов не требуется регистрировать отдельный инструмент отправки, редактирования или реакции для обычных действий чата. 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/`. Такие брендированные фасады остаются адаптерами совместимости для внешних плагинов и старых потребителей, однако встроенные плагины должны использовать локальные экспорты и узкие универсальные подпути SDK, такие как `openclaw/plugin-sdk/channel-policy`, `openclaw/plugin-sdk/runtime-store` или `openclaw/plugin-sdk/webhook-ingress`. Новый код не должен добавлять специфичные для идентификатора плагина фасады SDK, если этого не требует граница совместимости существующей внешней экосистемы. В частности, для опросов существуют два пути выполнения: - `outbound.sendPoll` — общая основа для каналов, соответствующих общей модели опросов - `actions.handleAction("poll")` — предпочтительный путь для специфичной для канала семантики опросов или дополнительных параметров опроса Теперь ядро откладывает общий разбор опроса до момента, когда диспетчеризация опроса плагином отклонит действие, поэтому принадлежащие плагину обработчики опросов могут принимать специфичные для канала поля опроса, не блокируясь сначала универсальным анализатором опросов. Полную последовательность запуска см. в разделе [Внутреннее устройство архитектуры плагинов](/ru/plugins/architecture-internals). ## Модель владения возможностями OpenClaw рассматривает нативный плагин как границу владения **компанией** или **функцией**, а не как набор несвязанных интеграций. Это означает: - плагин компании обычно должен владеть всеми поверхностями этой компании, обращёнными к OpenClaw - плагин функции обычно должен владеть всей поверхностью вводимой им функции - каналы должны использовать общие возможности ядра вместо ситуативной повторной реализации поведения провайдера `google` отвечает за генерацию текста, серверную часть CLI, эмбеддинги, речь, голосовую связь в реальном времени, анализ медиафайлов, генерацию изображений, музыки и видео, а также веб-поиск. `openai` отвечает за генерацию текста, эмбеддинги, речь, транскрипцию в реальном времени, голосовую связь в реальном времени, анализ медиафайлов, генерацию изображений и видео. `minimax` отвечает за генерацию текста, а также анализ медиафайлов, речь, генерацию изображений, музыки и видео и веб-поиск. `arcee` и `chutes` отвечают только за генерацию текста; `microsoft` отвечает только за речь. Плагин поставщика может оставаться настолько узким, пока ему не потребуется охватить больше поверхностей этого поставщика. `voice-call` отвечает за транспорт вызовов, инструменты, CLI, маршруты и сопряжение с медиапотоками Twilio, но использует общие возможности речи, транскрипции в реальном времени и голосовой связи в реальном времени вместо прямого импорта плагинов поставщиков. Предполагаемое конечное состояние: - поверхность поставщика, обращённая к OpenClaw, находится в одном плагине, даже если охватывает текстовые модели, речь, изображения и видео - другие поставщики могут делать то же самое для собственных областей - каналам неважно, какой плагин поставщика владеет провайдером; они используют общий контракт возможности, предоставляемый ядром Ключевое различие: - **плагин** = граница владения - **возможность** = контракт ядра, который могут реализовывать или использовать несколько плагинов Поэтому, если OpenClaw добавляет новую область, например видео, первый вопрос — не «какой провайдер должен содержать жёстко заданную обработку видео?». Первый вопрос — «каков контракт основной возможности работы с видео?». После появления этого контракта плагины поставщиков могут регистрироваться для него, а плагины каналов и функций — использовать его. Если возможность ещё не существует, обычно следует: Определить недостающую возможность в ядре. Предоставить её типизированным способом через API и среду выполнения плагинов. Подключить каналы и функции к этой возможности. Позволить плагинам поставщиков регистрировать реализации. Это сохраняет явные границы владения и одновременно предотвращает появление в ядре поведения, зависящего от одного поставщика или разового специфичного для плагина пути кода. ### Уровни возможностей При определении места для кода используйте следующую мысленную модель: Общая оркестрация, политики, резервные механизмы, правила объединения конфигурации, семантика доставки и типизированные контракты. Специфичные для поставщика API, аутентификация, каталоги моделей, синтез речи, генерация изображений, серверные части для видео и конечные точки учёта использования. Интеграция с Discord, Slack, голосовыми вызовами и другими поверхностями, которая использует возможности ядра и предоставляет их на соответствующей поверхности. Например, TTS соответствует этой структуре: - ядро отвечает за политику TTS при ответе, порядок резервных механизмов, настройки и доставку в канал - `elevenlabs`, `google`, `microsoft` и `openai` отвечают за реализации синтеза - `voice-call` использует вспомогательное средство среды выполнения телефонии TTS Этой же схеме следует отдавать предпочтение для будущих возможностей. ### Пример плагина компании с несколькими возможностями Плагин компании должен восприниматься извне как единое целое. Если OpenClaw предоставляет общие контракты для моделей, речи, транскрипции в реальном времени, голосовой связи в реальном времени, анализа медиафайлов, генерации изображений, генерации видео, получения веб-ресурсов и веб-поиска, поставщик может владеть всеми своими поверхностями в одном месте: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; import { describeImageWithModel, transcribeOpenAiCompatibleAudio, } from "openclaw/plugin-sdk/media-understanding"; import { createPluginBackedWebSearchProvider } from "openclaw/plugin-sdk/provider-web-search"; 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 уже рассматривает анализ изображений, аудио и видео как одну общую возможность. Та же модель владения применяется и здесь: Ядро определяет контракт анализа медиа. Плагины поставщиков регистрируют `describeImage`, `transcribeAudio` и `describeVideo`, когда это применимо. Каналы и функциональные плагины используют общее поведение ядра вместо прямого подключения к коду поставщика. Это позволяет не встраивать в ядро предположения одного провайдера о видео. Плагин отвечает за интерфейс поставщика, а ядро — за контракт возможностей и резервное поведение. Генерация видео уже использует ту же последовательность: ядро отвечает за типизированный контракт возможностей и вспомогательную функцию среды выполнения, а плагины поставщиков регистрируют в нём реализации `api.registerVideoGenerationProvider(...)`. Нужен конкретный контрольный список внедрения? См. [Руководство по возможностям](/ru/plugins/adding-capabilities). ## Контракты и контроль соблюдения Поверхность API плагинов намеренно типизирована и централизована в `OpenClawPluginApi`. Этот контракт определяет поддерживаемые точки регистрации и вспомогательные функции среды выполнения, на которые может полагаться плагин. Почему это важно: - авторы плагинов получают единый стабильный внутренний стандарт - ядро может отклонять дублирование владения, например регистрацию одного идентификатора провайдера двумя плагинами - при запуске могут выводиться действенные диагностические сообщения о некорректной регистрации - контрактные тесты могут проверять владение встроенными плагинами и предотвращать незаметное расхождение Предусмотрено два уровня контроля: Реестр плагинов проверяет регистрации по мере загрузки плагинов. Например, дублирующиеся идентификаторы провайдеров, дублирующиеся идентификаторы провайдеров синтеза речи и некорректные регистрации приводят к диагностическим сообщениям плагина вместо неопределённого поведения. Во время выполнения тестов встроенные плагины фиксируются в контрактных реестрах, чтобы OpenClaw мог явно проверять владение. Сейчас это используется для провайдеров моделей, провайдеров синтеза речи, провайдеров веб-поиска и владения встроенными регистрациями. На практике OpenClaw заранее знает, какой плагин отвечает за каждую поверхность. Благодаря этому ядро и каналы могут бесшовно взаимодействовать, поскольку владение объявлено, типизировано и доступно для тестирования, а не задано неявно. ### Что должно входить в контракт - типизированы - компактны - относятся к конкретной возможности - принадлежат ядру - могут повторно использоваться несколькими плагинами - могут использоваться каналами и функциями без знания о поставщике - специфичная для поставщика политика, скрытая в ядре - одноразовые обходные механизмы плагинов, минующие реестр - код канала, напрямую обращающийся к реализации поставщика - специальные объекты среды выполнения, не являющиеся частью `OpenClawPluginApi` или `api.runtime` В случае сомнений поднимите уровень абстракции: сначала определите возможность, а затем позвольте плагинам подключаться к ней. ## Модель выполнения Нативные плагины OpenClaw работают **внутри процесса** вместе с Gateway. Они не изолированы в песочнице. Загруженный нативный плагин находится в той же границе доверия на уровне процесса, что и код ядра. Последствия использования нативных плагинов: плагин может регистрировать инструменты, сетевые обработчики, перехватчики и службы; ошибка в плагине может вызвать сбой или нарушить стабильность Gateway; вредоносный нативный плагин эквивалентен выполнению произвольного кода внутри процесса OpenClaw. Совместимые пакеты по умолчанию безопаснее, поскольку OpenClaw сейчас рассматривает их как пакеты метаданных и содержимого. В текущих выпусках это в основном означает встроенные навыки. Для невстроенных плагинов используйте списки разрешений и явные пути установки и загрузки. Рассматривайте плагины рабочей области как код для разработки, а не как настройки по умолчанию для рабочей среды. Для имён встроенных пакетов рабочей области сохраняйте привязку идентификатора плагина к имени npm: по умолчанию `@openclaw/` или утверждённый типизированный суффикс, например `-provider`, `-plugin`, `-speech`, `-sandbox` или `-media-understanding`, если пакет намеренно предоставляет более узкую роль плагина. **Примечание о доверии:** `plugins.allow` доверяет **идентификаторам плагинов**, а не происхождению исходного кода. Если плагин рабочей области имеет тот же идентификатор, что и встроенный плагин, он намеренно замещает встроенную копию, когда этот плагин рабочей области включён или добавлен в список разрешений. Это нормальное и полезное поведение для локальной разработки, тестирования исправлений и срочных исправлений. Доверие к встроенному плагину определяется по снимку исходного кода — манифесту и коду на диске в момент загрузки, — а не по метаданным установки. Повреждённая или подменённая запись об установке не может незаметно расширить доверенную поверхность встроенного плагина за пределы заявленного фактическим исходным кодом. ## Граница экспорта OpenClaw экспортирует возможности, а не вспомогательные детали реализации. Оставляйте регистрацию возможностей общедоступной. Сокращайте экспорт вспомогательных элементов, не входящих в контракт: - вспомогательные подпути, специфичные для встроенных плагинов - подпути инфраструктуры среды выполнения, не предназначенные для использования как общедоступный API - специфичные для поставщика вспомогательные функции - вспомогательные функции настройки и первоначальной конфигурации, являющиеся деталями реализации Зарезервированные вспомогательные подпути встроенных плагинов удалены из создаваемой карты экспорта SDK. Храните вспомогательные функции конкретного владельца внутри пакета соответствующего плагина; переносите в общие контракты SDK только многократно используемое поведение хоста, например `plugin-sdk/gateway-runtime`, `plugin-sdk/security-runtime` и `plugin-sdk/plugin-config-runtime`. ## Внутреннее устройство и справочные материалы Сведения о конвейере загрузки, модели реестра, перехватчиках среды выполнения провайдера, HTTP-маршрутах Gateway, схемах инструментов сообщений, разрешении целей каналов, каталогах провайдеров, плагинах контекстного движка и руководстве по добавлению новой возможности см. в разделе [Внутренняя архитектура плагинов](/ru/plugins/architecture-internals). ## Связанные материалы - [Создание плагинов](/ru/plugins/building-plugins) - [Манифест плагина](/ru/plugins/manifest) - [Настройка SDK плагина](/ru/plugins/sdk-setup)