Налаштування та конфігурація 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.*) залишаються у власності core і завжди розв’язуються в 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": {}  }}

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

{  "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);

Це дає змогу не завантажувати важкий runtime-код (криптографічні бібліотеки, реєстрації CLI, фонові служби) під час потоків налаштування.

Вбудовані канали робочого простору, які тримають безпечні для налаштування експорти в допоміжних модулях, можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей вбудований контракт також підтримує необов’язковий експорт runtime, щоб wiring runtime під час налаштування залишався легким і явним.

Вузькі імпорти помічників налаштування

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

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

Використовуйте createSetupTranslator(...) для фіксованого тексту майстра налаштування. Він дотримується локалі майстра CLI (OPENCLAW_LOCALE, потім системних змінних локалі) і повертається до англійської. Зберігайте специфічний для Plugin текст налаштування в коді, яким володіє Plugin, і використовуйте спільні ключі каталогу лише для поширених міток налаштування, тексту статусу та офіційного тексту налаштування вбудованих Plugin.

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

Просування одного облікового запису, яким володіє канал

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

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

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

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

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

{  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 на шляхах метаданих:

  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> без завантаження runtime-коду.

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

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

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

Зовнішні плагіни: опублікуйте в ClawHub, потім установіть:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Плагіни в репозиторії: розмістіть їх у дереві робочої області вбудованих плагінів, і їх буде автоматично виявлено під час збірки.

Користувачі можуть установити:

openclaw plugins install <package-name>

Метадані вбудованого пакета є явними, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності мають бути в пакеті плагіна, якому вони належать; запуск упакованого OpenClaw ніколи не виправляє й не дзеркалює залежності плагінів.

Пов’язане

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