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

​

Конвейер загрузки

1. обнаруживает корневые каталоги потенциальных плагинов
2. читает нативные или совместимые манифесты пакетов и метаданные пакетов
3. отклоняет небезопасные кандидаты
4. нормализует конфигурацию плагинов (plugins.enabled, allow, deny, entries, slots, load.paths)
5. определяет, следует ли включить каждого кандидата
6. загружает включённые нативные модули: собранные встроенные модули используют нативный загрузчик; сторонний локальный исходный код TypeScript использует аварийный резервный механизм Jiti
7. вызывает нативные перехватчики register(api) и собирает регистрации в реестре плагинов
8. предоставляет реестр командам и поверхностям среды выполнения

• его разрешённая точка входа находится за пределами корня плагина
• его путь (или корневой каталог) доступен для записи всем пользователям
• для невстроенных плагинов владелец пути не соответствует текущему uid (или root)

​

Приоритет манифеста

• идентифицировать плагин
• обнаруживать объявленные каналы, Skills, схему конфигурации или возможности пакета
• проверять plugins.entries.<id>.config
• дополнять подписи и заполнители Control UI
• показывать метаданные установки и каталога
• сохранять недорогие дескрипторы активации и настройки без загрузки среды выполнения плагина

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

​

Граница кеширования плагинов

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

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

​

Модель реестра

• модуль плагина -> регистрация в реестре
• среда выполнения ядра -> использование реестра

​

Обратные вызовы привязки беседы

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Теперь для этого плагина и беседы существует привязка.
        console.log(event.binding?.conversationId);
        return;
      }

      // Запрос отклонён; очистите всё локальное состояние ожидания.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" или "denied"
• decision: "allow-once", "allow-always" или "deny"
• binding: разрешённая привязка для одобренных запросов
• request: исходная сводка запроса, подсказка отсоединения, идентификатор отправителя и метаданные беседы

​

Перехватчики среды выполнения провайдера

• Метаданные манифеста для быстрого и нетребовательного поиска до запуска: setup.providers[].envVars, устаревшая совместимость providerAuthEnvVars, providerAuthAliases, providerAuthChoices и channelEnvVars.
• Хуки этапа конфигурации: catalog (устаревший discovery), а также applyConfigDefaults.
• Хуки среды выполнения: более 40 необязательных хуков, охватывающих аутентификацию, разрешение моделей, обёртывание потоков, уровни рассуждений, политику повторного воспроизведения и конечные точки учёта использования. См. Порядок и использование хуков.

​

Порядок и использование хуков

​

Пример провайдера

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Встроенные примеры

​

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

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech возвращает стандартную полезную нагрузку результата TTS ядра для поверхностей файлов/голосовых заметок.
• Использует конфигурацию ядра messages.tts и выбор провайдера.
• Возвращает буфер аудио PCM и частоту дискретизации. Плагины должны передискретизировать/кодировать данные для провайдеров.
• listVoices является необязательным для каждого провайдера. Используйте его для принадлежащих поставщику средств выбора голоса или процессов настройки.
• Ядро передаёт рассчитанный крайний срок запроса в хуки провайдера listVoices; настройки тайм-аута конкретного провайдера могут его переопределить.
• Списки голосов могут содержать более подробные метаданные, такие как локаль, пол и теги характера, для средств выбора с учётом провайдера.
• OpenAI и ElevenLabs сейчас поддерживают телефонию. Microsoft — нет.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Сохраняйте политику TTS, резервный механизм и доставку ответов в ядре.
• Используйте провайдеров синтеза речи для принадлежащего поставщику поведения синтеза.
• Устаревший вход Microsoft edge нормализуется в идентификатор провайдера microsoft.
• Предпочтительная модель владения ориентирована на компанию: один плагин поставщика может управлять провайдерами текста, речи, изображений и будущих типов мультимедиа по мере добавления OpenClaw соответствующих контрактов возможностей.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Сохраняйте оркестрацию, резервный механизм, конфигурацию и подключение каналов в ядре.
• Сохраняйте поведение поставщика в плагине провайдера.
• Аддитивное расширение должно оставаться типизированным: новые необязательные методы, новые необязательные поля результатов, новые необязательные возможности.
• Генерация видео уже следует тому же шаблону:
  • ядро управляет контрактом возможностей и вспомогательным средством среды выполнения
  • плагины поставщиков регистрируют api.registerVideoGenerationProvider(...)
  • плагины функций/каналов используют api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* — предпочтительная общая поверхность для анализа изображений/аудио/видео.
• extractStructuredWithModel(...) — доступный плагинам интерфейс для ограниченного извлечения, принадлежащего провайдеру и ориентированного прежде всего на изображения. Включайте хотя бы один вход изображения; текстовые входы служат дополнительным контекстом. Продуктовые плагины управляют своими маршрутами и схемами, а OpenClaw — границей провайдера и среды выполнения.
• Использует аудиоконфигурацию анализа мультимедиа ядра (tools.media.audio) и порядок резервного выбора провайдеров.
• Возвращает { text: undefined }, если результат транскрибирования не создан (например, вход пропущен/не поддерживается).
• api.runtime.stt.transcribeAudioFile(...) сохраняется как псевдоним совместимости.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider и model — необязательные переопределения для отдельного выполнения, а не постоянные изменения сеанса.
• OpenClaw учитывает эти поля переопределения только для доверенных вызывающих сторон.
• Для принадлежащих плагину резервных выполнений операторы должны явно включить их с помощью plugins.entries.<id>.subagent.allowModelOverride: true.
• Используйте plugins.entries.<id>.subagent.allowedModels, чтобы ограничить доверенные плагины конкретными каноническими целями provider/model, либо "*", чтобы явно разрешить любую цель.
• Выполнения подагентов недоверенных плагинов по-прежнему работают, но запросы на переопределение отклоняются вместо неявного перехода к резервному варианту.
• Сеансы подагентов, созданные плагином, помечаются идентификатором создавшего их плагина. Резервный механизм api.runtime.subagent.deleteSession(...) может удалять только эти принадлежащие ему сеансы; для удаления произвольных сеансов по-прежнему требуется запрос к Gateway с областью администратора.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Сохраняйте выбор провайдера, разрешение учётных данных и общую семантику запросов в ядре.
• Используйте провайдеров веб-поиска для специфичных для поставщика транспортов поиска.
• api.runtime.webSearch.* — предпочтительная общая поверхность для плагинов функций/каналов, которым требуется поведение поиска без зависимости от оболочки инструмента агента.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): создать изображение с помощью настроенной цепочки провайдеров генерации изображений.
• listProviders(...): вывести список доступных провайдеров генерации изображений и их возможностей.

​

HTTP-маршруты Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: путь маршрута на HTTP-сервере Gateway.
• auth: обязательное поле, "gateway" или "plugin". Используйте "gateway", чтобы требовать обычную аутентификацию Gateway, или "plugin" для управляемой плагином аутентификации либо проверки Webhook.
• match: необязательное поле. "exact" (по умолчанию) или "prefix".
• handleUpgrade: необязательный обработчик запросов обновления соединения до WebSocket на том же маршруте.
• replaceExisting: необязательное поле. Позволяет тому же плагину заменить собственную существующую регистрацию маршрута.
• handler: верните true, если маршрут обработал запрос.

• api.registerHttpHandler(...) удалён и вызовет ошибку загрузки плагина. Вместо него используйте api.registerHttpRoute(...).
• Маршруты плагина должны явно объявлять auth.
• Конфликты точных значений path + match отклоняются, если не задано replaceExisting: true; один плагин не может заменить маршрут другого плагина.
• Перекрывающиеся маршруты с разными уровнями auth отклоняются. Цепочки перехода exact/prefix должны использовать только один уровень аутентификации.
• Маршруты auth: "plugin" не получают области доступа среды выполнения оператора автоматически. Они предназначены для управляемых плагином Webhook и проверки подписей, а не для привилегированных вызовов вспомогательных функций Gateway.
• Маршруты auth: "gateway" выполняются в области среды выполнения запроса Gateway. Поверхность по умолчанию (gatewayRuntimeScopeSurface: "write-default") намеренно ограничена:
  • аутентификация носителя по общему секрету (gateway.auth.mode = "token" / "password") и любой метод аутентификации без доверенного прокси получают единственную область operator.write, даже если вызывающая сторона передаёт x-openclaw-scopes
  • вызывающие стороны trusted-proxy без явного заголовка x-openclaw-scopes также сохраняют устаревшую поверхность только с operator.write
  • вызывающие стороны trusted-proxy, которые передают x-openclaw-scopes, получают вместо этого объявленные области
  • маршрут может включить gatewayRuntimeScopeSurface: "trusted-operator", чтобы всегда учитывать x-openclaw-scopes для режимов аутентификации с идентификационными данными (при отсутствии заголовка используется полный набор областей CLI по умолчанию)
• Практическое правило: не считайте маршрут плагина с аутентификацией Gateway неявной административной поверхностью. Если маршруту требуется поведение, доступное только администратору, включите поверхность областей trusted-operator, потребуйте режим аутентификации с идентификационными данными и документируйте явный контракт заголовка x-openclaw-scopes.
• После сопоставления маршрута и аутентификации обычные обработчики участвуют в допуске корневых задач Gateway. Подготовленный или перезапускающийся Gateway возвращает 503 до вызова обработчика. Узкое исключение — разрешённый манифестом маршрут auth: "gateway", который также включает специфичную для маршрута поверхность trusted-operator; он остаётся доступным, чтобы диспетчеризация управления приостановкой не оказалась заблокированной, тогда как обычные соседние маршруты того же плагина остаются за границей допуска. Владение WebSocket handleUpgrade использует ту же атомарную границу допуска; после принятия сокета обработчиком его дальнейший жизненный цикл принадлежит плагину и этой границей не отслеживается.

​

Пути импорта SDK плагинов

• index.js — точка входа встроенного плагина
• api.js — реэкспортирующий модуль вспомогательных средств и типов
• runtime-api.js — реэкспортирующий модуль только для среды выполнения
• setup-entry.js — точка входа плагина настройки

​

Схемы инструмента сообщений

• presentation для семантических блоков представления (text, context, divider, chart, table, buttons, select)
• delivery-pin для запросов закреплённой доставки

​

Разрешение целей каналов

• messaging.inferTargetChatType({ to }) определяет, следует ли рассматривать нормализованную цель как direct, group или channel до поиска в каталоге.
• messaging.targetResolver.looksLikeId(raw, normalized) сообщает ядру, следует ли для входного значения сразу перейти к разрешению по идентификатору вместо поиска в каталоге.
• messaging.targetResolver.reservedLiterals перечисляет отдельные слова, которые являются ссылками на канал или сеанс для данного провайдера. При разрешении сохраняются настроенные записи каталога до отклонения зарезервированных литералов, а при отсутствии совпадения в каталоге операция завершается отказом.
• messaging.targetResolver.resolveTarget(...) — резервный механизм плагина, когда ядру требуется окончательное разрешение, принадлежащее провайдеру, после нормализации или отсутствия совпадения в каталоге.
• messaging.resolveOutboundSessionRoute(...) отвечает за построение специфичного для провайдера маршрута сеанса после разрешения цели.

• Используйте inferTargetChatType для решений о категории, которые должны приниматься до поиска одноранговых узлов или групп.
• Используйте looksLikeId для проверок «рассматривать это как явный или нативный идентификатор цели».
• Используйте resolveTarget как специфичный для провайдера резервный механизм нормализации, а не для широкого поиска в каталоге.
• Храните нативные идентификаторы провайдера, такие как идентификаторы чатов, потоков и комнат, JID и дескрипторы, внутри значений target или специфичных для провайдера параметров, а не в универсальных полях SDK.

​

Каталоги на основе конфигурации

• одноранговые узлы личных сообщений на основе списка разрешений
• настроенные сопоставления каналов или групп
• статические резервные каталоги на уровне учётной записи

• фильтрация запросов
• применение ограничений
• вспомогательные средства устранения дубликатов и нормализации
• создание ChannelDirectoryEntry[]

​

Каталоги провайдеров

• { provider } для одной записи провайдера
• { providers } для нескольких записей провайдера

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

• discovery по-прежнему работает как устаревший псевдоним, но выводит предупреждение об устаревании
• если зарегистрированы и catalog, и discovery, OpenClaw использует catalog и выводит предупреждение
• augmentModelCatalog устарел; встроенные провайдеры должны публиковать дополнительные строки через registerModelCatalogProvider

​

Проверка канала в режиме только для чтения

• resolveAccount(...) — это путь среды выполнения. Он может предполагать, что учётные данные полностью материализованы, и немедленно завершаться с ошибкой при отсутствии обязательных секретов.
• Пути команд только для чтения, такие как openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, а также потоки исправления doctor/config, не должны материализовывать учётные данные среды выполнения только для того, чтобы описать конфигурацию.

• Возвращайте только описательное состояние учётной записи.
• Сохраняйте enabled и configured.
• При необходимости включайте поля источника и состояния учётных данных, например:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Для сообщения о доступности в режиме только для чтения не нужно возвращать необработанные значения токенов. Для команд, отображающих состояние, достаточно вернуть tokenStatus: "available" (и соответствующее поле источника).
• Используйте configured_unavailable, когда учётные данные настроены через SecretRef, но недоступны в текущем пути команды.

​

Пакеты плагинов

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• саму регистрацию канала
• все HTTP-маршруты, которые должны быть доступны до начала прослушивания Gateway
• все методы Gateway, инструменты или службы, которые должны существовать в течение того же периода

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Метаданные каталога каналов

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: дополнительная метка для более информативных поверхностей каталога и состояния
• docsLabel: переопределение текста ссылки на документацию
• preferOver: идентификаторы плагинов или каналов с более низким приоритетом, которые эта запись каталога должна опережать
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: параметры текста поверхности выбора
• markdownCapable: отмечает, что канал поддерживает Markdown, для принятия решений о форматировании исходящих сообщений
• exposure.configured: скрывает канал из поверхностей списка настроенных каналов, если задано значение false
• exposure.setup: скрывает канал из интерактивных списков выбора при настройке и конфигурировании, если задано значение false
• exposure.docs: отмечает канал как внутренний или закрытый для поверхностей навигации по документации
• showConfigured / showInSetup: устаревшие псевдонимы, которые по-прежнему принимаются для совместимости; рекомендуется exposure
• quickstartAllowFrom: включает для канала стандартный поток быстрого запуска allowFrom
• forceAccountBinding: требует явной привязки учётной записи, даже если существует только одна учётная запись
• preferSessionLookupForAnnounceTarget: отдаёт предпочтение поиску сеанса при разрешении целей объявлений

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Плагины движка контекста

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Добавление новой возможности

1. Определите контракт ядра. Решите, за какое общее поведение должно отвечать ядро: политики, резервное поведение, объединение конфигурации, жизненный цикл, семантику для каналов и форму вспомогательных функций среды выполнения.
2. Добавьте типизированные поверхности регистрации и среды выполнения плагинов. Расширьте OpenClawPluginApi и/или api.runtime минимальной полезной типизированной поверхностью возможности.
3. Подключите ядро и потребителей в каналах и функциональных плагинах. Каналы и функциональные плагины должны использовать новую возможность через ядро, а не импортировать реализацию поставщика напрямую.
4. Зарегистрируйте реализации поставщиков. Затем плагины поставщиков регистрируют свои серверные реализации для этой возможности.
5. Добавьте проверку контракта. Добавьте тесты, чтобы принадлежность и форма регистрации со временем оставались явными.

​

Контрольный список возможности

• типы контракта ядра в src/<capability>/types.ts
• исполнитель или вспомогательную функцию среды выполнения ядра в src/<capability>/runtime.ts
• поверхность регистрации API плагина в src/plugins/types.ts
• подключение реестра плагинов в src/plugins/registry.ts
• предоставление среды выполнения плагина в src/plugins/runtime/*, когда функциональным или канальным плагинам необходимо её использовать
• вспомогательные средства захвата и тестирования в src/test-utils/plugin-registration.ts
• проверки принадлежности и контракта в src/plugins/contracts/registry.ts
• документацию для операторов и разработчиков плагинов в docs/

​

Шаблон возможности

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

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

​

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

• Архитектура плагинов — общедоступная модель возможностей и структуры
• Подпути SDK плагинов
• Настройка SDK плагинов
• Разработка плагинов