Перейти до основного вмісту

​
Точки входу плагінів

Кожен плагін експортує типовий об’єкт точки входу. SDK надає три допоміжні функції для їх створення.
Шукаєте покрокове пояснення? Див. Channel Plugins або Provider Plugins для покрокових посібників.

​
definePluginEntry

Імпорт: openclaw/plugin-sdk/plugin-entry Для плагінів провайдерів, плагінів інструментів, плагінів хуків і всього, що не є каналом обміну повідомленнями. 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});
ПолеТипОбов’язковеТипове значення
idstringТак—
namestringТак—
descriptionstringТак—
kindstringНі—
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchemaНіПорожня схема об’єкта
register(api: OpenClawPluginApi) => voidТак—
  • id має збігатися з вашим маніфестом openclaw.plugin.json.
  • kind призначено для ексклюзивних слотів: "memory" або "context-engine".
  • configSchema може бути функцією для ледачого обчислення.
  • OpenClaw визначає та мемоїзує цю схему при першому доступі, тому витратні побудовники схем виконуються лише один раз.

​
defineChannelPluginEntry

Імпорт: openclaw/plugin-sdk/channel-core Обгортає definePluginEntry логікою, специфічною для каналів. Автоматично викликає api.registerChannel({ plugin }), надає необов’язковий шов метаданих CLI для кореневої довідки та обмежує registerFull режимом реєстрації. 
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});
ПолеТипОбов’язковеТипове значення
idstringТак—
namestringТак—
descriptionstringТак—
pluginChannelPluginТак—
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchemaНіПорожня схема об’єкта
setRuntime(runtime: PluginRuntime) => voidНі—
registerCliMetadata(api: OpenClawPluginApi) => voidНі—
registerFull(api: OpenClawPluginApi) => voidНі—
  • setRuntime викликається під час реєстрації, щоб ви могли зберегти посилання на runtime (зазвичай через createPluginRuntimeStore). Під час захоплення метаданих CLI вона пропускається.
  • registerCliMetadata виконується і під час api.registrationMode === "cli-metadata", і під час api.registrationMode === "full". Використовуйте це як канонічне місце для дескрипторів CLI, що належать каналу, щоб коренева довідка залишалася без активації, а звичайна реєстрація команд CLI зберігала сумісність із повними завантаженнями плагінів.
  • registerFull виконується лише тоді, коли api.registrationMode === "full". Воно пропускається під час завантаження лише для setup.
  • Як і у definePluginEntry, configSchema може бути лінивою фабрикою, а OpenClaw мемоїзує визначену схему при першому доступі.
  • Для кореневих CLI-команд, що належать плагіну, надавайте перевагу api.registerCli(..., { descriptors: [...] }), якщо хочете, щоб команда залишалася ліниво завантажуваною, але не зникала з дерева розбору кореневого CLI. Для каналових плагінів надавайте перевагу реєстрації цих дескрипторів із registerCliMetadata(...), а registerFull(...) зосередьте на роботі, потрібній лише під час runtime.
  • Якщо registerFull(...) також реєструє gateway RPC-методи, тримайте їх на префіксі, специфічному для плагіна. Зарезервовані простори назв адміністрування ядра (config.*, exec.approvals.*, wizard.*, update.*) завжди примусово переводяться в operator.admin.

​
defineSetupPluginEntry

Імпорт: openclaw/plugin-sdk/channel-core Для полегшеного файла setup-entry.ts. Повертає лише { plugin } без логіки runtime або CLI. 
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);
OpenClaw завантажує це замість повної точки входу, коли канал вимкнено, не налаштовано або коли ввімкнено відкладене завантаження. Див. Setup and Config, щоб зрозуміти, коли це важливо. На практиці поєднуйте defineSetupPluginEntry(...) із вузькими сімействами допоміжних функцій setup:
  • openclaw/plugin-sdk/setup-runtime для безпечних для runtime допоміжних функцій setup, як-от безпечні для імпорту адаптери патчів setup, вивід приміток lookup, promptResolvedAllowFrom, splitSetupEntries і делеговані проксі setup
  • openclaw/plugin-sdk/channel-setup для поверхонь setup необов’язкового встановлення
  • openclaw/plugin-sdk/setup-tools для допоміжних функцій CLI/архівів/документації для setup/install
Тримайте важкі SDK, реєстрацію CLI та довготривалі сервіси runtime у повній точці входу.

​
Режим реєстрації

api.registrationMode повідомляє вашому плагіну, як саме його було завантажено:
РежимКолиЩо реєструвати
"full"Звичайний запуск gatewayУсе
"setup-only"Вимкнений/не налаштований каналЛише реєстрацію каналу
"setup-runtime"Потік setup із доступним runtimeРеєстрацію каналу плюс лише легкий runtime, потрібний до завантаження повної точки входу
"cli-metadata"Коренева довідка / захоплення метаданих CLIЛише дескриптори CLI
defineChannelPluginEntry обробляє цей поділ автоматично. Якщо ви використовуєте definePluginEntry безпосередньо для каналу, перевіряйте режим самостійно: 
register(api) {
  if (api.registrationMode === "cli-metadata" || api.registrationMode === "full") {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}
Розглядайте "setup-runtime" як проміжок, у якому поверхні запуску лише для setup мають існувати без повторного входу в повний bundled runtime каналу. Добре підходять реєстрація каналу, безпечні для setup HTTP-маршрути, безпечні для setup gateway-методи та делеговані допоміжні функції setup. Важкі фонові сервіси, реєстратори CLI та завантаження SDK провайдерів/клієнтів, як і раніше, належать до "full". Зокрема для реєстраторів CLI:
  • використовуйте descriptors, коли реєстратор володіє однією або кількома кореневими командами і ви хочете, щоб OpenClaw ліниво завантажував справжній модуль CLI при першому виклику
  • переконайтеся, що ці дескриптори охоплюють кожен корінь команди верхнього рівня, який відкриває реєстратор
  • використовуйте лише commands для жадібних шляхів сумісності

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

OpenClaw класифікує завантажені плагіни за їхньою поведінкою реєстрації:
ФормаОпис
plain-capabilityОдин тип можливостей (наприклад, лише провайдер)
hybrid-capabilityКілька типів можливостей (наприклад, провайдер + speech)
hook-onlyЛише hooks, без можливостей
non-capabilityІнструменти/команди/сервіси, але без можливостей
Використовуйте openclaw plugins inspect <id>, щоб побачити форму плагіна.

​
Пов’язане