diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index 57423465c..4da6a688d 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -2,32 +2,32 @@ read_when: - Перше налаштування OpenClaw - Пошук поширених шаблонів конфігурації - - Перехід до конкретних розділів конфігурації + - Перехід до певних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-21T21:40:53Z" + generated_at: "2026-04-22T21:30:54Z" model: gpt-5.4 provider: openai - source_hash: c627ccf9f17087e0b71663fe3086d637aeaa8cd1d6d34d816bfcbc0f0cc6f07c + source_hash: 36162008b66dcaaac6d51882f20d74aebd9b637bfddde00395cdfbd5721e3d20 source_path: gateway/configuration.md workflow: 15 --- # Конфігурація -OpenClaw читає необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. +OpenClaw зчитує необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Поширені причини додати конфігурацію: - Підключити канали та керувати тим, хто може надсилати повідомлення боту -- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks) +- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, хуки) - Налаштувати сесії, медіа, мережу або UI -Перегляньте [повний довідник](/uk/gateway/configuration-reference) для всіх доступних полів. +Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля. -**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання. +**Вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з готовими конфігураціями для копіювання. ## Мінімальна конфігурація @@ -45,8 +45,8 @@ OpenClaw читає необов’язкову конфігурацію ```bash - openclaw onboard # full onboarding flow - openclaw configure # config wizard + openclaw onboard # повний процес початкового налаштування + openclaw configure # майстер конфігурації ``` @@ -57,12 +57,12 @@ OpenClaw читає необов’язкову конфігурацію - Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використайте вкладку **Config**. - Control UI відображає форму на основі актуальної схеми конфігурації, включно з - метаданими документації полів `title` / `description`, а також схемами Plugin і каналів, - коли вони доступні, із редактором **Raw JSON** як запасним варіантом. Для UI - з деталізацією та інших інструментів Gateway також надає `config.schema.lookup` для - отримання одного вузла схеми, обмеженого шляхом, разом із короткими зведеннями безпосередніх дочірніх елементів. + Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і скористайтеся вкладкою **Config**. + Control UI відображає форму на основі актуальної схеми конфігурації, включно з метаданими документації полів + `title` / `description`, а також схемами Plugin і каналів, коли + вони доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих + UI та інших інструментів gateway також надає `config.schema.lookup`, щоб + отримати один вузол схеми для заданого шляху разом із підсумками безпосередніх дочірніх елементів. Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). @@ -72,29 +72,29 @@ OpenClaw читає необов’язкову конфігурацію -OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. +OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema. Примітки щодо інструментів схеми: - `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI і валідація конфігурації. -- Вважайте цей вивід схеми канонічним машинозчитуваним контрактом для +- Вважайте цей вивід схеми канонічним машиночитаним контрактом для `openclaw.json`; цей огляд і довідник конфігурації його узагальнюють. -- Значення полів `title` і `description` переносяться до виводу схеми для - редакторів і інструментів побудови форм. -- Вкладені об’єкти, шаблони (`*`) і елементи масивів (`[]`) успадковують ті самі - метадані документації там, де є відповідна документація поля. -- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані - документації, тож варіанти union/intersection зберігають однакові підказки для полів. +- Значення полів `title` і `description` переносяться у вивід схеми для + редакторів та інструментів форм. +- Вкладені об’єкти, шаблони з wildcard (`*`) і елементи масиву (`[]`) успадковують ті самі + метадані документації, якщо для відповідного поля є документація. +- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі + метадані документації, тож варіанти union/intersection зберігають ті самі підказки для полів. - `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження - та подібні поля валідації), відповідними метаданими UI-підказок і короткими зведеннями + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі + та подібні поля валідації), відповідними метаданими підказок UI і стислими описами безпосередніх дочірніх елементів для інструментів деталізації. - Схеми Plugin/каналів під час виконання об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розбіжності між артефактами базової конфігурації, - видимими в документації, і поточною поверхнею схеми. +- `pnpm config:docs:check` виявляє розбіжності між артефактами базової конфігурації для документації + і поточною поверхнею схеми. Коли валідація не проходить: @@ -103,21 +103,25 @@ OpenClaw приймає лише конфігурації, які повніст - Запустіть `openclaw doctor`, щоб побачити точні проблеми - Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway також зберігає довірену останню відому коректну копію після успішного запуску. Якщо -`openclaw.json` згодом буде змінено поза OpenClaw і він більше не проходитиме валідацію, під час запуску -та гарячого перезавантаження пошкоджений файл буде збережено як `.clobbered.*` зі штампом часу, -відновлено останню відому коректну копію та записано помітне попередження з причиною відновлення. -Під час наступного ходу головного агента він також отримає попередження про системну подію з повідомленням, що -конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої відомої коректної -копії відбувається після запуску з успішною валідацією і після прийнятих гарячих перезавантажень, включно з -записами конфігурації, виконаними OpenClaw, якщо хеш збереженого файлу все ще відповідає прийнятому -запису. Оновлення пропускається, якщо кандидат містить замасковані заповнювачі секретів +Gateway також зберігає довірену останню відому справну копію після успішного запуску. Якщо +`openclaw.json` пізніше буде змінено поза OpenClaw і він більше не проходитиме валідацію, під час запуску +та гарячого перезавантаження зіпсований файл буде збережено як позначений часовою міткою знімок `.clobbered.*`, +відновлено останню відому справну копію та записано помітне попередження з причиною відновлення. +Якщо перед інакше коректною JSON-конфігурацією випадково додано рядок статусу/журналу, +під час запуску gateway і виконання `openclaw doctor --fix` цей префікс можна видалити, +зберегти забруднений файл як `.clobbered.*` і продовжити роботу з відновленим +JSON. +Наступний хід основного агента також отримує попередження системної події про те, що +конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої відомої справної копії +відбувається після валідованого запуску та після прийнятих гарячих перезавантажень, включно з +записами конфігурації, виконаними самим OpenClaw, якщо хеш збереженого файлу все ще збігається з прийнятим +записом. Оновлення пропускається, якщо кандидат містить замасковані заповнювачі секретів на кшталт `***` або скорочені значення токенів. ## Поширені завдання - + Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу для кроків налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` @@ -131,7 +135,7 @@ Gateway також зберігає довірену останню відому - [iMessage](/uk/channels/imessage) — `channels.imessage` - [Mattermost](/uk/channels/mattermost) — `channels.mattermost` - Усі канали мають спільний шаблон політики приватних повідомлень: + Усі канали використовують однаковий шаблон політики DM: ```json5 { @@ -148,8 +152,8 @@ Gateway також зберігає довірену останню відому - - Укажіть основну модель і необов’язкові резервні варіанти: + + Задайте основну модель і необов’язкові резервні варіанти: ```json5 { @@ -168,30 +172,30 @@ Gateway також зберігає довірену останню відому } ``` - - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. + - `agents.defaults.models` визначає каталог моделей і виконує роль allowlist для `/model`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. - - Див. [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації та поведінки резервних моделей. - - Для користувацьких/self-hosted провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням масштабу зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. + - Див. [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервного перемикання. + - Для користувацьких/self-hosted provider див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. - - Доступ до приватних повідомлень керується окремо для кожного каналу через `dmPolicy`: + + Доступ до DM контролюється окремо для кожного каналу через `dmPolicy`: - `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження - - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow) - - `"open"`: дозволити всі вхідні приватні повідомлення (потребує `allowFrom: ["*"]`) - - `"disabled"`: ігнорувати всі приватні повідомлення + - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища дозволів після сполучення) + - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) + - `"disabled"`: ігнорувати всі DM - Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. + Для груп використовуйте `groupPolicy` + `groupAllowFrom` або специфічні для каналу allowlist. Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для деталей по кожному каналу. - - Для повідомлень у групах типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: + + Повідомлення в групах типово **вимагають згадки**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -213,15 +217,15 @@ Gateway також зберігає довірену останню відому } ``` - - **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) - - **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns` + - **Metadata mentions**: нативні @-згадки (tap-to-mention у WhatsApp, @bot у Telegram тощо) + - **Text patterns**: безпечні regex-шаблони в `mentionPatterns` - Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень по каналах і режиму self-chat. - - Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте конкретних - агентів через `agents.list[].skills`: + + Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте + конкретних агентів через `agents.list[].skills`: ```json5 { @@ -238,16 +242,16 @@ Gateway також зберігає довірену останню відому } ``` - - Не вказуйте `agents.defaults.skills`, щоб Skills за замовчуванням не були обмежені. + - Не вказуйте `agents.defaults.skills`, якщо за замовчуванням Skills не мають бути обмежені. - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. - - Установіть `agents.list[].skills: []`, щоб не було жодних Skills. - - Див. [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і - [довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). + - Встановіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills. + - Див. [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і + [Довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). - - Керуйте тим, наскільки активно gateway перезапускає канали, які виглядають застарілими: + + Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають неактивними: ```json5 { @@ -269,14 +273,14 @@ Gateway також зберігає довірену останню відому } ``` - - Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски моніторингу стану. + - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану. - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального монітора. - - Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. + - Див. [Health Checks](/uk/gateway/health) для операційної діагностики та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - + Сесії керують безперервністю розмови та ізоляцією: ```json5 @@ -297,15 +301,15 @@ Gateway також зберігає довірену останню відому } ``` - - `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` + - `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Див. [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання. + - Див. [Керування сесіями](/uk/concepts/session) щодо області дії, зв’язків ідентичностей і політики надсилання. - Див. [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. - - Запускайте сесії агента в ізольованих sandbox-середовищах виконання: + + Запускайте сесії агентів в ізольованих середовищах sandbox: ```json5 { @@ -322,14 +326,14 @@ Gateway також зберігає довірену останню відому Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. + Див. [Ізоляція](/uk/gateway/sandboxing) для повного посібника і [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. - - Relay-backed push налаштовується в `openclaw.json`. + + Push через relay налаштовується в `openclaw.json`. - Установіть це в конфігурації gateway: + Вкажіть це в конфігурації gateway: ```json5 { @@ -347,7 +351,7 @@ Gateway також зберігає довірену останню відому } ``` - Еквівалент для CLI: + Еквівалент у CLI: ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com @@ -355,35 +359,35 @@ Gateway також зберігає довірену останню відому Що це робить: - - Дозволяє gateway надсилати `push.test`, імпульси пробудження та пробудження для повторного підключення через зовнішній relay. - - Використовує право надсилання, прив’язане до реєстрації, яке пересилає спарений застосунок iOS. Gateway не потрібен relay-токен на рівні всього розгортання. - - Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою було спарено застосунок iOS, тому інший gateway не зможе повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційно поширюваних збірок, які зареєструвалися через relay. - - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до одного й того ж розгортання relay. + - Дозволяє gateway надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній relay. + - Використовує дозвіл на надсилання в межах реєстрації, який пересилається спареним застосунком iOS. Gateway не потребує relay-токена для всього розгортання. + - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою було спарено застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямих APNs. Надсилання через relay застосовується лише до офіційно поширюваних збірок, що зареєстровані через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. - Наскрізний потік: + Наскрізний процес: 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. - 3. Спарте застосунок iOS із gateway і дозвольте підключитися як сесії Node, так і сесії оператора. - 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` до спареного gateway. - 5. Gateway зберігає relay handle і право надсилання, а потім використовує їх для `push.test`, імпульсів пробудження та пробуджень для повторного підключення. + 3. Спарте застосунок iOS з gateway і дочекайтеся підключення обох сесій: Node та операторської. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay на спарений gateway. + 5. Gateway зберігає дескриптор relay і дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для повторного підключення. Операційні примітки: - - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. - - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свій кешований relay-registration замість повторного використання старого relay origin. + - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway. + - Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює свій кешований запис реєстрації relay замість повторного використання старого джерела relay. Примітка щодо сумісності: - - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` лишається винятком для розробки лише для loopback; не зберігайте HTTP URL relay у конфігурації. + - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` все ще працюють як тимчасові перевизначення через env. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається запасним варіантом для розробки лише в loopback; не зберігайте HTTP URL relay у конфігурації. - Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного потоку та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. + Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. - + ```json5 { agents: { @@ -404,7 +408,7 @@ Gateway також зберігає довірену останню відому - + ```json5 { cron: { @@ -419,14 +423,14 @@ Gateway також зберігає довірену останню відому } ``` - - `sessionRetention`: видаляти завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). - - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. + - `sessionRetention`: очищає завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: очищає `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI. - - Увімкніть HTTP-ендпойнти Webhook на Gateway: + + Увімкніть HTTP-ендпоїнти Webhook на Gateway: ```json5 { @@ -450,20 +454,20 @@ Gateway також зберігає довірену останню відому ``` Примітка щодо безпеки: - - Розглядайте весь вміст payload hook/Webhook як недовірений ввід. - - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. - - `hooks.path` не може бути `/`; використовуйте для вхідних Webhook окремий підшлях, наприклад `/hooks`. - - Залишайте прапори обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо тільки не виконуєте вузькоспрямоване налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які можуть вибирати викликаючі сторони. + - Увесь вміст payload hook/webhook слід вважати недовіреним введенням. + - Використовуйте окремий `hooks.token`; не використовуйте спільний токен Gateway повторно. + - Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. + - `hooks.path` не може бути `/`; використовуйте для вхідних webhook окремий підшлях, наприклад `/hooks`. + - Не вмикайте прапорці обходу небезпечного вмісту (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити вибір ключів сесії з боку викликача. - Для агентів, керованих hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де це можливо). - Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mapping і інтеграції Gmail. + Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів зіставлення та інтеграції Gmail. - - Запускайте кілька ізольованих агентів з окремими робочими просторами та сесіями: + + Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями: ```json5 { @@ -480,12 +484,12 @@ Gateway також зберігає довірену останню відому } ``` - Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил binding і профілів доступу для кожного агента. + Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил прив’язки та профілів доступу для кожного агента. - - Використовуйте `$include` для організації великих конфігурацій: + + Використовуйте `$include`, щоб упорядковувати великі конфігурації: ```json5 // ~/.openclaw/openclaw.json @@ -498,41 +502,41 @@ Gateway також зберігає довірену останню відому } ``` - - **Один файл**: замінює об’єкт, у якому міститься - - **Масив файлів**: об’єднується глибоким злиттям у вказаному порядку (пізніший має пріоритет) - - **Сусідні ключі**: об’єднуються після include (перевизначають включені значення) - - **Вкладені include**: підтримуються до 10 рівнів вкладеності - - **Відносні шляхи**: обчислюються відносно файла, що включає - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include + - **Один файл**: замінює об’єкт, що містить його + - **Масив файлів**: об’єднується deep-merge за порядком (пізніші мають пріоритет) + - **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення) + - **Вкладені includes**: підтримуються до 10 рівнів вкладеності + - **Відносні шляхи**: обчислюються відносно файлу, що включає + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору та циклічних includes ## Гаряче перезавантаження конфігурації -Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості параметрів ручний перезапуск не потрібен. +Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. -Прямі редагування файла вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, -поки завершиться тимчасовий запис/перейменування файла редактором, читає фінальний файл і відхиляє -некоректні зовнішні редагування, відновлюючи останню відому коректну конфігурацію. Записи конфігурації, -виконані самим OpenClaw, проходять ту саму перевірку схемою перед записом; руйнівні перезаписи, -наприклад видалення `gateway.mode` або зменшення файла більш ніж удвічі, відхиляються +Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, +поки вщухне тимчасовий запис/перейменування з боку редактора, читає остаточний файл і відхиляє +некоректні зовнішні редагування, відновлюючи останню відому справну конфігурацію. Записи конфігурації, +виконані самим OpenClaw, проходять ту саму перевірку схеми перед записом; руйнівні перезаписи, +наприклад видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються і зберігаються як `.rejected.*` для перевірки. -Якщо ви бачите `Config auto-restored from last-known-good` або -`config reload restored last-known-good config` у логах, перевірте відповідний -файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте -`openclaw config validate`. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) +Якщо ви бачите в журналах `Config auto-restored from last-known-good` або +`config reload restored last-known-good config`, перевірте відповідний файл +`.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте +`openclaw config validate`. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) для контрольного списку відновлення. ### Режими перезавантаження | Режим | Поведінка | | ---------------------- | ---------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Миттєво застосовує безпечні зміни. Автоматично перезапускає для критичних змін. | -| **`hot`** | Застосовує лише безпечні зміни без перезапуску. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. | -| **`restart`** | Перезапускає Gateway після будь-якої зміни конфігурації, безпечної чи ні. | -| **`off`** | Вимикає відстеження файла. Зміни набудуть чинності під час наступного ручного перезапуску. | +| **`hybrid`** (типово) | Безпечно застосовує зміни гарячим способом миттєво. Автоматично перезапускається для критичних змін. | +| **`hot`** | Гарячим способом застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. | +| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | +| **`off`** | Вимикає відстеження файлу. Зміни набудуть чинності під час наступного ручного перезапуску. | ```json5 { @@ -542,46 +546,46 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично } ``` -### Що застосовується без перезапуску, а що потребує перезапуску +### Що застосовується гарячим способом, а що потребує перезапуску -Більшість полів застосовуються без перезапуску й без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. +Більшість полів застосовуються гарячим способом без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. -| Категорія | Поля | Потрібен перезапуск? | -| ------------------- | ----------------------------------------------------------------- | -------------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали Plugin | Ні | -| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | -| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сесії та повідомлення | `session`, `messages` | Ні | -| Інструменти та медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | -| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | -| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | -| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | +| Категорія | Поля | Потрібен перезапуск? | +| ------------------ | ----------------------------------------------------------------- | -------------------- | +| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали Plugin | Ні | +| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | +| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | +| Сесії та повідомлення | `session`, `messages` | Ні | +| Інструменти та медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | +| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | +| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | +| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` є винятками — їхня зміна **не** спричиняє перезапуск. +`gateway.reload` і `gateway.remote` є винятками — їх зміна **не** спричиняє перезапуск. ## Config RPC (програмні оновлення) -RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. +RPC керувальної площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження частоти: **3 запити за 60 секунд** для кожної пари `deviceId+clientIp`. Якщо ліміт перевищено, RPC повертає `UNAVAILABLE` з `retryAfterMs`. -Безпечний/типовий потік: +Безпечний/типовий процес: -- `config.schema.lookup`: переглянути одне піддерево конфігурації, обмежене шляхом, із неглибоким - вузлом схеми, відповідними метаданими підказок і короткими зведеннями безпосередніх дочірніх елементів -- `config.get`: отримати поточний snapshot + hash -- `config.patch`: бажаний шлях часткового оновлення +- `config.schema.lookup`: перевірити одне піддерево конфігурації для заданого шляху з неглибоким + вузлом схеми, відповідними метаданими підказок і стислими описами безпосередніх дочірніх елементів +- `config.get`: отримати поточний знімок + хеш +- `config.patch`: бажаний шлях для часткового оновлення - `config.apply`: лише повна заміна конфігурації - `update.run`: явне самооновлення + перезапуск -Якщо ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup` -потім `config.patch`. +Якщо ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup`, +а потім `config.patch`. - Перевіряє + записує повну конфігурацію та перезапускає Gateway за один крок. + Перевіряє, записує повну конфігурацію та перезапускає Gateway за один крок. `config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів. @@ -590,12 +594,12 @@ RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) м Параметри: - `raw` (string) — payload JSON5 для всієї конфігурації - - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язково, якщо конфігурація існує) - - `sessionKey` (необов’язково) — ключ сесії для ping пробудження після перезапуску - - `note` (необов’язково) — примітка для restart sentinel + - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) + - `sessionKey` (необов’язково) — ключ сесії для сигналу пробудження після перезапуску + - `note` (необов’язково) — примітка для маркера перезапуску - `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундна пауза. + Запити на перезапуск об’єднуються, якщо один уже очікує або виконується, а між циклами перезапуску діє 30-секундна пауза. ```bash openclaw gateway call config.get --params '{}' # capture payload.hash @@ -617,9 +621,9 @@ RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) м Параметри: - - `raw` (string) — JSON5 лише з ключами, які потрібно змінити + - `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити - `baseHash` (обов’язково) — хеш конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` + - `sessionKey`, `note`, `restartDelayMs` — ті самі, що й у `config.apply` Поведінка перезапуску збігається з `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундна пауза між циклами перезапуску. @@ -635,12 +639,12 @@ RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) м ## Змінні середовища -OpenClaw читає env vars із батьківського процесу, а також із: +OpenClaw зчитує змінні середовища з батьківського процесу, а також з: - `.env` з поточного робочого каталогу (якщо є) - `~/.openclaw/.env` (глобальний резервний варіант) -Жоден із цих файлів не перевизначає вже наявні env vars. Ви також можете задавати вбудовані env vars у конфігурації: +Жоден із цих файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: ```json5 { @@ -652,7 +656,7 @@ OpenClaw читає env vars із батьківського процесу, а ``` - Якщо ввімкнено і потрібні ключі не задані, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + Якщо цю функцію ввімкнено й очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: ```json5 { @@ -662,11 +666,11 @@ OpenClaw читає env vars із батьківського процесу, а } ``` -Еквівалент env var: `OPENCLAW_LOAD_SHELL_ENV=1` +Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1` - - Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: + + Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -677,15 +681,15 @@ OpenClaw читає env vars із батьківського процесу, а Правила: -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` -- Відсутні/порожні vars спричиняють помилку під час завантаження -- Використовуйте `$${VAR}` для буквального виводу +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Відсутні/порожні змінні викликають помилку під час завантаження +- Використовуйте `$${VAR}` для виведення літерала - Працює всередині файлів `$include` - Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - + Для полів, які підтримують об’єкти SecretRef, можна використовувати: ```json5 @@ -718,15 +722,15 @@ OpenClaw читає env vars із батьківського процесу, а } ``` -Подробиці щодо SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведено в [Керування секретами](/uk/gateway/secrets). -Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Докладніше про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) див. у [Керування секретами](/uk/gateway/secrets). +Підтримувані шляхи облікових даних наведено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). Див. [Середовище](/uk/help/environment) для повного опису пріоритетів і джерел. ## Повний довідник -Повний довідник поле за полем дивіться в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. +Повний довідник для кожного поля див. в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. ---