Обзор SDK плагинов

​

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

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

​

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

​

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

​

Регистрация возможностей

​

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

agentPromptGuidance: [
  "Глобальная подсказка команды.",
  { text: "Показывать это только в основной подсказке OpenClaw.", surfaces: ["openclaw_main"] },
];

​

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

​

Перехватчики хоста для плагинов рабочих процессов

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Журнал",
  description: "Ваш день в виде временной шкалы, созданной из снимков экрана.",
  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(...)

• Внешние плагины могут управлять расширениями сеансов, дескрипторами пользовательского интерфейса, командами, метаданными инструментов, внедрениями в следующий ход и обычными перехватчиками.
• Доверенные политики инструментов выполняются до обычных перехватчиков before_tool_call и пользуются доверием хоста. Политики встроенных плагинов выполняются первыми; политики установленных плагинов требуют явного включения и указания их локальных идентификаторов в contracts.trustedToolPolicies, после чего выполняются в порядке загрузки плагинов. Идентификаторы политик ограничены областью зарегистрировавшего их плагина.
• Владение зарезервированными командами доступно только встроенным плагинам. Внешним плагинам следует использовать собственные имена команд или псевдонимы.
• 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 плагина
• parentPath: необязательный путь родительской команды для вложенных групп команд, например ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Управление учётными записями Matrix, проверкой, устройствами и состоянием профиля",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Захват или отрисовка содержимого холста с сопряжённого узла",
        hasSubcommands: true,
      },
    ],
  },
);

​

Регистрация бэкенда CLI

• Идентификатор бэкенда id становится префиксом провайдера в ссылках на модели, таких как my-cli/gpt-5.
• Конфигурация бэкенда config имеет ту же структуру, что и agents.defaults.cliBackends.<id>.
• Пользовательская конфигурация по-прежнему имеет приоритет. Перед запуском CLI OpenClaw объединяет agents.defaults.cliBackends.<id> с конфигурацией плагина по умолчанию, применяя пользовательские значения поверх неё.
• Используйте normalizeConfig, когда бэкенду после объединения требуется преобразование для совместимости (например, нормализация старых форм флагов).
• Используйте resolveExecutionArgs для относящихся к запросу преобразований argv, которые принадлежат диалекту CLI, например для сопоставления уровней рассуждения OpenClaw с нативным флагом интенсивности. Хук получает ctx.executionMode; используйте "side-question", чтобы добавить нативные для бэкенда флаги изоляции для эфемерных вызовов /btw. Если эти флаги надёжно отключают нативные инструменты для CLI, в котором они иначе всегда включены, также объявите sideQuestionToolMode: "disabled".
• Используйте prepareExecution для принадлежащего бэкенду окружения запуска или временных мостов аутентификации/конфигурации. Его ctx.contextTokenBudget — это фактический лимит токенов, выбранный для запуска, благодаря чему бэкенды с нативной Compaction могут согласовать собственный порог без специфичных для провайдера ветвей в ядре.
• Бэкенды, способные отключить все нативные инструменты для конкретного запуска, могут объявить nativeToolMode: "selectable". Ограниченные вызовы передают пустой кортеж ctx.toolAvailability.native вместе с точным списком разрешённых MCP, изолированным на уровне хоста; resolveExecutionArgs должен обеспечить соблюдение обоих ограничений в итоговом argv для нового или возобновлённого запуска. Если бэкенд не может это сделать, OpenClaw блокирует выполнение.

​

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

​

Устаревшие адаптеры векторных представлений памяти

• registerMemoryCapability — предпочтительный эксклюзивный API плагина памяти.
• registerMemoryCapability также может предоставлять publicArtifacts.listArtifacts(...), чтобы сопутствующие плагины могли получать экспортированные артефакты памяти через openclaw/plugin-sdk/memory-host-core, не обращаясь к закрытой структуре каталогов конкретного плагина памяти.
• registerMemoryPromptSection, registerMemoryFlushPlan и registerMemoryRuntime — эксклюзивные API плагинов памяти с поддержкой устаревшей совместимости.
• MemoryFlushPlan.model может привязать ход сброса к точной ссылке provider/model, например ollama/qwen3:8b, не наследуя активную цепочку резервных вариантов.
• registerMemoryEmbeddingProvider устарел. Новые провайдеры векторных представлений должны использовать api.registerEmbeddingProvider(...) и contracts.embeddingProviders.
• Существующие провайдеры, специфичные для памяти, продолжают работать в течение периода миграции, однако для плагинов, не входящих в комплект, проверка плагинов сообщает об этом как о долге совместимости.

​

События и жизненный цикл

​

Семантика решений хуков

• 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: отслеживает принадлежащие Gateway изменения жизненного цикла Cron. События scheduled и removed являются подсказками для согласования после фиксации, а не упорядоченным журналом изменений. В запланированном событии event.nextRunAtMs отсутствует, если у задания нет следующего пробуждения; событие удаления по-прежнему содержит снимок удалённого задания.

​

Поля объекта API

​

Соглашение для внутренних модулей

my-plugin/
  api.ts            # Публичные экспорты для внешних потребителей
  runtime-api.ts    # Внутренние экспорты только для среды выполнения
  index.ts          # Точка входа плагина
  setup-entry.ts    # Облегчённая точка входа только для настройки (необязательно)

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

​

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