Внутрішня архітектура 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
• доповнювати мітки/заповнювачі Control UI
• показувати метадані встановлення/каталогу
• зберігати дешеві дескриптори активації та налаштування без завантаження runtime plugin

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

​

Межа кешу plugin

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

• результатів виявлення
• прямих реєстрів маніфестів
• реєстрів маніфестів, реконструйованих із встановленого індексу plugin
• lookup власника провайдера, model suppression, політики провайдера або метаданих public-artifact
• будь-якої іншої відповіді, виведеної з маніфесту, де змінений маніфест, встановлений індекс або load path має бути видимим під час наступного читання метаданих

​

Модель реєстру

• записи plugin (ідентичність, джерело, походження, статус, діагностика)
• інструменти
• застарілі хуки та типізовані хуки
• канали
• провайдерів
• обробники Gateway RPC
• HTTP-маршрути
• CLI-реєстратори
• фонові сервіси
• команди, якими володіє plugin

• модуль plugin -> реєстрація в реєстрі
• core runtime -> споживання реєстру

​

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: розв’язана прив’язка для схвалених requests
• request: початкове summary request, підказка detach, sender id і метадані розмови

​

Runtime-хуки провайдера

• Метадані маніфесту для дешевого pre-runtime lookup: setup.providers[].envVars, застарілий compatibility providerAuthEnvVars, providerAuthAliases, providerAuthChoices і channelEnvVars.
• Хуки часу конфігурації: catalog (застарілий discovery) плюс applyConfigDefaults.
• Runtime-хуки: понад 40 необов’язкових хуків, що покривають auth, model resolution, stream wrapping, thinking levels, replay policy і usage 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-помічники

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 audio buffer + sample rate. Plugin-и мають виконувати resample/encode для постачальників.
• 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, fallback і доставку відповідей у core.
• Використовуйте мовленнєвих постачальників для поведінки синтезу, якою володіє постачальник.
• Застарілий вхід Microsoft edge нормалізується до ідентифікатора постачальника microsoft.
• Бажана модель володіння орієнтована на компанію: один Plugin постачальника може володіти текстовими, мовленнєвими, зображувальними та майбутніми медіапостачальниками, коли OpenClaw додає ці контракти можливостей.

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

• Тримайте оркестрацію, fallback, конфігурацію та wiring каналів у core.
• Тримайте поведінку постачальника в Plugin-і постачальника.
• Додавальне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результатів, нові необов’язкові можливості.
• Генерація відео вже дотримується того самого шаблону:
  • core володіє контрактом можливості та runtime-помічником
  • Plugin-и постачальників реєструють api.registerVideoGenerationProvider(...)
  • Plugin-и функцій/каналів споживають 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.* є бажаною спільною поверхнею для розуміння зображень/аудіо/відео.
• extractStructuredWithModel(...) є межею для Plugin-ів для обмеженого витягування, яким володіє постачальник і яке орієнтоване насамперед на зображення. Додайте принаймні один вхід зображення; текстові входи є додатковим контекстом. product Plugin-и володіють своїми маршрутами та схемами, тоді як OpenClaw володіє межею provider/runtime.
• Використовує основну аудіоконфігурацію media-understanding (tools.media.audio) і порядок fallback постачальників.
• Повертає { text: undefined }, коли транскрипційний вивід не створено (наприклад, вхід пропущено/не підтримується).
• api.runtime.stt.transcribeAudioFile(...) залишається 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 є необов’язковими перевизначеннями для окремого запуску, а не постійними змінами сесії.
• OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
• Для fallback-запусків, якими володіє Plugin, оператори мають явно ввімкнути plugins.entries.<id>.subagent.allowModelOverride: true.
• Використовуйте plugins.entries.<id>.subagent.allowedModels, щоб обмежити довірені Plugin-и конкретними канонічними цілями provider/model, або "*", щоб явно дозволити будь-яку ціль.
• Недовірені subagent-запуски Plugin-ів усе ще працюють, але запити перевизначення відхиляються замість тихого fallback.
• Створені Plugin-ом subagent-сесії позначаються ідентифікатором Plugin-а, що їх створив. Fallback api.runtime.subagent.deleteSession(...) може видаляти лише ці власні сесії; довільне видалення сесій і далі потребує Gateway-запиту з admin scope.

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

• Тримайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у core.
• Використовуйте постачальників вебпошуку для специфічних для постачальника пошукових transport-ів.
• api.runtime.webSearch.* є бажаною спільною поверхнею для Plugin-ів функцій/каналів, яким потрібна пошукова поведінка без залежності від 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(...): згенерувати зображення за допомогою налаштованого ланцюга постачальників генерації зображень.
• 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", щоб вимагати звичайну автентифікацію Gateway, або "plugin" для автентифікації/перевірки Webhook, керованої Plugin.
• match: необов’язково. "exact" (типово) або "prefix".
• replaceExisting: необов’язково. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту.
• handler: поверніть true, коли маршрут обробив запит.

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

​

Шляхи імпорту Plugin SDK

• index.js — точка входу вбудованого Plugin
• api.js — barrel допоміжних засобів/типів
• runtime-api.js — barrel лише для runtime
• setup-entry.js — точка входу setup Plugin

​

Схеми інструментів повідомлень

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

​

Розв’язання цілі каналу

• messaging.inferTargetChatType({ to }) вирішує, чи нормалізовану ціль слід трактувати як direct, group або channel перед пошуком у каталозі.
• messaging.targetResolver.looksLikeId(raw, normalized) повідомляє core, чи введення має перейти безпосередньо до id-подібного розв’язання замість пошуку в каталозі.
• messaging.targetResolver.reservedLiterals перелічує прості слова, які є посиланнями каналу/сеансу для цього провайдера. Розв’язання зберігає налаштовані записи каталогу перед відхиленням зарезервованих літералів, а потім закрито завершується помилкою за промаху в каталозі.
• messaging.targetResolver.resolveTarget(...) є fallback Plugin, коли core потребує остаточного розв’язання, яким володіє провайдер, після нормалізації або після промаху в каталозі.
• messaging.resolveOutboundSessionRoute(...) володіє побудовою маршруту сеансу, специфічною для провайдера, після розв’язання цілі.

• Використовуйте inferTargetChatType для категорійних рішень, які мають відбуватися перед пошуком peers/groups.
• Використовуйте looksLikeId для перевірок “трактувати це як явний/нативний id цілі”.
• Використовуйте resolveTarget для fallback нормалізації, специфічної для провайдера, а не для широкого пошуку в каталозі.
• Тримайте нативні для провайдера id, як-от id чатів, id потоків, JID, handles і id кімнат, усередині значень target або специфічних для провайдера параметрів, а не в загальних полях SDK.

​

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

• DM peers, керовані allowlist
• налаштовані мапи channel/group
• статичні fallback каталогу в межах облікового запису

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

​

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

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

• simple: прості провайдери, керовані API-key або env
• profile: провайдери, що з’являються, коли існують auth profiles
• paired: провайдери, що синтезують кілька пов’язаних записів провайдера
• late: останній прохід, після інших неявних провайдерів

• discovery досі працює як legacy alias, але видає попередження про застарілість
• якщо зареєстровано і catalog, і discovery, OpenClaw використовує catalog
• augmentModelCatalog застаріло; вбудовані провайдери мають публікувати додаткові рядки через registerModelCatalogProvider

​

Read-only перевірка каналу

• resolveAccount(...) є runtime-шляхом. Він може припускати, що облікові дані повністю матеріалізовані, і може швидко завершуватися помилкою, коли обов’язкових секретів бракує.
• Read-only командні шляхи, як-от openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, а також потоки doctor/repair конфігурації, не повинні матеріалізувати runtime credentials лише для того, щоб описати конфігурацію.

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

​

Пакети package

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

• сама реєстрація каналу
• будь-які HTTP routes, які мають бути доступні до того, як gateway почне прослуховування
• будь-які gateway methods, tools або services, які мають існувати протягом того самого вікна

• 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: plugin/channel ids із нижчим пріоритетом, які цей запис каталогу має випереджати
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: елементи керування текстом selection-surface
• markdownCapable: позначає канал як здатний працювати з markdown для рішень щодо вихідного форматування
• exposure.configured: приховати канал із поверхонь списку налаштованих каналів, якщо встановлено false
• exposure.setup: приховати канал з інтерактивних засобів вибору setup/configure, якщо встановлено false
• exposure.docs: позначити канал як internal/private для поверхонь навігації документації
• showConfigured / showInSetup: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу exposure
• quickstartAllowFrom: підключити канал до стандартного quickstart flow allowFrom
• forceAccountBinding: вимагати явного прив’язування account, навіть коли існує лише один account
• preferSessionLookupForAnnounceTarget: віддавати перевагу пошуку session під час розв’язання announce targets

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

​

Plugins контекстного рушія

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

​

Додавання нової capability

1. визначте core contract Вирішіть, якою спільною поведінкою має володіти core: policy, fallback, config merge, lifecycle, channel-facing semantics і форма runtime helper.
2. додайте типізовані plugin registration/runtime surfaces Розширте OpenClawPluginApi і/або api.runtime найменшою корисною типізованою capability surface.
3. під’єднайте core + channel/feature consumers Channels і feature plugins мають споживати нову capability через core, а не імпортувати vendor implementation напряму.
4. зареєструйте vendor implementations Потім vendor plugins реєструють свої backends для capability.
5. додайте contract coverage Додайте тести, щоб ownership і registration shape залишалися явними з часом.

​

Checklist capability

• core contract types у src/<capability>/types.ts
• core runner/runtime helper у src/<capability>/runtime.ts
• plugin API registration surface у src/plugins/types.ts
• plugin registry wiring у src/plugins/registry.ts
• plugin runtime exposure у src/plugins/runtime/*, коли feature/channel plugins мають її споживати
• capture/test helpers у src/test-utils/plugin-registration.ts
• ownership/contract assertions у src/plugins/contracts/registry.ts
• operator/plugin docs у docs/

​

Шаблон capability

// 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