Огляд Plugin SDK

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

Угода щодо імпорту

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

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

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

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

SDK плагінів надається як набір вузьких підшляхів, згрупованих за областями (entry плагіна, канал, провайдер, автентифікація, runtime, capability, memory та зарезервовані хелпери вбудованих плагінів). Повний каталог — згрупований і з посиланнями — дивіться в підшляхах SDK плагінів.

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

API реєстрації

Callback register(api) отримує об’єкт OpenClawPluginApi з такими методами:

Реєстрація capability

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

Специфічні для memory провайдери, які все ще надають runtime batchEmbed(...), залишаються на наявному контракті batch-обробки на файл, якщо їхній runtime явно не встановлює sourceWideBatchEmbed: true. Ця opt-in опція дає memory host змогу надсилати chunks з кількох змінених memory-файлів і ввімкнених джерел в одному виклику batchEmbed(...) до batch-лімітів host. Batch-адаптери, які завантажують JSONL request-файли, також мають розділяти provider jobs до досягнення обмеження розміру завантаження, а також обмеження кількості запитів. Провайдер має повернути один embedding на кожен input chunk у тому самому порядку, що й batch.chunks; не вказуйте прапорець, коли провайдер очікує file-local batches або не може зберегти порядок input у більшому source-wide job.

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

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

Команди плагінів можуть встановлювати agentPromptGuidance, коли агенту потрібна коротка, належна команді підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте політику, специфічну для провайдера або плагіна, у core prompt builders.

Guidance entries можуть бути застарілими рядками, які застосовуються до кожної prompt surface, або структурованими entries:

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 залишається застарілим alias для openclaw_main. Пропускайте surfaces для навмисної guidance на всіх surfaces. Не передавайте порожній масив surfaces; його буде відхилено, щоб випадкова втрата scope не стала глобальним prompt-текстом.

Native Codex app-server developer instructions суворіші за інші prompt surfaces: лише guidance, явно scoped до codex_app_server, просувається у цей lane з вищим пріоритетом. Застаріла string guidance і unscoped structured guidance залишаються доступними для prompt surfaces, що не належать до Codex, для сумісності.

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

Host hooks для плагінів workflow

Host hooks — це seams SDK для плагінів, яким потрібно брати участь у життєвому циклі host, а не лише додавати провайдер, канал або інструмент. Це універсальні контракти; Plan Mode може їх використовувати, але так само можуть approval workflows, workspace policy gates, background monitors, setup wizards і UI companion plugins.

Використовуйте згруповані простори назв для нового коду 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(...)

Еквівалентні плоскі методи залишаються доступними як застарілі псевдоніми сумісності для наявних Plugin. Не додавайте новий код 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.

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

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

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

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

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

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() };  },});

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

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

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

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

Для функцій парних вузлів надавайте перевагу api.registerNodeCliFeature(registrar, opts?). Це невелика обгортка навколо api.registerCli(..., { parentPath: ["nodes"] }), яка робить команди на кшталт openclaw nodes canvas явними функціями вузлів, якими володіє 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. Цей eager-шлях сумісності залишається підтримуваним, але він не встановлює placeholder-и на основі дескрипторів для ледачого завантаження під час парсингу.

Реєстрація бекенду CLI

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

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

Повний посібник з авторства дивіться в CLI backend plugins.

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

Застарілі адаптери embedding пам’яті

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

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

Дивіться хуки Plugin для прикладів, поширених назв хуків і семантики guard.

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

before_install є lifecycle hook runtime plugin, а не поверхнею політики встановлення оператора. Використовуйте security.installPolicy, коли рішення allow/block має охоплювати шляхи встановлення або оновлення через CLI і Gateway.

• before_tool_call: повернення { block: true } є термінальним. Щойно будь-який handler встановить його, handler-и з нижчим пріоритетом пропускаються.
• before_tool_call: повернення { block: false } трактується як відсутність рішення (так само, як пропуск block), а не як override.
• before_install: повернення { block: true } є термінальним. Щойно будь-який handler встановить його, handler-и з нижчим пріоритетом пропускаються.
• before_install: повернення { block: false } трактується як відсутність рішення (так само, як пропуск block), а не як override.
• reply_dispatch: повернення { handled: true, ... } є термінальним. Щойно будь-який handler приймає dispatch, handler-и з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
• message_sending: повернення { cancel: true } є термінальним. Щойно будь-який handler встановить його, handler-и з нижчим пріоритетом пропускаються.
• message_sending: повернення { cancel: false } трактується як відсутність рішення (так само, як пропуск cancel), а не як override.
• message_received: використовуйте типізоване поле threadId, коли потрібна маршрутизація вхідного треду/теми. Залишайте metadata для специфічних для каналу додаткових даних.
• message_sending: використовуйте типізовані поля маршрутизації replyToId / threadId, перш ніж переходити до специфічного для каналу metadata.
• gateway_start: використовуйте ctx.config, ctx.workspaceDir і ctx.getCron?.() для стану запуску, що належить Gateway, замість покладання на внутрішні хуки gateway:startup.
• cron_changed: спостерігайте за змінами життєвого циклу cron, що належить Gateway. Використовуйте event.job?.state?.nextRunAtMs і ctx.getCron?.() під час синхронізації зовнішніх wake schedulers, і залишайте OpenClaw джерелом істини для перевірок строків виконання та виконання.

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

Конвенція внутрішніх модулів

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

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

Публічні поверхні bundled plugin, завантажені через facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts і подібні публічні entry-файли), віддають перевагу активному runtime config snapshot, коли OpenClaw уже запущений. Якщо runtime snapshot ще не існує, вони повертаються до розв’язного файлу конфігурації на диску. Facade-и packaged bundled plugin мають завантажуватися через plugin facade loaders OpenClaw; прямі імпорти з dist/extensions/... обходять manifest і runtime sidecar checks, які packaged installs використовують для коду, що належить plugin.

Provider plugins можуть надавати вузький локальний для plugin contract barrel, коли helper навмисно специфічний для провайдера і ще не належить до generic SDK subpath. Bundled приклади:

• Anthropic: публічний seam api.ts / contract-api.ts для Claude beta-header і stream helper-ів service_tier.
• @openclaw/openai-provider: api.ts експортує provider builders, default-model helpers і realtime provider builders.
• @openclaw/openrouter-provider: api.ts експортує provider builder плюс onboarding/config helpers.

Пов’язане