Точки входа плагина

​

Точки входа пакета

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

• extensions и setupEntry — исходные точки входа, используемые при разработке в рабочей области и из рабочей копии git.
• runtimeExtensions и runtimeSetupEntry предпочтительны для установленных пакетов: благодаря им npm-пакетам не требуется компиляция TypeScript во время выполнения.
• Если runtimeExtensions присутствует, длина его массива должна совпадать с extensions (точки входа сопоставляются позиционно). Для runtimeSetupEntry требуется setupEntry.
• Если артефакт runtimeExtensions/runtimeSetupEntry объявлен, но отсутствует, установка или обнаружение завершается ошибкой упаковки; OpenClaw не выполняет неявный откат к исходному коду. Откат к исходному коду (описанный ниже) применяется, только если точка входа среды выполнения вообще не объявлена.
• Если установленный пакет объявляет только исходную точку входа TypeScript, OpenClaw ищет соответствующую собранную парную точку dist/*.js (либо .mjs/.cjs) и использует её; в противном случае выполняется откат к исходному коду TypeScript.
• Все пути точек входа должны оставаться внутри каталога пакета плагина. Точки входа среды выполнения и выведенные парные JS-файлы сборки не делают допустимым путь к исходному файлу extensions или setupEntry, выходящий за пределы каталога.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema необязателен; если его опустить, используется строгая схема пустого объекта (созданный манифест всё равно содержит configSchema).
• execute возвращает обычную строку или сериализуемое в JSON значение; вспомогательная функция оборачивает его в текстовый результат инструмента, задавая в details исходное (не преобразованное в строку) возвращаемое значение.
• Для пользовательских результатов инструментов openclaw/plugin-sdk/tool-results экспортирует textResult и jsonResult.
• Имена инструментов статичны, поэтому openclaw plugins build формирует contracts.tools из объявленных инструментов без ручного дублирования имён.
• Загрузка во время выполнения остаётся строгой: установленным плагинам по-прежнему необходимы openclaw.plugin.json и package.json openclaw.extensions. OpenClaw никогда не выполняет код плагина для вывода отсутствующих данных манифеста.

​

definePluginEntry

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

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({/* ... */});
    api.registerTool({/* ... */});
  },
});

• id должен соответствовать вашему манифесту openclaw.plugin.json.
• Внешние каталоги сеансов используют openclaw/plugin-sdk/session-catalog и api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). Ядро отвечает за методы Gateway sessions.catalog.*; провайдеры возвращают проекции узла, сеанса и нормализованной расшифровки, не регистрируя RPC.
• kind устарел: вместо него объявите эксклюзивный слот ("memory" или "context-engine") в поле kind манифеста openclaw.plugin.json. kind в точке входа среды выполнения сохраняется только как совместимый резервный вариант для старых плагинов.
• configSchema может быть функцией для отложенного вычисления. OpenClaw разрешает и мемоизирует схему при первом обращении, поэтому ресурсоёмкие построители схем запускаются только один раз.
• Дескриптор nodeHostCommands может определять isAvailable({ config, env }). Возврат false исключает эту команду и её возможность из объявления Gateway безголового узла. OpenClaw вычисляет это значение на основе локальной конфигурации запуска узла; обработчики команд всё равно должны проверять доступность при вызове.

​

defineChannelPluginEntry

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

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• setRuntime выполняется во всех режимах, кроме "cli-metadata" и "tool-discovery". Сохраните здесь ссылку на среду выполнения, обычно через createPluginRuntimeStore.
• registerCliMetadata выполняется для "cli-metadata", "discovery" и "full". Используйте его как каноническое место для принадлежащих каналу дескрипторов CLI, чтобы корневая справка не активировала плагин, снимки обнаружения содержали статические метаданные команд, а обычная регистрация CLI оставалась совместимой с полной загрузкой плагинов.
• registerFull выполняется только для "full" и "tool-discovery". Для "tool-discovery" он выполняется вместо регистрации канала: OpenClaw полностью пропускает registerChannel/setRuntime и вызывает только registerFull, поэтому вся регистрация провайдера или инструмента, необходимая каналу для автономного обнаружения или выполнения инструментов, должна находиться там, а не за обычной настройкой канала.
• Регистрация обнаружения не активирует плагин, но выполняет импорты: OpenClaw может вычислить доверенную точку входа плагина и модуль плагина канала для построения снимка. Импорты верхнего уровня не должны иметь побочных эффектов, а сокеты, клиенты, рабочие процессы и службы следует размещать только в путях "full".
• Как и definePluginEntry, configSchema может быть фабрикой с отложенным выполнением; OpenClaw мемоизирует разрешённую схему при первом обращении.

• Используйте api.registerCli(..., { descriptors: [...] }) для принадлежащих плагину корневых команд CLI, которые должны загружаться отложенно, не исчезая из дерева разбора корневого CLI. Имена дескрипторов должны состоять из букв, цифр, дефисов и символов подчёркивания и начинаться с буквы или цифры; OpenClaw отклоняет другие формы и удаляет управляющие последовательности терминала из описаний перед отображением справки. Охватите каждый корень команды верхнего уровня, предоставляемый регистратором. Один commands остаётся на пути ранней загрузки для совместимости.
• Используйте api.registerNodeCliFeature(...) для команд возможностей сопряжённого узла, чтобы они размещались в openclaw nodes (эквивалентно registerCli(registrar, { parentPath: ["nodes"], ... })).
• Для других вложенных команд плагина добавьте parentPath и регистрируйте команды в объекте program, переданном регистратору; OpenClaw разрешает его в родительскую команду перед вызовом плагина.
• Для плагинов каналов регистрируйте дескрипторы CLI из registerCliMetadata, а registerFull используйте только для работы среды выполнения.
• Если registerFull также регистрирует методы RPC Gateway, используйте для них префикс конкретного плагина. Зарезервированные административные пространства имён ядра (config.*, exec.approvals.*, wizard.*, update.*) всегда принудительно переводят режим в operator.admin.

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* безопасный для настройки маршрут */
      },
    });
  },
});

​

Режим регистрации

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  if (api.registrationMode === "tool-discovery") {
    // Регистрировать только поверхности возможностей (провайдеры/инструменты), без канала.
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Ресурсоёмкие регистрации только для среды выполнения
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

Формы плагинов

​

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

• Обзор SDK — API регистрации и справочник подпутей
• Вспомогательные функции среды выполнения — api.runtime и createPluginRuntimeStore
• Настройка и конфигурация — манифест, точка входа настройки, отложенная загрузка
• Плагины каналов — создание объекта ChannelPlugin
• Плагины провайдеров — регистрация провайдера и хуки