Внутренние механизмы архитектуры Plugin

​

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

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

​

Поведение с приоритетом манифеста

• идентифицировать plugin
• обнаруживать объявленные каналы/skills/схему конфигурации или возможности bundle
• валидировать plugins.entries.<id>.config
• дополнять метки/placeholder’ы Control UI
• показывать метаданные установки/каталога
• сохранять дешевые дескрипторы активации и настройки без загрузки runtime plugin

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

​

Граница кэша plugin

• PluginLoaderCacheState и совместимые активные runtime-реестры
• кэши jiti/module и кэши загрузчика public-surface, используемые для избежания повторного импорта одной и той же runtime-поверхности
• кэши файловой системы для установленных артефактов plugin
• краткоживущие per-call maps для нормализации путей или разрешения дубликатов

• результатов обнаружения
• прямых реестров манифестов
• реестров манифестов, реконструированных из индекса установленных plugin
• поиска владельца provider, подавления модели, policy provider или метаданных public-artifact
• любых других ответов, выведенных из манифеста, где измененный манифест, установленный индекс или load path должны быть видны при следующем чтении метаданных

​

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

• записи plugin (identity, source, origin, status, diagnostics)
• tools
• устаревшие хуки и typed hooks
• channels
• providers
• gateway RPC handlers
• HTTP routes
• CLI registrars
• background services
• команды, принадлежащие plugin

• plugin module -> registry registration
• core runtime -> registry consumption

​

Callback’и привязки беседы

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

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

​

Runtime-хуки provider

• Метаданные манифеста для дешевого pre-runtime поиска: setup.providers[].envVars, устаревшая совместимость providerAuthEnvVars, providerAuthAliases, providerAuthChoices и channelEnvVars.
• Хуки времени конфигурации: catalog (устаревший discovery) плюс applyConfigDefaults.
• Runtime-хуки: более 40 необязательных хуков, покрывающих auth, разрешение модели, обертку stream, уровни thinking, policy replay и endpoints использования. См. полный список в разделе Порядок и использование хуков.

​

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

​

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

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);
  },
});

​

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

​

Runtime helpers

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 возвращает обычный core TTS output payload для поверхностей file/voice-note.
• Использует core-конфигурацию messages.tts и выбор провайдера.
• Возвращает PCM audio buffer + sample rate. Plugins должны выполнять resample/encode для провайдеров.
• listVoices необязателен для каждого провайдера. Используйте его для voice pickers или setup flows, принадлежащих поставщику.
• Списки голосов могут включать более богатые метаданные, такие как locale, gender и personality tags для provider-aware pickers.
• OpenAI и ElevenLabs сегодня поддерживают telephony. 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, fallback и доставку ответов в core.
• Используйте speech providers для поведения синтеза, принадлежащего поставщику.
• Устаревший Microsoft edge input нормализуется в идентификатор провайдера microsoft.
• Предпочтительная модель владения ориентирована на компанию: один vendor plugin может владеть text, speech, image и будущими media providers по мере добавления OpenClaw этих capability contracts.

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

• Держите orchestration, fallback, config и channel wiring в core.
• Держите поведение поставщика в provider plugin.
• Additive expansion должен оставаться типизированным: новые optional methods, новые optional result fields, новые optional capabilities.
• Генерация видео уже следует тому же шаблону:
  • core владеет capability contract и runtime helper
  • vendor plugins регистрируют api.registerVideoGenerationProvider(...)
  • feature/channel plugins используют 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.5",
  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.* является предпочтительной общей поверхностью для понимания image/audio/video.
• extractStructuredWithModel(...) является обращенным к Plugin швом для ограниченной provider-owned image-first extraction. Включите как минимум один image input; text inputs являются дополнительным контекстом. product plugins владеют своими routes и schemas, а OpenClaw владеет boundary provider/runtime.
• Использует core media-understanding audio configuration (tools.media.audio) и provider fallback order.
• Возвращает { text: undefined }, когда transcription output не создан (например, input пропущен или не поддерживается).
• api.runtime.stt.transcribeAudioFile(...) остается compatibility alias.

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 являются необязательными per-run overrides, а не постоянными изменениями session.
• OpenClaw учитывает эти override fields только для доверенных callers.
• Для plugin-owned fallback runs операторы должны явно включить plugins.entries.<id>.subagent.allowModelOverride: true.
• Используйте plugins.entries.<id>.subagent.allowedModels, чтобы ограничить доверенные Plugins конкретными canonical provider/model targets, или "*", чтобы явно разрешить любой target.
• Untrusted plugin subagent runs всё ещё работают, но override requests отклоняются вместо silent fallback.
• Созданные Plugin subagent sessions помечаются идентификатором создавшего Plugin. Fallback api.runtime.subagent.deleteSession(...) может удалять только эти принадлежащие ему sessions; удаление произвольных sessions всё ещё требует admin-scoped Gateway request.

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,
  },
});

• Держите provider selection, credential resolution и shared request semantics в core.
• Используйте web-search providers для vendor-specific search transports.
• api.runtime.webSearch.* является предпочтительной общей поверхностью для feature/channel plugins, которым нужно search behavior без зависимости от agent tool wrapper.

​

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(...): сгенерировать изображение с использованием настроенной цепочки image-generation provider.
• listProviders(...): перечислить доступных image-generation providers и их capabilities.

​

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", чтобы требовать обычную аутентификацию Gateway, или "plugin" для управляемой плагином аутентификации/проверки Webhook.
• match: необязательно. "exact" (по умолчанию) или "prefix".
• replaceExisting: необязательно. Позволяет тому же плагину заменить собственную существующую регистрацию маршрута.
• handler: возвращайте true, когда маршрут обработал запрос.

• api.registerHttpHandler(...) удален и вызовет ошибку загрузки плагина. Используйте вместо него api.registerHttpRoute(...).
• Маршруты плагинов должны явно объявлять auth.
• Точные конфликты path + match отклоняются, если не задано replaceExisting: true, и один плагин не может заменить маршрут другого плагина.
• Перекрывающиеся маршруты с разными уровнями auth отклоняются. Оставляйте цепочки переходов exact/prefix только на одном уровне аутентификации.
• Маршруты auth: "plugin" не получают автоматически области runtime оператора. Они предназначены для управляемых плагином Webhook/проверки подписей, а не для привилегированных вызовов вспомогательных средств Gateway.
• Маршруты auth: "gateway" выполняются внутри области runtime запроса Gateway, но эта область намеренно консервативна:
  • аутентификация bearer с общим секретом (gateway.auth.mode = "token" / "password") удерживает области runtime маршрутов плагина на operator.write, даже если вызывающая сторона отправляет x-openclaw-scopes
  • доверенные HTTP-режимы с идентификацией (например, trusted-proxy или gateway.auth.mode = "none" на приватном ingress) учитывают x-openclaw-scopes только когда заголовок явно присутствует
  • если x-openclaw-scopes отсутствует в таких запросах маршрутов плагина с идентификацией, область runtime откатывается к operator.write
• Практическое правило: не предполагайте, что маршрут плагина с аутентификацией Gateway является неявной административной поверхностью. Если маршруту нужно поведение только для администраторов, требуйте режим аутентификации с идентификацией и документируйте явный контракт заголовка x-openclaw-scopes.

​

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

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

​

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

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

​

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

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

• Используйте inferTargetChatType для решений о категории, которые должны происходить до поиска peers/groups.
• Используйте looksLikeId для проверок “считать это явным/нативным id цели”.
• Используйте resolveTarget для специфичного для провайдера отката нормализации, а не для широкого поиска в каталоге.
• Храните нативные для провайдера идентификаторы, такие как chat ids, thread ids, JIDs, handles и room ids, внутри значений target или специфичных для провайдера параметров, а не в универсальных полях SDK.

​

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

• DM peers, управляемые allowlist
• настроенные карты каналов/групп
• статические откаты каталога в области учетной записи

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

​

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

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

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

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

​

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

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

• Возвращайте только описательное состояние учетной записи.
• Сохраняйте enabled и configured.
• Включайте поля источника/статуса учетных данных, когда это уместно, например:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Не нужно возвращать сырые значения токенов только для сообщения о доступности только для чтения. Возврата tokenStatus: "available" (и соответствующего поля source) достаточно для команд в стиле status.
• Используйте 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: id Plugin/каналов с более низким приоритетом, которые эта запись каталога должна превосходить
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: элементы управления текстом поверхности выбора
• markdownCapable: помечает канал как поддерживающий markdown для решений о форматировании исходящих сообщений
• exposure.configured: скрывает канал из поверхностей списка настроенных каналов, когда задано false
• exposure.setup: скрывает канал из интерактивных выборщиков setup/configure, когда задано false
• exposure.docs: помечает канал как внутренний/приватный для поверхностей навигации документации
• showConfigured / showInSetup: устаревшие псевдонимы, все еще принимаемые для совместимости; предпочитайте exposure
• quickstartAllowFrom: подключает канал к стандартному потоку quickstart allowFrom
• forceAccountBinding: требует явной привязки учетной записи, даже когда существует только одна учетная запись
• preferSessionLookupForAnnounceTarget: предпочитает поиск сеанса при разрешении целей объявлений

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

​

Plugin движка контекста

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/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, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/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, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

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

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

​

Чек-лист возможностей

• типы контракта core в src/<capability>/types.ts
• runner/runtime-helper core в src/<capability>/runtime.ts
• поверхность регистрации API Plugin в src/plugins/types.ts
• проводку реестра Plugin в src/plugins/registry.ts
• экспозицию среды выполнения Plugin в src/plugins/runtime/*, когда функциональным/канальным Plugin нужно ее потреблять
• helper-функции захвата/тестов в src/test-utils/plugin-registration.ts
• утверждения владения/контракта в src/plugins/contracts/registry.ts
• документацию оператора/Plugin в 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(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• ядро владеет контрактом возможности и оркестрацией
• Plugin поставщика владеют реализациями поставщиков
• функциональные/канальные Plugin используют runtime-помощники
• контрактные тесты сохраняют владение явным

​

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

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