Точки входу Plugin

Кожен Plugin експортує типовий об’єкт входу. SDK надає допоміжні засоби для їх створення.

Для встановлених Plugin package.json має спрямовувати завантаження середовища виконання на зібраний JavaScript, коли він доступний:

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

extensions і setupEntry залишаються чинними вихідними точками входу для розробки в робочому просторі та git checkout. runtimeExtensions і runtimeSetupEntry є бажаними, коли OpenClaw завантажує встановлений пакет, і дозволяють npm-пакетам уникати компіляції TypeScript під час виконання. Явні точки входу середовища виконання є обов’язковими: runtimeSetupEntry вимагає setupEntry, а відсутні артефакти runtimeExtensions або runtimeSetupEntry спричиняють помилку встановлення/виявлення замість мовчазного повернення до вихідного коду. Якщо встановлений пакет оголошує лише вихідну точку входу TypeScript, OpenClaw використає відповідний зібраний peer dist/*.js, коли він існує, а потім повернеться до вихідного коду TypeScript.

Усі шляхи точок входу мають залишатися всередині каталогу пакета Plugin. Точки входу середовища виконання та виведені зібрані JavaScript peer не роблять дійсним вихідний шлях extensions або setupEntry, що виходить за межі каталогу.

defineToolPlugin

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

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

  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 є необов’язковою. Якщо її пропущено, OpenClaw використовує строгу схему порожнього об’єкта, а згенерований маніфест усе одно містить configSchema.
• execute повертає звичайний рядок або JSON-серіалізоване значення. Допоміжний засіб обгортає його як текстовий результат інструмента з details.
• Імена інструментів статичні. openclaw plugins build виводить contracts.tools з оголошених інструментів, тому авторам не потрібно дублювати імена вручну.
• Завантаження середовища виконання залишається строгим. Установленим Plugin все ще потрібні openclaw.plugin.json і openclaw.extensions у package.json; OpenClaw не виконує код Plugin, щоб вивести відсутні дані маніфесту.

definePluginEntry

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

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

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

• id має збігатися з вашим маніфестом openclaw.plugin.json.
• kind призначений для ексклюзивних слотів: "memory" або "context-engine".
• configSchema може бути функцією для лінивого обчислення.
• 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 викликається під час реєстрації, щоб ви могли зберегти посилання на середовище виконання (зазвичай через createPluginRuntimeStore). Під час захоплення метаданих CLI його пропускають.
• registerCliMetadata виконується під час api.registrationMode === "cli-metadata", api.registrationMode === "discovery" і api.registrationMode === "full". Використовуйте його як канонічне місце для CLI-дескрипторів, якими володіє канал, щоб коренева довідка залишалася без активації, знімки виявлення містили статичні метадані команд, а звичайна реєстрація команд CLI лишалася сумісною з повними завантаженнями Plugin.
• Реєстрація виявлення є безактиваційною, але не безімпортною. OpenClaw може обчислювати довірену точку входу Plugin і модуль канального Plugin, щоб побудувати знімок, тому тримайте імпорти верхнього рівня без побічних ефектів, а сокети, клієнти, workers і сервіси розміщуйте за шляхами лише для "full".
• registerFull виконується лише коли api.registrationMode === "full". Його пропускають під час завантаження лише для налаштування.
• Як і definePluginEntry, configSchema може бути лінивою фабрикою, а OpenClaw мемоїзує розв’язану схему під час першого доступу.
• Для кореневих команд CLI, якими володіє Plugin, віддавайте перевагу api.registerCli(..., { descriptors: [...] }), коли хочете, щоб команда лишалася ліниво завантажуваною, але не зникала з дерева розбору кореневого CLI. Для команд можливостей парних вузлів віддавайте перевагу api.registerNodeCliFeature(...), щоб команда потрапила під openclaw nodes. Для інших вкладених команд Plugin додайте parentPath і реєструйте команди на об’єкті program, переданому реєстратору; OpenClaw розв’язує його до батьківської команди перед викликом Plugin. Для канальних Plugin віддавайте перевагу реєстрації цих дескрипторів із 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(...) із вузькими сімействами допоміжних засобів налаштування:

• openclaw/plugin-sdk/setup-runtime для безпечних для середовища виконання допоміжних засобів налаштування, таких як createSetupTranslator, import-safe адаптери патчів налаштування, вивід нотаток пошуку, promptResolvedAllowFrom, splitSetupEntries і делеговані проксі налаштування
• openclaw/plugin-sdk/channel-setup для поверхонь налаштування необов’язкового встановлення
• openclaw/plugin-sdk/setup-tools для допоміжних засобів CLI/архіву/документації для налаштування/встановлення

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

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

 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) => {        /* setup-safe route */      },    });  },});

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

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

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

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

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    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(/* ... */);}

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

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

Зокрема для реєстраторів CLI:

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

Форми Plugin

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

Використовуйте openclaw plugins inspect <id>, щоб побачити форму plugin.

Пов’язане

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