Настройка и конфигурация плагина

Справочник по упаковке плагинов (метаданные package.json), манифестам (openclaw.plugin.json), точкам входа настройки и схемам конфигурации.

Метаданные пакета

Вашему package.json требуется поле openclaw, которое сообщает системе плагинов, какие возможности предоставляет ваш плагин:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

Поля openclaw

openclaw.channel

openclaw.channel — это легковесные метаданные пакета для обнаружения каналов и интерфейсов настройки до загрузки среды выполнения.

Пример:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure поддерживает:

• configured: включать канал в интерфейсы списков настроенных каналов и состояния
• setup: включать канал в интерактивные средства выбора при настройке и конфигурировании
• docs: помечать канал как общедоступный в документации и интерфейсах навигации

openclaw.install

openclaw.install относится к метаданным пакета, а не манифеста.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Отложенная полная загрузка

Плагины каналов могут включить отложенную загрузку с помощью:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Когда эта возможность включена, OpenClaw загружает только setupEntry на этапе запуска до начала прослушивания, даже для уже настроенных каналов. Полная точка входа загружается после того, как Gateway начинает прослушивание.

Если ваша установочная/полная точка входа регистрирует RPC-методы Gateway, используйте для них префикс конкретного плагина. Зарезервированные пространства имён администрирования ядра (config.*, exec.approvals.*, wizard.*, update.*) остаются под управлением ядра и всегда нормализуются в operator.admin.

Манифест плагина

Каждый нативный плагин должен содержать openclaw.plugin.json в корне пакета. OpenClaw использует его для проверки конфигурации без выполнения кода плагина.

{  "id": "my-plugin",  "name": "Мой плагин",  "description": "Добавляет возможности «Моего плагина» в OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Секрет проверки Webhook"      }    }  }}

Для плагинов каналов добавьте channels (а для плагинов провайдеров — providers):

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Даже плагины без конфигурации должны содержать схему. Допускается пустая схема:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Полное описание схемы см. в разделе Манифест плагина.

Публикация в ClawHub

Для пакетов Skills и плагинов используются разные команды публикации в ClawHub. Для пакетов плагинов используйте специальную команду пакета:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Установочная точка входа

setup-entry.ts — облегчённая альтернатива index.ts, которую OpenClaw загружает, когда требуются только установочные поверхности (первоначальная настройка, исправление конфигурации, проверка отключённого канала):

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Это позволяет не загружать тяжёлый код среды выполнения (криптографические библиотеки, регистрации CLI, фоновые службы) во время процессов установки.

Встроенные каналы рабочей области, хранящие безопасные для установки экспорты во вспомогательных модулях, могут использовать defineBundledChannelSetupEntry(...) из openclaw/plugin-sdk/channel-entry-contract вместо defineSetupPluginEntry(...). Этот контракт для встроенных компонентов также поддерживает необязательный экспорт runtime, благодаря чему связывание среды выполнения на этапе установки остаётся облегчённым и явным.

Узкие импорты вспомогательных функций установки

Для часто вызываемых путей, используемых только при установке, предпочитайте узкие интерфейсы вспомогательных функций установки более широкому универсальному интерфейсу plugin-sdk/setup, если вам нужна только часть установочной поверхности:

Используйте более широкий интерфейс plugin-sdk/setup, когда требуется полный общий набор инструментов установки, включая вспомогательные функции изменения конфигурации, такие как moveSingleAccountChannelSectionToDefaultAccount(...).

Используйте createSetupTranslator(...) для фиксированных текстов мастера установки. Он учитывает локаль мастера CLI (OPENCLAW_LOCALE, затем системные переменные локали) и при невозможности её определить использует английский язык. Храните текст установки, относящийся к конкретному плагину, в коде этого плагина, а общие ключи каталога используйте только для общих меток установки, текста состояния и установочных текстов официальных встроенных плагинов.

Импорт адаптеров изменений установки остаётся безопасным для часто вызываемых путей. Поиск поверхности контракта повышения встроенной конфигурации с одной учётной записью выполняется лениво, поэтому импорт plugin-sdk/setup-runtime не приводит к немедленной загрузке механизма обнаружения поверхности встроенного контракта до фактического использования адаптера.

Управляемое каналом повышение конфигурации с одной учётной записью

Когда канал переходит от конфигурации одной учётной записи верхнего уровня к channels.<id>.accounts.*, общее поведение по умолчанию перемещает повышаемые значения, относящиеся к учётной записи, в accounts.default.

Встроенные каналы могут сузить или переопределить это повышение через свою поверхность установочного контракта:

• singleAccountKeysToMove: дополнительные ключи верхнего уровня, которые следует переместить в повышаемую учётную запись
• namedAccountPromotionKeys: если именованные учётные записи уже существуют, в повышаемую учётную запись перемещаются только эти ключи; общие ключи политики/доставки остаются в корне канала
• resolveSingleAccountPromotionTarget(...): выбор существующей учётной записи, которая получит повышаемые значения

Схема конфигурации

Конфигурация плагина проверяется по JSON Schema из вашего манифеста. Пользователи настраивают плагины следующим образом:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

При регистрации ваш плагин получает эту конфигурацию как api.pluginConfig.

Для конфигурации конкретного канала используйте вместо этого раздел конфигурации канала:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Создание схем конфигурации каналов

Используйте buildChannelConfigSchema, чтобы преобразовать схему Zod в обёртку ChannelConfigSchema, используемую артефактами конфигурации, принадлежащими плагину:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

Если контракт уже описан в JSON Schema или TypeBox, используйте прямую вспомогательную функцию, чтобы OpenClaw мог пропустить преобразование Zod в JSON Schema на путях обработки метаданных:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Для сторонних плагинов контрактом для редко вызываемых путей по-прежнему служит манифест плагина: скопируйте созданную JSON Schema в openclaw.plugin.json#channelConfigs, чтобы поверхности конфигурации, установки и пользовательского интерфейса могли проверять channels.<id> без загрузки кода среды выполнения.

Мастера установки

Плагины каналов могут предоставлять интерактивные мастера установки для openclaw onboard. Мастер представляет собой объект ChannelSetupWizard в ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Подключено",    unconfiguredLabel: "Не настроено",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Токен бота",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Использовать MY_CHANNEL_BOT_TOKEN из окружения?",      keepPrompt: "Сохранить текущий токен?",      inputPrompt: "Введите токен бота:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

ChannelSetupWizard также поддерживает textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize и другие возможности. Полный пример встроенного плагина см. в src/setup-core.ts плагина Discord.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "Мой канал",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Возвращает { setupAdapter, setupWizard }

Публикация и установка

Внешние плагины: опубликуйте в ClawHub, затем установите:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Плагины в репозитории: размещайте их в дереве рабочего пространства встроенных плагинов; они автоматически обнаруживаются во время сборки.

Метаданные встроенных пакетов задаются явно, а не выводятся из собранного JavaScript при запуске Gateway. Зависимости среды выполнения должны находиться в пакете плагина, которому они принадлежат; запуск упакованного OpenClaw никогда не восстанавливает и не зеркалирует зависимости плагинов.

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

• Создание плагинов — пошаговое руководство по началу работы
• Манифест плагина — полный справочник по схеме манифеста
• Точки входа SDK — definePluginEntry и defineChannelPluginEntry