Внутрішня реалізація архітектури Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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-поверхонь

​

Поведінка manifest-first

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

• завантаження CLI звужується до Plugin, які володіють запитаною primary command
• setup/розв’язання Plugin для каналу звужується до Plugin, які володіють запитаним channel id
• явне setup/runtime-розв’язання provider звужується до Plugin, які володіють запитаним provider id
• планування запуску Gateway використовує activation.onStartup для явних startup imports і startup opt-outs; Plugin без startup-метаданих завантажуються лише через вужчі activation triggers

​

Межа кешу Plugin

• PluginLoaderCacheState і сумісні active runtime registries
• jiti/module caches і public-surface loader caches, що використовуються, щоб уникати імпорту тієї самої runtime surface повторно
• filesystem caches для installed plugin artifacts
• short-lived per-call maps для path normalization або duplicate resolution

• результатів discovery
• прямих manifest registries
• manifest registries, реконструйованих із installed plugin index
• provider owner lookup, model suppression, provider policy або public-artifact metadata
• будь-якої іншої manifest-derived відповіді, де змінений manifest, installed index або load path має бути видимим під час наступного metadata read

​

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

• записи Plugin (identity, source, origin, status, diagnostics)
• інструменти
• legacy hooks і typed hooks
• канали
• providers
• gateway RPC handlers
• HTTP routes
• CLI registrars
• background services
• plugin-owned commands

• 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: resolved binding для approved requests
• request: початковий request summary, detach hint, sender id і metadata розмови

​

Runtime-хуки provider

• Метадані маніфесту для дешевого pre-runtime lookup: setup.providers[].envVars, deprecated compatibility providerAuthEnvVars, providerAuthAliases, providerAuthChoices і channelEnvVars.
• Config-time hooks: catalog (legacy discovery) плюс applyConfigDefaults.
• Runtime hooks: понад 40 optional hooks, що охоплюють auth, model resolution, stream wrapping, thinking levels, replay policy і usage endpoints. Повний список див. у Порядок і використання hook.

​

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

​

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

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 повертає звичайний core TTS output payload для поверхонь файлів/voice-note.
• Використовує core конфігурацію messages.tts і вибір провайдера.
• Повертає PCM audio buffer + sample rate. Plugins мають resample/encode для провайдерів.
• listVoices є необов’язковим для кожного провайдера. Використовуйте його для vendor-owned вибору голосів або setup flows.
• Списки голосів можуть містити багатші metadata, як-от 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 policy, fallback і доставку відповіді в core.
• Використовуйте speech providers для vendor-owned поведінки synthesis.
• Застарілий input Microsoft edge нормалізується до provider id microsoft.
• Бажана модель володіння орієнтована на компанію: один vendor plugin може володіти text, speech, image і майбутніми media providers, коли OpenClaw додаватиме ці контракти можливостей.

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.
• Тримайте поведінку vendor у provider plugin.
• Additive expansion має лишатися типізованим: нові optional methods, нові optional result fields, нові optional capabilities.
• Video generation уже дотримується того самого шаблону:
  • 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(...) є межею для plugins для обмеженого provider-owned image-first extraction. Додайте принаймні один image input; text inputs є додатковим контекстом. product plugins володіють своїми routes і schemas, тоді як OpenClaw володіє межею provider/runtime.
• Використовує core media-understanding audio configuration (tools.media.audio) і provider fallback order.
• Повертає { text: undefined }, коли transcription output не створено (наприклад, input пропущений/непідтримуваний).
• 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 є optional per-run overrides, а не persistent session changes.
• OpenClaw враховує ці override fields лише для trusted callers.
• Для plugin-owned fallback runs оператори мають увімкнути це через plugins.entries.<id>.subagent.allowModelOverride: true.
• Використовуйте plugins.entries.<id>.subagent.allowedModels, щоб обмежити trusted plugins конкретними canonical targets provider/model, або "*", щоб явно дозволити будь-який target.
• Untrusted plugin subagent runs усе ще працюють, але override requests відхиляються замість мовчазного fallback.
• Subagent sessions, створені plugin, позначаються id plugin, який їх створив. Fallback api.runtime.subagent.deleteSession(...) може видаляти лише ці owned sessions; довільне видалення session усе ще потребує 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: шлях маршруту під gateway HTTP server.
• auth: обов’язкове. Використовуйте "gateway", щоб вимагати звичайну gateway auth, або "plugin" для plugin-managed auth/webhook verification.
• match: optional. "exact" (default) або "prefix".
• replaceExisting: optional. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту.
• handler: повертайте true, коли маршрут обробив запит.

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

​

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

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

​

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

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

​

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

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

• Використовуйте inferTargetChatType для категорійних рішень, які мають відбутися до пошуку peers/groups.
• Використовуйте looksLikeId для перевірок “трактувати це як явний/native target id”.
• Використовуйте resolveTarget для provider-specific fallback нормалізації, а не для широкого пошуку в directory.
• Тримайте provider-native ids, як-от chat ids, thread ids, JIDs, handles і room ids, усередині значень target або provider-specific params, а не в загальних полях SDK.

​

Директорії на основі конфігурації

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

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

​

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

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

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

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

​

Read-only інспекція каналу

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

• Повертайте лише описовий стан акаунта.
• Зберігайте enabled і configured.
• Додавайте поля джерела/статусу credentials, коли це доречно, як-от:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Вам не потрібно повертати сирі значення token лише для повідомлення read-only доступності. Повернення tokenStatus: "available" (і відповідного поля source) достатньо для status-style команд.
• Використовуйте configured_unavailable, коли credential налаштовано через 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: вторинна мітка для багатших catalog/status surfaces
• docsLabel: перевизначає текст посилання для docs link
• preferOver: plugin/channel ids нижчого пріоритету, які цей catalog entry має випереджати
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controls для selection-surface copy
• markdownCapable: позначає канал як markdown-capable для рішень щодо outbound formatting
• exposure.configured: приховує канал із configured-channel listing surfaces, коли встановлено false
• exposure.setup: приховує канал з interactive setup/configure pickers, коли встановлено false
• exposure.docs: позначає канал як internal/private для docs navigation surfaces
• showConfigured / showInSetup: legacy aliases, які все ще приймаються для сумісності; надавайте перевагу exposure
• quickstartAllowFrom: додає канал до стандартного quickstart allowFrom flow
• forceAccountBinding: вимагає явного account binding, навіть коли існує лише один account
• preferSessionLookupForAnnounceTarget: надає перевагу session lookup під час resolve announce targets

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

​

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

​

Додавання нової можливості

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

​

Checklist можливостей

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

​

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

// 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"]);

• core володіє capability contract + orchestration
• vendor plugins володіють vendor implementations
• feature/channel plugins споживають runtime helpers
• contract tests зберігають ownership явним

​

Пов’язане

• Архітектура Plugin — публічна capability model і shapes
• Plugin SDK subpaths
• Plugin SDK setup
• Створення plugins