Огляд Plugin SDK

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

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

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

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

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

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

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

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

API реєстрації

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

Реєстрація capability

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

Команди Plugin можуть задавати agentPromptGuidance, коли агенту потрібна коротка, належна команді підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте provider- або plugin-specific політику до builder prompt ядра.

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

Host hooks для workflow Plugin

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

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

Еквівалентні flat methods залишаються доступними як застарілі aliases сумісності для наявних 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(...) — це зручна сесійна обгортка над планувальником Gateway Cron. Cron відповідає за таймінг і створює запис фонової задачі, коли запускається хід; Plugin SDK лише обмежує цільову сесію, назви, що належать plugin, і очищення. Використовуйте api.runtime.tasks.managedFlows усередині запланованого ходу, коли сама робота потребує довготривалого багатоетапного стану TaskFlow.

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

• Зовнішні plugins можуть володіти розширеннями сесій, дескрипторами UI, командами, метаданими інструментів, ін’єкціями наступного ходу та звичайними хуками.
• Довірені політики інструментів виконуються перед звичайними хуками before_tool_call і доступні лише в комплекті, бо вони беруть участь у політиці безпеки хоста.
• Володіння зарезервованими командами доступне лише в комплекті. Зовнішні plugins мають використовувати власні назви команд або псевдоніми.
• 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, а під час завершення роботи 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"]

Для функцій парних вузлів надавайте перевагу 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. Цей шлях сумісності з негайним завантаженням залишається підтримуваним, але він не встановлює заповнювачі на основі дескрипторів для лінивого завантаження на етапі розбору.

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

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

• id бекенда стає префіксом провайдера в посиланнях на моделі на кшталт codex-cli/gpt-5.
• config бекенда використовує ту саму форму, що й agents.defaults.cliBackends.<id>.
• Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує agents.defaults.cliBackends.<id> поверх типових значень plugin перед запуском CLI.
• Використовуйте normalizeConfig, коли бекенду потрібні переписування сумісності після об’єднання (наприклад, нормалізація старих форм прапорців).
• Використовуйте resolveExecutionArgs для переписувань argv в області запиту, які належать діалекту CLI, наприклад зіставлення рівнів мислення OpenClaw із нативним прапорцем зусилля.

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

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

Адаптери embedding пам’яті

• 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, без успадкування активного ланцюга fallback.
• registerMemoryEmbeddingProvider дає активному plugin пам’яті змогу зареєструвати один або більше id адаптерів embedding (наприклад openai, gemini або користувацький id, визначений plugin).
• Конфігурація користувача, така як agents.defaults.memorySearch.provider і agents.defaults.memorySearch.fallback, розв’язується відносно цих зареєстрованих id адаптерів.

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

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

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

• before_tool_call: повернення { block: true } є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
• before_tool_call: повернення { block: false } розглядається як відсутність рішення (так само, як пропуск block), а не як перевизначення.
• before_install: повернення { block: true } є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
• before_install: повернення { block: false } розглядається як відсутність рішення (так само, як пропуск block), а не як перевизначення.
• reply_dispatch: повернення { handled: true, ... } є термінальним. Щойно будь-який обробник заявляє dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
• 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_changed: спостерігайте за змінами життєвого циклу Cron, що належать gateway. Використовуйте event.job?.state?.nextRunAtMs і ctx.getCron?.() під час синхронізації зовнішніх планувальників пробудження, і залишайте 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)

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

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

• Anthropic: публічна межа api.ts / contract-api.ts для Claude beta-header і stream-допоміжних засобів service_tier.
• @openclaw/openai-provider: api.ts експортує builder-и provider, допоміжні засоби для моделей за замовчуванням і builder-и realtime-provider.
• @openclaw/openrouter-provider: api.ts експортує builder provider разом із допоміжними засобами onboarding/config.

Пов’язане