Огляд SDK Plugin

​

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

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

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

​

API реєстрації

​

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

​

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

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

​

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

​

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

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

• 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 можуть володіти розширеннями сеансів, дескрипторами інтерфейсу, командами, метаданими інструментів, введеннями до наступного ходу та звичайними хуками.
• Довірені політики інструментів виконуються перед звичайними хуками 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({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

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

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

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

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

​

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

​

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

​

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

• 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.

​

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

​

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

• 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 відсутнє, якщо завдання не має наступного пробудження; видалена подія все одно містить знімок видаленого завдання.

​

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

​

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

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

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

​

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