diff --git a/docs/uk/cli/doctor.md b/docs/uk/cli/doctor.md index 633407089..bc01a2140 100644 --- a/docs/uk/cli/doctor.md +++ b/docs/uk/cli/doctor.md @@ -1,21 +1,21 @@ --- read_when: - - У вас є проблеми з підключенням/автентифікацією, і ви хочете отримати покрокові виправлення - - Ви оновилися і хочете виконати базову перевірку працездатності -summary: Довідка CLI для `openclaw doctor` (перевірки працездатності + покрокові виправлення) -title: Лікар## + - У вас є проблеми з підключенням/автентифікацією, і ви хочете отримати керовані способи їх усунення + - Ви оновилися й хочете виконати базову перевірку працездатності +summary: Довідка CLI для `openclaw doctor` (перевірки стану + керовані виправлення) +title: Діагностика x-i18n: - generated_at: "2026-04-25T01:02:43Z" + generated_at: "2026-04-26T08:15:43Z" model: gpt-5.4 provider: openai - source_hash: 18e185d17d91d1677d0b16152d022b633d012d22d484bd9961820b200d5c4ce5 + source_hash: 1e2c21765f8c287c8d2aa066004ac516566c76a455337c377cf282551619e92a source_path: cli/doctor.md workflow: 15 --- # `openclaw doctor` -Перевірки працездатності + швидкі виправлення для Gateway і каналів. +Перевірки стану + швидкі виправлення для Gateway і каналів. Пов’язано: @@ -35,33 +35,34 @@ openclaw doctor --generate-gateway-token ## Параметри - `--no-workspace-suggestions`: вимкнути підказки щодо пам’яті/пошуку робочого простору -- `--yes`: приймати типові значення без запитів +- `--yes`: приймати значення за замовчуванням без запитів - `--repair`: застосувати рекомендовані виправлення без запитів - `--fix`: псевдонім для `--repair` -- `--force`: застосувати агресивні виправлення, зокрема перезаписати користувацьку конфігурацію сервісу за потреби +- `--force`: застосувати агресивні виправлення, зокрема перезаписати власну конфігурацію служби за потреби - `--non-interactive`: запуск без запитів; лише безпечні міграції - `--generate-gateway-token`: згенерувати й налаштувати токен Gateway -- `--deep`: сканувати системні сервіси на наявність додаткових встановлень Gateway +- `--deep`: сканувати системні служби на наявність додаткових установок Gateway Примітки: -- Інтерактивні запити (наприклад, виправлення keychain/OAuth) запускаються лише тоді, коли stdin є TTY і `--non-interactive` **не** встановлено. Безголові запуски (Cron, Telegram, без термінала) пропускатимуть запити. -- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження Plugin, щоб безголові перевірки працездатності залишалися швидкими. Інтерактивні сеанси, як і раніше, повністю завантажують Plugin, коли перевірці потрібен їхній внесок. -- `--fix` (псевдонім для `--repair`) записує резервну копію до `~/.openclaw/openclaw.json.bak` і видаляє невідомі ключі конфігурації, перелічуючи кожне видалення. -- Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів і можуть архівувати їх як `.deleted.`, щоб безпечно звільнити місце. -- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм завдань Cron і може переписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання. -- Doctor відновлює відсутні runtime-залежності вбудованих Plugin, не записуючи їх у глобальні пакетні встановлення. Для npm-встановлень із root-власником або жорстко захищених модулів systemd встановіть `OPENCLAW_PLUGIN_STAGE_DIR` у каталог із правом запису, наприклад `/var/lib/openclaw/plugin-runtime-deps`. -- Doctor автоматично мігрує застарілу пласку конфігурацію Talk (`talk.voiceId`, `talk.modelId` та подібні) до `talk.provider` + `talk.providers.`. -- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, якщо єдина відмінність — це порядок ключів об’єкта. +- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і `--non-interactive` **не** встановлено. У headless-запусках (Cron, Telegram, без термінала) запити буде пропущено. +- Продуктивність: неінтерактивні запуски `doctor` пропускають жадібне завантаження Plugin, щоб headless-перевірки стану залишалися швидкими. Інтерактивні сеанси, як і раніше, повністю завантажують Plugin, коли перевірці потрібен їхній внесок. +- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і видаляє невідомі ключі конфігурації, перелічуючи кожне видалення. +- Перевірки цілісності стану тепер виявляють осиротілі файли стенограм у каталозі сеансів і можуть архівувати їх як `.deleted.`, щоб безпечно звільнити місце. +- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм завдань Cron і може переписати їх на місці, перш ніж планувальник буде змушений автоматично нормалізувати їх під час виконання. +- Doctor відновлює відсутні залежності середовища виконання вбудованих Plugin без запису в упаковані глобальні встановлення. Для npm-встановлень, що належать root, або захищених модулів systemd, установіть `OPENCLAW_PLUGIN_STAGE_DIR` у каталог із правом запису, наприклад `/var/lib/openclaw/plugin-runtime-deps`. +- Установіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо життєвим циклом Gateway керує інший супервізор. Doctor, як і раніше, повідомляє про стан Gateway/служби й застосовує неслужбові виправлення, але пропускає встановлення/запуск/перезапуск/початкове налаштування служби та очищення застарілих служб. +- Doctor автоматично мігрує застарілу плоску конфігурацію Talk (`talk.voiceId`, `talk.modelId` та подібні) у `talk.provider` + `talk.providers.`. +- Повторні запуски `doctor --fix` більше не повідомляють/не застосовують нормалізацію Talk, якщо єдина відмінність полягає в порядку ключів об’єкта. - Doctor містить перевірку готовності пошуку в пам’яті й може рекомендувати `openclaw configure --section model`, якщо відсутні облікові дані для вбудовувань. -- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє виразне попередження з рекомендацією щодо усунення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). -- Якщо `gateway.auth.token`/`gateway.auth.password` керуються через SecretRef і недоступні в поточному шляху виконання команди, doctor повідомляє попередження лише для читання й не записує відкриті резервні облікові дані. -- Якщо перевірка SecretRef каналу завершується помилкою в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового завершення. -- Автоматичне визначення імен користувачів Telegram у `allowFrom` (`doctor --fix`) потребує токена Telegram, який можна визначити в поточному шляху виконання команди. Якщо перевірка токена недоступна, doctor повідомляє попередження і пропускає автоматичне визначення для цього запуску. +- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє про виразне попередження з варіантами усунення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). +- Якщо `gateway.auth.token`/`gateway.auth.password` керуються через SecretRef і недоступні в поточному шляху виконання команди, doctor повідомляє про попередження лише для читання і не записує резервні відкриті облікові дані. +- Якщо перевірка SecretRef каналу завершується помилкою на шляху виправлення, doctor продовжує роботу й повідомляє про попередження замість передчасного завершення. +- Автоматичне визначення імені користувача для Telegram `allowFrom` (`doctor --fix`) потребує токена Telegram, який можна розв’язати в поточному шляху виконання команди. Якщо перевірка токена недоступна, doctor повідомляє про попередження й пропускає автоматичне визначення для цього проходу. ## macOS: перевизначення змінних середовища `launchctl` -Якщо ви раніше виконували `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти постійні помилки «неавторизовано». +Якщо ви раніше виконували `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення має пріоритет над вашим файлом конфігурації та може спричиняти постійні помилки «неавторизовано». ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -74,4 +75,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## Пов’язано - [Довідка CLI](/uk/cli) -- [Doctor Gateway](/uk/gateway/doctor) +- [Діагностика Gateway](/uk/gateway/doctor) diff --git a/docs/uk/cli/update.md b/docs/uk/cli/update.md index 3e9af43d3..c32d7995b 100644 --- a/docs/uk/cli/update.md +++ b/docs/uk/cli/update.md @@ -1,14 +1,14 @@ --- read_when: - - Ви хочете безпечно оновити робочу копію джерела + - Ви хочете безпечно оновити вихідну копію репозиторію - Вам потрібно зрозуміти скорочену поведінку `--update` summary: Довідник CLI для `openclaw update` (відносно безпечне оновлення джерела + автоматичний перезапуск Gateway) title: Оновлення x-i18n: - generated_at: "2026-04-26T05:40:43Z" + generated_at: "2026-04-26T08:15:42Z" model: gpt-5.4 provider: openai - source_hash: 67da56f0281b6268063952fc8cab70842a0882a6c7d0add65cd2654c3bff41fa + source_hash: b06cab7f4eee12e0fa474b2ea0fb2848fb4899517f9446369888391d2eb3ea9e source_path: cli/update.md workflow: 15 --- @@ -17,8 +17,8 @@ x-i18n: Безпечно оновлюйте OpenClaw і перемикайтеся між каналами stable/beta/dev. -Якщо ви встановили через **npm/pnpm/bun** (глобальне встановлення, без метаданих git), -оновлення відбуваються через потік менеджера пакетів у [Оновлення](/uk/install/updating). +Якщо ви встановили через **npm/pnpm/bun** (глобальне встановлення без метаданих git), +оновлення виконуються через потік менеджера пакетів у розділі [Оновлення](/uk/install/updating). ## Використання @@ -40,18 +40,18 @@ openclaw --update ## Параметри - `--no-restart`: пропустити перезапуск служби Gateway після успішного оновлення. Оновлення через менеджер пакетів, які перезапускають Gateway, перевіряють, що перезапущена служба повідомляє очікувану оновлену версію, перш ніж команда завершиться успішно. -- `--channel `: установити канал оновлення (git + npm; зберігається в конфігурації). -- `--tag `: перевизначити ціль пакета лише для цього оновлення. Для встановлень із пакетів `main` зіставляється з `github:openclaw/openclaw#main`. -- `--dry-run`: попередньо показати заплановані дії оновлення (канал/тег/ціль/потік перезапуску) без запису конфігурації, встановлення, синхронізації плагінів або перезапуску. -- `--json`: вивести машиночитаний JSON `UpdateRunResult`, включно з `postUpdate.plugins.integrityDrifts`, коли під час синхронізації плагінів після оновлення виявлено розходження цілісності артефактів npm Plugin. -- `--timeout `: тайм-аут для кожного кроку (типове значення — 1200 с). -- `--yes`: пропустити запити на підтвердження (наприклад, підтвердження пониження версії) +- `--channel `: встановити канал оновлення (git + npm; зберігається в конфігурації). +- `--tag `: перевизначити цільовий пакет лише для цього оновлення. Для пакетних встановлень `main` зіставляється з `github:openclaw/openclaw#main`. +- `--dry-run`: попередньо показати заплановані дії оновлення (канал/тег/цільовий об’єкт/потік перезапуску) без запису конфігурації, встановлення, синхронізації Plugin або перезапуску. +- `--json`: вивести машиночитний JSON `UpdateRunResult`, включно з `postUpdate.plugins.integrityDrifts`, якщо під час післяоновлювальної синхронізації Plugin виявлено розбіжність артефактів npm Plugin. +- `--timeout `: тайм-аут для кожного кроку (типово 1200 с). +- `--yes`: пропустити запити на підтвердження (наприклад, підтвердження зниження версії) -Примітка: пониження версії потребує підтвердження, оскільки старіші версії можуть пошкодити конфігурацію. +Примітка: зниження версії потребує підтвердження, оскільки старіші версії можуть пошкодити конфігурацію. ## `update status` -Показати активний канал оновлення + тег/гілку/SHA git (для робочих копій джерела), а також доступність оновлення. +Показати активний канал оновлення + тег/гілку/SHA git (для вихідних копій репозиторію), а також доступність оновлення. ```bash openclaw update status @@ -61,73 +61,77 @@ openclaw update status --timeout 10 Параметри: -- `--json`: вивести машиночитаний JSON стану. -- `--timeout `: тайм-аут для перевірок (типове значення — 3 с). +- `--json`: вивести машиночитний JSON стану. +- `--timeout `: тайм-аут для перевірок (типово 3 с). ## `update wizard` -Інтерактивний процес для вибору каналу оновлення та підтвердження, чи перезапускати Gateway -після оновлення (типово — перезапускати). Якщо ви виберете `dev` без робочої копії git, -буде запропоновано її створити. +Інтерактивний потік для вибору каналу оновлення та підтвердження того, чи потрібно перезапускати Gateway +після оновлення (типово перезапуск виконується). Якщо ви виберете `dev` без checkout git, він +запропонує створити його. Параметри: -- `--timeout `: тайм-аут для кожного кроку оновлення (типове значення `1200`) +- `--timeout `: тайм-аут для кожного кроку оновлення (типово `1200`) -## Що це робить +## Що він робить -Коли ви явно перемикаєте канали (`--channel ...`), OpenClaw також підтримує -узгодженість методу встановлення: +Коли ви явно перемикаєте канали (`--channel ...`), OpenClaw також узгоджує +спосіб встановлення: -- `dev` → забезпечує наявність робочої копії git (типово: `~/openclaw`, перевизначається через `OPENCLAW_GIT_DIR`), - оновлює її та встановлює глобальний CLI з цієї робочої копії. +- `dev` → забезпечує наявність checkout git (типово: `~/openclaw`, перевизначається через `OPENCLAW_GIT_DIR`), + оновлює його та встановлює глобальний CLI із цього checkout. - `stable` → встановлює з npm за допомогою `latest`. - `beta` → надає перевагу dist-tag npm `beta`, але повертається до `latest`, якщо beta відсутня або старіша за поточний стабільний випуск. -Автооновлювач ядра Gateway (коли його ввімкнено через конфігурацію) повторно використовує цей самий шлях оновлення. +Автооновлювач ядра Gateway (якщо ввімкнений через конфігурацію) повторно використовує цей самий шлях оновлення. -Для встановлень через менеджер пакетів `openclaw update` визначає цільову версію пакета -перед викликом менеджера пакетів. Якщо встановлена версія точно -збігається з цільовою і не потрібно зберігати зміну каналу оновлення, -команда завершується як пропущена до встановлення пакета, синхронізації плагінів, оновлення completion -або перезапуску Gateway. +Для встановлень через менеджер пакетів `openclaw update` визначає цільову +версію пакета перед викликом менеджера пакетів. Навіть якщо встановлена версія +вже відповідає цільовій, команда оновлює глобальне встановлення пакета, +потім запускає синхронізацію Plugin, оновлення completion і перезапуск. Це підтримує узгодженість +пакованих sidecar-компонентів і записів Plugin, що належать каналу, з установленою збіркою OpenClaw. -## Потік для робочої копії git +## Потік checkout git Канали: -- `stable`: перейти на останній тег без beta, потім виконати build + doctor. -- `beta`: надавати перевагу останньому тегу `-beta`, але повертатися до останнього стабільного тегу, +- `stable`: checkout останнього тега без beta, потім build + doctor. +- `beta`: надає перевагу останньому тегу `-beta`, але повертається до останнього стабільного тега, якщо beta відсутня або старіша. -- `dev`: перейти на `main`, потім виконати fetch + rebase. +- `dev`: checkout `main`, потім fetch + rebase. -Загалом: +На високому рівні: -1. Потребує чистої робочої директорії (без незакомічених змін). +1. Потрібна чиста робоча директорія (без незакомічених змін). 2. Перемикається на вибраний канал (тег або гілку). -3. Виконує отримання з upstream (лише dev). -4. Лише dev: попередньо виконує lint і TypeScript build у тимчасовій робочій копії; якщо вершина не проходить, відступає назад до 10 комітів, щоб знайти найновішу коректну збірку. -5. Виконує rebase на вибраний коміт (лише dev). -6. Установлює залежності за допомогою менеджера пакетів репозиторію. Для робочих копій pnpm засіб оновлення за потреби ініціалізує `pnpm` (спочатку через `corepack`, потім через тимчасовий резервний варіант `npm install pnpm@10`) замість виконання `npm run build` усередині робочого простору pnpm. +3. Виконує fetch з upstream (лише для dev). +4. Лише для dev: попередня перевірка lint + збірка TypeScript у тимчасовій робочій директорії; якщо поточна вершина не проходить, відступає назад максимум на 10 комітів, щоб знайти найновішу збірку, яка проходить без помилок. +5. Виконує rebase на вибраний коміт (лише для dev). +6. Встановлює залежності за допомогою менеджера пакетів репозиторію. Для checkout із pnpm засіб оновлення за потреби ініціалізує `pnpm` (спочатку через `corepack`, потім через тимчасовий резервний варіант `npm install pnpm@10`) замість запуску `npm run build` всередині робочого простору pnpm. 7. Виконує build + build для Control UI. 8. Запускає `openclaw doctor` як фінальну перевірку «безпечного оновлення». -9. Синхронізує плагіни з активним каналом (dev використовує вбудовані плагіни; stable/beta використовує npm) і оновлює плагіни, установлені через npm. +9. Синхронізує Plugin з активним каналом (dev використовує вбудовані Plugin; stable/beta використовують npm) і оновлює Plugin, встановлені через npm. Якщо точне оновлення закріпленого npm Plugin визначає артефакт, чия цілісність відрізняється від збереженого запису встановлення, `openclaw update` перериває це оновлення -артефакту плагіна замість його встановлення. Перевстановлюйте або оновлюйте плагін явно -лише після того, як переконаєтеся, що довіряєте новому артефакту. +артефакту Plugin замість його встановлення. Перевстановлюйте або оновлюйте Plugin явно +лише після перевірки, що ви довіряєте новому артефакту. -Якщо ініціалізація pnpm усе ще не вдається, засіб оновлення тепер зупиняється раніше з помилкою, специфічною для менеджера пакетів, замість спроби виконати `npm run build` усередині робочої копії. +Помилки післяоновлювальної синхронізації Plugin завершують оновлення з помилкою та зупиняють подальші дії +з перезапуском. Виправте помилку встановлення/оновлення Plugin, а потім повторно запустіть +`openclaw update`. + +Якщо ініціалізація pnpm усе ще не вдається, засіб оновлення тепер зупиняється раніше з помилкою, специфічною для менеджера пакетів, замість спроби виконати `npm run build` всередині checkout. ## Скорочення `--update` -`openclaw --update` переписується на `openclaw update` (корисно для оболонок і скриптів запуску). +`openclaw --update` переписується на `openclaw update` (зручно для оболонок і скриптів запуску). ## Пов’язане -- `openclaw doctor` (пропонує спочатку запустити оновлення для робочих копій git) +- `openclaw doctor` (пропонує спочатку запустити оновлення для checkout git) - [Канали розробки](/uk/install/development-channels) - [Оновлення](/uk/install/updating) - [Довідник CLI](/uk/cli) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 8eb967764..68838f553 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -6,15 +6,15 @@ sidebarTitle: Doctor summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-26T07:48:29Z" + generated_at: "2026-04-26T08:15:41Z" model: gpt-5.4 provider: openai - source_hash: 53248eb2777a16197480654302d6802b8b6d4f4b810b443d0aea44e5d40b1cd5 + source_hash: 592a9f886e0e6dcbfeb41a09c765ab289f3ed16ed360be37ff9fbefba920754f source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення. +`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення. ## Швидкий старт @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Приймати типові значення без запитів (зокрема кроки відновлення перезапуску/служби/sandbox, коли це застосовно). + Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служб/пісочниці, якщо застосовно). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - Застосовувати рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). + Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Застосовувати також агресивні виправлення (перезаписує користувацькі конфігурації supervisor). + Також застосувати агресивні виправлення (перезаписує користувацькі конфігурації супервізора). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запускати без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + перенесення стану на диску). Пропускає дії перезапуску/служби/sandbox, які потребують підтвердження людиною. Міграції застарілого стану виконуються автоматично, коли їх виявлено. + Запустити без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/пісочницею, які потребують підтвердження людиною. Міграції застарілого стану виконуються автоматично, якщо їх виявлено. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Сканувати системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks). + Просканувати системні служби на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). @@ -73,106 +73,106 @@ openclaw doctor cat ~/.openclaw/openclaw.json ``` -## Що це робить (коротко) +## Що він робить (коротко) - + - Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі). - - Перевірка актуальності протоколу UI (перебудовує Control UI, коли схема протоколу новіша). + - Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). - Перевірка стану + запит на перезапуск. - - Зведення стану Skills (доступні/відсутні/заблоковані) і стан Plugin. + - Зведення стану Skills (доступні/відсутні/заблоковані) і стану Plugin. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. - - Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. + - Міграція конфігурації Talk зі старих пласких полів `talk.*` до `talk.provider` + `talk.providers.`. + - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - - Попередження про затінення Codex OAuth (`models.providers.openai-codex`). - - Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. + - Попередження про перекриття Codex OAuth (`models.providers.openai-codex`). + - Перевірка передумов TLS для OAuth OpenAI Codex OAuth profiles. - Міграція застарілого стану на диску (sessions/каталог agent/автентифікація WhatsApp). - - Міграція застарілих ключів контрактів маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Міграція ключів контрактів маніфесту застарілого Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні завдання Webhook з `notify: true`). - - Міграція застарілої policy runtime агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Міграція застарілої policy виконання agent до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - Перевірка файлів блокування сесій і очищення застарілих блокувань. - - Відновлення стенограм сесій для дубльованих гілок перезапису prompt, створених у збірках 2026.4.24, яких це стосується. - - Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог state). + - Відновлення транскриптів сесій для дубльованих гілок prompt-rewrite, створених у збірках 2026.4.24, яких це стосується. + - Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). - Перевірки прав доступу до файлу конфігурації (`chmod 600`) при локальному запуску. - - Стан автентифікації model: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілів auth. + - Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для auth-profile. - Виявлення додаткового каталогу workspace (`~/openclaw`). - - - Відновлення образу sandbox, коли sandboxing увімкнено. - - Міграція застарілих служб і виявлення додаткових gateway. + + - Відновлення образу пісочниці, якщо ізоляція ввімкнена. + - Міграція застарілих служб і виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - - Перевірки runtime gateway (службу встановлено, але вона не працює; кешована мітка launchd). - - Попередження про стан channel (визначається із запущеного gateway). - - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. - - Перевірки рекомендованих практик runtime gateway (Node проти Bun, шляхи менеджера версій). - - Діагностика конфліктів портів gateway (типовий `18789`). + - Перевірки середовища виконання Gateway (службу встановлено, але вона не запущена; кешована мітка launchd). + - Попередження про стан каналів (зондуються з запущеного Gateway). + - Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням. + - Перевірки найкращих практик середовища виконання Gateway (Node проти Bun, шляхи менеджерів версій). + - Діагностика конфліктів порту Gateway (типово `18789`). - - - Попередження безпеки для відкритих policy DM. - - Перевірки auth gateway для локального режиму токена (пропонує згенерувати токен, коли немає джерела токена; не перезаписує конфігурації токенів SecretRef). - - Виявлення проблем із pairing пристроїв (очікувані запити першого pairing, очікувані підвищення ролі/області дії, застаріле розходження локального кешу токенів пристрою та розходження auth у paired-записах). + + - Попередження безпеки для відкритих політик DM. + - Перевірки автентифікації Gateway для локального режиму токенів (пропонує створити токен, якщо джерела токена немає; не перезаписує конфігурації token SecretRef). + - Виявлення проблем під час pairing пристроїв (очікувані перші запити на pairing, очікувані підвищення ролі/scope, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації записів pairing). - - - Перевірка `linger` systemd у Linux. + + - Перевірка systemd linger у Linux. - Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для контекстних файлів). - - Перевірка стану завершення команд shell і автоінсталяція/оновлення. - - Перевірка готовності провайдера embedding для пошуку в memory (локальна model, віддалений API-ключ або двійковий файл QMD). - - Перевірки source-інсталяції (невідповідність workspace pnpm, відсутні assets UI, відсутній двійковий файл tsx). - - Записує оновлену конфігурацію + метадані майстра. + - Перевірка стану завершення команд оболонки та автоматичне встановлення/оновлення. + - Перевірка готовності провайдера вбудовувань для пошуку в пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD). + - Перевірки source-інсталяції (невідповідність pnpm workspace, відсутні ресурси UI, відсутній бінарний файл tsx). + - Записує оновлену конфігурацію та метадані майстра. -## Заповнення назад і скидання Dreams UI +## Backfill і reset у Dreams UI -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded dreaming. Ці дії використовують RPC-методи gateway у стилі doctor, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. +Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи в стилі doctor для gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. Що вони роблять: - **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає grounded REM diary pass і записує оборотні записи backfill у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, які позначено. -- **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що походять з історичного відтворення й ще не накопичили live recall або щоденну підтримку. +- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника backfill, що мають відповідну позначку. +- **Clear Grounded** видаляє лише staged grounded-only short-term записи, які походять з історичного відтворення і ще не накопичили live recall або daily support. Чого вони самі по собі **не** роблять: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не виконують автоматично staged grounded candidates у live short-term promotion store, якщо ви явно не запустите staged CLI-шлях спочатку +- вони не додають автоматично grounded candidates до live short-term promotion store, якщо ви явно не запустите спочатку staged CLI path -Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, натомість використовуйте потік CLI: +Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, замість цього використовуйте CLI-потік: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Це поміщає grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` як поверхню для перегляду. +Це додає grounded durable candidates до short-term dreaming store, зберігаючи `DREAMS.md` як поверхню для перегляду. ## Детальна поведінка та обґрунтування - Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. + Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує виконати оновлення (fetch/rebase/build) перед запуском doctor. - Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для певного channel), doctor нормалізує їх до поточної схеми. + Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. - Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує застарілі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у карту provider. + Це також включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів. - - Коли конфігурація містить застарілі ключі, інші команди відмовляються виконуватися й просять запустити `openclaw doctor`. + + Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять вас виконати `openclaw doctor`. Doctor: - Пояснить, які застарілі ключі було знайдено. - Покажe міграцію, яку він застосував. - - Перезапише `~/.openclaw/openclaw.json` відповідно до оновленої схеми. + - Перезапише `~/.openclaw/openclaw.json` за оновленою схемою. - Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації відновлюються без ручного втручання. Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації відновлюються без ручного втручання. Міграції сховища завдань Cron обробляються командою `openclaw doctor --fix`. Поточні міграції: @@ -181,7 +181,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` - - `routing.bindings` → верхньорівневе `bindings` + - `routing.bindings` → верхньорівневий `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -197,85 +197,85 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Для channel із іменованими `accounts`, але зі збереженими верхньорівневими значеннями channel для одного облікового запису, ці значення рівня account переносяться в підвищений account, вибраний для цього channel (`accounts.default` для більшості channel; Matrix може зберігати наявну відповідну іменовану/default-ціль) + - Для каналів з іменованими `accounts`, але із застарілими значеннями каналу верхнього рівня для одного облікового запису, перемістити ці значення, обмежені обліковим записом, до вибраного promoted account для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну named/default ціль) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - видалення `browser.relayBindHost` (застарілий параметр relay для розширення) + - видалити `browser.relayBindHost` (застарілий параметр relay для розширення) - Попередження doctor також містять рекомендації щодо типового account для багатoоблікових channel: + Попередження doctor також містять рекомендації щодо default account для багатокористувацьких каналів: - - Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback routing може вибрати неочікуваний account. - - Якщо `channels..defaultAccount` встановлено на невідомий ID account, doctor попереджає та перелічує налаштовані ID account. + - Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback routing може вибрати неочікуваний обліковий запис. + - Якщо `channels..defaultAccount` вказує на невідомий ID облікового запису, doctor попереджає про це і показує налаштовані ID облікових записів. - Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати models до неправильного API або обнулити вартість. Doctor попереджає про це, щоб ви могли видалити перевизначення й відновити маршрутизацію API та вартість для кожної model. + Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви могли прибрати перевизначення і відновити маршрутизацію API та вартість для кожної моделі. - - Якщо ваша конфігурація browser усе ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної host-local моделі підключення Chrome MCP: + + Якщо ваша конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної host-local моделі підключення Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється Doctor також перевіряє host-local шлях Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів auto-connect + - перевіряє, чи встановлено Google Chrome на тому ж хості для типових профілів автопідключення - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - нагадує ввімкнути remote debugging на сторінці inspect у браузері (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може ввімкнути налаштування на боці Chrome за вас. Host-local Chrome MCP, як і раніше, вимагає: + Doctor не може ввімкнути налаштування на боці Chrome за вас. Host-local Chrome MCP, як і раніше, потребує: - - браузер на основі Chromium 144+ на хості gateway/node - - локально запущений браузер + - браузер на базі Chromium версії 144+ на хості gateway/node + - браузер, запущений локально - увімкнений remote debugging у цьому браузері - - підтвердження першого запиту згоди на підключення в браузері + - підтвердження першого запиту згоди на attach у браузері - Готовність тут стосується лише локальних передумов для підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого browser або профілю raw CDP. + Готовність тут стосується лише локальних передумов для attach. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, як і раніше, потребують керованого браузера або профілю raw CDP. - Ця перевірка **не** стосується Docker, sandbox, remote-browser або інших безголових сценаріїв. Вони, як і раніше, використовують raw CDP. + Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. - - Коли налаштовано профіль OpenAI Codex OAuth, doctor опитує endpoint авторизації OpenAI, щоб перевірити, чи локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо опитування завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить специфічні для платформи вказівки щодо виправлення. На macOS з Node, установленим через Homebrew, виправленням зазвичай є `brew postinstall ca-certificates`. Із `--deep` опитування виконується, навіть якщо gateway у здоровому стані. + + Коли налаштовано профіль OpenAI Codex OAuth, doctor виконує перевірку endpoint авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed сертифікат), doctor виводить платформозалежні рекомендації щодо виправлення. На macOS з Node, встановленим через Homebrew, виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується, навіть якщо Gateway справний. - Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поруч із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/fallback. Користувацькі proxy та перевизначення лише заголовків, як і раніше, підтримуються й не викликають цього попередження. + Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть перекривати вбудований шлях провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування поруч із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення і повернути вбудовану поведінку маршрутизації/fallback. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються й не викликають цього попередження. - Коли вбудований Plugin Codex увімкнено, doctor також перевіряє, чи первинні посилання на model `openai-codex/*` усе ще розв’язуються через типовий runner PI. Це поєднання є валідним, коли ви хочете використовувати автентифікацію Codex OAuth/підписки через PI, але його легко сплутати з native harness app-server Codex. Doctor попереджає про це й указує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи refs первинної моделі `openai-codex/*` усе ще резолвляться через типовий раннер Pi. Така комбінація коректна, якщо ви хочете автентифікацію Codex OAuth/subscription через Pi, але її легко сплутати з нативним harness app-server Codex. Doctor попереджає про це й вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor не виправляє це автоматично, оскільки обидва маршрути є валідними: + Doctor не виправляє це автоматично, тому що обидва маршрути коректні: - - `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw». - - `openai/*` + `runtime: "codex"` означає «виконувати вбудований turn через native app-server Codex». - - `/codex ...` означає «керувати native conversation Codex з чату або прив’язати її». + - `openai-codex/*` + Pi означає «використовувати автентифікацію Codex OAuth/subscription через звичайний раннер OpenClaw». + - `openai/*` + `runtime: "codex"` означає «виконати вбудований turn через нативний app-server Codex». + - `/codex ...` означає «керувати нативною розмовою Codex із чату або прив’язати її». - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». - Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залишайте попередження як є, якщо PI Codex OAuth є навмисним. + Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і вручну відредагуйте конфігурацію. Залишайте попередження як є, якщо Codex OAuth через Pi використовується навмисно. - - Doctor може мігрувати старіші розміщення на диску до поточної структури: + + Doctor може мігрувати старі структури на диску до поточної структури: - - Сховище sessions + transcripts: + - Сховище сесій + transcripts: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог agent: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - - Стан auth WhatsApp (Baileys): - - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий ID account: `default`) + - Стан автентифікації WhatsApp (Baileys): + - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий id облікового запису: `default`) - Ці міграції виконуються в режимі best-effort та є ідемпотентними; doctor виведе попередження, якщо залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі sessions + каталог agent під час запуску, тож history/auth/models потрапляють у шлях для конкретного agent без ручного запуску doctor. Auth WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map Talk тепер порівнюється за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних no-op змін у `doctor --fix`. + Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі sessions + каталог agent під час запуску, тож history/auth/models потрапляють до шляху конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map Talk тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних порожніх змін `doctor --fix`. - Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних. + Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перенести їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. - Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово або `cron.store`, якщо перевизначено) на наявність старих форм завдань, які scheduler усе ще приймає задля сумісності. + Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово або `cron.store`, якщо перевизначено) на наявність старих форм завдань, які планувальник усе ще приймає для сумісності. Поточні очищення Cron включають: @@ -286,178 +286,179 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - псевдоніми delivery `provider` у payload → явний `delivery.channel` - прості застарілі резервні завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true`, лише коли це можна зробити без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним режимом delivery, що не є webhook, doctor попереджає та залишає це завдання для ручної перевірки. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним режимом delivery, що не є webhook, doctor попереджає та залишає це завдання для ручної перевірки. - Doctor сканує каталог sessions кожного agent на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення session. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID усе ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або вік понад 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та пропонує повторно запустити з `--fix`. + Doctor сканує каталог сесій кожного agent на наявність застарілих write-lock файлів — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого lock-файлу він повідомляє: шлях, PID, чи PID ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі lock-файли; інакше друкує примітку та інструктує вас повторно запустити команду з `--fix`. - - Doctor сканує JSONL-файли sessions agent на наявність дубльованої форми гілки, створеної помилкою переписування стенограми prompt у 2026.4.24: покинутий turn користувача з внутрішнім контекстом runtime OpenClaw плюс активний sibling із тим самим видимим prompt користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує стенограму на активну гілку, щоб history gateway та читачі memory більше не бачили дубльованих turn. + + Doctor сканує JSONL-файли сесій agent на наявність дубльованої форми гілок, створеної помилкою переписування prompt transcript у 2026.4.24: покинутий user turn із внутрішнім runtime context OpenClaw плюс активний sibling з тим самим видимим user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує transcript на активну гілку, щоб history Gateway і readers пам’яті більше не бачили дубльованих turn. - Каталог state — це операційний стовбур мозку. Якщо він зникне, ви втратите sessions, credentials, logs і config (якщо у вас немає резервних копій в іншому місці). + Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите сесії, облікові дані, журнали та конфігурацію (якщо в іншому місці немає резервних копій). Doctor перевіряє: - - **Відсутній каталог state**: попереджає про катастрофічну втрату стану, пропонує відтворити каталог і нагадує, що не може відновити втрачені дані. - - **Права доступу до каталогу state**: перевіряє можливість запису; пропонує виправити права доступу (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). - - **Каталог state macOS, синхронізований із хмарою**: попереджає, коли state розв’язується в межах iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи, що підтримуються синхронізацією, можуть спричиняти повільніший I/O та гонки блокування/синхронізації. - - **Каталог state Linux на SD або eMMC**: попереджає, коли state розв’язується до джерела монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час запису sessions і credentials. - - **Відсутні каталоги sessions**: `sessions/` і каталог сховища sessions потрібні для збереження history та уникнення збоїв `ENOENT`. - - **Невідповідність transcripts**: попереджає, коли нещодавні записи session мають відсутні файли transcript. - - **Основна session «1-рядковий JSONL»**: позначає випадки, коли основний transcript має лише один рядок (history не накопичується). - - **Кілька каталогів state**: попереджає, коли існує кілька тек `~/.openclaw` у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може розділятися між інсталяціями). - - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запускати його на віддаленому хості (state живе там). - - **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групою/усіма, і пропонує обмежити до `600`. + - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує відновити каталог і нагадує, що не може відновити втрачені дані. + - **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права доступу (і виводить підказку `chown`, якщо виявлено невідповідність owner/group). + - **Каталог стану macOS, синхронізований із хмарою**: попереджає, якщо стан резолвиться в `iCloud Drive` (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, тому що шляхи із синхронізацією можуть спричиняти повільніший I/O та гонки блокування/синхронізації. + - **Каталог стану Linux на SD або eMMC**: попереджає, якщо стан резолвиться до джерела монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сесій і облікових даних. + - **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій потрібні для збереження history і уникнення збоїв `ENOENT`. + - **Невідповідність transcript**: попереджає, коли в нещодавніх записах сесій відсутні файли transcript. + - **Основна сесія "1-line JSONL"**: позначає випадки, коли основний transcript містить лише один рядок (history не накопичується). + - **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує на інше місце (history може розділятися між інсталяціями). + - **Нагадування про remote mode**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (саме там зберігається стан). + - **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/всім, і пропонує обмежити права до `600`. - - Doctor перевіряє профілі OAuth у сховищі auth, попереджає, коли строк дії токенів спливає/вже сплив, і може оновити їх, коли це безпечно. Якщо профіль Anthropic OAuth/token застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. + + Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли строк дії токенів спливає/сплив, і може оновлювати їх, коли це безпечно. Якщо профіль Anthropic OAuth/token застарів, він пропонує використати ключ Anthropic API або шлях Anthropic setup-token. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. - Коли оновлення OAuth остаточно завершується помилкою (наприклад, `refresh_token_reused`, `invalid_grant` або коли provider повідомляє, що потрібно ввійти знову), doctor повідомляє, що потрібна повторна auth, і виводить точну команду `openclaw models auth login --provider ...`, яку слід виконати. + Коли оновлення OAuth остаточно завершується невдачею (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер повідомляє, що потрібно знову увійти), doctor повідомляє, що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, яку слід виконати. - Doctor також повідомляє про профілі auth, які тимчасово непридатні до використання через: + Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні для використання через: - - короткі cooldown (обмеження частоти/тайм-аути/збої auth) - - довші відключення (збої білінгу/кредиту) + - короткі cooldown (rate limits/timeouts/auth failures) + - довші вимкнення (billing/credit failures) - - Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на model за каталогом і allowlist та попереджає, якщо воно не розв’язується або не дозволене. + + Якщо встановлено `hooks.gmail.model`, doctor перевіряє reference моделі за каталогом і allowlist та попереджає, коли її не вдається резолвити або вона не дозволена. - Коли sandboxing увімкнено, doctor перевіряє Docker-образи та пропонує зібрати їх або перейти на застарілі імена, якщо поточний образ відсутній. + Коли sandboxing увімкнено, doctor перевіряє Docker-образи й пропонує зібрати їх або переключитися на застарілі назви, якщо поточний образ відсутній. - - Doctor перевіряє runtime-залежності лише для вбудованих Plugin, які активні в поточній конфігурації або увімкнені типовим значенням у своєму вбудованому маніфесті, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або типово ввімкнений вбудований provider. Якщо чогось бракує, doctor повідомляє про пакети та встановлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugin, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів Plugin. + + Doctor перевіряє runtime-залежності лише для вбудованих Plugin, які активні в поточній конфігурації або ввімкнені типовим значенням у їхньому вбудованому маніфесті, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або вбудований провайдер, увімкнений типово. Якщо чогось бракує, doctor повідомляє про пакунки й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugin, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів Plugin. - Gateway і локальний CLI також можуть за потреби відновлювати runtime-залежності активних вбудованих Plugin перед імпортом вбудованого Plugin. Ці інсталяції обмежені коренем runtime-інсталяції Plugin, виконуються з вимкненими scripts, не записують package lock і захищені блокуванням install-root, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно. + Gateway і локальний CLI також можуть за потреби відновлювати runtime-залежності активних вбудованих Plugin перед імпортом вбудованого Plugin. Ці встановлення обмежені коренем встановлення runtime Plugin, виконуються з вимкненими scripts, не записують package lock і захищені блокуванням install-root, щоб одночасні запуски CLI або Gateway не змінювали те саме дерево `node_modules` одночасно. - - Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з поточним портом gateway. Він також може сканувати наявність додаткових служб, схожих на gateway, і виводити підказки щодо очищення. Служби gateway OpenClaw з іменами профілів вважаються повноцінними й не позначаються як «додаткові». + + Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. Іменовані за профілем служби gateway OpenClaw вважаються повноцінними і не позначаються як «додаткові». - - Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім виконує кроки міграції в режимі best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + + Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім запускає кроки міграції best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск триває. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - - Doctor тепер перевіряє стан pairing пристроїв як частину звичайного проходу перевірки стану системи. + + Doctor тепер перевіряє стан pairing пристроїв як частину звичайної перевірки справності. Що він повідомляє: - - очікувані запити на pairing уперше - - очікувані підвищення ролі для вже спарених пристроїв + - очікувані перші запити на pairing + - очікувані підвищення ролей для вже спарених пристроїв - очікувані підвищення scope для вже спарених пристроїв - - виправлення невідповідності public key, коли ID пристрою все ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом - - спарені записи без активного токена для схваленої ролі - - спарені токени, чиї scope відхилилися від базового схваленого pairing + - виправлення невідповідності публічного ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом + - у спарених записах немає активного токена для схваленої ролі + - у токенів спарених записів scope відхилилися від базової лінії схваленого pairing - локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope - Doctor не схвалює запити на pairing автоматично й не виконує автоматичну ротацію токенів пристрою. Натомість він виводить точні наступні кроки: + Doctor не схвалює запити на pairing автоматично і не виконує автоматичну ротацію токенів пристроїв. Натомість він виводить точні наступні кроки: - переглянути очікувані запити за допомогою `openclaw devices list` - - схвалити конкретний запит за допомогою `openclaw devices approve ` + - схвалити точний запит за допомогою `openclaw devices approve ` - виконати ротацію нового токена за допомогою `openclaw devices rotate --device --role ` - - видалити застарілий запис і повторно схвалити його за допомогою `openclaw devices remove ` + - видалити застарілий запис і схвалити його знову за допомогою `openclaw devices remove ` - Це закриває поширену прогалину «вже спарено, але все ще вимагається pairing»: doctor тепер розрізняє pairing уперше, очікувані підвищення ролі/scope і застаріле розходження токена/ідентичності пристрою. + Це закриває поширену прогалину «вже спарено, але все одно вимагається pairing»: тепер doctor розрізняє перший pairing, очікувані підвищення ролі/scope та дрейф застарілого токена/ідентичності пристрою. - Doctor видає попередження, коли provider відкритий для DM без allowlist або коли policy налаштовано небезпечним чином. + Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли policy налаштовано небезпечним чином. - Якщо запущено як користувацька служба systemd, doctor перевіряє, чи ввімкнено linger, щоб gateway залишався активним після виходу з системи. + Якщо запуск виконується як користувацька служба systemd, doctor перевіряє, що linger увімкнено, щоб gateway залишався активним після виходу з системи. Doctor виводить зведення стану workspace для типового agent: - - **Стан Skills**: кількість доступних, тих, яким бракує вимог, і Skills, заблокованих allowlist. - - **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace існують поруч із поточним workspace. - - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові Plugin; перелічує ID Plugin для будь-яких помилок; повідомляє про можливості bundle Plugin. - - **Попередження про сумісність Plugin**: позначає Plugin, які мають проблеми сумісності з поточним runtime. - - **Діагностика Plugin**: показує всі попередження або помилки під час завантаження, видані реєстром Plugin. + - **Стан Skills**: кількість доступних, тих, яким бракує вимог, і заблокованих allowlist Skills. + - **Застарілі каталоги workspace**: попереджає, якщо `~/openclaw` або інші застарілі каталоги workspace існують поруч із поточним workspace. + - **Стан Plugin**: кількість увімкнених/вимкнених/помилкових Plugin; перелік ID Plugin для всіх помилок; звіт про можливості bundle Plugin. + - **Попередження про сумісність Plugin**: позначає Plugin, що мають проблеми сумісності з поточним runtime. + - **Діагностика Plugin**: показує всі попередження або помилки під час завантаження, які видає реєстр Plugin. - Doctor перевіряє, чи bootstrap-файли workspace (наприклад, `AGENTS.md`, `CLAUDE.md` або інші впроваджені контекстні файли) наближаються до налаштованого ліміту символів або перевищують його. Він повідомляє для кожного файла кількість необроблених і впроваджених символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість впроваджених символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + Doctor перевіряє, чи наближаються bootstrap-файли workspace (наприклад `AGENTS.md`, `CLAUDE.md` або інші інжектовані контекстні файли) до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу кількість сирих та інжектованих символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість інжектованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - - Doctor перевіряє, чи встановлено завершення команд табуляцією для поточного shell (zsh, bash, fish або PowerShell): + + Doctor перевіряє, чи встановлено tab completion для поточної оболонки (zsh, bash, fish або PowerShell): - - Якщо профіль shell використовує повільний шаблон динамічного завершення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. - - Якщо завершення налаштовано в профілі, але файл кешу відсутній, doctor автоматично відтворює кеш. - - Якщо завершення взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). + - Якщо профіль оболонки використовує повільний динамічний шаблон completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. + - Якщо completion налаштовано в профілі, але кешований файл відсутній, doctor автоматично відновлює кеш. + - Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). - Запустіть `openclaw completion --write-state`, щоб вручну відтворити кеш. + Використайте `openclaw completion --write-state`, щоб вручну згенерувати кеш повторно. - - Doctor перевіряє готовність auth локального gateway на основі токена. + + Doctor перевіряє готовність автентифікації локального токена gateway. - - Якщо для режиму токена потрібен токен і джерело токена відсутнє, doctor пропонує згенерувати його. - - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає та не перезаписує його звичайним текстом. + - Якщо режиму токена потрібен токен і жодного джерела токена не існує, doctor пропонує згенерувати його. + - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано токен SecretRef. - - Деякі потоки відновлення потребують перевірки налаштованих облікових даних без послаблення поведінки runtime fail-fast. + + Для деяких потоків виправлення потрібно перевірити налаштовані облікові дані, не послаблюючи при цьому fail-fast поведінку runtime. - - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef у режимі лише читання, що й команди сімейства status, для цільового відновлення конфігурації. - - Приклад: відновлення `allowFrom` / `groupAllowFrom` Telegram для `@username` намагається використати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або хибного повідомлення про відсутність токена. + - `openclaw doctor --fix` тепер використовує ту саму read-only модель зведення SecretRef, що й команди сімейства status, для цільових виправлень конфігурації. + - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні. + - Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення про відсутність токена. - Doctor виконує перевірку стану системи й пропонує перезапустити gateway, якщо він виглядає нездоровим. + Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо той виглядає несправним. - - Doctor перевіряє, чи готовий налаштований provider embedding для пошуку в memory для типового agent. Поведінка залежить від налаштованого backend і provider: + + Doctor перевіряє, чи готовий налаштований провайдер embedding для пошуку в пам’яті для типового agent. Поведінка залежить від налаштованого бекенда та провайдера: - - **QMD backend**: перевіряє, чи доступний і чи може запускатися двійковий файл `qmd`. Якщо ні, виводить вказівки щодо виправлення, зокрема npm-пакет і варіант ручного шляху до двійкового файла. - - **Явний локальний provider**: перевіряє наявність локального файла model або розпізнаного URL віддаленої/завантажуваної model. Якщо його немає, пропонує перейти на віддалений provider. - - **Явний віддалений provider** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі auth. Якщо його немає, виводить практичні підказки щодо виправлення. - - **Автоматичний provider**: спочатку перевіряє доступність локальної model, а потім пробує кожен віддалений provider у порядку автоматичного вибору. + - **Бекенд QMD**: перевіряє, чи доступний і чи може запуститися бінарний файл `qmd`. Якщо ні, виводить рекомендації з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла. + - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаваної URL-адреси віддаленої/завантажуваної моделі. Якщо нічого немає, пропонує перейти на віддалений провайдер. + - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. + - **Автопровайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожен віддалений провайдер у порядку автопідбору. - Коли доступний результат опитування gateway (gateway був у здоровому стані на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою CLI, і зазначає будь-які розбіжності. + Якщо результат перевірки gateway доступний (gateway був справний на момент перевірки), doctor звіряє його з видимою для CLI конфігурацією і зазначає будь-яку невідповідність. - Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime. + Використайте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - - Якщо gateway у здоровому стані, doctor виконує перевірку стану channel і повідомляє про попередження з рекомендованими виправленнями. + + Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє попередження разом із запропонованими виправленнями. - - Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність відсутніх або застарілих типових значень (наприклад, залежностей systemd network-online і затримки перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення й може переписати файл служби/завдання відповідно до поточних типових значень. + + Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може переписати файл служби/завдання до поточних типових значень. Примітки: - - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. - - `openclaw doctor --yes` приймає типові запити на відновлення. + - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. + - `openclaw doctor --yes` приймає типові запити на виправлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. - - Якщо auth токена потребує токен, а `gateway.auth.token` керується через SecretRef, під час встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язане значення токена у відкритому вигляді в метаданих середовища служби supervisor. - - Якщо auth токена потребує токен, а налаштований токен SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення з практичними вказівками. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, але `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно задано. - - Для користувацьких systemd-модулів Linux перевірки розходження токенів doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих auth служби. - - Відновлення служб doctor відмовляється переписувати, зупиняти або перезапускати службу gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє записано новішою версією. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він, як і раніше, повідомляє про стан служби та запускає виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, тому що цим життєвим циклом керує зовнішній супервізор. + - Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів у відкритому тексті в метаданих середовища служби супервізора. + - Якщо автентифікація токеном вимагає токен, а налаштований токен SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення і виводить практичні рекомендації. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде явно встановлено. + - Для користувацьких unit systemd у Linux перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. + - Виправлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу gateway зі старішого бінарного файла OpenClaw, якщо конфігурацію востаннє записано новішою версією. Див. [усунення проблем Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. - - Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли службу встановлено, але фактично вона не працює. Він також перевіряє конфлікти портів на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущено, SSH-тунель). + + Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, якщо службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущений, SSH-тунель). - - Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашого shell. Doctor пропонує мігрувати на системну інсталяцію Node, якщо вона доступна (Homebrew/apt/choco). + + Doctor попереджає, коли служба gateway працює на Bun або на керованому менеджером версій шляху Node (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp і Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco). - Doctor зберігає всі зміни конфігурації та ставить метадані майстра, щоб зафіксувати запуск doctor. + Doctor зберігає всі зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor. - - Doctor пропонує систему memory для workspace, якщо вона відсутня, і виводить пораду щодо резервного копіювання, якщо workspace ще не перебуває під git. + + Doctor пропонує систему пам’яті workspace, якщо її немає, і виводить пораду щодо резервного копіювання, якщо workspace ще не перебуває під git. - Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури workspace і резервного копіювання через git (рекомендовано приватний GitHub або GitLab). @@ -465,4 +466,4 @@ openclaw memory rem-backfill --path ./memory --stage-short-term ## Пов’язане - [Runbook Gateway](/uk/gateway) -- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) +- [Усунення проблем Gateway](/uk/gateway/troubleshooting) diff --git a/docs/uk/gateway/trusted-proxy-auth.md b/docs/uk/gateway/trusted-proxy-auth.md index fab768583..d8c5c489c 100644 --- a/docs/uk/gateway/trusted-proxy-auth.md +++ b/docs/uk/gateway/trusted-proxy-auth.md @@ -1,79 +1,92 @@ --- read_when: - - Запуск OpenClaw за identity-aware проксі + - Запуск OpenClaw за проксі з підтримкою ідентифікації - Налаштування Pomerium, Caddy або nginx з OAuth перед OpenClaw - - Усунення помилок WebSocket 1008 unauthorized у конфігураціях зі зворотним проксі - - Визначення місця встановлення HSTS та інших заголовків посилення HTTP-безпеки -summary: Делегувати автентифікацію gateway довіреному зворотному проксі (Pomerium, Caddy, nginx + OAuth) -title: Автентифікація через довірений проксі + - Виправлення помилок WebSocket 1008 «неавторизовано» у конфігураціях зі зворотним проксі + - Визначення місця налаштування HSTS та інших заголовків HTTP для посилення безпеки +sidebarTitle: Trusted proxy auth +summary: Делегуйте автентифікацію Gateway довіреному зворотному проксі (Pomerium, Caddy, nginx + OAuth) +title: Автентифікація довіреного проксі x-i18n: - generated_at: "2026-04-23T20:55:20Z" + generated_at: "2026-04-26T08:15:43Z" model: gpt-5.4 provider: openai - source_hash: af406f218fb91c5ae2fed04921670bfc4cd3d06f51b08eec91cddde4521bf771 + source_hash: 64e0f4dee942aedec548135f0408e7773e7b498f8262af13a4d0eff262cae646 source_path: gateway/trusted-proxy-auth.md workflow: 15 --- -> ⚠️ **Функція, чутлива до безпеки.** Цей режим повністю делегує автентифікацію вашому зворотному проксі. Неправильна конфігурація може відкрити ваш Gateway для неавторизованого доступу. Уважно прочитайте цю сторінку перед увімкненням. + +**Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому зворотному проксі. Неправильна конфігурація може відкрити ваш Gateway для несанкціонованого доступу. Уважно прочитайте цю сторінку перед увімкненням. + ## Коли використовувати -Використовуйте режим автентифікації `trusted-proxy`, якщо: +Використовуйте режим автентифікації `trusted-proxy`, коли: -- Ви запускаєте OpenClaw за **identity-aware proxy** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth) -- Ваш проксі обробляє всю автентифікацію і передає identity користувача через заголовки -- Ви працюєте в середовищі Kubernetes або контейнерів, де проксі є єдиним шляхом до Gateway -- Ви отримуєте помилки WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в payload WS +- Ви запускаєте OpenClaw за **проксі з підтримкою ідентифікації** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth). +- Ваш проксі виконує всю автентифікацію та передає ідентичність користувача через заголовки. +- Ви працюєте в середовищі Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway. +- Ви стикаєтеся з помилками WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в корисному навантаженні WS. ## Коли НЕ використовувати -- Якщо ваш проксі не автентифікує користувачів (лише термінатор TLS або балансувальник навантаження) -- Якщо існує будь-який шлях до Gateway в обхід проксі (дірки у фаєрволі, доступ із внутрішньої мережі) -- Якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує forwarded headers -- Якщо вам потрібен лише персональний однокористувацький доступ (розгляньте Tailscale Serve + local loopback для простішого налаштування) +- Якщо ваш проксі не автентифікує користувачів (лише завершує TLS або є балансувальником навантаження). +- Якщо існує будь-який шлях до Gateway в обхід проксі (дірки у фаєрволі, доступ із внутрішньої мережі). +- Якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує переслані заголовки. +- Якщо вам потрібен лише персональний доступ для одного користувача (розгляньте Tailscale Serve + loopback для простішого налаштування). ## Як це працює -1. Ваш зворотний проксі автентифікує користувачів (OAuth, OIDC, SAML тощо) -2. Проксі додає заголовок з identity автентифікованого користувача (наприклад, `x-forwarded-user: nick@example.com`) -3. OpenClaw перевіряє, що запит надійшов від **довіреної IP-адреси проксі** (налаштовується в `gateway.trustedProxies`) -4. OpenClaw витягує identity користувача з налаштованого заголовка -5. Якщо все збігається, запит авторизується + + + Ваш зворотний проксі автентифікує користувачів (OAuth, OIDC, SAML тощо). + + + Проксі додає заголовок з ідентичністю автентифікованого користувача (наприклад, `x-forwarded-user: nick@example.com`). + + + OpenClaw перевіряє, що запит надійшов від **довіреної IP-адреси проксі** (налаштованої в `gateway.trustedProxies`). + + + OpenClaw витягує ідентичність користувача з налаштованого заголовка. + + + Якщо все гаразд, запит авторизується. + + -## Поведінка pairing у Control UI +## Поведінка сполучення Control UI -Коли активний `gateway.auth.mode = "trusted-proxy"` і запит проходить -перевірки trusted-proxy, WebSocket-сесії Control UI можуть підключатися без -identity pairing пристрою. +Коли `gateway.auth.mode = "trusted-proxy"` активний і запит проходить перевірки trusted-proxy, сеанси WebSocket Control UI можуть підключатися без ідентичності сполучення пристрою. Наслідки: -- Pairing більше не є основним шлюзом доступу для Control UI у цьому режимі. -- Ваша політика автентифікації зворотного проксі та `allowUsers` стають ефективним контролем доступу. -- Тримайте вхід до gateway заблокованим лише для IP-адрес довірених проксі (`gateway.trustedProxies` + фаєрвол). +- Сполучення більше не є основним бар’єром для доступу до Control UI в цьому режимі. +- Політика автентифікації вашого зворотного проксі та `allowUsers` стають фактичним контролем доступу. +- Тримайте вхідний доступ до gateway заблокованим лише для IP-адрес довіреного проксі (`gateway.trustedProxies` + фаєрвол). ## Конфігурація ```json5 { gateway: { - // Trusted-proxy auth expects requests from a non-loopback trusted proxy source + // Автентифікація trusted-proxy очікує запити з не-loopback джерела довіреного проксі bind: "lan", - // CRITICAL: Only add your proxy's IP(s) here + // КРИТИЧНО: Додавайте тут лише IP-адреси вашого проксі trustedProxies: ["10.0.0.1", "172.17.0.1"], auth: { mode: "trusted-proxy", trustedProxy: { - // Header containing authenticated user identity (required) + // Заголовок, що містить ідентичність автентифікованого користувача (обов’язково) userHeader: "x-forwarded-user", - // Optional: headers that MUST be present (proxy verification) + // Необов’язково: заголовки, які ОБОВ’ЯЗКОВО мають бути присутні (перевірка проксі) requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"], - // Optional: restrict to specific users (empty = allow all) + // Необов’язково: обмеження до конкретних користувачів (порожньо = дозволити всіх) allowUsers: ["nick@example.com", "admin@company.org"], }, }, @@ -81,204 +94,217 @@ identity pairing пристрою. } ``` -Важливе правило під час runtime: + +**Важливі правила під час виконання** - Автентифікація trusted-proxy відхиляє запити з loopback-джерела (`127.0.0.1`, `::1`, loopback CIDR). -- Зворотні проксі на тому самому хості через loopback **не** задовольняють trusted-proxy auth. -- Для конфігурацій із loopback-проксі на тому самому хості використовуйте натомість token/password auth або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити. -- Для розгортань Control UI не через loopback усе одно потрібен явний `gateway.controlUi.allowedOrigins`. -- **Докази forwarded-header мають пріоритет над локальністю loopback.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на нелокальне джерело, такі докази скасовують припущення про локальність loopback. Запит розглядається як віддалений для pairing, trusted-proxy auth і шлюзу identity пристрою Control UI. Це не дозволяє loopback-проксі на тому самому хості «відмивати» identity з forwarded-header у trusted-proxy auth. +- Зворотні проксі loopback на тому самому хості **не** задовольняють вимоги автентифікації trusted-proxy. +- Для конфігурацій із loopback-проксі на тому самому хості використовуйте натомість автентифікацію за токеном/паролем або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити. +- Розгортання Control UI поза loopback усе одно потребують явного `gateway.controlUi.allowedOrigins`. +- **Докази з пересланих заголовків мають пріоритет над loopback-локальністю.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на не-локальне джерело, ці докази спростовують твердження про loopback-локальність. Такий запит вважається віддаленим для сполучення, автентифікації trusted-proxy та контролю ідентичності пристрою в Control UI. Це запобігає тому, щоб loopback-проксі на тому самому хості «відмивав» ідентичність із пересланих заголовків у trusted-proxy автентифікацію. + ### Довідник конфігурації -| Поле | Обов’язково | Опис | -| ------------------------------------------- | ----------- | ---------------------------------------------------------------------------- | -| `gateway.trustedProxies` | Так | Масив IP-адрес проксі, яким довіряють. Запити з інших IP відхиляються. | -| `gateway.auth.mode` | Так | Має бути `"trusted-proxy"` | -| `gateway.auth.trustedProxy.userHeader` | Так | Ім’я заголовка, що містить identity автентифікованого користувача | -| `gateway.auth.trustedProxy.requiredHeaders` | Ні | Додаткові заголовки, які мають бути присутні, щоб запит вважався довіреним | -| `gateway.auth.trustedProxy.allowUsers` | Ні | Allowlist identity користувачів. Порожньо означає дозволити всіх автентифікованих користувачів | + + Масив IP-адрес проксі, яким можна довіряти. Запити з інших IP-адрес відхиляються. + + + Має бути `"trusted-proxy"`. + + + Назва заголовка, що містить ідентичність автентифікованого користувача. + + + Додаткові заголовки, які мають бути присутні, щоб запит вважався довіреним. + + + Список дозволених ідентичностей користувачів. Порожньо означає дозволити всіх автентифікованих користувачів. + ## Завершення TLS і HSTS -Використовуйте одну точку завершення TLS і застосовуйте HSTS там. +Використовуйте одну точку завершення TLS і застосовуйте HSTS саме там. -### Рекомендований шаблон: завершення TLS на проксі + + + Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, налаштуйте `Strict-Transport-Security` на проксі для цього домену. -Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, задайте -`Strict-Transport-Security` на проксі для цього домену. + - Добре підходить для розгортань, доступних з інтернету. + - Зберігає сертифікати та політику посилення безпеки HTTP в одному місці. + - OpenClaw може залишатися на loopback HTTP за проксі. -- Добре підходить для розгортань, доступних з інтернету. -- Зберігає сертифікати й політику посилення HTTP в одному місці. -- OpenClaw може залишатися на loopback HTTP за проксі. + Приклад значення заголовка: -Приклад значення заголовка: + ```text + Strict-Transport-Security: max-age=31536000; includeSubDomains + ``` -```text -Strict-Transport-Security: max-age=31536000; includeSubDomains -``` + + + Якщо сам OpenClaw напряму обслуговує HTTPS (без проксі, що завершує TLS), налаштуйте: -### Завершення TLS на Gateway - -Якщо сам OpenClaw напряму обслуговує HTTPS (без проксі, що завершує TLS), задайте: - -```json5 -{ - gateway: { - tls: { enabled: true }, - http: { - securityHeaders: { - strictTransportSecurity: "max-age=31536000; includeSubDomains", + ```json5 + { + gateway: { + tls: { enabled: true }, + http: { + securityHeaders: { + strictTransportSecurity: "max-age=31536000; includeSubDomains", + }, + }, }, - }, - }, -} -``` + } + ``` -`strictTransportSecurity` приймає рядкове значення заголовка або `false` для явного вимкнення. + `strictTransportSecurity` приймає рядкове значення заголовка або `false` для явного вимкнення. + + + ### Рекомендації щодо поетапного впровадження -- Спочатку використовуйте малий max age (наприклад, `max-age=300`), поки перевіряєте трафік. -- Збільшуйте до довгоживучих значень (наприклад, `max-age=31536000`) лише після достатньої впевненості. +- Спочатку використовуйте короткий max age (наприклад, `max-age=300`) під час перевірки трафіку. +- Збільшуйте до довготривалих значень (наприклад, `max-age=31536000`) лише після того, як будете повністю впевнені. - Додавайте `includeSubDomains` лише якщо кожен піддомен готовий до HTTPS. -- Використовуйте preload лише якщо ви свідомо виконуєте вимоги preload для всього набору доменів. -- Локальна розробка лише через loopback не отримує користі від HSTS. +- Використовуйте preload лише якщо ви навмисно виконуєте вимоги preload для всього набору ваших доменів. +- Локальна розробка лише на loopback не отримує переваг від HSTS. ## Приклади налаштування проксі -### Pomerium + + + Pomerium передає ідентичність у `x-pomerium-claim-email` (або інші заголовки claims) і JWT у `x-pomerium-jwt-assertion`. -Pomerium передає identity в `x-pomerium-claim-email` (або інші claim-заголовки) і JWT в `x-pomerium-jwt-assertion`. - -```json5 -{ - gateway: { - bind: "lan", - trustedProxies: ["10.0.0.1"], // Pomerium's IP - auth: { - mode: "trusted-proxy", - trustedProxy: { - userHeader: "x-pomerium-claim-email", - requiredHeaders: ["x-pomerium-jwt-assertion"], + ```json5 + { + gateway: { + bind: "lan", + trustedProxies: ["10.0.0.1"], // IP-адреса Pomerium + auth: { + mode: "trusted-proxy", + trustedProxy: { + userHeader: "x-pomerium-claim-email", + requiredHeaders: ["x-pomerium-jwt-assertion"], + }, + }, }, - }, - }, -} -``` - -Фрагмент конфігурації Pomerium: - -```yaml -routes: - - from: https://openclaw.example.com - to: http://openclaw-gateway:18789 - policy: - - allow: - or: - - email: - is: nick@example.com - pass_identity_headers: true -``` - -### Caddy з OAuth - -Caddy з Plugin `caddy-security` може автентифікувати користувачів і передавати заголовки identity. - -```json5 -{ - gateway: { - bind: "lan", - trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP - auth: { - mode: "trusted-proxy", - trustedProxy: { - userHeader: "x-forwarded-user", - }, - }, - }, -} -``` - -Фрагмент Caddyfile: - -``` -openclaw.example.com { - authenticate with oauth2_provider - authorize with policy1 - - reverse_proxy openclaw:18789 { - header_up X-Forwarded-User {http.auth.user.email} } -} -``` + ``` -### nginx + oauth2-proxy + Фрагмент конфігурації Pomerium: -oauth2-proxy автентифікує користувачів і передає identity в `x-auth-request-email`. + ```yaml + routes: + - from: https://openclaw.example.com + to: http://openclaw-gateway:18789 + policy: + - allow: + or: + - email: + is: nick@example.com + pass_identity_headers: true + ``` -```json5 -{ - gateway: { - bind: "lan", - trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP - auth: { - mode: "trusted-proxy", - trustedProxy: { - userHeader: "x-auth-request-email", + + + Caddy з Plugin `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності. + + ```json5 + { + gateway: { + bind: "lan", + trustedProxies: ["10.0.0.1"], // IP-адреса Caddy/sidecar proxy + auth: { + mode: "trusted-proxy", + trustedProxy: { + userHeader: "x-forwarded-user", + }, + }, }, - }, - }, -} -``` + } + ``` -Фрагмент конфігурації nginx: + Фрагмент Caddyfile: -```nginx -location / { - auth_request /oauth2/auth; - auth_request_set $user $upstream_http_x_auth_request_email; + ``` + openclaw.example.com { + authenticate with oauth2_provider + authorize with policy1 - proxy_pass http://openclaw:18789; - proxy_set_header X-Auth-Request-Email $user; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; -} -``` + reverse_proxy openclaw:18789 { + header_up X-Forwarded-User {http.auth.user.email} + } + } + ``` -### Traefik з Forward Auth + + + oauth2-proxy автентифікує користувачів і передає ідентичність у `x-auth-request-email`. -```json5 -{ - gateway: { - bind: "lan", - trustedProxies: ["172.17.0.1"], // Traefik container IP - auth: { - mode: "trusted-proxy", - trustedProxy: { - userHeader: "x-forwarded-user", + ```json5 + { + gateway: { + bind: "lan", + trustedProxies: ["10.0.0.1"], // IP-адреса nginx/oauth2-proxy + auth: { + mode: "trusted-proxy", + trustedProxy: { + userHeader: "x-auth-request-email", + }, + }, }, - }, - }, -} -``` + } + ``` + + Фрагмент конфігурації nginx: + + ```nginx + location / { + auth_request /oauth2/auth; + auth_request_set $user $upstream_http_x_auth_request_email; + + proxy_pass http://openclaw:18789; + proxy_set_header X-Auth-Request-Email $user; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + ``` + + + + ```json5 + { + gateway: { + bind: "lan", + trustedProxies: ["172.17.0.1"], // IP-адреса контейнера Traefik + auth: { + mode: "trusted-proxy", + trustedProxy: { + userHeader: "x-forwarded-user", + }, + }, + }, + } + ``` + + ## Змішана конфігурація токенів -OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`) і режим `trusted-proxy`. Змішані конфігурації токенів можуть призвести до того, що loopback-запити тихо автентифікуються через неправильний шлях автентифікації. +OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`) і режим `trusted-proxy`. Змішані конфігурації токенів можуть призвести до того, що loopback-запити мовчки автентифікуватимуться неправильним шляхом автентифікації. Якщо під час запуску ви бачите помилку `mixed_trusted_proxy_token`: -- Видаліть спільний токен під час використання режиму trusted-proxy, або -- Перемкніть `gateway.auth.mode` на `"token"`, якщо ви справді хочете автентифікацію на основі токена. +- Видаліть спільний токен, якщо використовуєте режим trusted-proxy, або +- Змініть `gateway.auth.mode` на `"token"`, якщо ви маєте намір використовувати автентифікацію на основі токена. -Автентифікація trusted-proxy через loopback також завершується безпечною відмовою: виклики з того самого хоста мають надсилати налаштовані заголовки identity через довірений проксі, а не автентифікуватися мовчки. +Loopback trusted-proxy автентифікація також працює за принципом fail closed: виклики з того самого хоста мають передавати налаштовані заголовки ідентичності через довірений проксі, а не автентифікуватися мовчки. -## Заголовок операторських scope +## Заголовок областей операторів -Автентифікація trusted-proxy — це HTTP-режим, що **переносить identity**, тому виклики -можуть необов’язково оголошувати operator scope через `x-openclaw-scopes`. +Автентифікація trusted-proxy — це HTTP-режим, **що несе ідентичність**, тому виклики можуть за бажанням оголошувати області операторів через `x-openclaw-scopes`. Приклади: @@ -288,118 +314,130 @@ OpenClaw відхиляє неоднозначні конфігурації, у Поведінка: -- Коли заголовок присутній, OpenClaw дотримується оголошеного набору scope. -- Коли заголовок присутній, але порожній, запит оголошує **відсутність** operator scope. -- Коли заголовок відсутній, звичайні HTTP API, що переносять identity, повертаються до стандартного типового набору operator scope. -- **Plugin HTTP routes** з gateway-auth типово вужчі: коли `x-openclaw-scopes` відсутній, їхній runtime scope повертається до `operator.write`. -- HTTP-запити з браузера все одно мають пройти `gateway.controlUi.allowedOrigins` (або навмисний fallback-режим заголовка Host) навіть після успішної trusted-proxy auth. +- Коли заголовок присутній, OpenClaw враховує оголошений набір областей. +- Коли заголовок присутній, але порожній, запит оголошує **жодних** областей операторів. +- Коли заголовок відсутній, звичайні HTTP API, що несуть ідентичність, повертаються до стандартного набору областей операторів за замовчуванням. +- **HTTP-маршрути Plugin** з gateway-auth за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня область виконання повертається до `operator.write`. +- HTTP-запити з браузера все одно мають проходити `gateway.controlUi.allowedOrigins` (або навмисний резервний режим Host-заголовка), навіть після успішної trusted-proxy автентифікації. -Практичне правило: - -- Явно надсилайте `x-openclaw-scopes`, коли хочете, щоб запит trusted-proxy - був вужчим за типові значення, або коли gateway-auth Plugin route потребує - чогось сильнішого за scope write. +Практичне правило: надсилайте `x-openclaw-scopes` явно, коли хочете, щоб trusted-proxy запит мав вужчі області, ніж типові значення за замовчуванням, або коли маршруту Plugin з gateway-auth потрібне щось сильніше за область write. ## Контрольний список безпеки -Перед увімкненням автентифікації trusted-proxy перевірте: +Перш ніж увімкнути автентифікацію trusted-proxy, перевірте: -- [ ] **Проксі — єдиний шлях**: порт Gateway закритий фаєрволом від усього, крім вашого проксі -- [ ] **trustedProxies мінімальний**: лише фактичні IP вашого проксі, а не цілі підмережі -- [ ] **Немає loopback-джерела проксі**: trusted-proxy auth завершується безпечною відмовою для запитів із loopback-джерела -- [ ] **Проксі очищує заголовки**: ваш проксі перезаписує (а не дописує) заголовки `x-forwarded-*`, отримані від клієнтів -- [ ] **Завершення TLS**: ваш проксі обробляє TLS; користувачі підключаються через HTTPS -- [ ] **allowedOrigins задано явно**: для non-loopback Control UI використовується явний `gateway.controlUi.allowedOrigins` -- [ ] **allowUsers задано** (рекомендовано): обмежуйте доступ відомими користувачами замість дозволу будь-кому з автентифікацією -- [ ] **Немає змішаної конфігурації токенів**: не задавайте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"` +- [ ] **Проксі є єдиним шляхом**: Порт Gateway захищений фаєрволом від усього, окрім вашого проксі. +- [ ] **trustedProxies мінімальний**: Лише фактичні IP-адреси вашого проксі, а не цілі підмережі. +- [ ] **Немає loopback-джерела проксі**: автентифікація trusted-proxy працює за принципом fail closed для запитів із loopback-джерела. +- [ ] **Проксі видаляє заголовки**: Ваш проксі перезаписує (а не додає) заголовки `x-forwarded-*`, отримані від клієнтів. +- [ ] **Завершення TLS**: Ваш проксі обробляє TLS; користувачі підключаються через HTTPS. +- [ ] **allowedOrigins явний**: Control UI поза loopback використовує явний `gateway.controlUi.allowedOrigins`. +- [ ] **allowUsers налаштовано** (рекомендовано): Обмежуйте доступ відомими користувачами, а не дозволяйте будь-кому, хто пройшов автентифікацію. +- [ ] **Немає змішаної конфігурації токена**: Не налаштовуйте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`. ## Аудит безпеки -`openclaw security audit` позначатиме trusted-proxy auth як проблему з рівнем **critical**. Це навмисно — нагадування про те, що ви делегуєте безпеку конфігурації свого проксі. +`openclaw security audit` позначить автентифікацію trusted-proxy як проблему з рівнем серйозності **critical**. Це навмисно — це нагадування про те, що ви делегуєте безпеку вашій конфігурації проксі. Аудит перевіряє: -- базове попередження/нагадування `gateway.trusted_proxy_auth` рівня warning/critical -- відсутню конфігурацію `trustedProxies` -- відсутню конфігурацію `userHeader` -- порожній `allowUsers` (дозволяє будь-якому автентифікованому користувачу) -- wildcard або відсутню політику browser-origin на відкритих поверхнях Control UI +- Базове попередження/нагадування warning/critical для `gateway.trusted_proxy_auth` +- Відсутня конфігурація `trustedProxies` +- Відсутня конфігурація `userHeader` +- Порожній `allowUsers` (дозволяє будь-якого автентифікованого користувача) +- Політика browser-origin із wildcard або її відсутність на відкритих поверхнях Control UI -## Усунення проблем +## Усунення несправностей -### `trusted_proxy_untrusted_source` + + + Запит не надійшов з IP-адреси, вказаної в `gateway.trustedProxies`. Перевірте: -Запит надійшов не з IP-адреси з `gateway.trustedProxies`. Перевірте: + - Чи правильна IP-адреса проксі? (IP-адреси контейнерів Docker можуть змінюватися.) + - Чи є балансувальник навантаження перед вашим проксі? + - Використайте `docker inspect` або `kubectl get pods -o wide`, щоб знайти фактичні IP-адреси. -- Чи правильна IP-адреса проксі? (IP контейнерів Docker можуть змінюватися) -- Чи є балансувальник навантаження перед вашим проксі? -- Використовуйте `docker inspect` або `kubectl get pods -o wide`, щоб знайти реальні IP-адреси + + + OpenClaw відхилив trusted-proxy запит із loopback-джерела. -### `trusted_proxy_loopback_source` + Перевірте: -OpenClaw відхилив trusted-proxy-запит із loopback-джерела. + - Чи підключається проксі з `127.0.0.1` / `::1`? + - Чи намагаєтеся ви використовувати trusted-proxy автентифікацію зі зворотним loopback-проксі на тому самому хості? -Перевірте: + Виправлення: -- Чи підключається проксі з `127.0.0.1` / `::1`? -- Чи намагаєтеся ви використовувати trusted-proxy auth із loopback reverse proxy на тому самому хості? + - Використовуйте автентифікацію за токеном/паролем для конфігурацій із loopback-проксі на тому самому хості, або + - Маршрутизуйте через не-loopback адресу довіреного проксі та збережіть цю IP-адресу в `gateway.trustedProxies`. -Виправлення: + + + Заголовок користувача був порожній або відсутній. Перевірте: -- Використовуйте token/password auth для конфігурацій із loopback proxy на тому самому хості, або -- Маршрутизуйте через не-loopback адресу довіреного проксі й тримайте цю IP-адресу в `gateway.trustedProxies`. + - Чи налаштований ваш проксі на передавання заголовків ідентичності? + - Чи правильна назва заголовка? (регістр не має значення, але написання має) + - Чи користувач справді автентифікований на проксі? -### `trusted_proxy_user_missing` + + + Обов’язковий заголовок був відсутній. Перевірте: -Заголовок користувача був порожнім або відсутнім. Перевірте: + - Конфігурацію вашого проксі для цих конкретних заголовків. + - Чи не видаляються заголовки десь у ланцюжку. -- Чи налаштований ваш проксі на передавання заголовків identity? -- Чи правильна назва заголовка? (без урахування регістру, але написання важливе) -- Чи користувач справді автентифікований на проксі? + + + Користувач автентифікований, але його немає в `allowUsers`. Або додайте його, або видаліть список дозволених. + + + Trusted-proxy автентифікація пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки походження Control UI. -### `trusted_proxy_missing_header*` + Перевірте: -Не було одного з обов’язкових заголовків. Перевірте: + - `gateway.controlUi.allowedOrigins` містить точне browser origin. + - Ви не покладаєтеся на wildcard origins, якщо тільки навмисно не хочете поведінку «дозволити все». + - Якщо ви навмисно використовуєте резервний режим Host-заголовка, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` налаштовано свідомо. -- Конфігурацію вашого проксі для цих конкретних заголовків -- Чи не видаляються заголовки десь у ланцюжку + + + Переконайтеся, що ваш проксі: -### `trusted_proxy_user_not_allowed` + - Підтримує оновлення WebSocket (`Upgrade: websocket`, `Connection: upgrade`). + - Передає заголовки ідентичності в запитах на оновлення WebSocket (а не лише для HTTP). + - Не має окремого шляху автентифікації для з’єднань WebSocket. -Користувач автентифікований, але його немає в `allowUsers`. Або додайте його, або приберіть allowlist. + + -### `trusted_proxy_origin_not_allowed` +## Міграція з автентифікації за токеном -Автентифікація trusted-proxy пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки origin у Control UI. +Якщо ви переходите з автентифікації за токеном на trusted-proxy: -Перевірте: - -- `gateway.controlUi.allowedOrigins` містить точний origin браузера -- Ви не покладаєтеся на wildcard origins, якщо тільки свідомо не хочете дозволити все -- Якщо ви свідомо використовуєте fallback-режим заголовка Host, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` задано навмисно - -### WebSocket усе ще не працює - -Переконайтеся, що ваш проксі: - -- Підтримує WebSocket upgrade (`Upgrade: websocket`, `Connection: upgrade`) -- Передає заголовки identity у запитах WebSocket upgrade (а не лише HTTP) -- Не має окремого шляху автентифікації для з’єднань WebSocket - -## Міграція з token auth - -Якщо ви переходите з token auth на trusted-proxy: - -1. Налаштуйте проксі на автентифікацію користувачів і передавання заголовків -2. Перевірте конфігурацію проксі незалежно (curl із заголовками) -3. Оновіть конфігурацію OpenClaw для trusted-proxy auth -4. Перезапустіть Gateway -5. Перевірте WebSocket-з’єднання з Control UI -6. Запустіть `openclaw security audit` і перегляньте результати + + + Налаштуйте ваш проксі на автентифікацію користувачів і передавання заголовків. + + + Окремо протестуйте налаштування проксі (`curl` із заголовками). + + + Оновіть конфігурацію OpenClaw для trusted-proxy автентифікації. + + + Перезапустіть Gateway. + + + Перевірте з’єднання WebSocket з Control UI. + + + Запустіть `openclaw security audit` і перегляньте результати. + + ## Пов’язане -- [Security](/uk/gateway/security) — повний посібник із безпеки -- [Configuration](/uk/gateway/configuration) — довідник конфігурації -- [Remote Access](/uk/gateway/remote) — інші шаблони віддаленого доступу +- [Конфігурація](/uk/gateway/configuration) — довідник конфігурації +- [Віддалений доступ](/uk/gateway/remote) — інші шаблони віддаленого доступу +- [Безпека](/uk/gateway/security) — повний посібник із безпеки - [Tailscale](/uk/gateway/tailscale) — простіша альтернатива для доступу лише в межах tailnet diff --git a/docs/uk/nodes/media-understanding.md b/docs/uk/nodes/media-understanding.md index 462fa9aef..6203be7f9 100644 --- a/docs/uk/nodes/media-understanding.md +++ b/docs/uk/nodes/media-understanding.md @@ -2,77 +2,92 @@ read_when: - Проєктування або рефакторинг розуміння медіа - Налаштування попередньої обробки вхідного аудіо/відео/зображень -summary: Розуміння вхідних зображень/аудіо/відео (необов’язково) з резервними варіантами через провайдера та CLI +sidebarTitle: Media understanding +summary: Вхідне розуміння зображень/аудіо/відео (необов’язково) з резервними варіантами через провайдера + CLI title: Розуміння медіа x-i18n: - generated_at: "2026-04-26T04:25:09Z" + generated_at: "2026-04-26T08:15:40Z" model: gpt-5.4 provider: openai - source_hash: 513fe1557bb3fce3189f7009d85ad13f43713521243a95fd9427a4c89b57f238 + source_hash: 25ee170a7af523fd2ce4f5f7764638f510b135f94a7796325daf1c3e04147f90 source_path: nodes/media-understanding.md workflow: 15 --- -# Розуміння медіа — вхідні дані (2026-01-17) +OpenClaw може **підсумовувати вхідні медіа** (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, коли доступні локальні інструменти або ключі провайдера, і може бути вимкнений або налаштований. Якщо розуміння вимкнене, моделі, як і раніше, отримують оригінальні файли/URL. -OpenClaw може **узагальнювати вхідні медіа** (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, чи доступні локальні інструменти або ключі провайдера, і цю функцію можна вимкнути або налаштувати. Якщо розуміння вимкнене, моделі, як і раніше, отримують вихідні файли/URL-адреси. - -Поведінка медіа для конкретних постачальників реєструється через vendor Plugin, тоді як -ядро OpenClaw керує спільною конфігурацією `tools.media`, порядком резервних варіантів і -інтеграцією в конвеєр відповіді. +Поведінка медіа, специфічна для постачальника, реєструється плагінами постачальників, тоді як ядро OpenClaw відповідає за спільну конфігурацію `tools.media`, порядок резервних варіантів і інтеграцію з конвеєром відповіді. ## Цілі -- Необов’язково: попередньо перетворювати вхідні медіа на короткий текст для швидшої маршрутизації й кращого розбору команд. -- Завжди зберігати доставку оригінальних медіа до моделі. +- Необов’язково: попередньо зводити вхідні медіа до короткого тексту для швидшої маршрутизації та кращого розбору команд. +- Зберігати доставку оригінальних медіа до моделі (завжди). - Підтримувати **API провайдерів** і **резервні варіанти CLI**. - Дозволяти кілька моделей з упорядкованим резервуванням (помилка/розмір/тайм-аут). ## Поведінка на високому рівні -1. Зібрати вхідні вкладення (`MediaPaths`, `MediaUrls`, `MediaTypes`). -2. Для кожної ввімкненої можливості (зображення/аудіо/відео) вибрати вкладення відповідно до політики (типово: **перше**). -3. Вибрати перший придатний запис моделі (розмір + можливість + автентифікація). -4. Якщо модель не спрацьовує або медіа завелике, **перейти до наступного запису**. -5. У разі успіху: - - `Body` стає блоком `[Image]`, `[Audio]` або `[Video]`. - - Для аудіо встановлюється `{{Transcript}}`; розбір команд використовує текст підпису, якщо він є, інакше — транскрипт. - - Підписи зберігаються як `User text:` усередині блоку. + + + Збирає вхідні вкладення (`MediaPaths`, `MediaUrls`, `MediaTypes`). + + + Для кожної ввімкненої можливості (зображення/аудіо/відео) вибирає вкладення згідно з політикою (типово: **перше**). + + + Вибирає перший придатний запис моделі (розмір + можливість + автентифікація). + + + Якщо модель завершується з помилкою або медіа надто велике, **переходить до наступного запису**. + + + У разі успіху: -Якщо розуміння не спрацювало або вимкнене, **потік відповіді продовжується** з початковим body і вкладеннями. + - `Body` стає блоком `[Image]`, `[Audio]` або `[Video]`. + - Для аудіо встановлюється `{{Transcript}}`; розбір команд використовує текст підпису, якщо він є, інакше — транскрипт. + - Підписи зберігаються як `User text:` усередині блоку. + + + + +Якщо розуміння завершується невдачею або вимкнене, **потік відповіді продовжується** з початковим тілом і вкладеннями. ## Огляд конфігурації -`tools.media` підтримує **спільні моделі** плюс перевизначення для кожної можливості: +`tools.media` підтримує **спільні моделі**, а також перевизначення для окремих можливостей: -- `tools.media.models`: спільний список моделей (використовуйте `capabilities` для обмеження). -- `tools.media.image` / `tools.media.audio` / `tools.media.video`: - - типові значення (`prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`) - - перевизначення провайдера (`baseUrl`, `headers`, `providerOptions`) - - параметри аудіо Deepgram через `tools.media.audio.providerOptions.deepgram` - - параметри відображення транскрипту аудіо (`echoTranscript`, типово `false`; `echoFormat`) - - необов’язковий список `models` **для конкретної можливості** (має пріоритет над спільними моделями) - - політика `attachments` (`mode`, `maxAttachments`, `prefer`) - - `scope` (необов’язкове обмеження за channel/chatType/session key) -- `tools.media.concurrency`: максимальна кількість одночасних запусків можливостей (типово **2**). + + + - `tools.media.models`: спільний список моделей (використовуйте `capabilities` для обмеження). + - `tools.media.image` / `tools.media.audio` / `tools.media.video`: + - типові значення (`prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`) + - перевизначення провайдера (`baseUrl`, `headers`, `providerOptions`) + - параметри аудіо Deepgram через `tools.media.audio.providerOptions.deepgram` + - параметри відлуння аудіотранскрипту (`echoTranscript`, типово `false`; `echoFormat`) + - необов’язковий список `models` **для окремої можливості** (має пріоритет над спільними моделями) + - політика `attachments` (`mode`, `maxAttachments`, `prefer`) + - `scope` (необов’язкове обмеження за каналом/chatType/ключем сесії) + - `tools.media.concurrency`: максимальна кількість одночасних запусків можливостей (типово **2**). + + ```json5 { tools: { media: { models: [ - /* спільний список */ + /* shared list */ ], image: { - /* необов’язкові перевизначення */ + /* optional overrides */ }, audio: { - /* необов’язкові перевизначення */ + /* optional overrides */ echoTranscript: true, echoFormat: '📝 "{transcript}"', }, video: { - /* необов’язкові перевизначення */ + /* optional overrides */ }, }, }, @@ -81,101 +96,114 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб ### Записи моделей -Кожен запис `models[]` може бути типу **provider** або **CLI**: +Кожен запис `models[]` може бути **provider** або **CLI**: -```json5 -{ - type: "provider", // типово, якщо не вказано - provider: "openai", - model: "gpt-5.5", - prompt: "Опишіть зображення не більше ніж у 500 символах.", - maxChars: 500, - maxBytes: 10485760, - timeoutSeconds: 60, - capabilities: ["image"], // необов’язково, використовується для мультимодальних записів - profile: "vision-profile", - preferredProfile: "vision-fallback", -} -``` + + + ```json5 + { + type: "provider", // default if omitted + provider: "openai", + model: "gpt-5.5", + prompt: "Describe the image in <= 500 chars.", + maxChars: 500, + maxBytes: 10485760, + timeoutSeconds: 60, + capabilities: ["image"], // optional, used for multi-modal entries + profile: "vision-profile", + preferredProfile: "vision-fallback", + } + ``` + + + ```json5 + { + type: "cli", + command: "gemini", + args: [ + "-m", + "gemini-3-flash", + "--allowed-tools", + "read_file", + "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + ], + maxChars: 500, + maxBytes: 52428800, + timeoutSeconds: 120, + capabilities: ["video", "image"], + } + ``` -```json5 -{ - type: "cli", - command: "gemini", - args: [ - "-m", - "gemini-3-flash", - "--allowed-tools", - "read_file", - "Прочитайте медіа за адресою {{MediaPath}} і опишіть його не більше ніж у {{MaxChars}} символах.", - ], - maxChars: 500, - maxBytes: 52428800, - timeoutSeconds: 120, - capabilities: ["video", "image"], -} -``` + Шаблони CLI також можуть використовувати: -Шаблони CLI також можуть використовувати: + - `{{MediaDir}}` (каталог, що містить медіафайл) + - `{{OutputDir}}` (тимчасовий каталог, створений для цього запуску) + - `{{OutputBase}}` (базовий шлях тимчасового файла без розширення) -- `{{MediaDir}}` (каталог, що містить медіафайл) -- `{{OutputDir}}` (тимчасовий каталог, створений для цього запуску) -- `{{OutputBase}}` (базовий шлях тимчасового файла без розширення) + + -## Типові значення й обмеження +## Типові значення та обмеження Рекомендовані типові значення: - `maxChars`: **500** для зображень/відео (коротко, зручно для команд) -- `maxChars`: **не задано** для аудіо (повний транскрипт, якщо ви не встановили обмеження) +- `maxChars`: **не задано** для аудіо (повний транскрипт, якщо ви не встановите обмеження) - `maxBytes`: - зображення: **10MB** - аудіо: **20MB** - відео: **50MB** -Правила: - -- Якщо медіа перевищує `maxBytes`, цю модель пропускають і **пробують наступну модель**. -- Аудіофайли менші за **1024 байти** вважаються порожніми/пошкодженими й пропускаються до транскрибування через провайдера/CLI; вхідний контекст відповіді отримує детермінований заповнювач транскрипту, щоб агент знав, що нотатка була замалою. -- Якщо модель повертає більше за `maxChars`, результат обрізається. -- `prompt` типово дорівнює простому «Опишіть {media}.» плюс вказівка щодо `maxChars` (лише для зображень/відео). -- Якщо активна основна модель зображень уже нативно підтримує vision, OpenClaw - пропускає блок підсумку `[Image]` і натомість передає оригінальне зображення в - модель. -- Якщо основна модель Gateway/WebChat є лише текстовою, вкладення зображень - зберігаються як винесені посилання `media://inbound/*`, щоб інструменти - зображень/PDF або налаштована модель зображень усе ще могли їх перевіряти, а вкладення не втрачалося. -- Явні запити `openclaw infer image describe --model ` - відрізняються: вони запускають безпосередньо цей provider/model з підтримкою зображень, зокрема - посилання Ollama, такі як `ollama/qwen2.5vl:7b`. -- Якщо `.enabled: true`, але моделі не налаштовані, OpenClaw пробує - **активну модель відповіді**, якщо її провайдер підтримує цю можливість. + + + - Якщо медіа перевищує `maxBytes`, ця модель пропускається і **використовується наступна модель**. + - Аудіофайли менші за **1024 байти** вважаються порожніми/пошкодженими й пропускаються до транскрибування через provider/CLI; вхідний контекст відповіді отримує детермінований заповнювач транскрипту, щоб агент знав, що нотатка була надто малою. + - Якщо модель повертає більше ніж `maxChars`, вивід обрізається. + - `prompt` типово дорівнює простому "Describe the {media}." плюс вказівка `maxChars` (лише для зображення/відео). + - Якщо активна основна модель для зображень уже нативно підтримує vision, OpenClaw пропускає блок підсумку `[Image]` і натомість передає оригінальне зображення в модель. + - Якщо основна модель Gateway/WebChat є лише текстовою, вкладення зображень зберігаються як винесені посилання `media://inbound/*`, щоб інструменти зображень/PDF або налаштована модель зображень усе ще могли їх перевірити замість втрати вкладення. + - Явні запити `openclaw infer image describe --model ` відрізняються: вони напряму запускають вказану provider/model із підтримкою зображень, включно з посиланнями Ollama, такими як `ollama/qwen2.5vl:7b`. + - Якщо `.enabled: true`, але моделі не налаштовані, OpenClaw пробує **активну модель відповіді**, якщо її провайдер підтримує цю можливість. + + ### Автовизначення розуміння медіа (типово) -Якщо `tools.media..enabled` **не** встановлено в `false` і ви не -налаштували моделі, OpenClaw виконує автовизначення в такому порядку й **зупиняється на першому -робочому варіанті**: +Якщо `tools.media..enabled` **не** встановлено в `false` і ви не налаштували моделі, OpenClaw автоматично визначає в такому порядку і **зупиняється на першому робочому варіанті**: -1. **Активна модель відповіді**, якщо її провайдер підтримує цю можливість. -2. Основні/резервні посилання `agents.defaults.imageModel` (лише для зображень). -3. **Локальні CLI** (лише для аудіо; якщо встановлені) - - `sherpa-onnx-offline` (потребує `SHERPA_ONNX_MODEL_DIR` з encoder/decoder/joiner/tokens) - - `whisper-cli` (`whisper-cpp`; використовує `WHISPER_CPP_MODEL` або вбудовану tiny-модель) - - `whisper` (Python CLI; автоматично завантажує моделі) -4. **Gemini CLI** (`gemini`) з використанням `read_many_files` -5. **Автентифікація провайдера** - - Налаштовані записи `models.providers.*`, які підтримують цю можливість, - пробуються до вбудованого резервного порядку. - - Провайдери з конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розуміння медіа, навіть якщо вони не є вбудованим vendor Plugin. - - Розуміння зображень Ollama доступне при явному виборі, наприклад через `agents.defaults.imageModel` або - `openclaw infer image describe --model ollama/`. - - Вбудований резервний порядок: - - Аудіо: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral - - Зображення: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI - - Відео: Google → Qwen → Moonshot + + + Активна модель відповіді, якщо її провайдер підтримує цю можливість. + + + Основні/резервні посилання `agents.defaults.imageModel` (лише для зображень). + + + Локальні CLI (якщо встановлені): -Щоб вимкнути автовизначення, установіть: + - `sherpa-onnx-offline` (потребує `SHERPA_ONNX_MODEL_DIR` з encoder/decoder/joiner/tokens) + - `whisper-cli` (`whisper-cpp`; використовує `WHISPER_CPP_MODEL` або вбудовану tiny model) + - `whisper` (Python CLI; автоматично завантажує моделі) + + + + `gemini` з `read_many_files`. + + + - Налаштовані записи `models.providers.*`, які підтримують цю можливість, пробуються до вбудованого порядку резервування. + - Провайдери конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розуміння медіа, навіть якщо вони не є вбудованим плагіном постачальника. + - Розуміння зображень Ollama доступне за явного вибору, наприклад через `agents.defaults.imageModel` або `openclaw infer image describe --model ollama/`. + + Вбудований порядок резервування: + + - Аудіо: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral + - Зображення: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI + - Відео: Google → Qwen → Moonshot + + + + +Щоб вимкнути автовизначення, встановіть: ```json5 { @@ -189,26 +217,24 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб } ``` -Примітка: виявлення двійкових файлів працює за принципом best-effort у macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну модель CLI з повним шляхом до команди. + +Визначення двійкових файлів виконується за принципом best-effort у macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну CLI-модель із повним шляхом до команди. + -### Підтримка проксі через середовище (моделі провайдерів) +### Підтримка проксі-середовища (моделі provider) -Коли ввімкнено розуміння медіа **аудіо** та **відео** на основі провайдера, OpenClaw -дотримується стандартних змінних середовища вихідного проксі для HTTP-викликів до провайдера: +Коли ввімкнено розуміння медіа **audio** та **video** на основі provider, OpenClaw враховує стандартні змінні середовища вихідного проксі для HTTP-викликів до провайдера: - `HTTPS_PROXY` - `HTTP_PROXY` - `https_proxy` - `http_proxy` -Якщо змінні середовища проксі не задані, розуміння медіа використовує прямий вихідний трафік. -Якщо значення проксі має неправильний формат, OpenClaw журналює попередження й повертається до прямого -отримання. +Якщо жодні змінні середовища проксі не встановлені, розуміння медіа використовує прямий вихідний трафік. Якщо значення проксі некоректне, OpenClaw записує попередження в журнал і повертається до прямого отримання. ## Можливості (необов’язково) -Якщо ви задаєте `capabilities`, запис запускається лише для цих типів медіа. Для спільних -списків OpenClaw може визначати типові значення: +Якщо ви встановите `capabilities`, запис виконуватиметься лише для цих типів медіа. Для спільних списків OpenClaw може вивести типові значення: - `openai`, `anthropic`, `minimax`: **image** - `minimax-portal`: **image** @@ -221,226 +247,223 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб - `groq`: **audio** - `xai`: **audio** - `deepgram`: **audio** -- Будь-який каталог `models.providers..models[]` із моделлю, що підтримує зображення: - **image** +- Будь-який каталог `models.providers..models[]` із моделлю, що підтримує зображення: **image** -Для записів CLI **вказуйте `capabilities` явно**, щоб уникнути неочікуваних збігів. -Якщо `capabilities` не вказано, запис придатний для списку, у якому він з’являється. +Для записів CLI **явно задавайте `capabilities`**, щоб уникнути неочікуваних збігів. Якщо ви не вкажете `capabilities`, запис придатний для списку, у якому він знаходиться. -## Матриця підтримки провайдерів (інтеграції OpenClaw) +## Матриця підтримки provider (інтеграції OpenClaw) -| Можливість | Інтеграція провайдера | Примітки | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Зображення | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, провайдери з конфігурації | Підтримку зображень реєструють vendor Plugin; `openai-codex/*` використовує механізм OAuth-провайдера; `codex/*` використовує обмежений хід Codex app-server; MiniMax і MiniMax OAuth обидва використовують `MiniMax-VL-01`; провайдери з конфігурації, що підтримують зображення, реєструються автоматично. | -| Аудіо | OpenAI, Groq, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral | Транскрибування провайдерами (Whisper/Groq/xAI/Deepgram/Gemini/SenseAudio/Scribe/Voxtral). | -| Відео | Google, Qwen, Moonshot | Розуміння відео через провайдерів за допомогою vendor Plugin; розуміння відео Qwen використовує стандартні кінцеві точки DashScope. | +| Можливість | Інтеграція provider | Примітки | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Зображення | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Плагіни постачальників реєструють підтримку зображень; `openai-codex/*` використовує механіку OAuth-провайдера; `codex/*` використовує обмежений хід Codex app-server; MiniMax і MiniMax OAuth обидва використовують `MiniMax-VL-01`; config providers із підтримкою зображень реєструються автоматично. | +| Аудіо | OpenAI, Groq, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral | Транскрибування через provider (Whisper/Groq/xAI/Deepgram/Gemini/SenseAudio/Scribe/Voxtral). | +| Відео | Google, Qwen, Moonshot | Розуміння відео через provider за допомогою плагінів постачальників; розуміння відео Qwen використовує стандартні кінцеві точки DashScope. | -Примітка щодо MiniMax: + +**Примітка щодо MiniMax** -- Розуміння зображень `minimax` і `minimax-portal` надається через media provider - `MiniMax-VL-01`, що належить Plugin. -- Вбудований текстовий каталог MiniMax усе ще починається з лише текстових моделей; явні - записи `models.providers.minimax` матеріалізують посилання M2.7 chat з підтримкою зображень. +- Розуміння зображень `minimax` і `minimax-portal` походить від провайдера медіа `MiniMax-VL-01`, що належить плагіну. +- Вбудований текстовий каталог MiniMax усе ще починається як лише текстовий; явні записи `models.providers.minimax` матеріалізують чат-посилання M2.7 із підтримкою зображень. + ## Рекомендації щодо вибору моделі -- Віддавайте перевагу найсильнішій моделі останнього покоління, доступній для кожної можливості медіа, коли важливі якість і безпека. -- Для агентів з увімкненими інструментами, які працюють із недовіреними вхідними даними, уникайте старіших/слабших медіамоделей. -- Тримайте принаймні один резервний варіант для кожної можливості заради доступності (якісна модель + швидша/дешевша модель). +- Віддавайте перевагу найсильнішій доступній моделі останнього покоління для кожної медіаможливості, коли важливі якість і безпека. +- Для агентів з увімкненими інструментами, що обробляють недовірені вхідні дані, уникайте старіших/слабших медіамоделей. +- Зберігайте принаймні один резервний варіант на можливість для доступності (якісна модель + швидша/дешевша модель). - Резервні варіанти CLI (`whisper-cli`, `whisper`, `gemini`) корисні, коли API провайдерів недоступні. -- Примітка щодо `parakeet-mlx`: з `--output-dir` OpenClaw читає `/.txt`, якщо формат виводу — `txt` (або не вказаний); формати, відмінні від `txt`, повертаються до stdout. +- Примітка щодо `parakeet-mlx`: з `--output-dir` OpenClaw читає `/.txt`, коли формат виводу — `txt` (або не вказаний); формати, відмінні від `txt`, повертаються до stdout. ## Політика вкладень -Параметр `attachments` для кожної можливості визначає, які вкладення обробляються: +Параметр `attachments` для окремої можливості керує тим, які вкладення обробляються: -- `mode`: `first` (типово) або `all` -- `maxAttachments`: обмеження кількості оброблюваних вкладень (типово **1**) -- `prefer`: `first`, `last`, `path`, `url` + + Чи обробляти перше вибране вкладення або всі. + + + Обмежує кількість оброблених вкладень. + + + Перевага вибору серед кандидатів на вкладення. + Коли `mode: "all"`, результати позначаються як `[Image 1/2]`, `[Audio 2/2]` тощо. -Поведінка вилучення файлових вкладень: - -- Вилучений текст файла обгортається як **недовірений зовнішній вміст** перед тим, як - його буде додано до prompt медіа. -- Вставлений блок використовує явні маркери меж, такі як - `<<>>` / - `<<>>`, і містить рядок метаданих - `Source: External`. -- Цей шлях вилучення з вкладень навмисно пропускає довгий банер - `SECURITY NOTICE:`, щоб не роздувати prompt медіа; маркери меж і - метадані все одно зберігаються. -- Якщо файл не містить тексту, який можна вилучити, OpenClaw вставляє `[No extractable text]`. -- Якщо в цьому шляху PDF переходить до резервного варіанта з рендерингом сторінок у зображення, prompt медіа зберігає - заповнювач `[PDF content rendered to images; images not forwarded to model]`, - оскільки цей крок вилучення з вкладень пересилає текстові блоки, а не відрендерені зображення PDF. + + + - Вилучений текст файла обгортається як **недовірений зовнішній вміст** перед додаванням до запиту медіа. + - Вставлений блок використовує явні маркери меж, такі як `<<>>` / `<<>>`, і містить рядок метаданих `Source: External`. + - Цей шлях вилучення з вкладень навмисно не містить довгий банер `SECURITY NOTICE:`, щоб уникнути роздуття запиту медіа; маркери меж і метадані при цьому зберігаються. + - Якщо файл не має тексту, який можна вилучити, OpenClaw вставляє `[No extractable text]`. + - Якщо PDF у цьому шляху повертається до відрендерених зображень сторінок, запит медіа зберігає заповнювач `[PDF content rendered to images; images not forwarded to model]`, оскільки цей крок вилучення з вкладень передає текстові блоки, а не відрендерені зображення PDF. + + ## Приклади конфігурації -### 1) Спільний список моделей + перевизначення - -```json5 -{ - tools: { - media: { - models: [ - { provider: "openai", model: "gpt-5.5", capabilities: ["image"] }, - { - provider: "google", - model: "gemini-3-flash-preview", - capabilities: ["image", "audio", "video"], - }, - { - type: "cli", - command: "gemini", - args: [ - "-m", - "gemini-3-flash", - "--allowed-tools", - "read_file", - "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + + + ```json5 + { + tools: { + media: { + models: [ + { provider: "openai", model: "gpt-5.5", capabilities: ["image"] }, + { + provider: "google", + model: "gemini-3-flash-preview", + capabilities: ["image", "audio", "video"], + }, + { + type: "cli", + command: "gemini", + args: [ + "-m", + "gemini-3-flash", + "--allowed-tools", + "read_file", + "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + ], + capabilities: ["image", "video"], + }, ], - capabilities: ["image", "video"], + audio: { + attachments: { mode: "all", maxAttachments: 2 }, + }, + video: { + maxChars: 500, + }, }, - ], - audio: { - attachments: { mode: "all", maxAttachments: 2 }, }, - video: { - maxChars: 500, - }, - }, - }, -} -``` - -### 2) Лише аудіо + відео (зображення вимкнено) - -```json5 -{ - tools: { - media: { - audio: { - enabled: true, - models: [ - { provider: "openai", model: "gpt-4o-mini-transcribe" }, - { - type: "cli", - command: "whisper", - args: ["--model", "base", "{{MediaPath}}"], - }, - ], - }, - video: { - enabled: true, - maxChars: 500, - models: [ - { provider: "google", model: "gemini-3-flash-preview" }, - { - type: "cli", - command: "gemini", - args: [ - "-m", - "gemini-3-flash", - "--allowed-tools", - "read_file", - "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + } + ``` + + + ```json5 + { + tools: { + media: { + audio: { + enabled: true, + models: [ + { provider: "openai", model: "gpt-4o-mini-transcribe" }, + { + type: "cli", + command: "whisper", + args: ["--model", "base", "{{MediaPath}}"], + }, ], }, - ], - }, - }, - }, -} -``` - -### 3) Необов’язкове розуміння зображень - -```json5 -{ - tools: { - media: { - image: { - enabled: true, - maxBytes: 10485760, - maxChars: 500, - models: [ - { provider: "openai", model: "gpt-5.5" }, - { provider: "anthropic", model: "claude-opus-4-6" }, - { - type: "cli", - command: "gemini", - args: [ - "-m", - "gemini-3-flash", - "--allowed-tools", - "read_file", - "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + video: { + enabled: true, + maxChars: 500, + models: [ + { provider: "google", model: "gemini-3-flash-preview" }, + { + type: "cli", + command: "gemini", + args: [ + "-m", + "gemini-3-flash", + "--allowed-tools", + "read_file", + "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + ], + }, ], }, - ], + }, }, - }, - }, -} -``` - -### 4) Один мультимодальний запис (явні можливості) - -```json5 -{ - tools: { - media: { - image: { - models: [ - { - provider: "google", - model: "gemini-3.1-pro-preview", - capabilities: ["image", "video", "audio"], + } + ``` + + + ```json5 + { + tools: { + media: { + image: { + enabled: true, + maxBytes: 10485760, + maxChars: 500, + models: [ + { provider: "openai", model: "gpt-5.5" }, + { provider: "anthropic", model: "claude-opus-4-6" }, + { + type: "cli", + command: "gemini", + args: [ + "-m", + "gemini-3-flash", + "--allowed-tools", + "read_file", + "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.", + ], + }, + ], }, - ], + }, }, - audio: { - models: [ - { - provider: "google", - model: "gemini-3.1-pro-preview", - capabilities: ["image", "video", "audio"], + } + ``` + + + ```json5 + { + tools: { + media: { + image: { + models: [ + { + provider: "google", + model: "gemini-3.1-pro-preview", + capabilities: ["image", "video", "audio"], + }, + ], }, - ], - }, - video: { - models: [ - { - provider: "google", - model: "gemini-3.1-pro-preview", - capabilities: ["image", "video", "audio"], + audio: { + models: [ + { + provider: "google", + model: "gemini-3.1-pro-preview", + capabilities: ["image", "video", "audio"], + }, + ], }, - ], + video: { + models: [ + { + provider: "google", + model: "gemini-3.1-pro-preview", + capabilities: ["image", "video", "audio"], + }, + ], + }, + }, }, - }, - }, -} -``` + } + ``` + + -## Вивід status +## Вивід стану -Коли запускається розуміння медіа, `/status` містить короткий підсумковий рядок: +Коли розуміння медіа виконується, `/status` містить короткий підсумковий рядок: ``` 📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes) ``` -Тут показано результат для кожної можливості та вибраний provider/model, якщо застосовно. +Це показує результати для кожної можливості та вибрані provider/model, коли це застосовно. ## Примітки -- Розуміння виконується в режимі **best-effort**. Помилки не блокують відповіді. -- Вкладення все одно передаються моделям, навіть якщо розуміння вимкнене. -- Використовуйте `scope`, щоб обмежити місця запуску розуміння (наприклад, лише приватними повідомленнями). +- Розуміння виконується за принципом **best-effort**. Помилки не блокують відповіді. +- Вкладення все одно передаються моделям, навіть коли розуміння вимкнене. +- Використовуйте `scope`, щоб обмежити, де запускається розуміння (наприклад, лише в приватних повідомленнях). -## Пов’язана документація +## Пов’язане - [Конфігурація](/uk/gateway/configuration) - [Підтримка зображень і медіа](/uk/nodes/images) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index dbd24a49e..e0b5af6bf 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,65 +1,53 @@ --- read_when: - - Ви створюєте Plugin OpenClaw + - Ви створюєте Plugin для OpenClaw - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Маніфест Plugin + вимоги до схеми JSON (сувора валідація конфігурації) -title: Маніфест Plugin +summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) +title: маніфест Plugin x-i18n: - generated_at: "2026-04-26T07:02:44Z" + generated_at: "2026-04-26T08:15:41Z" model: gpt-5.4 provider: openai - source_hash: 12eae5bd8e3ca47e7d2fb2202cd32abba8d79136d14dd5e38f0aac1c30c02e35 + source_hash: b86920ad774c5ef4ace7b546ef44e5b087a8ca694dea622ddb440258ffff4237 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка стосується **лише нативного маніфесту Plugin OpenClaw**. +Ця сторінка призначена лише для **рідного маніфесту Plugin OpenClaw**. -Щодо сумісних макетів пакетів див. [Пакети Plugin](/uk/plugins/bundles). +Сумісні структури пакетів описані в [Пакети Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude - без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- пакет Codex: `.codex-plugin/plugin.json` +- пакет Claude: `.claude-plugin/plugin.json` або стандартна структура компонента Claude без маніфесту +- пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять -валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці структури пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета разом із -оголошеними коренями skill, коренями команд Claude, типовими значеннями -`settings.json` пакета Claude, типовими значеннями LSP пакета Claude та -підтримуваними наборами hook, якщо макет відповідає очікуванням середовища виконання OpenClaw. +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skills, корені команд Claude, стандартні значення Claude-пакета з `settings.json`, стандартні значення LSP для Claude-пакета та підтримувані набори хуків, якщо структура відповідає очікуванням середовища виконання OpenClaw. -Кожен нативний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` -у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються -помилками Plugin і блокують валідацію конфігурації. +Кожен рідний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. -Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). -Щодо нативної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: +Повний посібник із системи Plugin див. у [Plugins](/uk/tools/plugin). +Для рідної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду -вашого Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску -середовища виконання Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску середовища виконання Plugin. **Використовуйте його для:** - ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- метаданих автентифікації, онбордингу й налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) - підказок активації для поверхонь control-plane -- скороченого володіння сімейством моделей +- володіння скороченими сімействами моделей - статичних знімків володіння можливостями (`contracts`) - метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації для конкретного каналу, об’єднаних у поверхні каталогу та валідації +- метаданих конфігурації для конкретних каналів, об’єднаних у поверхні каталогу та валідації -**Не використовуйте його для:** реєстрації поведінки середовища виконання, оголошення -точок входу коду або метаданих встановлення npm. Це належить вашому коду Plugin -і `package.json`. +**Не використовуйте його для:** реєстрації поведінки середовища виконання, оголошення точок входу коду або метаданих встановлення npm. Вони належать коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -80,7 +68,7 @@ OpenClaw також автоматично виявляє ці макети па { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin провайдера OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -108,19 +96,19 @@ OpenClaw також автоматично виявляє ці макети па "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Ключ API OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Ключ API OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Ключ API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -139,72 +127,68 @@ OpenClaw також автоматично виявляє ці макети па ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована схема JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Пропустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб Plugin лишався типово вимкненим. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовуються для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження Plugin до запуску середовища виконання. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього списку лише для читання, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів/baseUrl кінцевих точок, якими володіє маніфест, для маршрутів провайдера, які ядро має класифікувати до завантаження середовища виконання провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей Plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдер або backend CLI, для яких синтетичний hook автентифікації, що належить Plugin, слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, що належать вбудованим Plugin, які представляють несекретний локальний стан, OAuth або ambient credential state. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin, що мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/стану провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw все ще читає це під час вікна депрекейту. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, що використовує той самий базовий ключ API провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Полегшені метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу, керованого env, або поверхонь автентифікації, які мають бачити універсальні допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для засобів вибору в онбордингу, визначення бажаного провайдера та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою все одно володіє середовище виконання Plugin. | -| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | -| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх hook автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search та володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Полегшені типові значення розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | -| `name` | Ні | `string` | Людинозрозуміла назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки чутливості для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Не вказуйте його або задайте будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовуються для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | +| `modelSupport` | Ні | `object` | Метадані скорочених сімейств моделей, що належать маніфесту і використовуються для автозавантаження Plugin до запуску середовища виконання. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього доступного лише для читання списку, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження середовища виконання провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів інференсу CLI, якими володіє цей Plugin. Використовуються для автоактивації під час запуску на основі явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або CLI-бекенди, чиї синтетичні хуки автентифікації, що належать Plugin, слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому Plugin і позначають несекретний локальний стан, OAuth або стан облікових даних із середовища. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin і які мають формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані змінних середовища для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw і далі зчитує це під час перехідного періоду відмови. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер для кодування, що використовує той самий API-ключ базового провайдера й профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища каналів, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів через змінні середовища або для поверхонь автентифікації, які мають бачити узагальнені помічники запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення бажаного провайдера та простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, яке запускається провайдером, командою, каналом, маршрутом і можливостями. Лише метадані; фактичною поведінкою й далі володіє середовище виконання Plugin. | +| `setup` | Ні | `object` | Полегшені описи налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | +| `qaRunners` | Ні | `object[]` | Полегшені описи QA runner, які спільний хост `openclaw qa` використовує до завантаження середовища виконання Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Полегшені стандартні значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту і об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. OpenClaw читає це до завантаження середовища виконання провайдера. -Списки налаштування провайдера використовують ці варіанти маніфесту, варіанти -налаштування, отримані з дескрипторів, і метадані каталогу встановлення без -завантаження середовища виконання провайдера. +Списки налаштування провайдерів використовують ці варіанти з маніфесту, варіанти налаштування, похідні від дескрипторів, і метадані каталогу встановлення без завантаження середовища виконання провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід диспетчеризувати. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовують потоки онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих помічником. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору помічника, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього замінного варіанта. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типове значення — `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, на який слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із засобів вибору асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей варіант заміни. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, використовується значення `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє іменем команди середовища виконання, яке користувачі можуть -помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. +Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. ```json { @@ -218,34 +202,22 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | -| `name` | Так | `string` | Ім’я команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як chat slash command, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для CLI-операцій, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane -мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли Plugin може недорого оголосити, які події control-plane мають включати його в план активації/завантаження. -Цей блок — метадані планувальника, а не API життєвого циклу. Він не реєструє -поведінку середовища виконання, не замінює `register(...)` і не обіцяє, що код -Plugin уже виконано. Планувальник активації використовує ці поля, щоб звузити -кандидатні Plugin, перш ніж повертатися до наявних метаданих володіння маніфесту, -таких як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку середовища виконання, не замінює `register(...)` і не гарантує, що код Plugin уже було виконано. Планувальник активації використовує ці поля, щоб звузити перелік кандидатів Plugin перед поверненням до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. -Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок -планувальника, які не можна представити через ці поля володіння. +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна подати через ці поля володіння. +Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища виконання CLI, таких як `claude-cli`, `codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначений лише для вбудованих ідентифікаторів harness агента, які ще не мають поля володіння. -Цей блок — лише метадані. Він не реєструє поведінку середовища виконання і не -замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/Plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тож -відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не -повинна змінювати коректність, поки ще існують застарілі резервні варіанти володіння маніфесту. +Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/Plugin. Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тож відсутність метаданих активації зазвичай лише впливає на продуктивність; це не повинно змінювати коректність, доки ще існують застарілі резервні механізми володіння з маніфесту. ```json { @@ -259,44 +231,38 @@ Plugin уже виконано. Планувальник активації ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються плануванням активації control-plane. За можливості віддавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin у плани активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих harness агента, які мають включати цей Plugin у плани активації/завантаження. Для псевдонімів CLI-бекенду використовуйте верхньорівневий `cliBackends`. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin у плани активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin у плани активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin у плани активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються під час планування активації control-plane. Якщо можливо, надавайте перевагу вужчим полям. | Поточні живі споживачі: -- планування CLI, що запускається командою, повертається до застарілих +- CLI-планування, запущене командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/каналу, що запускається каналом, повертається до застарілого - володіння `channels[]`, коли відсутні явні метадані активації каналу -- планування setup/середовища виконання, що запускається провайдером, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, коли відсутні явні - метадані активації провайдера +- планування запуску agent-runtime використовує `activation.onAgentHarnesses` для + вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI +- планування setup/каналу, запущене каналом, повертається до застарілого володіння `channels[]`, + якщо явні метадані активації каналу відсутні +- планування setup/середовища виконання, запущене провайдером, повертається до застарілого + володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та резервне -володіння маніфесту. Наприклад, `activation-command-hint` означає, що -збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені -для діагностики хоста та тестів; авторам Plugin слід і далі оголошувати метадані, -які найкраще описують володіння. +Діагностика планувальника може відрізняти явні підказки активації від резервного володіння з маніфесту. Наприклад, `activation-command-hint` означає, що спрацював збіг `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста й тестів; авторам Plugin слід і далі оголошувати метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під -спільний корінь `openclaw qa`. Зберігайте ці метадані дешевими та статичними; фактичною -реєстрацією CLI все одно володіє середовище виконання Plugin через полегшену -поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або більше transport runner під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI і далі володіє середовище виконання Plugin через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Запустити live QA lane Matrix на основі Docker проти одноразового homeserver" + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } @@ -305,12 +271,11 @@ Plugin уже виконано. Планувальник активації ви | Поле | Обов’язкове | Тип | Що воно означає | | ------------- | ----------- | -------- | ------------------------------------------------------------------------- | | `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub command. | +| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, -якими володіє Plugin, до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні дешеві метадані, що належать Plugin, до завантаження середовища виконання. ```json { @@ -329,60 +294,36 @@ Plugin уже виконано. Планувальник активації ви } ``` -Верхньорівневий `cliBackends` залишається чинним і надалі описує backend CLI inference. -`setup.cliBackends` — це специфічна для setup поверхня дескрипторів для -потоків control-plane/setup, які мають залишатися лише метаданими. +Верхньорівневий `cliBackends` залишається чинним і надалі описує CLI-бекенди інференсу. `setup.cliBackends` — це поверхня дескриптора, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо присутні, `setup.providers` і `setup.cliBackends` є бажаною -поверхнею пошуку setup за принципом descriptor-first для виявлення setup. Якщо дескриптор -лише звужує кандидатний Plugin і setup усе ще потребує багатших hook setup-часу середовища виконання, -задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +Якщо вказано, `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку descriptor-first для виявлення setup. Якщо дескриптор лише звужує кандидатний Plugin, а setup усе ще потребує багатших хуків середовища виконання на етапі setup, задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків -автентифікації провайдера та змінних середовища. `providerAuthEnvVars` лишається підтримуваним через -адаптер сумісності протягом вікна депрекейту, але невбудовані Plugin, які все ще його використовують, -отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для -setup/status у `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до узагальнених пошуків автентифікації провайдера та змінних середовища. `providerAuthEnvVars` і далі підтримується через адаптер сумісності протягом перехідного періоду відмови, але невбудовані Plugins, які досі його використовують, отримують діагностику маніфесту. Нові Plugins мають розміщувати метадані змінних середовища для setup/статусу в `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, -коли запис setup недоступний або коли `setup.requiresRuntime: false` -оголошує середовище виконання setup непотрібним. Явні записи `providerAuthChoices` залишаються -бажаними для користувацьких міток, прапорців CLI, області онбордингу та метаданих помічника. +OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` вказує, що середовище виконання setup не потрібне. Явні записи `providerAuthChoices` і далі мають перевагу для користувацьких міток, прапорців CLI, області онбордингу та метаданих асистента. -Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори -і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -Plugin лише з дескрипторами все ж постачає одну з цих точок входу середовища виконання setup, -OpenClaw повідомляє додаткову діагностику й продовжує її ігнорувати. Якщо -`requiresRuntime` пропущено, зберігається застаріла резервна поведінка, тож наявні Plugin, які додали -дескриптори без цього прапорця, не ламаються. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на основі дескриптора і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо Plugin, що має працювати лише через дескриптор, усе ж постачає один із цих записів середовища виконання setup, OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущене `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugins, які додали дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, -нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають лишатися -унікальними серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою -замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед усіх виявлених Plugins. Неоднозначне володіння завершується безпечною відмовою замість вибору переможця за порядком виявлення. -Коли середовище виконання setup все ж виконується, діагностика реєстру setup повідомляє -про розходження дескрипторів, якщо `setup-api` реєструє провайдера або backend CLI, -які не оголошені в дескрипторах маніфесту, або якщо дескриптор не має відповідної -реєстрації в середовищі виконання. Ці діагностики є додатковими й не відхиляють застарілі Plugin. +Коли середовище виконання setup все ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо `setup-api` реєструє провайдера або CLI-бекенд, який не оголошено в дескрипторах маніфесту, або якщо дескриптор не має відповідної реєстрації середовища виконання. Ці діагностики є додатковими і не відхиляють застарілі Plugins. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ----------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, що надається під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор провайдера, доступний під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | | `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. | -| `envVars` | Ні | `string[]` | Змінні середовища, які універсальні поверхні setup/status можуть перевіряти до завантаження середовища виконання Plugin. | +| `envVars` | Ні | `string[]` | Змінні середовища, які узагальнені поверхні setup/статусу можуть перевіряти до завантаження середовища виконання Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдера, які надаються під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup за принципом descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдера, доступні під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів на етапі setup, які використовуються для descriptor-first пошуку setup. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи setup усе ще потребує виконання `setup-api` після пошуку за дескриптором. | ## Довідник `uiHints` @@ -392,8 +333,8 @@ OpenClaw повідомляє додаткову діагностику й пр { "uiHints": { "apiKey": { - "label": "Ключ API", - "help": "Використовується для запитів OpenRouter", + "label": "API key", + "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -401,21 +342,20 @@ OpenClaw повідомляє додаткову діагностику й пр } ``` -Кожна підказка поля може містити: +Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | ---------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -читати без імпорту середовища виконання Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може зчитувати без імпорту середовища виконання Plugin. ```json { @@ -436,48 +376,33 @@ OpenClaw повідомляє додаткову діагностику й пр } ``` -Кожен список необов’язковий: +Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | -------------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори extension factory app-server Codex, наразі `codex-app-server`. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ------------------------------------------------------------------------ | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень Codex app-server, наразі `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | Ідентифікатори середовища виконання, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий hook зовнішнього профілю автентифікації належить цьому Plugin. | -| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрибування в реальному часі, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів векторизації пам’яті, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | -| `tools` | `string[]` | Імена інструментів агента, якими володіє цей Plugin, для перевірок вбудованих контрактів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чиї зовнішні хуки профілів автентифікації належать цьому Plugin. | +| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів embedding для пам’яті, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для перевірок контрактів вбудованих компонентів. | -`contracts.embeddedExtensionFactories` збережено для вбудованих extension factory -лише для app-server Codex. Вбудовані перетворення результатів інструментів мають -оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть -реєструвати middleware результатів інструментів, оскільки цей seam може переписувати -високодовірений вивід інструментів до того, як модель його побачить. +`contracts.embeddedExtensionFactories` збережено для фабрик розширень лише для вбудованого Codex app-server. Вбудовані перетворення результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugins не можуть реєструвати middleware результатів інструментів, оскільки цей seam може переписувати результати інструментів із високим рівнем довіри до того, як модель їх побачить. -Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють -через застарілий резервний механізм сумісності, але він повільніший і буде -видалений після завершення вікна міграції. +Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugins без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але цей механізм повільніший і буде видалений після завершення перехідного періоду. -Вбудовані провайдери векторизації пам’яті мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, зокрема -для вбудованих адаптерів, таких як `local`. Автономні шляхи CLI використовують цей контракт -маніфесту, щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway -зареєструє провайдерів. +Вбудовані провайдери embedding для пам’яті мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має -типові моделі, пріоритет резервної автоавтентифікації або нативну підтримку документів, які -потрібні універсальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в -`contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має стандартні моделі, пріоритет резервної автоавтентифікації або рідну підтримку документів, які потрібні узагальненим допоміжним компонентам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json { @@ -502,41 +427,27 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові значення відповідності можливість-модель, що використовуються, коли в конфігурації не задано модель. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Стандартні значення «можливість → модель», які використовуються, коли конфігурація не вказує модель. | | `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує провайдер. | +| `nativeDocumentInputs` | `"pdf"[]` | Рідні формати введення документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до -завантаження середовища виконання. Виявлення setup/status каналу в режимі лише для читання може -безпосередньо використовувати ці метадані для налаштованих зовнішніх каналів, коли запис setup недоступний -або коли `setup.requiresRuntime: false` оголошує середовище виконання setup непотрібним. +Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до завантаження середовища виконання. Виявлення setup/статусу каналу лише для читання може безпосередньо використовувати ці метадані для налаштованих зовнішніх каналів, коли запис setup недоступний або коли `setup.requiresRuntime: false` вказує, що середовище виконання setup не потрібне. -`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ конфігурації користувача. -Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. -OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим -каналом, до виконання коду середовища виконання Plugin. +`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ конфігурації користувача. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим каналом, до виконання коду середовища виконання Plugin. -Для Plugin каналу `configSchema` і `channelConfigs` описують різні -шляхи: +Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: - `configSchema` валідує `plugins.entries..config` - `channelConfigs..schema` валідує `channels.` -Невбудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але -поверхні cold-path для схеми конфігурації, setup і Control UI не можуть знати форму -параметрів, якими володіє канал, доки не виконається середовище виконання Plugin. +Невбудовані Plugins, які оголошують `channels[]`, також мають оголошувати відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але поверхні схеми конфігурації холодного шляху, setup і Control UI не знатимуть форму параметрів, що належать каналу, доки не виконається середовище виконання Plugin. -`channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок -конфігурації команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть -публікувати ті самі типові значення через `package.json#openclaw.channel.commands` разом зі -своїми іншими метаданими каталогу каналу, що належать пакету. +`channelConfigs..commands.nativeCommandsAutoEnabled` і `nativeSkillsAutoEnabled` можуть оголошувати статичні стандартні значення `auto` для перевірок конфігурації команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати ті самі стандартні значення через `package.json#openclaw.channel.commands` поряд з іншими метаданими каталогу каналів, що належать пакету. ```json { @@ -551,12 +462,12 @@ OpenClaw читає метадані маніфесту, щоб визначит }, "uiHints": { "homeserverUrl": { - "label": "URL homeserver", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Підключення до Matrix homeserver", + "description": "Matrix homeserver connection", "commands": { "nativeCommandsAutoEnabled": true, "nativeSkillsAutoEnabled": true @@ -569,21 +480,18 @@ OpenClaw читає метадані маніфесту, щоб визначит Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та inspect, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь inspect і каталогу. | -| `commands` | `object` | Статичні автоматичні типові значення нативних команд і нативних Skills для перевірок конфігурації до запуску середовища виконання. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugin, які цей канал має випереджати на поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та перегляду, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | +| `commands` | `object` | Статичні стандартні значення native command і native skill для перевірок конфігурації до запуску середовища виконання. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugins, які цей канал має перевершувати в поверхнях вибору. | ### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш Plugin є пріоритетним власником для ідентифікатора каналу, який -також може надавати інший Plugin. Типові випадки — перейменований ідентифікатор Plugin, -окремий Plugin, який замінює вбудований Plugin, або підтримуваний fork, що -зберігає той самий ідентифікатор каналу для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який також може надавати інший Plugin. Типові випадки — це перейменований ідентифікатор Plugin, окремий Plugin, який замінює вбудований Plugin, або підтримуваний fork, що зберігає той самий ідентифікатор каналу для сумісності конфігурації. ```json { @@ -604,22 +512,13 @@ OpenClaw читає метадані маніфесту, щоб визначит } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та -ідентифікатор пріоритетного Plugin. Якщо Plugin нижчого пріоритету було вибрано лише тому, -що він вбудований або ввімкнений типово, OpenClaw вимикає його в ефективній -конфігурації середовища виконання, щоб один Plugin володів каналом і його інструментами. Явний -вибір користувача все одно має пріоритет: якщо користувач явно вмикає обидва Plugin, OpenClaw -зберігає цей вибір і повідомляє про діагностику дубльованих каналів/інструментів замість -тихої зміни запитаного набору Plugin. +Коли налаштовано `channels.chat`, OpenClaw враховує як ідентифікатор каналу, так і бажаний ідентифікатор Plugin. Якщо Plugin із нижчим пріоритетом було вибрано лише тому, що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній конфігурації середовища виконання, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugins, OpenClaw зберігає цей вибір і повідомляє про діагностику дубльованого каналу/інструментів замість того, щоб тихо змінювати запитаний набір Plugins. -Тримайте `preferOver` обмеженим ідентифікаторами Plugin, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. +Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той самий канал. Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з -коротких ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження -середовища виконання Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера зі скорочених ідентифікаторів моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання Plugin. ```json { @@ -632,26 +531,21 @@ OpenClaw читає метадані маніфесту, щоб визначит OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` власника -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований - Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не задасть провайдера +- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника +- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ---------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, які перевіряються через `startsWith` для коротких ідентифікаторів моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються з короткими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження середовища виконання Plugin. Це джерело, яким володіє маніфест, для фіксованих рядків -каталогу, псевдонімів провайдера, правил приглушення та режиму виявлення. Оновлення в середовищі виконання -все ще належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли -середовище виконання потрібне. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до завантаження середовища виконання Plugin. Це джерело фіксованих рядків каталогу, псевдонімів провайдера, правил приглушення та режиму виявлення, що належить маніфесту. Оновлення в середовищі виконання, як і раніше, належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли середовище виконання є обов’язковим. ```json { @@ -690,7 +584,7 @@ OpenClaw застосовує такий пріоритет: { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", - "reason": "недоступно в Azure OpenAI Responses" + "reason": "not available on Azure OpenAI Responses" } ], "discovery": { @@ -702,165 +596,116 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають з’являтися у верхньорівневому `providers`. | -| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися до провайдера-власника для планування каталогу або приглушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи може каталог провайдера читатися з метаданих маніфесту, оновлюватися в кеш або потребує середовища виконання. | +| Поле | Тип | Що воно означає | +| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають бути вказані у верхньорівневому `providers`. | +| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися в провайдера-власника для каталогу або планування приглушення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | +| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати його в кеш чи для нього потрібне середовище виконання. | Поля провайдера: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | ------------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | +| Поле | Тип | Що воно означає | +| --------- | ------------------------ | --------------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язковий стандартний `baseUrl` для моделей у цьому каталозі провайдера. | +| `api` | `ModelApi` | Необов’язковий стандартний адаптер API для моделей у цьому каталозі провайдера. | | `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що воно означає | -| --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Нативне вікно контексту провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту в середовищі виконання, якщо воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| Поле | Тип | Що воно означає | +| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Рідне вікно контексту провайдера. | +| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту середовища виконання, якщо воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | | `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | -| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приглушуйте лише тоді, коли рядок узагалі не повинен з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується разом зі статусом не-доступності. | -| `replaces` | `string[]` | Старі локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | +| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Використовуйте приглушення лише тоді, коли рядок взагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується разом зі статусом, відмінним від доступного. | +| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору й фільтрами. | -Не поміщайте в `modelCatalog` дані лише для середовища виконання. Якщо провайдеру потрібні стан -облікового запису, запит API або виявлення локального процесу, щоб знати повний набір моделей, -оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. +Не додавайте до `modelCatalog` дані, доступні лише в середовищі виконання. Якщо провайдеру потрібен стан облікового запису, API-запит або виявлення локального процесу, щоб визначити повний набір моделей, оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. ### Індекс провайдерів OpenClaw -Індекс провайдерів OpenClaw — це preview-метадані OpenClaw для провайдерів, -Plugin яких можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. -Маніфести Plugin залишаються джерелом істини для встановлених Plugin. Індекс провайдерів — це -внутрішній резервний контракт, який використовуватимуть майбутні поверхні -встановлюваних провайдерів і засобів вибору моделей до встановлення, коли Plugin провайдера не встановлено. +Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, Plugins яких можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugins. Індекс провайдерів — це внутрішній резервний контракт, який у майбутньому використовуватимуть поверхні встановлюваних провайдерів і засобів вибору моделей до встановлення, коли Plugin провайдера ще не встановлено. Порядок пріоритету джерел каталогу: 1. Конфігурація користувача. 2. `modelCatalog` маніфесту встановленого Plugin. 3. Кеш каталогу моделей після явного оновлення. -4. Preview-рядки індексу провайдерів OpenClaw. +4. Preview-рядки Індексу провайдерів OpenClaw. -Індекс провайдерів не повинен містити секрети, стан увімкнення, hooks середовища виконання або -живі специфічні для облікового запису дані моделей. Його preview-каталоги використовують ту саму -форму рядків провайдера `modelCatalog`, що й маніфести Plugin, але мають обмежуватися -стабільними метаданими відображення, якщо лише поля адаптера середовища виконання, такі як `api`, -`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом -встановленого Plugin. Провайдери з живим виявленням `/models` мають записувати оновлені рядки через -явний шлях кешу каталогу моделей замість того, щоб під час звичайного відображення списку або онбордингу викликати API провайдера. +Індекс провайдерів не повинен містити секрети, стан увімкнення, хуки середовища виконання або живі дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають обмежуватися стабільними метаданими відображення, якщо тільки поля адаптера середовища виконання, такі як `api`, `baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом встановленого Plugin. Провайдери з живим виявленням через `/models` мають записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, щоб під час звичайного відображення списків або онбордингу викликати API провайдера. -Записи індексу провайдерів також можуть містити метадані встановлюваних Plugin для провайдерів, -Plugin яких винесено з core або які інакше ще не встановлені. Ці -метадані повторюють шаблон каталогу каналів: назви пакета, специфікація npm install, -очікувана цілісність та дешеві мітки варіантів автентифікації достатні, щоб показати -встановлюваний варіант setup. Щойно Plugin встановлено, його маніфест перемагає, а запис -індексу провайдерів для цього провайдера ігнорується. +Записи Індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, Plugin яких винесено з ядра або які з інших причин ще не встановлено. Ці метадані повторюють шаблон каталогу каналів: назви пакета, специфікації встановлення npm, очікувана цілісність і недорогі мітки варіантів автентифікації достатні, щоб показати варіант налаштування встановлюваного компонента. Після встановлення Plugin його маніфест отримує пріоритет, а запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі верхньорівневі ключі можливостей є застарілими. Використовуйте `openclaw doctor --fix`, щоб -перемістити `speechProviders`, `realtimeTranscriptionProviders`, -`realtimeVoiceProviders`, `mediaUnderstandingProviders`, -`imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не розглядає ці верхньорівневі поля як -володіння можливостями. +Застарілі верхньорівневі ключі можливостей більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перенести `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці верхньорівневі поля як володіння можливостями. -## Маніфест проти package.json +## Маніфест порівняно з `package.json` -Ці два файли виконують різні ролі: +Ці два файли виконують різні завдання: -| Файл | Використовуйте для | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, контролю встановлення, setup або метаданих каталогу | +| Файл | Використовуйте для | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом: +Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки npm install, помістіть це в `package.json` +- якщо OpenClaw повинен знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` -### Поля package.json, які впливають на виявлення +### Поля `package.json`, які впливають на виявлення -Частина метаданих Plugin до запуску середовища виконання навмисно зберігається в `package.json` у блоці -`openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані Plugin, потрібні до запуску середовища виконання, навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує нативні точки входу Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу зібраного JavaScript середовища виконання для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише для читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Полегшені метадані каталогу каналу, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.commands` | Статичні метадані авто-типових значень нативних команд і нативних Skills, що використовуються поверхнями конфігурації, аудиту та списку команд до завантаження середовища виконання каналу. | -| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на запитання "чи вже існує setup лише через env?" без завантаження повного середовища виконання каналу. | -| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання "чи вже десь виконано вхід?" без завантаження повного середовища виконання каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих Plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із semver-нижньою межею на кшталт `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує точки входу рідного Plugin. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу зібраного JavaScript середовища виконання для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Полегшена точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup для зібраного JavaScript у встановлених пакетах. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Недорогі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.commands` | Статичні метадані стандартних значень native command і native skill, які використовуються поверхнями конфігурації, аудиту та списку команд до завантаження середовища виконання каналу. | +| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного середовища виконання каналу. | +| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на питання «чи вже десь виконано вхід?» без завантаження повного середовища виконання каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих Plugins. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, як-от `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація некоректна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в -онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. -`openclaw.install.minHostVersion` примусово застосовується під час встановлення та -завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але чинні значення -пропускають Plugin на старіших хостах. +`openclaw.install.minHostVersion` примусово застосовується під час встановлення та завантаження реєстру маніфестів. Некоректні значення відхиляються; новіші, але коректні значення пропускають Plugin на старіших хостах. -Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися -безпечною відмовою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. -Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, -включно з простими назвами пакетів і dist-tag. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю -назви пакета та недійсні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає чинного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення примусово його застосовують; коли його пропущено, розв’язання реєстру -записується без закріплення цілісності. +Точне закріплення версії npm уже зберігається в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися безпечною відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. +Інтерактивний онбординг і далі пропонує довірені специфікації npm із реєстру, включно з простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та джерела з некоректним стандартним вибором. Вона також попереджає, коли `expectedIntegrity` задано, але немає коректного джерела npm, яке можна ним закріпити. +Коли `expectedIntegrity` задано, потоки встановлення/оновлення примусово його застосовують; коли його пропущено, розв’язання через реєстр фіксується без закріплення цілісності. -Plugin каналів мають надавати `openclaw.setupEntry`, коли статус, список каналів -або сканування SecretRef потребують визначення налаштованих облікових записів без завантаження повного -середовища виконання. Точка входу setup має надавати метадані каналу разом із безпечними для setup -адаптерами конфігурації, статусу та секретів; мережевих клієнтів, слухачів Gateway і -транспортні середовища виконання тримайте в основній точці входу extension. +Plugins каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів або сканування SecretRef потрібно визначати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу setup має надавати метадані каналу разом із безпечними для setup адаптерами конфігурації, статусу й секретів; мережеві клієнти, прослуховувачі Gateway і transport runtime слід залишати в основній точці входу розширення. -Поля точок входу середовища виконання не скасовують перевірки меж пакета для полів -точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити -придатним до завантаження шлях `openclaw.extensions`, що виходить за межі. +Поля точки входу середовища виконання не перевизначають перевірки меж пакета для полів точки входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета. -`openclaw.install.allowInvalidConfigRecovery` є навмисно вузьким. Воно -не робить довільні зламані конфігурації придатними для встановлення. Наразі воно лише дозволяє потокам встановлення -відновлюватися після конкретних застарілих збоїв оновлення вбудованих Plugin, як-от -відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого -вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно не робить довільно зламані конфігурації придатними до встановлення. На сьогодні воно лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, наприклад відсутнього шляху до вбудованого Plugin або застарілого запису `channels.` для того самого вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля -перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: ```json { @@ -876,13 +721,9 @@ Plugin каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевого yes/no -зонда автентифікації до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою -функцією, що читає лише збережений стан; не маршрутизуйте його через повний barrel -середовища виконання каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel середовища виконання каналу. -`openclaw.channel.configuredState` використовує ту саму форму для дешевих перевірок -налаштованого стану лише через env: +`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок налаштованого стану лише через env: ```json { @@ -898,68 +739,66 @@ Plugin каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли канал може визначити налаштований стан із env або інших невеликих -невиконуваних вхідних даних. Якщо перевірка потребує повного розв’язання конфігурації або реального -середовища виконання каналу, залишайте цю логіку в hook `config.hasConfiguredState` Plugin. +Використовуйте це, коли канал може визначити налаштований стан на основі env або інших мінімальних нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або реального середовища виконання каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. ## Пріоритет виявлення (дубльовані ідентифікатори Plugin) -OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, шляхи, явно вибрані конфігурацією). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати нижчого пріоритету відкидаються замість завантаження поруч. +OpenClaw виявляє Plugins із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені Plugins мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість одночасного завантаження. -Пріоритет, від найвищого до найнижчого: +Пріоритет від найвищого до найнижчого: -1. **Вибрані конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудовані** — Plugin, що постачаються з OpenClaw -3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw -4. **Workspace** — Plugin, виявлені відносно поточного workspace +1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — Plugins, що постачаються разом з OpenClaw +3. **Глобальне встановлення** — Plugins, встановлені до глобального кореня Plugin OpenClaw +4. **Workspace** — Plugins, виявлені відносно поточного workspace Наслідки: -- Fork або застаріла копія вбудованого Plugin у workspace не затьмарить вбудовану збірку. +- Fork або застаріла копія вбудованого Plugin у workspace не зможе затінити вбудовану збірку. - Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. - Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema - **Кожен Plugin повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми валідуються під час читання/запису конфігурації, а не в середовищі виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошено - маніфестом Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено + в маніфесті Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**. + мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. - Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але сам Plugin **вимкнено**, конфігурація зберігається і - у Doctor + журналах відображається **попередження**. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і + в Doctor + журналах відображається **попередження**. -Див. [Довідник із конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. +Повну схему `plugins.*` див. у [Довіднику конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для нативних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Середовище виконання все одно завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. -- Нативні маніфести розбираються як JSON5, тому коментарі, завершальні коми й ключі без лапок дозволені, якщо кінцеве значення все одно є об’єктом. -- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких верхньорівневих ключів. -- `channels`, `providers`, `cliBackends` і `skills` можна пропускати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри Plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Щодо метаданих майстра середовища виконання, які потребують коду провайдера, див. [Hooks середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для рідних Plugins OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання і далі завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. +- Рідні маніфести розбираються за допомогою JSON5, тож коментарі, кінцеві коми й ключі без лапок дозволені, якщо підсумкове значення все ще є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (стандартне значення `legacy`). +- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Метадані wizard середовища виконання, які потребують коду провайдера, див. у [Хуки середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з Plugin. + + Початок роботи з Plugins. Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin і імпорти підшляхів. + Довідник SDK Plugin та імпорти підшляхів. diff --git a/docs/uk/plugins/sdk-setup.md b/docs/uk/plugins/sdk-setup.md index f513459d1..84fd748dc 100644 --- a/docs/uk/plugins/sdk-setup.md +++ b/docs/uk/plugins/sdk-setup.md @@ -3,113 +3,119 @@ read_when: - Ви додаєте майстер налаштування до Plugin - Вам потрібно зрозуміти різницю між `setup-entry.ts` і `index.ts` - Ви визначаєте схеми конфігурації Plugin або метадані `openclaw` у `package.json` -sidebarTitle: Setup and Config -summary: Майстри налаштування, `setup-entry.ts`, схеми конфігурації та метадані `package.json` -title: Налаштування Plugin і конфігурація +sidebarTitle: Setup and config +summary: майстри налаштування, `setup-entry.ts`, схеми конфігурації та метадані `package.json` +title: налаштування Plugin і конфігурація x-i18n: - generated_at: "2026-04-25T21:54:32Z" + generated_at: "2026-04-26T08:15:41Z" model: gpt-5.4 provider: openai - source_hash: 66c44a08db7c83ec981c92fadea54482e5d85af3cc3c4621916e3e0b1223d9a6 + source_hash: d5ac08bf43af0a15e4ed797eb3a732d15f24f67304efbac7d74e6f24ffe67af9 source_path: plugins/sdk-setup.md workflow: 15 --- -Довідник щодо пакування Plugin (метадані `package.json`), маніфестів -(`openclaw.plugin.json`), записів налаштування та схем конфігурації. +Довідка щодо пакування Plugin (метадані `package.json`), маніфестів (`openclaw.plugin.json`), точок входу налаштування та схем конфігурації. - **Шукаєте покрокове пояснення?** У practical-гайдах розглядається пакування в контексті: - [Channel Plugins](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) та - [Provider Plugins](/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). -## Метадані пакунка +## Метадані пакета -Ваш `package.json` має містити поле `openclaw`, яке повідомляє системі Plugin, що -надає ваш Plugin: +У вашому `package.json` має бути поле `openclaw`, яке повідомляє системі Plugin, що надає ваш Plugin: -**Channel Plugin:** - -```json -{ - "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." + + + ```json + { + "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." + } + } } - } -} -``` - -**Provider Plugin / базовий шаблон публікації в ClawHub:** - -```json openclaw-clawhub-package.json -{ - "name": "@myorg/openclaw-my-plugin", - "version": "1.0.0", - "type": "module", - "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" + ``` + + + ```json openclaw-clawhub-package.json + { + "name": "@myorg/openclaw-my-plugin", + "version": "1.0.0", + "type": "module", + "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" + } + } } - } -} -``` + ``` + + -Якщо ви публікуєте Plugin зовні в ClawHub, поля `compat` і `build` -є обов’язковими. Канонічні фрагменти для публікації розміщені в -`docs/snippets/plugin-publish/`. + +Якщо ви публікуєте Plugin зовні у ClawHub, поля `compat` і `build` є обов’язковими. Канонічні фрагменти для публікації містяться в `docs/snippets/plugin-publish/`. + ### Поля `openclaw` -| Поле | Тип | Опис | -| ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------- | -| `extensions` | `string[]` | Файли точок входу (відносно кореня пакунка) | -| `setupEntry` | `string` | Легка точка входу лише для налаштування (необов’язково) | -| `channel` | `object` | Метадані каталогу Channel для налаштування, вибору, quickstart і поверхонь стану | -| `providers` | `string[]` | Ідентифікатори Provider, зареєстровані цим Plugin | -| `install` | `object` | Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` | -| `startup` | `object` | Прапори поведінки під час запуску | + + Файли точок входу (відносно кореня пакета). + + + Легка точка входу лише для налаштування (необов’язково). + + + Метадані каталогу каналів для налаштування, вибору, швидкого старту та поверхонь стану. + + + Ідентифікатори провайдерів, зареєстрованих цим Plugin. + + + Підказки для встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery`. + + + Прапорці поведінки запуску. + ### `openclaw.channel` -`openclaw.channel` — це недорогі метадані пакунка для виявлення Channel і поверхонь -налаштування до завантаження runtime. +`openclaw.channel` — це недорогі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження середовища виконання. -| Поле | Тип | Що це означає | -| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | -| `id` | `string` | Канонічний ідентифікатор Channel. | -| `label` | `string` | Основна мітка Channel. | -| `selectionLabel` | `string` | Мітка для picker/налаштування, якщо вона має відрізнятися від `label`. | -| `detailLabel` | `string` | Додаткова детальна мітка для багатших каталогів Channel і поверхонь стану. | -| `docsPath` | `string` | Шлях документації для посилань у налаштуванні та виборі. | -| `docsLabel` | `string` | Мітка-override для посилань на документацію, якщо вона має відрізнятися від id Channel. | -| `blurb` | `string` | Короткий опис для онбордингу/каталогу. | -| `order` | `number` | Порядок сортування в каталогах Channel. | -| `aliases` | `string[]` | Додаткові аліаси пошуку для вибору Channel. | -| `preferOver` | `string[]` | Ідентифікатори Plugin/Channel нижчого пріоритету, які цей Channel має випереджати. | -| `systemImage` | `string` | Необов’язкова назва іконки/system-image для каталогів UI Channel. | -| `selectionDocsPrefix` | `string` | Текст-префікс перед посиланнями на документацію в поверхнях вибору. | -| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість іменованого посилання в тексті вибору. | -| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються в тексті вибору. | -| `markdownCapable` | `boolean` | Позначає Channel як сумісний із markdown для рішень щодо вихідного форматування. | -| `exposure` | `object` | Керування видимістю Channel для налаштування, списків налаштованого та поверхонь документації. | -| `quickstartAllowFrom` | `boolean` | Додає цей Channel до стандартного quickstart-потоку налаштування `allowFrom`. | -| `forceAccountBinding` | `boolean` | Вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Надавати перевагу пошуку сесії під час визначення announce targets для цього Channel. | +| Поле | Тип | Що це означає | +| -------------------------------------- | ---------- | --------------------------------------------------------------------------- | +| `id` | `string` | Канонічний ідентифікатор каналу. | +| `label` | `string` | Основна мітка каналу. | +| `selectionLabel` | `string` | Мітка у виборі/налаштуванні, якщо вона має відрізнятися від `label`. | +| `detailLabel` | `string` | Вторинна мітка для багатших каталогів каналів і поверхонь стану. | +| `docsPath` | `string` | Шлях до документації для посилань у налаштуванні та виборі. | +| `docsLabel` | `string` | Мітка-перевизначення для посилань на документацію, якщо вона має відрізнятися від ідентифікатора каналу. | +| `blurb` | `string` | Короткий опис для онбордингу/каталогу. | +| `order` | `number` | Порядок сортування в каталогах каналів. | +| `aliases` | `string[]` | Додаткові псевдоніми для пошуку під час вибору каналу. | +| `preferOver` | `string[]` | Ідентифікатори Plugin/каналів з нижчим пріоритетом, які цей канал має випереджати. | +| `systemImage` | `string` | Необов’язкова назва іконки/системного зображення для UI-каталогів каналів. | +| `selectionDocsPrefix` | `string` | Текст-префікс перед посиланнями на документацію в поверхнях вибору. | +| `selectionDocsOmitLabel` | `boolean` | Показувати шлях до документації безпосередньо замість іменованого посилання в тексті вибору. | +| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються в тексті вибору. | +| `markdownCapable` | `boolean` | Позначає канал як сумісний з markdown для рішень щодо вихідного форматування. | +| `exposure` | `object` | Керування видимістю каналу для налаштування, списків налаштованого та поверхонь документації. | +| `quickstartAllowFrom` | `boolean` | Додає цей канал до стандартного потоку налаштування швидкого старту `allowFrom`. | +| `forceAccountBinding` | `boolean` | Вимагає явного прив’язування облікового запису навіть тоді, коли існує лише один обліковий запис. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Віддавати перевагу пошуку сесії під час визначення цілей оголошень для цього каналу. | Приклад: @@ -143,65 +149,58 @@ x-i18n: `exposure` підтримує: -- `configured`: включати Channel у поверхні списків налаштованого/стану -- `setup`: включати Channel в інтерактивні picker-и налаштування/конфігурації -- `docs`: позначати Channel як публічний у поверхнях документації/навігації +- `configured`: включати канал до поверхонь списку налаштованих каналів/стану +- `setup`: включати канал до інтерактивних засобів вибору налаштування/конфігурації +- `docs`: позначати канал як публічний у поверхнях документації/навігації -`showConfigured` і `showInSetup` усе ще підтримуються як застарілі аліаси. Надавайте -перевагу `exposure`. + +`showConfigured` і `showInSetup` залишаються підтримуваними як застарілі псевдоніми. Рекомендовано використовувати `exposure`. + ### `openclaw.install` -`openclaw.install` — це метадані пакунка, а не метадані маніфесту. +`openclaw.install` — це метадані пакета, а не метадані маніфесту. -| Поле | Тип | Що це означає | -| ---------------------------- | -------------------- | --------------------------------------------------------------------------------- | -| `npmSpec` | `string` | Канонічний npm spec для потоків встановлення/оновлення. | -| `localPath` | `string` | Локальний шлях для розробки або вбудованого встановлення. | -| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | -| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у форматі `>=x.y.z`. | -| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для фіксованих встановлень. | -| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованого Plugin відновлюватися після окремих збоїв через застарілу конфігурацію. | +| Поле | Тип | Що це означає | +| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- | +| `npmSpec` | `string` | Канонічна специфікація npm для потоків встановлення/оновлення. | +| `localPath` | `string` | Локальний шлях встановлення для розробки або вбудованого використання. | +| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | +| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у форматі `>=x.y.z`. | +| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для зафіксованих встановлень. | +| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих Plugin відновлюватися після певних збоїв через застарілу конфігурацію. | -Інтерактивний онбординг також використовує `openclaw.install` для поверхонь -встановлення на вимогу. Якщо ваш Plugin надає варіанти автентифікації Provider або метадані -налаштування/каталогу Channel до завантаження runtime, онбординг може показати цей вибір, -запитати про npm чи локальне встановлення, встановити або ввімкнути Plugin, а потім -продовжити вибраний потік. Варіанти онбордингу через npm потребують довірених метаданих -каталогу з `npmSpec` реєстру; точні версії та `expectedIntegrity` — необов’язкові -фіксатори. Якщо присутній `expectedIntegrity`, потоки встановлення/оновлення -застосовують його перевірку. Зберігайте метадані “що показувати” в `openclaw.plugin.json`, -а метадані “як це встановлювати” — у `package.json`. + + + Інтерактивний онбординг також використовує `openclaw.install` для поверхонь встановлення на вимогу. Якщо ваш Plugin показує варіанти автентифікації провайдера або метадані налаштування/каталогу каналів до завантаження середовища виконання, онбординг може показати цей вибір, запропонувати npm або локальне встановлення, встановити або увімкнути Plugin, а потім продовжити вибраний потік. Варіанти онбордингу через npm потребують довірених метаданих каталогу з реєстровим `npmSpec`; точні версії та `expectedIntegrity` є необов’язковими фіксаціями. Якщо `expectedIntegrity` задано, потоки встановлення/оновлення застосовують його перевірку. Зберігайте метадані «що показувати» в `openclaw.plugin.json`, а метадані «як це встановити» — у `package.json`. + + + Якщо встановлено `minHostVersion`, і встановлення, і завантаження через реєстр маніфестів застосовують це обмеження. Старіші хости пропускають Plugin; некоректні рядки версій відхиляються. + + + Для зафіксованих npm-встановлень зберігайте точну версію в `npmSpec` і додавайте очікувану цілісність артефакту: -Якщо задано `minHostVersion`, і встановлення, і завантаження реєстру маніфестів -застосовують цю перевірку. Старіші хости пропускають Plugin; некоректні рядки версій -відхиляються. - -Для фіксованих встановлень npm зберігайте точну версію в `npmSpec` і додавайте -очікувану цілісність артефакту: - -```json -{ - "openclaw": { - "install": { - "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3", - "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY", - "defaultChoice": "npm" + ```json + { + "openclaw": { + "install": { + "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3", + "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY", + "defaultChoice": "npm" + } + } } - } -} -``` + ``` -`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Воно -призначене лише для вузького відновлення вбудованого Plugin, щоб перевстановлення/налаштування -могло виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого Plugin -або застарілий запис `channels.` для цього самого Plugin. Якщо конфігурація зламана з -непов’язаних причин, встановлення все одно безпечно завершується з відмовою й повідомляє -оператору виконати `openclaw doctor --fix`. + + + `allowInvalidConfigRecovery` — це не загальний обхід для зламаних конфігурацій. Він призначений лише для вузького відновлення вбудованих Plugin, щоб перевстановлення/налаштування могли виправити відомі залишки після оновлення, наприклад відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для цього самого Plugin. Якщо конфігурація зламана з не пов’язаних причин, встановлення все одно безпечно завершується відмовою і повідомляє оператору виконати `openclaw doctor --fix`. + + ### Відкладене повне завантаження -Channel Plugins можуть увімкнути відкладене завантаження за допомогою: +Plugin каналів можуть увімкнути відкладене завантаження за допомогою: ```json { @@ -215,26 +214,17 @@ Channel Plugins можуть увімкнути відкладене заван } ``` -Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до -початку прослуховування, навіть для вже налаштованих Channel. Повна точка входу -завантажується після того, як Gateway починає слухати. +Якщо це увімкнено, OpenClaw завантажує лише `setupEntry` на етапі запуску до початку прослуховування, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як Gateway почне прослуховування. - Увімкнюйте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, - що потрібно Gateway до початку прослуховування (реєстрація Channel, HTTP-маршрути, - методи Gateway). Якщо необхідні можливості запуску належать повній точці входу, - залишайте стандартну поведінку. +Увімкнюйте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що Gateway потрібно до початку прослуховування (реєстрація каналу, HTTP-маршрути, методи Gateway). Якщо повна точка входу володіє необхідними можливостями запуску, залишайте стандартну поведінку. -Якщо ваш запис налаштування/повний запис реєструє методи Gateway RPC, зберігайте їх -під префіксом, специфічним для Plugin. Зарезервовані простори імен core admin (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються під керуванням core і завжди -резолвляться до `operator.admin`. +Якщо ваша точка входу налаштування/повна точка входу реєструє методи Gateway RPC, використовуйте для них префікс, специфічний для Plugin. Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності ядра і завжди зіставляються з `operator.admin`. ## Маніфест Plugin -Кожен native Plugin має постачатися з `openclaw.plugin.json` у корені пакунка. -OpenClaw використовує його для валідації конфігурації без виконання коду Plugin. +Кожен нативний Plugin має постачатися з `openclaw.plugin.json` у корені пакета. OpenClaw використовує його для валідації конфігурації без виконання коду Plugin. ```json { @@ -254,7 +244,7 @@ OpenClaw використовує його для валідації конфі } ``` -Для Channel Plugins додайте `kind` і `channels`: +Для Plugin каналів додайте `kind` і `channels`: ```json { @@ -269,7 +259,7 @@ OpenClaw використовує його для валідації конфі } ``` -Навіть Plugins без конфігурації мають постачатися зі схемою. Порожня схема є валідною: +Навіть Plugin без конфігурації мають постачатися зі схемою. Порожня схема є коректною: ```json { @@ -281,25 +271,24 @@ OpenClaw використовує його для валідації конфі } ``` -Див. [Plugin Manifest](/uk/plugins/manifest), щоб переглянути повний довідник схеми. +Повну довідку щодо схеми дивіться в розділі [Маніфест Plugin](/uk/plugins/manifest). ## Публікація в ClawHub -Для пакунків Plugin використовуйте команду ClawHub, специфічну для пакунків: +Для пакетів Plugin використовуйте спеціальну команду ClawHub для пакетів: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Застарілий аліас публікації лише для Skills призначений для Skills. Пакунки Plugin -завжди мають використовувати `clawhub package publish`. + +Застарілий псевдонім публікації лише для Skills призначений для Skills. Пакети Plugin завжди мають використовувати `clawhub package publish`. + ## Точка входу налаштування -Файл `setup-entry.ts` — це легка альтернатива `index.ts`, яку OpenClaw завантажує, -коли потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, -інспекція вимкненого Channel). +Файл `setup-entry.ts` — це легка альтернатива `index.ts`, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, перевірка вимкнених каналів). ```typescript // setup-entry.ts @@ -309,83 +298,63 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -Це дає змогу уникнути завантаження важкого runtime-коду (бібліотеки crypto, реєстрації CLI, -фонові служби) під час потоків налаштування. +Це дає змогу уникнути завантаження важкого коду середовища виконання (криптобібліотек, реєстрацій CLI, фонових сервісів) під час потоків налаштування. -Вбудовані workspace Channel, які зберігають безпечні для налаштування експорти в sidecar-модулях, можуть -використовувати `defineBundledChannelSetupEntry(...)` з -`openclaw/plugin-sdk/channel-entry-contract` замість -`defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий -експорт `runtime`, щоб налаштування runtime під час setup залишалося легким і явним. +Вбудовані канали workspace, які тримають безпечні для налаштування експорти в sidecar-модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість `defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий експорт `runtime`, щоб налаштування зв’язування runtime під час налаштування залишалося легким і явним. -**Коли OpenClaw використовує `setupEntry` замість повної точки входу:** + + + - Канал вимкнено, але йому потрібні поверхні налаштування/онбордингу. + - Канал увімкнено, але не налаштовано. + - Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`). + + + - Об’єкт Plugin каналу (через `defineSetupPluginEntry`). + - Усі HTTP-маршрути, потрібні до того, як Gateway почне прослуховування. + - Усі методи Gateway, потрібні під час запуску. -- Channel вимкнено, але потрібні поверхні налаштування/онбордингу -- Channel увімкнено, але не налаштовано -- Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`) + Ці стартові методи Gateway усе одно мають уникати зарезервованих просторів імен адміністратора ядра, таких як `config.*` або `update.*`. -**Що має реєструвати `setupEntry`:** + + + - Реєстрації CLI. + - Фонові сервіси. + - Важкі імпорти runtime (crypto, SDK). + - Методи Gateway, потрібні лише після запуску. + + -- Об’єкт Channel Plugin (через `defineSetupPluginEntry`) -- Будь-які HTTP-маршрути, потрібні до того, як Gateway почне слухати -- Будь-які методи Gateway, потрібні під час запуску +### Вузькі імпорти допоміжних засобів налаштування -Ці методи Gateway для запуску все одно мають уникати зарезервованих просторів -імен core admin, таких як `config.*` або `update.*`. +Для гарячих шляхів лише налаштування віддавайте перевагу вузьким допоміжним швам налаштування замість ширшого umbrella `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: -**Що НЕ має містити `setupEntry`:** +| Шлях імпорту | Використовуйте для | Ключові експорти | +| ---------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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` | -- Реєстрації CLI -- Фонові служби -- Важкі runtime-імпорти (crypto, SDK) -- Методи Gateway, потрібні лише після запуску +Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний набір інструментів налаштування, включно з допоміжними засобами патчів конфігурації, такими як `moveSingleAccountChannelSectionToDefaultAccount(...)`. -### Вузькі імпорти допоміжних засобів setup +Адаптери патчів налаштування залишаються безпечними для імпорту на гарячому шляху. Їхній пошук поверхні контракту просування одного облікового запису у вбудованому режимі є ледачим, тому імпорт `plugin-sdk/setup-runtime` не завантажує завчасно виявлення поверхні вбудованого контракту до фактичного використання адаптера. -Для гарячих шляхів лише setup віддавайте перевагу вузьким швам допоміжних засобів setup замість ширшого -парасолькового `plugin-sdk/setup`, якщо вам потрібна лише частина поверхні setup: +### Просування одного облікового запису під контролем каналу -| Шлях імпорту | Використовуйте для | Ключові експорти | -| --------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | допоміжні засоби runtime під час setup, які залишаються доступними в `setupEntry` / відкладеному запуску Channel | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | адаптери setup облікових записів з урахуванням середовища | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | допоміжні засоби CLI/архіву/документації для setup/install | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +Коли канал оновлюється від верхньорівневої конфігурації одного облікового запису до `channels..accounts.*`, стандартна спільна поведінка переміщує значення, що стали прив’язаними до облікового запису, у `accounts.default`. -Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний -набір інструментів setup, включно з допоміжними засобами для patch конфігурації, такими як -`moveSingleAccountChannelSectionToDefaultAccount(...)`. +Вбудовані канали можуть звузити або перевизначити це просування через свою поверхню контракту налаштування: -Адаптери patch для setup залишаються безпечними для імпорту на гарячому шляху. Їхній вбудований -lazy-пошук поверхні контракту для single-account promotion є відкладеним, тому імпорт -`plugin-sdk/setup-runtime` не виконує жадібне завантаження виявлення поверхні вбудованого контракту -до моменту фактичного використання адаптера. +- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити до просунутого облікового запису +- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці ключі переміщуються до просунутого облікового запису; спільні ключі політики/доставки залишаються в корені каналу +- `resolveSingleAccountPromotionTarget(...)`: вибір наявного облікового запису, який отримає просунуті значення -### Single-account promotion, що належить Channel - -Коли Channel оновлюється з однорівневої top-level конфігурації одного облікового запису до -`channels..accounts.*`, типова спільна поведінка полягає в перенесенні -значень рівня облікового запису, що просуваються, до `accounts.default`. - -Вбудовані Channel можуть звузити або перевизначити це просування через свою setup -поверхню контракту: - -- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити до - просунутого облікового запису -- `namedAccountPromotionKeys`: якщо іменовані облікові записи вже існують, лише ці - ключі переміщуються до просунутого облікового запису; спільні ключі policy/delivery залишаються в корені - Channel -- `resolveSingleAccountPromotionTarget(...)`: вибрати, який наявний обліковий запис - отримає просунуті значення - -Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix, -або якщо `defaultAccount` вказує на наявний неканонічний ключ, наприклад -`Ops`, просування зберігає цей обліковий запис замість створення нового запису -`accounts.default`. + +Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix або якщо `defaultAccount` вказує на наявний неканонічний ключ, такий як `Ops`, просування зберігає цей обліковий запис замість створення нового запису `accounts.default`. + ## Схема конфігурації -Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі -налаштовують Plugins через: +Конфігурація Plugin перевіряється на відповідність JSON Schema у вашому маніфесті. Користувачі налаштовують Plugin через: ```json5 { @@ -401,9 +370,9 @@ Matrix — поточний вбудований приклад. Якщо вже } ``` -Під час реєстрації ваш Plugin отримує цю конфігурацію як `api.pluginConfig`. +Ваш Plugin отримує цю конфігурацію як `api.pluginConfig` під час реєстрації. -Для конфігурації, специфічної для Channel, використовуйте натомість секцію конфігурації Channel: +Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу: ```json5 { @@ -416,10 +385,9 @@ Matrix — поточний вбудований приклад. Якщо вже } ``` -### Побудова схем конфігурації Channel +### Побудова схем конфігурації каналу -Використовуйте `buildChannelConfigSchema`, щоб перетворити схему Zod на -обгортку `ChannelConfigSchema`, яку використовують артефакти конфігурації, що належать Plugin: +Використовуйте `buildChannelConfigSchema`, щоб перетворити схему Zod на обгортку `ChannelConfigSchema`, яка використовується артефактами конфігурації під контролем Plugin: ```typescript import { z } from "zod"; @@ -435,15 +403,11 @@ const accountSchema = z.object({ const configSchema = buildChannelConfigSchema(accountSchema); ``` -Для сторонніх Plugins холодний шлях контракту все ще залишається маніфестом Plugin: -віддзеркальте згенеровану JSON Schema в `openclaw.plugin.json#channelConfigs`, щоб -поверхні схеми конфігурації, setup і UI могли перевіряти `channels.` без -завантаження runtime-коду. +Для сторонніх Plugin холодний шлях контракту все ще лишається за маніфестом Plugin: віддзеркальте згенеровану JSON Schema в `openclaw.plugin.json#channelConfigs`, щоб схема конфігурації, налаштування та поверхні UI могли перевіряти `channels.` без завантаження коду runtime. ## Майстри налаштування -Channel Plugins можуть надавати інтерактивні майстри налаштування для `openclaw onboard`. -Майстер — це об’єкт `ChannelSetupWizard` у `ChannelPlugin`: +Plugin каналів можуть надавати інтерактивні майстри налаштування для `openclaw onboard`. Майстер — це об’єкт `ChannelSetupWizard` у `ChannelPlugin`: ```typescript import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup"; @@ -476,82 +440,75 @@ 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` тощо. Повні приклади дивіться у вбудованих пакетах Plugin (наприклад, Plugin Discord `src/channel.setup.ts`). -Для prompt-ів списку дозволених DM, яким потрібен лише стандартний потік -`note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним допоміжним засобам setup -з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, -`createTopLevelChannelParsedAllowFromPrompt(...)` і -`createNestedChannelParsedAllowFromPrompt(...)`. + + + Для запитів DM allowlist, яким потрібен лише стандартний потік `note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним допоміжним засобам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`. + + + Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, віддавайте перевагу `createStandardChannelSetupStatus(...)` з `openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у кожному Plugin. + + + Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте `createOptionalChannelSetupSurface` з `openclaw/plugin-sdk/channel-setup`: -Для блоків статусу setup Channel, які відрізняються лише мітками, оцінками та необов’язковими -додатковими рядками, віддавайте перевагу `createStandardChannelSetupStatus(...)` з -`openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у -кожному Plugin. + ```typescript + import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; -Для необов’язкових поверхонь setup, які мають з’являтися лише в певних контекстах, використовуйте -`createOptionalChannelSetupSurface` з `openclaw/plugin-sdk/channel-setup`: + const setupSurface = createOptionalChannelSetupSurface({ + channel: "my-channel", + label: "My Channel", + npmSpec: "@myorg/openclaw-my-channel", + docsPath: "/channels/my-channel", + }); + // Повертає { setupAdapter, setupWizard } + ``` -```typescript -import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; + `plugin-sdk/channel-setup` також надає нижчорівневі білдери `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї необов’язкової поверхні встановлення. -const setupSurface = createOptionalChannelSetupSurface({ - channel: "my-channel", - label: "My Channel", - npmSpec: "@myorg/openclaw-my-channel", - docsPath: "/channels/my-channel", -}); -// Returns { setupAdapter, setupWizard } -``` + Згенеровані необов’язкові адаптер/майстер безпечно завершуються відмовою на реальних записах конфігурації. Вони повторно використовують одне повідомлення про обов’язкове встановлення для `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо задано `docsPath`. -`plugin-sdk/channel-setup` також надає нижчорівневі конструктори -`createOptionalChannelSetupAdapter(...)` і -`createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина -цієї необов’язкової поверхні встановлення. + + + Для UI налаштування з бінарною основою віддавайте перевагу спільним делегованим допоміжним засобам замість копіювання однакового glue-коду для binary/status у кожен канал: -Згенеровані необов’язкові adapter/wizard безпечно завершуються відмовою під час реальних записів конфігурації. Вони -повторно використовують одне повідомлення про необхідність встановлення в `validateInput`, -`applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо задано `docsPath`. + - `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише мітками, підказками, оцінками та виявленням binary + - `createCliPathTextInput(...)` для текстових вводів, що спираються на шлях + - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ледачо переспрямовувати до важчого повного майстра + - `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` має лише делегувати рішення `textInputs[*].shouldPrompt` -Для UI налаштування, що працюють через binary, віддавайте перевагу спільним делегованим helper-ам замість -копіювання того самого glue-коду binary/status у кожен Channel: - -- `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише мітками, - підказками, оцінками та виявленням binary -- `createCliPathTextInput(...)` для `textInputs`, що працюють зі шляхом -- `createDelegatedSetupWizardStatusResolvers(...)`, - `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і - `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво переспрямовувати до - важчого повного wizard -- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` потрібно лише - делегувати рішення `textInputs[*].shouldPrompt` + + ## Публікація та встановлення -**Зовнішні Plugins:** опублікуйте в [ClawHub](/uk/tools/clawhub) або npm, а потім встановіть: +**Зовнішні Plugin:** опублікуйте в [ClawHub](/uk/tools/clawhub) або npm, а потім встановіть: -```bash -openclaw plugins install @myorg/openclaw-my-plugin -``` + + + ```bash + openclaw plugins install @myorg/openclaw-my-plugin + ``` -OpenClaw спочатку намагається використати ClawHub і автоматично переходить на npm у разі невдачі. Ви також -можете явно примусово використати ClawHub: + OpenClaw спочатку пробує ClawHub і автоматично переходить до npm у разі невдачі. -```bash -openclaw plugins install clawhub:@myorg/openclaw-my-plugin # лише ClawHub -``` + + + ```bash + openclaw plugins install clawhub:@myorg/openclaw-my-plugin + ``` + + + Відповідного перевизначення `npm:` немає. Використовуйте звичайну специфікацію npm-пакета, коли вам потрібен шлях npm після відкату з ClawHub: -Відповідного override `npm:` не існує. Використовуйте звичайний npm package spec, якщо -вам потрібен шлях через npm після fallback із ClawHub: + ```bash + openclaw plugins install @myorg/openclaw-my-plugin + ``` -```bash -openclaw plugins install @myorg/openclaw-my-plugin -``` + + -**Plugins у репозиторії:** розмістіть їх у дереві workspace вбудованих Plugin, і вони автоматично -виявлятимуться під час збірки. +**Plugin у репозиторії:** розмістіть у дереві workspace вбудованих Plugin, і їх буде автоматично виявлено під час збірки. **Користувачі можуть встановити:** @@ -560,20 +517,15 @@ openclaw plugins install ``` - Для встановлень із npm `openclaw plugins install` запускає - локальний для проєкту `npm install --ignore-scripts` (без lifecycle scripts), ігноруючи - успадковані глобальні налаштування встановлення npm. Зберігайте дерева залежностей Plugin у чистому JS/TS - та уникайте пакунків, які потребують збірки через `postinstall`. +Для встановлень із джерела npm `openclaw plugins install` запускає локальний для проєкту `npm install --ignore-scripts` (без lifecycle scripts), ігноруючи успадковані глобальні налаштування npm install. Зберігайте дерева залежностей Plugin чистими JS/TS та уникайте пакетів, яким потрібні збірки через `postinstall`. -Вбудовані Plugins, що належать OpenClaw, — єдиний виняток для відновлення під час запуску: коли -упаковане встановлення бачить один із них увімкненим через конфігурацію Plugin, застарілу конфігурацію Channel або -його вбудований маніфест із увімкненням за замовчуванням, під час запуску встановлюються відсутні -runtime-залежності цього Plugin перед імпортом. Стороннім Plugins не слід покладатися на встановлення -під час запуску; продовжуйте використовувати явний installer Plugin. + +Вбудовані Plugin, що належать OpenClaw, — єдиний виняток для відновлення під час запуску: коли пакетне встановлення бачить один із них увімкненим через конфігурацію Plugin, застарілу конфігурацію каналу або його вбудований маніфест із увімкненням за замовчуванням, під час запуску виконуються встановлення відсутніх залежностей runtime цього Plugin перед імпортом. Стороннім Plugin не слід покладатися на встановлення під час запуску; і надалі використовуйте явний інсталятор Plugin. + ## Пов’язане +- [Створення Plugin](/uk/plugins/building-plugins) — покроковий посібник для початку роботи +- [Маніфест Plugin](/uk/plugins/manifest) — повна довідка щодо схеми маніфесту - [Точки входу SDK](/uk/plugins/sdk-entrypoints) — `definePluginEntry` і `defineChannelPluginEntry` -- [Маніфест Plugin](/uk/plugins/manifest) — повний довідник схеми маніфесту -- [Створення Plugins](/uk/plugins/building-plugins) — покроковий посібник для початку роботи diff --git a/docs/uk/tools/slash-commands.md b/docs/uk/tools/slash-commands.md index ba8567245..545e53e53 100644 --- a/docs/uk/tools/slash-commands.md +++ b/docs/uk/tools/slash-commands.md @@ -2,40 +2,44 @@ read_when: - Використання або налаштування команд чату - Налагодження маршрутизації команд або дозволів -summary: 'Слеш-команди: текстові та нативні, конфігурація та підтримувані команди' +sidebarTitle: Slash commands +summary: 'Слеш-команди: текстові проти нативних, конфігурація та підтримувані команди' title: Слеш-команди x-i18n: - generated_at: "2026-04-26T03:03:22Z" + generated_at: "2026-04-26T08:15:42Z" model: gpt-5.4 provider: openai - source_hash: cd97db0918e9ca0de77034d9a3e522d8b250ea66b210fc5d16ebfd60d6f73002 + source_hash: 75bf58d02738e30bfdc00ad1c264b2f066eebd2819f4ea0209f504f279755993 source_path: tools/slash-commands.md workflow: 15 --- -Команди зі слешем: текстові та нативні, конфігурація та підтримувані команди +Команди обробляються Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. Команда чату bash лише для хоста використовує `! ` (з псевдонімом `/bash `). -Команди обробляються Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. -Команда чату bash лише для хоста використовує `! ` (із псевдонімом `/bash `). - -Коли розмову або тред прив’язано до сесії ACP, звичайний подальший текст -маршрутизується до цього harness ACP. Команди керування Gateway усе одно залишаються локальними: -`/acp ...` завжди потрапляє до обробника команд ACP в OpenClaw, а `/status` і -`/unfocus` залишаються локальними завжди, коли обробку команд увімкнено для цієї поверхні. +Коли розмову або тред прив’язано до сесії ACP, звичайний подальший текст маршрутизується до цього harness ACP. Команди керування Gateway все одно залишаються локальними: `/acp ...` завжди потрапляє до обробника команд OpenClaw ACP, а `/status` і `/unfocus` залишаються локальними щоразу, коли для цієї поверхні ввімкнено обробку команд. Є дві пов’язані системи: -- **Команди**: окремі повідомлення `/...`. -- **Директиви**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - - Директиви видаляються з повідомлення до того, як модель його побачить. - - У звичайних повідомленнях чату (не лише з директивами) вони трактуються як «вбудовані підказки» і **не** зберігають налаштування сесії. - - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та відповідають підтвердженням. - - Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, це єдиний - список дозволених відправників; інакше авторизація походить зі списків дозволу/спарювання каналу плюс `commands.useAccessGroups`. - Для неавторизованих відправників директиви трактуються як звичайний текст. + + + Окремі повідомлення `/...`. + + + `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. -Є також кілька **вбудованих скорочень** (лише для відправників зі списку дозволених/авторизованих): `/help`, `/commands`, `/status`, `/whoami` (`/id`). -Вони виконуються негайно, видаляються до того, як модель побачить повідомлення, а решта тексту проходить далі звичайним потоком. + - Директиви вилучаються з повідомлення до того, як модель його побачить. + - У звичайних повідомленнях чату (не лише з директивами) вони трактуються як "вбудовані підказки" і **не** зберігають налаштування сесії. + - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та повертають підтвердження. + - Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, використовується лише цей список дозволу; інакше авторизація походить зі списків дозволу каналу/прив’язки плюс `commands.useAccessGroups`. Для неавторизованих відправників директиви трактуються як звичайний текст. + + + + Лише для відправників зі списку дозволу/авторизованих: `/help`, `/commands`, `/status`, `/whoami` (`/id`). + + Вони виконуються негайно, вилучаються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайним потоком. + + + ## Конфігурація @@ -64,112 +68,150 @@ x-i18n: } ``` -- `commands.text` (типово `true`) вмикає розбір `/...` у повідомленнях чату. - - На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо ви встановите це значення як `false`. -- `commands.native` (типово `"auto"`) реєструє нативні команди. - - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте слеш-команди); ігнорується для провайдерів без нативної підтримки. - - Щоб перевизначити для конкретного провайдера, задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native` (bool або `"auto"`). - - `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і автоматично не видаляються. -- `commands.nativeSkills` (типово `"auto"`) нативно реєструє команди **Skills**, коли це підтримується. - - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створювати окрему слеш-команду для кожного Skill). - - Щоб перевизначити для конкретного провайдера, задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills` (bool або `"auto"`). -- `commands.bash` (типово `false`) вмикає `! ` для запуску команд оболонки хоста (`/bash ` — псевдонім; потрібні списки дозволу `tools.elevated`). -- `commands.bashForegroundMs` (типово `2000`) керує тим, як довго bash чекає перед переходом у фоновий режим (`0` одразу переводить у фон). -- `commands.config` (типово `false`) вмикає `/config` (читання/запис `openclaw.json`). -- `commands.mcp` (типово `false`) вмикає `/mcp` (читання/запис конфігурації MCP, якою керує OpenClaw, у `mcp.servers`). -- `commands.plugins` (типово `false`) вмикає `/plugins` (виявлення/стан плагінів плюс керування встановленням і ввімкненням/вимкненням). -- `commands.debug` (типово `false`) вмикає `/debug` (перевизначення лише під час виконання). -- `commands.restart` (типово `true`) вмикає `/restart` плюс дії інструментів перезапуску gateway. -- `commands.ownerAllowFrom` (необов’язково) задає явний список дозволених власників для поверхонь команд/інструментів лише для власника. Це окремо від `commands.allowFrom`. -- `channels..commands.enforceOwnerForCommands` для кожного каналу (необов’язково, типово `false`) змушує команди лише для власника вимагати **ідентичність власника** для виконання на цій поверхні. Коли значення `true`, відправник має або відповідати визначеному кандидату у власники (наприклад, запису в `commands.ownerAllowFrom` або нативним метаданим власника провайдера), або мати внутрішню область дії `operator.admin` на внутрішньому каналі повідомлень. Запис із wildcard у `allowFrom` каналу або порожній/невизначений список кандидатів у власники **не** є достатнім — команди лише для власника на цьому каналі закриваються за принципом fail closed. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися лише `ownerAllowFrom` і стандартними списками дозволу команд. -- `commands.ownerDisplay` керує тим, як ID власника з’являються в системному промпті: `raw` або `hash`. -- `commands.ownerDisplaySecret` необов’язково задає секрет HMAC, що використовується, коли `commands.ownerDisplay="hash"`. -- `commands.allowFrom` (необов’язково) задає список дозволених відправників для авторизації команд окремо для кожного провайдера. Якщо його налаштовано, це - єдине джерело авторизації для команд і директив (списки дозволу/спарювання каналу та `commands.useAccessGroups` - ігноруються). Використовуйте `"*"` як глобальне значення за замовчуванням; ключі конкретних провайдерів мають пріоритет. -- `commands.useAccessGroups` (типово `true`) застосовує списки дозволу/політики для команд, коли `commands.allowFrom` не задано. + + Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити `false`. + + + Реєструє нативні команди. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте слеш-команди); ігнорується для провайдерів без нативної підтримки. Щоб перевизначити для окремого провайдера, задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native` (bool або `"auto"`). Значення `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються у застосунку Slack і не видаляються автоматично. + + + Реєструє команди **Skills** нативно, коли це підтримується. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створити слеш-команду для кожного skill). Щоб перевизначити для окремого провайдера, задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills` (bool або `"auto"`). + + + Вмикає `! ` для запуску shell-команд хоста (`/bash ` — псевдонім; потребує списків дозволу `tools.elevated`). + + + Керує тим, скільки часу bash чекає перед переходом у фоновий режим (`0` одразу переводить у фон). + + + Вмикає `/config` (читає/записує `openclaw.json`). + + + Вмикає `/mcp` (читає/записує конфігурацію MCP, якою керує OpenClaw, у `mcp.servers`). + + + Вмикає `/plugins` (виявлення/статус plugin-ів, а також керування встановленням і ввімкненням/вимкненням). + + + Вмикає `/debug` (лише перевизначення під час виконання). + + + Вмикає `/restart`, а також дії інструментів перезапуску gateway. + + + Встановлює явний список дозволу власника для поверхонь команд/інструментів, доступних лише власнику. Окремо від `commands.allowFrom`. + + + Для кожного каналу: змушує команди лише для власника вимагати **ідентичність власника** для виконання на цій поверхні. Якщо `true`, відправник має або відповідати визначеному кандидату у власники (наприклад, запису в `commands.ownerAllowFrom` або нативним метаданим власника провайдера), або мати внутрішню область доступу `operator.admin` на внутрішньому каналі повідомлень. Підстановний запис у `allowFrom` каналу або порожній/невизначений список кандидатів у власники **не** є достатнім — команди лише для власника в цьому каналі забороняються за замовчуванням. Залишайте це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися лише `ownerAllowFrom` і стандартними списками дозволу команд. + + + Керує тим, як ідентифікатори власника відображаються в системному prompt. + + + За потреби задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`. + + + Список дозволу для авторизації команд за провайдером. Якщо налаштовано, це єдине джерело авторизації для команд і директив (списки дозволу каналу/прив’язки та `commands.useAccessGroups` ігноруються). Використовуйте `"*"` як глобальне значення за замовчуванням; ключі для конкретних провайдерів мають пріоритет. + + + Застосовує списки дозволу/політики до команд, якщо `commands.allowFrom` не задано. + ## Список команд Поточне джерело істини: -- вбудовані команди ядра надходять із `src/auto-reply/commands-registry.shared.ts` -- згенеровані команди dock надходять із `src/auto-reply/commands-registry.data.ts` -- команди плагінів надходять із викликів `registerCommand()` у плагінах -- фактична доступність у вашому gateway усе одно залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених плагінів +- вбудовані core-команди походять із `src/auto-reply/commands-registry.shared.ts` +- згенеровані dock-команди походять із `src/auto-reply/commands-registry.data.ts` +- команди plugin-ів походять із викликів `registerCommand()` у plugin-ах +- фактична доступність у вашому gateway усе одно залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugin-ів -### Вбудовані команди ядра +### Вбудовані команди core -Сьогодні доступні вбудовані команди: - -- `/new [model]` починає нову сесію; `/reset` — псевдонім для скидання. -- `/reset soft [message]` зберігає поточний транскрипт, відкидає повторно використані ID сесій CLI backend і повторно запускає завантаження startup/system-prompt на місці. -- `/compact [instructions]` виконує Compaction контексту сесії. Див. [/concepts/compaction](/uk/concepts/compaction). -- `/stop` перериває поточний запуск. -- `/session idle ` і `/session max-age ` керують строком дії прив’язки до треду. -- `/think ` задає рівень thinking. Варіанти надходять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а користувацькі рівні на кшталт `xhigh`, `adaptive`, `max` або двійковий `on` доступні лише там, де це підтримується. Псевдоніми: `/thinking`, `/t`. -- `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`. -- `/trace on|off` перемикає вивід трасування плагінів для поточної сесії. -- `/fast [status|on|off]` показує або задає швидкий режим. -- `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`. -- `/elevated [on|off|ask|full]` перемикає підвищений режим. Псевдонім: `/elev`. -- `/exec host= security= ask= node=` показує або задає значення за замовчуванням для exec. -- `/model [name|#|status]` показує або задає модель. -- `/models [provider] [page] [limit=|size=|all]` перелічує провайдерів або моделі для провайдера. -- `/queue ` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) плюс параметрами на кшталт `debounce:2s cap:25 drop:summarize`. -- `/help` показує короткий підсумок довідки. -- `/commands` показує згенерований каталог команд. -- `/tools [compact|verbose]` показує, що поточний агент може використовувати просто зараз. -- `/status` показує статус виконання/середовища виконання, зокрема мітки `Execution`/`Runtime` і використання/квоту провайдера, коли це доступно. -- `/crestodian ` запускає помічник налаштування та відновлення Crestodian з особистих повідомлень власника. -- `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії. -- `/context [list|detail|json]` пояснює, як збирається контекст. -- `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`. -- `/export-trajectory [path]` експортує JSONL-[trajectory bundle](/uk/tools/trajectory) для поточної сесії. Псевдонім: `/trajectory`. -- `/whoami` показує ваш ID відправника. Псевдонім: `/id`. -- `/skill [input]` запускає Skill за назвою. -- `/allowlist [list|add|remove] ...` керує записами allowlist. Лише текстова. -- `/approve ` розв’язує запити на схвалення exec. -- `/btw ` ставить побічне запитання без зміни майбутнього контексту сесії. Див. [/tools/btw](/uk/tools/btw). -- `/subagents list|kill|log|info|send|steer|spawn` керує запусками субагентів для поточної сесії. -- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP і параметрами середовища виконання. -- `/focus ` прив’язує поточний тред Discord або тему/розмову Telegram до цільової сесії. -- `/unfocus` видаляє поточну прив’язку. -- `/agents` перелічує агентів, прив’язаних до треду, для поточної сесії. -- `/kill ` перериває одного або всіх запущених субагентів. -- `/steer ` надсилає керівну вказівку запущеному субагенту. Псевдонім: `/tell`. -- `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потрібно `commands.config: true`. -- `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, якою керує OpenClaw, у `mcp.servers`. Лише для власника. Потрібно `commands.mcp: true`. -- `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан плагінів. `/plugin` — псевдонім. Запис — лише для власника. Потрібно `commands.plugins: true`. -- `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише під час виконання. Лише для власника. Потрібно `commands.debug: true`. -- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальний підсумок вартості. -- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` керує TTS. Див. [/tools/tts](/uk/tools/tts). -- `/restart` перезапускає OpenClaw, якщо це ввімкнено. Типово: увімкнено; задайте `commands.restart: false`, щоб вимкнути. -- `/activation mention|always` задає режим активації групи. -- `/send on|off|inherit` задає політику надсилання. Лише для власника. -- `/bash ` запускає команду оболонки хоста. Лише текстова. Псевдонім: `! `. Потрібно `commands.bash: true` плюс allowlist `tools.elevated`. -- `!poll [sessionId]` перевіряє фонове bash-завдання. -- `!stop [sessionId]` зупиняє фонове bash-завдання. + + + - `/new [model]` запускає нову сесію; `/reset` — псевдонім для скидання. + - `/reset soft [message]` зберігає поточний transcript, скидає повторно використані ідентифікатори сесій CLI backend і повторно запускає завантаження startup/system-prompt на місці. + - `/compact [instructions]` стискає контекст сесії. Див. [Compaction](/uk/concepts/compaction). + - `/stop` перериває поточний запуск. + - `/session idle ` і `/session max-age ` керують строком дії прив’язки до треду. + - `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`. + - `/export-trajectory [path]` експортує JSONL [trajectory bundle](/uk/tools/trajectory) для поточної сесії. Псевдонім: `/trajectory`. + + + - `/think ` задає рівень мислення. Варіанти надходять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а також спеціальні рівні на кшталт `xhigh`, `adaptive`, `max` або бінарний `on` лише там, де це підтримується. Псевдоніми: `/thinking`, `/t`. + - `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`. + - `/trace on|off` перемикає вивід трасування plugin-ів для поточної сесії. + - `/fast [status|on|off]` показує або задає швидкий режим. + - `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`. + - `/elevated [on|off|ask|full]` перемикає elevated mode. Псевдонім: `/elev`. + - `/exec host= security= ask= node=` показує або задає значення exec за замовчуванням. + - `/model [name|#|status]` показує або задає модель. + - `/models [provider] [page] [limit=|size=|all]` перелічує провайдерів або моделі для провайдера. + - `/queue ` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`), а також параметрами на кшталт `debounce:2s cap:25 drop:summarize`. + + + - `/help` показує короткий довідковий підсумок. + - `/commands` показує згенерований каталог команд. + - `/tools [compact|verbose]` показує, чим поточний агент може користуватися прямо зараз. + - `/status` показує статус виконання/середовища виконання, зокрема мітки `Execution`/`Runtime` і використання/квоти провайдера, якщо доступно. + - `/crestodian ` запускає помічник налаштування й відновлення Crestodian із приватного повідомлення власника. + - `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії. + - `/context [list|detail|json]` пояснює, як збирається контекст. + - `/whoami` показує ваш ідентифікатор відправника. Псевдонім: `/id`. + - `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальний підсумок вартості. + + + - `/skill [input]` запускає skill за назвою. + - `/allowlist [list|add|remove] ...` керує записами списку дозволу. Лише текстовий режим. + - `/approve ` обробляє запити на підтвердження exec. + - `/btw ` ставить побічне запитання без зміни майбутнього контексту сесії. Див. [BTW](/uk/tools/btw). + + + - `/subagents list|kill|log|info|send|steer|spawn` керує запусками subagent-ів для поточної сесії. + - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP і параметрами середовища виконання. + - `/focus ` прив’язує поточний тред Discord або тему/розмову Telegram до цільової сесії. + - `/unfocus` знімає поточну прив’язку. + - `/agents` перелічує агентів, прив’язаних до треду, для поточної сесії. + - `/kill ` перериває один або всі запущені subagent-и. + - `/steer ` надсилає керуюче повідомлення до запущеного subagent-а. Псевдонім: `/tell`. + + + - `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потребує `commands.config: true`. + - `/mcp show|get|set|unset` читає або записує конфігурацію сервера MCP, якою керує OpenClaw, у `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`. + - `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin-ів. `/plugin` — псевдонім. Запис — лише для власника. Потребує `commands.plugins: true`. + - `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише під час виконання. Лише для власника. Потребує `commands.debug: true`. + - `/restart` перезапускає OpenClaw, якщо ввімкнено. За замовчуванням: увімкнено; щоб вимкнути, задайте `commands.restart: false`. + - `/send on|off|inherit` задає політику надсилання. Лише для власника. + + + - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` керує TTS. Див. [TTS](/uk/tools/tts). + - `/activation mention|always` задає режим активації групи. + - `/bash ` запускає shell-команду хоста. Лише текстовий режим. Псевдонім: `! `. Потребує `commands.bash: true` і списків дозволу `tools.elevated`. + - `!poll [sessionId]` перевіряє фонове завдання bash. + - `!stop [sessionId]` зупиняє фонове завдання bash. + + ### Згенеровані dock-команди -Dock-команди генеруються з плагінів каналів із підтримкою нативних команд. Поточний вбудований набір: +Dock-команди генеруються з channel plugin-ів із підтримкою нативних команд. Поточний вбудований набір: - `/dock-discord` (псевдонім: `/dock_discord`) - `/dock-mattermost` (псевдонім: `/dock_mattermost`) - `/dock-slack` (псевдонім: `/dock_slack`) - `/dock-telegram` (псевдонім: `/dock_telegram`) -### Команди вбудованих плагінів +### Команди вбудованих plugin-ів -Вбудовані плагіни можуть додавати більше слеш-команд. Поточні вбудовані команди в цьому репозиторії: +Вбудовані plugin-и можуть додавати більше слеш-команд. Поточні вбудовані команди в цьому репозиторії: - `/dreaming [on|off|status|help]` перемикає Dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming). -- `/pair [qr|status|pending|approve|cleanup|notify]` керує процесом спарювання/налаштування пристрою. Див. [Спарювання](/uk/channels/pairing). -- `/phone status|arm [duration]|disarm` тимчасово активує високоризикові команди Node телефона. +- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком прив’язки/налаштування пристрою. Див. [Pairing](/uk/channels/pairing). +- `/phone status|arm [duration]|disarm` тимчасово озброює високоризикові команди вузла телефону. - `/voice status|list [limit]|set ` керує конфігурацією голосу Talk. У Discord назва нативної команди — `/talkvoice`. -- `/card ...` надсилає пресети LINE rich card. Див. [LINE](/uk/channels/line). -- `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє та керує вбудованим harness сервера застосунку Codex. Див. [Codex Harness](/uk/plugins/codex-harness). +- `/card ...` надсилає набори rich card для LINE. Див. [LINE](/uk/channels/line). +- `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє та керує вбудованим harness app-server Codex. Див. [Codex harness](/uk/plugins/codex-harness). - Команди лише для QQBot: - `/bot-ping` - `/bot-version` @@ -177,77 +219,83 @@ Dock-команди генеруються з плагінів каналів і - `/bot-upgrade` - `/bot-logs` -### Динамічні команди Skills +### Динамічні команди skill-ів Skills, які може викликати користувач, також доступні як слеш-команди: -- `/skill [input]` завжди працює як загальна точка входу. -- Skills також можуть з’являтися як прямі команди, наприклад `/prose`, коли Skill/плагін їх реєструє. -- Реєстрацією нативних команд Skills керують `commands.nativeSkills` і `channels..commands.nativeSkills`. +- `/skill [input]` завжди працює як універсальна точка входу. +- skills також можуть з’являтися як прямі команди, наприклад `/prose`, коли їх реєструє skill/plugin. +- реєстрація нативних команд skill-ів керується через `commands.nativeSkills` і `channels..commands.nativeSkills`. -Примітки: - -- Команди приймають необов’язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). -- `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігів немає, текст трактується як тіло повідомлення. -- Для повного розподілу використання провайдера використовуйте `openclaw status --usage`. -- `/allowlist add|remove` потребує `commands.config=true` і враховує канал `configWrites`. -- У каналах із кількома обліковими записами команди `/allowlist --account `, націлені на конфігурацію, і `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. -- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальний підсумок вартості з журналів сесій OpenClaw. -- `/restart` увімкнено типово; задайте `commands.restart: false`, щоб вимкнути його. -- `/plugins install ` приймає ті самі специфікації плагінів, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет або `clawhub:`. -- `/plugins enable|disable` оновлює конфігурацію плагінів і може запропонувати перезапуск. -- Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступна як текстова). `join` потребує guild і вибраного голосового/stage-каналу. Потрібні `channels.discord.voice` і нативні команди. -- Команди прив’язки до тредів Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) вимагають, щоб ефективні прив’язки до тредів були ввімкнені (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). -- Довідник команд ACP і поведінка середовища виконання: [ACP Agents](/uk/tools/acp-agents). -- `/verbose` призначено для налагодження та додаткової видимості; у звичайному використанні тримайте його **вимкненим**. -- `/trace` вужчий за `/verbose`: він показує лише рядки trace/debug, що належать плагінам, і не вмикає звичайний докладний шум від інструментів. -- `/fast on|off` зберігає перевизначення для сесії. Використовуйте опцію `inherit` в інтерфейсі Sessions, щоб очистити його й повернутися до значень конфігурації за замовчуванням. -- `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних кінцевих точках Responses, тоді як прямі публічні запити до Anthropic, зокрема трафік з OAuth-автентифікацією, надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). -- Підсумки збоїв інструментів усе ще показуються, коли це доречно, але детальний текст збоїв включається лише коли `/verbose` має значення `on` або `full`. -- `/reasoning`, `/verbose` і `/trace` є ризикованими в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику плагінів, які ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах. -- `/model` негайно зберігає нову модель сесії. -- Якщо агент неактивний, наступний запуск одразу її використовує. -- Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускається на новій моделі лише в чистій точці повторної спроби. -- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача. -- У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до - Crestodian. Це окремо від режиму відновлення каналу повідомлень і не - надає віддалених повноважень на конфігурацію. -- **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволених обробляються негайно (обхід черги + моделі). -- **Фільтрація згадок у групах:** повідомлення лише з командами від відправників зі списку дозволених обходять вимоги щодо згадок. -- **Вбудовані скорочення (лише для відправників зі списку дозволених):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і видаляються до того, як модель побачить решту. - - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує проходити звичайним потоком. -- Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`). -- Неавторизовані повідомлення лише з командами тихо ігноруються, а вбудовані токени `/...` трактуються як звичайний текст. -- **Команди Skills:** Skills із `user-invocable` також доступні як слеш-команди. Назви санітизуються до `a-z0-9_` (макс. 32 символи); колізії отримують числові суфікси (наприклад, `_2`). - - `/skill [input]` запускає Skill за назвою (корисно, коли обмеження нативних команд не дозволяють окремі команди для кожного Skill). - - Типово команди Skills передаються моделі як звичайний запит. - - Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі). - - Приклад: `/prose` (плагін OpenProse) — див. [OpenProse](/uk/prose). -- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти й ви пропускаєте аргумент. Динамічні варіанти визначаються відносно моделі цільової сесії, тому специфічні для моделі параметри, такі як рівні `/think`, слідують перевизначенню `/model` цієї сесії. + + + - Команди приймають необов’язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). + - `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст трактується як тіло повідомлення. + - Для повного розподілу використання за провайдерами використовуйте `openclaw status --usage`. + - `/allowlist add|remove` потребує `commands.config=true` і враховує `configWrites` каналу. + - У каналах із кількома обліковими записами `/allowlist --account `, націлений на конфігурацію, і `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. + - `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальний підсумок вартості з логів сесій OpenClaw. + - `/restart` увімкнено за замовчуванням; щоб вимкнути, задайте `commands.restart: false`. + - `/plugins install ` приймає ті самі специфікації plugin-ів, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет або `clawhub:`. + - `/plugins enable|disable` оновлює конфігурацію plugin-ів і може запросити перезапуск. + + + - Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступна як текстова команда). `join` потребує guild і вибраного голосового/stage-каналу. Потребує `channels.discord.voice` і нативних команд. + - Команди прив’язки до тредів Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують, щоб ефективні прив’язки до тредів були ввімкнені (`session.threadBindings.enabled` і/або `channels.discord.threadBindings.enabled`). + - Довідник команд ACP і поведінка середовища виконання: [ACP agents](/uk/tools/acp-agents). + + + - `/verbose` призначено для налагодження та додаткової видимості; у звичайному використанні тримайте його **вимкненим**. + - `/trace` вужчий за `/verbose`: він показує лише рядки trace/debug, що належать plugin-ам, і не вмикає звичайну докладну балаканину інструментів. + - `/fast on|off` зберігає перевизначення сесії. Щоб очистити його й повернутися до значень конфігурації за замовчуванням, використовуйте опцію `inherit` в інтерфейсі Sessions. + - `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних ендпоінтах Responses, тоді як прямі публічні запити Anthropic, зокрема трафік з автентифікацією OAuth, надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). + - Підсумки помилок інструментів усе одно показуються, коли це доречно, але детальний текст помилки включається лише коли `/verbose` має значення `on` або `full`. + - `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику plugin-ів, які ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах. + + + - `/model` негайно зберігає нову модель сесії. + - Якщо агент неактивний, наступний запуск одразу її використовує. + - Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене і перезапускає з новою моделлю лише в чистій точці повторної спроби. + - Якщо активність інструментів або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача. + - У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від режиму порятунку каналу повідомлень і не надає віддалених повноважень на зміну конфігурації. + + + - **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволу обробляються негайно (обхід черги + моделі). + - **Обмеження згадкою в групі:** повідомлення лише з командами від відправників зі списку дозволу обходять вимоги згадки. + - **Вбудовані скорочення (лише для відправників зі списку дозволу):** деякі команди також працюють, коли вони вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту. + - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує проходити звичайним потоком. + - Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`). + - Неавторизовані повідомлення лише з командами мовчки ігноруються, а вбудовані токени `/...` трактуються як звичайний текст. + + + - **Команди skill-ів:** skills типу `user-invocable` доступні як слеш-команди. Імена нормалізуються до `a-z0-9_` (макс. 32 символи); у разі колізій додаються числові суфікси (наприклад, `_2`). + - `/skill [input]` запускає skill за назвою (корисно, коли обмеження нативних команд не дозволяють мати окрему команду для кожного skill-а). + - За замовчуванням команди skill-ів пересилаються моделі як звичайний запит. + - Skills можуть за бажанням оголосити `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі). + - Приклад: `/prose` (plugin OpenProse) — див. [OpenProse](/uk/prose). + - **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і кнопкові меню, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують кнопкове меню, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти вибору визначаються відносно моделі цільової сесії, тож параметри, залежні від моделі, як-от рівні `/think`, слідують за перевизначенням `/model` цієї сесії. + + ## `/tools` -`/tools` відповідає на питання про середовище виконання, а не на питання про конфігурацію: **що цей агент може використовувати просто зараз у -цій розмові**. +`/tools` відповідає на питання про середовище виконання, а не про конфігурацію: **чим цей агент може користуватися прямо зараз у цій розмові**. - Типове `/tools` є компактним і оптимізованим для швидкого перегляду. - `/tools verbose` додає короткі описи. -- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму як `compact|verbose`. -- Результати прив’язані до сесії, тому зміна агента, каналу, треду, авторизації відправника або моделі може - змінити вивід. -- `/tools` включає інструменти, які реально доступні під час виконання, зокрема базові інструменти, інструменти - підключених плагінів та інструменти, що належать каналам. +- Поверхні з нативними командами, які підтримують аргументи, надають той самий перемикач режимів `compact|verbose`. +- Результати прив’язані до сесії, тому зміна агента, каналу, треду, авторизації відправника або моделі може змінити вивід. +- `/tools` включає інструменти, які реально доступні під час виконання, зокрема core-інструменти, інструменти під’єднаних plugin-ів і інструменти, що належать каналу. -Для редагування профілів і перевизначень використовуйте панель Tools у Control UI або поверхні конфігурації/каталогу -замість того, щоб трактувати `/tools` як статичний каталог. +Для редагування профілів і перевизначень використовуйте панель Tools у Control UI або поверхні конфігурації/каталогу, а не сприймайте `/tools` як статичний каталог. ## Поверхні використання (що де показується) -- **Використання/квота провайдера** (приклад: “Claude 80% left”) показується в `/status` для поточного провайдера моделі, коли відстеження використання ввімкнено. OpenClaw нормалізує вікна провайдера до `% left`; для MiniMax поля відсотка лише залишку інвертуються перед показом, а відповіді `model_remains` надають перевагу запису chat-model плюс мітці плану з тегом моделі. -- **Рядки токенів/кешу** в `/status` можуть використовувати останній запис використання з транскрипту, коли знімок живої сесії є неповним. Наявні ненульові живі значення все одно мають пріоритет, а резервне значення з транскрипту також може відновити мітку активної моделі runtime плюс більший загальний обсяг, орієнтований на промпт, коли збережені підсумки відсутні або менші. -- **Execution vs runtime:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично виконує сесію: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend. -- **Токени/вартість для кожної відповіді** керуються через `/usage off|tokens|full` (додається до звичайних відповідей). -- `/model status` стосується **моделей/автентифікації/кінцевих точок**, а не використання. +- **Використання/квота провайдера** (наприклад, "Claude 80% left") відображається в `/status` для провайдера поточної моделі, коли ввімкнено відстеження використання. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля відсотка лише залишку інвертуються перед показом, а відповіді `model_remains` віддають перевагу запису chat-моделі разом із міткою плану, позначеною моделлю. +- **Рядки токенів/кешу** в `/status` можуть повертатися до останнього запису використання transcript-а, якщо живий знімок сесії неповний. Наявні ненульові живі значення все одно мають пріоритет, а резервне використання transcript-а також може відновити мітку активної моделі середовища виконання та більший сумарний обсяг, орієнтований на prompt, коли збережені підсумки відсутні або менші. +- **Execution проти Runtime:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично виконує сесію: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend. +- **Токени/вартість для кожної відповіді** керуються через `/usage off|tokens|full` (додаються до звичайних відповідей). +- `/model status` стосується **моделей/auth/ендпоінтів**, а не використання. ## Вибір моделі (`/model`) @@ -264,16 +312,16 @@ Skills, які може викликати користувач, також до /model status ``` -Примітки: +Нотатки: -- `/model` і `/model list` показують компактний нумерований селектор (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний селектор зі списками провайдера й моделі та кроком Submit. -- `/model <#>` вибирає зі списку цього селектора (і за можливості надає перевагу поточному провайдеру). -- `/model status` показує детальний вигляд, зокрема налаштовану кінцеву точку провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. +- `/model` і `/model list` показують компактний нумерований вибір (сімейство моделей + доступні провайдери). +- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадними списками провайдерів і моделей, а також кроком Submit. +- `/model <#>` вибирає з цього засобу вибору (і за можливості надає перевагу поточному провайдеру). +- `/model status` показує докладний вигляд, зокрема налаштований ендпоінт провайдера (`baseUrl`) і режим API (`api`), якщо доступно. ## Перевизначення налагодження -`/debug` дає змогу задавати **перевизначення конфігурації лише під час виконання** (у пам’яті, не на диску). Лише для власника. Типово вимкнено; увімкніть через `commands.debug: true`. +`/debug` дає змогу задавати перевизначення конфігурації **лише під час виконання** (пам’ять, не диск). Лише для власника. За замовчуванням вимкнено; увімкніть через `commands.debug: true`. Приклади: @@ -285,14 +333,13 @@ Skills, які може викликати користувач, також до /debug reset ``` -Примітки: + +Перевизначення застосовуються негайно до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. + -- Перевизначення застосовуються негайно до нових читань конфігурації, але **не** записуються в `openclaw.json`. -- Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. +## Вивід trace plugin-ів -## Вивід трасування плагінів - -`/trace` дає змогу перемикати **рядки trace/debug плагінів у межах сесії** без увімкнення повного докладного режиму. +`/trace` дає змогу перемикати **рядки trace/debug plugin-ів у межах сесії** без увімкнення повного verbose-режиму. Приклади: @@ -302,18 +349,18 @@ Skills, які може викликати користувач, також до /trace off ``` -Примітки: +Нотатки: -- `/trace` без аргументів показує поточний стан trace для сесії. -- `/trace on` вмикає рядки trace плагінів для поточної сесії. +- `/trace` без аргументу показує поточний стан trace для сесії. +- `/trace on` вмикає рядки trace plugin-ів для поточної сесії. - `/trace off` знову їх вимикає. -- Рядки trace плагінів можуть з’являтися в `/status` і як додаткове діагностичне повідомлення після звичайної відповіді помічника. -- `/trace` не замінює `/debug`; `/debug` і далі керує перевизначеннями конфігурації лише під час виконання. +- Рядки trace plugin-ів можуть з’являтися в `/status` і як додаткове діагностичне повідомлення після звичайної відповіді асистента. +- `/trace` не замінює `/debug`; `/debug` як і раніше керує перевизначеннями конфігурації лише під час виконання. - `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/статусу все ще належить до `/verbose`. ## Оновлення конфігурації -`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Типово вимкнено; увімкніть через `commands.config: true`. +`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. За замовчуванням вимкнено; увімкніть через `commands.config: true`. Приклади: @@ -325,14 +372,13 @@ Skills, які може викликати користувач, також до /config unset messages.responsePrefix ``` -Примітки: - -- Перед записом конфігурація проходить валідацію; невалідні зміни відхиляються. -- Оновлення `/config` зберігаються після перезапусків. + +Перед записом конфігурація проходить валідацію; неприпустимі зміни відхиляються. Оновлення `/config` зберігаються після перезапуску. + ## Оновлення MCP -`/mcp` записує визначення MCP-серверів, якими керує OpenClaw, у `mcp.servers`. Лише для власника. Типово вимкнено; увімкніть через `commands.mcp: true`. +`/mcp` записує визначення серверів MCP, якими керує OpenClaw, у `mcp.servers`. Лише для власника. За замовчуванням вимкнено; увімкніть через `commands.mcp: true`. Приклади: @@ -343,14 +389,13 @@ Skills, які може викликати користувач, також до /mcp unset context7 ``` -Примітки: + +`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, якими володіє Pi. Адаптери середовища виконання вирішують, які транспорти реально можна виконувати. + -- `/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. -- Адаптери runtime вирішують, які транспорти реально можна виконати. +## Оновлення plugin-ів -## Оновлення плагінів - -`/plugins` дозволяє операторам перевіряти виявлені плагіни й перемикати стан увімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Типово вимкнено; увімкніть через `commands.plugins: true`. +`/plugins` дає операторам змогу перевіряти виявлені plugin-и та перемикати їх увімкнення в конфігурації. Для сценаріїв лише читання можна використовувати `/plugin` як псевдонім. За замовчуванням вимкнено; увімкніть через `commands.plugins: true`. Приклади: @@ -362,37 +407,44 @@ Skills, які може викликати користувач, також до /plugins disable context7 ``` -Примітки: - -- `/plugins list` і `/plugins show` використовують реальне виявлення плагінів відносно поточного робочого простору плюс конфігурації на диску. -- `/plugins enable|disable` оновлює лише конфігурацію плагінів; це не встановлює і не видаляє плагіни. + +- `/plugins list` і `/plugins show` використовують реальне виявлення plugin-ів у поточному робочому просторі разом із конфігурацією на диску. +- `/plugins enable|disable` оновлює лише конфігурацію plugin-ів; воно не встановлює й не видаляє plugin-и. - Після змін `enable/disable` перезапустіть gateway, щоб застосувати їх. + ## Нотатки щодо поверхонь -- **Текстові команди** працюють у звичайній чат-сесії (DM спільно використовують `main`, групи мають власну сесію). -- **Нативні команди** використовують ізольовані сесії: - - Discord: `agent::discord:slash:` - - Slack: `agent::slack:slash:` (префікс можна налаштувати через `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (націлюється на чат-сесію через `CommandTargetSessionKey`) -- **`/stop`** націлюється на активну чат-сесію, щоб можна було перервати поточний запуск. -- **Slack:** `channels.slack.slashCommand` усе ще підтримується для однієї команди стилю `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити по одній слеш-команді Slack для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. - - Виняток для нативних команд Slack: реєструйте `/agentstatus` (а не `/status`), оскільки Slack резервує `/status`. Текстова `/status` у повідомленнях Slack усе ще працює. + + + - **Текстові команди** виконуються у звичайній сесії чату (приватні повідомлення спільно використовують `main`, групи мають власну сесію). + - **Нативні команди** використовують ізольовані сесії: + - Discord: `agent::discord:slash:` + - Slack: `agent::slack:slash:` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`) + - Telegram: `telegram:slash:` (націлюється на сесію чату через `CommandTargetSessionKey`) + - **`/stop`** націлюється на активну сесію чату, щоб можна було перервати поточний запуск. + + + `channels.slack.slashCommand` усе ще підтримується для однієї команди у стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну слеш-команду Slack для кожної вбудованої команди (з тими самими назвами, що й у `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. + + Виняток для нативних команд Slack: реєструйте `/agentstatus` (а не `/status`), оскільки Slack резервує `/status`. Текстова команда `/status` у повідомленнях Slack усе одно працює. + + + ## Побічні запитання BTW -`/btw` — це швидке **побічне запитання** про поточну сесію. +`/btw` — це швидке **побічне запитання** щодо поточної сесії. На відміну від звичайного чату: - воно використовує поточну сесію як фоновий контекст, -- виконується як окремий **одноразовий** виклик без інструментів, +- виконується як окремий одноразовий виклик **без інструментів**, - не змінює майбутній контекст сесії, -- не записується в історію транскрипту, -- доставляється як живий побічний результат замість звичайного повідомлення помічника. +- не записується в історію transcript, +- доставляється як живий побічний результат, а не як звичайне повідомлення асистента. -Це робить `/btw` корисним, коли вам потрібне тимчасове уточнення, поки основне -завдання триває. +Це робить `/btw` корисним, коли вам потрібне тимчасове уточнення, поки основне завдання триває. Приклад: @@ -400,11 +452,10 @@ Skills, які може викликати користувач, також до /btw what are we doing right now? ``` -Див. [BTW Side Questions](/uk/tools/btw) для повної поведінки й деталей UX -клієнта. +Див. [BTW Side Questions](/uk/tools/btw) для повного опису поведінки та деталей UX клієнта. ## Пов’язане +- [Створення skill-ів](/uk/tools/creating-skills) - [Skills](/uk/tools/skills) - [Конфігурація Skills](/uk/tools/skills-config) -- [Створення Skills](/uk/tools/creating-skills)