Обзор Plugin SDK

​

Соглашение об импорте

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

​

Справочник подпутей

​

API регистрации

​

Регистрация capability

​

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

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

​

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

​

Host hooks для workflow-плагинов

• 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 и являются доверенными со стороны хоста. Bundled-политики выполняются первыми; политики установленных plugins требуют явного включения, а также их локальных идентификаторов в contracts.trustedToolPolicies, и выполняются следующими в порядке загрузки plugins. Идентификаторы политик ограничены регистрирующим Plugin.
• Зарезервированное владение командами доступно только для bundled. Внешним plugins следует использовать собственные имена команд или алиасы.
• allowPromptInjection=false отключает хуки, изменяющие prompt, включая agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, поля prompt из устаревшего 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,
      },
    ],
  },
);

​

Регистрация backend CLI

• id backend становится префиксом provider в ссылках на модели вроде my-cli/gpt-5.
• config backend использует ту же форму, что и agents.defaults.cliBackends.<id>.
• Пользовательская конфигурация по-прежнему имеет приоритет. OpenClaw объединяет agents.defaults.cliBackends.<id> поверх значения по умолчанию от Plugin перед запуском CLI.
• Используйте normalizeConfig, когда backend нужны переписывания совместимости после слияния (например, нормализация старых форм флагов).
• Используйте resolveExecutionArgs для переписывания argv в области запроса, относящегося к диалекту CLI, например для сопоставления уровней thinking OpenClaw с нативным флагом effort. Хук получает ctx.executionMode; используйте "side-question", чтобы добавить backend-native флаги изоляции для эфемерных вызовов /btw. Если эти флаги надежно отключают нативные инструменты для CLI, который иначе всегда их включает, также объявите sideQuestionToolMode: "disabled".

​

Эксклюзивные слоты

​

Устаревшие адаптеры эмбеддингов памяти

• registerMemoryCapability — предпочтительный эксклюзивный API Plugin памяти.
• registerMemoryCapability также может предоставлять publicArtifacts.listArtifacts(...), чтобы сопутствующие Plugin могли потреблять экспортированные артефакты памяти через openclaw/plugin-sdk/memory-host-core, не обращаясь к приватной структуре конкретного Plugin памяти.
• registerMemoryPromptSection, registerMemoryFlushPlan и registerMemoryRuntime — эксклюзивные API Plugin памяти с поддержкой устаревшей совместимости.
• MemoryFlushPlan.model может закрепить ход сброса за точной ссылкой provider/model, например ollama/qwen3:8b, без наследования активной цепочки fallback.
• registerMemoryEmbeddingProvider устарел. Новым провайдерам эмбеддингов следует использовать api.registerEmbeddingProvider(...) и contracts.embeddingProviders.
• Существующие провайдеры, специфичные для памяти, продолжают работать в течение окна миграции, но инспекция Plugin сообщает об этом как о долге совместимости для невстроенных 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, ... } является терминальным. Как только любой обработчик берет отправку на себя, обработчики с более низким приоритетом и стандартный путь отправки в модель пропускаются.
• 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 и потока service_tier.
• @openclaw/openai-provider: api.ts экспортирует построители провайдера, вспомогательные средства модели по умолчанию и построители realtime-провайдера.
• @openclaw/openrouter-provider: api.ts экспортирует построитель провайдера плюс вспомогательные средства онбординга/конфигурации.

​

Связанные материалы