36 KiB
| read_when | sidebarTitle | summary | title | x-i18n | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Setup and config | Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json | Налаштування та конфігурація Plugin |
|
Довідка з пакування Plugin (метадані package.json), маніфестів (openclaw.plugin.json), записів налаштування та схем конфігурації.
Метадані пакета
Ваш package.json потребує поля openclaw, яке повідомляє системі Plugin, що надає ваш Plugin:
Поля openclaw
Файли точок входу (відносно кореня пакета).
Легка точка входу лише для налаштування (необов’язково).
Метадані каталогу каналів для поверхонь налаштування, вибору, швидкого старту та стану.
Ідентифікатори провайдерів, зареєстровані цим Plugin.
Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery`.
Прапорці поведінки під час запуску.
openclaw.channel
openclaw.channel — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження runtime.
| Поле | Тип | Що це означає |
|---|---|---|
id |
string |
Канонічний ідентифікатор каналу. |
label |
string |
Основна мітка каналу. |
selectionLabel |
string |
Мітка вибору/налаштування, коли вона має відрізнятися від label. |
detailLabel |
string |
Вторинна докладна мітка для розширених каталогів каналів і поверхонь стану. |
docsPath |
string |
Шлях документації для посилань налаштування й вибору. |
docsLabel |
string |
Перевизначає мітку, використану для посилань на документацію, коли вона має відрізнятися від ідентифікатора каналу. |
blurb |
string |
Короткий опис для onboarding/каталогу. |
order |
number |
Порядок сортування в каталогах каналів. |
aliases |
string[] |
Додаткові псевдоніми пошуку для вибору каналу. |
preferOver |
string[] |
Ідентифікатори Plugin/каналів із нижчим пріоритетом, які цей канал має випереджати. |
systemImage |
string |
Необов’язкова назва іконки/system-image для UI-каталогів каналів. |
selectionDocsPrefix |
string |
Текст префікса перед посиланнями на документацію в поверхнях вибору. |
selectionDocsOmitLabel |
boolean |
Показувати шлях документації напряму замість підписаного посилання на документацію в тексті вибору. |
selectionExtras |
string[] |
Додаткові короткі рядки, додані до тексту вибору. |
markdownCapable |
boolean |
Позначає канал як здатний працювати з Markdown для рішень щодо вихідного форматування. |
exposure |
object |
Керування видимістю каналу для налаштування, списків налаштованого та поверхонь документації. |
quickstartAllowFrom |
boolean |
Додає цей канал до стандартного потоку налаштування швидкого старту allowFrom. |
forceAccountBinding |
boolean |
Вимагати явну прив’язку облікового запису, навіть коли існує лише один обліковий запис. |
preferSessionLookupForAnnounceTarget |
boolean |
Надавати перевагу пошуку сеансу під час визначення цілей оголошень для цього каналу. |
Приклад:
{
"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 — це метадані пакета, а не метадані маніфесту.
| Поле | Тип | Що це означає |
|---|---|---|
npmSpec |
string |
Канонічна npm-специфікація для потоків встановлення/оновлення. |
localPath |
string |
Локальний шлях розробки або шлях встановлення в комплекті. |
defaultChoice |
"npm" | "local" |
Бажане джерело встановлення, коли доступні обидва. |
minHostVersion |
string |
Мінімальна підтримувана версія OpenClaw у формі >=x.y.z або >=x.y.z-prerelease. |
expectedIntegrity |
string |
Очікуваний рядок цілісності npm dist, зазвичай sha512-..., для закріплених встановлень. |
allowInvalidConfigRecovery |
boolean |
Дозволяє потокам перевстановлення Plugin у комплекті відновлюватися після конкретних збоїв через застарілу конфігурацію. |
```json
{
"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 починає прослуховування.
Якщо ваша точка входу setup/full реєструє gateway RPC-методи, тримайте їх на префіксі, специфічному для 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": {}
}
}
Навіть Plugin без конфігурації мають постачати схему. Порожня схема є дійсною:
{
"id": "my-plugin",
"configSchema": {
"type": "object",
"additionalProperties": false
}
}
Див. Маніфест Plugin для повної довідки зі схеми.
Публікація ClawHub
Для пакетів Plugin використовуйте специфічну для пакетів команду ClawHub:
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
Запис налаштування
Файл setup-entry.ts є легкою альтернативою index.ts, яку OpenClaw завантажує, коли потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, перевірка вимкненого каналу).
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
Це уникає завантаження важкого коду runtime (криптографічних бібліотек, реєстрацій CLI, фонових сервісів) під час потоків налаштування.
Вбудовані канали робочої області, які тримають безпечні для налаштування експорти в супровідних модулях, можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей вбудований контракт також підтримує необов’язковий експорт runtime, щоб runtime-зв’язування під час налаштування залишалося легким і явним.
Ці стартові методи Gateway все одно мають уникати зарезервованих core-просторів імен адміністрування, як-от `config.*` або `update.*`.
Вузькі імпорти допоміжних засобів налаштування
Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшої обгортки plugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
| Шлях імпорту | Для чого використовувати | Ключові експорти |
|---|---|---|
plugin-sdk/setup-runtime |
runtime-допоміжні засоби під час налаштування, які залишаються доступними в setupEntry / відкладеному запуску каналу |
createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime |
адаптери налаштування облікового запису з урахуванням середовища | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools |
допоміжні засоби CLI/архівів/документації для налаштування/встановлення | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
Використовуйте ширший шов plugin-sdk/setup, коли вам потрібен повний спільний інструментарій налаштування, зокрема допоміжні засоби патчів конфігурації, як-от moveSingleAccountChannelSectionToDefaultAccount(...).
Адаптери патчів налаштування залишаються безпечними для імпорту на гарячому шляху. Їхній пошук поверхні контракту вбудованого підвищення одного облікового запису є лінивим, тож імпорт plugin-sdk/setup-runtime не завантажує заздалегідь виявлення вбудованої поверхні контракту до фактичного використання адаптера.
Підвищення одного облікового запису, що належить каналу
Коли канал переходить від конфігурації одного облікового запису верхнього рівня до channels.<id>.accounts.*, стандартна спільна поведінка переносить підвищені значення, прив’язані до облікового запису, в accounts.default.
Вбудовані канали можуть звузити або перевизначити це підвищення через свою поверхню контракту налаштування:
singleAccountKeysToMove: додаткові ключі верхнього рівня, які слід перенести до підвищеного облікового записуnamedAccountPromotionKeys: коли іменовані облікові записи вже існують, лише ці ключі переносяться до підвищеного облікового запису; спільні ключі політики/доставки залишаються в корені каналу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:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
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);
Для сторонніх plugins контракт холодного шляху все ще є маніфестом Plugin: віддзеркальте згенеровану JSON Schema в openclaw.plugin.json#channelConfigs, щоб схема конфігурації, налаштування й UI-поверхні могли перевіряти channels.<id> без завантаження runtime-коду.
Майстри налаштування
Plugins каналів можуть надавати інтерактивні майстри налаштування для openclaw onboard. Майстер є об’єктом ChannelSetupWizard у ChannelPlugin:
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
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).
```typescript
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-sdk/channel-setup` також надає нижчерівневі побудовники `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї поверхні необов’язкового встановлення.
Згенерований необов’язковий адаптер/майстер закрито відмовляє для реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення в `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на документацію, коли задано `docsPath`.
- `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише мітками, підказками, оцінками та виявленням binary
- `createCliPathTextInput(...)` для текстових полів на основі шляху
- `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і `createDelegatedResolveConfigured(...)`, коли `setupEntry` потрібно ліниво переспрямовувати до важчого повного майстра
- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` потрібно лише делегувати рішення `textInputs[*].shouldPrompt`
Публікація та встановлення
Зовнішні plugins: опублікуйте в ClawHub, потім встановіть:
```bash openclaw plugins install @myorg/openclaw-my-plugin ```OpenClaw спочатку пробує ClawHub і автоматично переходить до npm у разі невдачі.
```bash
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