Внутрішні компоненти архітектури Plugin

​

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

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

​

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

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

• завантаження CLI звужується до Plugin, яким належить запитана основна команда
• налаштування каналу/визначення Plugin звужується до Plugin, яким належить запитаний id каналу
• явне визначення налаштування/runtime провайдера звужується до Plugin, яким належить запитаний id провайдера

​

Що кешує loader

• результатів виявлення
• даних реєстру маніфестів
• завантажених реєстрів Plugin

• Встановіть OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 або OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1, щоб вимкнути ці кеші.
• Налаштовуйте вікна кешу за допомогою OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS і OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

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

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

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

​

Колбеки прив’язки розмов

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

​

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

• Метадані маніфесту для недорогого пошуку до runtime: providerAuthEnvVars, providerAuthAliases, providerAuthChoices і channelEnvVars.
• Хуки часу конфігурації: catalog (застарілий discovery) плюс applyConfigDefaults.
• Runtime-хуки: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделей, обгортання потоків, рівні thinking, політику replay та кінцеві точки використання. Див. повний список у Порядок і використання хуків.

​

Порядок і використання хуків

​

Приклад провайдера

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 повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток.
• Використовує конфігурацію ядра messages.tts і вибір провайдера.
• Повертає PCM audio buffer + sample rate. Plugin повинні виконувати resample/encode для провайдерів.
• listVoices є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику.
• Списки голосів можуть містити ширші метадані, такі як locale, gender і теги personality для засобів вибору, обізнаних про провайдера.
• 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 і доставку відповідей у ядрі.
• Використовуйте speech providers для поведінки синтезу, що належить постачальнику.
• Застарілий ввід Microsoft edge нормалізується до id провайдера microsoft.
• Бажана модель володіння є орієнтованою на компанію: один Plugin постачальника може володіти провайдерами text, speech, image і майбутніми медіапровайдерами в міру того, як OpenClaw додає ці контракти можливостей.

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

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

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(...): перелічує доступних провайдерів генерації зображень і їхні можливості.

​

Gateway HTTP-маршрути

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

• path: шлях маршруту в межах Gateway HTTP-сервера.
• auth: обов’язково. Використовуйте "gateway", щоб вимагати звичайний auth Gateway, або "plugin" для auth/webhook verification, якими керує Plugin.
• match: необов’язково. "exact" (типово) або "prefix".
• replaceExisting: необов’язково. Дозволяє одному й тому самому Plugin замінити власну наявну реєстрацію маршруту.
• handler: повертайте true, коли маршрут обробив запит.

• api.registerHttpHandler(...) було вилучено, і він спричинить помилку завантаження Plugin. Натомість використовуйте api.registerHttpRoute(...).
• Маршрути Plugin повинні явно оголошувати auth.
• Конфлікти точних path + match відхиляються, якщо не вказано replaceExisting: true, і один Plugin не може замінити маршрут іншого Plugin.
• Перекривні маршрути з різними рівнями auth відхиляються. Залишайте ланцюжки fallthrough exact/prefix лише в межах одного рівня auth.
• Маршрути auth: "plugin" не отримують автоматично runtime scopes оператора. Вони призначені для webhook/signature verification, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway.
• Маршрути auth: "gateway" виконуються в межах runtime scope запиту Gateway, але цей scope навмисно консервативний:
  • bearer auth зі спільним секретом (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 auth є неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка x-openclaw-scopes.

​

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

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

​

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

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

​

Визначення цілей каналу

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

• Використовуйте inferTargetChatType для рішень щодо категорій, які мають прийматися до пошуку peer/group.
• Використовуйте looksLikeId для перевірок на кшталт «сприймати це як явний/native id цілі».
• Використовуйте resolveTarget як резервне визначення нормалізації, специфічне для провайдера, а не для широкого пошуку в каталозі.
• Залишайте native id провайдера, такі як id чату, id треду, JID, handle та room id, всередині значень target або параметрів, специфічних для провайдера, а не в загальних полях SDK.

​

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

• peer DM на основі allowlist
• налаштовані відповідності каналів/груп
• статичні резервні варіанти каталогу в межах облікового запису

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

​

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

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

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

• discovery усе ще працює як застарілий псевдонім
• якщо зареєстровано і catalog, і discovery, OpenClaw використовує catalog

​

Перевірка каналу лише для читання

• 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" (і відповідне поле джерела) для команд у стилі 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 чат через webhook-ботів Nextcloud Talk.",
      "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: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено false
• exposure.docs: позначає канал як внутрішній/приватний для поверхонь навігації документацією
• showConfigured / showInSetup: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу exposure
• quickstartAllowFrom: підключає канал до стандартного потоку quickstart allowFrom
• forceAccountBinding: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис
• preferSessionLookupForAnnounceTarget: надає перевагу пошуку сесії під час визначення announce target

• ~/.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", () => ({
    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", () => ({
    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. визначте контракт ядра Вирішіть, якою спільною поведінкою повинно володіти ядро: політикою, fallback, злиттям конфігурації, життєвим циклом, семантикою для каналів і формою runtime helper.
2. додайте типізовані поверхні реєстрації/runtime для Plugin Розширте OpenClawPluginApi та/або api.runtime найменшою корисною типізованою поверхнею можливості.
3. підключіть споживачів ядра й каналів/функцій Канали та Plugin функцій повинні споживати нову можливість через ядро, а не через прямий імпорт реалізації постачальника.
4. зареєструйте реалізації постачальника Потім Plugin постачальника реєструють свої backend щодо цієї можливості.
5. додайте покриття контракту Додайте тести, щоб форма володіння й реєстрації з часом залишалася явною.

​

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

• типи контракту ядра в src/<capability>/types.ts
• runner/runtime helper ядра в src/<capability>/runtime.ts
• поверхня реєстрації API Plugin в src/plugins/types.ts
• підключення реєстру Plugin в src/plugins/registry.ts
• runtime-експозиція Plugin в src/plugins/runtime/*, коли Plugin функцій/каналів мають це споживати
• helper для capture/test в src/test-utils/plugin-registration.ts
• перевірки володіння/контракту в src/plugins/contracts/registry.ts
• документація для операторів/Plugin у docs/

​

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

// контракт ядра
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

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

// спільний runtime helper для Plugin функцій/каналів
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

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

​

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

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