Настройка и конфигурация 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",  "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"    }  }}

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

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

Для пакетов plugin используйте команду ClawHub, предназначенную для пакетов:

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

Точка входа setup

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

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

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

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

Узкие импорты setup-хелперов

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

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

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

Адаптеры setup patch остаются безопасными для горячего пути при импорте. Их встроенный lookup поверхности контракта продвижения single-account ленивый, поэтому импорт plugin-sdk/setup-runtime не загружает заранее discovery встроенной contract-surface до фактического использования адаптера.

Продвижение single-account, принадлежащее каналу

Когда канал обновляется с top-level конфигурации single-account до channels.<id>.accounts.*, стандартное общее поведение переносит продвигаемые account-scoped значения в accounts.default.

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

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

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

Конфигурация Plugin проверяется по JSON Schema в вашем манифесте. Пользователи настраивают plugins через:

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

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

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

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

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

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

  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-to-JSON-Schema на путях metadata:

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

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

Мастера setup

Channel plugins могут предоставлять интерактивные мастера setup для 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 и многое другое. Полные примеры см. в пакетах встроенных plugins (например, plugin 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 }

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

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

openclaw plugins install @myorg/openclaw-my-plugin

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

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

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

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

openclaw plugins install <package-name>

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

См. также

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