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

​

Публічна модель можливостей

​

Позиція щодо зовнішньої сумісності

​

Форми Plugin-ів

​

Застарілі hooks

• підтримувати його працездатність
• документувати його як застарілий
• віддавати перевагу before_model_resolve для роботи з перевизначенням моделі/провайдера
• віддавати перевагу before_prompt_build для роботи зі зміною prompt
• видаляти лише після того, як реальне використання зменшиться, а покриття fixtures доведе безпечність міграції

​

Сигнали сумісності

​

Огляд архітектури

• metadata під час parsing надходять з registerCli(..., { descriptors: [...] })
• справжній модуль CLI Plugin-а може залишатися lazy та реєструватися під час першого виклику

• валідація manifest/config має працювати з metadata manifest/schema без виконання коду Plugin-а
• нативне виявлення можливостей може завантажувати trusted entry-код Plugin-а, щоб побудувати registry snapshot без активації
• нативна runtime-поведінка походить зі шляху register(api) модуля Plugin-а з api.registrationMode === "full"

​

Snapshot метаданих Plugin-а і lookup table

• ownership каналів
• deferred channel startup
• startup plugin ids
• ownership провайдерів і backend CLI
• ownership setup provider, command alias, model catalog provider і manifest contract
• валідація plugin config schema і channel config schema
• startup auto-enable decisions

​

Планування активації

• поля activation.* є явними підказками планувальника
• providers, channels, commandAliases, setup.providers, contracts.tools і хуки залишаються резервним механізмом володіння маніфестом
• API планувальника лише з ids залишається доступним для наявних викликачів
• API плану повідомляє мітки причин, щоб діагностика могла відрізняти явні підказки від резервного механізму володіння

​

Канальні плагіни та спільний інструмент повідомлень

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

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• довірений вхідний requesterSenderId

• outbound.sendPoll — спільна базова лінія для каналів, що відповідають загальній моделі опитування
• actions.handleAction("poll") — бажаний шлях для специфічної для каналу семантики опитувань або додаткових параметрів опитування

​

Модель володіння можливостями

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

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

• плагін = межа володіння
• можливість = контракт ядра, який кілька плагінів можуть реалізовувати або споживати

​

Шарування можливостей

• ядро володіє політикою TTS під час відповіді, порядком резервування, налаштуваннями та доставкою в канал
• openai, elevenlabs і microsoft володіють реалізаціями синтезу
• voice-call споживає runtime-помічник TTS для телефонії

​

Приклад плагіна компанії з кількома можливостями

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• один плагін володіє поверхнею постачальника
• ядро все ще володіє контрактами можливостей
• канали та функціональні плагіни споживають помічники api.runtime.*, а не код постачальника
• контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими заявляє, що володіє

​

Приклад можливості: розуміння відео

​

Контракти та примусове забезпечення

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

​

Що має входити до контракту

​

Модель виконання

​

Межа експорту

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

​

Внутрішні механізми й довідка

​

Пов’язане

• Створення плагінів
• Маніфест Plugin
• Налаштування SDK Plugin