Огляд Plugin SDK

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

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

​

API реєстрації

​

Реєстрація capability

​

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

​

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

​

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

​

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

​

Адаптери 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 адаптерів.

​

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

​

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

• 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

​

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

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)

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

​

Пов’язане