Налаштування та конфігурація Plugin

Довідка щодо пакування плагінів (метаданих 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.

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

Кожен нативний 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 каналів додайте channels (а для Plugin постачальників — providers):

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

Навіть Plugin без конфігурації повинні постачати схему. Порожня схема є допустимою:

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

Повний довідник зі схеми див. у розділі Маніфест Plugin.

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

Пакети Skills і Plugin використовують окремі команди публікації в ClawHub. Для пакетів Plugin використовуйте спеціальну команду для пакетів:

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 текст налаштування в коді, що належить Plugin, а ключі спільного каталогу використовуйте лише для загальних міток налаштування, тексту стану й тексту налаштування офіційних вбудованих Plugin.

Адаптери виправлення налаштувань залишаються безпечними для імпорту в часто використовуваних шляхах. Пошук поверхні контракту для підвищення вбудованої конфігурації одного облікового запису виконується відкладено, тому імпорт plugin-sdk/setup-runtime не запускає завчасно виявлення поверхні вбудованого контракту, доки адаптер фактично не буде використано.

Підвищення конфігурації одного облікового запису, кероване каналом

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

Вбудовані канали можуть звузити або перевизначити це підвищення через свою поверхню контракту налаштування:

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

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

Конфігурація Plugin перевіряється за схемою JSON у вашому маніфесті. Користувачі налаштовують Plugin так:

{  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 або TypeBox, використовуйте безпосередній допоміжний засіб, щоб OpenClaw міг пропустити перетворення Zod на схему JSON у шляхах метаданих:

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

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

Майстри налаштування

Plugin каналів можуть надавати інтерактивні майстри налаштування для 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 також підтримує textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize тощо. Повний приклад вбудованого Plugin див. у файлі src/setup-core.ts Plugin Discord.

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 }

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

Зовнішні плагіни: опублікуйте в 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