Точки входу Plugin

Кожен plugin експортує об’єкт запису за замовчуванням. SDK надає допоміжну функцію для кожної форми запису: defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry.

Записи пакета

Установлені plugins спрямовують поля package.json openclaw як на вихідні, так і на зібрані записи:

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

• extensions і setupEntry — це вихідні записи, які використовуються для розробки в робочому просторі та в отриманій копії git.
• runtimeExtensions і runtimeSetupEntry є пріоритетними для встановлених пакетів: завдяки їм npm-пакети можуть не виконувати компіляцію TypeScript під час виконання.
• runtimeExtensions, якщо наявний, має відповідати extensions за довжиною масиву (записи утворюють пари за позиціями). runtimeSetupEntry потребує setupEntry.
• Якщо артефакт runtimeExtensions/runtimeSetupEntry оголошено, але він відсутній, установлення/виявлення завершується помилкою пакування; OpenClaw не переходить неявно до вихідного коду. Перехід до вихідного коду (нижче) застосовується лише тоді, коли запис середовища виконання взагалі не оголошено.
• Якщо встановлений пакет оголошує лише вихідний запис TypeScript, OpenClaw шукає відповідний зібраний парний файл dist/*.js (або .mjs/.cjs) і використовує його; інакше він переходить до вихідного коду TypeScript.
• Усі шляхи записів мають залишатися в каталозі пакета plugin. Записи середовища виконання та виведені парні зібрані JS-файли не роблять чинним шлях вихідного коду extensions або setupEntry, що виходить за межі каталогу.

defineToolPlugin

Імпорт: openclaw/plugin-sdk/tool-plugin

Для plugins, які лише додають інструменти агента. Зберігає вихідний код компактним, виводить типи конфігурації та параметрів інструментів зі схем TypeBox, обгортає звичайні повернені значення у формат результатів інструментів OpenClaw та надає статичні метадані, які openclaw plugins build записує в маніфест plugin (contracts.tools, configSchema).

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema є необов’язковим; якщо його пропустити, використовується строга схема порожнього об’єкта (згенерований маніфест усе одно містить configSchema).
• execute повертає звичайний рядок або значення, яке можна серіалізувати в JSON; допоміжна функція обгортає його як текстовий результат інструмента з details, установленим у початкове (не перетворене на рядок) повернене значення.
• Для власних результатів інструментів openclaw/plugin-sdk/tool-results експортує textResult і jsonResult.
• Назви інструментів статичні, тому openclaw plugins build виводить contracts.tools з оголошених інструментів без ручного дублювання назв.
• Завантаження середовища виконання залишається строгим: установленим plugins усе одно потрібні openclaw.plugin.json і package.json openclaw.extensions. OpenClaw ніколи не виконує код plugin, щоб вивести відсутні дані маніфесту.

definePluginEntry

Імпорт: openclaw/plugin-sdk/plugin-entry

Для plugins провайдерів, розширених plugins інструментів, plugins перехоплень і всього, що не є каналом обміну повідомленнями.

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({/* ... */});    api.registerTool({/* ... */});  },});

• id має відповідати вашому маніфесту openclaw.plugin.json.
• Зовнішні каталоги сеансів використовують openclaw/plugin-sdk/session-catalog і api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). Ядро володіє методами Gateway sessions.catalog.*; провайдери повертають проєкції хоста, сеансу та нормалізованого транскрипту без реєстрації RPC.
• kind застаріло: натомість оголосіть ексклюзивний слот ("memory" або "context-engine") у полі kind маніфесту openclaw.plugin.json. kind запису середовища виконання залишається лише як сумісний резервний варіант для старіших plugins.
• configSchema може бути функцією для лінивого обчислення. OpenClaw розв’язує та мемоізує схему під час першого доступу, тому ресурсомісткі побудовники схем виконуються лише один раз.
• Дескриптор nodeHostCommands може визначати isAvailable({ config, env }). Повернення false вилучає цю команду та її можливість з оголошення Gateway безголового вузла. OpenClaw обчислює його за локальною конфігурацією запуску вузла; обробники команд усе одно мають перевіряти доступність під час виклику.

defineChannelPluginEntry

Імпорт: openclaw/plugin-sdk/channel-core

Обгортає definePluginEntry з підключенням, специфічним для каналу: автоматично викликає api.registerChannel({ plugin }), надає необов’язкову точку інтеграції метаданих CLI для кореневої довідки та обмежує registerFull режимом реєстрації.

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

Зворотні виклики виконуються відповідно до режиму реєстрації (повна таблиця в розділі Режим реєстрації):

• setRuntime виконується в кожному режимі, крім "cli-metadata" і "tool-discovery". Зберігайте тут посилання на середовище виконання, зазвичай через createPluginRuntimeStore.
• registerCliMetadata виконується для "cli-metadata", "discovery" і "full". Використовуйте його як канонічне місце для дескрипторів CLI, якими володіє канал, щоб коренева довідка не спричиняла активації, знімки виявлення містили статичні метадані команд, а звичайна реєстрація CLI залишалася сумісною з повним завантаженням plugin.
• registerFull виконується лише для "full" і "tool-discovery". Для "tool-discovery" він виконується замість реєстрації каналу: OpenClaw повністю пропускає registerChannel/setRuntime і викликає лише registerFull, тому будь-яка реєстрація провайдера/інструмента, потрібна вашому каналу для автономного виявлення чи виконання інструментів, має міститися там, а не за звичайним налаштуванням каналу.
• Реєстрація виявлення не спричиняє активації, але не виконується без імпорту: OpenClaw може обчислити довірений запис plugin і модуль plugin каналу, щоб побудувати знімок. Імпорти верхнього рівня не повинні мати побічних ефектів, а сокети, клієнти, воркери та служби слід розміщувати лише в шляхах "full".
• Як і definePluginEntry, configSchema може бути лінивою фабрикою; OpenClaw мемоізує розв’язану схему під час першого доступу.

Реєстрація CLI:

• Використовуйте api.registerCli(..., { descriptors: [...] }) для кореневих команд CLI, якими володіє plugin і які потрібно завантажувати ліниво без зникнення з кореневого дерева синтаксичного аналізу CLI. Назви дескрипторів мають складатися з літер, цифр, дефісів і підкреслень та починатися з літери або цифри; OpenClaw відхиляє інші форми й вилучає керівні послідовності термінала з описів перед відтворенням довідки. Охопіть кожен корінь команди верхнього рівня, який надає реєстратор. Лише commands залишається на шляху сумісності з негайним завантаженням.
• Використовуйте api.registerNodeCliFeature(...) для команд функцій спареного вузла, щоб вони розміщувалися під openclaw nodes (еквівалент registerCli(registrar, { parentPath: ["nodes"], ... })).
• Для інших вкладених команд plugin додайте parentPath і реєструйте команди в об’єкті program, переданому реєстратору; OpenClaw розв’язує його до батьківської команди перед викликом plugin.
• Для plugins каналів реєструйте дескриптори CLI з registerCliMetadata і зосередьте registerFull лише на роботі середовища виконання.
• Якщо registerFull також реєструє методи RPC Gateway, використовуйте для них префікс, специфічний для plugin. Зарезервовані простори назв адміністрування ядра (config.*, exec.approvals.*, wizard.*, update.*) завжди примусово перетворюються на operator.admin.

defineSetupPluginEntry

Імпорт: openclaw/plugin-sdk/channel-core

Для полегшеного файлу setup-entry.ts. Повертає лише { plugin } без підключення середовища виконання або CLI.

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw завантажує це замість повної точки входу, коли канал вимкнено, не налаштовано або ввімкнено відкладене завантаження. Відомості про те, коли це має значення, див. у розділі Налаштування та конфігурація.

Поєднуйте defineSetupPluginEntry(...) з вузькоспеціалізованими сімействами допоміжних засобів налаштування:

Зберігайте важкі SDK, реєстрацію CLI та довготривалі служби середовища виконання в повній точці входу.

Вбудовані канали робочого простору, які розділяють поверхні налаштування й середовища виконання, натомість можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract. Це дає змогу точці входу налаштування зберігати безпечні для налаштування експорти плагіна й секретів, водночас надаючи сеттер середовища виконання:

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* безпечний для налаштування маршрут */      },    });  },});

Використовуйте це лише тоді, коли процес налаштування справді потребує легкого сеттера середовища виконання або безпечної для налаштування поверхні Gateway до завантаження повної точки входу каналу. registerSetupRuntime виконується лише для завантажень "setup-runtime"; обмежуйте його маршрутами або методами лише для конфігурації, які мають існувати до відкладеної повної активації.

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

api.registrationMode повідомляє плагіну, як його було завантажено:

defineChannelPluginEntry обробляє це розділення автоматично. Якщо для каналу ви безпосередньо використовуєте definePluginEntry, перевіряйте режим самостійно й пам’ятайте, що "tool-discovery" пропускає реєстрацію каналу:

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   if (api.registrationMode === "tool-discovery") {    // Реєструйте лише поверхні можливостей (провайдери/інструменти), без каналу.    return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Важкі реєстрації лише для середовища виконання  api.registerService(/* ... */);}

Довготривалі служби можуть надсилати невеликі події інвалідації або життєвого циклу через контекст своєї служби:

api.registerService({  id: "index-events",  start(ctx) {    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });  },});

OpenClaw додає до цього простір імен plugin.<plugin-id>.changed. Назви подій складаються з одного сегмента в нижньому регістрі, корисне навантаження має бути обмеженим JSON, а область дії має бути operator.read, operator.write або operator.admin. Емітер існує лише протягом часу роботи служби та відкликається після зупинки або невдалого запуску. Надавайте перевагу корисному навантаженню з версією чи інвалідацією, а не повним записам, щоб авторизовані клієнти повторно зчитували канонічний стан через обмежені за областю дії методи Gateway плагіна.

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

Вважайте "setup-runtime" вікном, у якому поверхні запуску лише для налаштування мають існувати без повторного входу до повного середовища виконання вбудованого каналу. Доречними є реєстрація каналу, безпечні для налаштування HTTP-маршрути, безпечні для налаштування методи Gateway та делеговані допоміжні засоби налаштування. Важкі фонові служби, реєстратори CLI та ініціалізація SDK провайдерів і клієнтів усе ще належать до "full".

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

OpenClaw класифікує завантажені плагіни за їхньою поведінкою реєстрації:

Щоб переглянути форму плагіна, використовуйте openclaw plugins inspect <id>.

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

• Огляд SDK — API реєстрації та довідник підшляхів
• Допоміжні засоби середовища виконання — api.runtime і createPluginRuntimeStore
• Налаштування та конфігурація — маніфест, точка входу налаштування, відкладене завантаження
• Плагіни каналів — створення об’єкта ChannelPlugin
• Плагіни провайдерів — реєстрація провайдерів і хуки