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

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

Установка и использование плагинов

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

Создание плагинов

Руководство по созданию первого плагина с минимальным рабочим манифестом.

Плагины каналов

Создание плагина канала обмена сообщениями.

Плагины провайдеров

Создание плагина провайдера моделей.

Обзор SDK

Справочник по карте импорта и 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 <id>, чтобы просмотреть форму плагина и состав его возможностей. Подробнее см. в справочнике по CLI.

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

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

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

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

openclaw doctor, openclaw plugins inspect <id>, 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
принадлежность провайдера настройки, псевдонима команды, провайдера каталога моделей и контракта манифеста
проверка схемы конфигурации плагина и схемы конфигурации канала
решения об автоматическом включении при запуске

Границей безопасности является замена снимка, а не его изменение. Перестраивайте снимок при изменении конфигурации, состава плагинов, записей об установке или сохраняемой политики индекса. Не рассматривайте его как обширный изменяемый глобальный реестр и не храните неограниченное количество исторических снимков. Загрузка плагинов среды выполнения остаётся отделённой от снимков метаданных, чтобы устаревшее состояние среды выполнения нельзя было скрыть за кешем метаданных. Правило кеширования описано во внутреннем устройстве архитектуры плагинов: метаданные манифеста и обнаружения актуальны, если только вызывающий код не хранит явный снимок, таблицу поиска или реестр манифестов для текущего процесса. Скрытые кеши метаданных и 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/<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
плагин функции обычно должен владеть всей поверхностью вводимой им функции
каналы должны использовать общие возможности ядра вместо ситуативной повторной реализации поведения провайдера

Несколько возможностей поставщика

google отвечает за генерацию текста, серверную часть CLI, эмбеддинги, речь, голосовую связь в реальном времени, анализ медиафайлов, генерацию изображений, музыки и видео, а также веб-поиск. openai отвечает за генерацию текста, эмбеддинги, речь, транскрипцию в реальном времени, голосовую связь в реальном времени, анализ медиафайлов, генерацию изображений и видео. minimax отвечает за генерацию текста, а также анализ медиафайлов, речь, генерацию изображений, музыки и видео и веб-поиск.

Одна возможность поставщика

arcee и chutes отвечают только за генерацию текста; microsoft отвечает только за речь. Плагин поставщика может оставаться настолько узким, пока ему не потребуется охватить больше поверхностей этого поставщика.

Плагин функции

voice-call отвечает за транспорт вызовов, инструменты, CLI, маршруты и сопряжение с медиапотоками Twilio, но использует общие возможности речи, транскрипции в реальном времени и голосовой связи в реальном времени вместо прямого импорта плагинов поставщиков.

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

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

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

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

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

Определите возможность

Определить недостающую возможность в ядре.

Предоставьте через SDK

Предоставить её типизированным способом через API и среду выполнения плагинов.

Подключите потребителей

Подключить каналы и функции к этой возможности.

Реализации поставщиков

Позволить плагинам поставщиков регистрировать реализации.

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

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

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

Уровень возможностей ядра
Уровень плагина поставщика
Уровень плагина канала или функции

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

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

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

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

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

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

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(...). Нужен конкретный контрольный список внедрения? См. Руководство по возможностям.

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

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

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

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

Контроль регистрации во время выполнения

Реестр плагинов проверяет регистрации по мере загрузки плагинов. Например, дублирующиеся идентификаторы провайдеров, дублирующиеся идентификаторы провайдеров синтеза речи и некорректные регистрации приводят к диагностическим сообщениям плагина вместо неопределённого поведения.

Контрактные тесты

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

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

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

Хорошие контракты
Плохие контракты

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

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

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

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

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

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

Совместимые пакеты по умолчанию безопаснее, поскольку OpenClaw сейчас рассматривает их как пакеты метаданных и содержимого. В текущих выпусках это в основном означает встроенные навыки. Для невстроенных плагинов используйте списки разрешений и явные пути установки и загрузки. Рассматривайте плагины рабочей области как код для разработки, а не как настройки по умолчанию для рабочей среды. Для имён встроенных пакетов рабочей области сохраняйте привязку идентификатора плагина к имени npm: по умолчанию @openclaw/<id> или утверждённый типизированный суффикс, например -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, схемах инструментов сообщений, разрешении целей каналов, каталогах провайдеров, плагинах контекстного движка и руководстве по добавлению новой возможности см. в разделе Внутренняя архитектура плагинов.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

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

Установка и использование плагинов

Создание плагинов

Плагины каналов

Плагины провайдеров

Обзор SDK

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

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

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

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

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

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

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

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

Плагины каналов и общий инструмент сообщений

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

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

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

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

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

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

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

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

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

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

Установка и использование плагинов

Создание плагинов

Плагины каналов

Плагины провайдеров

Обзор SDK

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

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

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

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

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

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

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

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

​Плагины каналов и общий инструмент сообщений

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Плагины каналов и общий инструмент сообщений

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

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

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

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

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

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

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

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

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

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