Точки входа Plugin

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

​

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 необязателен. Если он опущен, OpenClaw использует строгую схему пустого объекта, а сгенерированный манифест все равно включает configSchema.
• execute возвращает простую строку или JSON-сериализуемое значение. Вспомогательная функция оборачивает его как текстовый результат инструмента с details.
• Имена инструментов статичны. openclaw plugins build выводит contracts.tools из объявленных инструментов, поэтому авторам не нужно вручную дублировать имена.
• Загрузка среды выполнения остается строгой. Установленным Plugin по-прежнему нужны openclaw.plugin.json и package.json openclaw.extensions; OpenClaw не выполняет код Plugin для вывода отсутствующих данных манифеста.

​

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.
• kind предназначен для эксклюзивных слотов: "memory" или "context-engine".
• configSchema может быть функцией для ленивого вычисления.
• 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 вызывается во время регистрации, чтобы вы могли сохранить ссылку на среду выполнения (обычно через createPluginRuntimeStore). Он пропускается во время захвата метаданных CLI.
• registerCliMetadata выполняется во время api.registrationMode === "cli-metadata", api.registrationMode === "discovery" и api.registrationMode === "full". Используйте его как каноническое место для принадлежащих каналу дескрипторов CLI, чтобы корневая справка оставалась неактивирующей, снимки обнаружения включали статические метаданные команд, а обычная регистрация команд CLI оставалась совместимой с полной загрузкой Plugin.
• Регистрация обнаружения не активирует Plugin, но не свободна от импортов. OpenClaw может вычислять доверенную точку входа Plugin и модуль channel Plugin для построения снимка, поэтому держите импорты верхнего уровня без побочных эффектов и размещайте сокеты, клиенты, воркеры и сервисы за путями только для "full".
• registerFull выполняется только когда api.registrationMode === "full". Он пропускается при загрузке только для настройки.
• Как и definePluginEntry, configSchema может быть ленивой фабрикой, и OpenClaw мемоизирует разрешенную схему при первом доступе.
• Для принадлежащих Plugin корневых команд CLI предпочитайте api.registerCli(..., { descriptors: [...] }), когда хотите, чтобы команда оставалась лениво загружаемой и при этом не исчезала из корневого дерева разбора CLI. Для команд функций парных узлов предпочитайте api.registerNodeCliFeature(...), чтобы команда попадала под openclaw nodes. Для других вложенных команд Plugin добавьте parentPath и регистрируйте команды на объекте program, переданном регистратору; OpenClaw разрешает его в родительскую команду перед вызовом Plugin. Для channel Plugin предпочитайте регистрировать эти дескрипторы из registerCliMetadata(...) и держать registerFull(...) сосредоточенным на работе только среды выполнения.
• Если registerFull(...) также регистрирует методы Gateway RPC, держите их на префиксе, специфичном для Plugin. Зарезервированные пространства имен администрирования ядра (config.*, exec.approvals.*, wizard.*, update.*) всегда приводятся к operator.admin.

​

defineSetupPluginEntry

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

export default defineSetupPluginEntry(myChannelPlugin);

• openclaw/plugin-sdk/setup-runtime для безопасных для среды выполнения вспомогательных функций настройки, таких как createSetupTranslator, import-safe адаптеры патчей настройки, вывод примечаний поиска, promptResolvedAllowFrom, splitSetupEntries и делегированные прокси настройки
• openclaw/plugin-sdk/channel-setup для поверхностей настройки optional-install
• openclaw/plugin-sdk/setup-tools для вспомогательных функций CLI/архива/документации настройки и установки

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) => {
        /* setup-safe route */
      },
    });
  },
});

​

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

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

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

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

• используйте descriptors, когда регистратор владеет одной или несколькими корневыми командами и вы хотите, чтобы OpenClaw лениво загружал настоящий модуль CLI при первом вызове
• убедитесь, что эти дескрипторы покрывают каждый корень команды верхнего уровня, предоставляемый регистратором
• ограничивайте имена команд в дескрипторах буквами, цифрами, дефисом и подчеркиванием, начиная с буквы или цифры; OpenClaw отклоняет имена дескрипторов вне этой формы и удаляет терминальные управляющие последовательности из описаний перед отображением справки
• используйте только commands лишь для путей энергичной совместимости

​

Формы Plugin

​

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

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