Внутрішні механізми Plugin

Documentation Index

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

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

​

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

​

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

​

Форми Plugin

​

Застарілі hooks

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

​

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

​

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

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

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

​

Snapshot метаданих Plugin і таблиця пошуку

• володіння каналами
• відкладений запуск каналів
• id Plugin запуску
• володіння провайдерами та бекендами CLI
• володіння setup provider, alias команди, provider каталогу моделей і контрактом маніфесту
• валідація config schema Plugin і channel config schema
• рішення автоматичного увімкнення під час запуску

​

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

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

​

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

• core володіє спільним хостом інструмента message, підключенням prompt, обліком сесій/потоків і dispatch виконання
• plugins каналів володіють виявленням scoped action, виявленням можливостей і будь-якими специфічними для каналу фрагментами schema
• plugins каналів володіють provider-specific граматикою сесійних розмов, наприклад тим, як conversation ids кодують thread ids або успадковуються від parent conversations
• plugins каналів виконують фінальну дію через свій action adapter

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• trusted inbound requesterSenderId

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

​

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

• company plugin зазвичай має володіти всіма OpenClaw-facing surfaces цієї компанії
• feature plugin зазвичай має володіти повною feature surface, яку він вводить
• канали мають споживати shared core capabilities замість ad hoc повторної реалізації provider behavior

• OpenAI живе в одному plugin, навіть якщо він охоплює text models, speech, images і майбутнє video
• інший постачальник може зробити те саме для власної surface area
• каналам байдуже, який vendor plugin володіє provider; вони споживають shared capability contract, відкритий core

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

​

Шарування capability

• core володіє reply-time TTS policy, fallback order, prefs і channel delivery
• openai, elevenlabs і microsoft володіють synthesis implementations
• voice-call споживає telephony TTS runtime helper

​

Приклад багатоможливісного company plugin

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;

• один plugin володіє vendor surface
• core усе ще володіє capability contracts
• channels і feature plugins споживають helpers api.runtime.*, а не vendor code
• contract tests можуть перевіряти, що plugin зареєстрував capabilities, якими заявляє володіння

​

Приклад capability: video understanding

​

Contracts і enforcement

• автори plugins отримують один стабільний внутрішній стандарт
• core може відхиляти duplicate ownership, як-от два plugins, що реєструють той самий provider id
• startup може показувати actionable diagnostics для malformed registration
• contract tests можуть забезпечувати bundled-plugin ownership і запобігати silent drift

​

Що належить до контракту

​

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

​

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

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

​

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

​

Пов’язане

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