diff --git a/docs/uk/channels/troubleshooting.md b/docs/uk/channels/troubleshooting.md index c39037fd3..d76ea03ab 100644 --- a/docs/uk/channels/troubleshooting.md +++ b/docs/uk/channels/troubleshooting.md @@ -1,19 +1,19 @@ --- read_when: - - Транспорт каналу показує підключення, але відповіді не працюють - - Вам потрібні перевірки, специфічні для каналу, перед глибшим зануренням у документацію провайдерів -summary: Швидке усунення несправностей на рівні каналу з типовими збоями для кожного каналу та способами виправлення -title: Усунення несправностей каналів + - Транспорт каналу показує, що підключений, але відповіді не надсилаються + - Перед поглибленим розглядом документації провайдера потрібні перевірки, специфічні для каналу +summary: Швидке усунення несправностей на рівні каналу з типовими ознаками збоїв і способами виправлення +title: Усунення несправностей каналу x-i18n: - generated_at: "2026-04-05T17:59:39Z" + generated_at: "2026-04-20T06:31:08Z" model: gpt-5.4 provider: openai - source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f + source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528 source_path: channels/troubleshooting.md workflow: 15 --- -# Усунення несправностей каналів +# Усунення несправностей каналу Використовуйте цю сторінку, коли канал підключається, але працює неправильно. @@ -29,112 +29,113 @@ openclaw doctor openclaw channels status --probe ``` -Ознаки здорового базового стану: +Ознаки справного базового стану: - `Runtime: running` -- `RPC probe: ok` -- Перевірка каналу показує, що транспорт підключено і, де це підтримується, `works` або `audit ok` +- `Connectivity probe: ok` +- `Capability: read-only`, `write-capable` або `admin-capable` +- Перевірка каналу показує, що транспорт підключений і, де це підтримується, `works` або `audit ok` ## WhatsApp -### Типові збої WhatsApp +### Ознаки збоїв у WhatsApp -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | -------------------------------------------------- | ------------------------------------------------------ | -| Підключено, але немає відповідей у приватних повідомленнях | `openclaw pairing list whatsapp` | Підтвердьте відправника або змініть політику приватних повідомлень/allowlist. | -| Групові повідомлення ігноруються | Перевірте `requireMention` + шаблони згадок у конфігурації | Згадайте бота або послабте політику згадок для цієї групи. | -| Випадкові цикли відключення/повторного входу | `openclaw channels status --probe` + журнали | Увійдіть знову й перевірте, що каталог облікових даних у належному стані. | +| Симптом | Найшвидша перевірка | Виправлення | +| ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------ | +| Підключено, але немає відповідей у DM | `openclaw pairing list whatsapp` | Підтвердьте відправника або змініть політику DM/список дозволених. | +| Повідомлення в групі ігноруються | Перевірте `requireMention` і шаблони згадок у конфігурації | Згадайте бота або послабте політику згадок для цієї групи. | +| Випадкові цикли відключення/повторного входу | `openclaw channels status --probe` + журнали | Увійдіть знову та переконайтеся, що каталог облікових даних справний. | -Повне усунення несправностей: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting) +Повне усунення несправностей: [/channels/whatsapp#troubleshooting](/uk/channels/whatsapp#troubleshooting) ## Telegram -### Типові збої Telegram +### Ознаки збоїв у Telegram -| Симптом | Найшвидша перевірка | Виправлення | -| ----------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | -| `/start`, але немає придатного сценарію відповіді | `openclaw pairing list telegram` | Підтвердьте прив’язку або змініть політику приватних повідомлень. | -| Бот онлайн, але в групі мовчить | Перевірте вимогу згадки та режим приватності бота | Вимкніть режим приватності для видимості в групі або згадайте бота. | -| Збої надсилання з мережевими помилками | Перегляньте журнали на предмет збоїв викликів API Telegram | Виправте DNS/IPv6/маршрутизацію через проксі до `api.telegram.org`. | -| `setMyCommands` відхиляється під час запуску | Перегляньте журнали на предмет `BOT_COMMANDS_TOO_MUCH` | Зменште кількість команд Telegram від plugins/Skills/користувацьких команд або вимкніть рідні меню. | -| Після оновлення allowlist блокує вас | `openclaw security audit` і allowlist у конфігурації | Запустіть `openclaw doctor --fix` або замініть `@username` на числові ID відправників. | +| Симптом | Найшвидша перевірка | Виправлення | +| ----------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | +| `/start`, але немає придатного для використання потоку відповідей | `openclaw pairing list telegram` | Підтвердьте сполучення або змініть політику DM. | +| Бот онлайн, але група мовчить | Перевірте вимогу згадки та режим приватності бота | Вимкніть режим приватності для видимості в групі або згадайте бота. | +| Помилки надсилання з мережевими помилками | Перегляньте журнали на помилки викликів Telegram API | Виправте маршрутизацію DNS/IPv6/proxy до `api.telegram.org`. | +| `setMyCommands` відхиляється під час запуску | Перегляньте журнали на `BOT_COMMANDS_TOO_MUCH` | Зменште кількість команд Telegram від Plugin/Skills/власних команд або вимкніть вбудовані меню. | +| Після оновлення список дозволених вас блокує | `openclaw security audit` і списки дозволених у конфігурації | Виконайте `openclaw doctor --fix` або замініть `@username` на числові ідентифікатори відправників. | -Повне усунення несправностей: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) +Повне усунення несправностей: [/channels/telegram#troubleshooting](/uk/channels/telegram#troubleshooting) ## Discord -### Типові збої Discord +### Ознаки збоїв у Discord -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | ---------------------------------------- | -------------------------------------------------------- | -| Бот онлайн, але немає відповідей у guild | `openclaw channels status --probe` | Дозвольте guild/канал і перевірте intent вмісту повідомлень. | -| Групові повідомлення ігноруються | Перевірте журнали на відхилення через керування згадками | Згадайте бота або встановіть `requireMention: false` для guild/каналу. | -| Немає відповідей у приватних повідомленнях | `openclaw pairing list discord` | Підтвердьте прив’язку приватних повідомлень або змініть політику приватних повідомлень. | +| Симптом | Найшвидша перевірка | Виправлення | +| ------------------------------- | -------------------------------- | -------------------------------------------------------- | +| Бот онлайн, але не відповідає в guild | `openclaw channels status --probe` | Дозвольте guild/channel і перевірте intent вмісту повідомлень. | +| Повідомлення в групі ігноруються | Перевірте журнали на відхилення через згадки | Згадайте бота або встановіть `requireMention: false` для guild/channel. | +| Немає відповідей у DM | `openclaw pairing list discord` | Підтвердьте сполучення DM або скоригуйте політику DM. | -Повне усунення несправностей: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) +Повне усунення несправностей: [/channels/discord#troubleshooting](/uk/channels/discord#troubleshooting) ## Slack -### Типові збої Slack +### Ознаки збоїв у Slack -| Симптом | Найшвидша перевірка | Виправлення | -| -------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Socket mode підключено, але немає відповідей | `openclaw channels status --probe` | Перевірте токен застосунку + токен бота і потрібні дозволи; зверніть увагу на `botTokenStatus` / `appTokenStatus = configured_unavailable` у конфігураціях на основі SecretRef. | -| Приватні повідомлення заблоковано | `openclaw pairing list slack` | Підтвердьте прив’язку або послабте політику приватних повідомлень. | -| Повідомлення в каналі ігноруються | Перевірте `groupPolicy` і allowlist каналів | Дозвольте канал або змініть політику на `open`. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Socket mode підключено, але немає відповідей | `openclaw channels status --probe` | Перевірте токен застосунку, токен бота та потрібні дозволи; зверніть увагу на `botTokenStatus` / `appTokenStatus = configured_unavailable` у налаштуваннях на основі SecretRef. | +| DM заблоковані | `openclaw pairing list slack` | Підтвердьте сполучення або послабте політику DM. | +| Повідомлення в каналі ігнорується | Перевірте `groupPolicy` і список дозволених каналів | Дозвольте канал або перемкніть політику на `open`. | -Повне усунення несправностей: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) +Повне усунення несправностей: [/channels/slack#troubleshooting](/uk/channels/slack#troubleshooting) ## iMessage і BlueBubbles -### Типові збої iMessage і BlueBubbles +### Ознаки збоїв у iMessage і BlueBubbles -| Симптом | Найшвидша перевірка | Виправлення | -| -------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- | -| Немає вхідних подій | Перевірте доступність webhook/сервера та дозволи застосунку | Виправте URL webhook або стан сервера BlueBubbles. | -| Можна надсилати, але не отримувати на macOS | Перевірте дозволи конфіденційності macOS для автоматизації Messages | Повторно надайте дозволи TCC і перезапустіть процес каналу. | -| Відправника приватних повідомлень заблоковано | `openclaw pairing list imessage` або `openclaw pairing list bluebubbles` | Підтвердьте прив’язку або оновіть allowlist. | +| Симптом | Найшвидша перевірка | Виправлення | +| -------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | +| Немає вхідних подій | Перевірте доступність Webhook/сервера та дозволи застосунку | Виправте URL Webhook або стан сервера BlueBubbles. | +| Можна надсилати, але немає прийому на macOS | Перевірте дозволи конфіденційності macOS для автоматизації Messages | Повторно надайте дозволи TCC і перезапустіть процес каналу. | +| Відправника DM заблоковано | `openclaw pairing list imessage` або `openclaw pairing list bluebubbles` | Підтвердьте сполучення або оновіть список дозволених. | Повне усунення несправностей: -- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting) -- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) +- [/channels/imessage#troubleshooting](/uk/channels/imessage#troubleshooting) +- [/channels/bluebubbles#troubleshooting](/uk/channels/bluebubbles#troubleshooting) ## Signal -### Типові збої Signal +### Ознаки збоїв у Signal -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | --------------------------------------- | ------------------------------------------------------- | -| Демон доступний, але бот мовчить | `openclaw channels status --probe` | Перевірте URL/обліковий запис демона `signal-cli` і режим отримання. | -| Приватні повідомлення заблоковано | `openclaw pairing list signal` | Підтвердьте відправника або змініть політику приватних повідомлень. | -| Відповіді в групі не запускаються | Перевірте allowlist групи та шаблони згадок | Додайте відправника/групу або послабте керування. | +| Симптом | Найшвидша перевірка | Виправлення | +| ------------------------------- | ----------------------------------- | ------------------------------------------------------- | +| Демон доступний, але бот мовчить | `openclaw channels status --probe` | Перевірте URL/обліковий запис демона `signal-cli` і режим прийому. | +| DM заблоковано | `openclaw pairing list signal` | Підтвердьте відправника або скоригуйте політику DM. | +| Відповіді в групі не спрацьовують | Перевірте список дозволених груп і шаблони згадок | Додайте відправника/групу або послабте фільтрацію. | -Повне усунення несправностей: [/channels/signal#troubleshooting](/channels/signal#troubleshooting) +Повне усунення несправностей: [/channels/signal#troubleshooting](/uk/channels/signal#troubleshooting) ## QQ Bot -### Типові збої QQ Bot +### Ознаки збоїв у QQ Bot -| Симптом | Найшвидша перевірка | Виправлення | -| ------------------------------- | ---------------------------------------- | -------------------------------------------------------------- | -| Бот відповідає "gone to Mars" | Перевірте `appId` і `clientSecret` у конфігурації | Задайте облікові дані або перезапустіть gateway. | -| Немає вхідних повідомлень | `openclaw channels status --probe` | Перевірте облікові дані на QQ Open Platform. | -| Голос не транскрибується | Перевірте конфігурацію провайдера STT | Налаштуйте `channels.qqbot.stt` або `tools.media.audio`. | -| Проактивні повідомлення не надходять | Перевірте вимоги платформи QQ до взаємодії | QQ може блокувати повідомлення, ініційовані ботом, без нещодавньої взаємодії. | +| Симптом | Найшвидша перевірка | Виправлення | +| ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------- | +| Бот відповідає "gone to Mars" | Перевірте `appId` і `clientSecret` у конфігурації | Налаштуйте облікові дані або перезапустіть Gateway. | +| Немає вхідних повідомлень | `openclaw channels status --probe` | Перевірте облікові дані на QQ Open Platform. | +| Голос не транскрибується | Перевірте конфігурацію провайдера STT | Налаштуйте `channels.qqbot.stt` або `tools.media.audio`. | +| Проактивні повідомлення не надходять | Перевірте вимоги платформи QQ щодо взаємодії | QQ може блокувати повідомлення, ініційовані ботом, без недавньої взаємодії. | -Повне усунення несправностей: [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting) +Повне усунення несправностей: [/channels/qqbot#troubleshooting](/uk/channels/qqbot#troubleshooting) ## Matrix -### Типові збої Matrix +### Ознаки збоїв у Matrix -| Симптом | Найшвидша перевірка | Виправлення | -| ----------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------- | -| Вхід виконано, але повідомлення в кімнаті ігноруються | `openclaw channels status --probe` | Перевірте `groupPolicy`, allowlist кімнат і керування згадками. | -| Приватні повідомлення не обробляються | `openclaw pairing list matrix` | Підтвердьте відправника або змініть політику приватних повідомлень. | -| Зашифровані кімнати не працюють | `openclaw matrix verify status` | Повторно підтвердьте пристрій, потім перевірте `openclaw matrix verify backup status`. | -| Відновлення резервної копії очікує/зламане | `openclaw matrix verify backup status` | Запустіть `openclaw matrix verify backup restore` або повторіть із ключем відновлення. | -| Cross-signing/bootstrap виглядає неправильно | `openclaw matrix verify bootstrap` | Виправте secret storage, cross-signing і стан резервної копії за один прохід. | +| Симптом | Найшвидша перевірка | Виправлення | +| ----------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ | +| Вхід виконано, але повідомлення кімнати ігноруються | `openclaw channels status --probe` | Перевірте `groupPolicy`, список дозволених кімнат і фільтрацію за згадками. | +| DM не обробляються | `openclaw pairing list matrix` | Підтвердьте відправника або скоригуйте політику DM. | +| Зашифровані кімнати не працюють | `openclaw matrix verify status` | Повторно верифікуйте пристрій, потім перевірте `openclaw matrix verify backup status`. | +| Відновлення резервної копії очікується/зламане | `openclaw matrix verify backup status` | Виконайте `openclaw matrix verify backup restore` або повторіть із ключем відновлення. | +| Cross-signing/bootstrap виглядає неправильно | `openclaw matrix verify bootstrap` | За один прохід виправте секретне сховище, cross-signing і стан резервної копії. | -Повне налаштування й конфігурація: [Matrix](/channels/matrix) +Повне налаштування і конфігурація: [Matrix](/uk/channels/matrix) diff --git a/docs/uk/gateway/index.md b/docs/uk/gateway/index.md index 6eb4b93df..8ac230ab8 100644 --- a/docs/uk/gateway/index.md +++ b/docs/uk/gateway/index.md @@ -1,33 +1,33 @@ --- read_when: - Запуск або налагодження процесу gateway -summary: Операційний посібник для служби Gateway, її життєвого циклу та експлуатації -title: Операційний посібник Gateway +summary: Посібник з експлуатації для служби Gateway, її життєвого циклу та операцій +title: Посібник з експлуатації Gateway x-i18n: - generated_at: "2026-04-06T15:28:26Z" + generated_at: "2026-04-20T06:31:08Z" model: gpt-5.4 provider: openai - source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd + source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8 source_path: gateway/index.md workflow: 15 --- -# Операційний посібник Gateway +# Посібник з експлуатації Gateway -Використовуйте цю сторінку для запуску Gateway у перший день і для операційної роботи надалі. +Використовуйте цю сторінку для запуску в перший день і операцій другого дня для служби Gateway. - - Діагностика за симптомами з точними послідовностями команд і сигнатурами журналів. + + Діагностика, що починається із симптому, з точними послідовностями команд і сигнатурами журналів. - - Практичний посібник із налаштування + повний довідник конфігурації. + + Посібник із налаштування, орієнтований на завдання, + повний довідник з конфігурації. Контракт SecretRef, поведінка знімків під час виконання та операції міграції/перезавантаження. - Точні правила target/path для `secrets apply` і поведінка профілю автентифікації лише з посиланнями. + Точні правила target/path для `secrets apply` і поведінка auth-profile лише з ref. @@ -38,9 +38,9 @@ x-i18n: ```bash openclaw gateway --port 18789 -# debug/trace дзеркально виводяться у stdio +# debug/trace дзеркаляться в stdio openclaw gateway --port 18789 --verbose -# примусово завершує процес, що слухає вибраний порт, а потім запускає +# примусово вбити listener на вибраному порту, потім запустити openclaw gateway --force ``` @@ -54,7 +54,7 @@ openclaw status openclaw logs --follow ``` -Базовий справний стан: `Runtime: running` і `RPC probe: ok`. +Базовий здоровий стан: `Runtime: running`, `Connectivity probe: ok` і `Capability: ...`, що відповідає вашим очікуванням. Використовуйте `openclaw gateway status --require-rpc`, коли вам потрібне підтвердження RPC з областю читання, а не лише досяжність. @@ -64,35 +64,35 @@ openclaw logs --follow openclaw channels status --probe ``` -За доступного gateway ця команда виконує живі перевірки каналів для кожного облікового запису та необов’язкові аудити. -Якщо gateway недоступний, CLI повертається до зведень каналів лише за конфігурацією -замість виводу живих probe-перевірок. +За наявності доступного gateway це виконує живі зондування каналів для кожного облікового запису та необов’язкові аудити. +Якщо gateway недоступний, CLI повертається до зведень каналів лише з конфігурації +замість виводу живого зондування. -Перезавантаження конфігурації Gateway відстежує активний шлях до файла конфігурації (визначений із типових значень профілю/стану або через `OPENCLAW_CONFIG_PATH`, якщо його задано). -Типовий режим — `gateway.reload.mode="hybrid"`. -Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно підміняє цей знімок. +Перезавантаження конфігурації Gateway відстежує активний шлях до файла конфігурації (визначений із профілю/стану за замовчуванням або через `OPENCLAW_CONFIG_PATH`, якщо його задано). +Режим за замовчуванням — `gateway.reload.mode="hybrid"`. +Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно замінює цей знімок. ## Модель виконання -- Один постійно активний процес для маршрутизації, control plane та підключень каналів. +- Один постійно запущений процес для маршрутизації, control plane і підключень каналів. - Один мультиплексований порт для: - - контролю WebSocket/RPC + - WebSocket control/RPC - HTTP API, сумісних з OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`) - - Control UI та hooks -- Типовий режим прив’язки: `loopback`. -- Автентифікація за замовчуванням обов’язкова. Налаштування зі спільним секретом використовують + - Control UI і hooks +- Режим прив’язки за замовчуванням: `loopback`. +- Автентифікація обов’язкова за замовчуванням. У конфігураціях зі спільним секретом використовуйте `gateway.auth.token` / `gateway.auth.password` (або - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а конфігурації - reverse proxy поза loopback можуть використовувати `gateway.auth.mode: "trusted-proxy"`. + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а для конфігурацій + reverse proxy не на `loopback` можна використовувати `gateway.auth.mode: "trusted-proxy"`. -## Кінцеві точки, сумісні з OpenAI +## Сумісні з OpenAI endpoint-и -Найважливіша поверхня сумісності OpenClaw тепер така: +Найцінніша поверхня сумісності OpenClaw зараз: - `GET /v1/models` - `GET /v1/models/{id}` @@ -104,31 +104,31 @@ openclaw channels status --probe - Більшість інтеграцій Open WebUI, LobeChat і LibreChat спочатку перевіряють `/v1/models`. - Багато конвеєрів RAG і пам’яті очікують `/v1/embeddings`. -- Клієнти, орієнтовані на агентів, дедалі частіше надають перевагу `/v1/responses`. +- Клієнти, орієнтовані на агентів, дедалі частіше віддають перевагу `/v1/responses`. Примітка щодо планування: -- `/v1/models` орієнтований насамперед на агентів: він повертає `openclaw`, `openclaw/default` і `openclaw/`. +- `/v1/models` орієнтований на агентів: він повертає `openclaw`, `openclaw/default` і `openclaw/`. - `openclaw/default` — це стабільний псевдонім, який завжди вказує на налаштованого агента за замовчуванням. -- Використовуйте `x-openclaw-model`, якщо вам потрібно перевизначити постачальника/модель бекенда; інакше вибраний агент і надалі керуватиме звичайним налаштуванням моделі та вбудовувань. +- Використовуйте `x-openclaw-model`, якщо вам потрібно перевизначити backend provider/model; інакше керування зберігають звичайні налаштування моделі та embeddings вибраного агента. -Усе це працює на основному порту Gateway і використовує той самий довірений периметр автентифікації оператора, що й решта HTTP API Gateway. +Усе це працює на основному порту Gateway і використовує ту саму межу автентифікації довіреного оператора, що й решта HTTP API Gateway. -### Пріоритет порту та режиму прив’язки +### Пріоритет порту і режиму прив’язки -| Параметр | Порядок визначення | -| -------- | ------------------ | -| Порт Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | -| Режим прив’язки | CLI/override → `gateway.bind` → `loopback` | +| Налаштування | Порядок визначення | +| ------------ | -------------------------------------------------------------- | +| Порт Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | +| Режим прив’язки | CLI/override → `gateway.bind` → `loopback` | ### Режими гарячого перезавантаження -| `gateway.reload.mode` | Поведінка | -| --------------------- | --------- | -| `off` | Без перезавантаження конфігурації | -| `hot` | Застосовує лише зміни, безпечні для hot-reload | -| `restart` | Перезапускає за змін, що вимагають перезапуску | -| `hybrid` (типово) | Гаряче застосовує, коли безпечно, і перезапускає, коли потрібно | +| `gateway.reload.mode` | Поведінка | +| --------------------- | ----------------------------------------- | +| `off` | Без перезавантаження конфігурації | +| `hot` | Застосовувати лише безпечні для hot зміни | +| `restart` | Перезапуск при змінах, що вимагають reload | +| `hybrid` (за замовчуванням) | Hot-застосування, коли безпечно, перезапуск, коли потрібно | ## Набір команд оператора @@ -145,14 +145,14 @@ openclaw doctor ``` `gateway status --deep` призначено для додаткового виявлення служб (LaunchDaemons/systemd system -units/schtasks), а не для глибшої RPC-перевірки стану. +units/schtasks), а не для глибшого RPC-зондування стану. ## Кілька gateway на одному хості -У більшості встановлень має працювати один gateway на машину. Один gateway може обслуговувати кількох +У більшості інсталяцій має працювати один gateway на машину. Один gateway може обслуговувати кількох агентів і канали. -Кілька gateway потрібні лише тоді, коли вам навмисно потрібна ізоляція або резервний бот. +Кілька gateway потрібні лише тоді, коли ви навмисно хочете ізоляцію або резервного бота. Корисні перевірки: @@ -164,35 +164,35 @@ openclaw gateway probe Що очікувати: - `gateway status --deep` може повідомити `Other gateway-like services detected (best effort)` - і вивести підказки з очищення, якщо навколо лишилися застарілі встановлення launchd/systemd/schtasks. -- `gateway probe` може попередити про `multiple reachable gateways`, коли відповідає - більше однієї цілі. -- Якщо це навмисно, ізолюйте порти, config/state і корені workspace для кожного gateway окремо. + і вивести підказки з очищення, якщо все ще присутні застарілі інсталяції launchd/systemd/schtasks. +- `gateway probe` може попередити про `multiple reachable gateways`, якщо відповідає більше + ніж одна ціль. +- Якщо це навмисно, ізолюйте порти, конфігурацію/стан і корені workspace для кожного gateway. -Детальне налаштування: [/gateway/multiple-gateways](/uk/gateway/multiple-gateways). +Докладне налаштування: [/gateway/multiple-gateways](/uk/gateway/multiple-gateways). ## Віддалений доступ Рекомендовано: Tailscale/VPN. -Резервний варіант: SSH-тунель. +Запасний варіант: SSH-тунель. ```bash ssh -N -L 18789:127.0.0.1:18789 user@host ``` -Потім підключайте клієнти локально до `ws://127.0.0.1:18789`. +Потім підключайте клієнтів локально до `ws://127.0.0.1:18789`. SSH-тунелі не обходять автентифікацію gateway. Для автентифікації зі спільним секретом клієнти все одно -мають надсилати `token`/`password` навіть через тунель. Для режимів з ідентифікацією -запит усе одно має задовольняти цей шлях автентифікації. +мають надсилати `token`/`password` навіть через тунель. Для режимів з ідентичністю +запит усе одно має відповідати цьому шляху автентифікації. Див.: [Remote Gateway](/uk/gateway/remote), [Authentication](/uk/gateway/authentication), [Tailscale](/uk/gateway/tailscale). ## Нагляд і життєвий цикл служби -Для надійності на рівні production використовуйте запуск під наглядом. +Для надійності, подібної до production, використовуйте керовані запуски. @@ -204,7 +204,7 @@ openclaw gateway restart openclaw gateway stop ``` -Мітки LaunchAgent: `ai.openclaw.gateway` (типово) або `ai.openclaw.` (іменований профіль). `openclaw doctor` перевіряє і виправляє дрейф конфігурації служби. +Мітки LaunchAgent: `ai.openclaw.gateway` (за замовчуванням) або `ai.openclaw.` (іменований профіль). `openclaw doctor` перевіряє та виправляє дрейф конфігурації служби. @@ -216,13 +216,13 @@ systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` -Щоб служба лишалася активною після виходу з сеансу, увімкніть lingering: +Для збереження після виходу із системи ввімкніть lingering: ```bash sudo loginctl enable-linger ``` -Приклад user-unit вручну, коли потрібен власний шлях встановлення: +Приклад ручного user-unit, коли потрібен власний шлях інсталяції: ```ini [Unit] @@ -254,25 +254,25 @@ openclaw gateway restart openclaw gateway stop ``` -Керований нативний автозапуск у Windows використовує Scheduled Task з назвою `OpenClaw Gateway` +Керований автозапуск у Windows використовує Scheduled Task з назвою `OpenClaw Gateway` (або `OpenClaw Gateway ()` для іменованих профілів). Якщо створення Scheduled Task -заборонено, OpenClaw переходить до launcher у Startup-folder для поточного користувача, +заборонене, OpenClaw повертається до launcher у Startup-folder для поточного користувача, який вказує на `gateway.cmd` у каталозі стану. -Використовуйте системний unit для багатокористувацьких/постійно активних хостів. +Використовуйте system unit для багатокористувацьких/постійно активних хостів. ```bash sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -Використовуйте той самий вміст служби, що й для user unit, але встановіть його в -`/etc/systemd/system/openclaw-gateway[-].service` і скоригуйте -`ExecStart=`, якщо ваш бінарний файл `openclaw` розташований в іншому місці. +Використовуйте той самий вміст служби, що й для user unit, але встановлюйте його в +`/etc/systemd/system/openclaw-gateway[-].service` і за потреби змініть +`ExecStart=`, якщо ваш бінарний файл `openclaw` розміщений в іншому місці. @@ -280,7 +280,7 @@ sudo systemctl enable --now openclaw-gateway[-].service ## Кілька gateway на одному хості У більшості конфігурацій має працювати **один** Gateway. -Використовуйте кілька лише для суворої ізоляції/резервування (наприклад, профіль відновлення). +Використовуйте кілька лише для суворої ізоляції/надлишковості (наприклад, резервний профіль). Контрольний список для кожного екземпляра: @@ -298,7 +298,7 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b opencla Див.: [Multiple gateways](/uk/gateway/multiple-gateways). -### Швидкий шлях для dev-профілю +### Швидкий шлях для dev profile ```bash openclaw --dev setup @@ -308,32 +308,32 @@ openclaw --dev status Типові значення включають ізольовані state/config і базовий порт gateway `19001`. -## Коротка довідка з протоколу (погляд оператора) +## Короткий довідник з протоколу (погляд оператора) -- Перший кадр клієнта має бути `connect`. +- Першим кадром клієнта має бути `connect`. - Gateway повертає знімок `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy). - `hello-ok.features.methods` / `events` — це консервативний список виявлення, а не - згенерований дамп усіх доступних маршрутів helper. + згенерований дамп кожного доступного допоміжного маршруту. - Запити: `req(method, params)` → `res(ok/payload|error)`. -- До поширених подій належать `connect.challenge`, `agent`, `chat`, +- Поширені події включають `connect.challenge`, `agent`, `chat`, `session.message`, `session.tool`, `sessions.changed`, `presence`, `tick`, `health`, `heartbeat`, події життєвого циклу pairing/approval і `shutdown`. -Запуски агентів складаються з двох етапів: +Запуски агентів мають дві стадії: -1. Негайне підтвердження прийняття (`status:"accepted"`) -2. Остаточна відповідь завершення (`status:"ok"|"error"`), із потоковими подіями `agent` між ними. +1. Негайне підтвердження accepted (`status:"accepted"`) +2. Фінальна відповідь про завершення (`status:"ok"|"error"`), з потоковими подіями `agent` між ними. -Повну документацію з протоколу див.: [Gateway Protocol](/uk/gateway/protocol). +Повна документація з протоколу: [Gateway Protocol](/uk/gateway/protocol). ## Операційні перевірки -### Перевірка доступності +### Живучість - Відкрийте WS і надішліть `connect`. - Очікуйте відповідь `hello-ok` зі знімком. -### Перевірка готовності +### Готовність ```bash openclaw gateway status @@ -343,28 +343,28 @@ openclaw health ### Відновлення після пропусків -Події не відтворюються повторно. За пропусків у послідовності оновіть стан (`health`, `system-presence`), перш ніж продовжувати. +Події не відтворюються повторно. У разі пропусків послідовності оновіть стан (`health`, `system-presence`), перш ніж продовжувати. ## Типові сигнатури збоїв -| Сигнатура | Імовірна проблема | -| --------- | ----------------- | -| `refusing to bind gateway ... without auth` | Прив’язка не до loopback без дійсного шляху автентифікації gateway | -| `another gateway instance is already listening` / `EADDRINUSE` | Конфлікт порту | -| `Gateway start blocked: set gateway.mode=local` | У конфігурації встановлено remote mode або в пошкодженій конфігурації відсутній штамп local-mode | -| `unauthorized` during connect | Невідповідність автентифікації між клієнтом і gateway | +| Сигнатура | Ймовірна проблема | +| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `refusing to bind gateway ... without auth` | Прив’язка не до loopback без дійсного шляху автентифікації gateway | +| `another gateway instance is already listening` / `EADDRINUSE` | Конфлікт порту | +| `Gateway start blocked: set gateway.mode=local` | У конфігурації встановлено remote mode або в пошкодженій конфігурації відсутній штамп local-mode | +| `unauthorized` during connect | Невідповідність автентифікації між клієнтом і gateway | -Щоб отримати повні послідовності діагностики, скористайтеся [Gateway Troubleshooting](/uk/gateway/troubleshooting). +Для повних послідовностей діагностики використовуйте [Gateway Troubleshooting](/uk/gateway/troubleshooting). ## Гарантії безпеки -- Клієнти протоколу Gateway швидко завершуються з помилкою, коли Gateway недоступний (без неявного fallback на прямий канал). -- Некоректні перші кадри або кадри не типу `connect` відхиляються, і з’єднання закривається. +- Клієнти протоколу Gateway швидко завершуються з помилкою, коли Gateway недоступний (без неявного fallback на direct-channel). +- Неприпустимі перші кадри або кадри не `connect` відхиляються, а з’єднання закривається. - Коректне завершення роботи надсилає подію `shutdown` перед закриттям сокета. --- -Пов’язані сторінки: +Пов’язане: - [Troubleshooting](/uk/gateway/troubleshooting) - [Background Process](/uk/gateway/background-process) diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 970e86914..d3ec72800 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,26 +1,26 @@ --- read_when: - - Центр усунення неполадок направив вас сюди для глибшої діагностики - - Вам потрібні стабільні розділи посібника з діагностики за симптомами з точними командами -summary: Детальний посібник з усунення неполадок для gateway, каналів, автоматизації, вузлів і браузера -title: Усунення неполадок + - Центр усунення несправностей направив вас сюди для глибшої діагностики + - Вам потрібні стабільні розділи посібника на основі симптомів із точними командами +summary: Детальний посібник з усунення несправностей для Gateway, каналів, автоматизації, Node і браузера +title: Усунення несправностей x-i18n: - generated_at: "2026-04-10T20:41:23Z" + generated_at: "2026-04-20T06:31:09Z" model: gpt-5.4 provider: openai - source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5 + source_hash: 853275aaf4ebddb9d2fd358df2e9fdc893dafdc7960d69c4f145ce615d5cbc1e source_path: gateway/troubleshooting.md workflow: 15 --- -# Усунення неполадок gateway +# Усунення несправностей Gateway -Ця сторінка є детальним посібником. -Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік первинної діагностики. +Ця сторінка — детальний посібник. +Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете швидкий сценарій первинної діагностики. -## Послідовність команд +## Командна послідовність -Спочатку виконайте ці команди в такому порядку: +Спочатку виконайте ці команди саме в такому порядку: ```bash openclaw status @@ -30,16 +30,16 @@ openclaw doctor openclaw channels status --probe ``` -Очікувані ознаки справного стану: +Очікувані ознаки нормального стану: -- `openclaw gateway status` показує `Runtime: running` і `RPC probe: ok`. -- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/служб. -- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису та, - де це підтримується, результати probe/audit, як-от `works` або `audit ok`. +- `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`. +- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісів. +- `openclaw channels status --probe` показує живий статус транспорту для кожного облікового запису і, + де це підтримується, результати probe/audit на кшталт `works` або `audit ok`. ## Anthropic 429: для довгого контексту потрібне додаткове використання -Використовуйте це, коли логи/помилки містять: +Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash @@ -52,13 +52,13 @@ openclaw config get agents.defaults.models - Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. - Поточні облікові дані Anthropic не мають права на використання довгого контексту. -- Запити збійно завершуються лише для довгих сесій/запусків моделі, яким потрібен beta-шлях 1M. +- Запити падають лише в довгих сесіях/запусках моделі, яким потрібен шлях 1M beta. Варіанти виправлення: 1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. 2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на ключ Anthropic API. -3. Налаштуйте резервні моделі, щоб виконання продовжувалося, коли запити Anthropic з довгим контекстом відхиляються. +3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли запити Anthropic із довгим контекстом відхиляються. Пов’язане: @@ -66,13 +66,13 @@ openclaw config get agents.defaults.models - [/reference/token-use](/uk/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/uk/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-compatible backend проходить прямі probe, але збоять запуски агента +## Локальний OpenAI-сумісний бекенд проходить прямі probe, але запуски агента не працюють Використовуйте це, коли: - `curl ... /v1/models` працює - малі прямі виклики `/v1/chat/completions` працюють -- запуски моделі OpenClaw збоять лише під час звичайних ходів агента +- запуски моделей OpenClaw падають лише на звичайних ходах агента ```bash curl http://127.0.0.1:1234/v1/models @@ -85,34 +85,34 @@ openclaw logs --follow Зверніть увагу на таке: -- прямі малі виклики успішні, але запуски OpenClaw збоять лише на більших prompt -- помилки backend про те, що `messages[].content` очікує рядок -- збої backend, які з’являються лише при більшій кількості токенів у prompt або в повних - prompt середовища виконання агента +- прямі малі виклики успішні, але запуски OpenClaw падають лише на більших prompt +- помилки бекенда про те, що `messages[].content` очікує рядок +- збої бекенда, які виникають лише за більшої кількості prompt-token або з повними + prompt середовища агента Поширені ознаки: -- `messages[...].content: invalid type: sequence, expected a string` → backend - відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть +- `messages[...].content: invalid type: sequence, expected a string` → бекенд + відхиляє структуровані частини content у Chat Completions. Виправлення: встановіть `models.providers..models[].compat.requiresStringContent: true`. -- прямі малі запити успішні, але ходи агента OpenClaw збоять через збої backend/моделі - (наприклад, Gemma у деяких збірках `inferrs`) → транспорт OpenClaw - імовірно вже налаштований правильно; проблема в тому, що backend не справляється з більшою формою - prompt середовища виконання агента. -- після вимкнення tools збоїв стає менше, але вони не зникають → схеми tools були - частиною навантаження, але решта проблеми все ще пов’язана з upstream місткістю моделі/сервера - або помилкою backend. +- прямі малі запити успішні, але запуски агента OpenClaw падають через збої бекенда/моделі + (наприклад Gemma у деяких збірках `inferrs`) → транспорт OpenClaw, + найімовірніше, уже налаштований правильно; бекенд падає через форму більших + prompt середовища агента. +- збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів + були частиною навантаження, але решта проблеми все одно пов’язана з обмеженням + моделі/сервера вище за рівнем або з багом бекенда. Варіанти виправлення: -1. Встановіть `compat.requiresStringContent: true` для backend Chat Completions, які підтримують лише рядковий вміст. -2. Встановіть `compat.supportsTools: false` для моделей/backend, які не можуть - надійно обробляти поверхню схем tools OpenClaw. -3. За можливості зменште навантаження prompt: менший bootstrap workspace, коротша - історія сесії, легша локальна модель або backend із кращою підтримкою довгого контексту. -4. Якщо прямі малі запити й далі проходять, а ходи агента OpenClaw усе ще збоять - всередині backend, розглядайте це як обмеження upstream сервера/моделі й створіть - там repro з формою payload, яка приймається. +1. Встановіть `compat.requiresStringContent: true` для бекендів Chat Completions, які підтримують лише рядки. +2. Встановіть `compat.supportsTools: false` для моделей/бекендів, які не можуть + надійно обробляти поверхню схем інструментів OpenClaw. +3. За можливості зменште навантаження prompt: менший bootstrap робочого простору, коротша + історія сесії, легша локальна модель або бекенд із кращою підтримкою довгого контексту. +4. Якщо малі прямі запити й далі проходять, а ходи агента OpenClaw все ще спричиняють збій + усередині бекенда, розглядайте це як обмеження сервера/моделі вище за рівнем і створіть + там repro із прийнятою формою payload. Пов’язане: @@ -122,7 +122,7 @@ openclaw logs --follow ## Немає відповідей -Якщо канали працюють, але ніхто не відповідає, перевірте маршрутизацію та політики перед тим, як щось перепідключати. +Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію та політики, перш ніж щось перепідключати. ```bash openclaw status @@ -134,15 +134,15 @@ openclaw logs --follow Зверніть увагу на таке: -- Pairing очікує на розгляд для відправників у DM. -- Обмеження згадок у групах (`requireMention`, `mentionPatterns`). +- Pairing у стані очікування для відправників у DM. +- Обмеження згадками в групах (`requireMention`, `mentionPatterns`). - Невідповідності allowlist каналу/групи. Поширені ознаки: -- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадки. -- `pairing request` → відправнику потрібне схвалення. -- `blocked` / `allowlist` → відправника/канал відфільтровано політикою. +- `drop guild message (mention required` → повідомлення в групі ігнорується, доки не буде згадки. +- `pairing request` → відправник потребує схвалення. +- `blocked` / `allowlist` → відправника/канал було відфільтровано політикою. Пов’язане: @@ -152,7 +152,7 @@ openclaw logs --follow ## Підключення dashboard/control UI -Коли dashboard/control UI не може підключитися, перевірте URL, режим auth і припущення про безпечний контекст. +Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо безпечного контексту. ```bash openclaw gateway status @@ -165,47 +165,47 @@ openclaw gateway status --json Зверніть увагу на таке: - Правильний URL probe і URL dashboard. -- Невідповідність режиму auth/токена між клієнтом і gateway. +- Невідповідність режиму автентифікації/токена між клієнтом і Gateway. - Використання HTTP там, де потрібна ідентичність пристрою. Поширені ознаки: -- `device identity required` → небезпечний контекст або відсутня auth пристрою. +- `device identity required` → небезпечний контекст або відсутня автентифікація пристрою. - `origin not allowed` → `Origin` браузера відсутній у `gateway.controlUi.allowedOrigins` - (або ви підключаєтеся з browser origin не на loopback без явного + (або ви підключаєтеся з браузерного origin не на loopback без явного allowlist). - `device nonce required` / `device nonce mismatch` → клієнт не завершує - flow auth пристрою на основі challenge (`connect.challenge` + `device.nonce`). + challenge-базований потік автентифікації пристрою (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → клієнт підписав неправильний payload (або використав застарілу часову мітку) для поточного handshake. - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. -- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із paired - токеном пристрою. Виклики з явними `deviceToken` / явними `scopes` зберігають - запитаний ними набір scope. -- Поза цим шляхом повторної спроби пріоритет auth для connect такий: - спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, +- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом + зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають + свій запитаний набір scope. +- Поза цим шляхом повторної спроби пріоритет автентифікації під час підключення такий: спочатку явний спільний + token/password, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. -- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого - `{scope, ip}` серіалізуються до того, як limiter зафіксує збій. Тому дві хибні +- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого + `{scope, ip}` серіалізуються до того, як лімітатор зафіксує невдачу. Тому дві невдалі одночасні повторні спроби від того самого клієнта можуть призвести до `retry later` - для другої спроби замість двох звичайних невідповідностей. + у другій спробі замість двох звичайних невідповідностей. - `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. -- повторюване `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та за потреби повторно схваліть/перегенеруйте токен пристрою. -- `gateway connect failed:` → неправильний host/port/url призначення. +- повторні `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та за потреби повторно схваліть/перевипустіть токен пристрою. +- `gateway connect failed:` → неправильна ціль host/port/url. -### Швидка таблиця кодів деталей auth +### Коротка карта кодів деталей автентифікації -Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` з невдалого response `connect`, щоб вибрати наступну дію: | Код деталей | Значення | Рекомендована дія | | ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий shared token. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, а потім вставте його в налаштуваннях Control UI. | -| `AUTH_TOKEN_MISMATCH` | Shared token не збігся з токеном auth gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явними `deviceToken` / `scopes` зберігають запитані scope. Якщо й далі не вдається, виконайте [контрольний список відновлення після розсинхронізації токена](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Перегенеруйте/повторно схваліть токен пристрою через [CLI devices](/cli/devices), а потім перепідключіться. | -| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve `. | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний token. | Вставте/встановіть token у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | +| `AUTH_TOKEN_MISMATCH` | Спільний token не збігся з токеном автентифікації gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явним `deviceToken` / `scopes` зберігають запитаний набір scope. Якщо все одно не працює, виконайте [контрольний список відновлення після drift токенів](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Перевипустіть/повторно схваліть токен пристрою через [CLI devices](/cli/devices), потім перепідключіться. | +| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve `. | -Перевірка міграції auth пристрою v2: +Перевірка міграції device auth v2: ```bash openclaw --version @@ -213,53 +213,53 @@ openclaw doctor openclaw gateway status ``` -Якщо логи показують помилки nonce/signature, оновіть клієнт, що підключається, і перевірте, що він: +Якщо журнали показують помилки nonce/signature, оновіть клієнт, що підключається, і перевірте, що він: 1. чекає на `connect.challenge` 2. підписує payload, прив’язаний до challenge -3. надсилає `connect.params.device.nonce` з тим самим nonce challenge +3. надсилає `connect.params.device.nonce` з тим самим challenge nonce -Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано заборонено: +Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхиляється: -- сесії з токеном paired-device можуть керувати лише **власним** пристроєм, якщо +- сесії з paired-device token можуть керувати лише **своїм власним** пристроєм, якщо виклик також не має `operator.admin` - `openclaw devices rotate --scope ...` може запитувати лише ті operator scope, - які вже має сесія виклику + які сесія виклику вже має Пов’язане: - [/web/control-ui](/web/control-ui) -- [/gateway/configuration](/uk/gateway/configuration) (режими auth gateway) +- [/gateway/configuration](/uk/gateway/configuration) (режими автентифікації gateway) - [/gateway/trusted-proxy-auth](/uk/gateway/trusted-proxy-auth) - [/gateway/remote](/uk/gateway/remote) - [/cli/devices](/cli/devices) -## Служба gateway не працює +## Сервіс Gateway не запущений -Використовуйте це, коли службу встановлено, але процес не залишається активним. +Використовуйте це, коли сервіс установлено, але процес не залишається запущеним. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # також сканує служби на рівні системи +openclaw gateway status --deep # also scan system-level services ``` Зверніть увагу на таке: -- `Runtime: stopped` з підказками щодо виходу. -- Невідповідність конфігурації служби (`Config (cli)` vs `Config (service)`). -- Конфлікти портів/слухачів. +- `Runtime: stopped` із підказками щодо завершення. +- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`). +- Конфлікти порту/слухача. - Додаткові встановлення launchd/systemd/schtasks при використанні `--deep`. -- Підказки для очищення `Other gateway-like services detected (best effort)`. +- Підказки очищення `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`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, стандартний шлях до конфігурації — `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → прив’язка не до loopback без коректного шляху auth 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 (token/password або trusted-proxy, де це налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. -- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні модулі launchd/systemd/schtasks. У більшості конфігурацій має бути один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks units. У більшості сценаріїв варто тримати один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). Пов’язане: @@ -267,7 +267,7 @@ openclaw gateway status --deep # також сканує служби на р - [/gateway/configuration](/uk/gateway/configuration) - [/gateway/doctor](/uk/gateway/doctor) -## Попередження gateway probe +## Попередження probe Gateway Використовуйте це, коли `openclaw gateway probe` до чогось дістається, але все одно виводить блок попереджень. @@ -280,14 +280,15 @@ openclaw gateway probe --ssh user@gateway-host Зверніть увагу на таке: - `warnings[].code` і `primaryTargetId` у JSON-виводі. -- Чи пов’язане попередження з резервним переходом через SSH, кількома gateway, відсутніми scope або нерозв’язаними auth refs. +- Чи пов’язане попередження з резервним переходом через SSH, кількома gateway, відсутніми scope або нерозв’язаними auth ref. Поширені ознаки: - `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-цілі. -- `multiple reachable gateways detected` → відповіла більше ніж одна ціль. Зазвичай це означає навмисну конфігурацію з кількома gateway або застарілі/дубльовані listeners. -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але детальний RPC обмежений scope; виконайте pairing ідентичності пристрою або використайте облікові дані з `operator.read`. -- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth-матеріал був недоступний у цьому шляху команди для цілі, що не пройшла перевірку. +- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисну конфігурацію з кількома gateway або застарілі/дубльовані listener. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але деталізований RPC обмежений scope; спарте ідентичність пристрою або використайте облікові дані з `operator.read`. +- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → gateway відповів, але цьому клієнту все ще потрібне pairing/схвалення перед звичайним доступом operator. +- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth-матеріал був недоступний у цьому шляху команди для цілі, що не вдалася. Пов’язане: @@ -297,7 +298,7 @@ openclaw gateway probe --ssh user@gateway-host ## Канал підключено, але повідомлення не проходять -Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиках, дозволах і правилах доставки, специфічних для каналу. +Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. ```bash openclaw channels status --probe @@ -315,7 +316,7 @@ openclaw config get channels Поширені ознаки: -- `mention required` → повідомлення ігнорується через політику згадок у групі. +- `mention required` → повідомлення ігнорується політикою згадок у групі. - `pairing` / сліди очікування схвалення → відправника не схвалено. - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з auth/дозволами каналу. @@ -326,9 +327,9 @@ openclaw config get channels - [/channels/telegram](/uk/channels/telegram) - [/channels/discord](/uk/channels/discord) -## Доставка cron і heartbeat +## Доставка Cron і Heartbeat -Якщо cron або heartbeat не запустився чи не доставився, спочатку перевірте стан scheduler, а вже потім ціль доставки. +Якщо Cron або Heartbeat не запустився чи не доставився, спочатку перевірте стан планувальника, а потім ціль доставки. ```bash openclaw cron status @@ -340,19 +341,19 @@ openclaw logs --follow Зверніть увагу на таке: -- Cron увімкнений і присутній час наступного пробудження. -- Стан історії запусків job (`ok`, `skipped`, `error`). -- Причини пропуску heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). +- Cron увімкнено і наявний наступний запуск. +- Статус історії запусків завдання (`ok`, `skipped`, `error`). +- Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). Поширені ознаки: -- `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. -- `cron: timer tick failed` → збій tick scheduler; перевірте помилки файлів/логів/runtime. -- `heartbeat skipped` з `reason=quiet-hours` → поза межами вікна активних годин. -- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. -- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але на цьому tick жодне із завдань не підлягає виконанню. -- `heartbeat: unknown accountId` → недійсний account id для цілі доставки heartbeat. -- `heartbeat skipped` з `reason=dm-blocked` → ціль heartbeat була визначена як призначення у стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`. +- `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. +- `cron: timer tick failed` → помилка тіку планувальника; перевірте помилки файлів/журналів/середовища виконання. +- `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` → недійсний id облікового запису для цілі доставки Heartbeat. +- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat було зіставлено з призначенням у стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) встановлено в `block`. Пов’язане: @@ -360,9 +361,9 @@ openclaw logs --follow - [/automation/cron-jobs](/uk/automation/cron-jobs) - [/gateway/heartbeat](/uk/gateway/heartbeat) -## Збій paired tool вузла +## Збій інструмента спареного Node -Якщо вузол paired, але tools не працюють, ізолюйте стан foreground, дозволи та схвалення. +Якщо Node спарений, але інструменти не працюють, ізолюйте стан foreground, дозволи та схвалення. ```bash openclaw nodes status @@ -374,15 +375,15 @@ openclaw status Зверніть увагу на таке: -- Вузол online з очікуваними capability. -- Надані дозволи ОС для camera/mic/location/screen. -- Стан exec approvals і allowlist. +- Node онлайн з очікуваними можливостями. +- Надані дозволи ОС на камеру/мікрофон/геолокацію/екран. +- Стан схвалень exec і allowlist. Поширені ознаки: -- `NODE_BACKGROUND_UNAVAILABLE` → застосунок вузла має бути у foreground. +- `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути на передньому плані. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС. -- `SYSTEM_RUN_DENIED: approval required` → схвалення exec очікує. +- `SYSTEM_RUN_DENIED: approval required` → очікує схвалення exec. - `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано через allowlist. Пов’язане: @@ -393,7 +394,7 @@ openclaw status ## Збій browser tool -Використовуйте це, коли дії browser tool завершуються з помилкою, хоча сам gateway справний. +Використовуйте це, коли дії browser tool не працюють, хоча сам Gateway справний. ```bash openclaw browser status @@ -405,30 +406,30 @@ openclaw doctor Зверніть увагу на таке: -- Чи задано `plugins.allow` і чи включає воно `browser`. +- Чи встановлено `plugins.allow` і чи містить він `browser`. - Коректний шлях до виконуваного файла браузера. - Досяжність профілю CDP. -- Наявність локального Chrome для профілів `existing-session` / `user`. +- Доступність локального Chrome для профілів `existing-session` / `user`. Поширені ознаки: -- `unknown command "browser"` або `unknown command 'browser'` → bundled browser plugin виключено через `plugins.allow`. -- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому plugin ніколи не завантажувався. -- `Failed to start Chrome CDP on port` → процес браузера не вдалося запустити. +- `unknown command "browser"` або `unknown command 'browser'` → вбудований browser Plugin виключено через `plugins.allow`. +- browser tool відсутній / недоступний, хоча `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 має некоректний або неприпустимий порт. -- `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 endpoint відповів, але CDP WebSocket усе одно не вдалося відкрити. -- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні gateway відсутній повний пакет Playwright; знімки ARIA і базові знімки сторінки все ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-селекторами та експорт PDF залишаються недоступними. -- `fullPage is not supported for element screenshots` → запит screenshot поєднав `--full-page` з `--ref` або `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики screenshot для Chrome MCP / `existing-session` мають використовувати захоплення сторінки або snapshot `--ref`, а не CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooks завантаження файлів у Chrome MCP потребують snapshot refs, а не CSS-селекторів. -- `existing-session file uploads currently support one file at a time.` → для профілів Chrome MCP надсилайте одне завантаження за виклик. -- `existing-session dialog handling does not support timeoutMs.` → hooks діалогів у профілях Chrome MCP не підтримують перевизначення timeout. -- `response body is not supported for existing-session profiles yet.` → `responsebody` поки що потребує керованого браузера або сирого профілю CDP. -- застарілі перевизначення viewport / dark-mode / locale / offline для профілів лише для приєднання або віддалених CDP-профілів → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування та скинути стан емуляції Playwright/CDP без перезапуску всього gateway. +- `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, таку як `file:` або `ftp:`. +- `browser.cdpUrl has invalid port` → налаштований URL CDP має неправильний або недопустимий порт. +- `No Chrome tabs found for profile="user"` → профіль підключення Chrome MCP не має відкритих локальних вкладок Chrome. +- `Remote CDP for profile "" is not reachable` → налаштований віддалений endpoint CDP недосяжний із хоста Gateway. +- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише-підключення не має досяжної цілі, або HTTP endpoint відповів, але CDP WebSocket все одно не вдалося відкрити. +- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні gateway відсутній повний пакет Playwright; ARIA snapshots і базові знімки сторінок ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-selector і експорт PDF залишаються недоступними. +- `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` зі snapshot, а не CSS `--element`. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів у Chrome MCP потребують snapshot ref, а не CSS selectors. +- `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP. +- `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення timeout. +- `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або сирого профілю CDP. +- застарілі перевизначення viewport / dark-mode / locale / offline у профілях лише-підключення або віддаленого CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування і звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. Пов’язане: @@ -437,7 +438,7 @@ openclaw doctor ## Якщо ви оновилися і щось раптово зламалося -Більшість проблем після оновлення — це дрейф конфігурації або суворіші стандартні значення, які тепер застосовуються. +Більшість збоїв після оновлення — це drift конфігурації або жорсткіші типові значення, які тепер застосовуються. ### 1) Змінилася поведінка auth і перевизначення URL @@ -450,15 +451,15 @@ openclaw config get gateway.auth.mode Що перевірити: -- Якщо `gateway.mode=remote`, виклики CLI можуть спрямовуватися на remote, тоді як ваша локальна служба працює нормально. -- Явні виклики `--url` не переходять до збережених облікових даних. +- Якщо `gateway.mode=remote`, виклики CLI можуть бути націлені на віддалений вузол, тоді як ваш локальний сервіс працює нормально. +- Явні виклики `--url` не використовують резервний перехід до збережених облікових даних. Поширені ознаки: -- `gateway connect failed:` → неправильна URL-ціль. -- `unauthorized` → endpoint досяжний, але auth неправильна. +- `gateway connect failed:` → неправильна ціль URL. +- `unauthorized` → endpoint досяжний, але auth неправильний. -### 2) Guardrails для bind і auth стали суворішими +### 2) Обмеження bind і auth стали суворішими ```bash openclaw config get gateway.bind @@ -470,13 +471,13 @@ openclaw logs --follow Що перевірити: -- Bind не до loopback (`lan`, `tailnet`, `custom`) потребують коректного шляху auth gateway: shared token/password auth або правильно налаштованого розгортання `trusted-proxy` не на loopback. +- Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху auth gateway: спільна автентифікація token/password або правильно налаштоване розгортання `trusted-proxy` не на loopback. - Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. Поширені ознаки: -- `refusing to bind gateway ... without auth` → bind не до loopback без коректного шляху auth gateway. -- `RPC probe: failed` коли runtime працює → gateway живий, але недоступний із поточними auth/url. +- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху auth gateway. +- `Connectivity probe: failed` коли середовище виконання працює → gateway живий, але недоступний із поточними auth/url. ### 3) Змінився стан pairing та ідентичності пристрою @@ -489,15 +490,15 @@ openclaw doctor Що перевірити: -- Pending-схвалення пристроїв для dashboard/nodes. -- Pending-схвалення pairing для DM після змін політики або ідентичності. +- Очікують схвалення пристрої для dashboard/nodes. +- Очікують схвалення DM pairing після змін політики або ідентичності. Поширені ознаки: -- `device identity required` → auth пристрою не виконано. +- `device identity required` → не виконано device auth. - `pairing required` → відправника/пристрій потрібно схвалити. -Якщо після перевірок конфігурація служби й runtime усе ще не збігаються, перевстановіть метадані служби з того самого каталогу профілю/стану: +Якщо конфігурація сервісу та середовище виконання все ще не збігаються після перевірок, перевстановіть метадані сервісу з того самого каталогу профілю/стану: ```bash openclaw gateway install --force diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index e9d2742e8..e5b251f76 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання. - - Сортування проблем, про які повідомляють користувачі, перед глибшим налагодженням + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час роботи системи + - Первинне опрацювання проблем, про які повідомили користувачі, перед глибшим налагодженням summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw -title: Поширені запитання +title: Часті запитання x-i18n: - generated_at: "2026-04-20T04:35:11Z" + generated_at: "2026-04-20T06:31:07Z" model: gpt-5.4 provider: openai - source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 + source_hash: ae8efda399e34f59f22f6ea8ce218eaf7b872e4117d8596ec19c09891d70813b source_path: help/faq.md workflow: 15 --- -# Поширені запитання +# Часті запитання -Швидкі відповіді плюс глибше усунення проблем для реальних середовищ (локальна розробка, VPS, multi-agent, OAuth/API keys, резервне перемикання моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Для повного довідника з конфігурації див. [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді та глибше усунення несправностей для реальних середовищ (локальна розробка, VPS, multi-agent, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час роботи див. [Усунення несправностей](/uk/gateway/troubleshooting). Для повного довідника з конфігурації див. [Конфігурація](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося @@ -25,7 +25,7 @@ x-i18n: openclaw status ``` - Швидке локальне зведення: ОС + оновлення, доступність gateway/service, agents/sessions, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). + Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, agents/sessions, конфігурація провайдера + проблеми під час роботи (коли gateway доступний). 2. **Звіт, який можна вставити й поділитися ним (безпечний для поширення)** @@ -33,7 +33,7 @@ x-i18n: openclaw status --all ``` - Діагностика в режимі лише читання з хвостом логів (токени замасковано). + Діагностика лише для читання з хвостом логів (токени замасковано). 3. **Стан демона + порту** @@ -41,7 +41,7 @@ x-i18n: openclaw gateway status ``` - Показує середовище виконання supervisor порівняно з доступністю RPC, цільову URL-адресу probe та те, яку конфігурацію служба, ймовірно, використовувала. + Показує доступність supervisor runtime порівняно з RPC, цільову URL-адресу probe та те, яку конфігурацію сервіс, імовірно, використовував. 4. **Глибокі probe-перевірки** @@ -49,22 +49,22 @@ x-i18n: openclaw status --deep ``` - Виконує живу probe-перевірку стану gateway, включно з probe-перевірками каналів, коли це підтримується + Виконує живу probe-перевірку стану gateway, включно з probe-перевірками каналів, якщо вони підтримуються (потрібен доступний 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 (виправлення)** @@ -81,39 +81,39 @@ x-i18n: openclaw health --verbose # показує цільову URL-адресу + шлях до конфігурації у разі помилок ``` - Запитує в запущеного gateway повний знімок стану (лише WS). Див. [Стан](/uk/gateway/health). + Запитує у запущеного gateway повний знімок стану (лише WS). Див. [Стан](/uk/gateway/health). ## Швидкий старт і початкове налаштування - - Використайте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж питати - у Discord, тому що більшість випадків "я застряг" — це **локальні проблеми з конфігурацією або середовищем**, + + Використайте локального AI-агента, який може **бачити вашу машину**. Це значно ефективніше, ніж запитувати + в Discord, тому що більшість випадків "я застряг" — це **локальні проблеми конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, запускати команди, перевіряти логи й допомагати виправити - налаштування на рівні машини (PATH, служби, дозволи, auth-файли). Надайте їм **повний checkout вихідного коду** через - зламуваний (git) спосіб встановлення: + Ці інструменти можуть читати репозиторій, запускати команди, перевіряти логи та допомагати виправляти + налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Надайте їм **повну копію вихідного коду** + через змінюване встановлення (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **із git checkout**, тож агент може читати код + документацію та + Це встановлює OpenClaw **з git checkout**, тож агент може читати код + документацію та аналізувати точну версію, яку ви використовуєте. Ви завжди можете повернутися до стабільної версії пізніше, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть агента **спланувати та супроводжувати** виправлення (покроково), а потім виконати лише - потрібні команди. Так зміни залишаться невеликими, і їх буде простіше перевірити. + Порада: попросіть агента **спланувати та проконтролювати** виправлення (покроково), а потім виконати лише + необхідні команди. Це робить зміни меншими й простішими для аудиту. - Якщо ви виявили справжню помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: + Якщо ви виявили реальну помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Почніть із цих команд (поділіться виводом, коли просите про допомогу): + Почніть із цих команд (діліться виводом, коли просите про допомогу): ```bash openclaw status @@ -123,30 +123,30 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану gateway/agent + базової конфігурації. - - `openclaw models status`: перевіряє auth провайдера + доступність моделі. - - `openclaw doctor`: перевіряє та виправляє типові проблеми з конфігурацією/станом. + - `openclaw status`: швидкий знімок стану gateway/agent + базова конфігурація. + - `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей. + - `openclaw doctor`: перевіряє та виправляє поширені проблеми конфігурації/стану. Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд,-якщо-щось-зламалося). + Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). - Поширені причини пропуску Heartbeat: + Поширені причини пропуску heartbeat: - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/лише-заголовкову заготовку - - `no-tasks-due`: режим задач у `HEARTBEAT.md` активний, але жоден з інтервалів задач ще не настав + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній/заголовковий каркас + - `no-tasks-due`: активний режим завдань `HEARTBEAT.md`, але жоден з інтервалів завдань ще не настав - `alerts-disabled`: уся видимість heartbeat вимкнена (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі задач мітки часу настання оновлюються лише після завершення - реального запуску heartbeat. Пропущені запуски не позначають задачі як виконані. + У режимі завдань часові позначки настання подій оновлюються лише після завершення + реального запуску heartbeat. Пропущені запуски не позначають завдання як виконані. - Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та задачі](/uk/automation). + Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та завдання](/uk/automation). @@ -160,7 +160,7 @@ x-i18n: Майстер також може автоматично зібрати UI assets. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**. - Із вихідного коду (для контриб'юторів/розробників): + Із вихідного коду (contributors/dev): ```bash git clone https://github.com/openclaw/openclaw.git @@ -176,84 +176,84 @@ x-i18n: - Майстер відкриває браузер із чистою (без токена) URL-адресою dashboard одразу після onboarding, а також виводить посилання у зведенні. Тримайте цю вкладку відкритою; якщо її не було запущено, скопіюйте/вставте надруковану URL-адресу на тій самій машині. + Майстер відкриває ваш браузер із чистою (без токена) URL-адресою dashboard одразу після onboarding, а також виводить посилання в підсумку. Залиште цю вкладку відкритою; якщо її не було запущено, скопіюйте й вставте надруковану URL-адресу на тій самій машині. **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується auth зі спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Якщо система запитує автентифікацію за спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - Якщо спільний секрет ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки identity задовольняють auth для Control UI/WebSocket (без вставлення спільного секрету, за умови довіри до хоста gateway); HTTP API усе одно вимагають auth зі спільним секретом, якщо ви навмисно не використовуєте private-ingress `none` або auth HTTP trusted-proxy. - Некоректні одночасні спроби auth від того самого клієнта серіалізуються до того, як обмежувач failed-auth зафіксує їх, тож друга невдала повторна спроба вже може показувати `retry later`. - - **Прив’язка до tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте auth за паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у налаштуваннях dashboard. - - **Reverse proxy з awareness identity**: залиште Gateway за trusted proxy не на loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL-адресу proxy. - - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Auth зі спільним секретом усе одно застосовується через tunnel; якщо буде запит, вставте налаштований токен або пароль. + - **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` дорівнює `true`, заголовки ідентифікації задовольняють автентифікацію Control UI/WebSocket (без вставлення спільного секрету, за умови довіреного хоста gateway); HTTP API, як і раніше, вимагають автентифікації за спільним секретом, якщо ви навмисно не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy. + Невдалі одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалих автентифікацій зафіксує їх, тому вже друга невдала повторна спроба може показати `retry later`. + - **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у налаштування dashboard. + - **Зворотний proxy з урахуванням ідентичності**: залиште Gateway за trusted proxy не в loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL-адресу proxy. + - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація за спільним секретом усе ще застосовується через тунель; якщо буде запит, вставте налаштований токен або пароль. - Див. [Dashboard](/web/dashboard) і [Web surfaces](/web) щодо режимів bind та деталей auth. + Див. [Dashboard](/web/dashboard) і [Веб-поверхні](/web) для деталей щодо режимів bind та автентифікації. - - Вони керують різними шарами: + + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на схвалення до призначень у чаті - - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals + - `approvals.exec`: пересилає запити на затвердження до чатів-призначень + - `channels..execApprovals`: робить цей канал нативним клієнтом затвердження для exec approvals - Політика host exec усе одно залишається справжнім бар’єром схвалення. Конфігурація чату лише визначає, де з’являються - запити на схвалення і як люди можуть на них відповідати. + Політика host exec усе ще є справжнім бар’єром затвердження. Конфігурація чату лише керує тим, де + з’являються запити на затвердження і як люди можуть на них відповідати. - У більшості середовищ вам **не** потрібні обидві: + У більшості конфігурацій вам **не** потрібні обидві: - Якщо чат уже підтримує команди та відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначати тих, хто схвалює, OpenClaw тепер автоматично вмикає нативні схвалення DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. - - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише якщо результат інструмента повідомляє, що chat approvals недоступні або ручне схвалення є єдиним шляхом. - - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або явні кімнати ops. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на схвалення публікувалися назад у вихідну кімнату/тему. - - Схвалення Plugin знову ж окремі: за замовчуванням вони використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку plugin-approval. + - Якщо підтримуваний нативний канал може безпечно визначити approvers, OpenClaw тепер автоматично вмикає нативні затвердження DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. + - Коли доступні нативні картки/кнопки затвердження, цей нативний UI є основним шляхом; агент повинен додавати ручну команду `/approve`, лише якщо результат інструмента каже, що затвердження в чаті недоступні або ручне затвердження — це єдиний шлях. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати до інших чатів або окремих ops-кімнат. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на затвердження публікувалися назад у вихідну кімнату/тему. + - Затвердження Plugin є ще окремішими: вони типово використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку plugin-затверджень. - Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. - Див. [Схвалення Exec](/uk/tools/exec-approvals). + Коротко: пересилання потрібне для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. + Див. [Exec Approvals](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендується `pnpm`. Bun **не рекомендується** для Gateway. + + Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендується** для Gateway. - Так. Gateway є легким — у документації вказано, що для персонального використання достатньо **512MB-1GB RAM**, **1 core** та приблизно **500MB** - дискового простору, а також зазначено, що **Raspberry Pi 4 може це запускати**. + Так. Gateway є легковаговим — у документації зазначено, що для особистого використання достатньо **512MB-1GB RAM**, **1 core** і приблизно **500MB** + дискового простору, а також вказано, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (логи, медіа, інші служби), **рекомендується 2GB**, але це + Якщо ви хочете трохи більше запасу (логи, медіа, інші сервіси), **рекомендовано 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може хостити Gateway, а ви можете підключити **nodes** на ноутбуці/телефоні для + Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під’єднати **nodes** на ноутбуці/телефоні для локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - - Коротко: це працює, але очікуйте шорсткі моменти. + + Коротко: це працює, але очікуйте шорстких моментів. - - Використовуйте **64-bit** ОС і Node >= 22. - - Віддавайте перевагу **зламуваному (git) встановленню**, щоб бачити логи та швидко оновлюватися. + - Використовуйте **64-бітну** ОС і Node >= 22. + - Віддавайте перевагу **змінюваному встановленню (git)**, щоб ви могли бачити логи й швидко оновлюватися. - Починайте без channels/Skills, а потім додавайте їх по одному. - - Якщо натрапите на дивні проблеми з бінарниками, зазвичай це проблема **сумісності ARM**. + - Якщо ви натрапляєте на дивні проблеми з бінарними файлами, зазвичай це проблема **ARM-сумісності**. Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). - - Цей екран залежить від того, чи доступний Gateway і чи пройдено auth. TUI також автоматично надсилає - "Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді** + + Цей екран залежить від того, чи gateway доступний і автентифікований. TUI також автоматично надсилає + "Wake up, my friend!" під час першого запуску hatch. Якщо ви бачите цей рядок **без відповіді** і токени залишаються на 0, agent так і не запустився. 1. Перезапустіть Gateway: @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. Перевірте статус + auth: + 2. Перевірте статус + автентифікацію: ```bash openclaw status @@ -270,35 +270,35 @@ x-i18n: openclaw logs --follow ``` - 3. Якщо це все ще зависає, виконайте: + 3. Якщо все одно зависає, виконайте: ```bash openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale з’єднання активне і що UI + Якщо Gateway віддалений, переконайтеся, що тунель/Tailscale-з’єднання активне і що UI вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - - Так. Скопіюйте **каталог стану** та **workspace**, а потім один раз запустіть Doctor. Це - збереже вашого бота "точно таким самим" (пам’ять, історію сесій, auth і стан + + Так. Скопіюйте **каталог стану** і **workspace**, а потім один раз запустіть Doctor. Це + збереже вашого бота «точно таким самим» (пам’ять, історію сесій, автентифікацію та стан каналів), якщо ви скопіюєте **обидва** розташування: - 1. Встановіть OpenClaw на нову машину. + 1. Установіть OpenClaw на нову машину. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). - 4. Виконайте `openclaw doctor` і перезапустіть службу Gateway. + 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. - Це зберігає конфігурацію, auth-профілі, облікові дані WhatsApp, сесії та пам’ять. Якщо ви працюєте - у віддаленому режимі, пам’ятайте, що хост gateway зберігає сховище сесій і workspace. + Це збереже конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам’ять. Якщо ви працюєте + у віддаленому режимі, пам’ятайте, що хост gateway володіє сховищем сесій і workspace. - **Важливо:** якщо ви лише commit/push свій workspace на GitHub, ви створюєте резервну копію - **пам’яті + bootstrap-файлів**, але **не** історії сесій чи auth. Вони зберігаються - у `~/.openclaw/` (наприклад `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише commit/push свій workspace у GitHub, ви створюєте резервну + копію **пам’яті + bootstrap-файлів**, але **не** історії сесій чи автентифікації. Вони зберігаються + у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). - Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#де-що-зберігається-на-диску), + Пов’язане: [Міграція](/uk/install/migrating), [Де все зберігається на диску](#де-все-зберігається-на-диску), [Workspace агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), [Віддалений режим](/uk/gateway/remote). @@ -308,16 +308,16 @@ x-i18n: Перегляньте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи зверху. Якщо верхній розділ позначено як **Unreleased**, то наступний датований - розділ — це остання випущена версія. Записи згруповані за **Основне**, **Зміни** та - **Виправлення** (а також розділами документації/іншими, коли потрібно). + Найновіші записи — вгорі. Якщо верхній розділ позначений як **Unreleased**, то наступний датований + розділ — це остання випущена версія. Записи згруповані за **Highlights**, **Changes** і + **Fixes** (а також за розділами docs/other за потреби). - + Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. - Будь ласка, допоможіть нам розблокувати це, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Будь ласка, допоможіть нам розблокувати його, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). Якщо ви все ще не можете відкрити сайт, документація дзеркалюється на GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -330,20 +330,20 @@ x-i18n: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний - крок підвищення переміщує ту саму версію в `latest`. Мейнтейнери також можуть - опублікувати одразу в `latest`, коли це потрібно. Ось чому beta і stable можуть - вказувати на **одну й ту саму версію** після підвищення. + Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім окремий + крок просування переміщує цю ж версію до `latest`. За потреби maintainers також можуть + публікувати одразу в `latest`. Саме тому beta і stable можуть + вказувати на **одну й ту саму версію** після просування. - Дивіться, що змінилося: + Подивитися, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Однорядкові команди для встановлення та різницю між beta і dev дивіться в акордеоні нижче. + Для однорядкових команд встановлення та різниці між beta і dev див. accordion нижче. - - **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після підвищення). + + **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після просування). **Dev** — це рухома вершина `main` (git); коли її публікують, вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -359,11 +359,11 @@ x-i18n: Інсталятор для Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). + Детальніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). - + Є два варіанти: 1. **Dev channel (git checkout):** @@ -372,9 +372,9 @@ x-i18n: openclaw update --channel dev ``` - Це перемикає вас на гілку `main` і оновлює з вихідного коду. + Це перемкне вас на гілку `main` і оновить із вихідного коду. - 2. **Зламуване встановлення (із сайту інсталятора):** + 2. **Hackable install (із сайту інсталятора):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -382,7 +382,7 @@ x-i18n: Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо ви віддаєте перевагу чистому клонуванню вручну, скористайтеся: + Якщо ви віддаєте перевагу чистому ручному clone, використайте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -396,18 +396,18 @@ x-i18n: - - Приблизний орієнтир: + + Орієнтовно: - - **Встановлення:** 2–5 хвилин - - **Onboarding:** 5–15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте + - **Встановлення:** 2-5 хвилин + - **Onboarding:** 5-15 хвилин залежно від кількості каналів/моделей, які ви налаштовуєте - Якщо все зависло, скористайтеся [Інсталятор завис?](#швидкий-старт-і-початкове-налаштування) + Якщо все зависає, скористайтеся [Інсталятор завис?](#швидкий-старт-і-початкове-налаштування) і швидким циклом налагодження в [Я застряг](#швидкий-старт-і-початкове-налаштування). - + Повторно запустіть інсталятор із **докладним виводом**: ```bash @@ -420,7 +420,7 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Для зламуваного (git) встановлення: + Для змінюваного встановлення (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -429,7 +429,7 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 поки не має окремого прапорця -Verbose. + # install.ps1 поки що не має окремого прапорця -Verbose. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 @@ -439,38 +439,38 @@ x-i18n: - + Дві поширені проблеми у Windows: **1) npm error spawn git / git not found** - - Встановіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. + - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. - **2) Після встановлення openclaw не розпізнається** + **2) openclaw is not recognized after install** - - Ваша глобальна папка npm bin відсутня в PATH. + - Ваша глобальна директорія npm bin відсутня в PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до вашого користувацького PATH (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - - Закрийте й знову відкрийте PowerShell після оновлення PATH. + - Додайте цю директорію до PATH користувача (у Windows суфікс `\bin` не потрібен; у більшості систем це `%AppData%\npm`). + - Після оновлення PATH закрийте й знову відкрийте PowerShell. - Якщо ви хочете найплавніше налаштування у Windows, використовуйте **WSL2** замість нативної Windows. + Якщо вам потрібне найплавніше налаштування у Windows, використовуйте **WSL2** замість нативного Windows. Документація: [Windows](/uk/platforms/windows). - - Зазвичай це невідповідність code page консолі в нативних оболонках Windows. + + Зазвичай це невідповідність кодової сторінки консолі в нативних оболонках Windows. Симптоми: - - Вивід `system.run`/`exec` показує китайський текст як mojibake - - Та сама команда нормально виглядає в іншому профілі термінала + - вивід `system.run`/`exec` показує китайський текст як mojibake + - та сама команда виглядає нормально в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -487,66 +487,66 @@ x-i18n: openclaw gateway restart ``` - Якщо ви все ще відтворюєте це в останній версії OpenClaw, відстежуйте/повідомляйте тут: + Якщо ви все ще відтворюєте це на останній версії OpenClaw, відстежуйте/повідомляйте про це тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **зламуване (git) встановлення**, щоб мати локально повний вихідний код і документацію, а потім запитайте - свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і дати точну відповідь. + Використайте **змінюване встановлення (git)**, щоб мати локально повний вихідний код і документацію, а потім запитайте + свого бота (або Claude/Codex) _з цієї теки_, щоб він міг читати репозиторій і відповідати точно. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Докладніше: [Встановлення](/uk/install) і [Прапорці інсталятора](/uk/install/installer). + Детальніше: [Встановлення](/uk/install) і [Прапорці інсталятора](/uk/install/installer). - + Коротка відповідь: дотримуйтесь інструкції для Linux, а потім запустіть onboarding. - - Швидкий шлях для Linux + встановлення служби: [Linux](/uk/platforms/linux). + - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - Інсталятор + оновлення: [Встановлення й оновлення](/uk/install/updating). - - Підійде будь-який Linux VPS. Встановіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. + + Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. - Інструкції: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). + Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - - Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Оберіть потрібного й дотримуйтесь інструкції: + + У нас є **центр хостингу** з поширеними провайдерами. Виберіть потрібного й дотримуйтесь інструкції: - - [Хостинг VPS](/uk/vps) (усі провайдери в одному місці) + - [VPS hosting](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) - Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ - зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан + workspace + Як це працює у хмарі: **Gateway працює на сервері**, а ви отримуєте доступ до нього + зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace зберігаються на сервері, тож вважайте хост джерелом істини й робіть його резервні копії. - Ви можете під’єднати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ - до локального екрана/камери/canvas або виконувати команди на ноутбуці, зберігаючи + Ви можете під’єднати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ до + локального екрана/камери/canvas або запускати команди на своєму ноутбуці, залишаючи Gateway у хмарі. - Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). + Центр: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). Nodes: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). - + Коротка відповідь: **можливо, але не рекомендується**. Процес оновлення може перезапустити Gateway (що розірве активну сесію), може вимагати чистого git checkout і - може запитувати підтвердження. Безпечніше запускати оновлення з оболонки як оператор. + може запитувати підтвердження. Безпечніше: запускати оновлення з оболонки від імені оператора. Використовуйте CLI: @@ -558,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо вам обов’язково потрібна автоматизація з agent: + Якщо вам усе ж потрібно автоматизувати це через агента: ```bash openclaw update --yes --no-restart @@ -570,98 +570,98 @@ x-i18n: - `openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: + `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделі/auth** (OAuth провайдера, API keys, Anthropic setup-token, а також локальні варіанти моделей, як-от LM Studio) + - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, Anthropic setup-token, а також варіанти локальних моделей, як-от LM Studio) - Розташування **workspace** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) - - **Встановлення демона** (LaunchAgent у macOS; systemd user unit у Linux/WSL2) + - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) + - **Установлення демона** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) - **Перевірки стану** та вибір **Skills** - Він також попереджає, якщо налаштована вами модель невідома або для неї відсутній auth. + Він також попереджає, якщо налаштована модель невідома або для неї бракує автентифікації. - Ні. Ви можете запускати OpenClaw з **API keys** (Anthropic/OpenAI/інші) або з + Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації у цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **Anthropic API key**: звичайна оплата Anthropic API - - **Claude CLI / auth підписки Claude в OpenClaw**: співробітники Anthropic - повідомили нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` - як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову + - **API-ключ Anthropic**: звичайна тарифікація Anthropic API + - **Автентифікація Claude CLI / підпискою Claude в OpenClaw**: співробітники Anthropic + повідомили нам, що таке використання знову дозволене, і OpenClaw вважає використання `claude -p` + санкціонованим для цієї інтеграції, якщо Anthropic не опублікує нову політику - Для довготривалих хостів gateway ключі Anthropic API все ще залишаються - більш передбачуваним варіантом налаштування. OpenAI Codex OAuth явно підтримується для зовнішніх + Для довготривалих хостів gateway API-ключі Anthropic залишаються + більш передбачуваним варіантом. OAuth OpenAI Codex прямо підтримується для зовнішніх інструментів на кшталт OpenClaw. OpenClaw також підтримує інші розміщені варіанти на основі підписки, зокрема - **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і + **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** та **Z.AI / GLM Coding Plan**. Документація: [Anthropic](/uk/providers/anthropic), [OpenAI](/uk/providers/openai), [Qwen Cloud](/uk/providers/qwen), - [MiniMax](/uk/providers/minimax), [Моделі GLM](/uk/providers/glm), + [MiniMax](/uk/providers/minimax), [GLM Models](/uk/providers/glm), [Локальні моделі](/uk/gateway/local-models), [Моделі](/uk/concepts/models). - + Так. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож - OpenClaw вважає auth через підписку Claude та використання `claude -p` санкціонованими - для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне - найбільш передбачуване серверне налаштування, використовуйте ключ Anthropic API. + OpenClaw вважає автентифікацію через підписку Claude і використання `claude -p` + санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. + Якщо вам потрібне найпередбачуваніше серверне налаштування, натомість використовуйте API-ключ Anthropic. - + Так. Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Anthropic setup-token усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. - Для production або multi-user навантажень auth за ключем Anthropic API усе ще є - безпечнішим і більш передбачуваним вибором. Якщо вас цікавлять інші розміщені - варіанти у стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model - Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [Моделі - GLM](/uk/providers/glm). + Anthropic setup-token усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. + Для production або multi-user навантажень автентифікація за API-ключем Anthropic все ще є + безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені + варіанти на основі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model + Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM + Models](/uk/providers/glm). -Це означає, що ваша **квота/обмеження швидкості Anthropic** вичерпано для поточного вікна. Якщо ви -використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій план. Якщо ви -використовуєте **ключ Anthropic API**, перевірте Anthropic Console -щодо використання/білінгу та за потреби збільште ліміти. +Це означає, що вашу **квоту/ліміт частоти Anthropic** вичерпано для поточного вікна. Якщо ви +використовуєте **Claude CLI**, зачекайте, поки вікно скинеться, або оновіть свій план. Якщо ви +використовуєте **API-ключ Anthropic**, перевірте Anthropic Console +щодо використання/оплати та за потреби підвищте ліміти. - Якщо повідомлення конкретно таке: - `Extra usage is required for long context requests`, запит намагається використовувати - 1M context beta від Anthropic (`context1m: true`). Це працює лише тоді, коли ваш - обліковий запис має право на білінг long-context (білінг за API key або - шлях входу в Claude через OpenClaw з увімкненим Extra Usage). + Якщо повідомлення має такий вигляд: + `Extra usage is required for long context requests`, запит намагається використати + бета-режим 1M context від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші + облікові дані мають право на тарифікацію long-context (тарифікація API-ключа або + шлях входу Claude OpenClaw із увімкненим Extra Usage). - Порада: задайте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений rate limit. - Див. [Моделі](/cli/models), [OAuth](/uk/concepts/oauth) і + Порада: установіть **резервну модель**, щоб OpenClaw міг продовжувати відповідати, поки провайдер обмежений rate limit. + Див. [Models](/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має bundled провайдер **Amazon Bedrock (Converse)**. Якщо присутні маркери середовища AWS, OpenClaw може автоматично виявляти каталог Bedrock для streaming/text і об’єднувати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку з ключем, OpenAI-сумісний proxy перед Bedrock також залишається коректним варіантом. + Так. OpenClaw має вбудований провайдер **Amazon Bedrock (Converse)**. Якщо присутні маркери AWS env, OpenClaw може автоматично виявити каталог потокових/текстових моделей Bedrock і об’єднати його як неявний провайдер `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, сумісний з OpenAI proxy перед Bedrock також залишається допустимим варіантом. - - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Onboarding може запустити OAuth-потік і за потреби встановить модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). + + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Onboarding може запустити потік OAuth і за потреби встановить модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). @@ -670,119 +670,119 @@ x-i18n: - `openai-codex/gpt-5.4` = OAuth ChatGPT/Codex - `openai/gpt-5.4` = прямий API OpenAI Platform - В OpenClaw вхід через ChatGPT/Codex прив’язаний до маршруту `openai-codex/*`, - а не до прямого маршруту `openai/*`. Якщо ви хочете прямий API-шлях в - OpenClaw, задайте `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). - Якщо ви хочете вхід ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + В OpenClaw вхід через ChatGPT/Codex прив’язаний до шляху `openai-codex/*`, + а не до прямого шляху `openai/*`. Якщо вам потрібен прямий API-шлях в + OpenClaw, установіть `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). + Якщо вам потрібен вхід через ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. - - `openai-codex/*` використовує маршрут Codex OAuth, і його доступні вікна квот + + `openai-codex/*` використовує шлях OAuth Codex, а його доступні вікна квот керуються OpenAI та залежать від плану. На практиці ці ліміти можуть відрізнятися від досвіду використання сайту/застосунку ChatGPT, навіть якщо обидва прив’язані до одного облікового запису. - OpenClaw може показувати поточні видимі вікна використання/квоти провайдера в - `openclaw models status`, але він не вигадує і не нормалізує права ChatGPT-web - у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, - використовуйте `openai/*` з API key. + OpenClaw може показувати видимі на поточний момент вікна використання/квоти провайдера у + `openclaw models status`, але не вигадує й не нормалізує + права ChatGPT-web до прямого доступу до API. Якщо вам потрібен прямий шлях + тарифікації/лімітів OpenAI Platform, використовуйте `openai/*` з API-ключем. - + Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. - OpenAI прямо дозволяє використання OAuth підписки в зовнішніх інструментах/процесах - на кшталт OpenClaw. Onboarding може запустити OAuth-потік за вас. + OpenAI явно дозволяє використання OAuth-підписки в зовнішніх інструментах/робочих процесах + на кшталт OpenClaw. Onboarding може запустити потік OAuth за вас. Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). - Gemini CLI використовує **потік auth Plugin**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **потік автентифікації Plugin**, а не client id чи secret у `openclaw.json`. Кроки: - 1. Встановіть Gemini CLI локально, щоб `gemini` був у `PATH` + 1. Установіть Gemini CLI локально, щоб `gemini` був у `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. Увімкніть Plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3-flash-preview` - 5. Якщо запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway + 5. Якщо запити не працюють, установіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає токени OAuth у auth-профілях на хості gateway. Деталі: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers). - - Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі картки обрізають і пропускають витоки. Якщо все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt-injection — див. [Безпека](/uk/gateway/security). + + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі моделі обрізають і пропускають витоки. Якщо вже потрібно, запускайте локально **найбільшу** збірку моделі, яку можете (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). - - Обирайте endpoint-и, прив’язані до регіону. OpenRouter надає варіанти з розміщенням у США для MiniMax, Kimi та GLM; оберіть варіант із розміщенням у США, щоб зберігати дані в межах регіону. Ви все одно можете перелічити Anthropic/OpenAI поряд із ними, використавши `models.mode: "merge"`, щоб резервні варіанти залишалися доступними з повагою до вибраного вами регіонального провайдера. + + Вибирайте endpoint-и, закріплені за регіоном. OpenRouter надає варіанти MiniMax, Kimi та GLM, розміщені у США; вибирайте варіант, розміщений у США, щоб дані залишалися в регіоні. Ви все одно можете перелічувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, одночасно дотримуючись вибраного вами регіонального провайдера. - + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий: дехто купує його як постійно ввімкнений хост, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. - Mac потрібен лише **для інструментів тільки для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або підключіть macOS Node. + Mac потрібен лише **для інструментів, доступних лише на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або під’єднайте macOS node. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - Вам потрібен **якийсь пристрій з macOS**, увійдений у Messages. Це **не обов’язково** має бути Mac mini — - підійде будь-який Mac. **Використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) для iMessage — сервер BlueBubbles працює на macOS, а Gateway може працювати на Linux або деінде. + Вам потрібен **будь-який пристрій macOS**, у якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — + підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. - Типові варіанти: + Поширені конфігурації: - - Запустіть Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, увійденому в Messages. - - Запустіть усе на Mac, якщо хочете найпростішу конфігурацію на одній машині. + - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac із входом у Messages. + - Запускайте все на Mac, якщо хочете найпростіше налаштування на одній машині. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як - **Node** (супутній пристрій). Nodes не запускають Gateway — вони надають додаткові - можливості, як-от screen/camera/canvas і `system.run` на цьому пристрої. + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може під’єднуватися як + **node** (companion device). Nodes не запускають Gateway — вони надають додаткові + можливості, як-от екран/камера/canvas і `system.run` на цьому пристрої. - Типовий шаблон: + Поширений шаблон: - - Gateway на Mac mini (постійно ввімкнений). - - MacBook Pro запускає застосунок macOS або хост Node і підключається до Gateway. - - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. + - Gateway на Mac mini (завжди ввімкнений). + - MacBook Pro запускає застосунок macOS або хост node і під’єднується до Gateway. + - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити це. Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). - Bun **не рекомендується**. Ми бачимо помилки під час виконання, особливо з WhatsApp і Telegram. - Використовуйте **Node** для стабільних gateway. + Bun **не рекомендується**. Ми бачимо помилки під час роботи, особливо з WhatsApp і Telegram. + Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете експериментувати з Bun, робіть це на non-production gateway + Якщо ви все ж хочете поекспериментувати з Bun, робіть це на непродукційному gateway без WhatsApp/Telegram. - - `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота. + + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не username бота. - Налаштування запитує лише числові user ID. Якщо у вашій конфігурації вже є застарілі записи `@username`, `openclaw doctor --fix` може спробувати розв’язати їх. + Під час налаштування запитуються лише числові user ID. Якщо у вашій конфігурації вже є застарілі записи `@username`, `openclaw doctor --fix` може спробувати їх розв’язати. Безпечніший варіант (без стороннього бота): - - Напишіть своєму боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. + - Напишіть вашому боту в DM, потім запустіть `openclaw logs --follow` і прочитайте `from.id`. Офіційний Bot API: - - Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. + - Напишіть вашому боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. Сторонній варіант (менш приватний): @@ -793,11 +793,11 @@ x-i18n: - Так, через **маршрутизацію multi-agent**. Прив’яжіть WhatsApp **DM** кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний workspace і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + Так, через **маршрутизацію multi-agent**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника, наприклад `+15551234567`) до різного `agentId`, щоб кожна людина мала власні workspace і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для всього облікового запису WhatsApp. Див. [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію multi-agent: призначте кожному agent власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного agent. Приклад конфігурації наведено в [Маршрутизації Multi-Agent](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію multi-agent: призначте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизація Multi-Agent](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -810,24 +810,24 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH служби містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, знаходилися в non-login shells. - Нещодавні збірки також додають на початок типові user bin directories у Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, коректно визначалися в оболонках без входу в систему. + Нещодавні збірки також додають на початок PATH поширені каталоги користувацьких bin у сервісах Linux systemd (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо їх установлено. - - - **Зламуване (git) встановлення:** повний checkout вихідного коду, можна редагувати, найкраще для контриб’юторів. - Ви локально запускаєте збірки й можете вносити виправлення в код/документацію. - - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію "просто запустити". - Оновлення надходять із npm dist-tags. + + - **Змінюване встановлення (git):** повний checkout вихідного коду, можна редагувати, найкраще для contributors. + Ви локально запускаєте збірки й можете вносити зміни в код/документацію. + - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію «просто запустити». + Оновлення надходять через npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). - - Так. Встановіть інший варіант, а потім запустіть Doctor, щоб служба gateway вказувала на нову точку входу. - Це **не видаляє ваші дані** — змінюється лише встановлений код OpenClaw. Ваш стан + + Так. Установіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову точку входу. + Це **не видаляє ваші дані** — змінюється лише встановлений код OpenClaw. Ваш state (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. З npm на git: @@ -849,67 +849,67 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність точки входу служби gateway і пропонує переписати конфігурацію служби відповідно до поточного встановлення (використовуйте `--repair` в автоматизації). + Doctor виявляє невідповідність точки входу сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (в automation використовуйте `--repair`). - Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-зберігається-на-диску). + Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-все-зберігається-на-диску). Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен - найменший поріг входу і вас влаштовують режим сну/перезапуски, запускайте локально. + мінімальний рівень тертя й вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Плюси:** немає витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. - - **Мінуси:** сон/обриви мережі = відключення, оновлення ОС/перезавантаження переривають роботу, комп’ютер має залишатися активним. + - **Плюси:** немає витрат на сервер, прямий доступ до локальних файлів, живе вікно браузера. + - **Мінуси:** сон/обриви мережі = відключення, оновлення/перезавантаження ОС переривають роботу, машина має залишатися активною. **VPS / хмара** - - **Плюси:** завжди ввімкнено, стабільна мережа, немає проблем із режимом сну ноутбука, простіше підтримувати роботу. - - **Мінуси:** часто працює без голови (використовуйте знімки екрана), лише віддалений доступ до файлів, для оновлень треба підключатися через SSH. + - **Плюси:** завжди ввімкнено, стабільна мережа, немає проблем через сон ноутбука, легше підтримувати безперервну роботу. + - **Мінуси:** часто працює безголово (використовуйте знімки екрана), доступ до файлів лише віддалений, для оновлень потрібен SSH. - **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють з VPS. Єдиний реальний компроміс — **безголовий браузер** проти видимого вікна. Див. [Браузер](/uk/tools/browser). + **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдина справжня різниця — **безголовий браузер** проти видимого вікна. Див. [Browser](/uk/tools/browser). - **Рекомендований варіант за замовчуванням:** VPS, якщо у вас уже були розриви gateway. Локальний запуск чудово підходить, коли ви активно працюєте на Mac і хочете мати локальний доступ до файлів або автоматизацію UI через видимий браузер. + **Рекомендований варіант за замовчуванням:** VPS, якщо раніше у вас були відключення gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете локальний доступ до файлів або автоматизацію UI з видимим браузером. Не обов’язково, але **рекомендується для надійності та ізоляції**. - - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати роботу. - - **Спільний ноутбук/настільний ПК:** цілком нормально для тестування й активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати безперервну роботу. + - **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. - Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук підключайте як **Node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). - Для рекомендацій із безпеки прочитайте [Безпека](/uk/gateway/security). + Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук під’єднайте як **node** для локальних інструментів екрана/камери/exec. Див. [Nodes](/uk/nodes). + Рекомендації з безпеки див. у [Безпека](/uk/gateway/security). - - OpenClaw є легким. Для базового Gateway + одного каналу чату: + + OpenClaw є легковаговим. Для базового Gateway + одного каналу чату: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. - - **Рекомендовано:** 1–2 vCPU, 2GB RAM або більше із запасом (логи, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть бути ресурсомісткими. + - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше із запасом (логи, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть бути вимогливими до ресурсів. - ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux там протестовано найкраще. + ОС: використовуйте **Ubuntu LTS** (або будь-яку сучасну Debian/Ubuntu). Шлях встановлення для Linux там протестовано найкраще. Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна й мати достатньо - RAM для Gateway і будь-яких каналів, які ви вмикаєте. + Так. Ставтеся до VM так само, як до VPS: вона має бути постійно ввімкненою, доступною та мати достатньо + RAM для Gateway і будь-яких каналів, які ви ввімкнули. Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи медіаінструменти. - - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. + - **ОС:** Ubuntu LTS або інша сучасна Debian/Ubuntu. - Якщо ви використовуєте Windows, **WSL2 — це найпростіше середовище у стилі VM** з найкращою - сумісністю інструментів. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). + Якщо ви працюєте у Windows, **WSL2 — це найпростіше налаштування у стилі VM** і воно має найкращу + сумісність інструментів. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -919,153 +919,153 @@ x-i18n: - OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає у вже знайомих вам каналах обміну повідомленнями (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і bundled channel plugins, таких як QQ Bot), а також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це завжди ввімкнена control plane; помічник — це продукт. + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і bundled channel plugins, як-от QQ Bot), а також може працювати з голосом + живим Canvas на підтримуваних платформах. **Gateway** — це завжди ввімкнена control plane; помічник і є продуктом. - OpenClaw — це не "просто обгортка для Claude". Це **local-first control plane**, яка дає змогу запускати + OpenClaw — це не «просто обгортка для Claude». Це **локально-орієнтована control plane**, яка дає змогу запускати потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі - сесіями зі станом, пам’яттю та інструментами — без передачі контролю над вашими робочими процесами розміщеному - SaaS. + станом сесій, пам’яттю та інструментами — без передавання контролю над вашими робочими процесами + хостинговому SaaS. - Основне: + Основні переваги: - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте workspace + історію сесій локально. - - **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + - **Реальні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, а також мобільний голос і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією - та резервним перемиканням на рівні agent. + - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо з маршрутизацією + і резервним перемиканням на рівні агента. - **Варіант лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. - - **Маршрутизація multi-agent:** окремі agents за каналом, обліковим записом або задачею, кожен із власним - workspace і типовими налаштуваннями. - - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте та self-host без прив’язки до постачальника. + - **Маршрутизація multi-agent:** окремі агенти для кожного каналу, облікового запису чи завдання, кожен зі своїм + workspace і налаштуваннями за замовчуванням. + - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте та self-host без vendor lock-in. Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), [Пам’ять](/uk/concepts/memory). - + Хороші перші проєкти: - Створити вебсайт (WordPress, Shopify або простий статичний сайт). - - Зробити прототип мобільного застосунку (структура, екрани, план API). - - Упорядкувати файли й папки (очищення, найменування, теги). - - Підключити Gmail і автоматизувати зведення або подальші дії. + - Створити прототип мобільного застосунку (структура, екрани, план API). + - Упорядкувати файли й теки (очищення, найменування, теги). + - Під’єднати Gmail і автоматизувати підсумки або подальші дії. - Він може впоратися з великими задачами, але найкраще працює, коли ви ділите їх на етапи й - використовуєте sub-agents для паралельної роботи. + Він може впоратися з великими завданнями, але працює найкраще, коли ви ділите їх на етапи і + використовуєте sub agents для паралельної роботи. - - Щоденні виграші зазвичай виглядають так: + + Щоденні переваги зазвичай виглядають так: - - **Персональні зведення:** підсумки inbox, календаря та новин, які вас цікавлять. - - **Дослідження та чернетки:** швидке дослідження, підсумки й перші чернетки листів або документів. - - **Нагадування та подальші дії:** підштовхування й чеклісти на основі cron або heartbeat. - - **Автоматизація браузера:** заповнення форм, збирання даних і повторення вебзадач. - - **Координація між пристроями:** надішліть задачу з телефона, дозвольте Gateway виконати її на сервері й отримайте результат назад у чат. + - **Персональні брифінги:** підсумки скриньки вхідних, календаря та новин, які вас цікавлять. + - **Дослідження й чернетки:** швидкі дослідження, підсумки та перші чернетки для листів або документів. + - **Нагадування та подальші дії:** підказки та чеклісти на основі cron або heartbeat. + - **Автоматизація браузера:** заповнення форм, збирання даних і повторення веб-завдань. + - **Координація між пристроями:** надішліть завдання з телефона, дайте Gateway виконати його на сервері й отримайте результат назад у чаті. - - Так — для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати короткі списки, + + Так — для **дослідження, кваліфікації та створення чернеток**. Він може сканувати сайти, створювати shortlists, підсумовувати інформацію про потенційних клієнтів і писати чернетки outreach або рекламних текстів. - Для **outreach або запуску реклами** тримайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ, і переглядайте все перед відправленням. Найбезпечніший шаблон — дозволити - OpenClaw підготувати чернетку, а вам її схвалити. + Для **outreach або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і + правил платформ та переглядайте все перед відправленням. Найбезпечніший шаблон — нехай + OpenClaw створює чернетку, а ви її затверджуєте. Документація: [Безпека](/uk/gateway/security). - OpenClaw — це **персональний помічник** і рівень координації, а не заміна IDE. Використовуйте - Claude Code або Codex для найшвидшого прямого циклу кодування всередині репозиторію. Використовуйте OpenClaw, коли вам - потрібні тривала пам’ять, доступ з різних пристроїв і оркестрація інструментів. + OpenClaw — це **персональний помічник** і шар координації, а не заміна IDE. Використовуйте + Claude Code або Codex для найшвидшого прямого циклу програмування всередині репозиторію. Використовуйте OpenClaw, коли вам + потрібні тривка пам’ять, доступ між пристроями та оркестрація інструментів. Переваги: - **Постійна пам’ять + workspace** між сесіями - - **Доступ із різних платформ** (WhatsApp, Telegram, TUI, WebChat) + - **Доступ із багатьох платформ** (WhatsApp, Telegram, TUI, WebChat) - **Оркестрація інструментів** (браузер, файли, планування, hooks) - - **Завжди ввімкнений Gateway** (запуск на VPS, взаємодія звідусіль) - - **Nodes** для локального browser/screen/camera/exec + - **Завжди ввімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль) + - **Nodes** для локального браузера/екрана/камери/exec Вітрина: [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` → bundled → `skills.load.extraDirs`, тож керовані перевизначення все одно мають вищий пріоритет за bundled skills без змін у git. Якщо вам потрібно, щоб skill був установлений глобально, але видимий лише деяким agents, зберігайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, варті додавання в upstream, мають жити в репозиторії й надсилатися як PR. + + Використовуйте керовані overrides замість редагування копії в репозиторії. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте теку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані overrides однаково мають вищий пріоритет за bundled skills без змін у git. Якщо вам потрібно, щоб skill був установлений глобально, але видимий лише для деяких агентів, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` і `agents.list[].skills`. Лише зміни, гідні включення в основну гілку, мають жити в репозиторії й надсилатися як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий порядок пріоритету: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw розглядає як `/skills` у наступній сесії. Якщо skill має бути видимим лише певним agents, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові теки через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Пріоритет за замовчуванням: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw розглядає як `/skills` у наступній сесії. Якщо skill має бути видимим лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - + Наразі підтримуються такі шаблони: - - **Cron jobs**: ізольовані задачі можуть задавати перевизначення `model` для кожної задачі. - - **Sub-agents**: маршрутизуйте задачі до окремих agents з різними типовими моделями. - - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити модель поточної сесії. + - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. + - **Sub-agents**: маршрутизуйте завдання до окремих агентів із різними моделями за замовчуванням. + - **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли змінити модель поточної сесії. Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [Slash commands](/uk/tools/slash-commands). - - Використовуйте **sub-agents** для тривалих або паралельних задач. Sub-agents працюють у власній сесії, - повертають підсумок і зберігають чуйність вашого основного чату. + + Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній сесії, + повертають підсумок і зберігають чутливість основного чату. - Попросіть бота "spawn a sub-agent for this task" або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб побачити, що Gateway робить просто зараз (і чи він зайнятий). + Попросіть бота «spawn a sub-agent for this task» або використайте `/subagents`. + Використовуйте `/status` у чаті, щоб бачити, що Gateway робить просто зараз (і чи він зайнятий). - Порада щодо токенів: і довгі задачі, і sub-agents споживають токени. Якщо вартість має значення, задайте - дешевшу модель для sub-agents через `agents.defaults.subagents.model`. + Порада щодо токенів: і довгі завдання, і sub-agents споживають токени. Якщо важлива + вартість, задайте дешевшу модель для sub-agents через `agents.defaults.subagents.model`. - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив’язки тредів. Ви можете прив’язати тред Discord до subagent або цільової сесії, щоб подальші повідомлення в цьому треді залишалися в межах прив’язаної сесії. + + Використовуйте прив’язки thread. Ви можете прив’язати thread Discord до subagent або цілі session, щоб подальші повідомлення в цьому thread залишалися в межах прив’язаної сесії. Базовий процес: - - Запустіть через `sessions_spawn` з `thread: true` (і, за потреби, `mode: "session"` для постійної подальшої роботи). - - Або прив’яжіть вручну за допомогою `/focus `. + - Запустіть через `sessions_spawn` з `thread: true` (і за бажанням `mode: "session"` для постійних подальших дій). + - Або прив’яжіть вручну через `/focus `. - Використовуйте `/agents`, щоб перевірити стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокусу. - - Використовуйте `/unfocus`, щоб від’єднати тред. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. + - Використовуйте `/unfocus`, щоб від’єднати thread. Потрібна конфігурація: - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Перевизначення Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоматична прив’язка під час spawn: задайте `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Overrides Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Автоприв’язка під час spawn: установіть `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). + Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Configuration Reference](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). - + Спочатку перевірте визначений маршрут запитувача: - - Доставка subagent у режимі завершення надає перевагу будь-якому прив’язаному треду або маршруту розмови, якщо такий існує. - - Якщо джерело завершення містить лише канал, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати. - - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і тоді результат повертається до доставки через чергу сесії замість негайної публікації в чат. - - Некоректні або застарілі цілі все ще можуть примусово перевести доставку в чергу або спричинити остаточну помилку доставки. - - Якщо остання видима відповідь assistant у дочірній сесії — це точний тихий токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно приглушує оголошення замість публікації застарілого попереднього прогресу. - - Якщо дочірня сесія завершилася за тайм-аутом після одних лише викликів інструментів, оголошення може згорнути це до короткого підсумку часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка subagent у режимі completion віддає перевагу будь-якому прив’язаному thread або маршруту розмови, якщо такий існує. + - Якщо джерело completion містить лише канал, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат замість негайної публікації в чаті перейде до доставки через чергу сесії. + - Неприпустимі або застарілі цілі все одно можуть змусити систему перейти до резервного варіанта з чергою або спричинити остаточний збій доставки. + - Якщо остання видима відповідь дочірнього assistant — це точний беззвучний токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує оголошення замість публікації застарілого попереднього прогресу. + - Якщо дочірній процес перевищив час очікування після лише викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість повторення сирого виводу інструментів. Налагодження: @@ -1073,19 +1073,19 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks), [Інструмент сесій](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент Session](/uk/concepts/session-tool). - Cron запускається всередині процесу Gateway. Якщо Gateway не працює безперервно, - заплановані задачі не виконуватимуться. + Cron працює всередині процесу Gateway. Якщо Gateway не працює безперервно, + заплановані завдання не запускатимуться. Контрольний список: - - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - - Перевірте, що Gateway працює 24/7 (без режиму сну/перезапусків). - - Перевірте налаштування часового поясу для задачі (`--tz` проти часового поясу хоста). + - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. + - Перевірте, що Gateway працює 24/7 (без сну/перезапусків). + - Перевірте налаштування часового поясу для завдання (`--tz` порівняно з часовим поясом хоста). Налагодження: @@ -1094,7 +1094,7 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та задачі](/uk/automation). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation). @@ -1102,13 +1102,13 @@ x-i18n: Спочатку перевірте режим доставки: - `--no-deliver` / `delivery.mode: "none"` означає, що зовнішнє повідомлення не очікується. - - Відсутня або некоректна ціль оголошення (`channel` / `to`) означає, що runner пропустив вихідну доставку. - - Помилки auth каналу (`unauthorized`, `Forbidden`) означають, що runner намагався доставити повідомлення, але облікові дані це заблокували. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` лише) вважається навмисно недоставним, тому runner також приглушує запасну доставку через чергу. + - Відсутня або неприпустима ціль оголошення (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що runner намагався доставити повідомлення, але облікові дані заблокували це. + - Беззвучний ізольований результат (`NO_REPLY` / `no_reply` і нічого більше) вважається навмисно непридатним для доставки, тому runner також пригнічує резервну доставку через чергу. Для ізольованих cron jobs runner відповідає за фінальну доставку. Очікується, - що agent поверне текстовий підсумок, який runner надішле. `--no-deliver` зберігає - цей результат внутрішнім; це не дозволяє agent натомість надсилати напряму через + що агент поверне простий текстовий підсумок, який runner зможе надіслати. `--no-deliver` зберігає + цей результат внутрішнім; він не дозволяє агенту натомість надсилати повідомлення напряму за допомогою message tool. Налагодження: @@ -1118,27 +1118,27 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові задачі](/uk/automation/tasks). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). - - Зазвичай це шлях live-перемикання моделі, а не дубльоване планування. + + Зазвичай це шлях живого перемикання моделі, а не дубльоване планування. - Ізольований cron може зберегти runtime-передачу моделі та повторити спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнений - provider/model, а якщо перемикання несло нове перевизначення auth-профілю, cron - також зберігає його перед повторною спробою. + Ізольований cron може зберігати передачу runtime-моделі й повторювати спробу, коли активний + запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає переключений + provider/model, а якщо переключення також містило новий override профілю автентифікації, cron + теж зберігає його перед повторною спробою. Пов’язані правила вибору: - - Спочатку застосовується перевизначення моделі Gmail hook, якщо воно доречне. - - Потім `model` для конкретної задачі. - - Потім будь-яке збережене перевизначення моделі cron-сесії. - - Потім звичайний вибір моделі agent/типової моделі. + - Override моделі hook Gmail має найвищий пріоритет, коли застосовується. + - Потім іде `model` для конкретного завдання. + - Потім — будь-який збережений override моделі cron-session. + - Потім — звичайний вибір моделі агента/за замовчуванням. - Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроб перемикання - cron перериває виконання замість нескінченного циклу. + Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторів через переключення + cron припиняє роботу замість нескінченного циклу. Налагодження: @@ -1151,8 +1151,8 @@ x-i18n: - - Використовуйте нативні команди `openclaw skills` або просто додавайте skills у свій workspace. UI Skills для macOS недоступний на Linux. + + Використовуйте нативні команди `openclaw skills` або просто кладіть skills у свій workspace. UI Skills для macOS недоступний на Linux. Переглянути skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash @@ -1168,39 +1168,39 @@ x-i18n: Нативна команда `openclaw skills install` записує у каталог `skills/` активного workspace. Окремий CLI `clawhub` встановлюйте лише якщо хочете публікувати або - синхронізувати власні skills. Для спільного встановлення між agents розміщуйте skill у + синхронізувати власні skills. Для спільних установлень між агентами розміщуйте skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете звузити коло agents, які можуть його бачити. + `agents.list[].skills`, якщо хочете звузити коло агентів, які можуть його бачити. - + Так. Використовуйте планувальник Gateway: - - **Cron jobs** для запланованих або повторюваних задач (зберігаються після перезапусків). - - **Heartbeat** для періодичних перевірок "основної сесії". - - **Ізольовані jobs** для автономних agents, які публікують підсумки або доставляють їх у чати. + - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). + - **Heartbeat** для періодичних перевірок «основної сесії». + - **Ізольовані jobs** для автономних агентів, які публікують підсумки або доставляють їх у чати. - Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та задачі](/uk/automation), + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Не напряму. Skills для macOS обмежуються через `metadata.openclaw.os` плюс потрібні бінарні файли, і skills з’являються в system prompt лише тоді, коли вони придатні на **хості 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 Node (без SSH).** - Запустіть Gateway на Linux, підключіть macOS Node (застосунок у menubar) і встановіть **Node Run Commands** у значення "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати macOS-only skills придатними, якщо потрібні бінарні файли існують на Node. Agent запускає ці skills через інструмент `nodes`. Якщо ви оберете "Always Ask", підтвердження "Always Allow" у запиті додає цю команду до allowlist. + **Варіант B — використовувати macOS node (без SSH).** + Запускайте Gateway на Linux, під’єднайте macOS node (застосунок у рядку меню) і встановіть **Node Run Commands** у режим "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати skills лише для macOS придатними, коли потрібні бінарні файли існують на node. Агент запускає ці skills через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додасть цю команду до allowlist. - **Варіант C — проксувати бінарні файли macOS через SSH (розширений варіант).** - Залиште Gateway на Linux, але налаштуйте так, щоб потрібні CLI-бінарники розв’язувалися у SSH-обгортки, які запускаються на Mac. Потім перевизначте skill, щоб дозволити Linux і зберегти його придатним. + **Варіант C — проксіювати бінарні файли macOS через SSH (просунутий).** + Залиште Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарні файли визначалися як SSH-обгортки, які запускаються на Mac. Потім перевизначте skill, щоб дозволити Linux і зберегти його придатним. - 1. Створіть SSH-обгортку для бінарного файлу (приклад: `memo` для Apple Notes): + 1. Створіть SSH-обгортку для бінарного файла (приклад: `memo` для Apple Notes): ```bash #!/usr/bin/env bash @@ -1208,13 +1208,13 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Розмістіть обгортку в `PATH` на Linux-хості (наприклад `~/bin/memo`). - 3. Перевизначте metadata skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: + 2. Додайте обгортку до `PATH` на Linux-хості (наприклад, `~/bin/memo`). + 3. Перевизначте метадані skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- name: apple-notes - description: Керування Apple Notes через CLI `memo` на macOS. + description: Manage Apple Notes via the memo CLI on macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` @@ -1223,54 +1223,54 @@ x-i18n: - - Вбудованої наразі немає. + + Сьогодні вбудованої немає. Варіанти: - **Власний skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - **Автоматизація браузера:** працює без коду, але повільніше й крихкіше. - Якщо ви хочете зберігати контекст для кожного клієнта (agency workflows), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (робочі процеси агентства), простий шаблон такий: - - Одна сторінка Notion на клієнта (контекст + налаштування + активна робота). - - Попросіть agent отримати цю сторінку на початку сесії. + - Одна сторінка Notion на кожного клієнта (контекст + уподобання + активна робота). + - Попросіть агента отримувати цю сторінку на початку сесії. - Якщо вам потрібна нативна інтеграція, створіть запит на нову функцію або побудуйте skill, - націлений на ці API. + Якщо вам потрібна нативна інтеграція, створіть запит на функцію або побудуйте skill, + орієнтований на ці API. - Встановлення skills: + Установлення skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних skills між agents розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі agents, налаштуйте `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/` активного workspace. Для спільних 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). - - Використовуйте вбудований профіль браузера `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 ``` - Цей шлях може використовувати локальний браузер хоста або підключений browser Node. Якщо Gateway працює деінде, або запустіть хост Node на машині з браузером, або використовуйте віддалений CDP. + Цей шлях може використовувати локальний браузер хоста або під’єднаний browser node. Якщо Gateway працює деінде, або запустіть хост node на машині з браузером, або натомість використовуйте віддалений CDP. - Поточні обмеження для `existing-session` / `user`: + Поточні обмеження `existing-session` / `user`: - - дії прив’язані до ref, а не до CSS-селекторів - - завантаження файлів потребує `ref` / `inputRef` і наразі підтримує лише один файл за раз + - дії керуються через ref, а не через CSS-селектори + - вивантаження файлів потребують `ref` / `inputRef` і наразі підтримують лише один файл за раз - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP @@ -1279,41 +1279,41 @@ x-i18n: ## Ізоляція та пам’ять - - Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи sandbox), див. [Docker](/uk/install/docker). + + Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи ізоляції), див. [Docker](/uk/install/docker). - - Образ за замовчуванням орієнтований на безпеку і запускається від користувача `node`, тож він не - містить системних пакетів, Homebrew або bundled браузерів. Для повнішого налаштування: + + Образ за замовчуванням орієнтований на безпеку й запускається від користувача `node`, тому він не + містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування: - - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші не втрачалися. - - Додавайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. - - Встановлюйте браузери Playwright через bundled 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). + Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). - - Так — якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**. + + Так — якщо ваш приватний трафік це **DM**, а публічний трафік — **groups**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сесії груп/каналів (ключі не-main) запускалися в Docker, а основна сесія DM залишалася на хості. Потім обмежте доступні інструменти в ізольованих сесіях через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (ключі не-main) виконувалися в Docker, а основна DM-сесія залишалася на хості. Потім обмежте набір інструментів, доступних в ізольованих сесіях, через `tools.sandbox.tools`. - Покрокове налаштування + приклад конфігурації: [Групи: приватні DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) + Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідка з ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідник із ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - - Задайте `agents.defaults.sandbox.docker.binds` у вигляді `["host:path:mode"]` (наприклад `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки для конкретного agent об’єднуються; прив’язки для конкретного agent ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові стіни sandbox. + + Установіть `agents.defaults.sandbox.docker.binds` у значення `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки для конкретного агента об’єднуються; прив’язки для конкретного агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові стіни ізоляції. - OpenClaw перевіряє джерела прив’язок і за нормалізованим шляхом, і за канонічним шляхом, визначеним через найглибшого наявного предка. Це означає, що виходи за межі через батьківський symlink усе одно надійно блокуються, навіть коли останній сегмент шляху ще не існує, а перевірки дозволеного кореня все одно застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind як за нормалізованим шляхом, так і за канонічним шляхом, розв’язаним через найглибший наявний предок. Це означає, що виходи за межі через батьківські symlink все одно безпечно блокуються, навіть коли останній сегмент шляху ще не існує, і перевірки allowed-root усе одно застосовуються після розв’язання symlink. - Див. [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і приміток щодо безпеки. + Приклади та зауваження щодо безпеки див. у [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check). @@ -1321,56 +1321,55 @@ x-i18n: Пам’ять OpenClaw — це просто Markdown-файли у workspace агента: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Відібрані довгострокові нотатки в `MEMORY.md` (лише для main/private sessions) + - Кураторські довгострокові нотатки в `MEMORY.md` (лише для main/private sessions) OpenClaw також виконує **тихий flush пам’яті перед Compaction**, щоб нагадати моделі - записати стійкі нотатки перед автоматичним Compaction. Це виконується лише тоді, коли workspace - доступний для запису (read-only sandbox це пропускають). Див. [Пам’ять](/uk/concepts/memory). + записати довготривалі нотатки перед автоматичним Compaction. Це виконується лише тоді, коли workspace + доступний для запису (у sandbox лише для читання це пропускається). Див. [Пам’ять](/uk/concepts/memory). - + Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки мають бути в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще напрям, який ми покращуємо. Корисно нагадувати моделі зберігати спогади; - вона знатиме, що робити. Якщо вона продовжує забувати, перевірте, що Gateway використовує той самий - workspace під час кожного запуску. + Це все ще сфера, яку ми покращуємо. Корисно нагадувати моделі зберігати спогади; + вона знатиме, що робити. Якщо вона продовжує забувати, перевірте, що Gateway щоразу використовує + той самий workspace. Документація: [Пам’ять](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). - Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сесії** все одно обмежений вікном контексту моделі, - тому довгі розмови можуть ущільнюватися або обрізатися. Саме тому існує - пошук у пам’яті — він повертає в контекст лише релевантні частини. + Файли пам’яті живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є + ваше сховище, а не модель. **Контекст сесії** все одно обмежений + вікном контексту моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому + існує пошук у пам’яті — він повертає в контекст лише релевантні частини. Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). - + Лише якщо ви використовуєте **embeddings OpenAI**. OAuth Codex покриває chat/completions і - **не** надає доступу до embeddings, тому **вхід через Codex (OAuth або - вхід через CLI Codex)** не допомагає для семантичного пошуку в пам’яті. Для embeddings OpenAI - усе одно потрібен справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). + **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або + вхід через Codex CLI)** не допомагає для семантичного пошуку в пам’яті. Для embeddings OpenAI + усе ще потрібен справжній API-ключ (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли - може визначити API key (auth-профілі, `models.providers.*.apiKey` або env vars). - Він надає перевагу OpenAI, якщо визначається ключ OpenAI, інакше Gemini, якщо визначається ключ Gemini, - далі Voyage, потім Mistral. Якщо віддалений ключ недоступний, пошук у пам’яті - залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано локальний шлях до моделі - і він наявний, OpenClaw - надає перевагу `local`. Ollama підтримується, якщо ви явно задаєте + може визначити API-ключ (профілі автентифікації, `models.providers.*.apiKey` або env vars). + Він віддає перевагу OpenAI, якщо вдається визначити ключ OpenAI, інакше Gemini, якщо вдається визначити ключ Gemini, + потім Voyage, потім Mistral. Якщо віддалений ключ недоступний, пошук у пам’яті + залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й наявний шлях до локальної моделі, OpenClaw + віддає перевагу `local`. Ollama підтримується, якщо ви явно задаєте `memorySearch.provider = "ollama"`. - Якщо ви хочете залишитися локально, задайте `memorySearch.provider = "local"` (і за бажанням - `memorySearch.fallback = "none"`). Якщо вам потрібні embeddings Gemini, задайте + Якщо ви хочете залишатися локально, установіть `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо вам потрібні embeddings Gemini, установіть `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — - див. [Пам’ять](/uk/concepts/memory) для деталей налаштування. + деталі налаштування див. у [Пам’ять](/uk/concepts/memory). @@ -1379,15 +1378,15 @@ x-i18n: - Ні — **стан OpenClaw локальний**, але **зовнішні служби все одно бачать те, що ви їм надсилаєте**. + Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** sessions, файли пам’яті, конфігурація та workspace живуть на хості Gateway - (`~/.openclaw` + каталог вашого workspace). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), надходять до - їхніх API, а платформи чатів (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на + - **Локально за замовчуванням:** sessions, файли пам’яті, конфігурація та workspace зберігаються на хості Gateway + (`~/.openclaw` + ваш каталог workspace). + - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), ідуть до + їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх серверах. - - **Ви контролюєте слід:** використання локальних моделей залишає prompts на вашій машині, але трафік - каналів усе одно проходить через сервери відповідного каналу. + - **Ви контролюєте обсяг даних:** використання локальних моделей залишає prompt-и на вашій машині, але трафік + каналів усе одно проходить через сервери цього каналу. Пов’язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). @@ -1399,31 +1398,31 @@ x-i18n: | Path | Призначення | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Імпорт застарілого OAuth (копіюється в auth-профілі під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth-профілі (OAuth, API keys та необов’язкові `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 + sessions) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Імпорт застарілого OAuth (копіюється в профілі автентифікації під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API-ключі та необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове корисне навантаження secret для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл сумісності зі застарілими версіями (статичні записи `api_key` очищено) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + sessions) | | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). - Ваш **workspace** (`AGENTS.md`, файли пам’яті, skills тощо) відокремлений і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (`AGENTS.md`, файли пам’яті, skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - Ці файли живуть у **workspace агента**, а не в `~/.openclaw`. + Ці файли зберігаються у **workspace агента**, а не в `~/.openclaw`. - - **Workspace (для кожного агента):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (або застарілий запасний варіант `memory.md`, коли `MEMORY.md` відсутній), - `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - - **Каталог стану (`~/.openclaw`)**: конфігурація, стан channel/provider, auth-профілі, sessions, логи + - **Workspace (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (або застарілий резервний варіант `memory.md`, якщо `MEMORY.md` відсутній), + `memory/YYYY-MM-DD.md`, необов’язково `HEARTBEAT.md`. + - **Каталог state (`~/.openclaw`)**: конфігурація, стан каналу/провайдера, профілі автентифікації, sessions, логи, і спільні skills (`~/.openclaw/skills`). - Типовий workspace: `~/.openclaw/workspace`, налаштовується через: + Типовий workspace — `~/.openclaw/workspace`, його можна налаштувати через: ```json5 { @@ -1431,11 +1430,11 @@ x-i18n: } ``` - Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway використовує той самий - workspace під час кожного запуску (і пам’ятайте: у віддаленому режимі використовується workspace **хоста gateway**, + Якщо бот «забуває» після перезапуску, переконайтеся, що Gateway використовує той самий + workspace під час кожного запуску (і пам’ятайте: віддалений режим використовує workspace **хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете стійку поведінку або налаштування, попросіть бота **записати це в + Порада: якщо ви хочете зберегти поведінку або вподобання надовго, попросіть бота **записати це в AGENTS.md або MEMORY.md**, а не покладатися на історію чату. Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). @@ -1443,13 +1442,13 @@ x-i18n: - Розмістіть свій **workspace агента** в **приватному** git-репозиторії та створюйте його резервні копії десь - у приватному місці (наприклад, у приватному GitHub). Це збереже пам’ять + файли AGENTS/SOUL/USER - і дасть змогу пізніше відновити "мислення" помічника. + Помістіть ваш **workspace агента** у **приватний** git-репозиторій і робіть його резервні копії десь + приватно (наприклад, у приватному GitHub). Це зберігає пам’ять + файли AGENTS/SOUL/USER + і дає змогу пізніше відновити «розум» помічника. - **Не** виконуйте commit для будь-чого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані секретні payloads). - Якщо вам потрібне повне відновлення, окремо робіть резервні копії і workspace, і каталогу стану - (див. питання про міграцію вище). + **Не** commit-те нічого з `~/.openclaw` (облікові дані, sessions, токени або зашифровані корисні навантаження secret). + Якщо вам потрібне повне відновлення, робіть резервні копії і workspace, і каталогу state + окремо (див. питання про міграцію вище). Документація: [Workspace агента](/uk/concepts/agent-workspace). @@ -1459,14 +1458,14 @@ x-i18n: Див. окремий посібник: [Видалення](/uk/install/uninstall). - - Так. Workspace — це **типовий cwd** і якір пам’яті, а не жорсткий sandbox. - Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть отримувати доступ до інших + + Так. Workspace — це **типовий cwd** і прив’язка пам’яті, а не жорстка sandbox. + Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть звертатися до інших розташувань хоста, якщо sandboxing не ввімкнено. Якщо вам потрібна ізоляція, використовуйте [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для конкретного агента. Якщо ви хочете, щоб репозиторій був типовим робочим каталогом, вкажіть `workspace` цього агента на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте - workspace окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. + workspace окремо, якщо тільки ви свідомо не хочете, щоб агент працював усередині нього. Приклад (репозиторій як типовий cwd): @@ -1482,7 +1481,7 @@ x-i18n: - + Стан сесій належить **хосту gateway**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище сесій розташоване на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). @@ -1490,22 +1489,22 @@ x-i18n: ## Основи конфігурації - + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються відносно безпечні типові значення (включно з типовим workspace `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (включно з типовим workspace `~/.openclaw/workspace`). - - Прив’язки не до loopback **вимагають дійсного шляху auth gateway**. На практиці це означає: + + Bind-и не в loopback **вимагають дійсного шляху автентифікації gateway**. На практиці це означає: - - auth зі спільним секретом: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим reverse proxy з awareness identity не на loopback + - автентифікація за спільним секретом: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не в loopback ```json5 { @@ -1521,32 +1520,32 @@ x-i18n: Примітки: - - `gateway.remote.token` / `.password` **самі по собі** не вмикають локальний auth gateway. - - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. - - Для auth за паролем задайте натомість `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується в закритому режимі (без маскувального запасного варіанту через remote). - - Конфігурації Control UI зі спільним секретом автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з identity, такі як Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запитів. Уникайте розміщення спільних секретів в URL. - - При `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback того ж хоста все одно **не** задовольняють trusted-proxy auth. Trusted proxy має бути налаштованим джерелом не на loopback. + - `gateway.remote.token` / `.password` самі по собі **не** вмикають автентифікацію локального gateway. + - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. + - Для автентифікації паролем натомість установіть `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається розв’язати, розв’язання безпечно завершується відмовою (без маскування резервним віддаленим варіантом). + - Конфігурації Control UI зі спільним секретом проходять автентифікацію через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях застосунку/UI). Режими з ідентифікацією, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запитів. Уникайте розміщення спільних секретів в URL. + - З `gateway.auth.mode: "trusted-proxy"` reverse proxy loopback на тому ж хості все одно **не** задовольняють автентифікацію trusted-proxy. Trusted proxy має бути налаштованим джерелом не в loopback. - OpenClaw примусово застосовує auth gateway за замовчуванням, включно з loopback. У звичайному типовому шляху це означає auth за токеном: якщо явний шлях auth не налаштовано, запуск gateway переходить у режим токена й автоматично генерує його, зберігаючи в `gateway.auth.token`, тож **локальні WS-клієнти мають автентифікуватися**. Це блокує інші локальні процеси від виклику Gateway. + OpenClaw примусово вимагає автентифікацію gateway за замовчуванням, зокрема й на loopback. У звичайному типовому сценарії це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, запуск gateway переходить у режим токена й автоматично генерує його, зберігаючи в `gateway.auth.token`, тому **локальні WS-клієнти мають проходити автентифікацію**. Це блокує інші локальні процеси від виклику Gateway. - Якщо ви віддаєте перевагу іншому шляху auth, можна явно вибрати режим пароля (або, для reverse proxy з awareness identity не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своїй конфігурації. Doctor може згенерувати токен для вас у будь-який момент: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху автентифікації, ви можете явно вибрати режим пароля (або, для identity-aware reverse proxy не в loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть у конфігурації `gateway.auth.mode: "none"`. Doctor може будь-коли згенерувати для вас токен: `openclaw doctor --generate-gateway-token`. - Gateway стежить за конфігурацією і підтримує гаряче перезавантаження: + Gateway відстежує конфігурацію та підтримує гаряче перезавантаження: - - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни на гарячу, перезапускає для критичних + - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни «на гарячу», а для критичних виконує перезапуск - також підтримуються `hot`, `restart`, `off` - - Задайте `cli.banner.taglineMode` у конфігурації: + + Установіть `cli.banner.taglineMode` у конфігурації: ```json5 { @@ -1558,23 +1557,23 @@ 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 key. `web_search` залежить від вибраного + `web_fetch` працює без API-ключа. `web_search` залежить від вибраного провайдера: - - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API key. - - Ollama Web Search не потребує ключа, але використовує налаштований хост Ollama і вимагає `ollama signin`. + - Провайдери з API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API-ключа. + - Ollama Web Search не потребує ключа, але використовує налаштований вами хост Ollama і вимагає `ollama signin`. - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує ключа/може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG не потребує ключа / підтримує self-hosting; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. + **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть провайдера. Альтернативи через середовище: - Brave: `BRAVE_API_KEY` @@ -1610,59 +1609,59 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // необов’язково; пропустіть для auto-detect + provider: "firecrawl", // необов’язково; пропустіть для автоматичного виявлення }, }, }, } ``` - Специфічна для провайдера конфігурація web-search тепер розміщується в `plugins.entries..config.webSearch.*`. - Застарілі шляхи провайдера `tools.web.search.*` тимчасово все ще завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. - Конфігурація запасного варіанта Firecrawl для web-fetch розміщується в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація web-search, специфічна для провайдера, тепер розташована в `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдерів `tools.web.search.*` тимчасово все ще завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. + Конфігурація резервного варіанта web-fetch Firecrawl розташована в `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - - Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. + - Якщо ви використовуєте allowlist-и, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). - - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового запасного провайдера fetch із доступних облікових даних. Наразі bundled провайдером є Firecrawl. - - Демони читають env vars з `~/.openclaw/.env` (або із середовища служби). + - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового провайдера резервного варіанта fetch із доступних облікових даних. Наразі вбудованим провайдером є Firecrawl. + - Демони читають env vars з `~/.openclaw/.env` (або із середовища сервісу). - Документація: [Web tools](/uk/tools/web). + Документація: [Веб-інструменти](/uk/tools/web). - - `config.apply` замінює **всю конфігурацію цілком**. Якщо ви надсилаєте частковий об’єкт, усе + + `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, усе інше буде видалено. Відновлення: - - Відновіть із резервної копії (git або скопійованого `~/.openclaw/openclaw.json`). - - Якщо резервної копії немає, знову запустіть `openclaw doctor` і повторно налаштуйте channels/models. - - Якщо це було неочікувано, створіть bug report і додайте останню відому конфігурацію або будь-яку резервну копію. - - Локальний агент для кодування часто може відновити працездатну конфігурацію з логів або історії. + - Відновіть із резервної копії (git або скопійований `~/.openclaw/openclaw.json`). + - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і заново налаштуйте канали/моделі. + - Якщо це було неочікувано, створіть bug і додайте останню відому конфігурацію або будь-яку резервну копію. + - Локальний coding agent часто може відновити робочу конфігурацію за логами або історією. Як уникнути: - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Спочатку використовуйте `config.schema.lookup`, коли ви не впевнені в точному шляху або формі поля; він повертає вузол неглибокої схеми плюс підсумки безпосередніх дочірніх елементів для подальшого заглиблення. - - Використовуйте `config.patch` для часткових редагувань через RPC; залишайте `config.apply` лише для повної заміни конфігурації. - - Якщо ви використовуєте owner-only інструмент `gateway` із запуску agent, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Спочатку використовуйте `config.schema.lookup`, якщо не впевнені щодо точного шляху або форми поля; він повертає поверхневий вузол схеми плюс зведення безпосередніх дочірніх елементів для подальшого заглиблення. + - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни конфігурації. + - Якщо ви використовуєте tool `gateway`, доступний лише власнику, у запуску агента, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). - Документація: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/uk/gateway/doctor). + Документація: [Конфігурація](/cli/config), [Налаштування](/cli/configure), [Doctor](/uk/gateway/doctor). - Поширений шаблон — **один Gateway** (наприклад Raspberry Pi) плюс **nodes** і **agents**: + Поширений шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє channels (Signal/WhatsApp), маршрутизацією та сесіями. - - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія та надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Agents (workers):** окремі інтелекти/workspaces для спеціальних ролей (наприклад "Hetzner ops", "Personal data"). - - **Sub-agents:** запускають фонову роботу з основного agent, коли вам потрібен паралелізм. - - **TUI:** підключається до Gateway і перемикає agents/sessions. + - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та sessions. + - **Nodes (пристрої):** Mac/iOS/Android під’єднуються як периферія і надають локальні інструменти (`system.run`, `canvas`, `camera`). + - **Agents (workers):** окремі «мізки»/workspace для спеціальних ролей (наприклад, «Hetzner ops», «Personal data»). + - **Sub-agents:** запускають фонову роботу від основного агента, коли вам потрібен паралелізм. + - **TUI:** під’єднуйтеся до Gateway і перемикайте agents/sessions. Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). @@ -1682,154 +1681,154 @@ x-i18n: } ``` - Типове значення — `false` (з інтерфейсом). Headless-режим частіше викликає anti-bot перевірки на деяких сайтах. Див. [Браузер](/uk/tools/browser). + Типове значення — `false` (з видимим вікном). Headless з більшою ймовірністю викликає перевірки антиботів на деяких сайтах. Див. [Browser](/uk/tools/browser). - Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, скрапінг, логіни). Основні відмінності: + Headless використовує **той самий рушій Chromium** і підходить для більшості сценаріїв автоматизації (форми, кліки, скрапінг, входи). Основні відмінності: - Немає видимого вікна браузера (використовуйте знімки екрана, якщо вам потрібна візуалізація). - - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, anti-bot). - Наприклад, X/Twitter часто блокує headless-сеанси. + - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, антибот). + Наприклад, X/Twitter часто блокує headless-сесії. - Задайте `browser.executablePath` для вашого бінарного файлу Brave (або будь-якого браузера на основі Chromium) і перезапустіть Gateway. - Див. повні приклади конфігурації в [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). + Установіть `browser.executablePath` на ваш виконуваний файл Brave (або будь-якого браузера на базі Chromium) і перезапустіть Gateway. + Повні приклади конфігурації див. у [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). ## Віддалені gateway і nodes - - Повідомлення Telegram обробляються **gateway**. Gateway запускає agent і - лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент Node: + + Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і + лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes не бачать вхідного трафіку провайдера; вони отримують лише виклики node RPC. + Nodes не бачать вхідний трафік провайдера; вони отримують лише RPC-виклики node. - - Коротка відповідь: **підключіть свій комп’ютер як Node**. Gateway працює в іншому місці, але він може + + Коротка відповідь: **під’єднайте свій комп’ютер як node**. Gateway працює деінде, але може викликати інструменти `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. Типове налаштування: 1. Запустіть Gateway на постійно ввімкненому хості (VPS/домашній сервер). - 2. Додайте хост Gateway і ваш комп’ютер до однієї tailnet. - 3. Переконайтеся, що Gateway WS доступний (прив’язка tailnet або SSH tunnel). - 4. Відкрийте застосунок macOS локально й підключіться в режимі **Remote over SSH** (або напряму через tailnet), - щоб він міг зареєструватися як Node. - 5. Схваліть Node на Gateway: + 2. Підключіть хост Gateway і ваш комп’ютер до однієї tailnet. + 3. Переконайтеся, що Gateway WS доступний (bind tailnet або SSH-тунель). + 4. Відкрийте локально застосунок macOS і під’єднайтеся в режимі **Remote over SSH** (або напряму через tailnet), + щоб він міг зареєструватися як node. + 5. Підтвердьте node на Gateway: ```bash openclaw devices list openclaw devices approve ``` - Окремий TCP bridge не потрібен; nodes підключаються через Gateway WebSocket. + Окремий TCP-міст не потрібен; nodes під’єднуються через Gateway WebSocket. - Нагадування щодо безпеки: підключення macOS Node дозволяє `system.run` на цій машині. Підключайте + Нагадування про безпеку: під’єднання macOS node дозволяє `system.run` на цій машині. Під’єднуйте лише пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). - Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). + Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). - - Перевірте базові речі: + + Перевірте основи: - - Gateway запущено: `openclaw gateway status` + - Gateway запущений: `openclaw gateway status` - Стан Gateway: `openclaw status` - Стан каналів: `openclaw channels status` - Потім перевірте auth і маршрутизацію: + Потім перевірте автентифікацію та маршрутизацію: - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. - - Якщо ви підключаєтеся через SSH tunnel, переконайтеся, що локальний tunnel активний і вказує на правильний порт. - - Переконайтеся, що ваші allowlist (DM або група) містять ваш обліковий запис. + - Якщо ви під’єднуєтеся через SSH-тунель, підтвердьте, що локальний тунель активний і вказує на правильний порт. + - Переконайтеся, що ваші allowlist-и (DM або група) включають ваш обліковий запис. - Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Channels](/uk/channels). + Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). - - Так. Вбудованого мосту "бот-до-бота" немає, але це можна організувати кількома + + Так. Вбудованого моста «бот-до-бота» немає, але це можна налаштувати кількома надійними способами: **Найпростіше:** використовуйте звичайний канал чату, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай Bot A надішле повідомлення Bot B, а тоді Bot B відповість як зазвичай. + Нехай Bot A надсилає повідомлення Bot B, а Bot B потім відповідає як завжди. - **CLI-міст (універсальний):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючись на чат, де слухає інший бот. - Якщо один бот працює на віддаленому VPS, спрямуйте свій CLI на цей віддалений Gateway + **CLI-міст (загальний):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націлюючи його на чат, де інший бот + слухає. Якщо один із ботів працює на віддаленому VPS, спрямуйте ваш CLI на той віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускається з машини, яка може дістатися до цільового Gateway): + Приклад шаблону (запускайте з машини, яка може досягти цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклилися безкінечно (лише згадки, channel - allowlist або правило "не відповідати на повідомлення ботів"). + Порада: додайте запобіжник, щоб два боти не зациклювалися безкінечно (відповідати лише на згадки, allowlist-и + каналів або правило «не відповідати на повідомлення ботів»). - Документація: [Віддалений доступ](/uk/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/uk/tools/agent-send). + Документація: [Віддалений доступ](/uk/gateway/remote), [Agent CLI](/cli/agent), [Надсилання Agent](/uk/tools/agent-send). - - Ні. Один Gateway може хостити кілька agents, кожен із власним workspace, типовими моделями - та маршрутизацією. Це нормальний варіант налаштування, і він значно дешевший і простіший, ніж запуск - окремого VPS для кожного agent. + + Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм workspace, типовими моделями + та маршрутизацією. Це нормальна конфігурація, і вона набагато дешевша й простіша, ніж запускати + один VPS на кожного агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні конфігурації, які ви не хочете ділити. В інших випадках залишайте один Gateway і - використовуйте кілька agents або sub-agents. + різні конфігурації, якими ви не хочете ділитися. В інших випадках тримайте один Gateway і + використовуйте кілька агентів або sub-agents. - - Так — nodes є основним способом доступу до вашого ноутбука з віддаленого Gateway, і вони + + Так — nodes є першокласним способом доступу до вашого ноутбука з віддаленого Gateway, і вони відкривають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким, тож типовий варіант — це постійно ввімкнений хост плюс ваш ноутбук як Node - (підійде невеликий VPS або пристрій класу Raspberry Pi; 4 GB RAM більш ніж достатньо). + легковаговим (невеликий VPS або пристрій класу Raspberry Pi цілком підходить; 4 GB RAM більш ніж достатньо), тому поширене + налаштування — це постійно ввімкнений хост плюс ваш ноутбук як node. - - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристроїв. - - **Безпечніший контроль виконання.** `system.run` обмежується allowlist/схваленнями Node на цьому ноутбуці. + - **Не потрібен вхідний SSH.** Nodes самі під’єднуються до Gateway WebSocket і використовують pairing пристрою. + - **Безпечніший контроль виконання.** `system.run` контролюється allowlist-ами/підтвердженнями node на цьому ноутбуці. - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост Node на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост node на ноутбуці або під’єднуйтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних agent-workflow - та автоматизації пристроїв. + SSH підходить для разового доступу до оболонки, але nodes простіші для постійних робочих процесів агентів і + автоматизації пристроїв. - Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Браузер](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Browser](/uk/tools/browser). - - Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні пристрої, які підключаються - до gateway (nodes на iOS/Android або macOS у "режимі Node" в menubar app). Для headless-хостів Node + + Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви свідомо не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні компоненти, які під’єднуються + до gateway (nodes iOS/Android або «node mode» macOS у застосунку рядка меню). Для безголових node-хостів і керування через CLI див. [Node host CLI](/cli/node). - Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. + Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. Так. - - `config.schema.lookup`: перевірити одне піддерево конфігурації з його неглибоким вузлом схеми, відповідною UI-підказкою та зведеннями безпосередніх дочірніх елементів перед записом + - `config.schema.lookup`: перевірити одне піддерево конфігурації разом із його поверхневим вузлом схеми, відповідною UI-підказкою та зведеннями безпосередніх дочірніх елементів перед записом - `config.get`: отримати поточний знімок + hash - - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); по можливості гаряче перезавантажує, а коли потрібно — перезапускає - - `config.apply`: перевіряє й замінює всю конфігурацію; по можливості гаряче перезавантажує, а коли потрібно — перезапускає - - owner-only runtime tool `gateway` усе одно відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); виконує гаряче перезавантаження, коли це можливо, і перезапуск, коли це потрібно + - `config.apply`: перевірити + замінити повну конфігурацію; виконує гаряче перезавантаження, коли це можливо, і перезапуск, коли це потрібно + - Runtime tool `gateway`, доступний лише власнику, усе одно відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1837,29 +1836,29 @@ x-i18n: } ``` - Це задає ваш workspace і обмежує, хто може активувати бота. + Це задає ваш workspace і обмежує коло тих, хто може запускати бота. - + Мінімальні кроки: - 1. **Встановіть і увійдіть на VPS** + 1. **Установіть + увійдіть на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Встановіть і увійдіть на Mac** + 2. **Установіть + увійдіть на вашому Mac** - Використайте застосунок Tailscale і увійдіть у ту саму tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. - 4. **Використовуйте ім’я хоста tailnet** + - В адміністративній консолі Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. + 4. **Використовуйте hostname tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` - Якщо ви хочете Control UI без SSH, використовуйте Tailscale Serve на VPS: + Якщо ви хочете Control UI без SSH, використайте Tailscale Serve на VPS: ```bash openclaw gateway --tailscale serve @@ -1869,49 +1868,49 @@ x-i18n: - - Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через ту саму кінцеву точку Gateway WS. + + Serve відкриває **Gateway Control UI + WS**. Nodes під’єднуються через той самий endpoint Gateway WS. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS і Mac знаходяться в одній tailnet**. - 2. **Використовуйте застосунок macOS у віддаленому режимі** (ціллю SSH може бути ім’я хоста tailnet). - Застосунок прокине порт Gateway через tunnel і підключиться як Node. - 3. **Схваліть Node** на gateway: + 1. **Переконайтеся, що VPS + Mac знаходяться в одній tailnet**. + 2. **Використовуйте застосунок macOS у режимі Remote** (ціллю SSH може бути hostname tailnet). + Застосунок протунелює порт Gateway і під’єднається як node. + 3. **Підтвердьте node** на gateway: ```bash openclaw devices list openclaw devices approve ``` - Документація: [Протокол Gateway](/uk/gateway/protocol), [Виявлення](/uk/gateway/discovery), [Віддалений режим macOS](/uk/platforms/mac/remote). + Документація: [Протокол Gateway](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [віддалений режим macOS](/uk/platforms/mac/remote). - - Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **Node**. Це залишає один Gateway і дозволяє уникнути дублювання конфігурації. Локальні інструменти Node - наразі доступні лише на macOS, але ми плануємо розширити їх на інші ОС. + + Якщо вам потрібні лише **локальні інструменти** (екран/камера/exec) на другому ноутбуці, додайте його як + **node**. Це зберігає один Gateway і дозволяє уникнути дублювання конфігурації. Локальні node-інструменти + наразі доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. - Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). -## Змінні середовища та завантаження .env +## Env vars і завантаження .env - OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: + OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо), а також додатково завантажує: - - `.env` з поточного робочого каталогу - - глобальний запасний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - `.env` із поточного робочого каталогу + - глобальний резервний `.env` із `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден із `.env`-файлів не перевизначає наявні env vars. + Жоден із файлів `.env` не перевизначає вже наявні env vars. - Ви також можете визначати вбудовані env vars у конфігурації (застосовуються лише якщо їх немає в env процесу): + Ви також можете визначити inline env vars у конфігурації (застосовуються, лише якщо їх немає в env процесу): ```json5 { @@ -1922,14 +1921,14 @@ x-i18n: } ``` - Див. [/environment](/uk/help/environment) для повного порядку пріоритету та джерел. + Повний порядок пріоритетів і джерела див. у [/environment](/uk/help/environment). - - Є два поширені виправлення: + + Два поширені виправлення: - 1. Розмістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли служба не успадковує env вашої оболонки. + 1. Додайте відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої оболонки. 2. Увімкніть імпорт оболонки (зручність за явною згодою): ```json5 @@ -1943,27 +1942,27 @@ x-i18n: } ``` - Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає). Еквіваленти env var: + Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти env vars: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status` повідомляє, чи ввімкнено **імпорт env оболонки**. "Shell env: off" + + `openclaw models status` повідомляє, чи ввімкнено **імпорт env із оболонки**. "Shell env: off" **не** означає, що ваші env vars відсутні — це лише означає, що OpenClaw не завантажуватиме вашу login shell автоматично. - Якщо Gateway працює як служба (launchd/systemd), він не успадковує середовище - вашої оболонки. Виправити можна одним із таких способів: + Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує env + вашої оболонки. Виправити це можна одним із таких способів: - 1. Розмістіть токен у `~/.openclaw/.env`: + 1. Додайте токен у `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт оболонки (`env.shellEnv.enabled: true`). - 3. Або додайте його в блок `env` вашої конфігурації (застосовується лише якщо значення відсутнє). + 2. Або ввімкніть імпорт оболонки (`env.shellEnv.enabled: true`). + 3. Або додайте його в блок `env` вашої конфігурації (застосовується лише за відсутності). Потім перезапустіть gateway і перевірте ще раз: @@ -1971,7 +1970,7 @@ x-i18n: openclaw models status ``` - Токени Copilot читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). + Токени Copilot читаються з `COPILOT_GITHUB_TOKEN` (а також `GH_TOKEN` / `GITHUB_TOKEN`). Див. [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment). @@ -1981,14 +1980,14 @@ x-i18n: - Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сесіями](/uk/concepts/session). + Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Керування сесіями](/uk/concepts/session). - - Сесії можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типове значення **0**). - Задайте додатне значення, щоб увімкнути завершення за неактивністю. Коли це ввімкнено, **наступне** + + Сесії можуть завершуватися після `session.idleMinutes`, але за замовчуванням це **вимкнено** (типове значення **0**). + Установіть додатне значення, щоб увімкнути завершення через неактивність. Коли це ввімкнено, **наступне** повідомлення після періоду неактивності починає новий id сесії для цього ключа чату. - Це не видаляє стенограми — просто починає нову сесію. + Це не видаляє транскрипти — лише починає нову сесію. ```json5 { @@ -2001,27 +2000,27 @@ x-i18n: - Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного координуючого - agent і кількох робочих agents із власними workspaces і моделями. + Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного координатора + й кількох робочих агентів із власними workspace і моделями. - Тим не менш, на це краще дивитися як на **цікавий експеримент**. Це дуже - затратне за токенами й часто менш ефективне, ніж використання одного бота з окремими сесіями. Типова модель, яку - ми уявляємо, — це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей + Втім, найкраще сприймати це як **веселий експеримент**. Це витрачає багато токенів і часто + менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми + бачимо, — це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей бот також може запускати sub-agents за потреби. - Документація: [Маршрутизація multi-agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). + Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). - - Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато - файлів можуть викликати Compaction або обрізання. + + Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або велика кількість + файлів можуть спричинити Compaction або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими задачами, а `/new` — під час зміни тем. - - Зберігайте важливий контекст у workspace і просіть бота знову його прочитати. + - Використовуйте `/compact` перед довгими завданнями, а `/new` — при зміні теми. + - Зберігайте важливий контекст у workspace і просіть бота перечитати його. - Використовуйте sub-agents для довгої або паралельної роботи, щоб основний чат залишався меншим. - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. @@ -2049,12 +2048,12 @@ x-i18n: Примітки: - Onboarding також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Onboarding (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог стану (типово це `~/.openclaw-`). - - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; стирає конфігурацію dev + облікові дані + сесії + workspace). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог state (типово це `~/.openclaw-`). + - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; очищає конфігурацію dev + облікові дані + sessions + workspace). - + Використайте один із цих варіантів: - **Compaction** (зберігає розмову, але підсумовує старіші ходи): @@ -2063,7 +2062,7 @@ x-i18n: /compact ``` - або `/compact `, щоб спрямувати підсумок. + або `/compact `, щоб керувати підсумком. - **Скидання** (новий id сесії для того самого ключа чату): @@ -2082,16 +2081,16 @@ x-i18n: - Це помилка валідації провайдера: модель вивела блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих тредів - або зміни інструмента/схеми). + Це помилка валідації провайдера: модель згенерувала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих thread + або зміни tool/schema). - Виправлення: почніть нову сесію за допомогою `/new` (окремим повідомленням). + Виправлення: почніть нову сесію за допомогою `/new` (окреме повідомлення). - Heartbeat запускається кожні **30m** за замовчуванням (**1h** під час використання OAuth auth). Налаштуйте або вимкніть його: + Heartbeat запускається кожні **30m** за замовчуванням (**1h** при використанні OAuth-автентифікації). Налаштуйте або вимкніть їх: ```json5 { @@ -2106,18 +2105,18 @@ x-i18n: ``` Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки - на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити виклики API. - Якщо файл відсутній, heartbeat усе одно виконується, і модель вирішує, що робити. + на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб зекономити API-виклики. + Якщо файла немає, heartbeat усе одно запускається, і модель вирішує, що робити. - Перевизначення для конкретного agent використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Overrides для конкретного агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - - Ні. OpenClaw працює на **вашому власному обліковому записі**, тож якщо ви є в групі, OpenClaw може її бачити. - За замовчуванням відповіді в групах заблоковано, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + + Ні. OpenClaw працює у **вашому власному обліковому записі**, тож якщо ви перебуваєте в групі, OpenClaw може її бачити. + За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). - Якщо ви хочете, щоб активувати відповіді в групі могли лише **ви**: + Якщо ви хочете, щоб лише **ви** могли запускати відповіді в групі: ```json5 { @@ -2133,7 +2132,7 @@ x-i18n: - Варіант 1 (найшвидший): перегляньте хвіст логів і надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): дивіться логи в реальному часі й надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json @@ -2142,7 +2141,7 @@ x-i18n: Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/додано до allowlist): перелічіть групи з конфігурації: + Варіант 2 (якщо вже налаштовано/додано до allowlist): виведіть список груп із конфігурації: ```bash openclaw directory groups list --channel whatsapp @@ -2156,80 +2155,80 @@ x-i18n: Дві поширені причини: - Увімкнено gating за згадкою (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і цю групу не додано до allowlist. + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до allowlist. - Див. [Групи](/uk/channels/groups) і [Повідомлення в групах](/uk/channels/group-messages). + Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Прямі чати за замовчуванням згортаються до основної сесії. Групи/канали мають власні ключі сесій, а теми Telegram / треди Discord є окремими сесіями. Див. [Групи](/uk/channels/groups) і [Повідомлення в групах](/uk/channels/group-messages). + + Прямі чати за замовчуванням згортаються в основну сесію. Групи/канали мають власні ключі сесій, а теми Telegram / thread-и Discord є окремими сесіями. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але зважайте на таке: + + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але звертайте увагу на: - - **Зростання диска:** sessions + стенограми живуть у `~/.openclaw/agents//sessions/`. - - **Вартість токенів:** більше agents означає більше одночасного використання моделі. - - **Операційні витрати:** auth-профілі, workspaces і маршрутизація каналів для кожного agent окремо. + - **Зростання диска:** sessions + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. + - **Витрати токенів:** більше агентів означає більше одночасного використання моделей. + - **Операційне навантаження:** профілі автентифікації для кожного агента, workspace і маршрутизація каналів. Поради: - - Тримайте один **активний** workspace на agent (`agents.defaults.workspace`). - - Очищуйте старі сесії (видаляйте JSONL або записи сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб виявляти stray workspaces і невідповідності профілів. + - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). + - Очищайте старі sessions (видаляйте JSONL або записи сховища), якщо диск розростається. + - Використовуйте `openclaw doctor`, щоб знаходити зайві workspace і невідповідності профілів. - - Так. Використовуйте **Маршрутизацію Multi-Agent**, щоб запускати кількох ізольованих agents і маршрутизувати вхідні повідомлення за - каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних agents. + + Так. Використовуйте **маршрутизацію Multi-Agent**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. - Доступ до браузера є потужним, але це не "зробити все, що може людина" — anti-bot, CAPTCHA і MFA - усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості - або CDP на машині, яка реально запускає браузер. + Доступ до браузера потужний, але це не «все, що може людина» — антибот-захист, CAPTCHA і MFA + усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості, + або використовуйте CDP на машині, яка фактично запускає браузер. Найкраща практика налаштування: - - Хост Gateway, який завжди ввімкнений (VPS/Mac mini). - - Один agent на роль (прив’язки). - - Канал(и) Slack, прив’язані до цих agents. - - Локальний браузер через Chrome MCP або Node, коли це потрібно. + - Постійно ввімкнений хост Gateway (VPS/Mac mini). + - Один агент на роль (bindings). + - Канал(и) Slack, прив’язані до цих агентів. + - Локальний браузер через Chrome MCP або node, коли це потрібно. Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). + [Browser](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі: типові значення, вибір, псевдоніми, перемикання +## Моделі: значення за замовчуванням, вибір, псевдоніми, перемикання - Типова модель OpenClaw — це те, що ви задаєте як: + Модель OpenClaw за замовчуванням — це те, що ви встановили як: ``` agents.defaults.model.primary ``` - На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного id моделі і лише потім повертається до налаштованого провайдера за замовчуванням як застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого провайдера/моделі замість показу застарілого типового значення від видаленого провайдера. Вам усе одно слід **явно** задавати `provider/model`. + На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку намагається знайти псевдонім, потім — унікальний збіг налаштованого провайдера для цього точного id моделі, і лише після цього повертається до налаштованого провайдера за замовчуванням як до застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw переходить до першої налаштованої пари провайдер/модель замість показу застарілого типового значення від видаленого провайдера. Однак вам усе одно слід **явно** задавати `provider/model`. - **Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. - **Для agents з інструментами або з недовіреним вхідним вмістом:** віддавайте перевагу силі моделі над вартістю. - **Для рутинних/невисокоризикових чатів:** використовуйте дешевші резервні моделі та маршрутизуйте за роллю agent. + **Рекомендовано за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів із увімкненими інструментами або недовіреним вхідним вводом:** ставте силу моделі вище за вартість. + **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента. Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і [Локальні моделі](/uk/gateway/local-models). - Правило великого пальця: використовуйте **найкращу модель, яку можете собі дозволити** для задач із високими ставками, і дешевшу - модель для рутинних чатів або підсумків. Ви можете маршрутизувати моделі для кожного agent окремо й використовувати sub-agents для - паралелізації довгих задач (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і + Емпіричне правило: використовуйте **найкращу модель, яку можете собі дозволити** для важливих завдань, і дешевшу + модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі на рівні агента й використовувати sub-agents для + паралелізації довгих завдань (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і [Sub-agents](/uk/tools/subagents). - Сильне попередження: слабші/надмірно квантизовані моделі вразливіші до prompt + Важливе попередження: слабші / надмірно квантизовані моделі більш уразливі до prompt injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). Більше контексту: [Моделі](/uk/concepts/models). @@ -2241,17 +2240,18 @@ x-i18n: Безпечні варіанти: - - `/model` у чаті (швидко, для сесії) + - `/model` у чаті (швидко, для окремої сесії) - `openclaw models set ...` (оновлює лише конфігурацію моделі) - `openclaw configure --section model` (інтерактивно) - - відредагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` + - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` з частковим об’єктом, якщо тільки ви не хочете замінити всю конфігурацію. - Для RPC-редагувань спочатку перевіряйте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Payload lookup дає вам нормалізований шлях, документацію/обмеження неглибокої схеми та зведення безпосередніх дочірніх елементів + Уникайте `config.apply` з частковим об’єктом, якщо не маєте наміру замінити всю конфігурацію. + Для RPC-редагувань спочатку перевіряйте через `config.schema.lookup` і віддавайте перевагу `config.patch`. + Корисне навантаження lookup дає вам нормалізований шлях, поверхневу документацію/обмеження схеми та зведення безпосередніх дочірніх елементів для часткових оновлень. - Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або знову запустіть `openclaw doctor` для виправлення. + Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. - Документація: [Моделі](/uk/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/uk/gateway/doctor). + Документація: [Моделі](/uk/concepts/models), [Налаштування](/cli/configure), [Конфігурація](/cli/config), [Doctor](/uk/gateway/doctor). @@ -2260,7 +2260,7 @@ x-i18n: Найшвидше налаштування: - 1. Встановіть Ollama з `https://ollama.com/download` + 1. Установіть Ollama з `https://ollama.com/download` 2. Завантажте локальну модель, наприклад `ollama pull gemma4` 3. Якщо ви хочете також хмарні моделі, виконайте `ollama signin` 4. Запустіть `openclaw onboard` і виберіть `Ollama` @@ -2269,12 +2269,12 @@ x-i18n: Примітки: - `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama - - хмарні моделі, як-от `kimi-k2.5:cloud`, не потребують локального завантаження + - хмарні моделі, такі як `kimi-k2.5:cloud`, не потребують локального завантаження - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - Примітка щодо безпеки: менші або сильно квантизовані моделі вразливіші до prompt + Примітка щодо безпеки: менші або сильно квантизовані моделі більш уразливі до prompt injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. - Якщо ви все ж хочете малі моделі, увімкніть sandboxing і строгі allowlist інструментів. + Якщо ви все ж хочете малі моделі, увімкніть sandboxing і суворі allowlist-и інструментів. Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), [Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), @@ -2284,8 +2284,8 @@ x-i18n: - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. - - Перевіряйте поточне runtime-налаштування на кожному gateway через `openclaw models status`. - - Для чутливих до безпеки agents з інструментами використовуйте найсильнішу доступну модель останнього покоління. + - Перевіряйте поточне налаштування runtime на кожному gateway за допомогою `openclaw models status`. + - Для агентів, чутливих до безпеки / з увімкненими інструментами, використовуйте найсильнішу доступну модель останнього покоління. @@ -2303,7 +2303,7 @@ x-i18n: Це вбудовані псевдоніми. Власні псевдоніми можна додати через `agents.defaults.models`. - Ви можете перелічити доступні моделі за допомогою `/model`, `/model list` або `/model status`. + Ви можете переглянути доступні моделі за допомогою `/model`, `/model list` або `/model status`. `/model` (і `/model list`) показує компактний нумерований вибір. Вибір за номером: @@ -2311,17 +2311,17 @@ x-i18n: /model 3 ``` - Ви також можете примусово задати конкретний auth-профіль для провайдера (на рівні сесії): + Ви також можете примусово вибрати певний профіль автентифікації для провайдера (на рівні сесії): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який agent активний, який файл `auth-profiles.json` використовується та який auth-профіль буде спробовано наступним. - Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано наступним. + Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли це доступно. - **Як зняти закріплення профілю, який я задав через @profile?** + **Як прибрати закріплення профілю, який я встановив через @profile?** Повторно виконайте `/model` **без** суфікса `@profile`: @@ -2329,28 +2329,28 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - Якщо ви хочете повернутися до типового значення, виберіть його в `/model` (або надішліть `/model `). - Використовуйте `/model status`, щоб підтвердити, який auth-профіль активний. + Якщо ви хочете повернутися до типового значення, виберіть його через `/model` (або надішліть `/model `). + Використайте `/model status`, щоб підтвердити, який профіль автентифікації активний. - - Так. Задайте одну як типову і перемикайте за потреби: + + Так. Установіть одну як типову і перемикайте за потреби: - - **Швидке перемикання (на рівні сесії):** `/model gpt-5.4` для щоденних задач, `/model openai-codex/gpt-5.4` для кодування з Codex OAuth. - - **Типова + перемикання:** задайте `agents.defaults.model.primary` як `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час кодування (або навпаки). - - **Sub-agents:** маршрутизуйте задачі кодування до sub-agents з іншою типовою моделлю. + - **Швидке перемикання (для окремої сесії):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для кодування з OAuth Codex. + - **Типова + перемикання:** установіть `agents.defaults.model.primary` на `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час кодування (або навпаки). + - **Sub-agents:** маршрутизуйте завдання з кодування до sub-agents з іншою типовою моделлю. Див. [Моделі](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands). - Використовуйте або перемикач для сесії, або типове значення в конфігурації: + Використовуйте або перемикач на рівні сесії, або типове значення в конфігурації: - - **Для сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. - - **Типове значення для моделі:** задайте `agents.defaults.models["openai/gpt-5.4"].params.fastMode` як `true`. - - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.4`, задайте той самий прапорець і там. + - **Для окремої сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. + - **Типове значення для моделі:** установіть `agents.defaults.models["openai/gpt-5.4"].params.fastMode` у `true`. + - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.4`, установіть той самий прапорець і там. Приклад: @@ -2375,15 +2375,15 @@ x-i18n: } ``` - Для OpenAI fast mode відображається в `service_tier = "priority"` у підтримуваних нативних запитах Responses. Сесійне `/fast` має пріоритет над типовими значеннями конфігурації. + Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Значення `/fast` на рівні сесії має вищий пріоритет за типові значення з конфігурації. - Див. [Мислення та fast mode](/uk/tools/thinking) і [Fast mode OpenAI](/uk/providers/openai#openai-fast-mode). + Див. [Thinking і fast mode](/uk/tools/thinking) та [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). - - Якщо задано `agents.defaults.models`, це стає **allowlist** для `/model` і будь-яких - перевизначень на рівні сесії. Вибір моделі, якої немає в цьому списку, повертає: + + Якщо задано `agents.defaults.models`, це стає **allowlist-ом** для `/model` і будь-яких + перевизначень сесії. Вибір моделі, якої немає в цьому списку, повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. @@ -2395,19 +2395,19 @@ x-i18n: - Це означає, що **провайдера не налаштовано** (не знайдено конфігурацію провайдера MiniMax або auth-профіль), - тому модель не вдається розв’язати. + Це означає, що **провайдера не налаштовано** (не знайдено конфігурацію провайдера MiniMax або профіль + автентифікації), тому модель неможливо розв’язати. Контрольний список виправлення: 1. Оновіться до поточного релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що auth MiniMax - існує в env/auth-профілях, щоб можна було вставити відповідний провайдер + 2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax + існує в env/профілях автентифікації, щоб відповідний провайдер міг бути підставлений (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax OAuth для `minimax-portal`). - 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху auth: - `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для - налаштування через API key, або `minimax-portal/MiniMax-M2.7` / + 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху автентифікації: + `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування + через API-ключ, або `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed` для налаштування через OAuth. 4. Виконайте: @@ -2421,9 +2421,9 @@ x-i18n: - - Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **на рівні сесії** за потреби. - Резервні варіанти призначені для **помилок**, а не для "складних задач", тож використовуйте `/model` або окремого agent. + + Так. Використовуйте **MiniMax за замовчуванням** і перемикайте моделі **на рівні сесії** за потреби. + Резервні варіанти призначені для **помилок**, а не для «складних завдань», тому використовуйте `/model` або окремого агента. **Варіант A: перемикання на рівні сесії** @@ -2448,11 +2448,11 @@ x-i18n: /model gpt ``` - **Варіант B: окремі agents** + **Варіант B: окремі агенти** - - Типове значення Agent A: MiniMax - - Типове значення Agent B: OpenAI - - Маршрутизуйте за agent або використовуйте `/agent` для перемикання + - Агент A за замовчуванням: MiniMax + - Агент B за замовчуванням: OpenAI + - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання Документація: [Моделі](/uk/concepts/models), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). @@ -2470,7 +2470,7 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Якщо ви задасте власний псевдонім із тим самим ім’ям, ваше значення матиме пріоритет. + Якщо ви задаєте власний псевдонім із тим самим ім’ям, перемагає ваше значення. @@ -2492,12 +2492,12 @@ x-i18n: } ``` - Тоді `/model sonnet` (або `/`, коли це підтримується) розв’язується в цей id моделі. + Тоді `/model sonnet` (або `/`, де це підтримується) розв’язується в цей ID моделі. - OpenRouter (оплата за токени; багато моделей): + OpenRouter (оплата за токен; багато моделей): ```json5 { @@ -2525,11 +2525,11 @@ x-i18n: } ``` - Якщо ви посилаєтесь на `provider/model`, але потрібний ключ провайдера відсутній, ви отримаєте помилку auth під час виконання (наприклад `No API key found for provider "zai"`). + Якщо ви посилаєтеся на `provider/model`, але потрібний ключ провайдера відсутній, ви отримаєте помилку автентифікації під час runtime (наприклад, `No API key found for provider "zai"`). - **Не знайдено API key для провайдера після додавання нового agent** + **No API key found for provider після додавання нового агента** - Зазвичай це означає, що **новий agent** має порожнє сховище auth. Auth є прив’язаним до agent і + Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація прив’язана до агента і зберігається тут: ``` @@ -2538,10 +2538,10 @@ x-i18n: Варіанти виправлення: - - Виконайте `openclaw agents add ` і налаштуйте auth під час майстра. - - Або скопіюйте `auth-profiles.json` з `agentDir` основного agent до `agentDir` нового agent. + - Виконайте `openclaw agents add ` і налаштуйте автентифікацію під час майстра. + - Або скопіюйте `auth-profiles.json` з `agentDir` основного агента до `agentDir` нового агента. - **Не** використовуйте спільний `agentDir` для кількох agents; це спричиняє колізії auth/сесій. + **Не** використовуйте спільний `agentDir` для кількох агентів; це спричиняє конфлікти автентифікації/сесій. @@ -2552,104 +2552,105 @@ x-i18n: Резервне перемикання відбувається у два етапи: - 1. **Ротація auth-профілів** у межах одного провайдера. - 2. **Резервна модель** до наступної моделі в `agents.defaults.model.fallbacks`. + 1. **Ротація профілю автентифікації** в межах одного провайдера. + 2. **Резервна модель** на наступну модель у `agents.defaults.model.fallbacks`. - Для профілів, що дають збої, застосовуються cooldown (експоненційний backoff), тому OpenClaw може продовжувати відповідати, навіть коли провайдер обмежений rate limit або тимчасово не працює. + Для профілів, що дають збій, застосовуються періоди cooldown (експоненційне збільшення інтервалу), тож OpenClaw може продовжувати відповідати, навіть коли провайдер обмежений rate limit або тимчасово не працює. - Кошик rate limit включає більше, ніж просто відповіді `429`. OpenClaw - також вважає такими, що заслуговують резервного перемикання, повідомлення на кшталт `Too many concurrent requests`, + Категорія rate limit включає більше, ніж просто відповіді `429`. OpenClaw + також вважає такими, що заслуговують на резервне перемикання, повідомлення на кшталт + `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - обмеження вікна використання (`weekly/monthly limit reached`). + ліміти вікна використання (`weekly/monthly limit reached`). - Деякі відповіді, схожі на білінгові, не є `402`, і деякі відповіді HTTP `402` - також залишаються в цьому транзитному кошику. Якщо провайдер повертає - явний білінговий текст на `401` або `403`, OpenClaw усе одно може залишити це - в білінговому напрямку, але специфічні для провайдера текстові збіги залишаються обмеженими - провайдером, якому вони належать (наприклад OpenRouter `Key limit exceeded`). Якщо повідомлення `402` - натомість схоже на повторюване вікно використання або + Деякі відповіді, схожі на платіжні, не мають коду `402`, а деякі HTTP `402` + також залишаються в цій тимчасовій категорії. Якщо провайдер повертає + явний текст про оплату з `401` або `403`, OpenClaw все одно може залишити це + в категорії billing, але matchers тексту, специфічні для провайдера, залишаються обмеженими + тим провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` + натомість виглядає як повторюваний ліміт вікна використання або ліміт витрат organization/workspace (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), OpenClaw трактує це як - `rate_limit`, а не як довготривале відключення через білінг. + `rate_limit`, а не як довготривале вимкнення через billing. - Помилки переповнення контексту — інші: сигнатури на кшталт + Помилки переповнення контексту відрізняються: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` залишаються на шляху Compaction/повторної спроби замість переходу до - резервної моделі. + exceeded` залишаються на шляху Compaction/повторної спроби замість переходу + до резервної моделі. - Загальний текст серверних помилок навмисно вужчий, ніж "усе, де є - unknown/error". OpenClaw вважає такими, що заслуговують резервного перемикання, тимчасові форми в межах провайдера, - як-от Anthropic bare `An unknown error occurred`, OpenRouter bare - `Provider returned error`, помилки stop-reason, як-от `Unhandled stop reason: - error`, JSON-повідомлення `api_error` із тимчасовим серверним текстом + Загальний текст серверних помилок навмисно вужчий, ніж «будь-що з + unknown/error усередині». OpenClaw розглядає як придатні для резервного перемикання тимчасові форми, + прив’язані до провайдера, такі як простий Anthropic `An unknown error occurred`, простий OpenRouter + `Provider returned error`, помилки stop-reason на кшталт `Unhandled stop reason: + error`, JSON-корисні навантаження `api_error` із тимчасовим серверним текстом (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) і помилки зайнятості провайдера, як-от `ModelNotReadyException`, як сигнали timeout/overloaded, - якщо контекст провайдера збігається. + error`) і помилки зайнятості провайдера на кшталт `ModelNotReadyException`, як сигнали + timeout/перевантаження, що заслуговують на резервне перемикання, коли збігається контекст провайдера. Загальний внутрішній текст резервного варіанта на кшталт `LLM request failed with an unknown - error.` лишається консервативним і сам по собі не запускає резервне перемикання моделі. + error.` залишається консервативним і сам по собі не запускає резервне перемикання моделі. - Це означає, що система намагалася використати id auth-профілю `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі auth. + Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. **Контрольний список виправлення:** - - **Підтвердьте, де живуть auth-профілі** (нові та застарілі шляхи) - - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` - - Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) - - **Підтвердьте, що ваша env var завантажується Gateway** - - Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадковувати. Розмістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`. - - **Переконайтеся, що ви редагуєте правильного agent** - - У середовищах multi-agent може бути кілька файлів `auth-profiles.json`. - - **Перевірте стан моделі/auth** - - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі й те, чи автентифіковані провайдери. + - **Перевірте, де зберігаються профілі автентифікації** (нові та застарілі шляхи) + - Поточний шлях: `~/.openclaw/agents//agent/auth-profiles.json` + - Застарілий шлях: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) + - **Переконайтеся, що ваша env var завантажується Gateway** + - Якщо ви встановили `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадковувати. Додайте її в `~/.openclaw/.env` або увімкніть `env.shellEnv`. + - **Переконайтеся, що ви редагуєте правильного агента** + - У конфігураціях multi-agent може бути кілька файлів `auth-profiles.json`. + - **Зробіть швидку перевірку стану моделі/автентифікації** + - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковано провайдерів. **Контрольний список виправлення для "No credentials found for profile anthropic"** - Це означає, що виконання закріплене за auth-профілем Anthropic, але Gateway - не може знайти його у своєму сховищі auth. + Це означає, що запуск закріплений за профілем автентифікації Anthropic, але Gateway + не може знайти його у своєму сховищі автентифікації. - **Використовуйте Claude CLI** - Виконайте `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. - - **Якщо ви хочете використовувати API key** - - Розмістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. - - Очистьте будь-який закріплений порядок, який примушує використовувати відсутній профіль: + - **Якщо ви хочете натомість використовувати API-ключ** + - Додайте `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. + - Очистіть будь-який закріплений порядок, який примусово використовує відсутній профіль: ```bash openclaw models auth order clear --provider anthropic ``` - - **Підтвердьте, що ви запускаєте команди на хості gateway** - - У віддаленому режимі auth-профілі живуть на машині gateway, а не на вашому ноутбуці. + - **Переконайтеся, що ви виконуєте команди на хості gateway** + - У віддаленому режимі профілі автентифікації зберігаються на машині gateway, а не на вашому ноутбуці. - Якщо ваша конфігурація моделі включає Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. + Якщо ваша конфігурація моделі включає Google Gemini як резервний варіант (або ви переключилися на скорочення Gemini), OpenClaw спробує її під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. - Виправлення: або надайте auth Google, або приберіть/уникайте моделей Google в `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувало туди. + Виправлення: або надайте автентифікацію Google, або видаліть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувалося туди. **LLM request rejected: thinking signature required (Google Antigravity)** - Причина: історія сесії містить **thinking-блоки без підписів** (часто через - перерваний/частковий стрім). Google Antigravity вимагає підписів для thinking-блоків. + Причина: історія сесії містить **блоки thinking без сигнатур** (часто через + перерваний/частковий стрим). Google Antigravity вимагає сигнатури для блоків thinking. - Виправлення: OpenClaw тепер видаляє непідписані thinking-блоки для Google Antigravity Claude. Якщо це все одно трапляється, почніть **нову сесію** або задайте `/thinking off` для цього agent. + Виправлення: OpenClaw тепер видаляє непідписані блоки thinking для Google Antigravity Claude. Якщо це все одно з’являється, почніть **нову сесію** або встановіть `/thinking off` для цього агента. -## Auth-профілі: що це таке і як ними керувати +## Профілі автентифікації: що це таке і як ними керувати -Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (OAuth-потоки, зберігання токенів, шаблони multi-account) +Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони для кількох облікових записів) - - Auth-профіль — це іменований запис облікових даних (OAuth або API key), прив’язаний до провайдера. Профілі зберігаються тут: + + Профіль автентифікації — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до провайдера. Профілі зберігаються тут: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2657,64 +2658,64 @@ x-i18n: - - OpenClaw використовує id з префіксом провайдера, наприклад: + + OpenClaw використовує ID з префіксом провайдера, наприклад: - `anthropic:default` (поширено, коли немає email-ідентичності) - `anthropic:` для OAuth-ідентичностей - - власні id, які ви обираєте (наприклад `anthropic:work`) + - власні ID, які ви обираєте (наприклад, `anthropic:work`) - - Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; воно зіставляє id з провайдером/режимом і задає порядок ротації. + + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; воно зіставляє ID з провайдером/режимом і задає порядок ротації. - OpenClaw може тимчасово пропускати профіль, якщо він перебуває у короткому **cooldown** (rate limits/timeouts/auth failures) або в довшому стані **disabled** (billing/insufficient credits). Щоб перевірити це, запустіть `openclaw models status --json` і подивіться `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + OpenClaw може тимчасово пропускати профіль, якщо він перебуває в короткому **cooldown** (rate limits/timeouts/збої автентифікації) або в довшому стані **disabled** (billing/недостатньо кредитів). Щоб перевірити це, виконайте `openclaw models status --json` і подивіться `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Cooldown через rate limit можуть бути прив’язані до моделі. Профіль, який перебуває на cooldown + Cooldown-и через rate limit можуть бути прив’язані до моделі. Профіль, що перебуває в cooldown для однієї моделі, усе ще може бути придатним для сусідньої моделі того самого провайдера, - тоді як білінгові/disabled-вікна все одно блокують увесь профіль. + тоді як вікна billing/disabled усе одно блокують увесь профіль. - Ви також можете задати **перевизначення порядку для кожного agent окремо** (зберігається в `auth-state.json` цього agent) через CLI: + Ви також можете встановити override порядку **для конкретного агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash - # Типово для налаштованого agent за замовчуванням (опустіть --agent) + # За замовчуванням використовується налаштований типовий агент (опустіть --agent) openclaw models auth order get --provider anthropic # Зафіксувати ротацію на одному профілі (пробувати лише його) openclaw models auth order set --provider anthropic anthropic:default - # Або задати явний порядок (резервне перемикання в межах провайдера) + # Або задати явний порядок (резервний варіант у межах провайдера) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Очистити перевизначення (повернутися до config auth.order / round-robin) + # Очистити override (повернутися до конфігурації auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` - Щоб націлитися на конкретного agent: + Щоб націлитися на конкретного агента: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Щоб перевірити, що насправді пробуватиметься, використовуйте: + Щоб перевірити, що саме буде реально спробовано, використовуйте: ```bash openclaw models status --probe ``` - Якщо збережений профіль опущено з явного порядку, probe повідомляє - `excluded_by_auth_order` для цього профілю замість мовчазної спроби використати його. + Якщо збережений профіль пропущено в явному порядку, probe повідомляє + `excluded_by_auth_order` для цього профілю замість тихої спроби. - + OpenClaw підтримує обидва варіанти: - **OAuth** часто використовує доступ за підпискою (де це застосовно). - - **API keys** використовують білінг pay-per-token. + - **API-ключі** використовують тарифікацію за токен. - Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API keys. + Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі. @@ -2728,24 +2729,24 @@ x-i18n: Пріоритет: ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > типове значення 18789 ``` - - Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). RPC probe — це фактичне підключення CLI до gateway WebSocket і виклик `status`. + + Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). А connectivity probe — це фактичне підключення CLI до gateway WebSocket. - Використовуйте `openclaw gateway status` і довіряйте цим рядкам: + Використовуйте `openclaw gateway status` і довіряйте таким рядкам: - - `Probe target:` (URL, який probe реально використав) + - `Probe target:` (URL, яку probe фактично використав) - `Listening:` (що реально прив’язано до порту) - `Last gateway error:` (поширена першопричина, коли процес живий, але порт не слухає) - Ви редагуєте один файл конфігурації, тоді як служба використовує інший (часто це невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + Ви редагуєте один файл конфігурації, а сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). Виправлення: @@ -2753,19 +2754,19 @@ x-i18n: openclaw gateway install --force ``` - Запустіть це з тим самим `--profile` / середовищем, яке ви хочете, щоб використовувала служба. + Запустіть це з того самого `--profile` / середовища, яке ви хочете використовувати для сервісу. - OpenClaw забезпечує runtime-блокування, одразу прив’язуючи прослуховувач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується помилкою `EADDRINUSE`, він викидає `GatewayLockError`, що означає, що інший екземпляр уже слухає. + OpenClaw примусово застосовує блокування runtime, негайно прив’язуючи слухача WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується з `EADDRINUSE`, система викидає `GatewayLockError`, що означає: інший екземпляр уже слухає. - Виправлення: зупиніть інший екземпляр, звільніть порт або запускайте з `openclaw gateway --port `. + Виправлення: зупиніть інший екземпляр, звільніть порт або запустіть з `openclaw gateway --port `. - - Задайте `gateway.mode: "remote"` і вкажіть віддалену URL-адресу WebSocket, за потреби з віддаленими обліковими даними спільного секрету: + + Установіть `gateway.mode: "remote"` і вкажіть віддалену URL WebSocket, за потреби з віддаленими обліковими даними за спільним секретом: ```json5 { @@ -2782,92 +2783,92 @@ x-i18n: Примітки: - - `openclaw gateway` запускається лише тоді, коли `gateway.mode` має значення `local` (або ви передаєте прапорець перевизначення). - - Застосунок macOS стежить за файлом конфігурації і перемикає режими в реальному часі, коли ці значення змінюються. - - `gateway.remote.token` / `.password` — це лише облікові дані клієнта для remote; самі по собі вони не вмикають локальний auth gateway. + - `openclaw gateway` запускається лише коли `gateway.mode` дорівнює `local` (або якщо ви передали прапорець перевизначення). + - Застосунок macOS відстежує файл конфігурації й перемикає режими в реальному часі, коли ці значення змінюються. + - `gateway.remote.token` / `.password` — це лише облікові дані клієнта для віддаленого доступу; вони самі по собі не вмикають автентифікацію локального gateway. - - Ваш шлях auth gateway і метод auth в UI не збігаються. + + Ваш шлях автентифікації gateway і метод автентифікації UI не збігаються. Факти (з коду): - - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраної URL-адреси gateway, тож оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого зберігання токена в localStorage. - - При `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені scopes, збережені разом із токеном пристрою. Явні виклики `deviceToken` / явні `scopes` все одно зберігають свій запитаний набір scopes замість успадкування кешованих scopes. - - Поза цим шляхом повторної спроби порядок auth для підключення такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. - - Перевірки scope bootstrap-токена мають префікси ролей. Вбудований allowlist операторів bootstrap задовольняє лише запити операторів; Node або інші ролі, не пов’язані з оператором, усе одно потребують scopes під власним префіксом ролі. + - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера і вибраної URL gateway, тож оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого зберігання токена в localStorage. + - У разі `AUTH_TOKEN_MISMATCH` довірені клієнти можуть зробити одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені scopes, збережені разом із токеном пристрою. Явні виклики `deviceToken` / явні `scopes` усе ще зберігають свій запитаний набір scope замість успадкування кешованих. + - Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. + - Перевірки scope для bootstrap-токена мають префікс ролі. Вбудований allowlist bootstrap-оператора задовольняє лише запити оператора; node або інші ролі, що не є оператором, усе одно потребують scopes під власним префіксом ролі. Виправлення: - - Найшвидше: `openclaw dashboard` (виводить + копіює URL-адресу dashboard, намагається відкрити; показує SSH-підказку, якщо середовище без голови). + - Найшвидше: `openclaw dashboard` (виводить + копіює URL dashboard, намагається відкрити; показує підказку SSH, якщо режим headless). - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. - - Якщо remote — спочатку підніміть tunnel: `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`, а потім вставте відповідний секрет у налаштуваннях Control UI. - - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL-адресу Serve, а не сиру loopback/tailnet URL-адресу, яка обходить заголовки identity Tailscale. - - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований reverse proxy з awareness identity не на loopback, а не через loopback proxy на тому ж хості чи пряму URL-адресу gateway. - - Якщо невідповідність зберігається після однієї повторної спроби, перевипустіть/повторно схваліть paired токен пристрою: + - Якщо віддалено, спочатку створіть тунель: `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`, а потім вставте відповідний секрет у налаштуваннях Control UI. + - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL Serve, а не сиру URL loopback/tailnet, яка обходить заголовки ідентичності Tailscale. + - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований identity-aware proxy не в loopback, а не через loopback proxy на тому ж хості чи сиру URL gateway. + - Якщо невідповідність залишається після однієї повторної спроби, перевипустіть/заново схваліть парний токен пристрою: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - Якщо виклик rotate каже, що йому відмовлено, перевірте дві речі: - - paired-device sessions можуть перевипускати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` - - явні значення `--scope` не можуть перевищувати поточні scopes оператора викликача - - Усе ще застрягли? Запустіть `openclaw status --all` і дотримуйтеся [Усунення несправностей](/uk/gateway/troubleshooting). Див. [Dashboard](/web/dashboard) для деталей auth. + - Якщо цей виклик rotate каже, що його відхилено, перевірте дві речі: + - сесії парних пристроїв можуть перевипускати лише **власний** пристрій, якщо лише вони не мають також `operator.admin` + - явні значення `--scope` не можуть перевищувати поточні operator scopes викликача + - Все ще застрягли? Виконайте `openclaw status --all` і скористайтеся [Усуненням несправностей](/uk/gateway/troubleshooting). Деталі автентифікації див. в [Dashboard](/web/dashboard). - - Прив’язка `tailnet` вибирає Tailscale IP з мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнений), прив’язуватися немає до чого. + + Bind `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 може запускати кілька каналів обміну повідомленнями та agents. Використовуйте кілька Gateway лише тоді, коли вам потрібна надлишковість (наприклад rescue bot) або жорстка ізоляція. + Зазвичай ні — один Gateway може обслуговувати кілька каналів обміну повідомленнями й агентів. Використовуйте кілька Gateway лише тоді, коли вам потрібне резервування (наприклад, rescue bot) або жорстка ізоляція. - Так, але ви маєте ізолювати: + Так, але потрібно ізолювати: - `OPENCLAW_CONFIG_PATH` (конфігурація для кожного екземпляра) - - `OPENCLAW_STATE_DIR` (стан для кожного екземпляра) + - `OPENCLAW_STATE_DIR` (state для кожного екземпляра) - `agents.defaults.workspace` (ізоляція workspace) - `gateway.port` (унікальні порти) Швидке налаштування (рекомендовано): - Використовуйте `openclaw --profile ...` для кожного екземпляра (автоматично створює `~/.openclaw-`). - - Задайте унікальний `gateway.port` у конфігурації кожного профілю (або передавайте `--port` для ручних запусків). - - Встановіть службу для конкретного профілю: `openclaw --profile gateway install`. + - Установіть унікальний `gateway.port` у конфігурації кожного профілю (або передавайте `--port` для ручних запусків). + - Установіть сервіс для кожного профілю: `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`. Якщо він отримує щось інше, він закриває з’єднання - з **code 1008** (порушення політики). + буде кадром `connect`. Якщо він отримує щось інше, то закриває з’єднання + з **кодом 1008** (порушення політики). Поширені причини: - - Ви відкрили URL-адресу **HTTP** у браузері (`http://...`) замість WS-клієнта. + - Ви відкрили URL **HTTP** у браузері (`http://...`) замість клієнта WS. - Ви використали неправильний порт або шлях. - - Proxy або tunnel зрізав заголовки auth або надіслав не-Gateway запит. + - Proxy або тунель видалив заголовки автентифікації чи надіслав запит, що не належить до Gateway. Швидкі виправлення: - 1. Використовуйте URL-адресу WS: `ws://:18789` (або `wss://...`, якщо це HTTPS). - 2. Не відкривайте WS-порт у звичайній вкладці браузера. - 3. Якщо auth увімкнено, включіть токен/пароль у кадр `connect`. + 1. Використовуйте URL WS: `ws://:18789` (або `wss://...`, якщо HTTPS). + 2. Не відкривайте порт WS у звичайній вкладці браузера. + 3. Якщо автентифікація ввімкнена, додайте токен/пароль у кадр `connect`. - Якщо ви використовуєте CLI або TUI, URL-адреса має виглядати так: + Якщо ви використовуєте CLI або TUI, URL має виглядати так: ``` openclaw tui --url ws://:18789 --token @@ -2888,25 +2889,25 @@ 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 ``` - Логи служби/supervisor (коли gateway запускається через launchd/systemd): + Логи сервісу/supervisor (коли gateway працює через launchd/systemd): - 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). - + Використовуйте допоміжні команди gateway: ```bash @@ -2914,7 +2915,7 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути собі порт. Див. [Gateway](/uk/gateway). + Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може звільнити порт. Див. [Gateway](/uk/gateway). @@ -2931,13 +2932,13 @@ x-i18n: openclaw gateway restart ``` - Якщо ви ніколи не встановлювали службу, запустіть її на передньому плані: + Якщо ви ніколи не встановлювали сервіс, запустіть його на передньому плані: ```bash openclaw gateway run ``` - **2) Нативна Windows (не рекомендується):** Gateway працює безпосередньо у Windows. + **2) Нативний Windows (не рекомендується):** Gateway працює безпосередньо у Windows. Відкрийте PowerShell і виконайте: @@ -2946,17 +2947,17 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте його вручну (без служби), використовуйте: + Якщо ви запускаєте його вручну (без сервісу), використовуйте: ```powershell openclaw gateway run ``` - Документація: [Windows (WSL2)](/uk/platforms/windows), [Інструкція зі служби Gateway](/uk/gateway). + Документація: [Windows (WSL2)](/uk/platforms/windows), [Інструкція з експлуатації сервісу Gateway](/uk/gateway). - + Почніть із швидкої перевірки стану: ```bash @@ -2968,26 +2969,26 @@ x-i18n: Поширені причини: - - Auth моделі не завантажено на **хості gateway** (перевірте `models status`). + - Автентифікація моделі не завантажена на **хості gateway** (перевірте `models status`). - Pairing/allowlist каналу блокує відповіді (перевірте конфігурацію каналу + логи). - WebChat/Dashboard відкрито без правильного токена. - Якщо ви працюєте віддалено, переконайтеся, що tunnel/Tailscale-з’єднання активне і що + Якщо ви працюєте віддалено, переконайтеся, що тунель/Tailscale-з’єднання активне і Gateway WebSocket доступний. - Документація: [Channels](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). + Документація: [Канали](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). - + Зазвичай це означає, що UI втратив з’єднання WebSocket. Перевірте: - 1. Чи запущений Gateway? `openclaw gateway status` - 2. Чи справний Gateway? `openclaw status` - 3. Чи має UI правильний токен? `openclaw dashboard` - 4. Якщо remote — чи активне з’єднання tunnel/Tailscale? + 1. Чи працює Gateway? `openclaw gateway status` + 2. Чи Gateway справний? `openclaw status` + 3. Чи UI має правильний токен? `openclaw dashboard` + 4. Якщо віддалено, чи активне тунельне/Tailscale-з’єднання? - Потім перегляньте хвіст логів: + Потім перегляньте логи в реальному часі: ```bash openclaw logs --follow @@ -2997,8 +2998,8 @@ x-i18n: - - Почніть з логів і стану каналу: + + Почніть з логів і статусу каналу: ```bash openclaw channels status @@ -3007,8 +3008,8 @@ x-i18n: Потім зіставте помилку: - - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато записів. OpenClaw уже обрізає їх до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно треба прибрати. Зменште кількість Plugin/skill/custom-команд або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволений і DNS працює для `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато пунктів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі пункти меню все одно потрібно прибрати. Зменште кількість plugin/skill/custom команд або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або схожі мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволений і DNS працює для `api.telegram.org`. Якщо Gateway віддалений, переконайтеся, що ви дивитеся логи на хості Gateway. @@ -3017,7 +3018,7 @@ x-i18n: - Спочатку переконайтеся, що Gateway доступний і agent може виконуватися: + Спочатку переконайтеся, що Gateway доступний і агент може працювати: ```bash openclaw status @@ -3026,44 +3027,44 @@ x-i18n: ``` У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чат-каналі, - переконайтеся, що доставку ввімкнено (`/deliver on`). + переконайтеся, що доставку увімкнено (`/deliver on`). Документація: [TUI](/web/tui), [Slash commands](/uk/tools/slash-commands). - Якщо ви встановили службу: + Якщо ви встановили сервіс: ```bash openclaw gateway stop openclaw gateway start ``` - Це зупиняє/запускає **керовану службу** (launchd на macOS, systemd на Linux). + Це зупиняє/запускає **сервіс під наглядом** (launchd на macOS, systemd на Linux). Використовуйте це, коли Gateway працює у фоновому режимі як демон. - Якщо ви запускаєте у foreground, зупиніть через Ctrl-C, потім: + Якщо ви запускаєте його на передньому плані, зупиніть через Ctrl-C, а потім: ```bash openclaw gateway run ``` - Документація: [Інструкція зі служби Gateway](/uk/gateway). + Документація: [Інструкція з експлуатації сервісу Gateway](/uk/gateway). - - `openclaw gateway restart`: перезапускає **фонову службу** (launchd/systemd). - - `openclaw gateway`: запускає gateway **у foreground** для цієї сесії термінала. + - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). + - `openclaw gateway`: запускає gateway **на передньому плані** для цієї сесії термінала. - Якщо ви встановили службу, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли - хочете одноразовий запуск у foreground. + Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли + вам потрібен одноразовий запуск на передньому плані. - - Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте лог-файл на помилки auth каналу, маршрутизації моделі та RPC. + + Запустіть Gateway з `--verbose`, щоб отримати докладніший вивід у консолі. Потім перевірте файл логів на наявність помилок автентифікації каналу, маршрутизації моделей і RPC. @@ -3071,7 +3072,7 @@ x-i18n: - Вихідні вкладення від agent мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Agent send](/uk/tools/agent-send). + Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування assistant OpenClaw](/uk/start/openclaw) і [Надсилання Agent](/uk/tools/agent-send). Надсилання через CLI: @@ -3081,10 +3082,10 @@ x-i18n: Також перевірте: - - Цільовий канал підтримує вихідні медіа й не заблокований allowlist. - - Файл не перевищує обмежень розміру провайдера (зображення змінюють розмір до максимуму 2048px). - - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store та файлами, перевіреними sandbox. - - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які agent уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, усе одно блокуються. + - Цільовий канал підтримує вихідні медіа й не заблокований allowlist-ами. + - Файл не перевищує обмеження розміру провайдера (зображення масштабуються максимум до 2048px). + - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними sandbox. + - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і Office-документи). Звичайний текст і файли, схожі на секрети, усе одно блокуються. Див. [Зображення](/uk/nodes/images). @@ -3095,108 +3096,108 @@ x-i18n: - Ставтеся до вхідних DM як до недовіреного вмісту. Типові значення спроєктовано так, щоб зменшити ризик: + Ставтеся до вхідних DM як до недовіреного вводу. Значення за замовчуванням спроєктовано для зменшення ризику: - - Типова поведінка на каналах, що підтримують DM, — це **pairing**: - - Невідомі відправники отримують код pairing; бот не обробляє їхнє повідомлення. - - Схвалення: `openclaw pairing approve --channel [--account ] ` - - Кількість очікуваних запитів обмежено до **3 на канал**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. - - Публічне відкриття DM потребує явної згоди (`dmPolicy: "open"` і allowlist `"*"`). + - Типова поведінка на каналах із підтримкою DM — **pairing**: + - Невідомі відправники отримують код pairing; бот не обробляє їх повідомлення. + - Підтвердження: `openclaw pairing approve --channel [--account ] ` + - Кількість очікуваних запитів обмежена **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. + - Відкриття DM для всіх вимагає явної згоди (`dmPolicy: "open"` і allowlist `"*"`). Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. - Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може написати боту в DM. + Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може писати боту в DM. Якщо ваш помічник читає зовнішній вміст (web search/fetch, сторінки браузера, email, документи, вкладення, вставлені логи), цей вміст може містити інструкції, які намагаються - перехопити контроль над моделлю. Це може статися, навіть якщо **ви є єдиним відправником**. + перехопити керування моделлю. Це може статися навіть якщо **ви єдиний відправник**. - Найбільший ризик виникає, коли ввімкнені інструменти: модель можна змусити - витягувати контекст або викликати інструменти від вашого імені. Зменшуйте радіус ураження таким чином: + Найбільший ризик виникає, коли ввімкнені інструменти: модель можна обманом змусити + ексфільтрувати контекст або викликати інструменти від вашого імені. Зменшуйте радіус ураження: - - використовуйте "reader" agent лише для читання або без інструментів, щоб підсумовувати недовірений вміст - - тримайте `web_search` / `web_fetch` / `browser` вимкненими для agents з увімкненими інструментами - - ставтеся до декодованого тексту файлів/документів також як до недовіреного: OpenResponses - `input_file` і витягування з медіавкладень обгортають витягнутий текст - явними маркерами меж зовнішнього вмісту замість передачі сирого тексту файла - - використовуйте sandboxing і суворі allowlist інструментів + - використовуйте агента-"читача" лише для читання або без інструментів, щоб підсумовувати недовірений вміст + - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів із увімкненими інструментами + - також ставтеся до декодованого тексту файлів/документів як до недовіреного: OpenResponses + `input_file` і витяг тексту з медіавкладень обгортають витягнутий текст + явними маркерами меж зовнішнього вмісту замість передавання сирого тексту файла + - використовуйте sandboxing і суворі allowlist-и інструментів Деталі: [Безпека](/uk/gateway/security). - - Так, для більшості налаштувань. Ізоляція бота в окремих облікових записах і номерах телефону + + Так, для більшості конфігурацій. Ізоляція бота окремими обліковими записами й номерами телефону зменшує радіус ураження, якщо щось піде не так. Це також полегшує ротацію - облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. + облікових даних або відкликання доступу без впливу на ваші особисті акаунти. - Починайте з малого. Надавайте доступ лише до тих інструментів і облікових записів, які вам справді потрібні, і розширюйте - пізніше, якщо знадобиться. + Починайте з малого. Надавайте доступ лише до тих інструментів і акаунтів, які вам справді потрібні, і розширюйте + пізніше за потреби. Документація: [Безпека](/uk/gateway/security), [Pairing](/uk/channels/pairing). - + Ми **не** рекомендуємо повну автономність над вашими особистими повідомленнями. Найбезпечніший шаблон: - Тримайте DM у режимі **pairing** або в жорсткому allowlist. - - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він писав від вашого імені. - - Нехай він створює чернетку, а потім **схвалюйте перед надсиланням**. + - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені. + - Нехай він створює чернетку, а ви **затверджуйте перед надсиланням**. - Якщо хочете експериментувати, робіть це на виділеному обліковому записі та тримайте його ізольованим. Див. + Якщо ви хочете поекспериментувати, робіть це на окремому акаунті й тримайте його ізольованим. Див. [Безпека](/uk/gateway/security). - - Так, **якщо** agent лише для чату і вхідні дані довірені. Менші рівні - більш схильні до перехоплення інструкцій, тому уникайте їх для agents з увімкненими інструментами - або при читанні недовіреного вмісту. Якщо вам усе ж потрібна менша модель, жорстко обмежте - інструменти й запускайте всередині sandbox. Див. [Безпека](/uk/gateway/security). + + Так, **якщо** агент працює лише в чаті й вхідні дані є довіреними. Менші рівні + більш схильні до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами + або під час читання недовіреного вмісту. Якщо вам все ж потрібна менша модель, жорстко обмежте + інструменти й запускайте все в sandbox. Див. [Безпека](/uk/gateway/security). - Коди pairing надсилаються **лише** тоді, коли невідомий відправник пише боту і + Коди pairing надсилаються **лише** коли невідомий відправник пише боту, і `dmPolicy: "pairing"` увімкнено. Сам по собі `/start` не генерує код. - Перевірте запити в очікуванні: + Перевірте запити, що очікують: ```bash openclaw pairing list telegram ``` - Якщо ви хочете негайний доступ, додайте свій id відправника в allowlist або задайте `dmPolicy: "open"` - для цього облікового запису. + Якщо вам потрібен негайний доступ, додайте свій sender id до allowlist або встановіть `dmPolicy: "open"` + для цього акаунта. - - Ні. Типова політика DM у WhatsApp — **pairing**. Невідомі відправники отримують лише код pairing, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які ви ініціюєте. + + Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише код pairing, а їх повідомлення **не обробляються**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які запускаєте ви. - Схвалити pairing: + Підтвердіть pairing за допомогою: ```bash openclaw pairing approve whatsapp ``` - Перелічити запити в очікуванні: + Переглянути запити, що очікують: ```bash openclaw pairing list whatsapp ``` - Запит номера телефону в майстрі: він використовується для налаштування вашого **allowlist/owner**, щоб дозволити ваші власні DM. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і увімкніть `channels.whatsapp.selfChatMode`. + Запит номера телефону в майстрі: він використовується для встановлення вашого **allowlist/owner**, щоб ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. -## Команди чату, переривання задач і "він не зупиняється" +## Команди чату, переривання завдань і "воно не зупиняється" - + Більшість внутрішніх або інструментальних повідомлень з’являються лише тоді, коли для цієї сесії ввімкнено **verbose**, **trace** або **reasoning**. Виправлення в чаті, де ви це бачите: @@ -3207,16 +3208,16 @@ x-i18n: /reasoning off ``` - Якщо все ще надто шумно, перевірте налаштування сесії в Control UI і встановіть verbose - у значення **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, встановленим - у `on` у конфігурації. + Якщо все одно занадто шумно, перевірте налаштування сесії в Control UI і встановіть verbose + на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, встановленим + на `on` у конфігурації. - Документація: [Thinking and verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). + Документація: [Thinking і verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). - - Надішліть будь-яке з цього **окремим повідомленням** (без слеша): + + Надішліть будь-що з цього **як окреме повідомлення** (без скісної риски): ``` stop @@ -3242,7 +3243,7 @@ x-i18n: Це тригери переривання (не slash commands). - Для фонових процесів (з інструмента exec) ви можете попросити agent виконати: + Для фонових процесів (з інструмента exec) ви можете попросити агента виконати: ``` process action:kill sessionId:XXX @@ -3250,15 +3251,15 @@ x-i18n: Огляд slash commands: див. [Slash commands](/uk/tools/slash-commands). - Більшість команд треба надсилати як **окреме** повідомлення, яке починається з `/`, але кілька скорочень (як-от `/status`) також працюють inline для відправників з allowlist. + Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад, `/status`) також працюють inline для відправників з allowlist. - OpenClaw блокує повідомлення **між різними провайдерами** за замовчуванням. Якщо виклик інструмента прив’язаний + За замовчуванням OpenClaw блокує повідомлення **між різними провайдерами**. Якщо виклик tool прив’язаний до Telegram, він не надсилатиме в Discord, якщо ви явно цього не дозволите. - Увімкніть міжпровайдерні повідомлення для agent: + Увімкніть міжпровайдерний обмін повідомленнями для агента: ```json5 { @@ -3278,15 +3279,15 @@ x-i18n: - Режим черги керує тим, як нові повідомлення взаємодіють із поточним виконанням. Використовуйте `/queue`, щоб змінити режими: + Режим черги керує тим, як нові повідомлення взаємодіють із виконанням, що вже триває. Використовуйте `/queue` для зміни режимів: - - `steer` - нові повідомлення перенаправляють поточну задачу + - `steer` - нові повідомлення перенаправляють поточне завдання - `followup` - повідомлення виконуються по одному - - `collect` - пакетування повідомлень і одна відповідь (типово) - - `steer-backlog` - перенаправити зараз, потім обробити накопичене - - `interrupt` - перервати поточне виконання і почати заново + - `collect` - пакетне збирання повідомлень і одна відповідь (типово) + - `steer-backlog` - перенаправлення зараз, потім обробка черги + - `interrupt` - перервати поточне виконання й почати заново - Ви можете додавати параметри на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. + Ви можете додавати опції на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. @@ -3294,8 +3295,8 @@ x-i18n: ## Різне - - В OpenClaw облікові дані та вибір моделі — це окремі речі. Задання `ANTHROPIC_API_KEY` (або збереження ключа Anthropic API в auth-профілях) вмикає автентифікацію, але фактична типова модель — це те, що ви налаштували в `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` для agent, який виконується. + + В 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` для агента, який виконується. diff --git a/docs/uk/help/troubleshooting.md b/docs/uk/help/troubleshooting.md index 7526b5d7e..dd88828ae 100644 --- a/docs/uk/help/troubleshooting.md +++ b/docs/uk/help/troubleshooting.md @@ -1,25 +1,25 @@ --- read_when: - OpenClaw не працює, і вам потрібен найшвидший шлях до виправлення - - Вам потрібен процес первинної діагностики, перш ніж переходити до детальних інструкцій + - Ви хочете пройти потік тріажу, перш ніж занурюватися в детальні інструкції щодо усунення проблем summary: Центр усунення несправностей OpenClaw за симптомами title: Загальне усунення несправностей x-i18n: - generated_at: "2026-04-10T20:41:24Z" + generated_at: "2026-04-20T06:31:12Z" model: gpt-5.4 provider: openai - source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a + source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88 source_path: help/troubleshooting.md workflow: 15 --- # Усунення несправностей -Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку діагностики. +Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку тріажу. ## Перші 60 секунд -Запустіть цю точну послідовність команд у вказаному порядку: +Виконайте цю точну послідовність команд по порядку: ```bash openclaw status @@ -31,19 +31,17 @@ openclaw channels status --probe openclaw logs --follow ``` -Хороший результат в одному рядку: +Ознаки коректного виводу в одному рядку: -- `openclaw status` → показує налаштовані канали та відсутність очевидних помилок автентифікації. -- `openclaw status --all` → повний звіт наявний і ним можна поділитися. -- `openclaw gateway probe` → очікувана ціль gateway доступна (`Reachable: yes`). `RPC: limited - missing scope: operator.read` означає погіршену діагностику, а не збій підключення. -- `openclaw gateway status` → `Runtime: running` і `RPC probe: ok`. -- `openclaw doctor` → немає блокувальних помилок конфігурації або сервісу. -- `openclaw channels status --probe` → доступний gateway повертає поточний - стан транспорту для кожного облікового запису разом із результатами probe/audit, такими як `works` або `audit ok`; якщо - gateway недоступний, команда переходить до зведень лише за конфігурацією. +- `openclaw status` → показує налаштовані канали й відсутність очевидних помилок автентифікації. +- `openclaw status --all` → повний звіт присутній і ним можна поділитися. +- `openclaw gateway probe` → очікуваний Gateway призначення доступний (`Reachable: yes`). `Capability: ...` показує, який рівень автентифікації змогла підтвердити перевірка, а `Read probe: limited - missing scope: operator.read` означає погіршену діагностику, а не збій з’єднання. +- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` і правдоподібний рядок `Capability: ...`. Використовуйте `--require-rpc`, якщо вам також потрібне підтвердження RPC з доступом на читання. +- `openclaw doctor` → немає блокувальних помилок конфігурації/сервісу. +- `openclaw channels status --probe` → доступний Gateway повертає поточний стан транспорту для кожного облікового запису разом із результатами перевірки/аудиту, наприклад `works` або `audit ok`; якщо Gateway недоступний, команда повертається до зведень лише за конфігурацією. - `openclaw logs --follow` → стабільна активність, без повторюваних фатальних помилок. -## Anthropic long context 429 +## 429 для довгого контексту Anthropic Якщо ви бачите: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`, @@ -51,29 +49,29 @@ openclaw logs --follow ## Локальний OpenAI-compatible бекенд працює напряму, але не працює в OpenClaw -Якщо ваш локальний або самостійно розміщений `/v1` бекенд відповідає на малі прямі -перевірки `/v1/chat/completions`, але завершується помилкою в `openclaw infer model run` або під час звичайних +Якщо ваш локальний або self-hosted бекенд `/v1` відповідає на малі прямі перевірки +`/v1/chat/completions`, але завершується помилкою на `openclaw infer model run` або під час звичайних ходів агента: -1. Якщо помилка згадує, що `messages[].content` очікує рядок, встановіть +1. Якщо в помилці згадується, що `messages[].content` очікує рядок, установіть `models.providers..models[].compat.requiresStringContent: true`. -2. Якщо бекенд усе ще не працює лише під час ходів агента OpenClaw, встановіть +2. Якщо бекенд і далі дає збій лише під час ходів агента OpenClaw, установіть `models.providers..models[].compat.supportsTools: false` і повторіть спробу. -3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw призводять до збою - бекенда, розглядайте решту проблеми як обмеження моделі/сервера на стороні джерела - і перейдіть до детальної інструкції: +3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw аварійно завершують + бекенд, вважайте решту проблеми обмеженням моделі/сервера на боці вищого рівня і + продовжуйте в детальній інструкції: [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/uk/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -## Не вдається встановити плагін через відсутні openclaw extensions +## Не вдається встановити Plugin через відсутні openclaw extensions -Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет плагіна +Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет Plugin використовує стару структуру, яку OpenClaw більше не приймає. -Виправлення в пакеті плагіна: +Виправлення в пакеті Plugin: 1. Додайте `openclaw.extensions` до `package.json`. 2. Спрямуйте записи на зібрані runtime-файли (зазвичай `./dist/index.js`). -3. Повторно опублікуйте плагін і знову виконайте `openclaw plugins install `. +3. Повторно опублікуйте Plugin і знову виконайте `openclaw plugins install `. Приклад: @@ -87,7 +85,7 @@ openclaw logs --follow } ``` -Довідка: [Архітектура плагінів](/uk/plugins/architecture) +Довідка: [Архітектура Plugin](/uk/plugins/architecture) ## Дерево рішень @@ -96,19 +94,19 @@ flowchart TD A[OpenClaw не працює] --> B{Що ламається першим} B --> C[Немає відповідей] B --> D[Dashboard або Control UI не підключається] - B --> E[Gateway не запускається або сервіс не запущено] + B --> E[Gateway не запускається або сервіс не працює] B --> F[Канал підключається, але повідомлення не проходять] - B --> G[Cron або heartbeat не спрацював чи не доставив] - B --> H[Node з'єднано, але інструмент camera canvas screen exec не працює] - B --> I[Не працює інструмент браузера] + B --> G[Cron або Heartbeat не спрацював чи не доставив повідомлення] + B --> H[Node спарено, але не працює інструмент camera canvas screen exec] + B --> I[Не працює інструмент browser] - C --> C1[/Розділ Немає відповідей/] - D --> D1[/Розділ Control UI/] - E --> E1[/Розділ Gateway/] - F --> F1[/Розділ Потік каналу/] - G --> G1[/Розділ Автоматизація/] - H --> H1[/Розділ Інструменти node/] - I --> I1[/Розділ Браузер/] + C --> C1[/Розділ «Немає відповідей»/] + D --> D1[/Розділ «Control UI»/] + E --> E1[/Розділ «Gateway»/] + F --> F1[/Розділ «Потік каналу»/] + G --> G1[/Розділ «Автоматизація»/] + H --> H1[/Розділ «Інструменти Node»/] + I --> I1[/Розділ «Browser»/] ``` @@ -121,18 +119,19 @@ flowchart TD openclaw logs --follow ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable` або `admin-capable` - Ваш канал показує підключений транспорт і, де це підтримується, `works` або `audit ok` у `channels status --probe` - - Відправника показано як схваленого (або політика DM є відкритою/зі списком дозволених) + - Відправника показано як схваленого (або політика DM відкрита/є в allowlist) - Поширені сигнатури в логах: + Типові сигнатури в журналах: - - `drop guild message (mention required` → обмеження за згадкою заблокувало повідомлення в Discord. - - `pairing request` → відправник не схвалений і очікує схвалення DM pairing. - - `blocked` / `allowlist` у логах каналу → відправник, кімната або група відфільтровані. + - `drop guild message (mention required` → обробку повідомлення було заблоковано вимогою згадки в Discord. + - `pairing request` → відправника не схвалено, він очікує на схвалення спарювання в DM. + - `blocked` / `allowlist` у журналах каналу → відправника, кімнату або групу відфільтровано. Детальні сторінки: @@ -151,27 +150,23 @@ flowchart TD openclaw channels status --probe ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - `Dashboard: http://...` показано в `openclaw gateway status` - - `RPC probe: ok` - - У логах немає циклу автентифікації + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable` або `admin-capable` + - У журналах немає циклу автентифікації - Поширені сигнатури в логах: + Типові сигнатури в журналах: - `device identity required` → HTTP/незахищений контекст не може завершити автентифікацію пристрою. - - `origin not allowed` → `Origin` браузера не дозволений для цілі gateway у Control UI. - - `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → одна повторна спроба з довіреним токеном пристрою може виконуватися автоматично. - - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із прив’язаним - токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають - свій запитаний набір scope. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого - `{scope, ip}` серіалізуються до того, як limiter фіксує збій, тож - друга одночасна невдала повторна спроба вже може показати `retry later`. - - `too many failed authentication attempts (retry later)` з браузерного origin localhost → повторні - невдалі спроби з того самого `Origin` тимчасово блокуються; інший origin localhost використовує окремий bucket. - - повторювані `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий токен прив’язаного пристрою. - - `gateway connect failed:` → UI націлений на неправильний URL/порт або gateway недоступний. + - `origin not allowed` → `Origin` браузера не дозволений для Gateway призначення Control UI. + - `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → автоматично може відбутися одна повторна спроба з довіреним токеном пристрою. + - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний ними набір scope. + - На асинхронному шляху Tailscale Serve для Control UI невдалі спроби для одного й того ж `{scope, ip}` серіалізуються до того, як лімітер зафіксує збій, тому друга одночасна хибна повторна спроба вже може показувати `retry later`. + - `too many failed authentication attempts (retry later)` з браузерного localhost-origin → повторні невдалі спроби з того самого `Origin` тимчасово блокуються; інший localhost-origin використовує окремий bucket. + - повторювані `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий спарений токен пристрою. + - `gateway connect failed:` → UI націлено на неправильний URL/порт або Gateway недоступний. Детальні сторінки: @@ -181,7 +176,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -190,16 +185,17 @@ flowchart TD openclaw channels status --probe ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - `Service: ... (loaded)` - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable` або `admin-capable` - Поширені сигнатури в логах: + Типові сигнатури в журналах: - - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим gateway є remote, або у файлі конфігурації відсутня позначка локального режиму, і його слід відновити. - - `refusing to bind gateway ... without auth` → прив’язування не до loopback без дійсного шляху автентифікації gateway (токен/пароль або trusted-proxy, якщо налаштовано). + - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим Gateway встановлено як remote, або у файлі конфігурації відсутня позначка local-mode і його слід виправити. + - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації Gateway (token/password або trusted-proxy, де налаштовано). - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнято. Детальні сторінки: @@ -219,16 +215,16 @@ flowchart TD openclaw channels status --probe ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - Транспорт каналу підключений. - Перевірки pairing/allowlist проходять. - - Згадки виявляються там, де це потрібно. + - Згадки визначаються там, де вони обов’язкові. - Поширені сигнатури в логах: + Типові сигнатури в журналах: - - `mention required` → обмеження за згадкою в групі заблокувало обробку. - - `pairing` / `pending` → відправник DM ще не схвалений. + - `mention required` → обробку заблоковано вимогою згадки в групі. + - `pairing` / `pending` → відправника DM ще не схвалено. - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → проблема з токеном дозволів каналу. Детальні сторінки: @@ -238,7 +234,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -248,21 +244,21 @@ flowchart TD openclaw logs --follow ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - - `cron.status` показує, що його ввімкнено, і вказує наступне пробудження. + - `cron.status` показує, що його ввімкнено, і вказує час наступного пробудження. - `cron runs` показує нещодавні записи `ok`. - - Heartbeat увімкнено, і він не поза активними годинами. + - Heartbeat увімкнено й він не поза межами активних годин. - Поширені сигнатури в логах: + Типові сигнатури в журналах: - - `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. + - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. - `heartbeat skipped` з `reason=quiet-hours` → поза налаштованими активними годинами. - - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній каркас або лише заголовки. - - `heartbeat skipped` з `reason=no-tasks-due` → режим завдань `HEARTBEAT.md` активний, але жоден із інтервалів завдань ще не настав. - - `heartbeat skipped` з `reason=alerts-disabled` → усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені). - - `requests-in-flight` → основна лінія зайнята; пробудження heartbeat було відкладено. - - `unknown accountId` → цільовий обліковий запис доставки heartbeat не існує. + - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній/header-only каркас. + - `heartbeat skipped` з `reason=no-tasks-due` → увімкнено режим завдань `HEARTBEAT.md`, але час для жодного з інтервалів завдань ще не настав. + - `heartbeat skipped` з `reason=alerts-disabled` → усю видимість Heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені). + - `requests-in-flight` → основна смуга зайнята; пробудження Heartbeat було відкладено. + - `unknown accountId` → цільовий account доставки Heartbeat не існує. Детальні сторінки: @@ -272,7 +268,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -281,18 +277,18 @@ flowchart TD openclaw logs --follow ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - - Node вказано як підключений і прив’язаний для ролі `node`. - - Для команди, яку ви викликаєте, наявна capability. - - Для інструмента надано потрібний стан дозволів. + - Node показано як підключений і спарений для ролі `node`. + - Для команди, яку ви викликаєте, існує Capability. + - Для інструмента надано стан дозволу. - Поширені сигнатури в логах: + Типові сигнатури в журналах: - - `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок node на передній план. - - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено або його бракує. - - `SYSTEM_RUN_DENIED: approval required` → схвалення exec очікує підтвердження. - - `SYSTEM_RUN_DENIED: allowlist miss` → команда відсутня у списку дозволених для exec. + - `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок Node на передній план. + - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено/він відсутній. + - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. + - `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist для exec. Детальні сторінки: @@ -302,7 +298,7 @@ flowchart TD - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -312,14 +308,14 @@ flowchart TD Що змінилося: - - Якщо `tools.exec.host` не задано, значенням за замовчуванням є `auto`. - - `host=auto` розв’язується в `sandbox`, коли активне sandbox runtime, і в `gateway` у протилежному разі. - - `host=auto` відповідає лише за маршрутизацію; поведінка "YOLO" без запиту зумовлюється `security=full` разом із `ask=off` на gateway/node. - - У `gateway` і `node` незадане `tools.exec.security` за замовчуванням має значення `full`. - - Незадане `tools.exec.ask` за замовчуванням має значення `off`. - - Результат: якщо ви бачите схвалення, якийсь локальний для хоста або для сеансу policy посилив exec порівняно з поточними значеннями за замовчуванням. + - Якщо `tools.exec.host` не встановлено, значенням за замовчуванням є `auto`. + - `host=auto` визначається як `sandbox`, коли активне sandbox runtime, і як `gateway` в іншому разі. + - `host=auto` впливає лише на маршрутизацію; поведінка "YOLO" без запитів походить від `security=full` разом із `ask=off` на gateway/node. + - Для `gateway` і `node`, якщо `tools.exec.security` не встановлено, значенням за замовчуванням є `full`. + - Якщо `tools.exec.ask` не встановлено, значенням за замовчуванням є `off`. + - Результат: якщо ви бачите запити на схвалення, значить якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням. - Відновити поточну типову поведінку без схвалення: + Відновіть поточну поведінку без схвалень за замовчуванням: ```bash openclaw config set tools.exec.host gateway @@ -330,15 +326,15 @@ flowchart TD Безпечніші альтернативи: - - Встановіть лише `tools.exec.host=gateway`, якщо вам потрібна просто стабільна маршрутизація хоста. - - Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо хочете виконання на хості, але все ще бажаєте перевірку у випадках промаху по allowlist. - - Увімкніть режим sandbox, якщо хочете, щоб `host=auto` знову розв’язувався в `sandbox`. + - Установіть лише `tools.exec.host=gateway`, якщо вам потрібна просто стабільна маршрутизація хоста. + - Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо хочете exec на хості, але все одно хочете перевірку для промахів повз allowlist. + - Увімкніть sandbox mode, якщо хочете, щоб `host=auto` знову визначався як `sandbox`. - Поширені сигнатури в логах: + Типові сигнатури в журналах: - `Approval required.` → команда очікує на `/approve ...`. - - `SYSTEM_RUN_DENIED: approval required` → очікує схвалення для node-host exec. - - `exec host=sandbox requires a sandbox runtime for this session` → неявно або явно вибрано sandbox, але режим sandbox вимкнено. + - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec на вузлі-хості. + - `exec host=sandbox requires a sandbox runtime for this session` → неявний/явний вибір sandbox, але sandbox mode вимкнено. Детальні сторінки: @@ -348,7 +344,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -357,22 +353,22 @@ flowchart TD openclaw doctor ``` - Хороший результат виглядає так: + Коректний вивід виглядає так: - - Статус браузера показує `running: true` і вибраний браузер/профіль. + - Статус browser показує `running: true` і вибраний browser/profile. - `openclaw` запускається, або `user` може бачити локальні вкладки Chrome. - Поширені сигнатури в логах: + Типові сигнатури в журналах: - - `unknown command "browser"` або `unknown command 'browser'` → задано `plugins.allow`, і воно не містить `browser`. - - `Failed to start Chrome CDP on port` → не вдалося запустити локальний Chrome CDP на порту. - - `browser.executablePath not found` → указаний шлях до виконуваного файла неправильний. - - `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему. - - `browser.cdpUrl has invalid port` → налаштований URL CDP має неправильний або неприпустимий порт. - - `No Chrome tabs found for profile="user"` → у профілі приєднання Chrome MCP немає відкритих локальних вкладок Chrome. + - `unknown command "browser"` або `unknown command 'browser'` → встановлено `plugins.allow`, і воно не містить `browser`. + - `Failed to start Chrome CDP on port` → не вдалося запустити локальний browser Chrome. + - `browser.executablePath not found` → налаштований шлях до бінарного файла неправильний. + - `browser.cdpUrl must be http(s) or ws(s)` → налаштований CDP URL використовує непідтримувану схему. + - `browser.cdpUrl has invalid port` → налаштований CDP URL має неправильний або неприпустимий порт. + - `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. - `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з цього хоста. - - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має живої цілі CDP. - - застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активний сеанс керування й скинути стан емуляції без перезапуску gateway. + - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має активної цілі CDP. + - застарілі перевизначення viewport / dark-mode / locale / offline на профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію й скинути стан емуляції без перезапуску gateway. Детальні сторінки: @@ -388,7 +384,7 @@ flowchart TD ## Пов’язане - [FAQ](/uk/help/faq) — поширені запитання -- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з gateway -- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану та виправлення +- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з Gateway +- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану й виправлення - [Усунення несправностей каналів](/uk/channels/troubleshooting) — проблеми з підключенням каналів -- [Усунення несправностей автоматизації](/uk/automation/cron-jobs#troubleshooting) — проблеми з cron і heartbeat +- [Усунення несправностей автоматизації](/uk/automation/cron-jobs#troubleshooting) — проблеми з Cron і Heartbeat