Огляд SDK Plugin

SDK плагінів — це типізований контракт між плагінами та ядром. Ця сторінка є довідником щодо того, що імпортувати та що можна реєструвати.

Правила імпорту

Завжди імпортуйте з конкретного підшляху:

Кожен підшлях є невеликим самодостатнім модулем. Це пришвидшує запуск і запобігає проблемам із циклічними залежностями. Для допоміжних засобів входу та збирання, специфічних для каналів, віддавайте перевагу openclaw/plugin-sdk/channel-core; використовуйте openclaw/plugin-sdk/core для ширшого узагальненого інтерфейсу та спільних допоміжних засобів, як-от buildChannelConfigSchema.

Для конфігурації каналу публікуйте JSON Schema, що належить каналу, через openclaw.plugin.json#channelConfigs. Підшлях plugin-sdk/channel-config-schema призначений для спільних примітивів схем і універсального конструктора. Вбудовані плагіни OpenClaw використовують plugin-sdk/bundled-channel-config-schema для збережених схем вбудованих каналів. Застарілі експорти сумісності залишаються в plugin-sdk/channel-config-schema-legacy; жоден із підшляхів схем вбудованих каналів не є зразком для нових плагінів.

Довідник підшляхів

SDK плагінів представлено як набір вузьких підшляхів, згрупованих за областями (точка входу плагіна, канал, постачальник, автентифікація, середовище виконання, можливості, пам’ять і зарезервовані допоміжні засоби вбудованих плагінів). Повний каталог із групуванням і посиланнями дивіться на сторінці Підшляхи SDK плагінів.

Перелік точок входу компілятора міститься у scripts/lib/plugin-sdk-entrypoints.json; експорти пакета генеруються з публічної підмножини після вилучення локальних для репозиторію тестових і внутрішніх підшляхів, перелічених у scripts/lib/plugin-sdk-private-local-only-subpaths.json. Виконайте pnpm plugin-sdk:surface, щоб перевірити кількість публічних експортів. Застарілі публічні підшляхи, які існують достатньо давно й не використовуються у виробничому коді вбудованих розширень, відстежуються у scripts/lib/plugin-sdk-deprecated-public-subpaths.json; широкі застарілі модулі повторного експорту відстежуються у scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API реєстрації

Функція зворотного виклику register(api) отримує об’єкт OpenClawPluginApi із такими методами:

Реєстрація можливостей

Постачальники робочих середовищ також мають оголосити свій ідентифікатор у contracts.workerProviders. Ядро зберігає стійкий намір перед викликом provision(profile, operationId). Постачальники перевіряють налаштування перед зовнішнім виділенням ресурсів і викидають WorkerProviderError у разі остаточного відхилення профілю. provision має використовувати ту саму оренду, коли ідентифікатор операції повторюється. Ядро зберігає перевірені налаштування профілю разом з орендою та передає цей знімок у destroy({ leaseId, profile }), який має бути ідемпотентним, і inspect({ leaseId, profile }), який повертає active, destroyed або unknown. Це дає постачальникам змогу спрямовувати виклики життєвого циклу після перезапуску Gateway або видалення іменованого профілю. Кінцеві точки SSH використовують SecretRef для keyRef, а не вбудований матеріал ключа, і містять hostKey із довіреного результату підготовки ресурсів у точному форматі algorithm base64, без імені хоста чи коментаря. Ядро закріплює hostKey і ніколи не довіряє ключу, отриманому під час першого з’єднання. Постачальник, який створює динамічний keyRef, може реалізувати resolveSshIdentity({ leaseId, profile, keyRef }); за наявності цей засіб визначення є авторитетним, тоді як постачальники без нього використовують налаштований універсальний засіб визначення секретів. Постачальники з поновлюваними орендами також можуть реалізувати renew(leaseId). inspect має викидати помилку за тимчасових або невизначених збоїв; повертайте unknown лише за авторитетно підтвердженої відсутності. Ядро позначає активний локальний запис як осиротілий або вважає відсутність завершенням видалення ресурсів після збереженого запиту на знищення.

Постачальники вбудовувань, зареєстровані через api.registerEmbeddingProvider(...), також мають бути перелічені в contracts.embeddingProviders у маніфесті плагіна. Це універсальний інтерфейс вбудовувань для багаторазово використовуваного генерування векторів. Пошук у пам’яті може використовувати цей універсальний інтерфейс постачальника. Старіший інтерфейс api.registerMemoryEmbeddingProvider(...) і contracts.memoryEmbeddingProviders є застарілим механізмом сумісності на час міграції наявних постачальників, специфічних для пам’яті.

Постачальники, специфічні для пам’яті, які все ще надають batchEmbed(...) у середовищі виконання, залишаються на наявному контракті пакетної обробки для окремих файлів, якщо їхнє середовище виконання явно не задає sourceWideBatchEmbed: true. Ця явна згода дає хосту пам’яті змогу передавати фрагменти з кількох змінених файлів пам’яті та ввімкнених джерел в одному виклику batchEmbed(...) у межах пакетних обмежень хоста. Пакетні адаптери, які вивантажують файли запитів JSONL, мають розділяти завдання постачальника як до досягнення обмеження розміру вивантаження, так і до досягнення обмеження кількості запитів. Постачальник має повертати по одному вбудовуванню для кожного вхідного фрагмента в тому самому порядку, що й batch.chunks; не вказуйте цей прапорець, якщо постачальник очікує пакети в межах одного файла або не може зберегти порядок вхідних даних у більшому завданні, що охоплює все джерело.

Інструменти та команди

Використовуйте defineToolPlugin для простих плагінів лише з інструментами та фіксованими назвами інструментів. Використовуйте api.registerTool(...) безпосередньо для змішаних плагінів або повністю динамічної реєстрації інструментів.

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

Записи вказівок можуть бути застарілими рядками, які застосовуються до кожної поверхні системних запитів, або структурованими записами:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

Структурований параметр surfaces може містити openclaw_main, codex_app_server, cli_backend, acp_backend або subagent. pi_main залишається застарілим псевдонімом для openclaw_main. Не вказуйте surfaces, якщо вказівка навмисно призначена для всіх поверхонь. Не передавайте порожній масив surfaces; його буде відхилено, щоб випадкова втрата області дії не перетворила текст на глобальний системний запит.

Інструкції розробника нативного сервера застосунків Codex суворіші, ніж для інших поверхонь системних запитів: лише вказівки, явно обмежені областю codex_app_server, підвищуються до цього пріоритетнішого рівня. Застарілі рядкові вказівки та структуровані вказівки без визначеної області залишаються доступними для поверхонь системних запитів, відмінних від Codex, задля сумісності.

Команди хоста Node виконуються на підключеному хості Node, а не всередині процесу Gateway. Якщо присутній agentTool, Node публікує дескриптор після успішного підключення до Gateway; Gateway надає його запускам агента лише доки цей Node підключений і лише якщо command дескриптора входить до схваленої поверхні команд Node. Установіть agentTool.defaultPlatforms, щоб додати безпечну команду до стандартного списку дозволених команд Node; інакше потрібні явне налаштування gateway.nodes.allowCommands або політика виклику Node. Значення agentTool.name має бути безпечним для провайдера: починатися з літери, містити лише літери, цифри, підкреслення або дефіси та не перевищувати 64 символи. Інструменти Node на основі MCP можуть задавати метадані agentTool.mcp, щоб у каталозі та інтерфейсах пошуку інструментів відображалися ідентичності віддаленого сервера й інструмента MCP, але виконання все одно відбувається через оголошену команду Node.

Інфраструктура

Побудовники доповнень промпту пам’яті отримують необов’язковий контекст agentId, agentSessionKey і sandboxed. Виклики search і get доповнення корпусу пам’яті отримують необов’язковий контекст agentId і sandboxed. Plugins зі сховищем, що належить агенту, мають визначати це сховище для кожного виклику, а не захоплювати один глобальний шлях під час реєстрації. Якщо ідентифікатор агента потрібен, але відсутній у багатоагентній операції, безпечно завершуйте операцію з помилкою замість вибору довільного агента.

Інтерактивні обробники Telegram можуть повертати { submitText }, щоб після успішного завершення обробника спрямувати текст через звичайний вхідний шлях агента Telegram. OpenClaw зберігає кнопку зворотного виклику, якщо політика вхідних повідомлень пропускає текст або обробка завершується помилкою, щоб користувач міг повторити спробу після зміни блокувальної умови. Це поле результату специфічне для Telegram; інші канали зберігають власні контракти інтерактивних результатів.

Хуки хоста для Plugins робочих процесів

Хуки хоста — це точки інтеграції SDK для Plugins, яким потрібно брати участь у життєвому циклі хоста, а не лише додавати провайдера, канал або інструмент. Це універсальні контракти; їх може використовувати режим планування, але також робочі процеси схвалення, шлюзи політик робочого простору, фонові монітори, майстри налаштування та Plugins-компаньйони інтерфейсу.

Дескриптор surface: "tab" додає вкладку бічної панелі до інтерфейсу керування. Дескриптори вкладок активних Plugins оголошуються клієнтам панелі керування у привітанні Gateway (controlUiTabs), тому вкладка з’являється лише тоді, коли Plugin увімкнено. Вбудовані Plugins можуть постачати повноцінне подання панелі керування для своєї вкладки; інші Plugins можуть задати path до HTTP-маршруту Plugin (див. api.registerHttpRoute(...)), який панель керування відтворює в ізольованому фреймі. icon — підказка назви піктограми панелі керування, group вибирає розділ бічної панелі (control або agent), order визначає порядок серед вкладок Plugins, а requiredScopes приховує вкладку від підключень без відповідних областей доступу оператора:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

Для нового коду Plugin використовуйте згруповані простори імен:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

Еквівалентні пласкі методи залишаються доступними як застарілі псевдоніми сумісності для наявних Plugins. Не додавайте новий код Plugin, який безпосередньо викликає api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn або api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) — це зручна оболонка з областю дії сеансу над планувальником Cron Gateway. Cron керує часом і створює запис фонового завдання під час виконання ходу; Plugin SDK лише обмежує цільовий сеанс, іменування, що належить Plugin, і очищення. Використовуйте api.runtime.tasks.managedFlows усередині запланованого ходу, коли самій роботі потрібен стійкий багатокроковий стан Task Flow.

Контракти навмисно розділяють повноваження:

• Зовнішні Plugins можуть володіти розширеннями сеансів, дескрипторами інтерфейсу, командами, метаданими інструментів, введеннями до наступного ходу та звичайними хуками.
• Довірені політики інструментів виконуються перед звичайними хуками before_tool_call і є довіреними хостом. Вбудовані політики виконуються першими; політики встановлених Plugins потребують явного ввімкнення та наявності їхніх локальних ідентифікаторів у contracts.trustedToolPolicies, після чого виконуються в порядку завантаження Plugins. Ідентифікатори політик обмежені областю Plugin, що їх реєструє.
• Зарезервовані команди можуть належати лише вбудованим компонентам. Зовнішні Plugins мають використовувати власні назви команд або псевдоніми.
• allowPromptInjection=false вимикає хуки, що змінюють промпт, зокрема agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, поля промпту із застарілого before_agent_start та enqueueNextTurnInjection.

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

Реєстрація виявлення Gateway

api.registerGatewayDiscoveryService(...) дає змогу Plugin оголошувати активний Gateway у локальному транспорті виявлення, як-от mDNS/Bonjour. OpenClaw викликає службу під час запуску Gateway, коли локальне виявлення ввімкнено, передає поточні порти Gateway і несекретні підказкові дані TXT, а під час завершення роботи Gateway викликає повернутий обробник stop.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Plugins виявлення Gateway не повинні вважати оголошені значення TXT секретами або автентифікацією. Виявлення є підказкою для маршрутизації; автентифікація Gateway і закріплення TLS, як і раніше, відповідають за довіру.

Метадані реєстрації CLI

api.registerCli(registrar, opts?) приймає два типи метаданих команд:

• commands: явні назви команд, якими володіє реєстратор
• descriptors: дескриптори команд на етапі синтаксичного аналізу, що використовуються для довідки CLI, маршрутизації та лінивої реєстрації CLI Plugin
• parentPath: необов’язковий шлях батьківської команди для вкладених груп команд, як-от ["nodes"]

Для функцій спарених Node віддавайте перевагу api.registerNodeCliFeature(registrar, opts?). Це невелика обгортка навколо api.registerCli(..., { parentPath: ["nodes"] }), яка явно визначає такі команди, як openclaw nodes canvas, як функції Node, якими володіє Plugin.

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

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

Вкладені команди отримують визначену батьківську команду як program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

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

Реєстрація серверної частини CLI

api.registerCliBackend(...) дає змогу Plugin володіти типовою конфігурацією для локальної серверної частини CLI ШІ, як-от claude-cli або my-cli.

• id серверної частини стає префіксом постачальника в посиланнях на моделі, як-от my-cli/gpt-5.
• config серверної частини використовує ту саму структуру, що й agents.defaults.cliBackends.<id>.
• Конфігурація користувача все одно має пріоритет. OpenClaw накладає agents.defaults.cliBackends.<id> на типову конфігурацію Plugin перед запуском CLI.
• Використовуйте normalizeConfig, коли серверній частині потрібне сумісне переписування після об’єднання (наприклад, нормалізація старих структур прапорців).
• Використовуйте resolveExecutionArgs для переписування argv у межах запиту, що належить до діалекту CLI, як-от зіставлення рівнів міркування OpenClaw із нативним прапорцем зусиль. Хук отримує ctx.executionMode; використовуйте "side-question", щоб додавати нативні для серверної частини прапорці ізоляції для ефемерних викликів /btw. Якщо ці прапорці надійно вимикають нативні інструменти для CLI, де вони зазвичай завжди ввімкнені, також оголосіть sideQuestionToolMode: "disabled".
• Серверні частини, які можуть вимкнути всі нативні інструменти для певного запуску, можуть оголосити nativeToolMode: "selectable". Обмежені виклики передають порожній кортеж ctx.toolAvailability.native разом із точним ізольованим хостом списком дозволених MCP; resolveExecutionArgs має забезпечити обидві умови в остаточному argv нового або відновленого запуску. OpenClaw безпечно завершує операцію відмовою, якщо серверна частина не може цього забезпечити.

Повний посібник зі створення див. у розділі Plugins серверної частини CLI.

Ексклюзивні слоти

Застарілі адаптери векторного подання пам’яті

• registerMemoryCapability — рекомендований ексклюзивний API Plugin пам’яті.
• registerMemoryCapability також може надавати publicArtifacts.listArtifacts(...), щоб супутні Plugins могли використовувати експортовані артефакти пам’яті через openclaw/plugin-sdk/memory-host-core, не звертаючись до приватної структури конкретного Plugin пам’яті.
• registerMemoryPromptSection, registerMemoryFlushPlan і registerMemoryRuntime — ексклюзивні API Plugin пам’яті із сумісністю зі застарілими версіями.
• MemoryFlushPlan.model може прив’язати хід скидання до точного посилання provider/model, як-от ollama/qwen3:8b, не успадковуючи активний ланцюжок резервних варіантів.
• registerMemoryEmbeddingProvider застарілий. Нові постачальники векторних подань мають використовувати api.registerEmbeddingProvider(...) і contracts.embeddingProviders.
• Наявні постачальники, специфічні для пам’яті, продовжують працювати протягом перехідного періоду, але перевірка Plugin позначає це як борг сумісності для невбудованих Plugins.

Події та життєвий цикл

Приклади, поширені назви хуків і семантику захисних умов див. у розділі Хуки Plugin.

Семантика рішень хуків

before_install — це хук життєвого циклу середовища виконання Plugin, а не поверхня політики встановлення оператора. Використовуйте security.installPolicy, коли рішення про дозвіл або блокування має охоплювати шляхи встановлення чи оновлення через CLI та Gateway.

• before_tool_call: повернення { block: true } є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
• before_tool_call: повернення { block: false } трактується як відсутність рішення (так само, як пропуск block), а не як перевизначення.
• before_install: повернення { block: true } є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
• before_install: повернення { block: false } трактується як відсутність рішення (так само, як пропуск block), а не як перевизначення.
• reply_dispatch: повернення { handled: true, ... } є термінальним. Щойно будь-який обробник бере диспетчеризацію на себе, обробники з нижчим пріоритетом і стандартний шлях диспетчеризації моделі пропускаються.
• message_sending: повернення { cancel: true } є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
• message_sending: повернення { cancel: false } трактується як відсутність рішення (так само, як пропуск cancel), а не як перевизначення.
• message_received: використовуйте типізоване поле threadId, коли потрібна маршрутизація вхідної гілки/теми. Зберігайте в metadata додаткові дані, специфічні для каналу.
• message_sending: спочатку використовуйте типізовані поля маршрутизації replyToId / threadId і лише потім вдавайтеся до специфічного для каналу metadata.
• gateway_start: використовуйте ctx.config, ctx.workspaceDir і ctx.getCron?.() для стану запуску, яким володіє Gateway, замість залежності від внутрішніх хуків gateway:startup. На цьому етапі Cron ще може завантажуватися.
• cron_reconciled: перебудовує повну зовнішню проєкцію Cron після запуску або перезавантаження планувальника. Вона містить reason і фактичний стан enabled, зокрема enabled: false, а ctx.getCron?.() повертає точний узгоджений планувальник. Передавайте ctx.abortSignal у довготривалу роботу з проєкцією; сигнал переривається, коли цей знімок планувальника замінюється новішим або Gateway закривається.
• cron_changed: відстежує зміни життєвого циклу Cron, яким володіє Gateway. Події scheduled і removed є підказками для узгодження після фіксації, а не впорядкованим журналом змін. У запланованої події event.nextRunAtMs відсутнє, якщо завдання не має наступного пробудження; видалена подія все одно містить знімок видаленого завдання.

Зовнішні планувальники пробуджень мають застосовувати затримку або об’єднувати події cron_changed, а потім повторно зчитувати повне довготривале представлення з планувальника, востаннє зафіксованого через cron_reconciled. Не використовуйте планувальник із контексту cron_changed: відокремлена підказка від старішого планувальника може накластися на пізніше перезавантаження.

Використовуйте cron_reconciled як тригер повного знімка для довготривалого стану, завантаженого під час запуску Gateway або заміни планувальника. Він не відтворюється під час гарячого перезавантаження лише Plugin. Обробники спостереження виконуються паралельно, а диспетчеризації без очікування результату можуть накладатися, тому споживачі не повинні покладатися на порядок завершення подій. Зберігайте OpenClaw як джерело істини для перевірок строку виконання та самого виконання.

Приклад адаптера з одночасним виконанням лише одного запиту, довготривалою заміною, повторними спробами/відступом і коректним завершенням роботи див. у розділі Безпечна зовнішня проєкція Cron.

Поля об’єкта API

Угода щодо внутрішніх модулів

У своєму Plugin використовуйте локальні агрегувальні файли для внутрішніх імпортів:

my-plugin/  api.ts            # Публічні експорти для зовнішніх споживачів  runtime-api.ts    # Внутрішні експорти середовища виконання  index.ts          # Точка входу Plugin  setup-entry.ts    # Полегшена точка входу лише для налаштування (необов’язково)

Публічні поверхні вбудованого Plugin, завантажуваного через фасад (api.ts, runtime-api.ts, index.ts, setup-entry.ts та подібні публічні файли входу), надають перевагу активному знімку конфігурації середовища виконання, якщо OpenClaw уже працює. Якщо знімка середовища виконання ще немає, вони повертаються до визначеного конфігураційного файлу на диску. Фасади упакованих вбудованих Plugin слід завантажувати через фасадні завантажувачі Plugin OpenClaw; прямі імпорти з dist/extensions/... обходять перевірки маніфесту та супровідного файла середовища виконання, які упаковані встановлення використовують для коду, що належить Plugin.

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

• Anthropic: публічна межа api.ts / contract-api.ts для допоміжних засобів бета-заголовка Claude та потоку service_tier.
• @openclaw/openai-provider: api.ts експортує конструктори постачальника, допоміжні засоби стандартної моделі та конструктори постачальника реального часу.
• @openclaw/openrouter-provider: api.ts експортує конструктор постачальника разом із допоміжними засобами початкового налаштування/конфігурації.

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