Внутрішня будова Plugin

​

Загальнодоступна модель можливостей

​

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

​

Форми плагінів

​

Застарілі перехоплювачі

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

​

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

​

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

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

• перевірка маніфесту й конфігурації має працювати на основі метаданих маніфесту та схеми без виконання коду плагіна
• виявлення нативних можливостей може завантажувати код точки входу довіреного плагіна, щоб створити неактивувальний знімок реєстру
• нативна поведінка під час виконання походить зі шляху register(api) модуля плагіна, коли api.registrationMode === "full"

​

Знімок метаданих плагінів і таблиця пошуку

• володіння каналами
• відкладений запуск каналів
• ідентифікатори плагінів запуску
• володіння провайдерами та серверами CLI
• володіння провайдером налаштування, псевдонімами команд, провайдером каталогу моделей і контрактами маніфестів
• перевірка схеми конфігурації плагінів і схеми конфігурації каналів
• рішення щодо автоматичного ввімкнення під час запуску

​

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

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

​

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

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

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

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

​

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

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

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

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

​

Рівні можливостей

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

​

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

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

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({
          ...req,
          provider: "exampleai",
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          ...req,
          provider: "exampleai",
        });
      },
    });

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

export default plugin;

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

​

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

​

Контракти та забезпечення дотримання

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

​

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

​

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

​

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

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

​

Внутрішня будова та довідкові матеріали

​

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

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