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

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

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

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

{  "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",  "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 — это недорогие метаданные пакета для обнаружения каналов и поверхностей настройки до загрузки runtime.

Пример:

{  "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"    }  }}

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

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

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

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

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

Манифест Plugin

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

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Для plugin каналов добавьте kind и channels:

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

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

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

См. манифест Plugin для полного справочника схемы.

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

Для пакетов плагинов используйте команду 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(...): выбор существующей учетной записи, которая получает повышенные значения

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

Конфигурация Plugin проверяется по 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())),  }),);

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

Мастера настройки

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

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

Тип ChannelSetupWizard поддерживает credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize и многое другое. Полные примеры см. в пакетах встроенных плагинов (например, в плагине Discord src/channel.setup.ts).

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

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

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

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Plugins в репозитории: разместите их в дереве рабочей области встроенных plugins, и они будут автоматически обнаружены во время сборки.

Пользователи могут установить:

openclaw plugins install <package-name>

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

См. также

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