diff --git a/docs/uk/cli/config.md b/docs/uk/cli/config.md index 0538c76de..c9635956a 100644 --- a/docs/uk/cli/config.md +++ b/docs/uk/cli/config.md @@ -2,26 +2,26 @@ read_when: - Ви хочете читати або редагувати конфігурацію неінтерактивно sidebarTitle: Config -summary: Довідка CLI для `openclaw config` (get/set/patch/unset/file/schema/validate) +summary: Довідник CLI для `openclaw config` (get/set/patch/unset/file/schema/validate) title: Конфігурація x-i18n: - generated_at: "2026-04-29T21:05:31Z" + generated_at: "2026-05-03T17:11:54Z" model: gpt-5.5 provider: openai - source_hash: f1f55c4b932d469cb9112d9f55b66f0ff88dbe066250651df7a0a753060a223d + source_hash: 7be6a2ff8474fe78deb1d32dd822a4cf8a2b420dfb45306be5d7c5a1d54f0b4d source_path: cli/config.md workflow: 16 --- -Помічники конфігурації для неінтерактивних правок в `openclaw.json`: отримуйте/встановлюйте/застосовуйте patch/скидайте/виводьте файл/схему/перевіряйте значення за шляхом і друкуйте активний файл конфігурації. Запустіть без підкоманди, щоб відкрити майстер налаштування (те саме, що `openclaw configure`). +Помічники конфігурації для неінтерактивних змін у `openclaw.json`: отримуйте/задавайте/патчте/скасовуйте/виводьте файл/схему/перевіряйте значення за шляхом і друкуйте активний файл конфігурації. Запустіть без підкоманди, щоб відкрити майстер налаштування (те саме, що `openclaw configure`). ## Кореневі опції - Повторюваний фільтр розділів керованого налаштування, коли ви запускаєте `openclaw config` без підкоманди. + Повторюваний фільтр секції керованого налаштування, коли ви запускаєте `openclaw config` без підкоманди. -Підтримувані керовані розділи: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`. +Підтримувані керовані секції: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`. ## Приклади @@ -47,20 +47,20 @@ openclaw config validate --json ### `config schema` -Друкує згенеровану схему JSON для `openclaw.json` у stdout як JSON. +Друкує згенеровану JSON-схему для `openclaw.json` у stdout як JSON. - - - Поточну кореневу схему конфігурації, а також кореневе рядкове поле `$schema` для інструментів редактора. + + - Поточна коренева схема конфігурації, а також кореневе рядкове поле `$schema` для інструментів редактора. - Метадані документації полів `title` і `description`, які використовує Control UI. - - Вкладені об’єкти, wildcard-вузли (`*`) і вузли елементів масиву (`[]`) успадковують ті самі метадані `title` / `description`, коли існує відповідна документація поля. + - Вкладені об'єкти, вузли з wildcard (`*`) і елементи масиву (`[]`) успадковують ті самі метадані `title` / `description`, коли існує відповідна документація поля. - Гілки `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані документації, коли існує відповідна документація поля. - - Best-effort метадані схеми живих plugin + каналів, коли можна завантажити маніфести середовища виконання. - - Чисту резервну схему навіть тоді, коли поточна конфігурація недійсна. + - Найкращі доступні живі метадані схеми Plugin + каналу, коли runtime-маніфести можна завантажити. + - Чиста резервна схема навіть тоді, коли поточна конфігурація недійсна. - - `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові межі), відповідними метаданими UI-підказки й короткими описами безпосередніх дочірніх елементів. Використовуйте це для деталізації за шляхом у Control UI або власних клієнтах. + + `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі), відповідними метаданими підказок UI та зведеннями безпосередніх дочірніх елементів. Використовуйте це для деталізації в межах шляху в Control UI або власних клієнтах. @@ -83,7 +83,7 @@ openclaw config get agents.defaults.workspace openclaw config get agents.list[0].id ``` -Використовуйте індекс списку агентів, щоб націлитися на конкретного агента: +Використовуйте індекс списку агентів, щоб вибрати конкретного агента: ```bash openclaw config get agents.list @@ -92,7 +92,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name" ## Значення -Значення розбираються як JSON5, коли це можливо; інакше вони обробляються як рядки. Використовуйте `--strict-json`, щоб вимагати розбору JSON5. `--json` залишається підтримуваним як застарілий alias. +Значення розбираються як JSON5, коли це можливо; інакше вони розглядаються як рядки. Використовуйте `--strict-json`, щоб вимагати розбору JSON5. `--json` залишається підтримуваним як застарілий псевдонім. ```bash openclaw config set agents.defaults.heartbeat.every "0m" @@ -100,13 +100,13 @@ openclaw config set gateway.port 19001 --strict-json openclaw config set channels.whatsapp.groups '["*"]' --strict-json ``` -`config get --json` друкує необроблене значення як JSON замість тексту, відформатованого для термінала. +`config get --json` друкує сире значення як JSON замість відформатованого для термінала тексту. -Присвоєння об’єкта за замовчуванням замінює цільовий шлях. Захищені шляхи map/list, які зазвичай містять додані користувачем записи, як-от `agents.defaults.models`, `models.providers`, `models.providers..models`, `plugins.entries` і `auth.profiles`, відмовляються від замін, які вилучили б наявні записи, якщо ви не передасте `--replace`. +Присвоєння об'єкта типово замінює цільовий шлях. Захищені шляхи мап/списків, які часто містять додані користувачем записи, як-от `agents.defaults.models`, `models.providers`, `models.providers..models`, `plugins.entries` і `auth.profiles`, відхиляють заміни, які прибрали б наявні записи, якщо не передати `--replace`. -Використовуйте `--merge`, коли додаєте записи до таких map: +Використовуйте `--merge`, коли додаєте записи до таких мап: ```bash openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge @@ -120,12 +120,12 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll `openclaw config set` підтримує чотири стилі присвоєння: - + ```bash openclaw config set ``` - + ```bash openclaw config set channels.discord.token \ --ref-provider default \ @@ -133,8 +133,8 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll --ref-id DISCORD_BOT_TOKEN ``` - - Режим побудовника provider націлюється лише на шляхи `secrets.providers.`: + + Режим конструктора провайдера націлений лише на шляхи `secrets.providers.`: ```bash openclaw config set secrets.providers.vault \ @@ -146,7 +146,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll ``` - + ```bash openclaw config set --batch-json '[ { @@ -168,28 +168,28 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll -Присвоєння SecretRef відхиляються на непідтримуваних runtime-mutable поверхнях (наприклад `hooks.token`, `commands.ownerDisplaySecret`, токени Webhook прив’язки потоків Discord і JSON облікових даних WhatsApp). Див. [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Присвоєння SecretRef відхиляються на непідтримуваних runtime-змінюваних поверхнях (наприклад, `hooks.token`, `commands.ownerDisplaySecret`, токени webhook прив'язки потоків Discord і JSON облікових даних WhatsApp). Див. [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Пакетний розбір завжди використовує пакетне payload (`--batch-json`/`--batch-file`) як джерело істини. `--strict-json` / `--json` не змінюють поведінку пакетного розбору. +Пакетний розбір завжди використовує пакетне навантаження (`--batch-json`/`--batch-file`) як джерело істини. `--strict-json` / `--json` не змінюють поведінку пакетного розбору. ## `config patch` -Використовуйте `config patch`, коли хочете вставити або передати через pipe patch у формі конфігурації замість запуску багатьох команд `config set` на основі шляхів. Вхідні дані — це об’єкт JSON5. Об’єкти рекурсивно об’єднуються, масиви й скалярні значення замінюють цільове значення, а `null` видаляє цільовий шлях. +Використовуйте `config patch`, коли хочете вставити або передати через канал патч у формі конфігурації замість запуску багатьох команд `config set` на основі шляхів. Вхідні дані є об'єктом JSON5. Об'єкти рекурсивно об'єднуються, масиви та скалярні значення замінюють цільове значення, а `null` видаляє цільовий шлях. ```bash openclaw config patch --file ./openclaw.patch.json5 --dry-run openclaw config patch --file ./openclaw.patch.json5 ``` -Також можна передати patch через stdin, що корисно для скриптів віддаленого налаштування: +Також можна передати патч через stdin, що корисно для скриптів віддаленого налаштування: ```bash ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5 ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5 ``` -Приклад patch: +Приклад патча: ```json5 { @@ -221,15 +221,15 @@ ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5 } ``` -Використовуйте `--replace-path `, коли один об’єкт або масив має стати точно наданим значенням замість рекурсивного застосування patch: +Використовуйте `--replace-path `, коли один об'єкт або масив має стати точно наданим значенням, а не рекурсивно патчитися: ```bash openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels' ``` -`--dry-run` запускає перевірки схеми та розв’язуваності SecretRef без запису. Exec-backed SecretRefs за замовчуванням пропускаються під час dry-run; додайте `--allow-exec`, коли ви навмисно хочете, щоб dry-run виконував команди provider. +`--dry-run` запускає перевірки схеми та розв'язуваності SecretRef без запису. SecretRef на основі exec типово пропускаються під час dry-run; додайте `--allow-exec`, коли навмисно хочете, щоб dry-run виконував команди провайдера. -Режим шляху/значення JSON залишається підтримуваним як для SecretRefs, так і для providers: +Режим JSON-шляху/значення залишається підтримуваним як для SecretRef, так і для провайдерів: ```bash openclaw config set channels.discord.token \ @@ -241,12 +241,12 @@ openclaw config set secrets.providers.vaultfile \ --strict-json ``` -## Прапорці побудовника provider +## Прапорці конструктора провайдера -Цілі побудовника provider мають використовувати `secrets.providers.` як шлях. +Цілі конструктора провайдера мають використовувати `secrets.providers.` як шлях. - + - `--provider-source ` - `--provider-timeout-ms ` (`file`, `exec`) @@ -256,14 +256,14 @@ openclaw config set secrets.providers.vaultfile \ - - `--provider-path ` (обов’язковий) + - `--provider-path ` (обов'язково) - `--provider-mode ` - `--provider-max-bytes ` - `--provider-allow-insecure-path` - - `--provider-command ` (обов’язковий) + - `--provider-command ` (обов'язково) - `--provider-arg ` (повторюваний) - `--provider-no-output-timeout-ms ` - `--provider-max-output-bytes ` @@ -277,7 +277,7 @@ openclaw config set secrets.providers.vaultfile \ -Приклад захищеного exec provider: +Приклад посиленого exec-провайдера: ```bash openclaw config set secrets.providers.vault \ @@ -291,9 +291,9 @@ openclaw config set secrets.providers.vault \ --provider-timeout-ms 5000 ``` -## Dry run +## Пробний запуск -Використовуйте `--dry-run`, щоб перевірити зміни без запису `openclaw.json`. +Використовуйте `--dry-run`, щоб перевірити зміни без запису в `openclaw.json`. ```bash openclaw config set channels.discord.token \ @@ -318,26 +318,26 @@ openclaw config set channels.discord.token \ ``` - - - Режим побудовника: запускає перевірки розв’язуваності SecretRef для змінених refs/providers. - - Режим JSON (`--strict-json`, `--json` або пакетний режим): запускає перевірку схеми та перевірки розв’язуваності SecretRef. - - Перевірка політики також виконується для відомих непідтримуваних цільових поверхонь SecretRef. - - Перевірки політики оцінюють повну конфігурацію після зміни, тому записи батьківських об’єктів (наприклад встановлення `hooks` як об’єкта) не можуть обійти перевірку непідтримуваних поверхонь. - - Перевірки exec SecretRef за замовчуванням пропускаються під час dry-run, щоб уникнути побічних ефектів команд. - - Використовуйте `--allow-exec` з `--dry-run`, щоб явно ввімкнути перевірки exec SecretRef (це може виконати команди provider). - - `--allow-exec` призначений лише для dry-run і завершується помилкою, якщо використаний без `--dry-run`. + + - Режим конструктора: запускає перевірки розв'язуваності SecretRef для змінених refs/провайдерів. + - Режим JSON (`--strict-json`, `--json` або пакетний режим): запускає перевірку схеми, а також перевірки розв'язуваності SecretRef. + - Перевірка політик також виконується для відомих непідтримуваних цільових поверхонь SecretRef. + - Перевірки політик оцінюють повну конфігурацію після зміни, тож записи батьківських об'єктів (наприклад, встановлення `hooks` як об'єкта) не можуть обійти перевірку непідтримуваної поверхні. + - Перевірки exec SecretRef типово пропускаються під час dry-run, щоб уникнути побічних ефектів команд. + - Використовуйте `--allow-exec` із `--dry-run`, щоб явно ввімкнути перевірки exec SecretRef (це може виконувати команди провайдера). + - `--allow-exec` працює лише для dry-run і завершується помилкою, якщо використаний без `--dry-run`. - + `--dry-run --json` друкує машинозчитуваний звіт: - `ok`: чи пройшов dry-run - `operations`: кількість оцінених присвоєнь - - `checks`: чи виконувалися перевірки схеми/розв’язуваності - - `checks.resolvabilityComplete`: чи перевірки розв’язуваності виконалися до завершення (false, коли exec refs пропущені) - - `refsChecked`: кількість refs, фактично розв’язаних під час dry-run - - `skippedExecRefs`: кількість exec refs, пропущених через те, що `--allow-exec` не було встановлено - - `errors`: структуровані помилки схеми/розв’язуваності, коли `ok=false` + - `checks`: чи виконувалися перевірки схеми/розв'язуваності + - `checks.resolvabilityComplete`: чи перевірки розв'язуваності завершилися повністю (false, коли exec refs пропущено) + - `refsChecked`: кількість refs, фактично розв'язаних під час dry-run + - `skippedExecRefs`: кількість exec refs, пропущених через те, що `--allow-exec` не встановлено + - `errors`: структуровані помилки схеми/розв'язуваності, коли `ok=false` @@ -413,21 +413,21 @@ openclaw config set channels.discord.token \ - - `config schema validation failed`: форма вашої конфігурації після зміни недійсна; виправте шлях/значення або форму об’єкта provider/ref. - - `Config policy validation failed: unsupported SecretRef usage`: перемістіть ці облікові дані назад до введення відкритим текстом/рядком і використовуйте SecretRefs лише на підтримуваних поверхнях. - - `SecretRef assignment(s) could not be resolved`: указаний provider/ref наразі неможливо розв’язати (відсутня змінна середовища, недійсний вказівник на файл, помилка exec-провайдера або невідповідність provider/source). - - `Dry run note: skipped exec SecretRef resolvability check(s)`: dry-run пропустив exec-посилання; повторіть запуск із `--allow-exec`, якщо вам потрібна перевірка розв’язності exec. - - Для пакетного режиму виправте записи з помилками й повторно запустіть `--dry-run` перед записом. + - `config schema validation failed`: форма конфігурації після зміни недійсна; виправте шлях/значення або форму об’єкта провайдера/ref. + - `Config policy validation failed: unsupported SecretRef usage`: перемістіть ці облікові дані назад у введення відкритим текстом/рядком і використовуйте SecretRefs лише на підтримуваних поверхнях. + - `SecretRef assignment(s) could not be resolved`: посиланий provider/ref наразі неможливо розв’язати (відсутня змінна середовища, недійсний вказівник на файл, помилка exec-провайдера або невідповідність provider/source). + - `Dry run note: skipped exec SecretRef resolvability check(s)`: dry-run пропустив exec refs; запустіть повторно з `--allow-exec`, якщо потрібна перевірка розв’язності exec. + - Для пакетного режиму виправте проблемні записи й повторно запустіть `--dry-run` перед записом. ## Безпека запису -`openclaw config set` та інші засоби запису конфігурації, що належать OpenClaw, перевіряють повну конфігурацію після зміни перед її збереженням на диск. Якщо нове навантаження не проходить перевірку схеми або схоже на руйнівне перезаписування, активна конфігурація лишається без змін, а відхилене навантаження зберігається поруч як `openclaw.json.rejected.*`. +`openclaw config set` та інші засоби запису конфігурації, що належать OpenClaw, перевіряють повну конфігурацію після зміни перед збереженням на диск. Якщо новий вміст не проходить перевірку схеми або виглядає як руйнівне перезаписування, активна конфігурація залишається без змін, а відхилений вміст зберігається поруч із нею як `openclaw.json.rejected.*`. -Активний шлях конфігурації має бути звичайним файлом. Макети з `openclaw.json` як символьним посиланням не підтримуються для запису; натомість використовуйте `OPENCLAW_CONFIG_PATH`, щоб указати безпосередньо на справжній файл. +Активний шлях конфігурації має бути звичайним файлом. Схеми з `openclaw.json` через symlink не підтримуються для запису; натомість використовуйте `OPENCLAW_CONFIG_PATH`, щоб напряму вказати на справжній файл. Для невеликих змін надавайте перевагу записам через CLI: @@ -438,7 +438,7 @@ openclaw config set gateway.reload.mode hybrid openclaw config validate ``` -Якщо запис відхилено, перевірте збережене навантаження й виправте повну форму конфігурації: +Якщо запис відхилено, перевірте збережений вміст і виправте повну форму конфігурації: ```bash CONFIG="$(openclaw config file)" @@ -446,19 +446,19 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head openclaw config validate ``` -Прямі зміни через редактор усе ще дозволені, але запущений Gateway вважає їх ненадійними, доки вони не пройдуть перевірку. Недійсні прямі зміни можна відновити з останньої справної резервної копії під час запуску або гарячого перезавантаження. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config). +Прямі записи через редактор усе ще дозволені, але запущений Gateway вважає їх ненадійними, доки вони не пройдуть перевірку. Недійсні прямі зміни призводять до помилки запуску або пропускаються під час hot reload; Gateway не перезаписує `openclaw.json`. Запустіть `openclaw doctor --fix`, щоб відновити конфігурацію з префіксом/перезаписану конфігурацію або повернути останню відому справну копію. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config). -Відновлення всього файла призначене для глобально пошкодженої конфігурації, як-от помилки розбору, помилки схеми на кореневому рівні, помилки міграції застарілої конфігурації або змішані помилки Plugin і кореня. Якщо перевірка не проходить лише під `plugins.entries....`, OpenClaw залишає активний `openclaw.json` на місці й повідомляє про локальну для Plugin проблему замість відновлення `.last-good`. Це запобігає відкату непов’язаних налаштувань користувача, таких як моделі, провайдери, профілі автентифікації, канали, експозиція gateway, інструменти, пам’ять, браузер або конфігурація cron, через зміни схеми Plugin чи розбіжність `minHostVersion`. +Відновлення всього файлу зарезервоване для ремонту через doctor. Зміни схем Plugin або невідповідність `minHostVersion` залишаються помітними замість відкату непов’язаних користувацьких налаштувань, як-от моделей, провайдерів, профілів автентифікації, каналів, доступності Gateway, інструментів, пам’яті, браузера або конфігурації cron. ## Підкоманди -- `config file`: вивести шлях до активного файла конфігурації (розв’язаний із `OPENCLAW_CONFIG_PATH` або типового розташування). Шлях має вказувати на звичайний файл, а не на символьне посилання. +- `config file`: Вивести шлях до активного файлу конфігурації (визначений з `OPENCLAW_CONFIG_PATH` або типового розташування). Шлях має вказувати на звичайний файл, а не на символічне посилання. -Перезапустіть gateway після змін. +Перезапустіть Gateway після редагувань. ## Перевірка -Перевірте поточну конфігурацію за активною схемою без запуску gateway. +Перевірте поточну конфігурацію за активною схемою без запуску Gateway. ```bash openclaw config validate @@ -468,7 +468,7 @@ openclaw config validate --json Після успішного проходження `openclaw config validate` можна використати локальний TUI, щоб вбудований агент порівняв активну конфігурацію з документацією, поки ви перевіряєте кожну зміну з того самого термінала: -Якщо перевірка вже завершується помилкою, почніть із `openclaw configure` або `openclaw doctor --fix`. `openclaw chat` не обходить захист від недійсної конфігурації. +Якщо перевірка вже завершується помилкою, почніть з `openclaw configure` або `openclaw doctor --fix`. `openclaw chat` не обходить захист від некоректної конфігурації. ```bash @@ -487,16 +487,16 @@ openclaw chat Типовий цикл виправлення: - + Попросіть агента порівняти вашу поточну конфігурацію з відповідною сторінкою документації та запропонувати найменше виправлення. - - Застосуйте цільові зміни за допомогою `openclaw config set` або `openclaw configure`. + + Застосуйте цільові редагування за допомогою `openclaw config set` або `openclaw configure`. - + Повторно запускайте `openclaw config validate` після кожної зміни. - + Якщо перевірка проходить, але середовище виконання все ще несправне, запустіть `openclaw doctor` або `openclaw doctor --fix`, щоб отримати допомогу з міграцією та виправленням. diff --git a/docs/uk/cli/plugins.md b/docs/uk/cli/plugins.md index 3bcee5f7d..af418a929 100644 --- a/docs/uk/cli/plugins.md +++ b/docs/uk/cli/plugins.md @@ -1,29 +1,29 @@ --- read_when: - - Ви хочете встановити або керувати plugins Gateway чи сумісними пакетами - - Ви хочете діагностувати збої завантаження Plugin + - Ви хочете встановити або керувати плагінами Gateway чи сумісними пакетами + - Ви хочете налагодити помилки завантаження Plugin sidebarTitle: Plugins -summary: Довідка CLI для `openclaw plugins` (`list`, `install`, `marketplace`, `uninstall`, `enable`/`disable`, `doctor`) -title: Плагіни +summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) +title: Plugins x-i18n: - generated_at: "2026-05-02T21:59:35Z" + generated_at: "2026-05-03T17:12:13Z" model: gpt-5.5 provider: openai - source_hash: 3b077ab0739e2453ccba434aa3b02b1d441bab792b7b131216221a8048d551cd + source_hash: f6ae613e39535ea20f9cf3dd451f110ae1b14de4586bdbe3d55d06d8e7cfd2cf source_path: cli/plugins.md workflow: 16 --- -Керуйте Gateway Plugin, пакетами hook і сумісними bundles. +Керуйте Gateway plugins, пакетами хуків і сумісними bundles. - Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення неполадок plugins. + Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення несправностей plugins. - Короткі приклади для встановлення, перегляду списку, оновлення, видалення та публікації. + Швидкі приклади встановлення, перегляду списку, оновлення, видалення та публікації. - + Модель сумісності bundle. @@ -62,16 +62,16 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Для розслідування повільного встановлення, інспектування, видалення або оновлення registry запустіть -команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує тривалість фаз -до stderr і зберігає JSON-вивід придатним для парсингу. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace). +Для дослідження повільного встановлення, перевірки, видалення або оновлення реєстру запустіть +команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує таймінги фаз +у stderr і залишає JSON-вивід придатним для розбору. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace). -Вбудовані plugins постачаються з OpenClaw. Деякі ввімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний plugin); інші потребують `plugins enable`. +Вбудовані plugins постачаються з OpenClaw. Деякі ввімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані мовленнєві провайдери та вбудований browser plugin); інші потребують `plugins enable`. -Нативні OpenClaw plugins мають постачати `openclaw.plugin.json` із вбудованою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні bundles натомість використовують власні маніфести bundle. +Нативні OpenClaw plugins мають постачати `openclaw.plugin.json` з inline JSON Schema (`configSchema`, навіть якщо порожньою). Сумісні bundles натомість використовують власні маніфести bundle. -`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info також показує підтип bundle (`codex`, `claude` або `cursor`) і виявлені можливості bundle. +`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info також показує підтип bundle (`codex`, `claude` або `cursor`) плюс виявлені можливості bundle. ### Встановлення @@ -93,7 +93,7 @@ openclaw plugins install --marketplace https://github.com// -Голі назви пакетів встановлюються з npm за замовчуванням під час перехідного запуску. Використовуйте `clawhub:` для ClawHub. Ставтеся до встановлення plugins як до запуску коду. Віддавайте перевагу закріпленим версіям. +Під час launch cutover голі назви пакетів за замовчуванням встановлюються з npm. Використовуйте `clawhub:` для ClawHub. Ставтеся до встановлення plugins як до запуску коду. Надавайте перевагу pinned-версіям. `plugins search` запитує ClawHub щодо доступних для встановлення пакетів plugin і виводить @@ -101,61 +101,61 @@ openclaw plugins install --marketplace https://github.com// -ClawHub є основною поверхнею розповсюдження та пошуку для більшості plugins. Npm -залишається підтримуваним запасним і прямим шляхом встановлення. Пакети plugin +ClawHub є основною поверхнею розповсюдження й пошуку для більшості plugins. Npm +залишається підтримуваним резервним варіантом і шляхом прямого встановлення. Пакети plugins `@openclaw/*`, що належать OpenClaw, знову публікуються в npm; див. поточний список -на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) або в -[інвентарі plugin](/uk/plugins/plugin-inventory). Стабільні встановлення використовують `latest`. -Встановлення й оновлення beta-каналу віддають перевагу npm dist-tag `beta`, коли цей тег +на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) або +[інвентар Plugin](/uk/plugins/plugin-inventory). Стабільні встановлення використовують `latest`. +Встановлення та оновлення beta-каналу надають перевагу npm dist-tag `beta`, коли цей tag доступний, а потім повертаються до `latest`. - - Якщо ваш розділ `plugins` підтримується однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записують зміни в цей включений файл і залишають `openclaw.json` без змін. Кореневі включення, масиви включень і включення з сусідніми перевизначеннями завершуються закрито замість сплющення. Див. [Включення конфігурації](/uk/gateway/configuration) для підтримуваних форм. + + Якщо ваш розділ `plugins` підкріплений однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записують у цей included file і залишають `openclaw.json` без змін. Root includes, include arrays і includes із sibling overrides завершуються закрито, замість flattening. Див. [Config includes](/uk/gateway/configuration) для підтримуваних форм. - Якщо конфігурація недійсна під час встановлення, `plugins install` зазвичай завершується закрито й повідомляє, що спочатку потрібно запустити `openclaw doctor --fix`. Під час запуску Gateway недійсна конфігурація одного plugin ізолюється до цього plugin, щоб інші канали та plugins могли продовжувати роботу; `openclaw doctor --fix` може помістити недійсний запис plugin у карантин. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення для вбудованих plugins, які явно погоджуються на `openclaw.install.allowInvalidConfigRecovery`. + Якщо під час встановлення конфігурація некоректна, `plugins install` зазвичай завершується закрито й повідомляє, що спершу потрібно запустити `openclaw doctor --fix`. Під час запуску Gateway і hot reload некоректна конфігурація plugin завершується закрито, як і будь-яка інша некоректна конфігурація; `openclaw doctor --fix` може ізолювати некоректний запис plugin. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення bundled-plugin для plugins, які явно opt into `openclaw.install.allowInvalidConfigRecovery`. - - `--force` повторно використовує наявну ціль встановлення та перезаписує вже встановлений plugin або пакет hook на місці. Використовуйте його, коли ви навмисно повторно встановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакта npm. Для звичайних оновлень уже відстежуваного npm plugin віддавайте перевагу `openclaw plugins update `. + + `--force` повторно використовує наявну ціль встановлення й перезаписує вже встановлений plugin або пакет хуків на місці. Використовуйте це, коли навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або npm-артефакта. Для звичайних оновлень уже відстежуваного npm plugin надавайте перевагу `openclaw plugins update `. - Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється та спрямовує вас до `plugins update ` для звичайного оновлення або до `plugins install --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела. + Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється й спрямовує вас до `plugins update ` для звичайного оновлення або до `plugins install --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела. - `--pin` застосовується лише до встановлень npm. Він не підтримується з встановленнями `git:`; використовуйте явний git ref, наприклад `git:github.com/acme/plugin@v1.2.3`, коли вам потрібне закріплене джерело. Він не підтримується з `--marketplace`, оскільки встановлення marketplace зберігають метадані джерела marketplace замість специфікації npm. + `--pin` застосовується лише до npm-встановлень. Він не підтримується з `git:` installs; використовуйте явний git ref, наприклад `git:github.com/acme/plugin@v1.2.3`, коли вам потрібне pinned-джерело. Він не підтримується з `--marketplace`, оскільки marketplace installs зберігають метадані джерела marketplace замість npm spec. - `--dangerously-force-unsafe-install` — це аварійний параметр для хибних спрацьовувань у вбудованому сканері небезпечного коду. Він дозволяє встановленню продовжитися, навіть коли вбудований сканер повідомляє про знахідки `critical`, але **не** обходить блокування політики hook `before_install` plugin і **не** обходить помилки сканування. + `--dangerously-force-unsafe-install` — це аварійна опція для хибнопозитивних спрацьовувань у вбудованому сканері небезпечного коду. Вона дозволяє встановленню продовжитися, навіть коли вбудований сканер повідомляє про знахідки `critical`, але вона **не** обходить policy blocks хуків `before_install` plugin і **не** обходить збої сканування. - Цей прапорець CLI застосовується до потоків встановлення/оновлення plugin. Встановлення залежностей skill, підтримувані Gateway, використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення skill з ClawHub. + Цей CLI-прапорець застосовується до потоків install/update plugin. Встановлення залежностей skill за підтримки Gateway використовують відповідний request override `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення skill з ClawHub. - Якщо plugin, який ви опублікували на ClawHub, заблоковано скануванням registry, скористайтеся кроками для видавця в [ClawHub](/uk/tools/clawhub). + Якщо plugin, який ви опублікували на ClawHub, заблоковано registry scan, скористайтеся кроками для видавців у [ClawHub](/uk/tools/clawhub). - - `plugins install` також є поверхнею встановлення для пакетів hook, які відкривають `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої видимості hook і ввімкнення окремих hook, а не для встановлення пакетів. + + `plugins install` також є поверхнею встановлення для пакетів хуків, які expose `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої видимості хуків і ввімкнення окремих хуків, а не для встановлення пакетів. - Специфікації npm є **лише registry** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Встановлення залежностей виконуються локально в проєкті з `--ignore-scripts` задля безпеки, навіть якщо ваша оболонка має глобальні налаштування встановлення npm. + Npm specs є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Git/URL/file specs і semver ranges відхиляються. Встановлення залежностей виконуються project-local з `--ignore-scripts` для безпеки, навіть коли ваша shell має глобальні налаштування npm install. - Використовуйте `npm:`, коли хочете зробити розв’язання npm явним. Голі специфікації пакетів також встановлюються безпосередньо з npm під час перехідного запуску. + Використовуйте `npm:`, коли хочете зробити npm resolution явним. Під час launch cutover голі package specs також встановлюються напряму з npm. - Голі специфікації та `@latest` залишаються на стабільному треку. Якщо npm розв’язує будь-яку з них у prerelease, OpenClaw зупиняється й просить вас явно погодитися за допомогою prerelease-тега, наприклад `@beta`/`@rc`, або точної prerelease-версії, наприклад `@1.2.3-beta.4`. + Bare specs і `@latest` залишаються на stable track. Якщо npm resolve будь-який із них до prerelease, OpenClaw зупиняється й просить вас явно opt in з prerelease tag, наприклад `@beta`/`@rc`, або з точною prerelease-версією, наприклад `@1.2.3-beta.4`. - Якщо гола специфікація встановлення збігається з офіційним id plugin (наприклад `diffs`), OpenClaw встановлює запис каталогу безпосередньо. Щоб встановити пакет npm з такою самою назвою, використовуйте явну scoped-специфікацію (наприклад `@scope/diffs`). + Якщо bare install spec збігається з офіційним id plugin (наприклад, `diffs`), OpenClaw встановлює catalog entry напряму. Щоб встановити npm package з такою самою назвою, використовуйте явний scoped spec (наприклад, `@scope/diffs`). - Використовуйте `git:` для встановлення безпосередньо з git-репозиторію. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні URL клонування `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@` або `#`, щоб перед встановленням перейти на гілку, тег або commit. + Використовуйте `git:` для встановлення напряму з git repository. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні clone URLs `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@` або `#`, щоб перед встановленням перейти на branch, tag або commit. - Git-встановлення клонують у тимчасову директорію, переходять на запитаний ref, якщо він є, а потім використовують звичайний інсталятор директорії plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення менеджера пакетів і записи встановлення поводяться як npm-встановлення. Записані git-встановлення містять вихідний URL/ref і розв’язаний commit, щоб `openclaw plugins update` міг пізніше повторно розв’язати джерело. + Git installs клонують у тимчасовий каталог, переходять на запитаний ref, якщо він присутній, а потім використовують звичайний installer каталогу plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення package-manager і install records поводяться як npm installs. Записані git installs містять source URL/ref плюс resolved commit, щоб `openclaw plugins update` міг пізніше повторно resolve джерело. - Після встановлення з git використовуйте `openclaw plugins inspect --runtime --json`, щоб перевірити runtime-реєстрації, як-от методи gateway і команди CLI. Якщо plugin зареєстрував корінь CLI через `api.registerCli`, виконайте цю команду безпосередньо через кореневий CLI OpenClaw, наприклад `openclaw demo-plugin ping`. + Після встановлення з git використовуйте `openclaw plugins inspect --runtime --json`, щоб перевірити runtime registrations, як-от gateway methods і CLI commands. Якщо plugin зареєстрував CLI root через `api.registerCli`, виконайте цю команду напряму через root CLI OpenClaw, наприклад `openclaw demo-plugin ping`. - Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних OpenClaw plugin мають містити дійсний `openclaw.plugin.json` у витягнутому корені plugin; архіви, які містять лише `package.json`, відхиляються до того, як OpenClaw запише записи встановлення. + Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних OpenClaw plugin мають містити дійсний `openclaw.plugin.json` у витягнутому root plugin; архіви, які містять лише `package.json`, відхиляються до того, як OpenClaw запише install records. Встановлення Claude marketplace також підтримуються. @@ -169,32 +169,32 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Голі npm-безпечні специфікації plugin встановлюються з npm за замовчуванням під час перехідного запуску: +Під час launch cutover голі npm-safe plugin specs за замовчуванням встановлюються з npm: ```bash openclaw plugins install openclaw-codex-app-server ``` -Використовуйте `npm:`, щоб зробити розв’язання лише через npm явним: +Використовуйте `npm:`, щоб зробити npm-only resolution явним: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw перевіряє оголошену сумісність plugin API / мінімальну сумісність gateway перед встановленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версіонований npm-pack `.tgz`, перевіряє заголовок digest ClawHub і digest артефакта, а потім встановлює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack усе ще встановлюються через застарілий шлях перевірки архіву пакета. Записані встановлення зберігають свої метадані джерела ClawHub, тип артефакта, цілісність npm, shasum npm, назву tarball і факти digest ClawPack для подальших оновлень. -Неверсіоновані встановлення ClawHub зберігають неверсіоновану записану специфікацію, щоб `openclaw plugins update` міг відстежувати новіші випуски ClawHub; явні селектори версії або тегу, такі як `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються закріпленими на цьому селекторі. +OpenClaw перевіряє оголошений plugin API / мінімальну сумісність gateway перед встановленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує versioned npm-pack `.tgz`, перевіряє ClawHub digest header і artifact digest, а потім встановлює його через звичайний archive path. Старіші версії ClawHub без метаданих ClawPack досі встановлюються через legacy package archive verification path. Записані встановлення зберігають метадані джерела ClawHub, artifact kind, npm integrity, npm shasum, tarball name і факти ClawPack digest для подальших оновлень. +Неверсійовані встановлення ClawHub зберігають неверсійований recorded spec, щоб `openclaw plugins update` міг слідувати за новішими релізами ClawHub; явні селектори версії або tag, як-от `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються pinned до цього селектора. #### Скорочення marketplace -Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному кеші registry Claude за адресою `~/.claude/plugins/known_marketplaces.json`: +Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному registry cache Claude за адресою `~/.claude/plugins/known_marketplaces.json`: ```bash openclaw plugins marketplace list openclaw plugins install @ ``` -Використовуйте `--marketplace`, коли хочете передати джерело marketplace явно: +Використовуйте `--marketplace`, коли хочете явно передати marketplace source: ```bash openclaw plugins install --marketplace @@ -204,16 +204,16 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json` - - локальний корінь marketplace або шлях `marketplace.json` - - скорочення репозиторію GitHub, як-от `owner/repo` - - URL репозиторію GitHub, як-от `https://github.com/owner/repo` + + - назва відомого Marketplace Claude з `~/.claude/plugins/known_marketplaces.json` + - локальний корінь Marketplace або шлях `marketplace.json` + - скорочення репозиторію GitHub, наприклад `owner/repo` + - URL репозиторію GitHub, наприклад `https://github.com/owner/repo` - git URL - - Для віддалених marketplace, завантажених із GitHub або git, записи Plugin мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає джерела з відносними шляхами з цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела Plugin із віддалених маніфестів. + + Для віддалених Marketplace, завантажених із GitHub або git, записи Plugin мають залишатися всередині клонованого репозиторію Marketplace. OpenClaw приймає джерела з відносними шляхами з цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела Plugin з віддалених маніфестів. @@ -221,11 +221,11 @@ openclaw plugins install --marketplace ./my-marketplace - нативні Plugin OpenClaw (`openclaw.plugin.json`) - сумісні з Codex пакети (`.codex-plugin/plugin.json`) -- сумісні з Claude пакети (`.claude-plugin/plugin.json` або стандартну структуру компонентів Claude) +- сумісні з Claude пакети (`.claude-plugin/plugin.json` або типовий макет компонентів Claude) - сумісні з Cursor пакети (`.cursor-plugin/plugin.json`) -Сумісні пакети встановлюються у звичайний корінь Plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, command-skills Claude, стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` / оголошених у маніфесті `lspServers`, command-skills Cursor і сумісні каталоги hook Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не підключені до виконання під час роботи. +Сумісні пакети встановлюються у звичайний корінь Plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги hook Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не підключені до виконання під час роботи. ### Список @@ -241,50 +241,55 @@ openclaw plugins search --json ``` - Показувати лише ввімкнені Plugin. + Показати лише ввімкнені plugins. - Перемкнутися з табличного подання на рядки деталей для кожного Plugin із метаданими джерела/походження/версії/активації. + Перемкнутися з табличного подання на рядки деталей для кожного Plugin з метаданими джерела/походження/версії/активації. - Машиночитний інвентар, а також діагностика реєстру й стан встановлення залежностей пакета. + Машиночитний інвентар, а також діагностика реєстру й стан встановлення залежностей пакунків. -`plugins list` спершу читає збережений локальний реєстр Plugin, із резервним варіантом, виведеним лише з маніфестів, коли реєстр відсутній або недійсний. Це корисно, щоб перевірити, чи Plugin встановлений, увімкнений і видимий для планування холодного запуску, але це не live-зонд процесу Gateway, який уже працює. Після зміни коду Plugin, стану ввімкнення, політики hook або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати виконання нового коду `register(api)` або hook. Для віддалених/контейнерних розгортань перевірте, що перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку. +`plugins list` спершу читає збережений локальний реєстр Plugin, із резервним варіантом, похідним лише від маніфестів, коли реєстр відсутній або недійсний. Це корисно для перевірки, чи Plugin встановлено, увімкнено та видно для планування холодного запуску, але це не живий runtime-зонд уже запущеного процесу Gateway. Після зміни коду Plugin, увімкнення, політики hook або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або hook. Для віддалених/контейнерних розгортань перевірте, що ви перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку. -`plugins list --json` включає `dependencyStatus` кожного Plugin з `dependencies` і `optionalDependencies` у `package.json`. OpenClaw перевіряє, чи ці назви пакетів присутні вздовж звичайного для Plugin шляху пошуку Node `node_modules`; він не імпортує runtime-код Plugin, не запускає менеджер пакетів і не виправляє відсутні залежності. +`plugins list --json` включає `dependencyStatus` кожного Plugin з `package.json` +`dependencies` і `optionalDependencies`. OpenClaw перевіряє, чи наявні ці назви пакунків уздовж звичайного шляху пошуку Node `node_modules` для Plugin; він не імпортує runtime-код Plugin, не запускає менеджер пакунків і не виправляє відсутні залежності. `plugins search` — це віддалений пошук у каталозі ClawHub. Він не перевіряє локальний -стан, не змінює конфігурацію, не встановлює пакети й не завантажує runtime-код Plugin. Результати пошуку містять назву пакета ClawHub, сімейство, канал, версію, короткий опис і підказку для встановлення, як-от `openclaw plugins install clawhub:`. +стан, не змінює конфігурацію, не встановлює пакунки й не завантажує runtime-код Plugin. Результати пошуку включають назву пакунка ClawHub, сімейство, канал, версію, короткий опис і +підказку для встановлення, наприклад `openclaw plugins install clawhub:`. -Для роботи з вбудованими Plugin усередині запакованого Docker-образу змонтуйте вихідний каталог Plugin поверх відповідного запакованого шляху до джерел, наприклад -`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване накладання джерел перед `/app/dist/extensions/synology-chat`; просто скопійований каталог джерел залишиться неактивним, тому звичайні запаковані встановлення й далі використовуватимуть скомпільований dist. +Для роботи з вбудованим Plugin всередині пакетованого Docker-образу змонтуйте вихідний каталог Plugin +поверх відповідного пакетованого вихідного шляху, наприклад +`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване вихідне +накладання перед `/app/dist/extensions/synology-chat`; звичайний скопійований вихідний +каталог залишиться неактивним, тому стандартні пакетовані встановлення й надалі використовуватимуть скомпільований dist. Для налагодження runtime hook: -- `openclaw plugins inspect --runtime --json` показує зареєстровані hook і діагностику з проходу інспекції із завантаженням модуля. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані Plugin. -- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки щодо сервісу/процесу, шлях до конфігурації та справність RPC. +- `openclaw plugins inspect --runtime --json` показує зареєстровані hook і діагностику з проходу інспекції із завантаженим модулем. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані plugins. +- `openclaw gateway status --deep --require-rpc` підтверджує досяжний Gateway, підказки щодо сервісу/процесу, шлях конфігурації та справність RPC. - Невбудовані hook розмов (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. -Використовуйте `--link`, щоб не копіювати локальний каталог (додає до `plugins.load.paths`): +Використовуйте `--link`, щоб не копіювати локальний каталог (додає його до `plugins.load.paths`): ```bash openclaw plugins install -l ./my-plugin ``` -`--force` не підтримується з `--link`, тому що зв’язані встановлення повторно використовують шлях до джерел замість копіювання поверх керованої цілі встановлення. +`--force` не підтримується з `--link`, оскільки пов’язані встановлення повторно використовують вихідний шлях замість копіювання поверх керованої цілі встановлення. -Використовуйте `--pin` для npm-встановлень, щоб зберегти вирішену точну специфікацію (`name@version`) у керованому індексі Plugin, залишаючи типову поведінку незакріпленою. +Використовуйте `--pin` для npm-встановлень, щоб зберегти розв’язаний точний spec (`name@version`) у керованому індексі Plugin, зберігаючи типову поведінку без фіксації. ### Індекс Plugin -Метадані встановлення Plugin — це машинно керований стан, а не користувацька конфігурація. Встановлення й оновлення записують його до `plugins/installs.json` в активному каталозі стану OpenClaw. Його верхньорівнева мапа `installRecords` є тривалим джерелом метаданих встановлення, включно із записами для пошкоджених або відсутніх маніфестів Plugin. Масив `plugins` — це виведений із маніфестів кеш холодного реєстру. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою й холодним реєстром Plugin. +Метадані встановлення Plugin — це керований машиною стан, а не користувацька конфігурація. Встановлення й оновлення записують його в `plugins/installs.json` у активному каталозі стану OpenClaw. Його верхньорівнева мапа `installRecords` є довготривалим джерелом метаданих встановлення, включно із записами для зламаних або відсутніх маніфестів Plugin. Масив `plugins` — це похідний від маніфестів кеш холодного реєстру. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою й холодним реєстром Plugin. -Коли OpenClaw бачить поставлені застарілі записи `plugins.installs` у конфігурації, він переносить їх до індексу Plugin і вилучає ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не були втрачені. +Коли OpenClaw бачить поставлені застарілі записи `plugins.installs` у конфігурації, він переносить їх в індекс Plugin і видаляє ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не було втрачено. ### Видалення @@ -294,7 +299,7 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` вилучає записи Plugin з `plugins.entries`, збереженого індексу Plugin, записів списку дозволів/заборон Plugin і пов’язаних записів `plugins.load.paths`, коли це застосовно. Якщо `--keep-files` не задано, видалення також вилучає відстежуваний керований каталог встановлення, коли він розташований усередині кореня розширень Plugin OpenClaw. Для Plugin активної пам’яті слот пам’яті скидається до `memory-core`. +`uninstall` видаляє записи Plugin з `plugins.entries`, збереженого індексу Plugin, записів списків дозволу/заборони Plugin і пов’язаних записів `plugins.load.paths`, коли застосовно. Якщо не задано `--keep-files`, видалення також прибирає відстежуваний каталог керованого встановлення, коли він розташований усередині кореня розширень Plugin OpenClaw. Для plugins Active Memory слот пам’яті скидається до `memory-core`. `--keep-config` підтримується як застарілий псевдонім для `--keep-files`. @@ -313,26 +318,26 @@ openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-ins Оновлення застосовуються до відстежуваних встановлень Plugin у керованому індексі Plugin і відстежуваних встановлень hook-pack у `hooks.internal.installs`. - - Коли ви передаєте id Plugin, OpenClaw повторно використовує записану специфікацію встановлення для цього Plugin. Це означає, що раніше збережені dist-tags, як-от `@beta`, і точні закріплені версії надалі використовуються під час наступних запусків `update `. + + Коли ви передаєте id Plugin, OpenClaw повторно використовує записаний spec встановлення для цього Plugin. Це означає, що раніше збережені dist-tags, як-от `@beta`, і точні зафіксовані версії продовжують використовуватися під час наступних запусків `update `. - Для npm-встановлень ви також можете передати явну специфікацію npm-пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета з відстежуваним записом Plugin, оновлює цей встановлений Plugin і записує нову npm-специфікацію для майбутніх оновлень на основі id. + Для npm-встановлень ви також можете передати явний npm package spec із dist-tag або точною версією. OpenClaw зіставляє цю назву пакунка з відстежуваним записом Plugin, оновлює цей встановлений Plugin і записує новий npm spec для майбутніх оновлень за id. - Передавання назви npm-пакета без версії або тегу також зіставляється з відстежуваним записом Plugin. Використовуйте це, коли Plugin був закріплений на точній версії, а ви хочете повернути його до стандартної лінії випусків реєстру. + Передання назви npm-пакунка без версії або тега також зіставляється з відстежуваним записом Plugin. Використовуйте це, коли Plugin було зафіксовано на точній версії й ви хочете повернути його до типової лінії випусків реєстру. - `openclaw plugins update` повторно використовує відстежувану специфікацію Plugin, якщо ви не передасте нову специфікацію. `openclaw update` додатково знає активний канал оновлень OpenClaw: на beta-каналі записи npm і ClawHub Plugin стандартної лінії спершу пробують `@beta`, а потім повертаються до записаної стандартної/latest специфікації, якщо beta-випуску Plugin не існує. Точні версії та явні теги залишаються закріпленими за цим селектором. + `openclaw plugins update` повторно використовує відстежуваний spec Plugin, якщо ви не передасте новий spec. `openclaw update` додатково знає активний канал оновлень OpenClaw: на beta-каналі записи npm і ClawHub Plugin типової лінії спершу пробують `@beta`, а потім повертаються до записаного default/latest spec, якщо beta-випуску Plugin не існує. Точні версії та явні теги залишаються зафіксованими на цьому селекторі. - Перед live-оновленням npm OpenClaw перевіряє встановлену версію пакета за метаданими npm-реєстру. Якщо встановлена версія й записана ідентичність артефакту вже збігаються з вирішеною ціллю, оновлення пропускається без завантаження, повторного встановлення або перезапису `openclaw.json`. + Перед живим npm-оновленням OpenClaw перевіряє встановлену версію пакунка за метаданими npm-реєстру. Якщо встановлена версія та записана ідентичність артефакту вже відповідають розв’язаній цілі, оновлення пропускається без завантаження, перевстановлення або перезапису `openclaw.json`. - Коли існує збережений hash цілісності, а hash отриманого артефакту змінюється, OpenClaw трактує це як дрейф npm-артефакту. Інтерактивна команда `openclaw plugins update` друкує очікуваний і фактичний hashes та просить підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються із закритою відмовою, якщо викликач не надасть явну політику продовження. + Коли збережений integrity hash існує, а hash отриманого артефакту змінюється, OpenClaw трактує це як дрейф npm-артефакту. Інтерактивна команда `openclaw plugins update` виводить очікуваний і фактичний hashes і просить підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються закрито, якщо викликач не надає явну політику продовження. - - `--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійне перевизначення для хибних спрацьовувань вбудованого сканування небезпечного коду під час оновлень Plugin. Він усе одно не обходить блокування політики `before_install` Plugin або блокування через збій сканування, і застосовується лише до оновлень Plugin, а не до оновлень hook-pack. + + `--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійне перевизначення для хибнопозитивних спрацьовувань вбудованого сканування небезпечного коду під час оновлень Plugin. Він однаково не обходить блокування політик Plugin `before_install` або блокування через збій сканування, і застосовується лише до оновлень Plugin, а не до оновлень hook-pack. @@ -344,21 +349,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політики, діагностику, метадані встановлення, можливості пакетів і будь-яку виявлену підтримку серверів MCP або LSP, типово без імпорту runtime-коду Plugin. Додайте `--runtime`, щоб завантажити модуль Plugin і включити зареєстровані hook, tools, commands, services, gateway methods і HTTP routes. Runtime-інспекція прямо повідомляє про відсутні залежності Plugin; встановлення й виправлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`. +Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політик, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку серверів MCP або LSP, типово не імпортуючи runtime Plugin. Додайте `--runtime`, щоб завантажити модуль Plugin і включити зареєстровані hook, tools, commands, services, gateway methods і HTTP routes. Runtime-інспекція повідомляє про відсутні залежності Plugin безпосередньо; встановлення й виправлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`. CLI-команди, що належать Plugin, встановлюються як кореневі групи команд `openclaw`. Після того як `inspect --runtime` покаже команду в `cliCommands`, запускайте її як `openclaw ...`; наприклад, Plugin, який реєструє `demo-git`, можна перевірити за допомогою `openclaw demo-git ping`. Кожен Plugin класифікується за тим, що він фактично реєструє під час роботи: -- **plain-capability** — один тип можливостей (наприклад, Plugin лише для provider) -- **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення) -- **hook-only** — лише hook, без можливостей або surface +- **plain-capability** — один тип можливості (наприклад, Plugin лише для provider) +- **hybrid-capability** — кілька типів можливостей (наприклад, text + speech + images) +- **hook-only** — лише hook, без можливостей або поверхонь - **non-capability** — tools/commands/services, але без можливостей Докладніше про модель можливостей див. [Форми Plugin](/uk/plugins/architecture#plugin-shapes). -Прапорець `--json` виводить машиночитний звіт, придатний для скриптів і аудиту. `inspect --all` відображає таблицю для всього парку зі shape, видами можливостей, повідомленнями сумісності, можливостями пакетів і колонками зведення hook. `info` є псевдонімом для `inspect`. +Прапорець `--json` виводить машиночитний звіт, придатний для сценаріїв і аудиту. `inspect --all` відображає таблицю для всього набору з shape, capability kinds, compatibility notices, bundle capabilities і колонками підсумку hook. `info` є псевдонімом для `inspect`. ### Doctor @@ -367,9 +372,9 @@ CLI-команди, що належать Plugin, встановлюються openclaw plugins doctor ``` -`doctor` повідомляє про помилки завантаження Plugin, діагностику маніфесту/виявлення та повідомлення сумісності. Коли все чисто, він друкує `No plugin issues detected.` +`doctor` повідомляє про помилки завантаження Plugin, діагностику маніфесту/виявлення та повідомлення про сумісність. Коли все чисто, він виводить `No plugin issues detected.` -Для збоїв форми модуля, як-от відсутні експорти `register`/`activate`, повторно запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб додати до діагностичного виводу компактне зведення форми експортів. +Для збоїв форми модуля, як-от відсутні експорти `register`/`activate`, повторно запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити компактний підсумок форми експорту в діагностичний вивід. ### Реєстр @@ -379,12 +384,12 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -Локальний реєстр Plugin — це збережена в OpenClaw холодна модель читання для ідентичності встановлених Plugin, стану ввімкнення, метаданих джерела та власності внесків. Звичайний запуск, пошук власника provider, класифікація налаштування каналу та інвентар Plugin можуть читати його без імпорту runtime-модулів Plugin. +Локальний реєстр Plugin — це збережена OpenClaw модель холодного читання для ідентичності встановлених Plugin, увімкнення, метаданих джерела та володіння внесками. Звичайний запуск, пошук власника provider, класифікація налаштування channel і інвентар Plugin можуть читати його без імпорту runtime-модулів Plugin. -Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр присутній, актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу Plugin, політики конфігурації та метаданих маніфесту/пакета. Це шлях виправлення, а не шлях runtime-активації. +Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр наявний, актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу Plugin, політики конфігурації та метаданих маніфесту/пакунка. Це шлях виправлення, а не шлях runtime-активації. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний env-механізм призначений лише для аварійного відновлення запуску, поки міграція розгортається. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — застарілий аварійний перемикач сумісності для збоїв читання реєстру. Віддавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через змінну середовища призначений лише для аварійного відновлення запуску під час розгортання міграції. ### Маркетплейс @@ -394,10 +399,10 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Список маркетплейсу приймає локальний шлях до маркетплейсу, шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить мітку розв’язаного джерела, а також розібраний маніфест маркетплейсу та записи Plugin. +Список маркетплейсу приймає локальний шлях до маркетплейсу, шлях до `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить визначену мітку джерела, а також розібраний маніфест маркетплейсу й записи плагінів. ## Пов’язане -- [Створення Plugin](/uk/plugins/building-plugins) +- [Створення плагінів](/uk/plugins/building-plugins) - [Довідник CLI](/uk/cli) -- [Plugin спільноти](/uk/plugins/community) +- [Плагіни спільноти](/uk/plugins/community) diff --git a/docs/uk/concepts/mantis.md b/docs/uk/concepts/mantis.md index 8cd3355d5..a06da546a 100644 --- a/docs/uk/concepts/mantis.md +++ b/docs/uk/concepts/mantis.md @@ -1,65 +1,85 @@ --- read_when: - - Створення або запуск візуальної перевірки якості в реальному часі для помилок OpenClaw + - Створення або запуск візуальної перевірки якості наживо для помилок OpenClaw - Додавання перевірки до та після для запиту на злиття - - Додавання сценаріїв із Discord, Slack, WhatsApp або іншими реальними транспортами - - Налагодження запусків QA, для яких потрібні знімки екрана, автоматизація браузера або доступ через VNC -summary: Mantis — це система візуальної наскрізної перевірки для відтворення помилок OpenClaw у реальних транспортах, фіксації доказів до й після та прикріплення артефактів до PR. + - Додавання сценаріїв із живим транспортом для Discord, Slack, WhatsApp або інших сервісів + - Налагодження запусків QA, яким потрібні знімки екрана, автоматизація браузера або доступ VNC +summary: Mantis — це візуальна система наскрізної перевірки для відтворення помилок OpenClaw у живих транспортах, фіксації доказів до й після та прикріплення артефактів до запитів на злиття. title: Богомол x-i18n: - generated_at: "2026-05-03T16:48:36Z" + generated_at: "2026-05-03T17:12:23Z" model: gpt-5.5 provider: openai - source_hash: 5b58934ec88a640745f7430c875c377e898f87f1b3d4a9ef03115395084664f5 + source_hash: 2a038872d2754b380a0983d81869de247d66c41b49746e1608dca215ab2096a7 source_path: concepts/mantis.md workflow: 16 --- -Mantis — це система наскрізної верифікації OpenClaw для помилок, яким потрібні реальне середовище виконання, реальний транспорт і видимий доказ. Вона запускає сценарій проти відомого поганого ref, збирає докази, запускає той самий сценарій проти кандидатного ref і публікує порівняння як артефакти, які мейнтейнер може переглянути з PR або з локальної команди. +Mantis — це система наскрізної перевірки OpenClaw для багів, яким потрібні справжнє +середовище виконання, справжній транспорт і видимий доказ. Вона запускає сценарій на відомому +поганому ref, збирає докази, запускає той самий сценарій на кандидатному ref і +публікує порівняння як артефакти, які мейнтейнер може перевірити з PR або +з локальної команди. -Mantis починає з Discord, бо Discord дає нам високоцінний перший напрям: справжню автентифікацію бота, реальні канали guild, реакції, треди, нативні команди й браузерний UI, де люди можуть візуально підтвердити, що показав транспорт. +Mantis починає з Discord, тому що Discord дає нам цінну першу смугу: +справжню автентифікацію бота, справжні канали гільдії, реакції, потоки, нативні команди та +інтерфейс браузера, де люди можуть візуально підтвердити, що показав транспорт. ## Цілі -- Відтворити помилку з GitHub issue або PR з тією самою формою транспорту, яку бачать користувачі. +- Відтворити баг з issue або PR на GitHub з тією самою формою транспорту, яку + бачать користувачі. - Зібрати артефакт **до** на базовому ref перед застосуванням виправлення. - Зібрати артефакт **після** на кандидатному ref після застосування виправлення. -- За можливості використовувати детермінований оракул, наприклад читання реакції Discord REST або перевірку транскрипту каналу. -- Збирати знімки екрана, коли помилка має видиму поверхню UI. +- Використовувати детермінований оракул, коли це можливо, наприклад читання реакції через REST Discord + або перевірку транскрипту каналу. +- Знімати скріншоти, коли баг має видиму поверхню UI. - Запускати локально з керованого агентом CLI і віддалено з GitHub. -- Зберігати достатньо стану машини для VNC-порятунку, коли вхід, браузерна автоматизація або автентифікація провайдера застрягають. -- Публікувати стислий статус в операторський канал Discord, коли запуск заблоковано, потрібна ручна допомога VNC або запуск завершено. +- Зберігати достатньо стану машини для порятунку через VNC, коли вхід, автоматизація браузера або + автентифікація провайдера застрягає. +- Надсилати стислий статус в операторський канал Discord, коли запуск заблоковано, + потрібна ручна допомога через VNC або запуск завершено. ## Нецілі -- Mantis не є заміною модульних тестів. Запуск Mantis після розуміння виправлення зазвичай має перетворюватися на менший регресійний тест. -- Mantis не є звичайним швидким шлюзом CI. Він повільніший, використовує живі облікові дані й призначений для помилок, де живе середовище має значення. -- Mantis не має вимагати людини для нормальної роботи. Ручний VNC — це шлях порятунку, а не штатний сценарій. -- Mantis не зберігає сирі секрети в артефактах, журналах, знімках екрана, Markdown-звітах або коментарях PR. +- Mantis не є заміною для модульних тестів. Запуск Mantis зазвичай має стати + меншим регресійним тестом після того, як виправлення зрозуміле. +- Mantis не є звичайним швидким CI-шлюзом. Він повільніший, використовує живі облікові дані та + призначений для багів, де живе середовище має значення. +- Mantis не повинен вимагати людину для нормальної роботи. Ручний VNC — це шлях порятунку, + а не штатний шлях. +- Mantis не зберігає сирі секрети в артефактах, журналах, скріншотах, Markdown-звітах + або коментарях PR. -## Володіння +## Власність -Mantis належить до стеку QA OpenClaw. +Mantis живе в QA-стеку OpenClaw. -- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і локальним CLI під `pnpm openclaw qa mantis`. -- QA Lab володіє частинами harness для живого транспорту, помічниками браузерного захоплення й записувачами артефактів. +- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і + локальним CLI під `pnpm openclaw qa mantis`. +- QA Lab володіє компонентами живого транспортного harness, допоміжними засобами захоплення браузера та + записувачами артефактів. - Crabbox володіє прогрітими Linux-машинами, коли потрібна віддалена VM. -- GitHub Actions володіє віддаленою точкою входу workflow і збереженням артефактів. -- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів, dispatch workflow і публікацією фінального коментаря PR. -- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування, налагодження або звітування про застряглий стан. +- GitHub Actions володіє віддаленою точкою входу workflow та зберіганням артефактів. +- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів, + запуском workflow і публікацією фінального коментаря PR. +- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування, + налагодження або звітування про застряглий стан. -Ця межа тримає знання про транспорт в OpenClaw, планування машин у Crabbox, а клей мейнтейнерського workflow у ClawSweeper. +Ця межа тримає знання про транспорт в OpenClaw, планування машин у +Crabbox, а клей мейнтейнерського workflow у ClawSweeper. -## Форма команди +## Форма команд -Перша локальна команда перевіряє бота Discord, guild, канал, надсилання повідомлення, надсилання реакції та шлях артефактів: +Перша локальна команда перевіряє бота Discord, гільдію, канал, надсилання повідомлення, +надсилання реакції та шлях артефактів: ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -Пізніший runner для до і після має приймати таку форму: +Пізніший runner до і після має приймати таку форму: ```bash pnpm openclaw qa mantis run \ @@ -70,12 +90,17 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -Smoke workflow GitHub — це `Mantis Discord Smoke`. Workflow GitHub для до і після першого реального сценарію — це `Mantis Discord Status Reactions`. Він приймає: +Димовий workflow GitHub — `Mantis Discord Smoke`. Workflow GitHub до і після +для першого справжнього сценарію — `Mantis Discord Status Reactions`. Він +приймає: -- `baseline_ref`: ref, на якому очікується відтворення поведінки лише queued. -- `candidate_ref`: ref, на якому очікується показ `queued -> thinking -> done`. +- `baseline_ref`: ref, який має відтворювати поведінку лише з queued. +- `candidate_ref`: ref, який має показувати `queued -> thinking -> done`. -Він checkout-ить ref harness workflow, будує окремі worktree для baseline і candidate, запускає `discord-status-reactions-tool-only` проти кожного worktree та завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як артефакти Actions. +Він checkout-ить ref harness workflow, створює окремі worktree для baseline і candidate, +запускає `discord-status-reactions-tool-only` проти кожного worktree і +завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як +артефакти Actions. Приклади команд ClawSweeper: @@ -84,7 +109,9 @@ Smoke workflow GitHub — це `Mantis Discord Smoke`. Workflow GitHub для д @clawsweeper verify e2e discord ``` -Перша команда явна й зосереджена на сценарії. Друга згодом може зіставляти PR або issue з рекомендованими сценаріями Mantis на основі міток, змінених файлів і знахідок рев’ю ClawSweeper. +Перша команда явна й зосереджена на сценарії. Друга згодом може зіставляти PR +або issue з рекомендованими сценаріями Mantis за мітками, зміненими файлами та +знахідками рев’ю ClawSweeper. ## Життєвий цикл запуску @@ -92,34 +119,38 @@ Smoke workflow GitHub — це `Mantis Discord Smoke`. Workflow GitHub для д 2. Виділити або повторно використати VM. 3. Підготувати чистий checkout для базового ref. 4. Встановити залежності й зібрати лише те, що потрібно сценарію. -5. Запустити дочірній OpenClaw Gateway з ізольованим каталогом стану. +5. Запустити дочірній OpenClaw Gateway з ізольованою директорією стану. 6. Налаштувати живий транспорт, провайдера, модель і профіль браузера. 7. Запустити сценарій і зібрати базові докази. 8. Зупинити Gateway і зберегти журнали. 9. Підготувати кандидатний ref у тій самій VM. 10. Запустити той самий сценарій і зібрати кандидатні докази. -11. Порівняти результати оракула й візуальні докази. -12. Записати Markdown, JSON, журнали, знімки екрана та опціональні артефакти трасування. +11. Порівняти результати оракула та візуальні докази. +12. Записати Markdown, JSON, журнали, скріншоти та опційні артефакти трасування. 13. Завантажити артефакти GitHub Actions. 14. Опублікувати стислий статус у PR або Discord. -Сценарій має вміти завершуватися невдачею двома різними способами: +Сценарій має вміти падати двома різними способами: -- **Помилку відтворено**: baseline впав очікуваним способом. -- **Збій harness**: налаштування середовища, облікові дані, Discord API, браузер або провайдер впали до того, як оракул помилки став змістовним. +- **Баг відтворено**: baseline впав очікуваним способом. +- **Збій harness**: налаштування середовища, облікові дані, API Discord, браузер або + провайдер впали до того, як оракул бага став змістовним. -Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне середовище з поведінкою продукту. +Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне +середовище з поведінкою продукту. -## MVP Discord +## MVP для Discord -Перший сценарій має націлюватися на реакції статусу Discord у каналах guild, де режим доставки вихідної відповіді — `message_tool_only`. +Перший сценарій має цілитися в статусні реакції Discord у каналах гільдії, де +режим доставки відповіді джерела — `message_tool_only`. -Чому це хороший початковий сценарій Mantis: +Чому це хороше зерно Mantis: -- Це видно в Discord як реакції на повідомлення, що запустило сценарій. -- Він має сильний REST-оракул через стан реакцій повідомлення Discord. -- Він перевіряє реальний OpenClaw Gateway, автентифікацію бота Discord, dispatch повідомлення, режим доставки вихідної відповіді, стан реакцій статусу та життєвий цикл ходу моделі. -- Він достатньо вузький, щоб перша реалізація залишалася чесною. +- Це видно в Discord як реакції на повідомлення-тригер. +- Воно має сильний REST-оракул через стан реакцій повідомлення Discord. +- Воно перевіряє справжній OpenClaw Gateway, автентифікацію бота Discord, диспетчеризацію повідомлень, + режим доставки відповіді джерела, стан статусних реакцій і життєвий цикл ходу моделі. +- Воно достатньо вузьке, щоб перша реалізація залишалася чесною. Очікувана форма сценарію: @@ -152,7 +183,10 @@ evidence: screenshotMessageRow: true ``` -Базові докази мають показувати реакцію підтвердження queued, але без переходу життєвого циклу в режимі лише інструментів. Кандидатні докази мають показувати виконання реакцій статусу життєвого циклу, коли `messages.statusReactions.enabled` явно дорівнює `true`. +Базові докази мають показувати реакцію підтвердження queued, але без +переходу життєвого циклу в режимі лише інструмента. Кандидатні докази мають показувати, що статусні +реакції життєвого циклу працюють, коли `messages.statusReactions.enabled` явно +дорівнює true. Виконуваний перший зріз — це opt-in живий QA-сценарій Discord: @@ -166,24 +200,34 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Він налаштовує SUT із постійно ввімкненою обробкою guild, `visibleReplies: -"message_tool"`, `ackReaction: "👀"` і явними реакціями статусу. Оракул опитує справжнє повідомлення-тригер Discord і очікує спостережувану послідовність `👀 -> 🤔 -> 👍`. Артефакти включають `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` і `discord-status-reactions-tool-only-timeline.png`. +Він налаштовує SUT з постійно увімкненою обробкою гільдій, `visibleReplies: +"message_tool"`, `ackReaction: "👀"` і явними статусними реакціями. Оракул +опитує справжнє повідомлення-тригер Discord і очікує спостережувану послідовність +`👀 -> 🤔 -> 👍`. Артефакти включають `discord-qa-reaction-timelines.json`, +`discord-status-reactions-tool-only-timeline.html` і +`discord-status-reactions-tool-only-timeline.png`. -## Наявні частини QA +## Наявні компоненти QA -Mantis має будуватися на наявному приватному стеку QA замість старту з нуля: +Mantis має будуватися на наявному приватному QA-стеку замість починати з +нуля: -- `pnpm openclaw qa discord` вже запускає живий напрям Discord з ботами driver і SUT. -- Runner живого транспорту вже записує звіти та артефакти спостережуваних повідомлень у `.artifacts/qa-e2e/`. -- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих транспортних облікових даних. -- Сервіс керування браузером уже підтримує знімки екрана, snapshots, headless керовані профілі та віддалені профілі CDP. -- QA Lab уже має UI налагоджувача і шину для тестування у формі транспорту. +- `pnpm openclaw qa discord` уже запускає живу смугу Discord з ботами driver і + SUT. +- Живий транспортний runner уже записує звіти й артефакти спостережених повідомлень + під `.artifacts/qa-e2e/`. +- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих + транспортних облікових даних. +- Сервіс керування браузером уже підтримує скріншоти, снапшоти, + керовані headless-профілі та віддалені CDP-профілі. +- QA Lab уже має UI налагоджувача і bus для тестування у формі транспорту. -Перша реалізація Mantis може бути тонким runner до/після поверх цих частин плюс один шар візуальних доказів. +Перша реалізація Mantis може бути тонким runner до/після поверх цих +компонентів плюс один шар візуальних доказів. ## Модель доказів -Кожен запуск записує стабільний каталог артефактів: +Кожен запуск записує стабільну директорію артефактів: ```text .artifacts/qa-e2e/mantis// @@ -203,63 +247,77 @@ Mantis має будуватися на наявному приватному с run.log ``` -`mantis-summary.json` має бути машинозчитуваним джерелом істини. Markdown-звіт призначений для коментарів PR і людського рев’ю. +`mantis-summary.json` має бути машиночитним джерелом істини. Звіт +Markdown призначений для коментарів PR і людського рев’ю. -Підсумок має включати: +Зведення має включати: - протестовані refs і SHA - транспорт і id сценарію - провайдера машини та id машини або id оренди -- джерело облікових даних без секретних значень +- джерело облікових даних без значень секретів - результат baseline - результат candidate -- чи відтворилася помилка на baseline -- чи candidate її виправив +- чи відтворився баг на baseline +- чи candidate виправив його - шляхи артефактів -- очищені проблеми налаштування або очищення +- очищені від секретів проблеми налаштування або очищення -Знімки екрана — це докази, а не секрети. Вони все одно потребують дисципліни редагування: можуть з’явитися назви приватних каналів, імена користувачів або вміст повідомлень. Для публічних PR віддавайте перевагу посиланням на артефакти GitHub Actions замість inline-зображень, доки історія редагування не стане сильнішою. +Скріншоти — це докази, а не секрети. Вони все одно потребують дисципліни редагування: +можуть з’являтися приватні назви каналів, імена користувачів або вміст повідомлень. Для публічних PR +надавайте перевагу посиланням на артефакти GitHub Actions замість вбудованих зображень, доки історія +редагування не стане сильнішою. ## Браузер і VNC -Браузерний напрям має два режими: +Браузерна смуга має два режими: -- **Headless-автоматизація**: типово для CI. Chrome працює з увімкненим CDP, а Playwright або браузерне керування OpenClaw збирає знімки екрана. -- **VNC-порятунок**: вмикається на тій самій VM, коли вхід, MFA, антиавтоматизація Discord або візуальне налагодження потребують людини. +- **Headless-автоматизація**: типово для CI. Chrome запускається з увімкненим CDP, а + Playwright або керування браузером OpenClaw збирає скріншоти. +- **Порятунок через VNC**: вмикається на тій самій VM, коли вхід, MFA, антиавтоматизація Discord + або візуальне налагодження потребують людини. -Профіль браузера-спостерігача Discord має бути достатньо persistent, щоб не входити в систему під час кожного запуску, але ізольованим від особистого стану браузера. Профіль належить пулу машин Mantis, а не ноутбуку розробника. +Профіль браузера-спостерігача Discord має бути достатньо постійним, щоб уникати +входу в кожному запуску, але ізольованим від особистого стану браузера. Профіль +належить пулу машин Mantis, а не ноутбуку розробника. -Коли Mantis застрягає, він публікує статусне повідомлення Discord з такими даними: +Коли Mantis застрягає, він публікує статусне повідомлення Discord з: - id запуску - id сценарію -- провайдер машини -- каталог артефактів -- інструкції підключення VNC або noVNC, якщо доступні -- короткий текст блокера +- провайдером машини +- директорією артефактів +- інструкціями підключення VNC або noVNC, якщо доступні +- коротким текстом блокера -Перше приватне розгортання може публікувати ці повідомлення в наявний операторський канал і пізніше перейти до окремого каналу Mantis. +Перше приватне розгортання може публікувати ці повідомлення в наявний операторський +канал і перейти до виділеного каналу Mantis пізніше. ## Машини -Mantis має віддавати перевагу AWS через Crabbox для першої віддаленої реалізації. Crabbox дає нам прогріті машини, відстеження оренд, hydration, журнали, результати й очищення. Якщо місткість AWS занадто повільна або недоступна, додайте провайдера Hetzner за тим самим інтерфейсом машини. +Mantis має надавати перевагу AWS через Crabbox для першої віддаленої реалізації. +Crabbox дає нам прогріті машини, відстеження оренд, гідратацію, журнали, результати та +очищення. Якщо місткість AWS надто повільна або недоступна, додайте провайдера Hetzner +за тим самим інтерфейсом машини. Мінімальні вимоги до VM: -- Linux з інсталяцією Chrome або Chromium, здатною працювати з робочим столом -- доступ CDP для браузерної автоматизації +- Linux з Chrome або Chromium, придатним для desktop +- доступ CDP для автоматизації браузера - VNC або noVNC для порятунку - Node 22 і pnpm - checkout OpenClaw і кеш залежностей - кеш браузера Playwright Chromium, коли використовується Playwright -- достатньо CPU і пам’яті для одного OpenClaw Gateway, одного браузера й одного запуску моделі -- вихідний доступ до Discord, GitHub, модельних провайдерів і брокера облікових даних +- достатньо CPU і пам’яті для одного OpenClaw Gateway, одного браузера та одного запуску моделі +- вихідний доступ до Discord, GitHub, провайдерів моделей і брокера облікових даних -VM не має зберігати довгоживучі сирі секрети поза очікуваними сховищами облікових даних або профілів браузера. +VM не повинна зберігати довгоживучі сирі секрети поза очікуваними сховищами облікових даних або +профілів браузера. ## Секрети -Секрети живуть у секретах організації або репозиторію GitHub для віддалених запусків і в локальному контрольованому оператором файлі секретів для локальних запусків. +Секрети живуть у секретах організації або репозиторію GitHub для віддалених запусків і в +локальному файлі секретів, керованому оператором, для локальних запусків. Рекомендовані назви секретів: @@ -273,9 +331,10 @@ VM не має зберігати довгоживучі сирі секрети - `OPENCLAW_QA_CONVEX_SITE_URL` - `OPENCLAW_QA_CONVEX_SECRET_CI` -У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для живих транспортних облікових даних. Секрети GitHub bootstrap-лять брокер і резервні напрями. +У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для живих +транспортних облікових даних. Секрети GitHub початково завантажують брокер і fallback-смуги. -Runner Mantis ніколи не має друкувати: +Runner Mantis ніколи не повинен друкувати: - токени ботів Discord - API-ключі провайдерів @@ -284,15 +343,20 @@ Runner Mantis ніколи не має друкувати: - паролі VNC - сирі payload облікових даних -Публічні завантаження артефактів також мають редагувати цільові метадані Discord, як-от id бота, guild, каналу й повідомлення. Smoke workflow GitHub вмикає `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` саме з цієї причини. +Публічні завантаження артефактів також мають редагувати цільові метадані Discord, як-от bot, +guild, channel і message ids. Димовий workflow GitHub вмикає +`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` з цієї причини. -Якщо токен випадково вставлено в issue, PR, чат або журнал, ротувати його після збереження нового секрету. +Якщо токен випадково вставлено в issue, PR, chat або log, поверніть його +після того, як новий секрет буде збережено. ## Артефакти GitHub і коментарі PR -Робочі процеси Mantis мають завантажувати повний пакет доказів як короткочасний артефакт Actions. Коли робочий процес запускається для звіту про помилку або PR з виправленням, він також має публікувати редаговані PNG-знімки екрана в гілку `qa-artifacts` і створювати або оновлювати коментар до цієї помилки чи PR з виправленням із вбудованими знімками екрана до/після. Не публікуйте основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережені повідомлення та інші об’ємні докази залишаються в артефакті Actions. +У робочих процесах Mantis слід завантажувати повний пакет доказів як короткочасний артефакт Actions. Коли робочий процес запускається для звіту про помилку або PR із виправленням, він також має публікувати відредаговані PNG-знімки екрана в гілку `qa-artifacts` і оновлювати або створювати коментар у цьому звіті про помилку чи PR із виправленням з вбудованими знімками екрана до/після. Не публікуйте основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережені повідомлення та інші об'ємні докази залишаються в артефакті Actions. -Коментар до PR має бути коротким і візуальним: +Виробничі робочі процеси мають публікувати ці коментарі через Mantis GitHub App, а не через `github-actions[bot]`. Зберігайте id застосунку та приватний ключ як секрети GitHub Actions `MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. Якщо цих секретів немає, робочий процес може відступити до `github-actions[bot]` для локального запуску, але це не бажана довгострокова ідентичність. + +Коментар у PR має бути коротким і наочним: ```md Mantis Discord Status Reactions QA @@ -312,21 +376,21 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Коли запуск завершується невдало через збій тестового стенда, у коментарі має бути сказано саме це, а не натяк, що кандидат не пройшов перевірку. +Коли запуск завершується невдало через збій обв'язки тестування, коментар має прямо це зазначати, а не створювати враження, що кандидат не пройшов перевірку. -## Примітки щодо приватного розгортання +## Нотатки щодо приватного розгортання -У приватному розгортанні вже може бути застосунок Mantis Discord. Повторно використайте цей застосунок замість створення іншого, якщо він має належні дозволи бота і його можна безпечно ротувати. +У приватному розгортанні вже може бути застосунок Mantis Discord. Повторно використовуйте цей застосунок замість створення ще одного, якщо він має потрібні дозволи бота і його можна безпечно ротувати. -Задайте початковий канал сповіщень оператора через secrets або конфігурацію розгортання. Спершу він може вказувати на наявний канал супровідників або операційний канал, а потім перейти на окремий канал Mantis, коли він з’явиться. +Задайте початковий канал сповіщень оператора через секрети або конфігурацію розгортання. Спершу він може вказувати на наявний канал супровідників або операційний канал, а потім перейти до виділеного каналу Mantis, коли такий з'явиться. -Не розміщуйте ідентифікатори гільдій, ідентифікатори каналів, токени ботів, браузерні cookie або паролі VNC у цьому документі. Зберігайте їх у GitHub secrets, брокері облікових даних або локальному сховищі секретів оператора. +Не додавайте в цей документ id гільдій, id каналів, токени ботів, browser cookies або паролі VNC. Зберігайте їх у секретах GitHub, брокері облікових даних або локальному сховищі секретів оператора. ## Додавання сценарію Сценарій Mantis має оголошувати: -- ідентифікатор і заголовок +- id і назву - транспорт - потрібні облікові дані - політику baseline ref @@ -337,35 +401,35 @@ candidate showed the expected queued -> thinking -> done sequence. - очікуваний оракул baseline - очікуваний оракул candidate - цілі візуального захоплення -- бюджет часу очікування +- бюджет таймауту - кроки очищення -Сценарії мають надавати перевагу невеликим типізованим оракулам: +Сценаріям слід надавати перевагу невеликим типізованим оракулам: - стан реакцій Discord для помилок реакцій -- посилання на повідомлення Discord для помилок гілкування -- thread ts Slack і стан API реакцій для помилок Slack -- ідентифікатори повідомлень електронної пошти та заголовки для помилок електронної пошти -- знімки екрана браузера, коли UI є єдиним надійним спостережуваним показником +- посилання на повідомлення Discord для помилок потоків обговорення +- Slack thread ts і стан API реакцій для помилок Slack +- id повідомлень електронної пошти та заголовки для помилок електронної пошти +- знімки екрана браузера, коли UI є єдиним надійним спостережуваним сигналом -Перевірки Vision мають бути додатковими. Якщо API платформи може довести помилку, використовуйте API як оракул pass/fail, а знімки екрана залишайте для впевненості людини. +Перевірки Vision мають бути додатковими. Якщо API платформи може довести помилку, використовуйте API як оракул успіху/помилки, а знімки екрана залишайте для людської впевненості. ## Розширення провайдерів Після Discord той самий runner може додати: -- Slack: реакції, гілки, згадки застосунку, модальні вікна, завантаження файлів. -- Електронна пошта: автентифікація Gmail і гілкування повідомлень за допомогою `gog`, коли конекторів недостатньо. -- WhatsApp: вхід через QR, повторна ідентифікація, доставлення повідомлень, медіа, реакції. -- Telegram: обмеження згадок у групах, команди, реакції, де вони доступні. -- Matrix: зашифровані кімнати, зв’язки гілок або відповідей, відновлення після перезапуску. +- Slack: реакції, потоки обговорення, згадки застосунку, модальні вікна, завантаження файлів. +- Електронна пошта: автентифікація Gmail і потоки повідомлень за допомогою `gog`, коли конекторів недостатньо. +- WhatsApp: вхід через QR, повторна ідентифікація, доставка повідомлень, медіа, реакції. +- Telegram: фільтрація згадок у групах, команди, реакції, де доступно. +- Matrix: зашифровані кімнати, зв'язки потоків або відповідей, відновлення після перезапуску. -Кожен транспорт має мати один дешевий smoke-сценарій і один або більше сценаріїв класів помилок. Дорогі візуальні сценарії мають залишатися opt-in. +Кожен транспорт повинен мати один дешевий smoke-сценарій і один або кілька сценаріїв класу помилок. Дорогі візуальні сценарії мають залишатися opt-in. ## Відкриті питання - Який бот Discord має бути драйвером, а який SUT, коли наявний бот Mantis використовується повторно? -- Чи має вхід спостерігача в браузері використовувати людський обліковий запис Discord, тестовий обліковий запис або лише доступні боту докази REST для першої фази? +- Чи має вхід у браузері спостерігача використовувати людський обліковий запис Discord, тестовий обліковий запис або лише доступні боту REST-докази для першої фази? - Як довго GitHub має зберігати артефакти Mantis для PR? - Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування команди супровідника? -- Чи потрібно редагувати або обрізати знімки екрана перед завантаженням для публічних PR? +- Чи слід редагувати або обрізати знімки екрана перед завантаженням у публічні PR? diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index aa96b9d9d..5bf184dd1 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -1,40 +1,40 @@ --- read_when: - - Перше налаштування OpenClaw + - Налаштування OpenClaw уперше - Пошук поширених шаблонів конфігурації - - Перехід до певних розділів конфігурації -summary: 'Огляд конфігурації: типові завдання, швидке налаштування та посилання на повний довідник' + - Перехід до конкретних розділів конфігурації +summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-05-03T12:47:57Z" + generated_at: "2026-05-03T17:12:12Z" model: gpt-5.5 provider: openai - source_hash: b17a72368bb8d178174ccd3ff401657c67911096efd5960e5a1aa8cf0d303c81 + source_hash: e27ef442d6375d8c22715f20194fb9ce50130204377c9ba4652c2949de28967c source_path: gateway/configuration.md workflow: 16 --- -OpenClaw читає необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. +OpenClaw читає необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. Активний шлях конфігурації має бути звичайним файлом. Макети `openclaw.json` -із символьними посиланнями не підтримуються для записів, якими володіє OpenClaw; атомарний запис може замінити -шлях замість збереження символьного посилання. Якщо ви зберігаєте конфігурацію поза -типовим каталогом стану, укажіть `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл. +із симлінками не підтримуються для записів, якими володіє OpenClaw; атомарний запис може замінити +шлях замість збереження симлінка. Якщо ви зберігаєте конфігурацію поза +стандартним каталогом стану, спрямуйте `OPENCLAW_CONFIG_PATH` безпосередньо на справжній файл. -Якщо файл відсутній, OpenClaw використовує безпечні стандартні значення. Поширені причини додати конфігурацію: +Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію: -- Під’єднати канали й контролювати, хто може писати боту -- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, хуки) +- Під’єднати канали та керувати тим, хто може писати боту +- Налаштувати моделі, інструменти, sandboxing або автоматизацію (cron, hooks) - Налаштувати сеанси, медіа, мережу або UI Див. [повний довідник](/uk/gateway/configuration-reference) для всіх доступних полів. Агенти й автоматизація мають використовувати `config.schema.lookup` для точних -документів на рівні полів перед редагуванням конфігурації. Використовуйте цю сторінку для практичних настанов і +документів рівня окремих полів перед редагуванням конфігурації. Використовуйте цю сторінку для орієнтованих на завдання вказівок і [довідник конфігурації](/uk/gateway/configuration-reference) для ширшої -карти полів і стандартних значень. +карти полів і значень за замовчуванням. -**Вперше налаштовуєте конфігурацію?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [приклади конфігурації](/uk/gateway/configuration-examples) із повними конфігураціями для копіювання. +**Новачок у конфігурації?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із повними конфігураціями для копіювання. ## Мінімальна конфігурація @@ -50,69 +50,65 @@ OpenClaw читає необов’язкову конфігурацію - + ```bash openclaw onboard # full onboarding flow openclaw configure # config wizard ``` - + ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` - - Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і скористайтеся вкладкою **Config**. - Control UI відтворює форму з живої схеми конфігурації, включно з метаданими документації - `title` / `description` для полів, а також схемами Plugin і каналів, коли вони - доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих - UI та інших інструментів gateway також надає `config.schema.lookup`, щоб - отримати один вузол схеми, обмежений шляхом, разом зі зведеннями безпосередніх дочірніх елементів. + + Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і скористайтеся вкладкою **Конфігурація**. + Інтерфейс керування відображає форму з актуальної схеми конфігурації, включно з + метаданими документації полів `title` / `description`, а також схемами plugin і каналів, коли + вони доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих + UI та інших інструментів Gateway також надає `config.schema.lookup`, щоб + отримати один вузол схеми з обмеженням за шляхом і зведення найближчих дочірніх елементів. - - Редагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і застосовує зміни автоматично (див. [гаряче перезавантаження](#config-hot-reload)). + + Редагуйте `~/.openclaw/openclaw.json` напряму. Gateway відстежує файл і застосовує зміни автоматично (див. [гаряче перезавантаження](#config-hot-reload)). ## Сувора валідація -OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, неправильно сформовані типи або недійсні значення змушують Gateway **відмовитися запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. +OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення змушують Gateway **відмовитися запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. -`openclaw config schema` виводить канонічну JSON Schema, яку використовують Control UI -і валідація. `config.schema.lookup` отримує один вузол, обмежений шляхом, разом зі -зведеннями дочірніх елементів для інструментів деталізації. Метадані документації полів `title`/`description` -передаються через вкладені об’єкти, wildcard (`*`), елементи масиву (`[]`) і гілки `anyOf`/ -`oneOf`/`allOf`. Схеми Plugin і каналів часу виконання об’єднуються, коли +`openclaw config schema` друкує канонічну JSON Schema, яку використовують інтерфейс керування +і валідація. `config.schema.lookup` отримує один вузол з обмеженням за шляхом і +зведення дочірніх елементів для інструментів деталізації. Метадані документації полів `title`/`description` +передаються через вкладені об’єкти, wildcard (`*`), елементи масиву (`[]`) та гілки `anyOf`/ +`oneOf`/`allOf`. Схеми runtime plugin і каналів об’єднуються, коли завантажено реєстр маніфестів. Коли валідація не проходить: -- Gateway не запускається +- Gateway не завантажується - Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) - Запустіть `openclaw doctor`, щоб побачити точні проблеми - Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway зберігає довірену останню справну копію після кожного успішного запуску. -Якщо `openclaw.json` пізніше не проходить валідацію (або втрачає `gateway.mode`, різко -зменшується чи має випадково доданий на початку рядок журналу), OpenClaw зберігає пошкоджений файл -як `.clobbered.*`, відновлює останню справну копію й записує причину відновлення -до журналу. Наступний хід агента також отримує попередження системної події, щоб основний -агент не переписав відновлену конфігурацію наосліп. Підвищення до останньої справної -копії пропускається, коли кандидат містить відредаговані заповнювачі секретів, як-от `***`. -Коли кожна проблема валідації обмежена `plugins.entries....`, OpenClaw -не виконує відновлення всього файлу. Він залишає поточну конфігурацію активною й -показує локальний збій Plugin, щоб невідповідність схеми Plugin або версії хоста -не могла відкотити непов’язані налаштування користувача. +Gateway зберігає довірену останню відому справну копію після кожного успішного запуску, +але запуск і гаряче перезавантаження не відновлюють її автоматично. Якщо `openclaw.json` +не проходить валідацію (зокрема локальну валідацію plugin), запуск Gateway завершується помилкою або +перезавантаження пропускається, а поточний runtime зберігає останню прийняту конфігурацію. +Запустіть `openclaw doctor --fix` (або `--yes`), щоб виправити конфігурацію з префіксами/перезаписами або +відновити останню відому справну копію. Просування до останньої відомої справної копії пропускається, коли +кандидат містить редаговані заповнювачі секретів, як-от `***`. ## Поширені завдання - - Кожен канал має власний розділ конфігурації в `channels.`. Див. окрему сторінку каналу для кроків налаштування: + + Кожен канал має власний розділ конфігурації під `channels.`. Див. спеціальну сторінку каналу для кроків налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` - [Telegram](/uk/channels/telegram) — `channels.telegram` @@ -142,8 +138,8 @@ Gateway зберігає довірену останню справну копі - - Установіть основну модель і необов’язкові резервні варіанти: + + Задайте основну модель і необов’язкові резервні варіанти: ```json5 { @@ -162,31 +158,31 @@ Gateway зберігає довірену останню справну копі } ``` - - `agents.defaults.models` визначає каталог моделей і діє як allowlist для `/model`. - - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи allowlist без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`. + - `agents.defaults.models` визначає каталог моделей і працює як allowlist для `/model`. + - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи allowlist без видалення наявних моделей. Прості заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням зображень транскрипту/інструментів (стандартно `1200`); нижчі значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю знімків екрана. - - Див. [CLI моделей](/uk/concepts/models) для перемикання моделей у чаті та [резервування моделей](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервних варіантів. - - Для власних або self-hosted провайдерів див. [власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls) у довіднику. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням зображень у стенограмі/інструментах (за замовчуванням `1200`); нижчі значення зазвичай зменшують використання vision-token у запусках із великою кількістю скриншотів. + - Див. [CLI моделей](/uk/concepts/models) для перемикання моделей у чаті та [Відмовостійкість моделей](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервних варіантів. + - Для власних/самостійно розгорнутих провайдерів див. [Власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls) у довіднику. - - Доступ до DM керується для кожного каналу через `dmPolicy`: + + Доступ DM керується окремо для кожного каналу через `dmPolicy`: - - `"pairing"` (стандартно): невідомі відправники отримують одноразовий код сполучення для схвалення - - `"allowlist"`: лише відправники в `allowFrom` (або у сховищі дозволених після сполучення) - - `"open"`: дозволити всі вхідні DM (потребує `allowFrom: ["*"]`) + - `"pairing"` (за замовчуванням): невідомі відправники отримують одноразовий код спарювання для схвалення + - `"allowlist"`: лише відправники в `allowFrom` (або у сховищі дозволених спарених) + - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) - `"disabled"`: ігнорувати всі DM Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. - Див. [повний довідник](/uk/gateway/config-channels#dm-and-group-access) для подробиць за каналами. + Див. [повний довідник](/uk/gateway/config-channels#dm-and-group-access) для деталей за каналами. - - Групові повідомлення стандартно **вимагають згадки**. Налаштуйте шаблони тригерів для кожного агента й залишайте видимі відповіді в кімнаті на стандартному шляху інструмента повідомлень, якщо ви навмисно не хочете застарілих автоматичних фінальних відповідей: + + Групові повідомлення за замовчуванням **вимагають згадки**. Налаштуйте шаблони тригерів для кожного агента й залишайте видимі відповіді в кімнаті на стандартному шляху message-tool, якщо ви навмисно не хочете застарілі автоматичні фінальні відповіді: ```json5 { @@ -216,14 +212,14 @@ Gateway зберігає довірену останню справну копі - **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) - **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns` - - **Видимі відповіді**: `messages.visibleReplies` може вимагати надсилання через інструмент повідомлень глобально; `messages.groupChat.visibleReplies` перевизначає це для груп/каналів. - - Див. [повний довідник](/uk/gateway/config-channels#group-chat-mention-gating) для режимів видимих відповідей, перевизначень за каналами та режиму self-chat. + - **Видимі відповіді**: `messages.visibleReplies` може вимагати надсилання через message-tool глобально; `messages.groupChat.visibleReplies` перевизначає це для груп/каналів. + - Див. [повний довідник](/uk/gateway/config-channels#group-chat-mention-gating) для режимів видимих відповідей, перевизначень за каналами та режиму чату із самим собою. - - Використовуйте `agents.defaults.skills` для спільної бази, а потім перевизначайте конкретних - агентів через `agents.list[].skills`: + + Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте окремих + агентів за допомогою `agents.list[].skills`: ```json5 { @@ -240,16 +236,16 @@ Gateway зберігає довірену останню справну копі } ``` - - Не вказуйте `agents.defaults.skills`, щоб Skills були необмеженими за замовчуванням. - - Не вказуйте `agents.list[].skills`, щоб успадкувати стандартні значення. - - Установіть `agents.list[].skills: []`, щоб вимкнути Skills. - - Див. [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і + - Опустіть `agents.defaults.skills`, щоб Skills за замовчуванням були необмежені. + - Опустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням. + - Встановіть `agents.list[].skills: []`, щоб Skills не було. + - Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [довідник конфігурації](/uk/gateway/config-agents#agents-defaults-skills). - - Керуйте тим, наскільки агресивно gateway перезапускає канали, що здаються неактивними: + + Керуйте тим, наскільки агресивно Gateway перезапускає канали, що виглядають застарілими: ```json5 { @@ -271,16 +267,16 @@ Gateway зберігає довірену останню справну копі } ``` - - Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану. + - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски health-monitor. - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоматичні перезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. - - Див. [перевірки стану](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Див. [Перевірки стану](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - - Дайте локальним клієнтам більше часу завершити pre-auth WebSocket handshake на - завантажених або малопотужних хостах: + + Дайте локальним клієнтам більше часу на завершення pre-auth WebSocket-рукостискання на + навантажених або малопотужних хостах: ```json5 { @@ -290,14 +286,14 @@ Gateway зберігає довірену останню справну копі } ``` - - Стандартне значення — `15000` мілісекунд. + - За замовчуванням `15000` мілісекунд. - `OPENCLAW_HANDSHAKE_TIMEOUT_MS` усе ще має пріоритет для одноразових перевизначень сервісу або shell. - - Спочатку бажано виправити зависання запуску/циклу подій; цей параметр призначений для хостів, які справні, але повільні під час прогрівання. + - Спершу краще виправити зависання запуску/event-loop; цей регулятор призначений для хостів, які справні, але повільні під час прогрівання. - - Сеанси керують безперервністю та ізоляцією розмови: + + Сеанси керують безперервністю та ізоляцією розмов: ```json5 { @@ -318,14 +314,14 @@ Gateway зберігає довірену останню справну копі ``` - `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: глобальні типові значення для маршрутизації сеансів, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Див. [Керування сеансами](/uk/concepts/session) щодо областей дії, зв’язків ідентичностей і політики надсилання. + - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сеансів, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Див. [Керування сеансами](/uk/concepts/session) для областей дії, зв’язків ідентичностей і політики надсилання. - Див. [повний довідник](/uk/gateway/config-agents#session) для всіх полів. - - Запускайте сеанси агентів в ізольованих середовищах sandbox: + + Запускайте сеанси агентів в ізольованих середовищах виконання: ```json5 { @@ -340,14 +336,14 @@ Gateway зберігає довірену останню справну копі } ``` - Спочатку зберіть образ — з вихідного checkout виконайте `scripts/sandbox-setup.sh`, або для встановлення з npm див. вбудовану команду `docker build` у [Sandboxing § Images and setup](/uk/gateway/sandboxing#images-and-setup). + Спочатку зберіть образ — із робочої копії джерельного коду запустіть `scripts/sandbox-setup.sh`, або для встановлення з npm дивіться вбудовану команду `docker build` у розділі [Ізоляція § Образи та налаштування](/uk/gateway/sandboxing#images-and-setup). - Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/config-agents#agentsdefaultssandbox) для всіх параметрів. + Дивіться [Ізоляція](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/config-agents#agentsdefaultssandbox) для всіх параметрів. - - Push через ретранслятор налаштовується в `openclaw.json`. + + Relay-backed push налаштовується в `openclaw.json`. Задайте це в конфігурації Gateway: @@ -375,35 +371,35 @@ Gateway зберігає довірену останню справну копі Що це робить: - - Дає Gateway змогу надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній ретранслятор. - - Використовує дозвіл на надсилання, прив’язаний до реєстрації, який пересилає спарений застосунок iOS. Gateway не потребує токена ретранслятора для всього розгортання. - - Прив’язує кожну реєстрацію через ретранслятор до ідентичності Gateway, з якою спарено застосунок iOS, тому інший Gateway не може повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямих APNs. Надсилання через ретранслятор застосовується лише до офіційних розповсюджених збірок, які зареєструвалися через ретранслятор. - - Має збігатися з базовим URL ретранслятора, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання потрапляв до того самого розгортання ретранслятора. + - Дає змогу gateway надсилати `push.test`, wake nudges і reconnect wakes через зовнішній relay. + - Використовує scoped-to-registration дозвіл на надсилання, переданий спареним застосунком iOS. Gateway не потребує relay-токена для всього розгортання. + - Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з яким було спарено застосунок iOS, тож інший gateway не зможе повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямих APNs. Relay-backed надсилання застосовуються лише до офіційних розповсюджуваних збірок, зареєстрованих через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. - Наскрізний потік: + Наскрізний процес: - 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL ретранслятора. - 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на Gateway. - 3. Спарте застосунок iOS із Gateway і дайте підключитися сеансам вузла та оператора. - 4. Застосунок iOS отримує ідентичність Gateway, реєструється в ретрансляторі за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через ретранслятор у спарений Gateway. - 5. Gateway зберігає handle ретранслятора й дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для повторного підключення. + 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. + 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. + 3. Спарте застосунок iOS із gateway і дайте змогу сеансам node та оператора підключитися. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` у спарений gateway. + 5. Gateway зберігає relay handle і дозвіл на надсилання, а потім використовує їх для `push.test`, wake nudges і reconnect wakes. Операційні примітки: - - Якщо перемкнути застосунок iOS на інший Gateway, повторно підключіть застосунок, щоб він міг опублікувати нову реєстрацію ретранслятора, прив’язану до цього Gateway. - - Якщо випустити нову збірку iOS, яка вказує на інше розгортання ретранслятора, застосунок оновлює кешовану реєстрацію ретранслятора замість повторного використання старого походження ретранслятора. + - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. + - Якщо ви постачаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свою кешовану relay-реєстрацію замість повторного використання старого relay origin. Примітка щодо сумісності: - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається обхідним механізмом розробки лише для local loopback; не зберігайте HTTP URL ретранслятора в конфігурації. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається лише для розробки через loopback; не зберігайте HTTP URL relay у конфігурації. - Див. [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) щодо наскрізного потоку та [Автентифікація й потік довіри](/uk/platforms/ios#authentication-and-trust-flow) щодо моделі безпеки ретранслятора. + Дивіться [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Потік автентифікації та довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. - + ```json5 { agents: { @@ -419,12 +415,12 @@ Gateway зберігає довірену останню справну копі - `every`: рядок тривалості (`30m`, `2h`). Задайте `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад `discord`, `matrix`, `telegram` або `whatsapp`) - - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM - - Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника. + - `directPolicy`: `allow` (за замовчуванням) або `block` для DM-style цілей heartbeat + - Дивіться [Heartbeat](/uk/gateway/heartbeat) для повного посібника. - + ```json5 { cron: { @@ -439,14 +435,14 @@ Gateway зберігає довірену останню справну копі } ``` - - `sessionRetention`: очищати завершені ізольовані сеанси запусків із `sessions.json` (типово `24h`; задайте `false`, щоб вимкнути). - - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду можливості та прикладів CLI. + - `sessionRetention`: очищає завершені ізольовані сеанси запусків із `sessions.json` (за замовчуванням `24h`; задайте `false`, щоб вимкнути). + - `runLog`: очищає `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Дивіться [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI. - - Увімкніть HTTP Webhook endpoints на Gateway: + + Увімкніть HTTP webhook endpoint-и на Gateway: ```json5 { @@ -470,20 +466,20 @@ Gateway зберігає довірену останню справну копі ``` Примітка щодо безпеки: - - Вважайте весь вміст payload hook/webhook ненадійними вхідними даними. + - Сприймайте весь вміст payload hook/webhook як недовірені вхідні дані. - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в query string відхиляються. - - `hooks.path` не може бути `/`; тримайте вхідний Webhook на окремому підшляху, наприклад `/hooks`. - - Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузько обмежене налагодження. - - Якщо ввімкнути `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сеансів, вибрані викликачем. - - Для агентів, керованих hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де можливо). + - `hooks.path` не може бути `/`; тримайте webhook ingress на окремому підшляху, наприклад `/hooks`. + - Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте чітко обмежене налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити session keys, вибрані викликачем. + - Для агентів, керованих hooks, надавайте перевагу сильним сучасним рівням моделей і строгій політиці інструментів (наприклад, лише messaging плюс ізоляція, де це можливо). - Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів зіставлення та інтеграції Gmail. + Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mapping і інтеграції Gmail. - - Запускайте кілька ізольованих агентів з окремими робочими просторами та сеансами: + + Запускайте кількох ізольованих агентів з окремими робочими просторами та сеансами: ```json5 { @@ -500,11 +496,11 @@ Gateway зберігає довірену останню справну копі } ``` - Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/config-agents#multi-agent-routing) щодо правил прив’язки та профілів доступу для кожного агента. + Дивіться [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/config-agents#multi-agent-routing) для правил binding і профілів доступу для окремих агентів. - + Використовуйте `$include`, щоб упорядкувати великі конфігурації: ```json5 @@ -519,56 +515,51 @@ Gateway зберігає довірену останню справну копі ``` - **Один файл**: замінює об’єкт, що його містить - - **Масив файлів**: глибоко об’єднується за порядком (пізніший перемагає) - - **Сусідні ключі**: об’єднуються після include (перевизначають включені значення) - - **Вкладені include**: підтримуються до 10 рівнів углиб - - **Відносні шляхи**: розв’язуються відносно файлу, що виконує include - - **Записи, якими володіє OpenClaw**: коли запис змінює лише один розділ верхнього рівня, - підкріплений include одного файлу, наприклад `plugins: { $include: "./plugins.json5" }`, + - **Масив файлів**: глибоко об’єднується за порядком (пізніший має пріоритет) + - **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення) + - **Вкладені includes**: підтримуються до 10 рівнів углиб + - **Відносні шляхи**: розв’язуються відносно файлу, який виконує include + - **Записи, що належать OpenClaw**: коли запис змінює лише один розділ верхнього рівня, + підкріплений однофайловим include, наприклад `plugins: { $include: "./plugins.json5" }`, OpenClaw оновлює цей включений файл і залишає `openclaw.json` без змін - - **Непідтримуваний write-through**: кореневі include, масиви include та include - із сусідніми перевизначеннями відмовляють закрито для записів, якими володіє OpenClaw, замість - згладжування конфігурації + - **Непідтримуваний write-through**: кореневі includes, масиви includes і includes + із сусідніми перевизначеннями завершуються закрито для записів, що належать OpenClaw, замість + flattening конфігурації - **Обмеження**: шляхи `$include` мають розв’язуватися в межах каталогу, що містить `openclaw.json`. Щоб спільно використовувати дерево між машинами або користувачами, задайте - `OPENCLAW_INCLUDE_ROOTS` як список шляхів (`:` у POSIX, `;` у Windows) до - додаткових каталогів, на які можуть посилатися include. Симлінки розв’язуються - і перевіряються повторно, тому шлях, який лексично перебуває в каталозі конфігурації, але реальна - ціль якого виходить за межі кожного дозволеного кореня, усе одно відхиляється. - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору та циклічних include + `OPENCLAW_INCLUDE_ROOTS` як список шляхів (`:` на POSIX, `;` на Windows) до + додаткових каталогів, на які можуть посилатися includes. Символічні посилання розв’язуються + й перевіряються повторно, тому шлях, який лексично розташований у каталозі конфігурації, але чия + реальна ціль виходить за межі кожного дозволеного кореня, усе одно відхиляється. + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних includes ## Гаряче перезавантаження конфігурації -Gateway відстежує `~/.openclaw/openclaw.json` і застосовує зміни автоматично — для більшості налаштувань ручний перезапуск не потрібен. +Gateway відстежує `~/.openclaw/openclaw.json` і застосовує зміни автоматично — ручний перезапуск не потрібен для більшості налаштувань. -Прямі редагування файлу вважаються ненадійними, доки не пройдуть перевірку. Watcher чекає, -доки завершаться тимчасові записи/перейменування редактора, читає остаточний файл і відхиляє -недійсні зовнішні редагування, відновлюючи останню справну конфігурацію. Записи конфігурації, -якими володіє OpenClaw, використовують той самий schema gate перед записом; руйнівні перезаписи, -як-от видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються -і зберігаються як `.rejected.*` для перевірки. +Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Watcher чекає, +поки вщухне churn тимчасового запису/перейменування редактора, читає фінальний файл і відхиляє +некоректні зовнішні редагування без переписування `openclaw.json`. Записи конфігурації, що належать OpenClaw, +використовують той самий schema gate перед записом; руйнівні clobbers, як-от +видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються та +зберігаються як `.rejected.*` для перевірки. -Помилки локальної перевірки Plugin є винятком: якщо всі проблеми перебувають під -`plugins.entries....`, перезавантаження зберігає поточну конфігурацію й повідомляє про проблему -Plugin замість відновлення `.last-good`. - -Якщо в журналах ви бачите `Config auto-restored from last-known-good` або -`config reload restored last-known-good config`, перегляньте відповідний файл -`.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте -`openclaw config validate`. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) -для контрольного списку відновлення. +Якщо ви бачите `config reload skipped (invalid config)` або під час запуску повідомляється `Invalid +config`, перевірте конфігурацію, запустіть `openclaw config validate`, а потім запустіть `openclaw +doctor --fix` для ремонту. Дивіться [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config) +для контрольного списку. ### Режими перезавантаження | Режим | Поведінка | | ---------------------- | --------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | -| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його. | +| **`hybrid`** (default) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускає для критичних. | +| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — ви обробляєте це. | | **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | -| **`off`** | Вимикає відстеження файлів. Зміни набувають чинності під час наступного ручного перезапуску. | +| **`off`** | Вимикає відстеження файлів. Зміни набирають чинності під час наступного ручного перезапуску. | ```json5 { @@ -580,55 +571,56 @@ Plugin замість відновлення `.last-good`. ### Що застосовується гаряче, а що потребує перезапуску -Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. +Більшість полів гаряче застосовуються без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. -| Категорія | Поля | Потрібен перезапуск? | -| ------------------- | ----------------------------------------------------------------- | --------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та Plugin-канали | Ні | -| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | -| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сеанси й повідомлення | `session`, `messages` | Ні | -| Інструменти й медіа | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | Ні | -| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | -| Сервер Gateway | `gateway.*` (порт, прив’язка, автентифікація, tailscale, TLS, HTTP) | **Так** | -| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | +| Категорія | Поля | Потрібен перезапуск? | +| ------------------ | ----------------------------------------------------------------- | -------------------- | +| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані та plugin канали | Ні | +| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | +| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | +| Сеанси й повідомлення | `session`, `messages` | Ні | +| Інструменти й медіа | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | Ні | +| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | +| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | +| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` є винятками — їх зміна **не** запускає перезапуск. +`gateway.reload` і `gateway.remote` є винятками — їхня зміна **не** запускає перезапуск. ### Планування перезавантаження Коли ви редагуєте вихідний файл, на який є посилання через `$include`, OpenClaw планує -перезавантаження з авторського макета джерела, а не зі сплощеного подання в пам’яті. -Це зберігає передбачуваність рішень щодо гарячого перезавантаження (гаряче застосування чи перезапуск), навіть коли -один розділ верхнього рівня міститься у власному включеному файлі, наприклад -`plugins: { $include: "./plugins.json5" }`. Планування перезавантаження завершується закрито, якщо +перезавантаження на основі авторського макета джерела, а не вирівняного подання в пам’яті. +Це робить рішення щодо гарячого перезавантаження (гаряче застосування чи перезапуск) +передбачуваними, навіть коли один верхньорівневий розділ міститься у власному включеному файлі, наприклад +`plugins: { $include: "./plugins.json5" }`. Планування перезавантаження завершується без змін, якщо макет джерела неоднозначний. ## Config RPC (програмні оновлення) -Для інструментів, які записують конфігурацію через API Gateway, віддавайте перевагу такому потоку: +Для інструментів, які записують конфігурацію через API Gateway, надавайте перевагу такому процесу: -- `config.schema.lookup`, щоб переглянути одне піддерево (поверхневий вузол схеми + зведення дочірніх елементів) +- `config.schema.lookup`, щоб переглянути одне піддерево (неглибокий вузол схеми + зведення + дочірніх елементів) - `config.get`, щоб отримати поточний знімок разом із `hash` - `config.patch` для часткових оновлень (JSON merge patch: об’єкти об’єднуються, `null` видаляє, масиви замінюються) - `config.apply` лише тоді, коли ви маєте намір замінити всю конфігурацію -- `update.run` для явного самооновлення з перезапуском; додайте `continuationMessage`, коли після перезапуску сеанс має виконати один наступний хід -- `update.status`, щоб переглянути останній sentinel перезапуску оновлення та перевірити запущену версію після перезапуску +- `update.run` для явного самооновлення разом із перезапуском; додайте `continuationMessage`, коли після перезапуску сесія має виконати один наступний хід +- `update.status`, щоб переглянути останній сторожовий маркер перезапуску після оновлення й перевірити запущену версію після перезапуску -Агенти мають розглядати `config.schema.lookup` як першу точку для точних +Агенти мають розглядати `config.schema.lookup` як перше місце для точних документів і обмежень на рівні полів. Використовуйте [Довідник конфігурації](/uk/gateway/configuration-reference), -коли їм потрібні ширша карта конфігурації, типові значення або посилання на окремі +коли потрібна ширша карта конфігурації, значення за замовчуванням або посилання на окремі довідники підсистем. Записи площини керування (`config.apply`, `config.patch`, `update.run`) -обмежені частотою до 3 запитів за 60 секунд на `deviceId+clientIp`. Запити на перезапуск -об’єднуються, а потім застосовують 30-секундне охолодження між циклами перезапуску. -`update.status` доступний лише для читання, але обмежений адміністративною областю, бо sentinel перезапуску може -містити зведення кроків оновлення та хвости виводу команд. +обмежені за частотою до 3 запитів за 60 секунд на `deviceId+clientIp`. Запити на перезапуск +об’єднуються, а потім застосовується 30-секундний період очікування між циклами перезапуску. +`update.status` доступний лише для читання, але обмежений адміністративною областю, оскільки сторожовий маркер перезапуску може +містити зведення кроків оновлення та кінцеві фрагменти виводу команд. Приклад часткового патча: @@ -642,7 +634,7 @@ openclaw gateway call config.patch --params '{ ``` І `config.apply`, і `config.patch` приймають `raw`, `baseHash`, `sessionKey`, -`note` і `restartDelayMs`. `baseHash` є обов’язковим для обох методів, коли +`note` та `restartDelayMs`. `baseHash` є обов’язковим для обох методів, коли конфігурація вже існує. ## Змінні середовища @@ -652,7 +644,7 @@ OpenClaw читає змінні середовища з батьківсько - `.env` з поточного робочого каталогу (якщо є) - `~/.openclaw/.env` (глобальний резервний варіант) -Жоден із файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: +Жоден із цих файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: ```json5 { @@ -663,8 +655,8 @@ OpenClaw читає змінні середовища з батьківсько } ``` - - Якщо ввімкнено й очікувані ключі не задані, OpenClaw запускає вашу оболонку входу та імпортує лише відсутні ключі: + + Якщо ввімкнено і очікувані ключі не задані, OpenClaw запускає вашу login shell та імпортує лише відсутні ключі: ```json5 { @@ -677,7 +669,7 @@ OpenClaw читає змінні середовища з батьківсько Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1` - + Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: ```json5 @@ -689,15 +681,15 @@ OpenClaw читає змінні середовища з батьківсько Правила: -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Збігаються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` - Відсутні або порожні змінні спричиняють помилку під час завантаження -- Екрануйте через `$${VAR}` для буквального виводу +- Екрануйте за допомогою `$${VAR}` для буквального виводу - Працює всередині файлів `$include` - Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - + Для полів, які підтримують об’єкти SecretRef, можна використовувати: ```json5 @@ -730,15 +722,15 @@ OpenClaw читає змінні середовища з батьківсько } ``` -Відомості про SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) наведено в [Керуванні секретами](/uk/gateway/secrets). -Підтримувані шляхи облікових даних наведено в [Поверхні облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Подробиці SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) наведені в [Керуванні секретами](/uk/gateway/secrets). +Підтримувані шляхи облікових даних перелічені в [Поверхні облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Див. [Середовище](/uk/help/environment) для повного пріоритету та джерел. +Див. [Середовище](/uk/help/environment), щоб дізнатися повний пріоритет і джерела. ## Повний довідник -Повний довідник по кожному полю див. у **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. +Повний довідник за всіма полями див. у **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. --- diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 38e1a2623..a8f16872b 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,24 +1,24 @@ --- read_when: - - Центр усунення несправностей спрямував вас сюди для глибшої діагностики + - Центр усунення несправностей скерував вас сюди для глибшої діагностики - Потрібні стабільні розділи операційного посібника на основі симптомів із точними командами sidebarTitle: Troubleshooting -summary: Поглиблений операційний посібник з усунення несправностей для Gateway, каналів, автоматизації, вузлів і браузера +summary: Поглиблений регламент усунення несправностей для Gateway, каналів, автоматизації, вузлів і браузера title: Усунення несправностей x-i18n: - generated_at: "2026-05-01T20:37:53Z" + generated_at: "2026-05-03T17:12:04Z" model: gpt-5.5 provider: openai - source_hash: 815fbbca4d12b4b9c65b1172e07606d0eaf4c64df7fd6ca23a8f8d104b78c2a9 + source_hash: 19422615706ca09124b19dd3e21b2c13391d6daf2b1807e01b4ce2047d02e522 source_path: gateway/troubleshooting.md workflow: 16 --- -Ця сторінка є докладним операційним посібником. Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу хочете пройти швидкий процес діагностики. +Ця сторінка — докладний runbook. Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу потрібен швидкий потік тріажу. -## Послідовність команд +## Драбина команд -Спочатку виконайте ці команди в такому порядку: +Спершу виконайте ці команди в такому порядку: ```bash openclaw status @@ -32,13 +32,13 @@ openclaw channels status --probe - `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`. - `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації чи служби. -- `openclaw channels status --probe` показує актуальний статус транспорту для кожного облікового запису та, де підтримується, результати перевірки/аудиту, як-от `works` або `audit ok`. +- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису і, де підтримується, результати проби/аудиту, як-от `works` або `audit ok`. -## Розсинхронізовані інсталяції та захист від новішої конфігурації +## Split brain-встановлення й захист від новішої конфігурації Використовуйте це, коли служба Gateway несподівано зупиняється після оновлення або журнали показують, що один бінарний файл `openclaw` старіший за версію, яка востаннє записувала `openclaw.json`. -OpenClaw позначає записи конфігурації через `meta.lastTouchedVersion`. Команди лише для читання все ще можуть переглядати конфігурацію, записану новішою версією OpenClaw, але операції, що змінюють процеси й служби, відмовляються продовжувати роботу зі старішого бінарного файлу. Заблоковані дії включають запуск, зупинку, перезапуск і видалення служби Gateway, примусове перевстановлення служби, запуск Gateway у режимі служби та очищення порту через `gateway --force`. +OpenClaw позначає записи конфігурації через `meta.lastTouchedVersion`. Команди лише для читання все ще можуть перевіряти конфігурацію, записану новішим OpenClaw, але мутації процесів і служб відмовляються продовжувати роботу зі старішого бінарного файла. Заблоковані дії включають запуск, зупинку, перезапуск, видалення служби Gateway, примусове перевстановлення служби, запуск Gateway у режимі служби та очищення порту через `gateway --force`. ```bash which openclaw @@ -49,10 +49,10 @@ openclaw config get meta.lastTouchedVersion - Виправте `PATH`, щоб `openclaw` вказував на новішу інсталяцію, а потім повторно виконайте дію. + Виправте `PATH`, щоб `openclaw` указував на новіше встановлення, а потім повторно виконайте дію. - Перевстановіть потрібну службу Gateway із новішої інсталяції: + Перевстановіть потрібну службу Gateway із новішого встановлення: ```bash openclaw gateway install --force @@ -61,15 +61,15 @@ openclaw config get meta.lastTouchedVersion - Видаліть застарілий системний пакет або старі записи обгорток, які все ще вказують на старий бінарний файл `openclaw`. + Видаліть застарілі записи системного пакета або старої обгортки, які досі вказують на старий бінарний файл `openclaw`. -Лише для навмисного зниження версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для нормальної роботи залишайте її невстановленою. +Лише для навмисного відкату версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для звичайної роботи залиште це значення невстановленим. -## Anthropic 429: для довгого контексту потрібне додаткове використання +## Для довгого контексту Anthropic 429 потрібне додаткове використання Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. @@ -81,9 +81,9 @@ openclaw config get agents.defaults.models Шукайте: -- Обрана модель Anthropic Opus/Sonnet має `params.context1m: true`. -- Поточні облікові дані Anthropic не придатні для використання довгого контексту. -- Запити завершуються помилкою лише в довгих сесіях/запусках моделей, яким потрібен beta-шлях 1M. +- Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. +- Поточні облікові дані Anthropic не мають права на використання довгого контексту. +- Запити падають лише в довгих сесіях/запусках моделі, яким потрібен beta-шлях 1M. Варіанти виправлення: @@ -99,19 +99,19 @@ openclaw config get agents.defaults.models -Пов’язано: +Пов’язане: - [Anthropic](/uk/providers/anthropic) - [Використання токенів і витрати](/uk/reference/token-use) - [Чому я бачу HTTP 429 від Anthropic?](/uk/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-сумісний бекенд проходить прямі перевірки, але запуски агента завершуються помилкою +## Локальний OpenAI-сумісний бекенд проходить прямі проби, але запуски агента падають Використовуйте це, коли: - `curl ... /v1/models` працює -- малі прямі виклики `/v1/chat/completions` працюють -- запуски моделей OpenClaw завершуються помилкою лише під час звичайних ходів агента +- крихітні прямі виклики `/v1/chat/completions` працюють +- Запуски моделей OpenClaw падають лише на звичайних ходах агента ```bash curl http://127.0.0.1:1234/v1/models @@ -124,39 +124,39 @@ openclaw logs --follow Шукайте: -- малі прямі виклики успішні, але запуски OpenClaw завершуються помилкою лише на більших промптах +- прямі крихітні виклики успішні, але запуски OpenClaw падають лише на більших промптах - помилки `model_not_found` або 404, хоча прямий `/v1/chat/completions` - працює з тим самим ідентифікатором моделі без префікса + працює з тим самим простим ідентифікатором моделі - помилки бекенду про те, що `messages[].content` очікує рядок - періодичні попередження `incomplete turn detected ... stopReason=stop payloads=0` з OpenAI-сумісним локальним бекендом -- збої бекенду, які з’являються лише за більшої кількості токенів промпту або повних промптів середовища виконання агента +- падіння бекенду, які з’являються лише з більшою кількістю prompt-токенів або повними промптами runtime агента - - - `model_not_found` з локальним сервером у стилі MLX/vLLM → перевірте, що `baseUrl` містить `/v1`, `api` має значення `"openai-completions"` для бекендів `/v1/chat/completions`, а `models.providers..models[].id` є локальним ідентифікатором провайдера без префікса. Виберіть її один раз із префіксом провайдера, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; залиште запис каталогу як `mlx-community/Qwen3-30B-A3B-6bit`. - - `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: установіть `models.providers..models[].compat.requiresStringContent: true`. - - `incomplete turn detected ... stopReason=stop payloads=0` → бекенд завершив запит Chat Completions, але не повернув видимого користувачу тексту асистента для цього ходу. OpenClaw один раз повторює порожні OpenAI-сумісні ходи, безпечні для повторного відтворення; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді. - - малі прямі запити успішні, але запуски агента OpenClaw завершуються збоями бекенду/моделі (наприклад Gemma на деяких збірках `inferrs`) → транспорт OpenClaw, імовірно, вже налаштований правильно; бекенд не справляється з більшою формою промпту середовища виконання агента. - - збоїв стає менше після вимкнення інструментів, але вони не зникають → схеми інструментів були частиною навантаження, але залишкова проблема все ще полягає в обмеженнях моделі/сервера вище за стеком або помилці бекенду. + + - `model_not_found` із локальним сервером у стилі MLX/vLLM → перевірте, що `baseUrl` містить `/v1`, `api` є `"openai-completions"` для бекендів `/v1/chat/completions`, а `models.providers..models[].id` є простим локальним ідентифікатором провайдера. Виберіть його один раз із префіксом провайдера, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; запис каталогу залиште як `mlx-community/Qwen3-30B-A3B-6bit`. + - `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть `models.providers..models[].compat.requiresStringContent: true`. + - `incomplete turn detected ... stopReason=stop payloads=0` → бекенд завершив запит Chat Completions, але не повернув видимого користувачу тексту асистента для цього ходу. OpenClaw один раз повторює replay-safe порожні OpenAI-сумісні ходи; сталі збої зазвичай означають, що бекенд видає порожній/нетекстовий вміст або пригнічує текст фінальної відповіді. + - прямі крихітні запити успішні, але запуски агента OpenClaw падають через аварії бекенду/моделі (наприклад Gemma в деяких збірках `inferrs`) → транспорт OpenClaw, імовірно, уже правильний; бекенд падає на більшій формі промпта runtime агента. + - збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів були частиною навантаження, але залишкова проблема все ще в місткості upstream-моделі/сервера або помилці бекенду. - 1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, що підтримують лише рядковий вміст. + 1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, які приймають лише рядки. 2. Установіть `compat.supportsTools: false` для моделей/бекендів, які не можуть надійно обробляти поверхню схем інструментів OpenClaw. - 3. Зменште навантаження промпту, де це можливо: менша початкова ініціалізація робочої області, коротша історія сесії, легша локальна модель або бекенд із кращою підтримкою довгого контексту. - 4. Якщо малі прямі запити й далі проходять, а ходи агента OpenClaw все ще падають усередині бекенду, вважайте це обмеженням upstream-сервера/моделі та подайте туди відтворення з прийнятою формою корисного навантаження. + 3. За можливості зменште навантаження промпта: менший bootstrap робочої області, коротша історія сесії, легша локальна модель або бекенд із сильнішою підтримкою довгого контексту. + 4. Якщо крихітні прямі запити й далі проходять, а ходи агента OpenClaw досі падають усередині бекенду, розглядайте це як upstream-обмеження сервера/моделі й подайте туди відтворення з прийнятою формою payload. -Пов’язано: +Пов’язане: - [Конфігурація](/uk/gateway/configuration) - [Локальні моделі](/uk/gateway/local-models) -- [OpenAI-сумісні кінцеві точки](/uk/gateway/configuration-reference#openai-compatible-endpoints) +- [OpenAI-сумісні endpoints](/uk/gateway/configuration-reference#openai-compatible-endpoints) ## Немає відповідей -Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію й політику, перш ніж щось перепідключати. +Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. ```bash openclaw status @@ -168,25 +168,25 @@ openclaw logs --follow Шукайте: -- Очікується сполучення для відправників приватних повідомлень. -- Обмеження групових згадок (`requireMention`, `mentionPatterns`). -- Невідповідності списку дозволених каналів/груп. +- Очікуване сполучення для відправників DM. +- Обмеження згадками в групах (`requireMention`, `mentionPatterns`). +- Невідповідності allowlist каналу/групи. -Поширені ознаки: +Типові ознаки: - `drop guild message (mention required` → групове повідомлення ігнорується до згадки. -- `pairing request` → відправник потребує схвалення. -- `blocked` / `allowlist` → відправника/канал відфільтровано політикою. +- `pairing request` → відправнику потрібне схвалення. +- `blocked` / `allowlist` → відправника/канал було відфільтровано політикою. -Пов’язано: +Пов’язане: - [Усунення несправностей каналів](/uk/channels/troubleshooting) - [Групи](/uk/channels/groups) - [Сполучення](/uk/channels/pairing) -## Підключення панелі керування +## Підключення dashboard control UI -Коли панель або інтерфейс керування не підключається, перевірте URL, режим автентифікації та припущення щодо захищеного контексту. +Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо захищеного контексту. ```bash openclaw gateway status @@ -198,40 +198,40 @@ openclaw gateway status --json Шукайте: -- Правильні URL перевірки та панелі керування. -- Невідповідність режиму автентифікації/токена між клієнтом і Gateway. +- Правильний URL проби та URL dashboard. +- Невідповідність режиму автентифікації/токена між клієнтом і gateway. - Використання HTTP там, де потрібна ідентичність пристрою. - `device identity required` → незахищений контекст або відсутня автентифікація пристрою. - - `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` (або ви підключаєтеся з браузерного origin не через loopback без явного списку дозволених). - - `device nonce required` / `device nonce mismatch` → клієнт не завершує процес автентифікації пристрою на основі перевірочного виклику (`connect.challenge` + `device.nonce`). - - `device signature invalid` / `device signature expired` → клієнт підписав неправильне корисне навантаження (або застарілу часову мітку) для поточного узгодження. + - `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` (або ви підключаєтеся з не-loopback походження браузера без явного allowlist). + - `device nonce required` / `device nonce mismatch` → клієнт не завершує challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`). + - `device signature invalid` / `device signature expired` → клієнт підписав неправильний payload (або застарілу часову мітку) для поточного handshake. - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. - - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений зі сполученим токеном пристрою. Викликачі з явним `deviceToken` / явними `scopes` натомість зберігають запитаний набір scope. - - Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спершу явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач зафіксує збій. Тому дві невдалі одночасні повторні спроби від одного клієнта можуть показати `retry later` на другій спробі замість двох звичайних невідповідностей. - - `too many failed authentication attempts (retry later)` від loopback-клієнта з браузерним origin → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий лімітний сегмент. - - повторювані `unauthorized` після цієї повторної спроби → розсинхронізація спільного токена/токена пристрою; оновіть конфігурацію токена та за потреби повторно схваліть/ротуйту токен пристрою. - - `gateway connect failed:` → неправильна ціль хоста/порту/URL. + - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом зі сполученим токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний набір scope. + - За межами цього шляху повторної спроби пріоритет автентифікації connect такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач записує збій. Тому дві погані одночасні повторні спроби від того самого клієнта можуть показати `retry later` на другій спробі замість двох простих невідповідностей. + - `too many failed authentication attempts (retry later)` від browser-origin loopback-клієнта → повторні збої від того самого нормалізованого `Origin` тимчасово заблоковані; інше localhost-походження використовує окремий bucket. + - повторні `unauthorized` після цієї повторної спроби → розходження спільного токена/токена пристрою; оновіть конфігурацію токена й за потреби повторно схваліть/ротируйте токен пристрою. + - `gateway connect failed:` → неправильний хост/порт/url-ціль. -### Швидка мапа кодів деталей автентифікації +### Швидка мапа detail-кодів автентифікації -Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: +Використайте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: -| Код подробиць | Значення | Рекомендована дія | +| Код деталі | Значення | Рекомендована дія | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів панелі: `openclaw config get gateway.auth.token`, потім вставте його в налаштування Control UI. | -| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з auth-токеном gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scopes; виклики з явними `deviceToken` / `scopes` зберігають запитані scopes. Якщо помилка лишається, виконайте [контрольний список відновлення після дрейфу токена](/uk/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен окремого пристрою застарів або був відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), потім під’єднайтеся знову. | -| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade` і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve `. Оновлення scope/ролі використовують той самий потік після того, як ви переглянете запитаний доступ. | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав потрібний спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте в налаштування Control UI. | +| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені області доступу; явні виклики з `deviceToken` / `scopes` зберігають запитані області доступу. Якщо помилка не зникає, виконайте [контрольний список відновлення після розсинхронізації токена](/uk/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для окремого пристрою застарів або був відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), потім підключіться знову. | +| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використовуйте `requestId` / `remediationHint`, коли вони присутні. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. Оновлення областей доступу/ролей використовують той самий потік після перегляду запитаного доступу. | -Прямі backend RPC через loopback, автентифіковані спільним токеном/паролем gateway, не мають залежати від базової лінії scope для спареного пристрою в CLI. Якщо subagents або інші внутрішні виклики все ще завершуються помилкою `scope-upgrade`, перевірте, що виклик використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примусово задає явний `deviceIdentity` або токен пристрою. +Прямі loopback RPC бекенду, автентифіковані спільним токеном/паролем Gateway, не повинні залежати від базової лінії областей доступу сполученого пристрою CLI. Якщо subagents або інші внутрішні виклики все ще завершуються помилкою `scope-upgrade`, перевірте, що виклик використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примусово задає явний `deviceIdentity` або токен пристрою. Перевірка міграції автентифікації пристроїв v2: @@ -242,36 +242,36 @@ openclaw doctor openclaw gateway status ``` -Якщо журнали показують помилки nonce/signature, оновіть клієнт, що під’єднується, і перевірте його: +Якщо журнали показують помилки nonce/підпису, оновіть клієнт, що підключається, і перевірте його: - Клієнт чекає на виданий gateway `connect.challenge`. + Клієнт чекає на виданий Gateway `connect.challenge`. Клієнт підписує payload, прив’язаний до challenge. - Клієнт надсилає `connect.params.device.nonce` з тим самим nonce challenge. + Клієнт надсилає `connect.params.device.nonce` з тим самим challenge nonce. -Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхилено: +Якщо `openclaw devices rotate` / `revoke` / `remove` несподівано відхилено: -- сесії з токеном спареного пристрою можуть керувати лише **своїм власним** пристроєм, якщо виклик також не має `operator.admin` -- `openclaw devices rotate --scope ...` може запитувати лише scopes оператора, які сесія виклику вже має +- сесії з токеном сполученого пристрою можуть керувати лише **своїм власним** пристроєм, якщо виклик також не має `operator.admin` +- `openclaw devices rotate --scope ...` може запитувати лише операторські області доступу, які вже має сесія виклику Пов’язано: -- [Конфігурація](/uk/gateway/configuration) (режими автентифікації gateway) +- [Конфігурація](/uk/gateway/configuration) (режими автентифікації Gateway) - [Control UI](/uk/web/control-ui) - [Пристрої](/uk/cli/devices) - [Віддалений доступ](/uk/gateway/remote) - [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth) -## Служба Gateway не працює +## Сервіс Gateway не запущено -Використовуйте це, коли службу встановлено, але процес не залишається запущеним. +Використовуйте це, коли сервіс установлено, але процес не залишається запущеним. ```bash openclaw gateway status @@ -283,33 +283,34 @@ openclaw gateway status --deep # also scan system-level services Шукайте: -- `Runtime: stopped` з підказками щодо виходу. -- Невідповідність конфігурації служби (`Config (cli)` проти `Config (service)`). -- Конфлікти порту/listener. +- `Runtime: stopped` із підказками щодо виходу. +- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`). +- Конфлікти порту/слухача. - Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`. - Підказки очищення `Other gateway-like services detected (best effort)`. - - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим локального gateway не ввімкнено, або файл конфігурації було перезаписано й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб повторно проставити очікувану конфігурацію local-mode. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації — `~/.openclaw/openclaw.json`. - - `refusing to bind gateway ... without auth` → прив’язування не до loopback без дійсного шляху автентифікації gateway (token/password або trusted-proxy, де налаштовано). + - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим Gateway не ввімкнено, або файл конфігурації було перезаписано й він утратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у своїй конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб повторно проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях конфігурації: `~/.openclaw/openclaw.json`. + - `refusing to bind gateway ... without auth` → прив’язка не до loopback без чинного шляху автентифікації Gateway (токен/пароль або trusted-proxy, де налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. - - `Other gateway-like services detected (best effort)` → існують застарілі або паралельні units launchd/systemd/schtasks. У більшості налаштувань має бути один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). - - `System-level OpenClaw gateway service detected` від doctor → існує systemd system unit, тоді як служба рівня користувача відсутня. Видаліть або вимкніть дублікат, перш ніж дозволити doctor встановити користувацьку службу, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо system unit є запланованим супервізором. - - `Gateway service port does not match current gateway config` → встановлений supervisor досі закріплює старий `--port`. Запустіть `openclaw doctor --fix` або `openclaw gateway install --force`, потім перезапустіть службу gateway. + - `Other gateway-like services detected (best effort)` → існують застарілі або паралельні юніти launchd/systemd/schtasks. Більшість налаштувань має тримати один Gateway на машину; якщо вам потрібно більше ніж один, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). + - `System-level OpenClaw gateway service detected` від doctor → існує системний юніт systemd, тоді як сервіс рівня користувача відсутній. Видаліть або вимкніть дублікат перед тим, як дозволити doctor установити користувацький сервіс, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо системний юніт є потрібним supervisor. + - `Gateway service port does not match current gateway config` → установлений supervisor усе ще фіксує старий `--port`. Запустіть `openclaw doctor --fix` або `openclaw gateway install --force`, потім перезапустіть сервіс Gateway. Пов’язано: -- [Фоновий exec і process tool](/uk/gateway/background-process) +- [Фонове виконання та process tool](/uk/gateway/background-process) - [Конфігурація](/uk/gateway/configuration) - [Doctor](/uk/gateway/doctor) -## Gateway відновив останню відому справну конфігурацію +## Gateway відхилив недійсну конфігурацію -Використовуйте це, коли Gateway запускається, але журнали кажуть, що він відновив `openclaw.json`. +Використовуйте це, коли запуск Gateway завершується помилкою `Invalid config` або журнали гарячого перезавантаження кажуть, +що недійсну зміну пропущено. ```bash openclaw logs --follow @@ -320,19 +321,19 @@ openclaw doctor Шукайте: -- `Config auto-restored from last-known-good` -- `gateway: invalid config was restored from last-known-good backup` -- `config reload restored last-known-good config after invalid-config` -- Файл `openclaw.json.clobbered.*` з часовою міткою поруч з активною конфігурацією -- Системну подію main-agent, що починається з `Config recovery warning` +- `Invalid config at ...` +- `config reload skipped (invalid config): ...` +- `Config write rejected: ...` +- Файл `openclaw.json.rejected.*` із позначкою часу поруч з активною конфігурацією +- Файл `openclaw.json.clobbered.*` із позначкою часу, якщо `doctor --fix` відремонтував зламане пряме редагування - - Відхилена конфігурація не пройшла валідацію під час запуску або гарячого перезавантаження. - - OpenClaw зберіг відхилений payload як `.clobbered.*`. - - Активну конфігурацію було відновлено з останньої валідованої копії last-known-good. - - Наступний хід main-agent отримує попередження не переписувати відхилену конфігурацію наосліп. - - Якщо всі проблеми валідації були під `plugins.entries....`, OpenClaw не відновлював би весь файл. Локальні збої Plugin лишаються помітними, тоді як непов’язані користувацькі налаштування залишаються в активній конфігурації. + - Конфігурація не пройшла валідацію під час запуску, гарячого перезавантаження або запису, яким володіє OpenClaw. + - Запуск Gateway завершується закрито замість переписування `openclaw.json`. + - Гаряче перезавантаження пропускає недійсні зовнішні редагування та залишає поточну runtime-конфігурацію активною. + - Записи, якими володіє OpenClaw, відхиляють недійсні/руйнівні payload перед commit і зберігають `.rejected.*`. + - `openclaw doctor --fix` володіє ремонтом. Він може видалити не-JSON префікси або відновити останню відому справну копію, зберігаючи відхилений payload як `.clobbered.*`. @@ -345,16 +346,17 @@ openclaw doctor ``` - - `.clobbered.*` існує → зовнішнє пряме редагування або читання під час запуску було відновлено. - - `.rejected.*` існує → запис конфігурації, керований OpenClaw, не пройшов перевірки схеми або clobber перед комітом. - - `Config write rejected:` → запис намагався видалити обов’язкову форму, різко зменшити файл або зберегти недійсну конфігурацію. - - `Rejected validation details:` → журнал відновлення або повідомлення main-agent містить шлях схеми, що спричинив відновлення, наприклад `agents.defaults.execution` або `gateway.auth.password.source`. - - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запуск обробив поточний файл як clobbered, бо він втратив поля або розмір порівняно з резервною копією last-known-good. - - `Config last-known-good promotion skipped` → кандидат містив відредаговані placeholder-и секретів, як-от `***`. + - `.clobbered.*` існує → doctor зберіг зламане зовнішнє редагування під час ремонту активної конфігурації. + - `.rejected.*` існує → запис конфігурації, яким володіє OpenClaw, не пройшов перевірки схеми або clobber перед commit. + - `Config write rejected:` → запис намагався прибрати потрібну структуру, різко зменшити файл або зберегти недійсну конфігурацію. + - `config reload skipped (invalid config):` → пряме редагування не пройшло валідацію та було проігнороване запущеним Gateway. + - `Invalid config at ...` → запуск завершився помилкою до завантаження сервісів Gateway. + - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запис, яким володіє OpenClaw, було відхилено, бо він утратив поля або розмір порівняно з останньою відомою справною резервною копією. + - `Config last-known-good promotion skipped` → кандидат містив замасковані placeholders секретів, як-от `***`. - 1. Залиште відновлену активну конфігурацію, якщо вона правильна. + 1. Запустіть `openclaw doctor --fix`, щоб doctor відремонтував конфігурацію з префіксом/clobbered або відновив останню відому справну. 2. Скопіюйте лише потрібні ключі з `.clobbered.*` або `.rejected.*`, потім застосуйте їх за допомогою `openclaw config set` або `config.patch`. 3. Запустіть `openclaw config validate` перед перезапуском. 4. Якщо редагуєте вручну, зберігайте повну конфігурацію JSON5, а не лише частковий об’єкт, який хотіли змінити. @@ -368,9 +370,9 @@ openclaw doctor - [Конфігурація: сувора валідація](/uk/gateway/configuration#strict-validation) - [Doctor](/uk/gateway/doctor) -## Попередження probe для Gateway +## Попередження probe Gateway -Використовуйте це, коли `openclaw gateway probe` досягає чогось, але все ще друкує блок попередження. +Використовуйте це, коли `openclaw gateway probe` досягає чогось, але все одно друкує блок попереджень. ```bash openclaw gateway probe @@ -380,27 +382,27 @@ openclaw gateway probe --ssh user@gateway-host Шукайте: -- `warnings[].code` і `primaryTargetId` у JSON-виводі. -- Чи стосується попередження SSH fallback, кількох gateways, відсутніх scopes або нерозв’язаних auth refs. +- `warnings[].code` і `primaryTargetId` у виводі JSON. +- Чи стосується попередження fallback SSH, кількох Gateway, відсутніх областей доступу або нерозв’язаних посилань автентифікації. Поширені сигнатури: -- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback targets. -- `multiple reachable gateways detected` → відповіло більше ніж одне target. Зазвичай це означає навмисне налаштування multi-gateway або застарілі/дубльовані listeners. -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежено scope; спаруйте ідентичність пристрою або використайте credentials з `operator.read`. -- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення спрацювало, але повний набір діагностичних RPC вичерпав час очікування або завершився помилкою. Вважайте це досяжним Gateway з погіршеною діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виводі `--json`. -- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → gateway відповів, але цьому клієнту ще потрібне pairing/approval перед звичайним операторським доступом. -- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth material був недоступний у цьому шляху команди для target, що зазнав збою. +- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback цілі. +- `multiple reachable gateways detected` → відповіло більше ніж одна ціль. Зазвичай це означає навмисне налаштування з кількома Gateway або застарілі/дубльовані слухачі. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежений областями доступу; сполучіть ідентичність пристрою або використайте облікові дані з `operator.read`. +- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення спрацювало, але повний набір діагностичних RPC перевищив час очікування або завершився помилкою. Розглядайте це як досяжний Gateway із деградованою діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виводі `--json`. +- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне сполучення/схвалення перед звичайним операторським доступом. +- нерозв’язаний текст попередження SecretRef `gateway.auth.*` / `gateway.remote.*` → матеріал автентифікації був недоступний у цьому шляху команди для невдалої цілі. Пов’язано: - [Gateway](/uk/cli/gateway) -- [Кілька gateways на одному хості](/uk/gateway#multiple-gateways-same-host) +- [Кілька Gateway на одному хості](/uk/gateway#multiple-gateways-same-host) - [Віддалений доступ](/uk/gateway/remote) -## Канал під’єднано, повідомлення не передаються +## Канал підключено, повідомлення не надходять -Якщо стан каналу — під’єднано, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. +Якщо стан каналу підключено, але потік повідомлень не працює, зосередьтеся на політиках, дозволах і правилах доставки, специфічних для каналу. ```bash openclaw channels status --probe @@ -413,14 +415,14 @@ openclaw config get channels Шукайте: - Політика DM (`pairing`, `allowlist`, `open`, `disabled`). -- Allowlist груп і вимоги до згадок. +- Allowlist груп і вимоги щодо згадок. - Відсутні дозволи/області доступу API каналу. Поширені сигнатури: - `mention required` → повідомлення проігноровано політикою згадок у групі. - `pairing` / трасування очікування схвалення → відправника не схвалено. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією/дозволами каналу. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема автентифікації/дозволів каналу. Пов’язано: @@ -431,7 +433,7 @@ openclaw config get channels ## Доставка Cron і Heartbeat -Якщо Cron або Heartbeat не запустився чи не доставив повідомлення, спочатку перевірте стан планувальника, а потім ціль доставки. +Якщо Cron або Heartbeat не запустився чи не виконав доставку, спочатку перевірте стан планувальника, а потім ціль доставки. ```bash openclaw cron status @@ -443,19 +445,19 @@ openclaw logs --follow Шукайте: -- Cron увімкнено, і є наступне пробудження. -- Статус історії запусків завдання (`ok`, `skipped`, `error`). +- Cron увімкнено, і наявне наступне пробудження. +- Стан історії запусків завдання (`ok`, `skipped`, `error`). - Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. - `cron: timer tick failed` → збій такту планувальника; перевірте помилки файлів/журналів/середовища виконання. - - `heartbeat skipped` with `reason=quiet-hours` → поза вікном активних годин. - - `heartbeat skipped` with `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / заголовки markdown, тому OpenClaw пропускає виклик моделі. - - `heartbeat skipped` with `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися під час цього такту. - - `heartbeat: unknown accountId` → недійсний id облікового запису для цілі доставки Heartbeat. - - `heartbeat skipped` with `reason=dm-blocked` → ціль Heartbeat визначено як призначення типу DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для окремого агента) встановлено на `block`. + - `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. + - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. + - `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися на цьому такті. + - `heartbeat: unknown accountId` → недійсний ідентифікатор облікового запису для цілі доставки Heartbeat. + - `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначено як призначення в стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для агента) встановлено в `block`. @@ -468,7 +470,7 @@ openclaw logs --follow ## Node спарено, інструмент не працює -Якщо Node спарено, але інструменти не працюють, ізолюйте стан переднього плану, дозволів і схвалень. +Якщо Node спарено, але інструменти не працюють, ізолюйте стан переднього плану, дозволів і схвалення. ```bash openclaw nodes status @@ -481,25 +483,25 @@ openclaw status Шукайте: - Node онлайн з очікуваними можливостями. -- Надання дозволів ОС для камери/мікрофона/геолокації/екрана. -- Схвалення exec і стан allowlist. +- Надані дозволи ОС для камери/мікрофона/геолокації/екрана. +- Схвалення виконання й стан allowlist. Поширені сигнатури: - `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути на передньому плані. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС. -- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. -- `SYSTEM_RUN_DENIED: allowlist miss` → команда заблокована allowlist. +- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення виконання. +- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist. Пов’язано: -- [Схвалення exec](/uk/tools/exec-approvals) +- [Схвалення виконання](/uk/tools/exec-approvals) - [Усунення несправностей Node](/uk/nodes/troubleshooting) - [Nodes](/uk/nodes/index) -## Інструмент браузера не працює +## Не працює інструмент браузера -Використовуйте це, коли дії інструмента браузера не вдаються, хоча сам Gateway справний. +Використовуйте це, коли дії інструмента браузера не працюють, хоча сам Gateway справний. ```bash openclaw browser status @@ -511,39 +513,39 @@ openclaw doctor Шукайте: -- Чи встановлено `plugins.allow` і чи включає він `browser`. +- Чи встановлено `plugins.allow` і чи містить воно `browser`. - Дійсний шлях до виконуваного файлу браузера. - Досяжність профілю CDP. -- Доступність локального Chrome для профілів `existing-session` / `user`. +- Наявність локального Chrome для профілів `existing-session` / `user`. - `unknown command "browser"` або `unknown command 'browser'` → вбудований Plugin браузера виключено через `plugins.allow`. - - інструмент браузера відсутній / недоступний, коли `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився. + - інструмент браузера відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився. - `Failed to start Chrome CDP on port` → процес браузера не вдалося запустити. - `browser.executablePath not found` → налаштований шлях недійсний. - - `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, наприклад `file:` або `ftp:`. - - `browser.cdpUrl has invalid port` → налаштований URL CDP має неправильний порт або порт поза діапазоном. - - `Playwright is not available in this gateway build; '' is unsupported.` → поточна інсталяція Gateway не має основної залежності середовища виконання браузера; перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. Знімки ARIA та базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними. + - `browser.cdpUrl must be http(s) or ws(s)` → налаштована CDP URL-адреса використовує непідтримувану схему, як-от `file:` або `ftp:`. + - `browser.cdpUrl has invalid port` → налаштована CDP URL-адреса має неправильний порт або порт поза допустимим діапазоном. + - `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні Gateway бракує основної залежності середовища виконання браузера; перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. ARIA-знімки й базові знімки сторінок усе ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селектором і експорт PDF залишаються недоступними. - - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, залиште браузер відкритим, схваліть перший запит на під’єднання, а потім повторіть спробу. Якщо стан входу не потрібен, віддайте перевагу керованому профілю `openclaw`. + - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку інспектування браузера, увімкніть віддалене налагодження, тримайте браузер відкритим, схваліть перший запит на під’єднання, а потім повторіть спробу. Якщо стан входу не потрібен, надайте перевагу керованому профілю `openclaw`. - `No Chrome tabs found for profile="user"` → профіль під’єднання Chrome MCP не має відкритих локальних вкладок Chrome. - - `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста Gateway. - - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для під’єднання не має досяжної цілі, або HTTP-кінцева точка відповіла, але WebSocket CDP усе одно не вдалося відкрити. + - `Remote CDP for profile "" is not reachable` → налаштована віддалена CDP-крапка недосяжна з хоста Gateway. + - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для під’єднання не має досяжної цілі, або HTTP-крапка відповіла, але CDP WebSocket все одно не вдалося відкрити. - - `fullPage is not supported for element screenshots` → запит знімка екрана змішав `--full-page` з `--ref` або `--element`. + - `fullPage is not supported for element screenshots` → запит знімка екрана поєднав `--full-page` з `--ref` або `--element`. - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі знімка, а не CSS `--element`. - - `existing-session file uploads do not support element selectors; use ref/inputRef.` → хукам завантаження Chrome MCP потрібні refs зі знімків, а не CSS-селектори. - - `existing-session file uploads currently support one file at a time.` → надсилайте по одному завантаженню за виклик у профілях Chrome MCP. - - `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення часу очікування. - - `existing-session type does not support timeoutMs overrides.` → опустіть `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний час очікування. - - `existing-session evaluate does not support timeoutMs overrides.` → опустіть `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний час очікування. + - `existing-session file uploads do not support element selectors; use ref/inputRef.` → хукам завантаження Chrome MCP потрібні посилання зі знімка, а не CSS-селектори. + - `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP. + - `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення тайм-ауту. + - `existing-session type does not support timeoutMs overrides.` → пропустіть `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний тайм-аут. + - `existing-session evaluate does not support timeoutMs overrides.` → пропустіть `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session або використовуйте керований/CDP-профіль браузера, коли потрібен власний тайм-аут. - `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або сирого CDP-профілю. - - застарілі перевизначення viewport / темного режиму / locale / офлайн-режиму в профілях лише для під’єднання або віддалених CDP-профілях → запустіть `openclaw browser stop --browser-profile `, щоб закрити активний сеанс керування й звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway. + - застарілі перевизначення viewport / темного режиму / локалі / офлайн-режиму в attach-only або віддалених CDP-профілях → виконайте `openclaw browser stop --browser-profile `, щоб закрити активний сеанс керування та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway. @@ -555,7 +557,7 @@ openclaw doctor ## Якщо ви оновилися, і щось раптово зламалося -Більшість збоїв після оновлення спричинені розбіжностями конфігурації або суворішими стандартними налаштуваннями, які тепер застосовуються. +Більшість збоїв після оновлення спричинені дрейфом конфігурації або суворішими типовими параметрами, які тепер застосовуються. @@ -568,8 +570,8 @@ openclaw doctor Що перевірити: - - Якщо `gateway.mode=remote`, виклики CLI можуть націлюватися на віддалений сервіс, тоді як ваш локальний сервіс працює нормально. - - Явні виклики `--url` не повертаються до збережених облікових даних. + - Якщо `gateway.mode=remote`, виклики CLI можуть спрямовуватися на віддалений сервіс, тоді як ваш локальний сервіс працює нормально. + - Явні виклики з `--url` не повертаються до збережених облікових даних. Поширені сигнатури: @@ -577,7 +579,7 @@ openclaw doctor - `unauthorized` → кінцева точка досяжна, але автентифікація неправильна. - + ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode @@ -588,16 +590,16 @@ openclaw doctor Що перевірити: - - Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: автентифікації спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не для loopback. + - Прив’язування не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: автентифікації за спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не через loopback. - Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. Поширені сигнатури: - - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації Gateway. - - `Connectivity probe: failed`, коли середовище виконання працює → Gateway живий, але недоступний з поточною автентифікацією/url. + - `refusing to bind gateway ... without auth` → прив’язування не до loopback без дійсного шляху автентифікації Gateway. + - `Connectivity probe: failed`, коли середовище виконання працює → Gateway активний, але недоступний з поточною автентифікацією/URL. - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -607,18 +609,18 @@ openclaw doctor Що перевірити: - - Очікувані схвалення пристроїв для панелі керування/Nodes. - - Очікувані схвалення DM pairing після змін політики або ідентичності. + - Очікувані схвалення пристроїв для панелі керування/nodes. + - Очікувані схвалення спарення DM після змін політики або ідентичності. Поширені сигнатури: - - `device identity required` → автентифікацію пристрою не задоволено. - - `pairing required` → відправника/пристрій має бути схвалено. + - `device identity required` → автентифікація пристрою не задоволена. + - `pairing required` → відправника/пристрій потрібно схвалити. -Якщо конфігурація сервісу й середовище виконання після перевірок усе ще не збігаються, перевстановіть метадані сервісу з того самого профілю/каталогу стану: +Якщо конфігурація сервісу й середовище виконання все ще не збігаються після перевірок, перевстановіть метадані сервісу з того самого профілю/каталогу стану: ```bash openclaw gateway install --force @@ -628,8 +630,8 @@ openclaw gateway restart Пов’язано: - [Автентифікація](/uk/gateway/authentication) -- [Фоновий exec і інструмент процесу](/uk/gateway/background-process) -- [Pairing, керований Gateway](/uk/gateway/pairing) +- [Фонове виконання та інструмент процесів](/uk/gateway/background-process) +- [Спарення, кероване Gateway](/uk/gateway/pairing) ## Пов’язано diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index 580ca3051..63ff6452d 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,37 +1,37 @@ --- read_when: - - Відповіді на поширені запитання щодо налаштування, встановлення, початку роботи або підтримки під час роботи - - Попередній розбір проблем, про які повідомили користувачі, перед глибшим налагодженням -summary: Поширені запитання про початкове налаштування, конфігурацію та використання OpenClaw + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки середовища виконання + - Тріаж проблем, про які повідомили користувачі, перед глибшим налагодженням +summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw title: Поширені запитання x-i18n: - generated_at: "2026-05-02T20:49:24Z" + generated_at: "2026-05-03T17:12:06Z" model: gpt-5.5 provider: openai - source_hash: 1437a84d7da0e4111edd46297b2a486e2da4f6e4a6cff0d69d6a372e85608130 + source_hash: 372220d62f872db1427b2836662bc8cc74e07d2cdfb651c105d3df25131855dd source_path: help/faq.md workflow: 16 --- -Швидкі відповіді та глибше усунення несправностей для реальних конфігурацій (локальна розробка, VPS, кілька агентів, OAuth/ключі API, резервне перемикання моделей). Для діагностики виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді та докладніше усунення несправностей для реальних налаштувань (локальна розробка, VPS, кілька агентів, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурація](/uk/gateway/configuration). -## Перші 60 секунд, якщо щось зламано +## Перші 60 секунд, якщо щось зламалося -1. **Швидкий стан (перша перевірка)** +1. **Швидкий статус (перша перевірка)** ```bash openclaw status ``` - Швидкий локальний підсумок: ОС + оновлення, доступність Gateway/сервісу, агенти/сеанси, конфігурація провайдера + проблеми виконання (коли Gateway доступний). + Швидке локальне зведення: ОС + оновлення, доступність gateway/служби, агенти/сеанси, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). -2. **Звіт для вставлення (безпечно ділитися)** +2. **Звіт для вставлення (безпечний для поширення)** ```bash openclaw status --all ``` - Діагностика лише для читання з хвостом журналу (токени відредаговано). + Діагностика лише для читання з хвостом журналу (токени приховано). 3. **Стан демона + порту** @@ -39,204 +39,204 @@ x-i18n: openclaw gateway status ``` - Показує середовище виконання супервізора порівняно з доступністю RPC, цільову URL-адресу перевірки та яку конфігурацію сервіс, імовірно, використав. + Показує середовище виконання супервізора порівняно з доступністю RPC, цільову URL-адресу проби та яку конфігурацію, імовірно, використала служба. -4. **Глибокі перевірки** +4. **Глибокі проби** ```bash openclaw status --deep ``` - Виконує живу перевірку справності Gateway, зокрема перевірки каналів, коли вони підтримуються - (потрібен доступний Gateway). Див. [Справність](/uk/gateway/health). + Запускає живу перевірку справності gateway, включно з пробами каналів, коли це підтримується + (потрібен доступний gateway). Див. [Справність](/uk/gateway/health). -5. **Переглянути хвіст останнього журналу** +5. **Стежити за найновішим журналом** ```bash openclaw logs --follow ``` - Якщо RPC не працює, скористайтеся резервним варіантом: + Якщо RPC недоступний, використайте запасний варіант: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові журнали відокремлені від журналів сервісу; див. [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). + Файлові журнали відокремлені від журналів служби; див. [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). -6. **Запустіть doctor (виправлення)** +6. **Запустити doctor (виправлення)** ```bash openclaw doctor ``` - Відновлює/мігрує конфігурацію/стан і запускає перевірки працездатності. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію/стан + запускає перевірки справності. Див. [Doctor](/uk/gateway/doctor). 7. **Знімок Gateway** ```bash openclaw health --json - openclaw health --verbose # shows the target URL + config path on errors + openclaw health --verbose # показує цільову URL-адресу + шлях конфігурації під час помилок ``` - Запитує в запущеного Gateway повний знімок (лише WS). Див. [Стан працездатності](/uk/gateway/health). + Запитує в запущеного gateway повний знімок (лише WS). Див. [Справність](/uk/gateway/health). -## Швидкий старт і налаштування під час першого запуску +## Швидкий старт і налаштування першого запуску -Запитання й відповіді для першого запуску — встановлення, онбординг, маршрути автентифікації, підписки, початкові збої — -розміщені в [FAQ першого запуску](/uk/help/faq-first-run). +Запитання й відповіді для першого запуску — встановлення, onboarding, маршрути автентифікації, підписки, початкові збої — +розміщено в [FAQ першого запуску](/uk/help/faq-first-run). ## Що таке OpenClaw? - OpenClaw — це персональний AI-асистент, який ви запускаєте на власних пристроях. Він відповідає в уже звичних вам середовищах обміну повідомленнями (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудованих Plugin каналів, як-от QQ Bot), а також може працювати з голосом і живим Canvas на підтримуваних платформах. **Gateway** — це постійно ввімкнена площина керування; асистент — це продукт. + OpenClaw — це персональний ШІ-асистент, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, наприклад QQ Bot), і також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це постійно ввімкнена площина керування; асистент — це продукт. - OpenClaw — це не «просто обгортка Claude». Це **local-first площина керування**, яка дає змогу запускати - потужного асистента на **вашому власному обладнанні**, доступного з чат-додатків, якими ви вже користуєтеся, зі - сеансами зі станом, пам’яттю та інструментами — без передавання контролю над вашими робочими процесами хостинговому + OpenClaw — це не "просто обгортка Claude". Це **локально-орієнтована площина керування**, яка дає змогу запускати + спроможного асистента на **вашому власному обладнанні**, доступного з чат-додатків, якими ви вже користуєтеся, зі + сеансами зі станом, пам’яттю та інструментами — без передавання контролю над вашими робочими процесами розміщеному SaaS. Основне: - - **Ваші пристрої, ваші дані:** запускайте Gateway там, де хочете (Mac, Linux, VPS), і зберігайте - робочий простір та історію сеансів локально. + - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте + робочий простір + історію сеансів локально. - **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/тощо, - плюс мобільний голос і Canvas на підтримуваних платформах. + а також мобільний голос і Canvas на підтримуваних платформах. - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією - та відмовостійким перемиканням для кожного агента. - - **Лише локальний варіант:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. + для кожного агента й резервним перемиканням. + - **Опція лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. - **Маршрутизація кількох агентів:** окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм - робочим простором і типовими налаштуваннями. - - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте й самостійно хостіть без прив’язки до постачальника. + робочим простором і типовими значеннями. + - **Відкритий код і гнучке доопрацювання:** переглядайте, розширюйте та розміщуйте самостійно без прив’язки до постачальника. Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Кілька агентів](/uk/concepts/multi-agent), [Пам’ять](/uk/concepts/memory). - + Хороші перші проєкти: - Створити вебсайт (WordPress, Shopify або простий статичний сайт). - - Створити прототип мобільного додатка (структура, екрани, план API). + - Прототипувати мобільний додаток (план, екрани, план API). - Упорядкувати файли й папки (очищення, іменування, теги). - - Під’єднати Gmail і автоматизувати підсумки або подальші дії. + - Підключити Gmail і автоматизувати зведення або подальші дії. - Він може виконувати великі завдання, але працює найкраще, коли ви ділите їх на фази й - використовуєте субагентів для паралельної роботи. + Він може виконувати великі завдання, але працює найкраще, коли ви розбиваєте їх на фази й + використовуєте підагентів для паралельної роботи. - Повсякденні переваги зазвичай виглядають так: + Повсякденні виграші зазвичай мають такий вигляд: - - **Особисті брифінги:** підсумки вхідних, календаря та важливих для вас новин. - - **Дослідження й чернетки:** швидке дослідження, підсумки та перші чернетки для електронних листів або документів. - - **Нагадування й подальші дії:** підказки та списки перевірок на основі Cron або Heartbeat. + - **Персональні брифінги:** зведення вхідних, календаря та новин, які вас цікавлять. + - **Дослідження та чернетки:** швидкі дослідження, зведення та перші чернетки для електронних листів або документів. + - **Нагадування та подальші дії:** підказки й контрольні списки, керовані Cron або Heartbeat. - **Автоматизація браузера:** заповнення форм, збирання даних і повторення вебзавдань. - **Координація між пристроями:** надішліть завдання з телефона, дозвольте Gateway виконати його на сервері й отримайте результат назад у чаті. - - Так, для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати короткі списки, - узагальнювати інформацію про потенційних клієнтів і писати чернетки аутріч-повідомлень або рекламних текстів. + + Так, для **дослідження, кваліфікації та написання чернеток**. Він може сканувати сайти, створювати короткі списки, + підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів. - Для **аутрічу або рекламних запусків** залишайте людину в процесі. Уникайте спаму, дотримуйтеся місцевих законів і - правил платформ та переглядайте все перед надсиланням. Найбезпечніший підхід — дати - OpenClaw підготувати чернетку, а вам її схвалити. + Для **outreach або запусків реклами** залишайте людину в контурі. Уникайте спаму, дотримуйтеся місцевих законів і + політик платформ, а також переглядайте все перед надсиланням. Найбезпечніший шаблон — дозволити + OpenClaw створити чернетку, а ви затверджуєте. Документація: [Безпека](/uk/gateway/security). - OpenClaw — це **персональний асистент** і шар координації, а не заміна IDE. Використовуйте + OpenClaw — це **персональний асистент** і координаційний шар, а не заміна IDE. Використовуйте Claude Code або Codex для найшвидшого прямого циклу кодування всередині репозиторію. Використовуйте OpenClaw, коли вам - потрібні довготривала пам’ять, доступ із різних пристроїв і оркестрація інструментів. + потрібні довготривала пам’ять, доступ між пристроями та оркестрація інструментів. Переваги: - **Постійна пам’ять + робочий простір** між сеансами - - **Багатоплатформний доступ** (WhatsApp, Telegram, TUI, WebChat) + - **Доступ із кількох платформ** (WhatsApp, Telegram, TUI, WebChat) - **Оркестрація інструментів** (браузер, файли, планування, хуки) - - **Постійно ввімкнений Gateway** (запуск на VPS, взаємодія звідки завгодно) - - **Node** для локального браузера/екрана/камери/виконання команд + - **Постійно ввімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль) + - **Nodes** для локального браузера/екрана/камери/exec - Демонстрація: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) -## Skills та автоматизація +## Skills і автоматизація - - Використовуйте керовані перевизначення замість редагування копії в репозиторії. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тож керовані перевизначення все одно мають перевагу над вбудованими Skills без змін у git. Якщо вам потрібно встановити Skill глобально, але зробити його видимим лише для деяких агентів, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. У репозиторії мають жити лише зміни, придатні для upstream, і виходити як PR. + + Використовуйте керовані перевизначення замість редагування копії в репозиторії. Розмістіть зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тож керовані перевизначення все одно мають перевагу над вбудованими skills без змін у git. Якщо skill потрібно встановити глобально, але він має бути видимим лише деяким агентам, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні upstream, мають жити в репозиторії та виходити як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw у наступному сеансі трактує як `/skills`. Якщо Skill має бути видимим лише для певних агентів, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw під час наступного сеансу трактує як `/skills`. Якщо skill має бути видимим лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - Наразі підтримуються такі підходи: + Сьогодні підтримувані шаблони такі: - **Завдання Cron**: ізольовані завдання можуть задавати перевизначення `model` для кожного завдання. - - **Субагенти**: скеровуйте завдання окремим агентам із різними типовими моделями. + - **Підагенти**: маршрутизуйте завдання до окремих агентів із різними типовими моделями. - **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли перемкнути модель поточного сеансу. - Див. [Завдання Cron](/uk/automation/cron-jobs), [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [Команди зі скісною рискою](/uk/tools/slash-commands). + Див. [Завдання Cron](/uk/automation/cron-jobs), [Маршрутизація кількох агентів](/uk/concepts/multi-agent) і [Slash-команди](/uk/tools/slash-commands). - - Використовуйте **субагентів** для довгих або паралельних завдань. Субагенти працюють у власному сеансі, - повертають підсумок і зберігають основний чат чуйним. + + Використовуйте **підагентів** для довгих або паралельних завдань. Підагенти працюють у власному сеансі, + повертають зведення й залишають ваш основний чат responsive. - Попросіть бота "створити субагента для цього завдання" або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб побачити, що Gateway робить зараз (і чи він зайнятий). + Попросіть бота "spawn a sub-agent for this task" або використайте `/subagents`. + Використовуйте `/status` у чаті, щоб побачити, що Gateway робить прямо зараз (і чи він зайнятий). - Порада щодо токенів: довгі завдання та субагенти споживають токени. Якщо вас турбує вартість, задайте - дешевшу модель для субагентів через `agents.defaults.subagents.model`. + Порада щодо токенів: довгі завдання й підагенти обидва споживають токени. Якщо вартість важлива, задайте + дешевшу модель для підагентів через `agents.defaults.subagents.model`. - Документація: [Субагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). + Документація: [Підагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив’язки тредів. Ви можете прив’язати тред Discord до субагента або цільового сеансу, щоб подальші повідомлення в цьому треді залишалися в цьому прив’язаному сеансі. + + Використовуйте прив’язки гілок. Ви можете прив’язати гілку Discord до підагента або цілі сеансу, щоб подальші повідомлення в цій гілці залишалися в цьому прив’язаному сеансі. Базовий процес: - - Створіть через `sessions_spawn` із `thread: true` (і, за бажання, `mode: "session"` для постійних подальших повідомлень). + - Створіть через `sessions_spawn` з `thread: true` (і необов’язково `mode: "session"` для постійних подальших відповідей). - Або прив’яжіть вручну через `/focus `. - Використовуйте `/agents`, щоб переглянути стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. - - Використовуйте `/unfocus`, щоб від’єднати тред. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати авто-скасуванням фокуса. + - Використовуйте `/unfocus`, щоб від’єднати гілку. - Потрібна конфігурація: + Обов’язкова конфігурація: - Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - Перевизначення Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоприв’язка під час створення: `channels.discord.threadBindings.spawnSessions` типово має значення `true`; установіть `false`, щоб вимкнути створення прив’язаних до тредів сеансів. + - Автоприв’язка під час створення: `channels.discord.threadBindings.spawnSessions` типово дорівнює `true`; задайте `false`, щоб вимкнути створення сеансів, прив’язаних до гілки. - Документація: [Субагенти](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник конфігурації](/uk/gateway/configuration-reference), [Команди зі скісною рискою](/uk/tools/slash-commands). + Документація: [Підагенти](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands). - - Спочатку перевірте визначений маршрут запитувача: + + Спершу перевірте визначений маршрут requester: - - Доставка субагента в режимі завершення віддає перевагу будь-якому прив’язаному треду або маршруту розмови, якщо він існує. - - Якщо джерело завершення містить лише канал, OpenClaw повертається до збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. - - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат натомість повернеться до доставки через чергу сеансу, а не буде негайно опублікований у чаті. - - Недійсні або застарілі цілі все ще можуть примусово спричинити повернення до черги або остаточний збій доставки. - - Якщо остання видима відповідь асистента в дочірньому сеансі — це точний тихий токен `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення, а не публікує застарілий попередній прогрес. - - Якщо дочірній сеанс завершився за тайм-аутом після самих лише викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість повторення сирого виводу інструментів. + - Доставка підагента в режимі завершення надає перевагу будь-якій прив’язаній гілці або маршруту розмови, якщо він існує. + - Якщо джерело завершення містить лише канал, OpenClaw повертається до збереженого маршруту сеансу requester (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла успішно виконатися. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може завершитися невдало, і результат натомість повертається до доставки через чергу сеансу, а не публікується негайно в чат. + - Недійсні або застарілі цілі все ще можуть примусити fallback до черги або остаточну помилку доставки. + - Якщо остання видима відповідь асистента дочірнього сеансу — це точний тихий токен `NO_REPLY` / `no_reply`, або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу. + - Якщо дочірній сеанс завершився за тайм-аутом після лише викликів інструментів, оголошення може згорнути це в коротке зведення часткового прогресу замість повторення сирого виводу інструментів. Налагодження: @@ -244,7 +244,7 @@ x-i18n: openclaw tasks show ``` - Документація: [Субагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструменти сеансу](/uk/concepts/session-tool). + Документація: [Підагенти](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструменти сеансів](/uk/concepts/session-tool). @@ -254,7 +254,7 @@ x-i18n: Контрольний список: - - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. + - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - Перевірте, що Gateway працює 24/7 (без сну/перезапусків). - Перевірте налаштування часового поясу для завдання (`--tz` порівняно з часовим поясом хоста). @@ -269,15 +269,15 @@ x-i18n: - + Спершу перевірте режим доставки: - `--no-deliver` / `delivery.mode: "none"` означає, що резервне надсилання runner не очікується. - Відсутня або недійсна ціль оголошення (`channel` / `to`) означає, що runner пропустив вихідну доставку. - - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner намагався доставити повідомлення, але облікові дані це заблокували. - - Тихий ізольований результат (лише `NO_REPLY` / `no_reply`) вважається навмисно непридатним для доставки, тому runner також пригнічує резервну доставку з черги. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити повідомлення, але облікові дані це заблокували. + - Беззвучний ізольований результат (лише `NO_REPLY` / `no_reply`) вважається навмисно недоставним, тому runner також пригнічує резервну доставку з черги. - Для ізольованих cron-завдань агент усе ще може надсилати напряму за допомогою інструмента `message`, + Для ізольованих завдань cron агент усе ще може надсилати напряму за допомогою інструмента `message`, коли доступний маршрут чату. `--announce` керує лише резервним шляхом runner для фінального тексту, який агент ще не надіслав. @@ -288,27 +288,27 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron-завдання](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). + Документація: [Завдання Cron](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). - - Зазвичай це шлях перемикання live-моделі, а не дубльоване планування. + + Зазвичай це шлях живого перемикання моделі, а не дубльоване планування. Ізольований cron може зберегти runtime-передавання моделі й повторити спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнутого - провайдера/модель, і якщо перемикання містило нове перевизначення профілю автентифікації, cron - також зберігає його перед повторною спробою. + запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого + провайдера/модель, а якщо перемикання містило нове перевизначення профілю автентифікації, cron + також зберігає його перед повтором. Пов’язані правила вибору: - - Перевизначення моделі хуком Gmail має пріоритет, коли застосовується. + - Перевизначення моделі Gmail hook має пріоритет, коли застосовне. - Потім `model` для окремого завдання. - Потім будь-яке збережене перевизначення моделі cron-сесії. - - Потім звичайний вибір моделі агента/типової моделі. + - Потім звичайний вибір моделі агента/за замовчуванням. - Цикл повторів обмежений. Після початкової спроби плюс 2 повтори через перемикання - cron переривається замість нескінченного циклу. + Цикл повторів обмежений. Після початкової спроби плюс 2 повтори перемикання + cron переривається, а не зациклюється назавжди. Налагодження: @@ -317,12 +317,12 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron-завдання](/uk/automation/cron-jobs), [cron CLI](/uk/cli/cron). + Документація: [Завдання Cron](/uk/automation/cron-jobs), [CLI cron](/uk/cli/cron). - - Використовуйте нативні команди `openclaw skills` або додайте Skills у свій робочий простір. Інтерфейс Skills для macOS недоступний на Linux. + + Використовуйте нативні команди `openclaw skills` або додавайте Skills у свій робочий простір. Інтерфейс macOS Skills UI недоступний у Linux. Переглядайте Skills на [https://clawhub.ai](https://clawhub.ai). ```bash @@ -336,39 +336,39 @@ x-i18n: openclaw skills check ``` - Нативний `openclaw skills install` записує в каталог `skills/` - активного робочого простору. Установлюйте окремий CLI `clawhub` лише якщо хочете публікувати або - синхронізувати власні Skills. Для спільних установок між агентами розмістіть Skill у + Нативна команда `openclaw skills install` записує в каталог `skills/` + активного робочого простору. Встановлюйте окремий CLI `clawhub` лише якщо хочете публікувати або + синхронізувати власні Skills. Для спільних встановлень між агентами розмістіть Skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або `agents.list[].skills`, якщо хочете звузити, які агенти можуть його бачити. - + Так. Використовуйте планувальник Gateway: - - **Cron-завдання** для запланованих або повторюваних завдань (зберігаються після перезапусків). + - **Завдання Cron** для запланованих або повторюваних завдань (зберігаються після перезапусків). - **Heartbeat** для періодичних перевірок "основної сесії". - - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють у чати. + - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють повідомлення в чати. - Документація: [Cron-завдання](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation), + Документація: [Завдання Cron](/uk/automation/cron-jobs), [Автоматизація й завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - Не напряму. Skills для macOS обмежуються `metadata.openclaw.os` плюс необхідними бінарними файлами, і Skills з’являються в системному промпті лише тоді, коли вони придатні на **хості Gateway**. На Linux Skills лише для `darwin` (наприклад, `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите обмеження. + Не напряму. macOS Skills обмежуються `metadata.openclaw.os` плюс потрібними бінарними файлами, і Skills з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. У Linux Skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. - Є три підтримувані шаблони: + Є три підтримувані схеми: **Варіант A - запустіть Gateway на Mac (найпростіше).** - Запустіть Gateway там, де є бінарні файли macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються нормально, бо хост Gateway працює на macOS. + Запустіть Gateway там, де існують бінарні файли macOS, а потім під’єднайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються штатно, бо хост Gateway працює на macOS. **Варіант B - використовуйте вузол macOS (без SSH).** - Запустіть Gateway на Linux, спарте вузол macOS (застосунок у рядку меню) і встановіть **Команди запуску Node** на "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли необхідні бінарні файли існують на вузлі. Агент запускає ці Skills через інструмент `nodes`. Якщо вибрати "Always Ask", підтвердження "Always Allow" у промпті додає цю команду до списку дозволених. + Запустіть Gateway у Linux, спарте вузол macOS (застосунок у рядку меню) і встановіть **Node Run Commands** на "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли потрібні бінарні файли існують на вузлі. Агент запускає ці Skills через інструмент `nodes`. Якщо вибрати "Always Ask", підтвердження "Always Allow" у prompt додає цю команду до allowlist. **Варіант C - проксіюйте бінарні файли macOS через SSH (розширено).** - Залиште Gateway на Linux, але зробіть так, щоб необхідні CLI-бінарники резолвилися в SSH-обгортки, які запускаються на Mac. Потім перевизначте Skill, щоб дозволити Linux, аби він залишався придатним. + Залиште Gateway у Linux, але зробіть так, щоб потрібні CLI-бінарні файли розв’язувалися в SSH-обгортки, які запускаються на Mac. Потім перевизначте Skill, щоб дозволити Linux, і він залишався придатним. 1. Створіть SSH-обгортку для бінарного файла (приклад: `memo` для Apple Notes): @@ -389,7 +389,7 @@ x-i18n: --- ``` - 4. Запустіть нову сесію, щоб знімок Skills оновився. + 4. Запустіть нову сесію, щоб snapshot Skills оновився. @@ -398,70 +398,70 @@ x-i18n: Варіанти: - - **Користувацький Skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). + - **Власний Skill / Plugin:** найкраще для надійного доступу до API (Notion і HeyGen мають API). - **Автоматизація браузера:** працює без коду, але повільніша й крихкіша. - Якщо хочете зберігати контекст для кожного клієнта (агентські робочі процеси), простий шаблон такий: + Якщо хочете зберігати контекст для кожного клієнта (агентські робочі процеси), проста схема така: - Одна сторінка Notion на клієнта (контекст + уподобання + активна робота). - Попросіть агента отримувати цю сторінку на початку сесії. Якщо хочете нативну інтеграцію, відкрийте запит на функцію або створіть Skill, - орієнтований на ці API. + націлений на ці API. - Установити Skills: + Встановлення Skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного робочого простору. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарні файли, установлені через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ Homebrew Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активного робочого простору. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо лише деякі агенти мають бачити спільне встановлення, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарні файли, встановлені через Homebrew; у Linux це означає Linuxbrew (див. запис Homebrew Linux FAQ вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований браузерний профіль `user`, який під’єднується через Chrome DevTools MCP: + + Використовуйте вбудований профіль браузера `user`, який під’єднується через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо хочете користувацьку назву, створіть явний профіль MCP: + Якщо хочете власну назву, створіть явний профіль MCP: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях може використовувати локальний браузер хоста або підключений браузерний вузол. Якщо Gateway працює деінде, запустіть хост вузла на машині з браузером або використайте віддалений CDP. + Цей шлях може використовувати локальний браузер хоста або під’єднаний браузерний вузол. Якщо Gateway працює деінде, або запустіть хост вузла на машині з браузером, або використовуйте віддалений CDP. - Поточні обмеження для `existing-session` / `user`: + Поточні обмеження `existing-session` / `user`: - дії керуються ref, а не CSS-селекторами - - завантаження файлів потребують `ref` / `inputRef` і наразі підтримують один файл за раз - - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або raw CDP-профілю + - завантаження потребують `ref` / `inputRef` і наразі підтримують один файл за раз + - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP -## Пісочниця та пам’ять +## Пісочниця й пам’ять Так. Див. [Пісочниця](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи пісочниці), див. [Docker](/uk/install/docker). - - Типовий образ створений із пріоритетом безпеки й запускається як користувач `node`, тому він не + + Стандартний образ передусім орієнтований на безпеку й запускається як користувач `node`, тому він не містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування: - - Зберігайте `/home/node` за допомогою `OPENCLAW_HOME_VOLUME`, щоб кеші не втрачалися. - - Вбудуйте системні залежності в образ за допомогою `OPENCLAW_DOCKER_APT_PACKAGES`. - - Установіть браузери Playwright через вбудований CLI: + - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші не зникали. + - Додайте системні залежності в образ за допомогою `OPENCLAW_DOCKER_APT_PACKAGES`. + - Встановіть браузери Playwright через вбудований CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Установіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що шлях зберігається. + - Встановіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що шлях зберігається. Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser). @@ -470,20 +470,20 @@ x-i18n: Так - якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (неосновні ключі) виконувалися в налаштованому backend пісочниці, тоді як основна DM-сесія залишалася на хості. Docker є типовим backend, якщо ви не вибрали інший. Потім обмежте, які інструменти доступні в сесіях пісочниці, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (неосновні ключі) запускалися в налаштованому backend пісочниці, тоді як основна DM-сесія залишалася на хості. Docker є стандартним backend, якщо ви не вибрали інший. Потім обмежте, які інструменти доступні в ізольованих сесіях, через `tools.sandbox.tools`. Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідник ключової конфігурації: [Конфігурація Gateway](/uk/gateway/config-agents#agentsdefaultssandbox) + Ключова довідка з конфігурації: [Конфігурація Gateway](/uk/gateway/config-agents#agentsdefaultssandbox) - Установіть `agents.defaults.sandbox.docker.binds` на `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки для окремого агента об’єднуються; прив’язки для окремого агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять стіни файлової системи пісочниці. + Встановіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні й агентські binds об’єднуються; агентські binds ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що binds обходять стіни файлової системи пісочниці. - OpenClaw перевіряє джерела прив’язок і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківські symlink усе одно fail closed, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все одно застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind за нормалізованим шляхом і за канонічним шляхом, розв’язаним через найглибшого наявного предка. Це означає, що виходи через батьківський symlink усе одно закриваються відмовою, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все ще застосовуються після розв’язання symlink. - Див. [Пісочниця](/uk/gateway/sandboxing#custom-bind-mounts) і [Пісочниця vs політика інструментів vs підвищені права](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і приміток щодо безпеки. + Див. [Пісочниця](/uk/gateway/sandboxing#custom-bind-mounts) і [Пісочниця проти політики інструментів проти підвищених прав](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і нотаток щодо безпеки. @@ -493,9 +493,9 @@ x-i18n: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - Відібрані довгострокові нотатки в `MEMORY.md` (лише основні/приватні сесії) - OpenClaw також запускає **тихий скид пам’яті перед Compaction**, щоб нагадати моделі + OpenClaw також виконує **беззвучне скидання пам’яті перед Compaction**, щоб нагадати моделі записати довговічні нотатки перед auto-compaction. Це запускається лише коли робочий простір - доступний для запису (пісочниці лише для читання пропускають це). Див. [Пам’ять](/uk/concepts/memory). + доступний для запису (пісочниці тільки для читання пропускають це). Див. [Пам’ять](/uk/concepts/memory). @@ -503,7 +503,7 @@ x-i18n: Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки належать до `MEMORY.md`, короткостроковий контекст іде в `memory/YYYY-MM-DD.md`. - Це все ще напрям, який ми покращуємо. Допомагає нагадувати моделі зберігати спогади; + Це все ще напрям, який ми вдосконалюємо. Корисно нагадувати моделі зберігати спогади; вона знатиме, що робити. Якщо вона й далі забуває, перевірте, що Gateway використовує той самий робочий простір під час кожного запуску. @@ -512,89 +512,88 @@ x-i18n: - Файли пам’яті розташовані на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сесії** все ще обмежений вікном контексту моделі, - тому довгі розмови можуть compact або truncated. Саме тому існує - пошук у пам’яті - він повертає в контекст лише релевантні частини. + Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше + сховище, а не модель. **Контекст сесії** все ще обмежений контекстним вікном моделі, + тому довгі розмови можуть compact або truncatе. Саме тому існує пошук у пам’яті - він повертає в контекст лише релевантні частини. Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). - Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває чат/доповнення та - **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або - вхід Codex CLI)** не допомагає для семантичного пошуку в пам’яті. OpenAI embeddings + Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває чат/завершення та + **не** надає доступу до embeddings, тому **вхід через Codex (OAuth або + Codex CLI login)** не допоможе для семантичного пошуку в пам’яті. OpenAI embeddings все одно потребують справжнього ключа API (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). - Якщо ви не задаєте провайдера явно, OpenClaw автоматично вибирає провайдера, коли - може знайти ключ API (профілі автентифікації, `models.providers.*.apiKey` або змінні середовища). - Він віддає перевагу OpenAI, якщо знайдено ключ OpenAI, інакше Gemini, якщо знайдено ключ Gemini, - потім Voyage, потім Mistral. Якщо віддалений ключ недоступний, пошук у пам’яті - залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано і наявний - шлях до локальної моделі, OpenClaw - віддає перевагу `local`. Ollama підтримується, коли ви явно задаєте + Якщо ви явно не задасте провайдера, OpenClaw автоматично вибирає провайдера, коли + може знайти ключ API (auth profiles, `models.providers.*.apiKey` або env vars). + Він надає перевагу OpenAI, якщо знайдено ключ OpenAI, інакше Gemini, якщо + знайдено ключ Gemini, потім Voyage, потім Mistral. Якщо віддаленого ключа немає, пошук + у пам’яті лишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований + і наявний шлях до локальної моделі, OpenClaw + надає перевагу `local`. Ollama підтримується, коли ви явно задаєте `memorySearch.provider = "ollama"`. - Якщо ви хочете залишитися локально, задайте `memorySearch.provider = "local"` (і, за бажанням, + Якщо ви хочете лишитися локально, задайте `memorySearch.provider = "local"` (і за потреби `memorySearch.fallback = "none"`). Якщо вам потрібні Gemini embeddings, задайте `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо моделі embedding **OpenAI, Gemini, Voyage, Mistral, Ollama або local** - - див. [Пам’ять](/uk/concepts/memory), щоб дізнатися подробиці налаштування. + `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** - + див. [Пам’ять](/uk/concepts/memory), щоб дізнатися деталі налаштування. -## Де все розташовано на диску +## Де все зберігається на диску - Ні - **стан OpenClaw є локальним**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. + Ні - **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація та робочий простір розміщені на хості Gateway + - **Локально за замовчуванням:** сеанси, файли пам’яті, конфігурація та робочий простір зберігаються на хості Gateway (`~/.openclaw` + каталог вашого робочого простору). - - **Віддалено через необхідність:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), йдуть до + - **Віддалено через необхідність:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), потрапляють до їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх серверах. - - **Ви контролюєте обсяг даних:** використання локальних моделей зберігає підказки на вашій машині, але трафік каналів - усе одно проходить через сервери відповідного каналу. + - **Ви контролюєте обсяг даних:** використання локальних моделей лишає промпти на вашій машині, але трафік каналів + все одно проходить через сервери відповідного каналу. Пов’язано: [Робочий простір агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). - Усе розташовано в `$OPENCLAW_STATE_DIR` (за замовчуванням: `~/.openclaw`): + Усе зберігається в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): | Шлях | Призначення | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в профілі автентифікації під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, ключі API та необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове секретне навантаження для провайдерів SecretRef `file` | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищено) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + сесії) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в auth profiles під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, ключі API та необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове секретне навантаження для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Застарілий файл сумісності (статичні записи `api_key` очищено) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + сеанси) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сеансів (для кожного агента) | Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). - Ваш **робочий простір** (AGENTS.md, файли пам’яті, Skills тощо) є окремим і налаштовується через `agents.defaults.workspace` (за замовчуванням: `~/.openclaw/workspace`). + Ваш **робочий простір** (AGENTS.md, файли пам’яті, skills тощо) окремий і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - - Ці файли розміщуються в **робочому просторі агента**, а не в `~/.openclaw`. + + Ці файли зберігаються в **робочому просторі агента**, а не в `~/.openclaw`. - **Робочий простір (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - Кореневий файл `memory.md` у нижньому регістрі є лише застарілим вхідним файлом для виправлення; `openclaw doctor --fix` + Кореневий файл `memory.md` у нижньому регістрі є лише застарілим вхідним файлом для ремонту; `openclaw doctor --fix` може об’єднати його в `MEMORY.md`, коли існують обидва файли. - - **Каталог стану (`~/.openclaw`)**: конфігурація, стан каналів/провайдерів, профілі автентифікації, сесії, журнали + - **Каталог стану (`~/.openclaw`)**: конфігурація, стан каналів/провайдерів, auth profiles, сеанси, журнали та спільні skills (`~/.openclaw/skills`). - Робочий простір за замовчуванням: `~/.openclaw/workspace`, налаштовується через: + Типовий робочий простір - `~/.openclaw/workspace`, його можна налаштувати через: ```json5 { @@ -604,9 +603,9 @@ x-i18n: Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway використовує той самий робочий простір під час кожного запуску (і пам’ятайте: віддалений режим використовує **робочий простір хоста gateway**, - а не вашого локального ноутбука). + а не ваш локальний ноутбук). - Порада: якщо вам потрібна сталість поведінки або налаштування, попросіть бота **записати це в + Порада: якщо вам потрібна стійка поведінка або вподобання, попросіть бота **записати це в AGENTS.md або MEMORY.md**, а не покладатися на історію чату. Див. [Робочий простір агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). @@ -614,13 +613,13 @@ x-i18n: - Помістіть свій **робочий простір агента** у **приватний** git-репозиторій і створюйте резервну копію в приватному місці - (наприклад, GitHub private). Це зберігає пам’ять + файли AGENTS/SOUL/USER - і дає змогу пізніше відновити "розум" асистента. + Розмістіть ваш **робочий простір агента** у **приватному** git-репозиторії та створюйте його резервну копію в + приватному місці (наприклад, у приватному GitHub). Це збереже файли пам’яті + AGENTS/SOUL/USER + і дасть змогу пізніше відновити "розум" асистента. - **Не** комітьте нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані секретні навантаження). - Якщо вам потрібне повне відновлення, створюйте резервні копії і робочого простору, і каталогу стану - окремо (див. питання про міграцію вище). + **Не** комітьте нічого з `~/.openclaw` (облікові дані, сеанси, токени або зашифровані секретні навантаження). + Якщо вам потрібне повне відновлення, окремо створіть резервні копії і робочого простору, і каталогу стану + (див. запитання про міграцію вище). Документація: [Робочий простір агента](/uk/concepts/agent-workspace). @@ -631,15 +630,15 @@ x-i18n: - Так. Робочий простір є **default cwd** і якорем пам’яті, а не жорсткою пісочницею. + Так. Робочий простір - це **типовий cwd** і опорна точка пам’яті, а не жорстка пісочниця. Відносні шляхи розв’язуються всередині робочого простору, але абсолютні шляхи можуть отримувати доступ до інших - розташувань хоста, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте + розташувань на хості, якщо пісочницю не ввімкнено. Якщо вам потрібна ізоляція, використовуйте [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування пісочниці для окремого агента. Якщо ви - хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть для `workspace` цього агента + хочете, щоб репозиторій був типовим робочим каталогом, вкажіть для `workspace` цього агента корінь репозиторію. Репозиторій OpenClaw - це лише вихідний код; тримайте - робочий простір окремо, якщо ви навмисно не хочете, щоб агент працював усередині нього. + робочий простір окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. - Приклад (репозиторій як default cwd): + Приклад (репозиторій як типовий cwd): ```json5 { @@ -653,30 +652,30 @@ x-i18n: - - Стан сесій належить **хосту gateway**. Якщо ви у віддаленому режимі, потрібне вам сховище сесій розташоване на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). + + Стан сеансів належить **хосту gateway**. Якщо ви у віддаленому режимі, потрібне вам сховище сеансів розташоване на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сеансами](/uk/concepts/session). ## Основи конфігурації - - OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (за замовчуванням: `~/.openclaw/openclaw.json`): + + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються достатньо безпечні стандартні значення (зокрема робочий простір за замовчуванням `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються доволі безпечні типові значення (зокрема типовий робочий простір `~/.openclaw/workspace`). - + Прив’язки не до loopback **потребують дійсного шляху автентифікації gateway**. На практиці це означає: - - автентифікація зі спільним секретом: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy + - автентифікація через спільний секрет: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим reverse proxy з урахуванням ідентичності ```json5 { @@ -693,26 +692,26 @@ x-i18n: Примітки: - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. - - Локальні шляхи викликів можуть використовувати `gateway.remote.*` як fallback лише коли `gateway.auth.*` не задано. - - Для автентифікації паролем натомість задайте `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується закрито (без маскування віддаленим fallback). - - Налаштування Control UI зі спільним секретом автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігається в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення спільних секретів в URL. - - З `gateway.auth.mode: "trusted-proxy"` loopback reverse proxies на тому самому хості потребують явного `gateway.auth.trustedProxy.allowLoopback = true` і запису loopback у `gateway.trustedProxies`. + - Локальні шляхи викликів можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. + - Для автентифікації паролем натомість задайте `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується закритою відмовою (без маскування через віддалений fallback). + - Налаштування Control UI зі спільним секретом автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях застосунку/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запитів. Уникайте розміщення спільних секретів в URL. + - З `gateway.auth.mode: "trusted-proxy"` same-host loopback reverse proxies потребують явного `gateway.auth.trustedProxy.allowLoopback = true` і запису loopback у `gateway.trustedProxies`. - - OpenClaw за замовчуванням примусово вимагає автентифікацію gateway, зокрема loopback. У звичайному стандартному шляху це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим токена й автоматично генерує його, зберігаючи в `gateway.auth.token`, тому **локальні WS-клієнти мають автентифікуватися**. Це блокує інші локальні процеси від виклику Gateway. + + OpenClaw примусово вимагає автентифікацію gateway за замовчуванням, зокрема для loopback. У звичайному типовому шляху це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway розв’язується в режим токена й автоматично генерує його, зберігаючи в `gateway.auth.token`, тому **локальні WS-клієнти мають автентифікуватися**. Це блокує інші локальні процеси від викликів Gateway. - Якщо ви віддаєте перевагу іншому шляху автентифікації, можна явно вибрати режим пароля (або, для identity-aware reverse proxies, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своїй конфігурації. Doctor може згенерувати для вас токен будь-коли: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху автентифікації, можете явно вибрати режим пароля (або, для reverse proxy з урахуванням ідентичності, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своїй конфігурації. Doctor може згенерувати токен для вас будь-коли: `openclaw doctor --generate-gateway-token`. - Gateway відстежує конфігурацію та підтримує гаряче перезавантаження: + Gateway відстежує конфігурацію та підтримує hot-reload: - - `gateway.reload.mode: "hybrid"` (за замовчуванням): безпечно застосовує зміни наживо, перезапускає для критичних змін - - `hot`, `restart`, `off` також підтримуються + - `gateway.reload.mode: "hybrid"` (типово): hot-застосування безпечних змін, перезапуск для критичних + - також підтримуються `hot`, `restart`, `off` @@ -729,24 +728,24 @@ x-i18n: } ``` - - `off`: приховує текст слогана, але залишає рядок заголовка/версії банера. + - `off`: приховує текст слогана, але лишає рядок заголовка/версії банера. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: ротація кумедних/сезонних слоганів (поведінка за замовчуванням). - - Якщо ви хочете взагалі без банера, задайте env `OPENCLAW_HIDE_BANNER=1`. + - `random`: ротація кумедних/сезонних слоганів (типова поведінка). + - Якщо ви взагалі не хочете банер, задайте env `OPENCLAW_HIDE_BANNER=1`. - + `web_fetch` працює без ключа API. `web_search` залежить від вибраного провайдера: - - Провайдери на базі API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують свого звичайного налаштування ключа API. + - Провайдери з API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують свого звичайного налаштування ключа API. - Ollama Web Search не потребує ключа, але використовує ваш налаштований хост Ollama і потребує `ollama signin`. - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує ключа/є самостійно розгорнутим; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG не потребує ключа/може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. - Альтернативи середовища: + Альтернативи через середовище: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -788,15 +787,15 @@ x-i18n: } ``` - Конфігурація вебпошуку, специфічна для провайдера, тепер розміщується в `plugins.entries..config.webSearch.*`. - Застарілі шляхи провайдера `tools.web.search.*` ще тимчасово завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. - Резервна конфігурація web-fetch Firecrawl розміщується в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація вебпошуку для конкретного провайдера тепер міститься в `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдера `tools.web.search.*` тимчасово ще завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. + Резервна конфігурація веботримання Firecrawl міститься в `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - Якщо ви використовуєте списки дозволів, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). - - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового резервного провайдера fetch із доступних облікових даних. Наразі вбудованим провайдером є Firecrawl. + - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично виявляє першого готового резервного провайдера отримання з доступних облікових даних. Наразі вбудований провайдер — Firecrawl. - Демони читають змінні середовища з `~/.openclaw/.env` (або із середовища служби). Документація: [Вебінструменти](/uk/tools/web). @@ -804,44 +803,44 @@ x-i18n: - `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, усе - інше видаляється. + `config.apply` замінює **всю конфігурацію**. Якщо надіслати частковий об’єкт, усе + інше буде видалено. Поточний OpenClaw захищає від багатьох випадкових перезаписів: - - Записи конфігурації, які належать OpenClaw, перед записом перевіряють повну конфігурацію після зміни. - - Недійсні або руйнівні записи, які належать OpenClaw, відхиляються й зберігаються як `openclaw.json.rejected.*`. - - Якщо пряме редагування ламає запуск або гаряче перезавантаження, Gateway відновлює останню відому справну конфігурацію й зберігає відхилений файл як `openclaw.json.clobbered.*`. - - Головний агент після відновлення отримує попередження під час завантаження, щоб він не записав хибну конфігурацію знову наосліп. + - Записи конфігурації, які належать OpenClaw, перевіряють повну конфігурацію після змін перед записом. + - Недійсні або руйнівні записи, які належать OpenClaw, відхиляються та зберігаються як `openclaw.json.rejected.*`. + - Якщо пряме редагування ламає запуск або гаряче перезавантаження, Gateway безпечно завершується або пропускає перезавантаження; він не перезаписує `openclaw.json`. + - `openclaw doctor --fix` відповідає за відновлення й може повернути останню справну версію, зберігши відхилений файл як `openclaw.json.clobbered.*`. Відновлення: - - Перевірте `openclaw logs --follow` на наявність `Config auto-restored from last-known-good`, `Config write rejected:` або `config reload restored last-known-good config`. + - Перевірте `openclaw logs --follow` на наявність `Invalid config at`, `Config write rejected:` або `config reload skipped (invalid config)`. - Перегляньте найновіший `openclaw.json.clobbered.*` або `openclaw.json.rejected.*` поруч з активною конфігурацією. - - Залиште активну відновлену конфігурацію, якщо вона працює, а потім скопіюйте назад лише потрібні ключі за допомогою `openclaw config set` або `config.patch`. - - Запустіть `openclaw config validate` і `openclaw doctor`. - - Якщо у вас немає останньої відомої справної конфігурації або відхиленого вмісту, відновіть із резервної копії або повторно запустіть `openclaw doctor` і переналаштуйте канали/моделі. - - Якщо це було неочікувано, створіть звіт про помилку й додайте останню відому конфігурацію або будь-яку резервну копію. - - Локальний агент кодування часто може відтворити робочу конфігурацію з логів або історії. + - Запустіть `openclaw config validate` і `openclaw doctor --fix`. + - Скопіюйте назад лише потрібні ключі за допомогою `openclaw config set` або `config.patch`. + - Якщо у вас немає останньої справної версії або відхиленого вмісту, відновіть із резервної копії або повторно запустіть `openclaw doctor` і заново налаштуйте канали/моделі. + - Якщо це було неочікувано, повідомте про помилку й додайте свою останню відому конфігурацію або будь-яку резервну копію. + - Локальний агент для кодування часто може відтворити робочу конфігурацію з журналів або історії. Як уникнути: - - Використовуйте `openclaw config set` для невеликих змін. + - Використовуйте `openclaw config set` для малих змін. - Використовуйте `openclaw configure` для інтерактивних редагувань. - - Спершу використовуйте `config.schema.lookup`, якщо ви не впевнені щодо точного шляху або форми поля; він повертає неглибокий вузол схеми та короткі описи безпосередніх дочірніх елементів для деталізації. - - Використовуйте `config.patch` для часткових редагувань RPC; залишайте `config.apply` лише для повної заміни конфігурації. - - Якщо ви використовуєте інструмент `gateway`, доступний лише власнику, із запуску агента, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Спершу використовуйте `config.schema.lookup`, коли не впевнені щодо точного шляху або форми поля; він повертає неглибокий вузол схеми плюс короткі описи безпосередніх дочірніх елементів для деталізації. + - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для заміни повної конфігурації. + - Якщо ви використовуєте інструмент `gateway` лише для власника з запуску агента, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (зокрема застарілі псевдоніми `tools.bash.*`, що нормалізуються до тих самих захищених шляхів exec). - Документація: [Конфігурація](/uk/cli/config), [Налаштування](/uk/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/uk/gateway/doctor). + Документація: [Конфігурація](/uk/cli/config), [Налаштування](/uk/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-rejected-invalid-config), [Doctor](/uk/gateway/doctor). Типовий шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **вузли** й **агенти**: - - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сеансами. + - **Gateway (центральний):** відповідає за канали (Signal/WhatsApp), маршрутизацію та сеанси. - **Вузли (пристрої):** Macs/iOS/Android підключаються як периферійні пристрої та надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Агенти (працівники):** окремі мозки/робочі простори для спеціальних ролей (наприклад, "Операції Hetzner", "Особисті дані"). + - **Агенти (працівники):** окремі «мізки»/робочі простори для спеціальних ролей (наприклад, "Hetzner ops", "Personal data"). - **Субагенти:** запускають фонову роботу з головного агента, коли потрібен паралелізм. - **TUI:** підключайтеся до Gateway і перемикайте агентів/сеанси. @@ -849,7 +848,7 @@ x-i18n: - + Так. Це параметр конфігурації: ```json5 @@ -863,45 +862,45 @@ x-i18n: } ``` - За замовчуванням `false` (з вікном). Режим без графічного інтерфейсу на деяких сайтах частіше спрацьовує як ознака бота. Див. [Браузер](/uk/tools/browser). + За замовчуванням значення `false` (із вікном). Headless-режим на деяких сайтах частіше запускає перевірки проти ботів. Див. [Браузер](/uk/tools/browser). - Режим без графічного інтерфейсу використовує **той самий рушій Chromium** і працює для більшості автоматизації (форми, кліки, скрейпінг, входи). Основні відмінності: + Headless використовує **той самий рушій Chromium** і працює для більшості автоматизацій (форми, кліки, збирання даних, входи). Основні відмінності: - Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуальна перевірка). - - Деякі сайти суворіше ставляться до автоматизації в режимі без графічного інтерфейсу (CAPTCHA, захист від ботів). - Наприклад, X/Twitter часто блокує сеанси без графічного інтерфейсу. + - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, захист від ботів). + Наприклад, X/Twitter часто блокує headless-сеанси. - Установіть `browser.executablePath` на ваш виконуваний файл Brave (або будь-який браузер на основі Chromium) і перезапустіть Gateway. + Установіть `browser.executablePath` на двійковий файл Brave (або будь-який браузер на основі Chromium) і перезапустіть Gateway. Повні приклади конфігурації див. у [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). -## Віддалені Gateway і вузли +## Віддалені Gateway та вузли - - Повідомлення Telegram обробляються **gateway**. Gateway запускає агента й + + Повідомлення Telegram обробляються **Gateway**. Gateway запускає агента й лише потім викликає вузли через **Gateway WebSocket**, коли потрібен інструмент вузла: - Telegram → Gateway → Агент → `node.*` → Вузол → Gateway → Telegram + Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Вузли не бачать вхідний трафік провайдера; вони отримують лише RPC-виклики вузла. + Вузли не бачать вхідний трафік провайдера; вони отримують лише RPC-виклики вузлів. - Коротко: **спаруйте ваш комп’ютер як вузол**. Gateway працює в іншому місці, але може + Коротка відповідь: **сполучіть свій комп’ютер як вузол**. Gateway працює в іншому місці, але може викликати інструменти `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на постійно ввімкненому хості (VPS/домашньому сервері). + 1. Запустіть Gateway на постійно ввімкненому хості (VPS/домашній сервер). 2. Додайте хост Gateway і ваш комп’ютер до однієї tailnet. - 3. Переконайтеся, що Gateway WS доступний (прив’язка до tailnet або SSH-тунель). - 4. Відкрийте macOS-застосунок локально та підключіться в режимі **Віддалено через SSH** (або напряму через tailnet), + 3. Переконайтеся, що Gateway WS доступний (прив’язка tailnet або SSH-тунель). + 4. Відкрийте застосунок macOS локально й підключіться в режимі **Віддалено через SSH** (або напряму через tailnet), щоб він міг зареєструватися як вузол. 5. Схваліть вузол на Gateway: @@ -912,101 +911,101 @@ x-i18n: Окремий TCP-міст не потрібен; вузли підключаються через Gateway WebSocket. - Нагадування щодо безпеки: сполучення macOS-вузла дозволяє `system.run` на цій машині. Сполучайте + Нагадування про безпеку: сполучення вузла macOS дозволяє `system.run` на цій машині. Сполучайте лише пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). Документація: [Вузли](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). - - Перевірте базові речі: + + Перевірте основне: - Gateway запущено: `openclaw gateway status` - Стан Gateway: `openclaw status` - - Стан каналу: `openclaw channels status` + - Стан каналів: `openclaw channels status` - Потім перевірте автентифікацію та маршрутизацію: + Потім перевірте автентифікацію й маршрутизацію: - - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` задано правильно. - - Якщо ви підключаєтеся через SSH-тунель, підтвердьте, що локальний тунель працює і вказує на правильний порт. - - Підтвердьте, що ваші списки дозволених користувачів (DM або група) містять ваш обліковий запис. + - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. + - Якщо підключаєтеся через SSH-тунель, підтвердьте, що локальний тунель працює й вказує на правильний порт. + - Переконайтеся, що ваші списки дозволів (DM або група) містять ваш обліковий запис. Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). - Так. Вбудованого моста «бот-до-бота» немає, але це можна налаштувати кількома - надійними способами: + Так. Вбудованого мосту "бот-до-бота" немає, але це можна надійно налаштувати кількома + способами: - **Найпростіше:** використайте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай бот A надішле повідомлення боту B, а потім бот B відповість як зазвичай. + **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). + Нехай Bot A надішле повідомлення Bot B, а потім Bot B відповість як зазвичай. - **CLI-міст (загальний):** запустіть скрипт, який викликає інший Gateway через + **CLI-міст (універсальний):** запустіть скрипт, який викликає інший Gateway за допомогою `openclaw agent --message ... --deliver`, націлюючись на чат, де слухає інший бот. - Якщо один бот розміщено на віддаленому VPS, спрямуйте свій CLI на цей віддалений Gateway + Якщо один бот на віддаленому VPS, спрямуйте свій CLI на цей віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускайте з машини, яка може дістатися цільового Gateway): + Приклад шаблону (запускайте з машини, яка може досягти цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклилися нескінченно (лише згадки, списки дозволених - каналів або правило «не відповідати на повідомлення ботів»). + Порада: додайте запобіжник, щоб два боти не зациклилися безкінечно (лише за згадкою, списки дозволів + каналів або правило "не відповідати на повідомлення ботів"). - Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/uk/cli/agent), [Надсилання агентом](/uk/tools/agent-send). + Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/uk/cli/agent), [Надсилання агента](/uk/tools/agent-send). - Ні. Один Gateway може розміщувати кілька агентів, кожен зі своїм робочим простором, типовими моделями - та маршрутизацією. Це звичайне налаштування, і воно значно дешевше та простіше, ніж запускати - по одному VPS на кожного агента. + Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм робочим простором, типовими моделями + та маршрутизацією. Це нормальне налаштування, і воно значно дешевше та простіше, ніж запускати + по одному VPS на агента. Використовуйте окремі VPS лише тоді, коли потрібна жорстка ізоляція (межі безпеки) або дуже - різні конфігурації, які ви не хочете спільно використовувати. В іншому разі залиште один Gateway і - використовуйте кілька агентів або підлеглих агентів. + різні конфігурації, якими ви не хочете ділитися. Інакше залишайте один Gateway і + використовуйте кількох агентів або субагентів. - - Так - вузли є основним способом доступу до вашого ноутбука з віддаленого Gateway, і вони + + Так — вузли є першокласним способом дістатися до вашого ноутбука з віддаленого Gateway, і вони відкривають більше можливостей, ніж доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (невеликого VPS або пристрою класу Raspberry Pi достатньо; 4 ГБ RAM цілком вистачає), тому поширене - налаштування - це постійно ввімкнений хост плюс ваш ноутбук як вузол. + легким (невеликий VPS або пристрій класу Raspberry Pi цілком достатній; 4 ГБ RAM більш ніж досить), тож поширене + налаштування — постійно ввімкнений хост плюс ваш ноутбук як вузол. - **Вхідний SSH не потрібен.** Вузли підключаються назовні до Gateway WebSocket і використовують сполучення пристроїв. - - **Безпечніші засоби керування виконанням.** `system.run` обмежується списками дозволених вузлів/схваленнями на цьому ноутбуці. - - **Більше інструментів пристрою.** Вузли надають `canvas`, `camera` і `screen` на додаток до `system.run`. - - **Локальна автоматизація браузера.** Залишайте Gateway на VPS, але запускайте Chrome локально через хост вузла на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. + - **Безпечніші засоби контролю виконання.** `system.run` обмежується списками дозволів/схваленнями вузла на цьому ноутбуці. + - **Більше інструментів пристрою.** Вузли надають `canvas`, `camera` і `screen` на додачу до `system.run`. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост вузла на ноутбуці або під’єднуйтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для разового доступу до оболонки, але вузли простіші для постійних робочих процесів агентів і + SSH підходить для ситуативного доступу до оболонки, але вузли простіші для постійних робочих процесів агента й автоматизації пристроїв. Документація: [Вузли](/uk/nodes), [CLI вузлів](/uk/cli/nodes), [Браузер](/uk/tools/browser). - - Ні. На кожному хості має працювати лише **один gateway**, якщо ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Вузли - це периферійні пристрої, які підключаються - до gateway (вузли iOS/Android або «режим вузла» macOS у застосунку в рядку меню). Для безголових хостів вузлів - і керування через CLI див. [CLI хоста вузла](/uk/cli/node). + + Ні. На хості має працювати лише **один Gateway**, якщо ви навмисно не запускаєте ізольовані профілі (див. [Кілька Gateway](/uk/gateway/multiple-gateways)). Вузли — це периферійні пристрої, які підключаються + до Gateway (вузли iOS/Android або "режим вузла" macOS у застосунку меню). Для headless-хостів вузлів + і керування через CLI див. [CLI хоста Node](/uk/cli/node). - Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. + Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. - + Так. - - `config.schema.lookup`: переглянути одне піддерево конфігурації з його неглибоким вузлом схеми, відповідною підказкою UI та зведеннями безпосередніх дочірніх елементів перед записом + - `config.schema.lookup`: переглянути одне піддерево конфігурації з його неглибоким вузлом схеми, відповідною UI-підказкою та короткими описами безпосередніх дочірніх елементів перед записом - `config.get`: отримати поточний знімок + хеш - - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); виконує гаряче перезавантаження, коли це можливо, і перезапускає, коли потрібно - - `config.apply`: перевірити + замінити повну конфігурацію; виконує гаряче перезавантаження, коли це можливо, і перезапускає, коли потрібно - - Runtime-інструмент `gateway` лише для власника й надалі відмовляється перезаписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.patch`: безпечне часткове оновлення (бажане для більшості RPC-редагувань); виконує гаряче перезавантаження, коли можливо, і перезапускає, коли потрібно + - `config.apply`: перевірити + замінити повну конфігурацію; виконує гаряче перезавантаження, коли можливо, і перезапускає, коли потрібно + - Інструмент виконання `gateway` лише для власника все одно відмовляється перезаписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec @@ -1022,21 +1021,21 @@ x-i18n: - + Мінімальні кроки: - 1. **Установіть і увійдіть на VPS** + 1. **Установіть і ввійдіть на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Установіть і увійдіть на вашому Mac** - - Використайте застосунок Tailscale і ввійдіть у ту саму tailnet. + 2. **Установіть і ввійдіть на своєму Mac** + - Використайте застосунок Tailscale і ввійдіть у той самий tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім'я. - 4. **Використовуйте ім'я хоста tailnet** + - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. + 4. **Використовуйте ім’я хоста tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1046,19 +1045,19 @@ x-i18n: openclaw gateway --tailscale serve ``` - Це залишає gateway прив'язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). + Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). - - Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через той самий endpoint Gateway WS. + + Serve відкриває **Gateway Control UI + WS**. Вузли підключаються через ту саму кінцеву точку Gateway WS. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS і Mac перебувають в одній tailnet**. - 2. **Використайте застосунок macOS у віддаленому режимі** (ціллю SSH може бути ім'я хоста tailnet). - Застосунок тунелюватиме порт Gateway і підключиться як node. - 3. **Схваліть node** на gateway: + 1. **Переконайтеся, що VPS і Mac перебувають в одному tailnet**. + 2. **Використовуйте застосунок macOS у віддаленому режимі** (ціллю SSH може бути ім’я хоста tailnet). + Застосунок прокладе тунель до порту Gateway і підключиться як вузол. + 3. **Підтвердьте вузол** на gateway: ```bash openclaw devices list @@ -1069,14 +1068,14 @@ x-i18n: - + Якщо на другому ноутбуці вам потрібні лише **локальні інструменти** (екран/камера/exec), додайте його як - **node**. Так зберігається один Gateway і не дублюється конфігурація. Локальні інструменти node - наразі доступні лише для macOS, але ми плануємо розширити їх на інші ОС. + **вузол**. Так ви збережете один Gateway і уникнете дублювання конфігурації. Локальні інструменти вузлів + зараз доступні лише для macOS, але ми плануємо розширити їх на інші ОС. - Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Установлюйте другий Gateway лише тоді, коли потрібна **жорстка ізоляція** або два повністю окремі боти. - Документація: [Nodes](/uk/nodes), [CLI Nodes](/uk/cli/nodes), [кілька gateway](/uk/gateway/multiple-gateways). + Документація: [вузли](/uk/nodes), [CLI вузлів](/uk/cli/nodes), [кілька gateway](/uk/gateway/multiple-gateways). @@ -1088,11 +1087,11 @@ x-i18n: OpenClaw читає змінні середовища з батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: - `.env` з поточного робочого каталогу - - глобальний резервний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - глобальний резервний `.env` з `~/.openclaw/.env` (також `$OPENCLAW_STATE_DIR/.env`) Жоден файл `.env` не перевизначає наявні змінні середовища. - Ви також можете визначити inline-змінні середовища в конфігурації (застосовуються лише якщо їх немає в середовищі процесу): + Ви також можете визначити вбудовані змінні середовища в конфігурації (застосовуються лише якщо їх немає в середовищі процесу): ```json5 { @@ -1103,15 +1102,15 @@ x-i18n: } ``` - Див. [/environment](/uk/help/environment), щоб отримати повний порядок пріоритетів і джерела. + Повний порядок пріоритету та джерела див. у [/environment](/uk/help/environment). - - Два поширені способи виправлення: + + Два поширені виправлення: - 1. Додайте відсутні ключі в `~/.openclaw/.env`, щоб їх було підхоплено навіть тоді, коли сервіс не успадковує середовище вашого shell. - 2. Увімкніть імпорт shell (зручність за явним увімкненням): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб їх було підхоплено навіть тоді, коли служба не успадковує середовище вашого shell. + 2. Увімкніть імпорт із shell (зручність за явним увімкненням): ```json5 { @@ -1129,24 +1128,24 @@ x-i18n: - + `openclaw models status` повідомляє, чи ввімкнено **імпорт середовища shell**. "Shell env: off" - **не** означає, що ваші змінні середовища відсутні - це лише означає, що OpenClaw не завантажуватиме + **не** означає, що ваших змінних середовища бракує, - це лише означає, що OpenClaw не завантажуватиме ваш login shell автоматично. - Якщо Gateway працює як сервіс (launchd/systemd), він не успадкує ваше середовище + Якщо Gateway працює як служба (launchd/systemd), він не успадкує ваше середовище shell. Виправте це одним із таких способів: - 1. Додайте токен у `~/.openclaw/.env`: + 1. Помістіть токен у `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт shell (`env.shellEnv.enabled: true`). - 3. Або додайте його до блока `env` у вашій конфігурації (застосовується лише якщо відсутній). + 2. Або ввімкніть імпорт із shell (`env.shellEnv.enabled: true`). + 3. Або додайте його до блоку `env` у конфігурації (застосовується лише якщо відсутній). - Потім перезапустіть gateway і перевірте ще раз: + Потім перезапустіть gateway і перевірте знову: ```bash openclaw models status @@ -1158,18 +1157,18 @@ x-i18n: -## Сесії та кілька чатів +## Сеанси та кілька чатів - Надішліть `/new` або `/reset` як окреме повідомлення. Див. [керування сесіями](/uk/concepts/session). + Надішліть `/new` або `/reset` як окреме повідомлення. Див. [керування сеансами](/uk/concepts/session). - - Сесії можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типово **0**). - Установіть додатне значення, щоб увімкнути завершення через неактивність. Коли це ввімкнено, **наступне** - повідомлення після періоду неактивності починає новий ID сесії для цього ключа чату. - Це не видаляє transcripts - лише починає нову сесію. + + Сеанси можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типово **0**). + Задайте додатне значення, щоб увімкнути завершення через бездіяльність. Коли це ввімкнено, **наступне** + повідомлення після періоду бездіяльності запускає новий ідентифікатор сеансу для цього ключа чату. + Це не видаляє транскрипти - лише починає новий сеанс. ```json5 { @@ -1181,30 +1180,30 @@ x-i18n: - - Так, через **маршрутизацію кількох агентів** і **sub-agents**. Ви можете створити одного агента-координатора - і кількох агентів-виконавців із власними робочими просторами та моделями. + + Так, через **маршрутизацію між агентами** та **субагентів**. Ви можете створити одного координувального + агента і кількох робочих агентів із власними робочими просторами та моделями. - Водночас це найкраще сприймати як **цікавий експеримент**. Це потребує багато токенів і часто - менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми - бачимо, - це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей - бот також може створювати sub-agents за потреби. + Водночас це найкраще сприймати як **цікавий експеримент**. Він потребує багато токенів і часто + менш ефективний, ніж один бот із окремими сеансами. Типова модель, яку ми + уявляємо, - один бот, із яким ви спілкуєтеся, і різні сеанси для паралельної роботи. Цей + бот також може запускати субагентів, коли потрібно. - Документація: [маршрутизація кількох агентів](/uk/concepts/multi-agent), [sub-agents](/uk/tools/subagents), [CLI агентів](/uk/cli/agents). + Документація: [маршрутизація між агентами](/uk/concepts/multi-agent), [субагенти](/uk/tools/subagents), [CLI агентів](/uk/cli/agents). - Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато - файлів можуть спричинити Compaction чи обрізання. + Контекст сеансу обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато + файлів можуть спричинити Compaction або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими завданнями та `/new` під час перемикання тем. - - Зберігайте важливий контекст у робочому просторі й просіть бота перечитати його. - - Використовуйте sub-agents для довгої або паралельної роботи, щоб основний чат лишався меншим. - - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. + - Використовуйте `/compact` перед довгими завданнями та `/new` під час зміни теми. + - Тримайте важливий контекст у робочому просторі й просіть бота перечитати його. + - Використовуйте субагентів для довгої або паралельної роботи, щоб основний чат залишався меншим. + - Виберіть модель із більшим контекстним вікном, якщо це трапляється часто. @@ -1229,16 +1228,16 @@ x-i18n: Примітки: - - Onboarding також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Onboarding (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог стану (типові значення: `~/.openclaw-`). - - Скидання для розробки: `openclaw gateway --dev --reset` (лише для розробки; стирає dev-конфігурацію + credentials + сесії + робочий простір). + - Onboarding також пропонує **Reset**, якщо знаходить наявну конфігурацію. Див. [Onboarding (CLI)](/uk/start/wizard). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог стану (типово це `~/.openclaw-`). + - Скидання для розробки: `openclaw gateway --dev --reset` (лише для розробки; стирає dev-конфігурацію + облікові дані + сеанси + робочий простір). - + Використайте один із цих варіантів: - - **Compact** (зберігає розмову, але підсумовує старіші ходи): + - **Compaction** (зберігає розмову, але підсумовує старіші ходи): ``` /compact @@ -1246,33 +1245,33 @@ x-i18n: або `/compact `, щоб скерувати підсумок. - - **Reset** (нова ID сесії для того самого ключа чату): + - **Reset** (новий ID сеансу для того самого ключа чату): ``` /new /reset ``` - Якщо це продовжує траплятися: + Якщо це повторюється: - - Увімкніть або налаштуйте **обрізання сесії** (`agents.defaults.contextPruning`), щоб прибирати старий вивід інструментів. - - Використайте модель із більшим вікном контексту. + - Увімкніть або налаштуйте **обрізання сеансів** (`agents.defaults.contextPruning`), щоб скорочувати старий вивід інструментів. + - Використовуйте модель із більшим контекстним вікном. - Документація: [Compaction](/uk/concepts/compaction), [обрізання сесії](/uk/concepts/session-pruning), [керування сесіями](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [обрізання сеансів](/uk/concepts/session-pruning), [керування сеансами](/uk/concepts/session). - Це помилка валідації провайдера: модель згенерувала блок `tool_use` без обов'язкового - `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих гілок + Це помилка валідації провайдера: модель видала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сеансу застаріла або пошкоджена (часто після довгих гілок або зміни інструмента/схеми). - Виправлення: почніть нову сесію за допомогою `/new` (окреме повідомлення). + Виправлення: почніть новий сеанс за допомогою `/new` (окреме повідомлення). - Heartbeat запускається кожні **30m** за замовчуванням (**1h** під час використання OAuth-автентифікації). Налаштуйте або вимкніть його: + Heartbeat за замовчуванням запускаються кожні **30m** (**1h** під час використання OAuth-автентифікації). Налаштуйте або вимкніть їх: ```json5 { @@ -1287,15 +1286,15 @@ x-i18n: ``` Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown- - заголовки на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API-виклики. - Якщо файл відсутній, heartbeat усе одно запускається, а модель вирішує, що робити. + заголовки на кшталт `# Heading`), OpenClaw пропускає запуск Heartbeat, щоб заощадити API-виклики. + Якщо файла немає, Heartbeat усе одно запускається, і модель вирішує, що робити. - Перевизначення для окремих агентів використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Перевизначення для окремого агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - - Ні. OpenClaw працює на **вашому власному акаунті**, тож якщо ви є в групі, OpenClaw може її бачити. + + Ні. OpenClaw працює на **вашому власному обліковому записі**, тож якщо ви в групі, OpenClaw її бачить. За замовчуванням відповіді в групах заблоковано, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). Якщо ви хочете, щоб лише **ви** могли запускати відповіді в групі: @@ -1314,7 +1313,7 @@ x-i18n: - Варіант 1 (найшвидший): переглядайте logs і надішліть тестове повідомлення в групі: + Варіант 1 (найшвидший): відстежуйте журнали й надішліть тестове повідомлення в групі: ```bash openclaw logs --follow --json @@ -1329,70 +1328,70 @@ x-i18n: openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/uk/cli/directory), [Logs](/uk/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [каталог](/uk/cli/directory), [журнали](/uk/cli/logs). Дві поширені причини: - - Увімкнено gating за згадкою (за замовчуванням). Ви маєте @mention бота (або відповідати `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і група не додана до allowlist. + - Увімкнено gating за згадкою (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до allowlist. - Див. [Groups](/uk/channels/groups) і [групові повідомлення](/uk/channels/group-messages). + Див. [групи](/uk/channels/groups) і [групові повідомлення](/uk/channels/group-messages). - - Direct chats за замовчуванням згортаються в основну сесію. Groups/channels мають власні ключі сесій, а теми Telegram / threads Discord є окремими сесіями. Див. [Groups](/uk/channels/groups) і [групові повідомлення](/uk/channels/group-messages). + + Прямі чати за замовчуванням зводяться до основного сеансу. Групи/канали мають власні ключі сеансів, а теми Telegram / гілки Discord є окремими сеансами. Див. [групи](/uk/channels/groups) і [групові повідомлення](/uk/channels/group-messages). - Жорстких обмежень немає. Десятки (навіть сотні) - нормально, але стежте за: + Жорстких обмежень немає. Десятки (навіть сотні) цілком підходять, але стежте за: - - **Зростанням диска:** сесії + transcripts зберігаються в `~/.openclaw/agents//sessions/`. + - **Зростанням диска:** сеанси + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. - **Вартістю токенів:** більше агентів означає більше одночасного використання моделей. - - **Операційними витратами:** auth-профілі, робочі простори та маршрутизація каналів для кожного агента. + - **Операційними витратами:** профілі автентифікації, робочі простори й маршрутизація каналів для кожного агента. Поради: - Тримайте один **активний** робочий простір на агента (`agents.defaults.workspace`). - - Очищайте старі сесії (видаляйте JSONL або записи сховища), якщо диск зростає. - - Використовуйте `openclaw doctor`, щоб виявляти зайві робочі простори та невідповідності профілів. + - Обрізайте старі сеанси (видаляйте JSONL або записи сховища), якщо диск росте. + - Використовуйте `openclaw doctor`, щоб знаходити зайві робочі простори та невідповідності профілів. - Так. Використовуйте **маршрутизацію кількох агентів**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за - каналом/обліковим записом/співрозмовником. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. + Так. Використовуйте **маршрутизацію для кількох агентів**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/співрозмовником. Slack підтримується як канал і може бути прив'язаний до конкретних агентів. - Доступ через браузер потужний, але це не "робити все, що може людина" - антибот-захист, CAPTCHA та MFA - все ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості + Доступ через браузер потужний, але це не "робити все, що може людина" - антибот-захист, CAPTCHA та MFA все ще можуть + блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості або CDP на машині, яка фактично запускає браузер. Рекомендоване налаштування: - Постійно ввімкнений хост Gateway (VPS/Mac mini). - - Один агент на роль (прив’язки). - - Канал(и) Slack, прив’язані до цих агентів. - - Локальний браузер через Chrome MCP або вузол, коли потрібно. + - Один агент на роль (прив'язки). + - Канал(и) Slack, прив'язані до цих агентів. + - Локальний браузер через Chrome MCP або Node за потреби. - Документація: [маршрутизація кількох агентів](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [браузер](/uk/tools/browser), [вузли](/uk/nodes). + Документація: [Маршрутизація для кількох агентів](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі, аварійне перемикання та профілі автентифікації +## Моделі, відновлення після збою та профілі автентифікації -Питання й відповіді щодо моделей — стандартні значення, вибір, псевдоніми, перемикання, аварійне перемикання, профілі автентифікації — -містяться в [поширених запитаннях про моделі](/uk/help/faq-models). +Питання й відповіді щодо моделей — стандартні значення, вибір, псевдоніми, перемикання, відновлення після збою, профілі автентифікації — +розміщено в [FAQ щодо моделей](/uk/help/faq-models). ## Gateway: порти, "уже запущено" та віддалений режим - `gateway.port` керує єдиним мультиплексованим портом для WebSocket + HTTP (інтерфейс керування, hooks тощо). + `gateway.port` керує єдиним мультиплексованим портом для WebSocket + HTTP (Control UI, хуки тощо). Пріоритет: @@ -1407,14 +1406,14 @@ x-i18n: Використовуйте `openclaw gateway status` і довіряйте цим рядкам: - - `Probe target:` (URL, який перевірка фактично використала) - - `Listening:` (що фактично прив’язано до порту) - - `Last gateway error:` (типова першопричина, коли процес живий, але порт не прослуховується) + - `Probe target:` (URL, який фактично використала перевірка) + - `Listening:` (що фактично прив'язано до порту) + - `Last gateway error:` (поширена першопричина, коли процес живий, але порт не слухає) - Ви редагуєте один файл конфігурації, а сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + Ви редагуєте один файл конфігурації, тоді як сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). Виправлення: @@ -1427,14 +1426,14 @@ x-i18n: - OpenClaw застосовує блокування часу виконання, одразу прив’язуючи WebSocket-слухач під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується помилкою `EADDRINUSE`, він викидає `GatewayLockError`, який вказує, що інший екземпляр уже слухає. + OpenClaw застосовує блокування виконання, одразу прив'язуючи слухач WebSocket під час запуску (за замовчуванням `ws://127.0.0.1:18789`). Якщо прив'язка завершується помилкою `EADDRINUSE`, він викидає `GatewayLockError`, що вказує: інший екземпляр уже слухає. Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть із `openclaw gateway --port `. - Установіть `gateway.mode: "remote"` і вкажіть віддалений WebSocket URL, за потреби зі спільними секретними віддаленими обліковими даними: + Установіть `gateway.mode: "remote"` і вкажіть віддалений WebSocket URL, за бажанням зі спільними секретними віддаленими обліковими даними: ```json5 { @@ -1451,55 +1450,55 @@ x-i18n: Примітки: - - `openclaw gateway` запускається лише коли `gateway.mode` має значення `local` (або якщо ви передаєте прапорець перевизначення). - - Застосунок macOS стежить за файлом конфігурації та перемикає режими наживо, коли ці значення змінюються. - - `gateway.remote.token` / `.password` — це лише клієнтські віддалені облікові дані; самі по собі вони не вмикають локальну автентифікацію Gateway. + - `openclaw gateway` запускається лише коли `gateway.mode` має значення `local` (або ви передаєте прапорець перевизначення). + - Застосунок macOS відстежує файл конфігурації та перемикає режими наживо, коли ці значення змінюються. + - `gateway.remote.token` / `.password` — це лише клієнтські віддалені облікові дані; самі по собі вони не вмикають автентифікацію локального Gateway. - - Ваш шлях автентифікації Gateway і метод автентифікації інтерфейсу не збігаються. + + Шлях автентифікації вашого Gateway і метод автентифікації UI не збігаються. Факти (з коду): - - Інтерфейс керування зберігає токен у `sessionStorage` для поточного сеансу вкладки браузера та вибраного URL Gateway, тому оновлення тієї самої вкладки продовжують працювати без відновлення довготривалого збереження токена в localStorage. - - У разі `AUTH_TOKEN_MISMATCH` довірені клієнти можуть спробувати одну обмежену повторну спробу з кешованим токеном пристрою, коли Gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені області доступу, збережені з токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` і надалі зберігають запитаний набір областей доступу замість успадкування кешованих областей. + - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраного URL Gateway, тому оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого збереження токена в localStorage. + - У разі `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли Gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені області доступу, збережені з токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` усе ще зберігають запитаний набір областей доступу замість успадкування кешованих. - Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. - - Перевірки областей доступу bootstrap-токена мають рольовий префікс. Вбудований список дозволених bootstrap-операторів задовольняє лише запити операторів; вузлам або іншим неоператорським ролям усе ще потрібні області доступу з власним рольовим префіксом. + - Перевірки областей доступу bootstrap-токена мають префікс ролі. Вбудований allowlist bootstrap-оператора задовольняє лише запити оператора; Node або інші неоператорські ролі все ще потребують областей доступу з власним префіксом ролі. Виправлення: - - Найшвидше: `openclaw dashboard` (виводить і копіює URL панелі керування, намагається відкрити; показує SSH-підказку, якщо середовище без графічного інтерфейсу). + - Найшвидше: `openclaw dashboard` (виводить і копіює URL панелі, намагається відкрити; показує підказку SSH, якщо хост без графічного інтерфейсу). - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. - Якщо віддалено, спочатку створіть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. - - Режим спільного секрету: установіть `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, потім вставте відповідний секрет у налаштування інтерфейсу керування. + - Режим спільного секрету: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, потім вставте відповідний секрет у налаштування Control UI. - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте Serve URL, а не сирий loopback/tailnet URL, який обходить заголовки ідентичності Tailscale. - - Режим довіреного проксі: переконайтеся, що ви заходите через налаштований identity-aware проксі, а не через сирий URL Gateway. Проксі loopback на тому самому хості також потребують `gateway.auth.trustedProxy.allowLoopback = true`. - - Якщо невідповідність зберігається після однієї повторної спроби, перестворіть/повторно схваліть спарений токен пристрою: + - Режим довіреного проксі: переконайтеся, що ви заходите через налаштований identity-aware проксі, а не через сирий URL Gateway. Проксі local loopback на тому самому хості також потребують `gateway.auth.trustedProxy.allowLoopback = true`. + - Якщо невідповідність зберігається після однієї повторної спроби, змініть/повторно схваліть спарений токен пристрою: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - Якщо цей виклик rotate повідомляє, що його відхилено, перевірте дві речі: - - сеанси спарених пристроїв можуть ротувати лише свій **власний** пристрій, якщо вони також не мають `operator.admin` + - Якщо цей виклик ротації повідомляє, що його відхилено, перевірте дві речі: + - сесії спареного пристрою можуть ротувати лише **власний** пристрій, якщо вони також не мають `operator.admin` - явні значення `--scope` не можуть перевищувати поточні операторські області доступу викликача - - Усе ще не працює? Запустіть `openclaw status --all` і дотримуйтесь [усунення несправностей](/uk/gateway/troubleshooting). Див. [панель керування](/uk/web/dashboard) щодо деталей автентифікації. + - Все ще застрягли? Запустіть `openclaw status --all` і дотримуйтеся [Усунення несправностей](/uk/gateway/troubleshooting). Деталі автентифікації див. у [Панелі](/uk/web/dashboard). - - Прив’язка `tailnet` вибирає IP Tailscale з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнений), немає до чого прив’язуватися. + + Прив'язка `tailnet` вибирає IP Tailscale з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнений), прив'язуватися ні до чого. Виправлення: - Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або - Перемкніться на `gateway.bind: "loopback"` / `"lan"`. - Примітка: `tailnet` є явним. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли вам потрібна прив’язка лише до tailnet. + Примітка: `tailnet` є явним. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли потрібна прив'язка лише до tailnet. - Зазвичай ні - один Gateway може запускати кілька каналів обміну повідомленнями та агентів. Використовуйте кілька Gateway лише коли потрібна надлишковість (наприклад: rescue bot) або жорстка ізоляція. + Зазвичай ні - один Gateway може запускати кілька каналів обміну повідомленнями та агентів. Використовуйте кілька Gateway лише коли потрібна надлишковість (наприклад: рятувальний бот) або жорстка ізоляція. Так, але потрібно ізолювати: @@ -1512,29 +1511,29 @@ x-i18n: - Використовуйте `openclaw --profile ...` для кожного екземпляра (автоматично створює `~/.openclaw-`). - Установіть унікальний `gateway.port` у конфігурації кожного профілю (або передайте `--port` для ручних запусків). - - Установіть сервіс для кожного профілю: `openclaw --profile gateway install`. + - Установіть сервіс для профілю: `openclaw --profile gateway install`. - Профілі також додають суфікс до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). - Повний посібник: [кілька gateway](/uk/gateway/multiple-gateways). + Профілі також додають суфікси до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Повний посібник: [Кілька gateway](/uk/gateway/multiple-gateways). Gateway — це **WebSocket-сервер**, і він очікує, що найперше повідомлення - буде фреймом `connect`. Якщо він отримує щось інше, він закриває з’єднання + буде фреймом `connect`. Якщо він отримує щось інше, він закриває з'єднання з **кодом 1008** (порушення політики). Поширені причини: - Ви відкрили **HTTP** URL у браузері (`http://...`) замість WS-клієнта. - Ви використали неправильний порт або шлях. - - Проксі або тунель прибрав заголовки автентифікації або надіслав запит не для Gateway. + - Проксі або тунель вилучив заголовки автентифікації чи надіслав не-Gateway-запит. Швидкі виправлення: 1. Використовуйте WS URL: `ws://:18789` (або `wss://...`, якщо HTTPS). 2. Не відкривайте WS-порт у звичайній вкладці браузера. - 3. Якщо автентифікація ввімкнена, додайте токен/пароль у фрейм `connect`. + 3. Якщо автентифікацію ввімкнено, додайте токен/пароль у фрейм `connect`. Якщо ви використовуєте CLI або TUI, URL має виглядати так: @@ -1542,7 +1541,7 @@ x-i18n: openclaw tui --url ws://:18789 --token ``` - Деталі протоколу: [протокол Gateway](/uk/gateway/protocol). + Деталі протоколу: [Протокол Gateway](/uk/gateway/protocol). @@ -1557,9 +1556,9 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Ви можете встановити стабільний шлях через `logging.file`. Рівень файлового журналювання керується `logging.level`. Докладність консолі керується `--verbose` і `logging.consoleLevel`. + Можна задати стабільний шлях через `logging.file`. Рівень файлового журналу керується `logging.level`. Докладність консолі керується `--verbose` і `logging.consoleLevel`. - Найшвидший перегляд журналу: + Найшвидший перегляд журналу в реальному часі: ```bash openclaw logs --follow @@ -1567,11 +1566,11 @@ x-i18n: Журнали сервісу/супервізора (коли gateway працює через launchd/systemd): - - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`) + - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (за замовчуванням: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Див. [усунення несправностей](/uk/gateway/troubleshooting), щоб дізнатися більше. + Докладніше див. [Усунення несправностей](/uk/gateway/troubleshooting). @@ -1583,7 +1582,7 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повторно зайняти порт. Див. [Gateway](/uk/gateway). + Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути порт. Див. [Gateway](/uk/gateway). @@ -1621,7 +1620,7 @@ x-i18n: openclaw gateway run ``` - Документація: [Windows (WSL2)](/uk/platforms/windows), [інструкція з експлуатації сервісу Gateway](/uk/gateway). + Документація: [Windows (WSL2)](/uk/platforms/windows), [Інструкція з експлуатації сервісу Gateway](/uk/gateway). @@ -1638,36 +1637,36 @@ x-i18n: Поширені причини: - Автентифікацію моделі не завантажено на **хості gateway** (перевірте `models status`). - - Прив’язування каналу/список дозволених блокує відповіді (перевірте конфігурацію каналу та журнали). - - WebChat/панель керування відкрито без правильного токена. + - Спарювання каналу/allowlist блокує відповіді (перевірте конфігурацію каналу + журнали). + - WebChat/Dashboard відкрито без правильного токена. - Якщо ви працюєте віддалено, підтвердьте, що тунель/підключення Tailscale активне і що + Якщо ви працюєте віддалено, підтвердьте, що тунель/з'єднання Tailscale активне і що WebSocket Gateway доступний. - Документація: [канали](/uk/channels), [усунення несправностей](/uk/gateway/troubleshooting), [віддалений доступ](/uk/gateway/remote). + Документація: [Канали](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). - Зазвичай це означає, що інтерфейс утратив WebSocket-з’єднання. Перевірте: + Зазвичай це означає, що UI втратив WebSocket-з'єднання. Перевірте: 1. Чи запущено Gateway? `openclaw gateway status` 2. Чи справний Gateway? `openclaw status` 3. Чи має UI правильний токен? `openclaw dashboard` - 4. Якщо доступ віддалений, чи працює тунель/посилання Tailscale? + 4. Якщо віддалено, чи активне посилання tunnel/Tailscale? - Потім перегляньте журнали в реальному часі: + Потім перегляньте логи в реальному часі: ```bash openclaw logs --follow ``` - Документація: [Панель керування](/uk/web/dashboard), [Віддалений доступ](/uk/gateway/remote), [Усунення несправностей](/uk/gateway/troubleshooting). + Документація: [Dashboard](/uk/web/dashboard), [Віддалений доступ](/uk/gateway/remote), [Усунення несправностей](/uk/gateway/troubleshooting). - - Почніть із журналів і стану каналу: + + Почніть із логів і статусу каналу: ```bash openclaw channels status @@ -1676,17 +1675,17 @@ x-i18n: Потім зіставте помилку: - - `BOT_COMMANDS_TOO_MUCH`: меню Telegram має забагато пунктів. OpenClaw уже обрізає їх до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі пункти меню все одно потрібно прибрати. Зменште кількість команд Plugin/Skills/власних команд або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за проксі, переконайтеся, що вихідний HTTPS дозволено і DNS працює для `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: меню Telegram має забагато записів. OpenClaw уже обрізає їх до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно вилучити. Зменште кількість команд Plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або схожі мережеві помилки: якщо ви на VPS або за проксі, переконайтеся, що вихідний HTTPS дозволено, а DNS працює для `api.telegram.org`. - Якщо Gateway віддалений, переконайтеся, що ви переглядаєте журнали на хості Gateway. + Якщо Gateway віддалений, переконайтеся, що ви дивитеся логи на хості Gateway. Документація: [Telegram](/uk/channels/telegram), [Усунення несправностей каналів](/uk/channels/troubleshooting). - Спочатку переконайтеся, що Gateway доступний і агент може запускатися: + Спершу переконайтеся, що Gateway доступний і агент може запускатися: ```bash openclaw status @@ -1694,53 +1693,53 @@ x-i18n: openclaw logs --follow ``` - У TUI використайте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в каналі - чату, переконайтеся, що доставку ввімкнено (`/deliver on`). + У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в каналі чату, + переконайтеся, що доставку ввімкнено (`/deliver on`). Документація: [TUI](/uk/web/tui), [Slash-команди](/uk/tools/slash-commands). - Якщо ви встановили сервіс: + Якщо ви встановили службу: ```bash openclaw gateway stop openclaw gateway start ``` - Це зупиняє/запускає **керований сервіс** (launchd на macOS, systemd на Linux). - Використовуйте це, коли Gateway працює у фоні як демон. + Це зупиняє/запускає **керовану службу** (launchd на macOS, systemd на Linux). + Використовуйте це, коли Gateway працює у фоновому режимі як daemon. - Якщо ви запускаєте у передньому плані, зупиніть за допомогою Ctrl-C, потім: + Якщо ви запускаєте у foreground, зупиніть за допомогою Ctrl-C, потім: ```bash openclaw gateway run ``` - Документація: [Ранбук сервісу Gateway](/uk/gateway). + Документація: [Runbook служби Gateway](/uk/gateway). - - - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). - - `openclaw gateway`: запускає gateway **у передньому плані** для цього сеансу термінала. + + - `openclaw gateway restart`: перезапускає **фонову службу** (launchd/systemd). + - `openclaw gateway`: запускає gateway **у foreground** для цього сеансу термінала. - Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли - вам потрібен одноразовий запуск у передньому плані. + Якщо ви встановили службу, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли + потрібен одноразовий запуск у foreground. - - Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перегляньте файл журналу щодо автентифікації каналу, маршрутизації моделі та помилок RPC. + + Запустіть Gateway із `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл логів на помилки автентифікації каналу, маршрутизації моделей і RPC. ## Медіа та вкладення - - Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Надсилання агентом](/uk/tools/agent-send). + + Вихідні вкладення від агента мають містити рядок `MEDIA:` (окремим рядком). Див. [Налаштування асистента OpenClaw](/uk/start/openclaw) і [Надсилання агентом](/uk/tools/agent-send). Надсилання через CLI: @@ -1750,9 +1749,9 @@ x-i18n: Також перевірте: - - Цільовий канал підтримує вихідні медіа й не заблокований списками дозволів. - - Файл відповідає обмеженням розміру провайдера (зображення змінюють розмір до максимум 2048px). - - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів робочою областю, temp/media-store і файлами, перевіреними sandbox. + - Цільовий канал підтримує вихідні медіа й не заблокований allowlist. + - Файл у межах обмежень розміру провайдера (зображення змінюються до максимуму 2048px). + - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними sandbox. - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, усе одно блокуються. Див. [Зображення](/uk/nodes/images). @@ -1763,73 +1762,73 @@ x-i18n: ## Безпека та контроль доступу - - Розглядайте вхідні особисті повідомлення як недовірені вхідні дані. Типові налаштування створені для зменшення ризику: + + Вважайте вхідні DM недовіреним введенням. Типові налаштування створені для зменшення ризику: - - Типова поведінка на каналах із підтримкою особистих повідомлень — **сполучення**: - - Невідомі відправники отримують код сполучення; бот не обробляє їхнє повідомлення. + - Типова поведінка на каналах із підтримкою DM — **pairing**: + - Невідомі відправники отримують код pairing; бот не обробляє їхнє повідомлення. - Підтвердьте за допомогою: `openclaw pairing approve --channel [--account ] ` - - Очікувані запити обмежено **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. - - Публічне відкриття особистих повідомлень потребує явної згоди (`dmPolicy: "open"` і список дозволів `"*"`). + - Очікувані запити обмежені **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. + - Публічне відкриття DM потребує явного ввімкнення (`dmPolicy: "open"` і allowlist `"*"`). - Запустіть `openclaw doctor`, щоб виявити ризиковані політики особистих повідомлень. + Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. - Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може написати боту особисте повідомлення. - Якщо ваш помічник читає зовнішній вміст (вебпошук/отримання даних, сторінки браузера, електронні листи, - документи, вкладення, вставлені журнали), цей вміст може містити інструкції, які намагаються - перехопити керування моделлю. Це може статися навіть якщо **ви єдиний відправник**. + Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може писати боту в DM. + Якщо ваш асистент читає зовнішній вміст (web search/fetch, сторінки браузера, електронні листи, + документи, вкладення, вставлені логи), цей вміст може містити інструкції, які намагаються + перехопити керування моделлю. Це може статися, навіть якщо **ви єдиний відправник**. Найбільший ризик виникає, коли інструменти ввімкнені: модель можна обманом змусити - ексфільтрувати контекст або викликати інструменти від вашого імені. Зменште радіус ураження так: + витікати контекст або викликати інструменти від вашого імені. Зменште радіус впливу так: - - використовуйте агент «читач» у режимі лише читання або з вимкненими інструментами, щоб підсумовувати недовірений вміст - - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами - - також розглядайте декодований текст файлів/документів як недовірений: OpenResponses + - використовуйте read-only або tool-disabled агента-"reader" для підсумовування недовіреного вмісту + - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів із увімкненими інструментами + - також вважайте розкодований текст файла/документа недовіреним: OpenResponses `input_file` і витягування медіавкладень обгортають витягнутий текст у - явні маркери межі зовнішнього вмісту, замість передавання необробленого тексту файлу - - використовуйте sandbox і суворі списки дозволених інструментів + явні маркери межі зовнішнього вмісту замість передавання сирого тексту файла + - використовуйте sandboxing і суворі allowlist для інструментів Деталі: [Безпека](/uk/gateway/security). - - Так, для більшості налаштувань. Ізоляція бота за допомогою окремих облікових записів і номерів телефону - зменшує радіус ураження, якщо щось піде не так. Це також спрощує ротацію - облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. + + Так, для більшості налаштувань. Ізоляція бота окремими акаунтами й номерами телефону + зменшує радіус впливу, якщо щось піде не так. Це також спрощує ротацію + облікових даних або відкликання доступу без впливу на ваші особисті акаунти. - Почніть з малого. Надавайте доступ лише до інструментів і облікових записів, які вам справді потрібні, і розширюйте + Почніть із малого. Надайте доступ лише до інструментів і акаунтів, які вам справді потрібні, і розширюйте пізніше за потреби. - Документація: [Безпека](/uk/gateway/security), [Сполучення](/uk/channels/pairing). + Документація: [Безпека](/uk/gateway/security), [Pairing](/uk/channels/pairing). Ми **не** рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон: - - Тримайте особисті повідомлення в **режимі сполучення** або зі строгим списком дозволів. - - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені. - - Нехай він створює чернетку, а потім **підтверджуйте перед надсиланням**. + - Тримайте DM у **режимі pairing** або суворому allowlist. + - Використовуйте **окремий номер або акаунт**, якщо хочете, щоб він надсилав повідомлення від вашого імені. + - Дайте йому створити чернетку, а потім **підтверджуйте перед надсиланням**. - Якщо хочете експериментувати, робіть це в окремому обліковому записі й тримайте його ізольованим. Див. + Якщо хочете експериментувати, робіть це на окремому акаунті й тримайте його ізольованим. Див. [Безпека](/uk/gateway/security). - - Так, **якщо** агент працює лише як чат і вхідні дані є довіреними. Менші рівні - більш вразливі до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами - або під час читання недовіреного вмісту. Якщо вам потрібно використовувати меншу модель, жорстко обмежте + + Так, **якщо** агент працює лише в чаті, а введення є довіреним. Менші рівні + більш вразливі до перехоплення інструкцій, тому уникайте їх для агентів із увімкненими інструментами + або під час читання недовіреного вмісту. Якщо потрібно використовувати меншу модель, жорстко обмежте інструменти й запускайте всередині sandbox. Див. [Безпека](/uk/gateway/security). - - Коди сполучення надсилаються **лише** коли невідомий відправник пише боту, а - `dmPolicy: "pairing"` увімкнено. Сам по собі `/start` не генерує код. + + Коди pairing надсилаються **лише** коли невідомий відправник пише боту й + `dmPolicy: "pairing"` увімкнено. `/start` сам по собі не генерує код. Перевірте очікувані запити: @@ -1837,39 +1836,39 @@ x-i18n: openclaw pairing list telegram ``` - Якщо вам потрібен негайний доступ, додайте свій ідентифікатор відправника до списку дозволів або встановіть `dmPolicy: "open"` - для цього облікового запису. + Якщо потрібен негайний доступ, додайте id відправника до allowlist або встановіть `dmPolicy: "open"` + для цього акаунта. - - Ні. Типова політика особистих повідомлень WhatsApp — **сполучення**. Невідомі відправники отримують лише код сполучення, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які запускаєте ви. + + Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише код pairing, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише в чатах, які отримує, або на явні надсилання, які ви запускаєте. - Підтвердьте сполучення за допомогою: + Підтвердьте pairing за допомогою: ```bash openclaw pairing approve whatsapp ``` - Перелічіть очікувані запити: + Перегляньте очікувані запити: ```bash openclaw pairing list whatsapp ``` - Запит номера телефону в майстрі: він використовується для налаштування вашого **списку дозволів/власника**, щоб ваші власні особисті повідомлення були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. + Запит номера телефону в майстрі: він використовується для налаштування вашого **allowlist/owner**, щоб ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. -## Команди чату, переривання задач і «воно не зупиняється» +## Команди чату, переривання завдань і "це не зупиняється" - Більшість внутрішніх повідомлень або повідомлень інструментів з’являються лише коли для цього сеансу ввімкнено - **verbose**, **trace** або **reasoning**. + Більшість внутрішніх повідомлень або повідомлень інструментів з’являються лише тоді, коли для цього сеансу + ввімкнено **verbose**, **trace** або **reasoning**. - Виправте це в чаті, де ви це бачите: + Виправте в чаті, де ви це бачите: ``` /verbose off @@ -1877,16 +1876,16 @@ x-i18n: /reasoning off ``` - Якщо шум усе ще є, перевірте налаштування сеансу в Control UI і встановіть verbose - на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, встановленим + Якщо шум усе ще є, перевірте налаштування сеансу в Control UI та встановіть verbose + на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, установленим на `on` у конфігурації. - Документація: [Міркування та verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security/index#reasoning-and-verbose-output-in-groups). + Документація: [Thinking і verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security/index#reasoning-and-verbose-output-in-groups). - - Надішліть будь-яке з цього **як окреме повідомлення** (без slash): + + Надішліть будь-яке з цих повідомлень **як окреме повідомлення** (без slash): ``` stop @@ -1910,7 +1909,7 @@ x-i18n: interrupt ``` - Це тригери переривання (не slash-команди). + Це тригери скасування (не slash-команди). Для фонових процесів (з інструмента exec) можна попросити агента виконати: @@ -1920,13 +1919,13 @@ x-i18n: Огляд slash-команд: див. [Slash-команди](/uk/tools/slash-commands). - Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (як-от `/status`) також працюють усередині рядка для відправників зі списку дозволів. + Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад `/status`) також працюють inline для відправників з allowlist. OpenClaw типово блокує обмін повідомленнями **між провайдерами**. Якщо виклик інструмента прив’язаний - до Telegram, він не надсилатиме в Discord, якщо ви явно це не дозволите. + до Telegram, він не надішле в Discord, якщо ви явно цього не дозволите. Увімкніть обмін повідомленнями між провайдерами для агента: @@ -1948,16 +1947,16 @@ x-i18n: - Режим черги керує тим, як нові повідомлення взаємодіють із поточним запуском. Використайте `/queue`, щоб змінити режими: + Режим черги керує тим, як нові повідомлення взаємодіють із виконанням у процесі. Використовуйте `/queue`, щоб змінити режими: - - `steer` - поставити всі очікувані керівні повідомлення в чергу до наступної межі моделі в поточному запуску - - `queue` - застаріле керування по одному повідомленню + - `steer` - поставити всі очікувані керувальні повідомлення в чергу для наступної межі моделі в поточному виконанні + - `queue` - застаріле керування по одному - `followup` - запускати повідомлення по одному - - `collect` - пакетувати повідомлення й відповісти один раз - - `steer-backlog` - скерувати зараз, потім обробити накопичену чергу - - `interrupt` - перервати поточний запуск і почати заново + - `collect` - згрупувати повідомлення й відповісти один раз + - `steer-backlog` - керувати зараз, потім обробити backlog + - `interrupt` - скасувати поточне виконання й почати заново - Типовий режим — `steer`. Для режимів followup можна додати параметри на кшталт `debounce:0.5s cap:25 drop:summarize`. Див. [Черга команд](/uk/concepts/queue) і [Черга керування](/uk/concepts/queue-steering). + Типовий режим — `steer`. Ви можете додати параметри на кшталт `debounce:0.5s cap:25 drop:summarize` для режимів followup. Див. [Черга команд](/uk/concepts/queue) і [Черга steering](/uk/concepts/queue-steering). @@ -1965,17 +1964,17 @@ x-i18n: ## Різне - - В OpenClaw облікові дані та вибір моделі відокремлені. Налаштування `ANTHROPIC_API_KEY` (або збереження API key Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична модель за замовчуванням — це та, яку ви налаштуєте в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для запущеного агента. + + В OpenClaw облікові дані та вибір моделі розділені. Налаштування `ANTHROPIC_API_KEY` (або збереження API-ключа Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична модель за замовчуванням — це та, яку ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який запущено. --- -Усе ще не виходить? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions). +Усе ще не вдається? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions). ## Пов’язане - [FAQ першого запуску](/uk/help/faq-first-run) — встановлення, початкове налаштування, автентифікація, підписки, ранні збої -- [FAQ моделей](/uk/help/faq-models) — вибір моделі, failover, профілі автентифікації -- [Усунення неполадок](/uk/help/troubleshooting) — triage за симптомами +- [FAQ щодо моделей](/uk/help/faq-models) — вибір моделі, перемикання в разі збою, профілі автентифікації +- [Усунення несправностей](/uk/help/troubleshooting) — діагностика за симптомами diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index 94a8a7593..0b8c35541 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -4,38 +4,38 @@ read_when: - Розуміння правил виявлення та завантаження Plugin - Робота з пакетами Plugin, сумісними з Codex/Claude sidebarTitle: Install and Configure -summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw +summary: Встановлення, налаштування й керування плагінами OpenClaw title: Plugins x-i18n: - generated_at: "2026-05-03T15:53:33Z" + generated_at: "2026-05-03T17:12:20Z" model: gpt-5.5 provider: openai - source_hash: 937623bf3bfd7832680264b28deaef58970b35fdae7cfa0e5731c097eccc38e6 + source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0 source_path: tools/plugin.md workflow: 16 --- -Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей, -оболонки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, -розуміння медіа, генерація зображень, генерація відео, отримання вебвмісту, вебпошук -та інше. Деякі плагіни є **core** (постачаються з OpenClaw), інші -є **зовнішніми**. Більшість зовнішніх плагінів публікуються та знаходяться через -[ClawHub](/uk/tools/clawhub). Npm залишається підтримуваним для прямих встановлень і для -тимчасового набору пакетів плагінів, що належать OpenClaw, доки ця міграція завершується. +Plugins розширюють OpenClaw новими можливостями: канали, постачальники моделей, +середовища агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, +голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, веботримання, вебпошук +та інше. Деякі plugins є **основними** (постачаються з OpenClaw), інші +є **зовнішніми**. Більшість зовнішніх plugins публікуються й виявляються через +[ClawHub](/uk/tools/clawhub). Npm і далі підтримується для прямих установлень і для +тимчасового набору пакетів plugins, що належать OpenClaw, поки ця міграція завершується. ## Швидкий старт -Приклади встановлення, перегляду списку, видалення, оновлення та публікації для копіювання дивіться в -[Керування плагінами](/uk/plugins/manage-plugins). +Приклади встановлення, перегляду списку, видалення, оновлення та публікації для копіювання і вставлення див. +[Керування plugins](/uk/plugins/manage-plugins). - + ```bash openclaw plugins list ``` - + ```bash # Search ClawHub plugins openclaw plugins search "calendar" @@ -56,7 +56,7 @@ x-i18n: - + ```bash openclaw gateway restart ``` @@ -65,17 +65,17 @@ x-i18n: - - У запущеному Gateway команди лише для власника `/plugins enable` і `/plugins disable` - запускають перезавантажувач конфігурації Gateway. Gateway перезавантажує runtime-поверхні плагінів - у процесі, а нові ходи агента перебудовують список інструментів із - оновленого реєстру. `/plugins install` змінює вихідний код плагіна, тому - Gateway запитує перезапуск, замість удавати, що поточний процес може + + У запущеному Gateway доступні лише власнику `/plugins enable` і `/plugins disable` + запускають перезавантажувач конфігурації Gateway. Gateway перезавантажує runtime-поверхні + plugin у поточному процесі, а нові ходи агента перебудовують свій список інструментів з + оновленого реєстру. `/plugins install` змінює вихідний код plugin, тому + Gateway запитує перезапуск замість того, щоб удавати, ніби поточний процес може безпечно перезавантажити вже імпортовані модулі. - + ```bash openclaw plugins inspect --runtime --json @@ -83,14 +83,14 @@ x-i18n: openclaw --help ``` - Використовуйте `--runtime`, коли потрібно довести зареєстровані інструменти, сервіси, методи Gateway, - hooks або CLI-команди, що належать плагіну. Звичайний `inspect` є холодною - перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime плагіна. + Використовуйте `--runtime`, коли потрібно довести зареєстровані інструменти, сервіси, методи gateway, + хуки або CLI-команди, що належать plugin. Звичайний `inspect` є холодною + перевіркою маніфесту/реєстру й навмисно уникає імпорту runtime plugin. -Якщо ви віддаєте перевагу керуванню в чаті, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub: @@ -98,86 +98,85 @@ x-i18n: /plugin enable ``` -Шлях встановлення використовує той самий розв’язувач, що й CLI: локальний шлях/архів, явний +Шлях встановлення використовує той самий резолвер, що й CLI: локальний шлях/архів, явний `clawhub:`, явний `npm:`, явний `git:` або проста специфікація пакета через npm. -Якщо конфігурація недійсна, встановлення зазвичай завершується закритою відмовою й спрямовує вас до -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення bundled-плагіна -для плагінів, які явно вмикають +Якщо конфігурація недійсна, встановлення зазвичай відмовляє закрито й спрямовує вас до +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення +вбудованого plugin для plugins, які явно обирають `openclaw.install.allowInvalidConfigRecovery`. -Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється до цього плагіна: -запуск записує проблему `plugins.entries..config`, пропускає цей плагін під час -завантаження та залишає інші плагіни й канали онлайн. Запустіть `openclaw doctor --fix`, -щоб ізолювати погану конфігурацію плагіна, вимкнувши цей запис плагіна та видаливши -його недійсне конфігураційне навантаження; звичайна резервна копія конфігурації зберігає попередні значення. -Коли конфігурація каналу посилається на плагін, який більше не можна знайти, але той самий -застарілий id плагіна залишається в конфігурації плагіна або записах встановлення, запуск Gateway -записує попередження та пропускає цей канал замість блокування всіх інших каналів. -Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/плагіна; невідомі -ключі каналів без доказів застарілого плагіна все одно не проходять валідацію, щоб помилки введення залишалися -видимими. -Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни вважаються інертними: -запуск Gateway пропускає виявлення/завантаження плагінів, а `openclaw doctor` зберігає -вимкнену конфігурацію плагіна замість автоматичного видалення. Повторно увімкніть плагіни перед -запуском очищення doctor, якщо хочете видалити застарілі id плагінів. +Під час запуску Gateway недійсна конфігурація plugin відмовляє закрито, як і будь-яка інша недійсна +конфігурація. Запустіть `openclaw doctor --fix`, щоб ізолювати погану конфігурацію plugin, +вимкнувши цей запис plugin і видаливши його недійсне корисне навантаження конфігурації; звичайна +резервна копія конфігурації зберігає попередні значення. +Коли конфігурація каналу посилається на plugin, який більше не виявляється, але той самий +застарілий id plugin лишається в конфігурації plugin або записах установлення, запуск Gateway +записує попередження в журнали й пропускає цей канал замість блокування всіх інших каналів. +Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/plugin; невідомі +ключі каналів без доказів застарілого plugin і далі не проходять валідацію, щоб помилки друку залишались +помітними. +Якщо задано `plugins.enabled: false`, застарілі посилання на plugin трактуються як інертні: +запуск Gateway пропускає роботу з виявлення/завантаження plugin, а `openclaw doctor` зберігає +вимкнену конфігурацію plugin замість автоматичного видалення. Повторно ввімкніть plugins перед +запуском очищення doctor, якщо хочете видалити застарілі id plugin. -Встановлення залежностей плагіна відбувається лише під час явних потоків встановлення/оновлення або -ремонту doctor. Запуск Gateway, перезавантаження конфігурації та runtime-інспекція -не запускають менеджери пакетів і не ремонтують дерева залежностей. Локальні плагіни вже мають -мати встановлені залежності, тоді як npm-, git- і ClawHub-плагіни -встановлюються в керовані корені плагінів OpenClaw. Залежності npm можуть бути hoisted -у межах керованого npm-кореня OpenClaw; встановлення/оновлення сканує цей керований корінь перед -довірою, а видалення прибирає npm-керовані пакети через npm. Зовнішні плагіни -та власні шляхи завантаження все одно потрібно встановлювати через `openclaw plugins install`. +Установлення залежностей plugin відбувається лише під час явних потоків install/update або +виправлення doctor. Запуск Gateway, перезавантаження конфігурації та інспекція runtime не +запускають менеджери пакетів і не відновлюють дерева залежностей. Локальні plugins вже повинні +мати встановлені залежності, тоді як npm, git і ClawHub plugins встановлюються +в керовані корені plugin OpenClaw. Залежності npm можуть бути підняті +в межах керованого npm-кореня OpenClaw; install/update сканує цей керований корінь перед +довірою, а uninstall видаляє керовані npm пакети через npm. Зовнішні plugins +і власні шляхи завантаження все одно мають бути встановлені через `openclaw plugins install`. Використовуйте `openclaw plugins list --json`, щоб побачити статичний `dependencyStatus` для кожного -видимого плагіна без імпорту runtime-коду або ремонту залежностей. -Дивіться [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) щодо життєвого циклу -під час встановлення. +видимого plugin без імпорту runtime-коду або відновлення залежностей. +Див. [Розв’язання залежностей Plugin](/uk/plugins/dependency-resolution) щодо +життєвого циклу під час встановлення. -Для npm-встановлень змінні селектори, як-от `latest` або dist-tag, розв’язуються -перед встановленням, а потім закріплюються за точною перевіреною версією в керованому +Для npm-встановлень змінні селектори, такі як `latest` або dist-tag, розв’язуються +перед установленням, а потім закріплюються на точній перевіреній версії в керованому npm-корені OpenClaw. Після завершення npm OpenClaw перевіряє, що встановлений -запис `package-lock.json` усе ще відповідає розв’язаній версії та integrity. Якщо -npm записує інші метадані пакета, встановлення завершується помилкою, а керований пакет -відкочується замість прийняття іншого артефакту плагіна. +запис `package-lock.json` досі відповідає розв’язаній версії та цілісності. Якщо +npm записує інші метадані пакета, установлення завершується помилкою, а керований пакет +відкочується замість прийняття іншого артефакту plugin. -Вихідні checkout-и є pnpm-робочими просторами. Якщо ви клонуєте OpenClaw, щоб працювати над bundled -плагінами, запустіть `pnpm install`; тоді OpenClaw завантажує bundled плагіни з -`extensions/`, тож правки й пакетно-локальні залежності використовуються напряму. -Звичайні встановлення кореня npm призначені для пакетованого OpenClaw, а не для розробки -з вихідного checkout-а. +Вихідні checkout-и є pnpm workspaces. Якщо ви клонуєте OpenClaw, щоб працювати над вбудованими +plugins, запустіть `pnpm install`; після цього OpenClaw завантажує вбудовані plugins з +`extensions/`, тому зміни та локальні для пакета залежності використовуються напряму. +Звичайні встановлення в npm root призначені для пакетованого OpenClaw, а не для розробки +у checkout вихідного коду. -## Типи плагінів +## Типи Plugin -OpenClaw розпізнає два формати плагінів: +OpenClaw розпізнає два формати plugin: | Формат | Як це працює | Приклади | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | -| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні плагіни, спільнотні npm-пакети | -| **Bundle** | Codex/Claude/Cursor-сумісна структура; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Нативний** | `openclaw.plugin.json` + runtime-модуль; виконується в процесі | Офіційні plugins, npm-пакети спільноти | +| **Bundle** | Сумісна з Codex/Claude/Cursor структура; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва відображаються в `openclaw plugins list`. Дивіться [Plugin Bundles](/uk/plugins/bundles) для деталей bundle. +Обидва з’являються в `openclaw plugins list`. Див. [Plugin Bundles](/uk/plugins/bundles) для подробиць про bundle. -Якщо ви пишете нативний плагін, почніть із [Створення Plugins](/uk/plugins/building-plugins) -та [Огляду Plugin SDK](/uk/plugins/sdk-overview). +Якщо ви пишете нативний plugin, почніть з [Створення Plugins](/uk/plugins/building-plugins) +і [Огляд Plugin SDK](/uk/plugins/sdk-overview). -## Точки входу пакетів +## Точки входу пакета -Нативні npm-пакети плагінів мають оголошувати `openclaw.extensions` у `package.json`. -Кожен запис має залишатися всередині каталогу пакета й розв’язуватися в читабельний -runtime-файл або у вихідний файл TypeScript з виведеним збудованим JavaScript -аналогом, наприклад `src/index.ts` до `dist/index.js`. -Пакетовані встановлення мають постачати цей JavaScript runtime-вивід. Резервний варіант -вихідного TypeScript призначений для вихідних checkout-ів і локальних шляхів розробки, а не для -npm-пакетів, встановлених у керований корінь плагінів OpenClaw. +Нативні npm-пакети plugin мають оголошувати `openclaw.extensions` у `package.json`. +Кожен запис має залишатися всередині каталогу пакета й розв’язуватися до читабельного +runtime-файлу або до вихідного TypeScript-файлу з виведеним зібраним JavaScript +відповідником, як-от `src/index.ts` до `dist/index.js`. +Пакетовані встановлення мають постачати цей JavaScript runtime-вивід. Резервний варіант із +вихідним TypeScript призначений для checkout-ів вихідного коду та шляхів локальної розробки, а не для +npm-пакетів, установлених у керований корінь plugin OpenClaw. -Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розташовані за -тими самими шляхами, що й вихідні записи. Якщо присутній, `runtimeExtensions` має містити +Використовуйте `openclaw.runtimeExtensions`, коли опубліковані runtime-файли не розміщені за +тими самими шляхами, що й вихідні записи. Коли `runtimeExtensions` присутній, він має містити рівно один запис для кожного запису `extensions`. Невідповідні списки провалюють встановлення та -виявлення плагінів замість тихого повернення до вихідних шляхів. Якщо ви також -публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його збудованого -JavaScript-аналога; цей файл обов’язковий, коли оголошений. +виявлення plugin, а не тихо повертаються до вихідних шляхів. Якщо ви також +публікуєте `openclaw.setupEntry`, використовуйте `openclaw.runtimeSetupEntry` для його зібраного +JavaScript-відповідника; цей файл є обов’язковим, коли оголошений. ```json { @@ -189,21 +188,21 @@ JavaScript-аналога; цей файл обов’язковий, коли } ``` -## Офіційні плагіни +## Офіційні plugins -### npm-пакети, що належать OpenClaw, під час міграції +### Npm-пакети, що належать OpenClaw, під час міграції -ClawHub є основним шляхом розповсюдження для більшості плагінів. Поточні пакетовані -випуски OpenClaw уже містять багато офіційних плагінів, тому вони не потребують -окремих npm-встановлень у звичайних налаштуваннях. Доки кожен плагін, що належить OpenClaw, -не мігрує до ClawHub, OpenClaw усе ще постачає деякі пакети плагінів `@openclaw/*` -на npm для старіших/власних встановлень і прямих npm-процесів. +ClawHub є основним шляхом розповсюдження для більшості plugins. Поточні пакетовані +випуски OpenClaw уже містять багато офіційних plugins, тому в нормальних налаштуваннях їм не потрібні +окремі npm-встановлення. Поки кожен plugin, що належить OpenClaw, не +мігрував до ClawHub, OpenClaw і далі постачає деякі пакети plugin `@openclaw/*` в +npm для старіших/власних установлень і прямих npm-процесів. -Якщо npm повідомляє, що пакет плагіна `@openclaw/*` застарілий, ця версія пакета -походить зі старішої зовнішньої лінійки пакетів. Використовуйте bundled плагін із +Якщо npm повідомляє, що пакет plugin `@openclaw/*` застарілий, ця версія пакета +походить зі старішої лінійки зовнішніх пакетів. Використовуйте вбудований plugin з поточного OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет. -| Плагін | Пакет | Документація | +| Plugin | Пакет | Документація | | --------------- | -------------------------- | ------------------------------------------ | | BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/uk/channels/bluebubbles) | | Discord | `@openclaw/discord` | [Discord](/uk/channels/discord) | @@ -219,10 +218,10 @@ ClawHub є основним шляхом розповсюдження для б | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Core (постачається з OpenClaw) +### Основні (постачаються з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -230,27 +229,27 @@ ClawHub є основним шляхом розповсюдження для б `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — bundled пошук пам’яті (за замовчуванням через `plugins.slots.memory`) - - `memory-lancedb` — довготривала пам’ять на базі LanceDB з автоматичним згадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`) + + - `memory-core` — вбудований пошук пам’яті (типово через `plugins.slots.memory`) + - `memory-lancedb` — довгострокова пам’ять на основі LanceDB з автоматичним пригадуванням/захопленням (задайте `plugins.slots.memory = "memory-lancedb"`) - Дивіться [Memory LanceDB](/uk/plugins/memory-lancedb) щодо налаштування embeddings, сумісних з OpenAI, - прикладів Ollama, лімітів згадування та усунення несправностей. + Див. [Memory LanceDB](/uk/plugins/memory-lancedb) щодо сумісного з OpenAI + налаштування embeddings, прикладів Ollama, обмежень пригадування та усунення несправностей. - + `elevenlabs`, `microsoft` - - - `browser` — bundled плагін браузера для інструмента браузера, CLI `openclaw browser`, методу gateway `browser.request`, runtime браузера та стандартного сервісу керування браузером (увімкнено за замовчуванням; вимкніть перед заміною) - - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено за замовчуванням) + + - `browser` — вбудований browser plugin для інструмента browser, CLI `openclaw browser`, gateway-методу `browser.request`, browser runtime і стандартного сервісу керування browser (увімкнено типово; вимкніть перед заміною) + - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнено типово) -Шукаєте сторонні плагіни? Дивіться [Плагіни спільноти](/uk/plugins/community). +Шукаєте сторонні plugins? Див. [Plugins спільноти](/uk/plugins/community). ## Конфігурація @@ -268,124 +267,120 @@ ClawHub є основним шляхом розповсюдження для б } ``` -| Поле | Опис | +| Поле | Опис | | ---------------- | --------------------------------------------------------- | -| `enabled` | Головний перемикач (типово: `true`) | -| `allow` | Список дозволених Plugin (необов’язково) | -| `deny` | Список заборонених Plugin (необов’язково; deny перемагає) | -| `load.paths` | Додаткові файли/каталоги plugin | +| `enabled` | Головний перемикач (за замовчуванням: `true`) | +| `allow` | Список дозволених Plugin (необов'язково) | +| `deny` | Список заборонених Plugin (необов'язково; заборона має пріоритет) | +| `load.paths` | Додаткові файли/каталоги Plugin | | `slots` | Ексклюзивні селектори слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі + конфігурація для окремого plugin | +| `entries.\` | Перемикачі та конфігурація для окремих Plugin | -`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися або -надавати інструменти можуть лише перелічені plugins, навіть якщо `tools.allow` -містить `"*"` або конкретну назву інструмента, що належить plugin. Якщо список -дозволених інструментів посилається на інструменти plugin, додайте ідентифікатори -відповідних plugins до `plugins.allow` або приберіть `plugins.allow`; `openclaw doctor` -попереджає про таку структуру. +`plugins.allow` є ексклюзивним. Коли він непорожній, завантажуватися +або надавати інструменти можуть лише перелічені Plugin, навіть якщо `tools.allow` містить `"*"` або конкретну назву +інструмента, що належить Plugin. Якщо список дозволених інструментів посилається на інструменти Plugin, додайте ідентифікатори Plugin-власників +до `plugins.allow` або вилучіть `plugins.allow`; `openclaw doctor` попереджає про таку +форму. -Зміни конфігурації, внесені через `/plugins enable` або `/plugins disable`, -запускають перезавантаження plugins Gateway у поточному процесі. Нові ходи агента -перебудовують свій список інструментів з оновленого реєстру plugins. Операції, -що змінюють джерела, як-от встановлення, оновлення та видалення, і далі -перезапускають процес Gateway, бо вже імпортовані модулі plugin неможливо -безпечно замінити на місці. +Зміни конфігурації, внесені через `/plugins enable` або `/plugins disable`, запускають +перезавантаження Plugin Gateway у межах процесу. Нові ходи агента перебудовують свій список інструментів із +оновленого реєстру Plugin. Операції, що змінюють джерело, як-от встановлення, +оновлення та видалення, усе ще перезапускають процес Gateway, оскільки вже імпортовані +модулі Plugin не можна безпечно замінити на місці. -`openclaw plugins list` — це локальний знімок реєстру/config plugins. Plugin -зі станом `enabled` там означає, що збережений реєстр і поточна config дозволяють -plugin брати участь. Це не доводить, що вже запущений віддалений Gateway -перезавантажився або перезапустився з тим самим кодом plugin. У налаштуваннях -VPS/контейнерів із процесами-обгортками надсилайте перезапуски або записи, що -запускають перезавантаження, до фактичного процесу `openclaw gateway run`, або -використовуйте `openclaw gateway restart` для запущеного Gateway, коли -перезавантаження повідомляє про помилку. +`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugin. Plugin зі станом +`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють цьому +Plugin брати участь. Це не доводить, що вже запущений віддалений Gateway +перезавантажився або перезапустився з тим самим кодом Plugin. У налаштуваннях VPS/контейнерів +із процесами-обгортками надсилайте перезапуски або записи, що запускають перезавантаження, фактичному +процесу `openclaw gateway run`, або використовуйте `openclaw gateway restart` для +запущеного Gateway, коли перезавантаження повідомляє про помилку. - - **Вимкнений**: plugin існує, але правила ввімкнення вимкнули його. Config збережено. - - **Відсутній**: config посилається на ідентифікатор plugin, якого не знайшло виявлення. - - **Недійсний**: plugin існує, але його config не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей plugin; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та вилучивши його config payload. + - **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. + - **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який виявлення не знайшло. + - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Запуск Gateway пропускає лише цей Plugin; `openclaw doctor --fix` може помістити недійсний запис у карантин, вимкнувши його та вилучивши його конфігураційне навантаження. ## Виявлення та пріоритет -OpenClaw сканує plugins у такому порядку (перший збіг перемагає): +OpenClaw сканує Plugin у такому порядку (перший збіг перемагає): - + `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, що вказують - назад на власні паковані каталоги bundled plugins OpenClaw, ігноруються; - запустіть `openclaw doctor --fix`, щоб прибрати ці застарілі aliases. + назад на власні упаковані каталоги вбудованих Plugin OpenClaw, ігноруються; + виконайте `openclaw doctor --fix`, щоб вилучити ці застарілі псевдоніми. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - - Постачаються з OpenClaw. Багато з них увімкнені типово (провайдери моделей, мовлення). + + Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення). Інші потребують явного ввімкнення. -Паковані встановлення та Docker-образи зазвичай розв’язують bundled plugins з -скомпільованого дерева `dist/extensions`. Якщо вихідний каталог bundled plugin -примонтовано поверх відповідного пакованого шляху джерел, наприклад -`/app/extensions/synology-chat`, OpenClaw розглядає цей примонтований каталог -джерел як overlay джерел bundled plugin і виявляє його перед пакованим bundle -`/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних -циклів мейнтейнерів без перемикання кожного bundled plugin назад на джерела -TypeScript. Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб -примусово використовувати паковані dist bundles, навіть коли присутні монтування -source overlay. +Упаковані встановлення та образи Docker зазвичай визначають вбудовані Plugin з +скомпільованого дерева `dist/extensions`. Якщо вихідний каталог вбудованого Plugin +змонтовано поверх відповідного упакованого вихідного шляху, наприклад +`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований вихідний каталог +як вбудоване вихідне накладання та виявляє його перед упакованим +пакетом `/app/dist/extensions/synology-chat`. Це зберігає працездатність контейнерних +циклів супровідників без перемикання кожного вбудованого Plugin назад на вихідний код TypeScript. +Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати упаковані dist-пакети +навіть за наявності змонтованих вихідних накладань. ### Правила ввімкнення -- `plugins.enabled: false` вимикає всі plugins і пропускає роботу з виявлення/завантаження plugins -- `plugins.deny` завжди перемагає allow -- `plugins.entries.\.enabled: false` вимикає цей plugin -- Plugins з робочої області **типово вимкнені** (їх потрібно явно ввімкнути) -- Bundled plugins дотримуються вбудованого набору default-on, якщо його не перевизначено -- Ексклюзивні слоти можуть примусово ввімкнути вибраний plugin для цього слота -- Деякі bundled opt-in plugins вмикаються автоматично, коли config називає - поверхню, що належить plugin, як-от provider model ref, channel config або harness - runtime -- Застаріла config plugin зберігається, поки активний `plugins.enabled: false`; - повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете вилучити застарілі ids -- Маршрути Codex сімейства OpenAI зберігають окремі межі plugin: - `openai-codex/*` належить OpenAI plugin, тоді як bundled Codex - app-server plugin вибирається через `agentRuntime.id: "codex"` або застарілі - model refs `codex/*` +- `plugins.enabled: false` вимикає всі Plugin і пропускає роботу з виявлення/завантаження Plugin +- `plugins.deny` завжди має пріоритет над allow +- `plugins.entries.\.enabled: false` вимикає цей Plugin +- Plugin з походженням із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Вбудовані Plugin дотримуються вбудованого набору ввімкнених за замовчуванням, якщо це не перевизначено +- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота +- Деякі вбудовані opt-in Plugin вмикаються автоматично, коли конфігурація називає + поверхню, що належить Plugin, як-от посилання на модель постачальника, конфігурація каналу або + runtime стенда +- Застаріла конфігурація Plugin зберігається, доки активний `plugins.enabled: false`; + повторно ввімкніть Plugin перед запуском очищення doctor, якщо хочете вилучити застарілі ідентифікатори +- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin: + `openai-codex/*` належить OpenAI Plugin, тоді як вбудований Plugin app-server Codex + вибирається через `agentRuntime.id: "codex"` або застарілі + посилання на модель `codex/*` -## Усунення проблем runtime hooks +## Усунення проблем із runtime-хуками -Якщо plugin відображається в `plugins list`, але побічні ефекти або hooks -`register(api)` не виконуються в live chat traffic, спершу перевірте це: +Якщо Plugin відображається в `plugins list`, але побічні ефекти або хуки `register(api)` +не виконуються в живому чат-трафіку, спершу перевірте це: -- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні - URL Gateway, профіль, шлях config і процес саме ті, які ви редагуєте. -- Перезапустіть live Gateway після змін встановлення/config/коду plugin. У - контейнерах-обгортках PID 1 може бути лише supervisor; перезапустіть або - надішліть сигнал дочірньому процесу `openclaw gateway run`. -- Використайте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації hooks і - діагностику. Небандлові conversation hooks, як-от `llm_input`, - `llm_output`, `before_agent_finalize` і `agent_end`, потребують +- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні + URL Gateway, профіль, шлях конфігурації та процес є саме тими, які ви редагуєте. +- Перезапустіть живий Gateway після змін встановлення/конфігурації/коду Plugin. У контейнерах-обгортках + PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому + процесу `openclaw gateway run`. +- Використайте `openclaw plugins inspect --runtime --json`, щоб підтвердити реєстрації хуків і + діагностику. Невбудованим хукам розмови, як-от `llm_input`, + `llm_output`, `before_agent_finalize` і `agent_end`, потрібен `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до - розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі - створить assistant output. -- Для доказу ефективної моделі сесії використовуйте `openclaw sessions` або - поверхні session/status Gateway, а під час налагодження provider payloads запускайте +- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується перед розв'язанням моделі + для ходів агента; `llm_output` виконується лише після того, як спроба моделі + створить вивід асистента. +- Для підтвердження ефективної моделі сесії використовуйте `openclaw sessions` або + поверхні сесії/статусу Gateway, а під час налагодження навантажень постачальника запускайте Gateway з `--raw-stream --raw-stream-path `. -### Повільне налаштування інструментів plugin +### Повільне налаштування інструментів Plugin -Якщо ходи агента, схоже, зависають під час підготовки інструментів, увімкніть trace logging і -перевірте рядки таймінгів фабрик інструментів plugin: +Якщо здається, що ходи агента зависають під час підготовки інструментів, увімкніть трасувальне логування та +перевірте рядки часу виконання фабрики інструментів Plugin: ```bash openclaw config set logging.level trace @@ -398,25 +393,25 @@ openclaw logs --follow [trace:plugin-tools] factory timings ... ``` -Підсумок перелічує загальний час фабрик і найповільніші фабрики інструментів plugin, -зокрема plugin id, оголошені назви інструментів, форму результату та чи є інструмент -необов’язковим. Повільні рядки підвищуються до warnings, коли одна фабрика займає -щонайменше 1 с або загальна підготовка фабрик інструментів plugin займає щонайменше 5 с. +Зведення перелічує загальний час фабрики та найповільніші фабрики інструментів Plugin, +включно з ідентифікатором Plugin, оголошеними назвами інструментів, формою результату та тим, чи є інструмент +необов'язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика займає +щонайменше 1 с або загальна підготовка фабрик інструментів Plugin займає щонайменше 5 с. -OpenClaw кешує успішні результати фабрик інструментів plugin для повторних розв’язань +OpenClaw кешує успішні результати фабрик інструментів Plugin для повторних розв'язань з тим самим ефективним контекстом запиту. Ключ кешу включає ефективну -runtime config, workspace, agent/session ids, sandbox policy, browser settings, -delivery context, requester identity і ownership state, тому фабрики, що -залежать від цих довірених полів, запускаються повторно, коли контекст змінюється. +runtime-конфігурацію, робочий простір, ідентифікатори агента/сесії, політику пісочниці, налаштування браузера, +контекст доставки, ідентичність запитувача та стан власності, тому фабрики, що +залежать від цих довірених полів, повторно виконуються, коли контекст змінюється. -Якщо один plugin домінує в таймінгах, перевірте його runtime registrations: +Якщо один Plugin домінує за часом, перевірте його runtime-реєстрації: ```bash openclaw plugins inspect --runtime --json ``` -Потім оновіть, перевстановіть або вимкніть цей plugin. Авторам plugins слід переносити -дороге завантаження залежностей за шлях виконання інструмента, а не робити це +Потім оновіть, перевстановіть або вимкніть цей Plugin. Автори Plugin мають переносити +дороге завантаження залежностей у шлях виконання інструмента, а не робити це всередині фабрики інструмента. ### Дубльоване володіння каналом або інструментом @@ -427,35 +422,34 @@ openclaw plugins inspect --runtime --json - `channel setup already registered: ()` - `plugin tool name conflict (): ` -Це означає, що кілька ввімкнених plugins намагаються володіти тим самим каналом, -потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній -channel plugin, встановлений поруч із bundled plugin, який тепер надає той самий channel id. +Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом, +потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу, +установлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу. Кроки налагодження: -- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений plugin - і походження. -- Запустіть `openclaw plugins inspect --runtime --json` для кожного підозрюваного plugin і - порівняйте `channels`, `channelConfigs`, `tools` і діагностику. -- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення - packages plugin, щоб збережені metadata відображали поточне встановлення. -- Перезапустіть Gateway після змін встановлення, реєстру або config. +- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin + і його походження. +- Виконайте `openclaw plugins inspect --runtime --json` для кожного підозрюваного Plugin і + порівняйте `channels`, `channelConfigs`, `tools` та діагностику. +- Виконайте `openclaw plugins registry --refresh` після встановлення або вилучення + пакетів Plugin, щоб збережені метадані відображали поточне встановлення. +- Перезапустіть Gateway після змін встановлення, реєстру або конфігурації. Варіанти виправлення: -- Якщо один plugin навмисно замінює інший для того самого channel id, бажаний - plugin має оголосити `channelConfigs..preferOver` з ідентифікатором - plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). -- Якщо дублікат випадковий, вимкніть одну сторону за допомогою - `plugins.entries..enabled: false` або видаліть застаріле встановлення - plugin. -- Якщо ви явно ввімкнули обидва plugins, OpenClaw зберігає цей запит і - повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте - інструменти, що належать plugin, щоб runtime surface була однозначною. +- Якщо один Plugin навмисно замінює інший для того самого ідентифікатора каналу, бажаний + Plugin має оголосити `channelConfigs..preferOver` з + ідентифікатором Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). +- Якщо дублювання випадкове, вимкніть один бік за допомогою + `plugins.entries..enabled: false` або вилучіть застаріле встановлення Plugin. +- Якщо ви явно ввімкнули обидва Plugin, OpenClaw зберігає цей запит і + повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, що належать Plugin, + щоб runtime-поверхня була однозначною. ## Слоти Plugin (ексклюзивні категорії) -Деякі категорії ексклюзивні (лише одна активна одночасно): +Деякі категорії ексклюзивні (активною може бути лише одна одночасно): ```json5 { @@ -468,12 +462,12 @@ channel plugin, встановлений поруч із bundled plugin, яки } ``` -| Слот | Що контролює | Типово | +| Слот | Що він контролює | За замовчуванням | | --------------- | --------------------- | ------------------- | -| `memory` | Plugin активної пам’яті | `memory-core` | -| `contextEngine` | Активний context engine | `legacy` (вбудований) | +| `memory` | Активний Plugin пам'яті | `memory-core` | +| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | -## Довідник CLI +## Довідка CLI ```bash openclaw plugins list # compact inventory @@ -521,82 +515,82 @@ openclaw plugins enable openclaw plugins disable ``` -Комплектні plugins постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад -комплектні постачальники моделей, комплектні постачальники мовлення та комплектний браузерний -plugin). Інші комплектні plugins усе ще потребують `openclaw plugins enable `. +Пакетні плагіни постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад +пакетні постачальники моделей, пакетні постачальники мовлення та пакетний браузерний +плагін). Інші пакетні плагіни все ще потребують `openclaw plugins enable `. -`--force` перезаписує наявний встановлений plugin або пакет хуків на місці. Використовуйте +`--force` перезаписує наявний установлений плагін або набір хуків на місці. Використовуйте `openclaw plugins update ` для звичайних оновлень відстежуваних npm -plugins. Це не підтримується з `--link`, який повторно використовує шлях до джерела замість +плагінів. Він не підтримується разом із `--link`, який повторно використовує шлях до джерела замість копіювання поверх керованої цілі встановлення. -Коли `plugins.allow` уже задано, `openclaw plugins install` додає id -встановленого plugin до цього списку дозволів перед його ввімкненням. Якщо той самий id plugin -наявний у `plugins.deny`, встановлення видаляє цей застарілий запис заборони, щоб -явно встановлений plugin можна було завантажити одразу після перезапуску. +Коли `plugins.allow` уже задано, `openclaw plugins install` додає +ідентифікатор установленого плагіна до цього списку дозволених перед його ввімкненням. Якщо той самий ідентифікатор плагіна +є в `plugins.deny`, встановлення видаляє цей застарілий запис заборони, щоб +явно встановлений плагін можна було завантажити одразу після перезапуску. -OpenClaw зберігає сталий локальний реєстр plugins як модель холодного читання для -інвентаризації plugins, володіння внесками та планування запуску. Потоки встановлення, оновлення, -видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану plugin. +OpenClaw зберігає постійний локальний реєстр плагінів як модель холодного читання для +інвентаризації плагінів, володіння внесками та планування запуску. Потоки встановлення, оновлення, +видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану плагіна. Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у -верхньорівневому `installRecords` і відновлювані метадані маніфесту в `plugins`. Якщо +верхньорівневому `installRecords` і відновлювані метадані маніфестів у `plugins`. Якщо реєстр відсутній, застарілий або недійсний, `openclaw plugins registry --refresh` перебудовує його подання маніфестів із записів встановлення, політики конфігурації та -метаданих маніфесту/пакета без завантаження модулів runtime plugin. +метаданих маніфестів/пакетів без завантаження модулів середовища виконання плагінів. `openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета -назад із відстежуваним записом plugin і записує нову специфікацію для майбутніх оновлень. -Передавання назви пакета без версії переміщує встановлення з точно зафіксованою версією назад до -типової лінії випусків реєстру. Якщо встановлений npm plugin уже відповідає +специфікації npm пакета з dist-tag або точною версією зіставляє назву пакета +назад із відстежуваним записом плагіна та записує нову специфікацію для майбутніх оновлень. +Передавання назви пакета без версії повертає встановлення з точно зафіксованою версією назад до +стандартної лінії випусків реєстру. Якщо встановлений npm плагін уже відповідає розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення без завантаження, перевстановлення або переписування конфігурації. -Коли `openclaw update` запускається на beta-каналі, записи plugins npm і ClawHub -типової лінії спочатку пробують `@beta` і повертаються до default/latest, коли beta-випуску plugin -не існує. Точні версії та явні теги залишаються зафіксованими. +Коли `openclaw update` виконується на beta-каналі, записи npm і ClawHub +плагінів стандартної лінії спершу пробують `@beta` і повертаються до default/latest, коли beta-випуску +плагіна немає. Точні версії та явні теги залишаються зафіксованими. -`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, оскільки -marketplace-встановлення зберігають метадані джерела marketplace замість npm-специфікації. +`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, тому що +встановлення з маркетплейсу зберігають метадані джерела маркетплейсу замість npm специфікації. `--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних -спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення plugins -і оновлення plugins продовжувати після вбудованих знахідок `critical`, але все одно -не обходить блокування політики plugin `before_install` або блокування через збій сканування. -Сканування встановлення ігнорують поширені тестові файли та каталоги, як-от `tests/`, -`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові mocks; -оголошені runtime-точки входу plugin усе одно скануються, навіть якщо вони використовують одну з +спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє встановлення +плагінів і оновлення плагінів продовжуватися попри вбудовані знахідки `critical`, але все одно +не обходить блокування політики плагінів `before_install` або блокування через помилку сканування. +Сканування під час встановлення ігнорують поширені тестові файли й каталоги, як-от `tests/`, +`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати запаковані тестові моки; +оголошені вхідні точки середовища виконання плагіна все одно скануються, навіть якщо вони використовують одну з цих назв. -Цей прапорець CLI застосовується лише до потоків встановлення/оновлення plugin. Встановлення -залежностей Skills на базі Gateway натомість використовують відповідне перевизначення запиту +Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення +залежностей Skills через Gateway використовують натомість відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. -Якщо plugin, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте -панель керування ClawHub або запустіть `clawhub package rescan `, щоб попросити ClawHub -перевірити його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашій -власній машині; він не просить ClawHub повторно сканувати plugin і не робить заблокований випуск +Якщо плагін, який ви опублікували на ClawHub, приховано або заблоковано скануванням, відкрийте +панель ClawHub або виконайте `clawhub package rescan `, щоб попросити ClawHub перевірити +його знову. `--dangerously-force-unsafe-install` впливає лише на встановлення на вашому власному +комп’ютері; він не просить ClawHub повторно просканувати плагін або зробити заблокований випуск публічним. -Сумісні bundles беруть участь у тому самому потоці списку/інспектування/ввімкнення/вимкнення -plugins. Поточна підтримка runtime охоплює bundle Skills, command-skills Claude, -типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і -оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги хуків Codex. +Сумісні бандли беруть участь у тому самому потоці списку/інспектування/увімкнення/вимкнення +плагінів. Поточна підтримка середовища виконання охоплює бандлові Skills, command-skills Claude, +типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті +`lspServers`, command-skills Cursor і сумісні каталоги хуків Codex. -`openclaw plugins inspect ` також повідомляє виявлені можливості bundle, а також -підтримувані або непідтримувані записи серверів MCP і LSP для plugins на базі bundle. +`openclaw plugins inspect ` також повідомляє виявлені можливості бандла, а також +підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі бандлів. -Джерела marketplace можуть бути назвою відомого marketplace Claude з -`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або -шляхом `marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або git URL. Для віддалених marketplaces записи plugins мають залишатися всередині -клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів. +Джерела маркетплейсу можуть бути відомою Claude назвою маркетплейсу з +`~/.claude/plugins/known_marketplaces.json`, локальним коренем маркетплейсу або шляхом до +`marketplace.json`, скороченням GitHub на кшталт `owner/repo`, URL репозиторію GitHub +або git URL. Для віддалених маркетплейсів записи плагінів мають залишатися всередині +клонованого репозиторію маркетплейсу та використовувати лише відносні джерела шляхів. -Див. [довідник CLI `openclaw plugins`](/uk/cli/plugins) для повної інформації. +Повні відомості дивіться в [довіднику CLI `openclaw plugins`](/uk/cli/plugins). -## Огляд API Plugin +## Огляд API плагінів -Нативні plugins експортують об’єкт входу, який відкриває `register(api)`. Старіші -plugins усе ще можуть використовувати `activate(api)` як застарілий alias, але нові plugins мають +Нативні плагіни експортують об’єкт входу, який надає `register(api)`. Старіші +плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але новим плагінам слід використовувати `register`. ```typescript @@ -618,74 +612,74 @@ export default definePluginEntry({ ``` OpenClaw завантажує об’єкт входу та викликає `register(api)` під час -активації plugin. Завантажувач усе ще повертається до `activate(api)` для старіших plugins, -але комплектні plugins і нові зовнішні plugins мають вважати `register` -публічним контрактом. +активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів, +але пакетні плагіни та нові зовнішні плагіни мають розглядати `register` як +публічний контракт. -`api.registrationMode` повідомляє plugin, чому його точку входу завантажують: +`api.registrationMode` повідомляє плагіну, чому його вхід завантажується: -| Режим | Значення | +| Режим | Значення | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Runtime-активація. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | -| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; довірений код точки входу plugin може завантажуватися, але пропускайте активні побічні ефекти. | -| `setup-only` | Завантаження метаданих налаштування каналу через легку точку входу налаштування. | -| `setup-runtime` | Завантаження налаштування каналу, якому також потрібна runtime-точка входу. | -| `cli-metadata` | Лише збирання метаданих команд CLI. | +| `full` | Активація середовища виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші активні побічні ефекти. | +| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; довірений код входу плагіна може завантажуватися, але пропускайте активні побічні ефекти. | +| `setup-only` | Завантаження метаданих налаштування каналу через легкий вхід налаштування. | +| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен вхід середовища виконання. | +| `cli-metadata` | Лише збирання метаданих команд CLI. | -Точки входу plugins, які відкривають сокети, бази даних, фонові workers або довготривалі -clients, мають захищати ці побічні ефекти через `api.registrationMode === "full"`. -Завантаження discovery кешуються окремо від активаційних завантажень і не замінюють -поточний реєстр Gateway. Discovery не активує, але не є вільним від імпорту: -OpenClaw може виконати довірену точку входу plugin або модуль channel plugin, щоб побудувати -snapshot. Тримайте верхні рівні модулів легкими та без побічних ефектів, а мережеві -clients, subprocesses, listeners, читання облікових даних і запуск служб перемістіть -за шляхи full-runtime. +Входи плагінів, які відкривають сокети, бази даних, фонові робочі процеси або довгоживучі +клієнти, мають обмежувати ці побічні ефекти умовою `api.registrationMode === "full"`. +Завантаження виявлення кешуються окремо від активаційних завантажень і не замінюють +поточний реєстр Gateway. Виявлення є неактиваційним, але не без імпорту: +OpenClaw може виконати довірений вхід плагіна або модуль плагіна каналу, щоб побудувати +знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів, а +мережеві клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб +переносьте за шляхи повного середовища виконання. Поширені методи реєстрації: -| Метод | Що він реєструє | -| --------------------------------------- | --------------------------- | -| `registerProvider` | Постачальник моделей (LLM) | -| `registerChannel` | Канал чату | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Хуки життєвого циклу | -| `registerSpeechProvider` | Text-to-speech / STT | -| `registerRealtimeTranscriptionProvider` | Streaming STT | -| `registerRealtimeVoiceProvider` | Duplex realtime voice | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Постачальник web fetch / scrape | -| `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP endpoint | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Context engine | -| `registerService` | Фонова служба | +| Метод | Що він реєструє | +| --------------------------------------- | --------------------------------------- | +| `registerProvider` | Постачальник моделей (LLM) | +| `registerChannel` | Канал чату | +| `registerTool` | Інструмент агента | +| `registerHook` / `on(...)` | Хуки життєвого циклу | +| `registerSpeechProvider` | Перетворення тексту на мовлення / STT | +| `registerRealtimeTranscriptionProvider` | Потоковий STT | +| `registerRealtimeVoiceProvider` | Дуплексний голос у реальному часі | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Постачальник веботримання / скрейпінгу | +| `registerWebSearchProvider` | Вебпошук | +| `registerHttpRoute` | HTTP кінцева точка | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Рушій контексту | +| `registerService` | Фонова служба | -Поведінка guard для типізованих хуків життєвого циклу: +Поведінка захисту хуків для типізованих хуків життєвого циклу: -- `before_tool_call`: `{ block: true }` є кінцевим; handlers із нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` не виконує дії й не очищує попередній block. -- `before_install`: `{ block: true }` є кінцевим; handlers із нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` не виконує дії й не очищує попередній block. -- `message_sending`: `{ cancel: true }` є кінцевим; handlers із нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` не виконує дії й не очищує попередній cancel. +- `before_tool_call`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: `{ block: false }` є no-op і не очищує попереднє блокування. +- `before_install`: `{ block: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. +- `before_install`: `{ block: false }` є no-op і не очищує попереднє блокування. +- `message_sending`: `{ cancel: true }` є кінцевим; обробники з нижчим пріоритетом пропускаються. +- `message_sending`: `{ cancel: false }` є no-op і не очищує попереднє скасування. -Нативний app-server Codex проводить події нативних інструментів Codex назад у цю -поверхню хуків. Plugins можуть блокувати нативні інструменти Codex через `before_tool_call`, +Нативний app-server Codex мостить нативні події інструментів Codex назад у цю +поверхню хуків. Плагіни можуть блокувати нативні інструменти Codex через `before_tool_call`, спостерігати результати через `after_tool_call` і брати участь у схваленнях Codex -`PermissionRequest`. Bridge ще не переписує аргументи нативних інструментів Codex. -Точна межа підтримки runtime Codex описана в +`PermissionRequest`. Міст поки що не переписує аргументи нативних інструментів Codex. +Точна межа підтримки середовища виконання Codex описана в [контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). -Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). +Повну поведінку типізованих хуків дивіться в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане -- [Створення plugins](/uk/plugins/building-plugins) — створіть власний plugin -- [Plugin bundles](/uk/plugins/bundles) — сумісність bundles Codex/Claude/Cursor -- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в plugin -- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і pipeline завантаження -- [Спільнотні plugins](/uk/plugins/community) — сторонні списки +- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін +- [Бандли плагінів](/uk/plugins/bundles) — сумісність бандлів Codex/Claude/Cursor +- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту +- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в плагіні +- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження +- [Плагіни спільноти](/uk/plugins/community) — списки сторонніх розробників