openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 14:35:54 +00:00
parent 0978fe0919
commit f859338078
2 changed files with 605 additions and 601 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

987
docs/uk/plugins/manifest.md
View File

File diff suppressed because it is too large Load Diff

219
docs/uk/plugins/sdk-setup.md
View File

@ -1,32 +1,32 @@
---
read_when:
- Ви додаєте майстер налаштування для Plugin
- Ви додаєте майстер налаштування до Plugin
- Потрібно зрозуміти setup-entry.ts порівняно з index.ts
- Ви визначаєте схеми конфігурації Plugin або метадані openclaw у package.json
- Ви визначаєте схеми конфігурації плагіна або метадані openclaw у package.json
sidebarTitle: Setup and config
summary: Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json
title: Налаштування та конфігурація Plugin
x-i18n:
generated_at: "2026-05-02T02:49:26Z"
generated_at: "2026-05-02T14:31:50Z"
model: gpt-5.5
provider: openai
source_hash: 322cf8988da686d5bf7577f9825f6f8decb738f91563e4022c14bf16dca22824
source_hash: 9474dbbbc984e19019f7d14c7d63d944c544868407f7908df282bc7c080dc0c2
source_path: plugins/sdk-setup.md
workflow: 16
---
Довідка з пакування Plugin (метадані `package.json`), маніфестів (`openclaw.plugin.json`), записів налаштування та схем конфігурації.
Довідник із пакування плагінів (метадані `package.json`), маніфестів (`openclaw.plugin.json`), записів налаштування та схем конфігурації.
<Tip>
**Шукаєте покроковий посібник?** Практичні посібники розглядають пакування в контексті: [Plugin каналів](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і [Plugin провайдерів](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest).
**Шукаєте покроковий посібник?** Практичні посібники охоплюють пакування в контексті: [Плагіни каналів](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest).
</Tip>
## Метадані пакета
Ваш `package.json` потребує поля `openclaw`, яке повідомляє системі Plugin, що надає ваш Plugin:
Ваш `package.json` потребує поля `openclaw`, яке повідомляє системі плагінів, що надає ваш плагін:
<Tabs>
<Tab title="Channel plugin">
<Tab title="Плагін каналу">
```json
{
"name": "@myorg/openclaw-my-channel",
@ -44,7 +44,7 @@ x-i18n:
}
```
</Tab>
<Tab title="Provider plugin / ClawHub baseline">
<Tab title="Плагін провайдера / базовий шаблон ClawHub">
```json openclaw-clawhub-package.json
{
"name": "@myorg/openclaw-my-plugin",
@ -67,7 +67,7 @@ x-i18n:
</Tabs>
<Note>
Якщо ви публікуєте Plugin зовнішньо на ClawHub, ці поля `compat` і `build` є обов’язковими. Канонічні фрагменти для публікації розташовані в `docs/snippets/plugin-publish/`.
Якщо ви публікуєте плагін зовнішньо в ClawHub, ці поля `compat` і `build` є обов’язковими. Канонічні фрагменти для публікації розміщені в `docs/snippets/plugin-publish/`.
</Note>
### Поля `openclaw`
@ -79,43 +79,43 @@ x-i18n:
Легка точка входу лише для налаштування (необов’язково).
</ParamField>
<ParamField path="channel" type="object">
Метадані каталогу каналів для поверхонь налаштування, вибору, швидкого старту та стану.
Метадані каталогу каналів для поверхонь налаштування, вибору, швидкого старту та статусу.
</ParamField>
<ParamField path="providers" type="string[]">
Ідентифікатори провайдерів, зареєстровані цим Plugin.
Ідентифікатори провайдерів, які реєструє цей плагін.
</ParamField>
<ParamField path="install" type="object">
Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery`.
</ParamField>
<ParamField path="startup" type="object">
Прапорці поведінки під час запуску.
Прапорці поведінки запуску.
</ParamField>
### `openclaw.channel`
`openclaw.channel` — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження runtime.
`openclaw.channel` — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження середовища виконання.
| Поле | Тип | Що це означає |
| Поле | Тип | Що означає |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| `id` | `string` | Канонічний ідентифікатор каналу. |
| `label` | `string` | Основна мітка каналу. |
| `selectionLabel` | `string` | Мітка вибору/налаштування, коли вона має відрізнятися від `label`. |
| `detailLabel` | `string` | Вторинна докладна мітка для розширених каталогів каналів і поверхонь стану. |
| `detailLabel` | `string` | Вторинна докладна мітка для розширених каталогів каналів і поверхонь статусу. |
| `docsPath` | `string` | Шлях документації для посилань налаштування й вибору. |
| `docsLabel` | `string` | Перевизначає мітку, використану для посилань на документацію, коли вона має відрізнятися від ідентифікатора каналу. |
| `blurb` | `string` | Короткий опис для onboarding/каталогу. |
| `docsLabel` | `string` | Перевизначена мітка для посилань документації, коли вона має відрізнятися від ідентифікатора каналу. |
| `blurb` | `string` | Короткий опис для первинного налаштування/каталогу. |
| `order` | `number` | Порядок сортування в каталогах каналів. |
| `aliases` | `string[]` | Додаткові псевдоніми пошуку для вибору каналу. |
| `preferOver` | `string[]` | Ідентифікатори Plugin/каналів із нижчим пріоритетом, які цей канал має випереджати. |
| `systemImage` | `string` | Необов’язкова назва іконки/system-image для UI-каталогів каналів. |
| `selectionDocsPrefix` | `string` | Текст префікса перед посиланнями на документацію в поверхнях вибору. |
| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість підписаного посилання на документацію в тексті вибору. |
| `selectionExtras` | `string[]` | Додаткові короткі рядки, додані до тексту вибору. |
| `preferOver` | `string[]` | Ідентифікатори плагінів/каналів нижчого пріоритету, які цей канал має випереджати. |
| `systemImage` | `string` | Необов’язкова назва іконки/system-image для UI-каталогів каналу. |
| `selectionDocsPrefix` | `string` | Текст префікса перед посиланнями документації в поверхнях вибору. |
| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість підписаного посилання документації в тексті вибору. |
| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються до тексту вибору. |
| `markdownCapable` | `boolean` | Позначає канал як здатний працювати з Markdown для рішень щодо вихідного форматування. |
| `exposure` | `object` | Керування видимістю каналу для налаштування, списків налаштованого та поверхонь документації. |
| `quickstartAllowFrom` | `boolean` | Додає цей канал до стандартного потоку налаштування швидкого старту `allowFrom`. |
| `forceAccountBinding` | `boolean` | Вимагати явну прив’язку облікового запису, навіть коли існує лише один обліковий запис. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | Надавати перевагу пошуку сеансу під час визначення цілей оголошень для цього каналу. |
| `exposure` | `object` | Параметри видимості каналу для налаштування, списків налаштованого та поверхонь документації. |
| `quickstartAllowFrom` | `boolean` | Додає цей канал до стандартного процесу налаштування швидкого старту `allowFrom`. |
| `forceAccountBinding` | `boolean` | Вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку сеансу під час визначення цілей оголошень для цього каналу. |
Приклад:
@ -149,8 +149,8 @@ x-i18n:
`exposure` підтримує:
- `configured`: включати канал у поверхні списків налаштованого/стану
- `setup`: включати канал в інтерактивні засоби вибору налаштування/конфігурування
- `configured`: включати канал у налаштовані/статусні поверхні списків
- `setup`: включати канал в інтерактивні селектори налаштування/конфігурування
- `docs`: позначати канал як публічний у поверхнях документації/навігації
<Note>
@ -161,24 +161,25 @@ x-i18n:
`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 у комплекті відновлюватися після конкретних збоїв через застарілу конфігурацію. |
| Поле | Тип | Що означає |
| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
| `clawhubSpec` | `string` | Канонічна специфікація ClawHub для процесів встановлення/оновлення та встановлення на вимогу під час первинного налаштування. |
| `npmSpec` | `string` | Канонічна специфікація npm для резервних процесів встановлення/оновлення. |
| `localPath` | `string` | Шлях локальної розробки або вбудованого встановлення. |
| `defaultChoice` | `"clawhub"` \| `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступно кілька джерел. |
| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у форматі `>=x.y.z` або `>=x.y.z-prerelease`. |
| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm-дистрибутива, зазвичай `sha512-...`, для закріплених встановлень. |
| `allowInvalidConfigRecovery` | `boolean` | Дає змогу процесам перевстановлення вбудованого плагіна відновлюватися після конкретних збоїв через застарілу конфігурацію. |
<AccordionGroup>
<Accordion title="Onboarding behavior">
Інтерактивний onboarding також використовує `openclaw.install` для поверхонь встановлення на вимогу. Якщо ваш Plugin надає вибір автентифікації провайдера або метадані налаштування/каталогу каналу до завантаження runtime, onboarding може показати цей вибір, запропонувати npm або локальне встановлення, встановити чи ввімкнути Plugin, а потім продовжити вибраний потік. Варіанти npm для onboarding потребують довірених метаданих каталогу з реєстровим `npmSpec`; точні версії та `expectedIntegrity` є необов’язковими закріпленнями. Якщо `expectedIntegrity` присутній, потоки встановлення/оновлення забезпечують його дотримання. Зберігайте метадані "що показувати" в `openclaw.plugin.json`, а метадані "як це встановити" — у `package.json`.
<Accordion title="Поведінка первинного налаштування">
Інтерактивне первинне налаштування також використовує `openclaw.install` для поверхонь встановлення на вимогу. Якщо ваш плагін надає варіанти автентифікації провайдера або метадані налаштування/каталогу каналу до завантаження середовища виконання, первинне налаштування може показати цей вибір, запропонувати встановлення з ClawHub, npm або локального джерела, встановити чи ввімкнути плагін, а потім продовжити вибраний процес. Варіанти ClawHub для первинного налаштування використовують `clawhubSpec` і мають перевагу, коли вони наявні; варіанти npm потребують довірених метаданих каталогу з реєстровим `npmSpec`; точні версії та `expectedIntegrity` є необов’язковими npm-закріпленнями. Якщо `expectedIntegrity` наявний, процеси встановлення/оновлення застосовують його для npm. Зберігайте метадані «що показувати» в `openclaw.plugin.json`, а метадані «як це встановити» — у `package.json`.
</Accordion>
<Accordion title="minHostVersion enforcement">
Якщо `minHostVersion` задано, і встановлення, і завантаження реєстру маніфестів для невбудованих Plugin забезпечують його дотримання. Старіші хости пропускають зовнішні Plugin; недійсні рядки версій відхиляються. Вбудовані вихідні Plugin вважаються версіонованими разом із checkout хоста.
<Accordion title="Застосування minHostVersion">
Якщо `minHostVersion` задано, і встановлення, і завантаження невбудованого реєстру маніфестів застосовують це обмеження. Старіші хости пропускають зовнішні плагіни; недійсні рядки версій відхиляються. Вважається, що вбудовані вихідні плагіни мають ту саму версію, що й робоча копія хоста.
</Accordion>
<Accordion title="Pinned npm installs">
Для закріплених npm-встановлень зберігайте точну версію в `npmSpec` і додайте очікувану цілісність артефакта:
<Accordion title="Закріплені встановлення npm">
Для закріплених встановлень npm зберігайте точну версію в `npmSpec` і додайте очікувану цілісність артефакту:
```json
{
@ -193,14 +194,14 @@ x-i18n:
```
</Accordion>
<Accordion title="allowInvalidConfigRecovery scope">
`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення Plugin у комплекті, щоб перевстановлення/налаштування могло виправити відомі залишки після оновлення, як-от відсутній шлях Plugin у комплекті або застарілий запис `channels.<id>` для того самого Plugin. Якщо конфігурація зламана з не пов’язаних причин, встановлення все одно безпечно завершується помилкою й повідомляє оператору запустити `openclaw doctor --fix`.
<Accordion title="Область дії allowInvalidConfigRecovery">
`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Він призначений лише для вузького відновлення вбудованих плагінів, щоб перевстановлення/налаштування могло виправляти відомі залишки після оновлення, як-от відсутній шлях вбудованого плагіна або застарілий запис `channels.<id>` для того самого плагіна. Якщо конфігурація зламана з непов’язаних причин, встановлення все одно завершується відмовою й повідомляє оператору запустити `openclaw doctor --fix`.
</Accordion>
</AccordionGroup>
### Відкладене повне завантаження
Plugin каналів можуть увімкнути відкладене завантаження за допомогою:
Плагіни каналів можуть увімкнути відкладене завантаження так:
```json
{
@ -214,17 +215,17 @@ Plugin каналів можуть увімкнути відкладене за
}
```
Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до початку прослуховування, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway починає прослуховування.
Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску перед прослуховуванням, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway починає прослуховування.
<Warning>
Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що потрібно Gateway до початку прослуховування (реєстрація каналу, HTTP-маршрути, методи gateway). Якщо повна точка входу володіє потрібними можливостями запуску, залиште поведінку за замовчуванням.
Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що потрібно Gateway до початку прослуховування (реєстрація каналу, HTTP-маршрути, методи Gateway). Якщо повна точка входу володіє потрібними можливостями запуску, залиште стандартну поведінку.
</Warning>
Якщо ваша точка входу setup/full реєструє gateway RPC-методи, тримайте їх на префіксі, специфічному для Plugin. Зарезервовані основні простори імен адміністратора (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності core і завжди вирішуються до `operator.admin`.
Якщо ваша точка входу setup/full реєструє RPC-методи Gateway, тримайте їх на префіксі, специфічному для плагіна. Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності ядра й завжди розв’язуються до `operator.admin`.
## Маніфест Plugin
Кожен нативний Plugin має постачати `openclaw.plugin.json` у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду Plugin.
Кожен нативний плагін має містити `openclaw.plugin.json` у корені пакета. OpenClaw використовує його для перевірки конфігурації без виконання коду плагіна.
```json
{
@ -244,7 +245,7 @@ Plugin каналів можуть увімкнути відкладене за
}
```
Для Plugin каналів додайте `kind` і `channels`:
Для плагінів каналів додайте `kind` і `channels`:
```json
{
@ -259,7 +260,7 @@ Plugin каналів можуть увімкнути відкладене за
}
```
Навіть Plugin без конфігурації мають постачати схему. Порожня схема є дійсною:
Навіть плагіни без конфігурації мають містити схему. Порожня схема є дійсною:
```json
{
@ -271,11 +272,11 @@ Plugin каналів можуть увімкнути відкладене за
}
```
Див. [Маніфест Plugin](/uk/plugins/manifest) для повної довідки зі схеми.
Див. [Маніфест Plugin](/uk/plugins/manifest), щоб отримати повну довідку зі схеми.
## Публікація ClawHub
## Публікація в ClawHub
Для пакетів Plugin використовуйте специфічну для пакетів команду ClawHub:
Для пакетів плагінів використовуйте специфічну для пакета команду ClawHub:
```bash
clawhub package publish your-org/your-plugin --dry-run
@ -288,7 +289,7 @@ clawhub package publish your-org/your-plugin
## Запис налаштування
Файл `setup-entry.ts` є легкою альтернативою `index.ts`, яку OpenClaw завантажує, коли потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, перевірка вимкненого каналу).
Файл `setup-entry.ts` — це легка альтернатива `index.ts`, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (первинне налаштування, відновлення конфігурації, інспекція вимкненого каналу).
```typescript
// setup-entry.ts
@ -298,65 +299,65 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
Це уникає завантаження важкого коду runtime (криптографічних бібліотек, реєстрацій CLI, фонових сервісів) під час потоків налаштування.
Це дає змогу не завантажувати важкий код виконання (криптографічні бібліотеки, реєстрації CLI, фонові служби) під час потоків налаштування.
Вбудовані канали робочої області, які тримають безпечні для налаштування експорти в супровідних модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість `defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий експорт `runtime`, щоб runtime-зв’язування під час налаштування залишалося легким і явним.
Вбудовані канали робочої області, які тримають безпечні для налаштування експорти в допоміжних модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість `defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий експорт `runtime`, щоб зв’язування середовища виконання під час налаштування залишалося легким і явним.
<AccordionGroup>
<Accordion title="Коли OpenClaw використовує setupEntry замість повного entry">
- Канал вимкнено, але йому потрібні поверхні налаштування/онбордингу.
<Accordion title="Коли OpenClaw використовує setupEntry замість повного запису">
- Канал вимкнено, але йому потрібні поверхні налаштування/первинного налаштування.
- Канал увімкнено, але не налаштовано.
- Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`).
</Accordion>
<Accordion title="Що setupEntry має реєструвати">
<Accordion title="Що має зареєструвати setupEntry">
- Об’єкт Plugin каналу (через `defineSetupPluginEntry`).
- Будь-які HTTP-маршрути, потрібні до запуску прослуховування Gateway.
- Будь-які методи Gateway, потрібні під час запуску.
- Будь-які HTTP-маршрути, потрібні до прослуховування gateway.
- Будь-які методи gateway, потрібні під час запуску.
Ці стартові методи Gateway все одно мають уникати зарезервованих core-просторів імен адміністрування, як-от `config.*` або `update.*`.
Ці методи gateway запуску все одно мають уникати зарезервованих просторів імен адміністрування ядра, як-от `config.*` або `update.*`.
</Accordion>
<Accordion title="Чого setupEntry НЕ має містити">
- Реєстрацій CLI.
- Фонових сервісів.
- Важких імпортів runtime (криптографія, SDK).
- Методів Gateway, потрібних лише після запуску.
<Accordion title="Що setupEntry НЕ має містити">
- Реєстрації CLI.
- Фонові служби.
- Важкі імпорти середовища виконання (crypto, SDK).
- Методи Gateway, потрібні лише після запуску.
</Accordion>
</AccordionGroup>
### Вузькі імпорти допоміжних засобів налаштування
### Вузькі імпорти помічників налаштування
Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшої обгортки `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування:
Для гарячих шляхів лише налаштування надавайте перевагу вузьким швам помічників налаштування замість ширшого парасолькового `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування:
| Шлях імпорту | Для чого використовувати | Ключові експорти |
| Шлях імпорту | Для чого використовувати | Ключові експорти |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | runtime-допоміжні засоби під час налаштування, які залишаються доступними в `setupEntry` / відкладеному запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-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-tools` | помічники CLI/archive/docs для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний інструментарій налаштування, зокрема допоміжні засоби патчів конфігурації, як-от `moveSingleAccountChannelSectionToDefaultAccount(...)`.
Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний набір інструментів налаштування, зокрема помічники виправлення конфігурації, як-от `moveSingleAccountChannelSectionToDefaultAccount(...)`.
Адаптери патчів налаштування залишаються безпечними для імпорту на гарячому шляху. Їхній пошук поверхні контракту вбудованого підвищення одного облікового запису є лінивим, тож імпорт `plugin-sdk/setup-runtime` не завантажує заздалегідь виявлення вбудованої поверхні контракту до фактичного використання адаптера.
Адаптери виправлень налаштування безпечні для гарячого шляху під час імпорту. Їхній вбудований пошук поверхні контракту просування одного облікового запису є ледачим, тому імпорт `plugin-sdk/setup-runtime` не завантажує завчасно виявлення вбудованої поверхні контракту до фактичного використання адаптера.
### Підвищення одного облікового запису, що належить каналу
### Просування одного облікового запису, яким володіє канал
Коли канал переходить від конфігурації одного облікового запису верхнього рівня до `channels.<id>.accounts.*`, стандартна спільна поведінка переносить підвищені значення, прив’язані до облікового запису, в `accounts.default`.
Коли канал переходить від конфігурації верхнього рівня для одного облікового запису до `channels.<id>.accounts.*`, стандартна спільна поведінка переносить просунуті значення області облікового запису в `accounts.default`.
Вбудовані канали можуть звузити або перевизначити це підвищення через свою поверхню контракту налаштування:
Вбудовані канали можуть звузити або перевизначити це просування через свою поверхню контракту налаштування:
- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перенести до підвищеного облікового запису
- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці ключі переносяться до підвищеного облікового запису; спільні ключі політики/доставки залишаються в корені каналу
- `resolveSingleAccountPromotionTarget(...)`: вибирає, який наявний обліковий запис отримує підвищені значення
- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які мають перейти до просунутого облікового запису
- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці ключі переходять до просунутого облікового запису; спільні ключі політики/доставки залишаються в корені каналу
- `resolveSingleAccountPromotionTarget(...)`: вибрати, який наявний обліковий запис отримає просунуті значення
<Note>
Matrix є поточним вбудованим прикладом. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо `defaultAccount` вказує на наявний неканонічний ключ, як-от `Ops`, підвищення зберігає цей обліковий запис замість створення нового запису `accounts.default`.
Matrix є поточним вбудованим прикладом. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо `defaultAccount` вказує на наявний неканонічний ключ, як-от `Ops`, просування зберігає цей обліковий запис замість створення нового запису `accounts.default`.
</Note>
## Схема конфігурації
Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі налаштовують plugins через:
Конфігурація Plugin перевіряється за JSON Schema у вашому manifest. Користувачі налаштовують plugins через:
```json5
{
@ -387,7 +388,7 @@ Matrix є поточним вбудованим прикладом. Якщо в
}
```
### Побудова схем конфігурації каналу
### Побудова схем конфігурації каналів
Використовуйте `buildChannelConfigSchema`, щоб перетворити схему Zod на обгортку `ChannelConfigSchema`, яку використовують артефакти конфігурації, що належать Plugin:
@ -405,11 +406,11 @@ const accountSchema = z.object({
const configSchema = buildChannelConfigSchema(accountSchema);
```
Для сторонніх plugins контракт холодного шляху все ще є маніфестом Plugin: віддзеркальте згенеровану JSON Schema в `openclaw.plugin.json#channelConfigs`, щоб схема конфігурації, налаштування й UI-поверхні могли перевіряти `channels.<id>` без завантаження runtime-коду.
Для сторонніх plugins контракт холодного шляху все ще є manifest Plugin: віддзеркальте згенеровану JSON Schema в `openclaw.plugin.json#channelConfigs`, щоб схема конфігурації, налаштування та поверхні UI могли інспектувати `channels.<id>` без завантаження коду виконання.
## Майстри налаштування
Plugins каналів можуть надавати інтерактивні майстри налаштування для `openclaw onboard`. Майстер є об’єктом `ChannelSetupWizard` у `ChannelPlugin`:
Plugins каналів можуть надавати інтерактивні майстри налаштування для `openclaw onboard`. Майстер — це об’єкт `ChannelSetupWizard` на `ChannelPlugin`:
```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
@ -442,14 +443,14 @@ const setupWizard: ChannelSetupWizard = {
};
```
Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, `dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` тощо. Повні приклади дивіться у вбудованих пакетах Plugin (наприклад, Plugin Discord `src/channel.setup.ts`).
Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, `dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` та інше. Повні приклади дивіться у вбудованих пакетах plugins (наприклад, Plugin Discord `src/channel.setup.ts`).
<AccordionGroup>
<Accordion title="Спільні запити allowFrom">
Для запитів списку дозволених DM, яким потрібен лише стандартний потік `note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним допоміжним засобам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`.
<Accordion title="Спільні prompts allowFrom">
Для prompts списку дозволених DM, яким потрібен лише стандартний потік `note -> prompt -> parse -> merge -> patch`, надавайте перевагу спільним помічникам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`.
</Accordion>
<Accordion title="Стандартний статус налаштування каналу">
Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, віддавайте перевагу `createStandardChannelSetupStatus(...)` з `openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у кожному Plugin.
Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, надавайте перевагу `createStandardChannelSetupStatus(...)` з `openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у кожному Plugin.
</Accordion>
<Accordion title="Необов’язкова поверхня налаштування каналу">
Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте `createOptionalChannelSetupSurface` з `openclaw/plugin-sdk/channel-setup`:
@ -466,18 +467,18 @@ const setupWizard: ChannelSetupWizard = {
// Returns { setupAdapter, setupWizard }
```
`plugin-sdk/channel-setup` також надає нижчерівневі побудовники `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї поверхні необов’язкового встановлення.
`plugin-sdk/channel-setup` також надає нижчорівневі конструктори `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї необов’язкової поверхні встановлення.
Згенерований необов’язковий адаптер/майстер закрито відмовляє для реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення в `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на документацію, коли задано `docsPath`.
Згенерований необов’язковий адаптер/майстер закривається з відмовою для реальних записів конфігурації. Вони повторно використовують одне повідомлення про потрібне встановлення в `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на docs, коли задано `docsPath`.
</Accordion>
<Accordion title="Допоміжні засоби налаштування на основі binary">
Для UI налаштування на основі binary віддавайте перевагу спільним делегованим допоміжним засобам замість копіювання того самого зв’язування binary/статусу в кожен канал:
<Accordion title="Помічники налаштування на основі binary">
Для UI налаштування на основі binary надавайте перевагу спільним делегованим помічникам замість копіювання того самого зв’язувального коду binary/status у кожен канал:
- `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише мітками, підказками, оцінками та виявленням binary
- `createCliPathTextInput(...)` для текстових полів на основі шляху
- `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і `createDelegatedResolveConfigured(...)`, коли `setupEntry` потрібно ліниво переспрямовувати до важчого повного майстра
- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` потрібно лише делегувати рішення `textInputs[*].shouldPrompt`
- `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише мітками, підказками, оцінками та виявленням binary
- `createCliPathTextInput(...)` для текстових введень на основі шляху
- `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ледаче переспрямувати до важчого повного майстра
- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` має лише делегувати рішення `textInputs[*].shouldPrompt`
</Accordion>
</AccordionGroup>
@ -487,12 +488,12 @@ const setupWizard: ChannelSetupWizard = {
**Зовнішні plugins:** опублікуйте в [ClawHub](/uk/tools/clawhub), потім встановіть:
<Tabs>
<Tab title="Автоматично (ClawHub, потім npm)">
<Tab title="Автоматично (спочатку ClawHub, потім npm)">
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
OpenClaw спочатку пробує ClawHub і автоматично переходить до npm у разі невдачі.
OpenClaw спочатку пробує ClawHub і автоматично повертається до npm.
</Tab>
<Tab title="Лише ClawHub">
@ -500,9 +501,9 @@ const setupWizard: ChannelSetupWizard = {
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
</Tab>
<Tab title="Специфікація npm-пакета">
Використовуйте npm, коли пакет ще не переміщено до ClawHub або коли вам потрібен
прямий шлях встановлення npm під час міграції:
<Tab title="Специфікація пакета npm">
Використовуйте npm, коли пакет ще не переміщено до ClawHub або коли під час міграції потрібен
прямий шлях встановлення npm:
```bash
openclaw plugins install npm:@myorg/openclaw-my-plugin
@ -520,17 +521,17 @@ openclaw plugins install <package-name>
```
<Info>
Для встановлень із npm `openclaw plugins install` встановлює пакет у `~/.openclaw/npm` з вимкненими lifecycle-скриптами. Тримайте дерева залежностей Plugin чистими JS/TS і уникайте пакетів, які потребують `postinstall`-збірок.
Для інсталяцій із джерелом npm `openclaw plugins install` встановлює пакет у `~/.openclaw/npm` з вимкненими сценаріями життєвого циклу. Тримайте дерева залежностей Plugin суто JS/TS і уникайте пакетів, які потребують збірок `postinstall`.
</Info>
<Note>
Запуск Gateway не встановлює залежності Plugin. Потоки встановлення npm/git/ClawHub відповідають за збіжність залежностей; локальні plugins уже мають мати встановлені свої залежності.
Запуск Gateway не встановлює залежності Plugin. Потоки встановлення npm/git/ClawHub відповідають за узгодження залежностей; локальні plugins уже повинні мати встановлені залежності.
</Note>
Метадані вбудованого пакета задаються явно, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності мають бути в пакеті Plugin, якому вони належать; запуск пакетованого OpenClaw ніколи не виправляє й не дзеркалить залежності Plugin.
Метадані вбудованого пакета є явними, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності мають бути в пакеті Plugin, якому вони належать; запуск упакованого OpenClaw ніколи не відновлює й не дзеркалить залежності Plugin.
## Пов’язане
- [Створення plugins](/uk/plugins/building-plugins) — покроковий посібник для початку роботи
- [Маніфест Plugin](/uk/plugins/manifest) — повна довідка зі схеми маніфесту
- [Точки входу SDK](/uk/plugins/sdk-entrypoints) — `definePluginEntry` та `defineChannelPluginEntry`
- [Маніфест Plugin](/uk/plugins/manifest) — повний довідник схеми маніфесту
- [Точки входу SDK](/uk/plugins/sdk-entrypoints) — `definePluginEntry` і `defineChannelPluginEntry`