Внутрішня архітектура Plugin

​

Конвеєр завантаження

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

• його визначена точка входу виходить за межі кореня Plugin
• його шлях (або кореневий каталог) доступний для запису всім користувачам
• для невбудованих Plugin власник шляху не відповідає поточному uid (або root)

​

Поведінка з пріоритетом маніфесту

• ідентифікувати Plugin
• виявляти оголошені канали/Skills/схему конфігурації або можливості пакета
• перевіряти plugins.entries.<id>.config
• доповнювати підписи/заповнювачі Control UI
• показувати метадані інсталяції/каталогу
• зберігати легковагові дескриптори активації та налаштування без завантаження середовища виконання Plugin

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

​

Межа кешу Plugin

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

• результатів виявлення
• безпосередніх реєстрів маніфестів
• реєстрів маніфестів, відновлених з індексу встановлених Plugin
• пошуку власника постачальника, приховування моделей, політик постачальника або метаданих публічних артефактів
• будь-якої іншої відповіді, отриманої з маніфесту, для якої змінений маніфест, індекс установлених компонентів або шлях завантаження має бути видимим під час наступного читання метаданих

​

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

• модуль Plugin -> реєстрація в реєстрі
• середовище виконання ядра -> використання реєстру

​

Зворотні виклики прив’язування розмови

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: початковий підсумок запиту, підказка щодо від’єднання, ідентифікатор відправника та метадані розмови

​

Перехоплювачі середовища виконання постачальника

• Метадані маніфесту для швидкого пошуку до запуску середовища виконання: 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 і частоту дискретизації. Plugin мають передискретизувати/закодувати дані для постачальників.
• 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.
• Бажана модель володіння орієнтована на компанію: один Plugin постачальника може керувати постачальниками тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додаватиме відповідні контракти можливостей.

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

• Зберігайте оркестрацію, резервний перехід, конфігурацію та підключення каналів у ядрі.
• Зберігайте поведінку постачальника в його Plugin.
• Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості.
• Генерування відео вже відповідає такому самому шаблону:
  • ядро володіє контрактом можливості та допоміжним засобом середовища виконання
  • 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.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(...) є доступною для Plugin межею обмеженого видобування даних із пріоритетом зображень, яким керує постачальник. Додайте принаймні одне вхідне зображення; текстові вхідні дані є додатковим контекстом. Plugin продукту володіють своїми маршрутами та схемами, а 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 враховує ці поля перевизначення лише для довірених викликових сторін.
• Для резервних виконань, якими керує Plugin, оператори мають явно дозволити їх за допомогою plugins.entries.<id>.subagent.allowModelOverride: true.
• Використовуйте plugins.entries.<id>.subagent.allowedModels, щоб обмежити довірені Plugin конкретними канонічними цілями provider/model, або "*", щоб явно дозволити будь-яку ціль.
• Виконання підагентів від недовірених Plugin і надалі працюють, але запити на перевизначення відхиляються замість непомітного резервного переходу.
• Створені Plugin сеанси підагентів позначаються ідентифікатором Plugin, що їх створив. Резервний 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.* є бажаним спільним інтерфейсом для Plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від оболонки інструменту агента.

​

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" для автентифікації чи перевірки вебхуків, якими керує плагін.
• match: необов’язкове поле. "exact" (типове значення) або "prefix".
• handleUpgrade: необов’язковий обробник запитів оновлення WebSocket на тому самому маршруті.
• replaceExisting: необов’язкове поле. Дає змогу тому самому плагіну замінити власну наявну реєстрацію маршруту.
• handler: поверніть true, коли маршрут обробив запит.

• api.registerHttpHandler(...) видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте api.registerHttpRoute(...).
• Маршрути плагінів мають явно оголошувати auth.
• Конфлікти однакових path + match відхиляються, якщо не вказано replaceExisting: true, а один плагін не може замінити маршрут іншого плагіна.
• Маршрути, що перекриваються та мають різні рівні auth, відхиляються. Ланцюжки переходу exact/prefix мають використовувати лише один рівень автентифікації.
• Маршрути з auth: "plugin" не отримують автоматично області дії середовища виконання оператора. Вони призначені для вебхуків і перевірки підписів, якими керує плагін, а не для привілейованих викликів допоміжних функцій 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 або 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 або конфігурації не повинні матеріалізувати облікові дані середовища виконання лише для опису конфігурації.

• Повертайте лише описовий стан облікового запису.
• Зберігайте 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: ідентифікатори Plugin/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати
• 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

​

Plugin рушія контексту

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. Додайте типізовані поверхні реєстрації Plugin і середовища виконання. Розширте OpenClawPluginApi та/або api.runtime найменшою корисною типізованою поверхнею можливості.
3. Під’єднайте ядро та споживачів каналів/функцій. Канали й Plugin функцій мають використовувати нову можливість через ядро, а не імпортувати реалізацію постачальника безпосередньо.
4. Зареєструйте реалізації постачальників. Потім Plugin постачальників реєструють свої серверні реалізації для цієї можливості.
5. Додайте покриття контракту. Додайте тести, щоб структура володіння та реєстрації залишалася явною з часом.

​

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

• типи контракту ядра в src/<capability>/types.ts
• засіб виконання ядра або допоміжний засіб середовища виконання в src/<capability>/runtime.ts
• поверхню реєстрації API Plugin у src/plugins/types.ts
• під’єднання реєстру Plugin у src/plugins/registry.ts
• надання середовища виконання Plugin у src/plugins/runtime/*, коли Plugin функцій або каналів мають його використовувати
• допоміжні засоби захоплення/тестування в 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(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• ядро відповідає за контракт можливості та оркестрацію
• Plugin постачальників відповідають за реалізації постачальників
• Plugin функцій/каналів використовують допоміжні засоби середовища виконання
• тести контрактів зберігають володіння явним

​

Пов’язані матеріали

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