chore(i18n): refresh uk translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 08:29:49 +00:00
parent 0f532557fc
commit ff74525e09
3 changed files with 1072 additions and 1121 deletions

File diff suppressed because it is too large Load Diff

View File

@ -1,38 +1,37 @@
---
read_when:
- Перше налаштування OpenClaw
- Пошук поширених шаблонів конфігурації
- Поширені шаблони конфігурації
- Перехід до конкретних розділів конфігурації
summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник'
title: Конфігурація
x-i18n:
generated_at: "2026-04-23T08:14:09Z"
generated_at: "2026-04-23T08:25:11Z"
model: gpt-5.4
provider: openai
source_hash: a674bbc73f3a501ffd47ef9396d55d6087806921cfb24ef576398022dd0248c3
source_hash: d76b40c25f98de791e0d8012b2bc5b80e3e38dde99bb9105539e800ddac3f362
source_path: gateway/configuration.md
workflow: 15
---
# Конфігурація
OpenClaw читає необов’язковий конфігураційний файл <Tooltip tip="JSON5 підтримує коментарі та кінцеві коми">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
Активний шлях конфігурації має вказувати на звичайний файл. Схеми
`openclaw.json` із символьними посиланнями не підтримуються для записів,
якими керує OpenClaw; атомарний запис може замінити шлях замість збереження
символьного посилання. Якщо ви зберігаєте конфігурацію поза типовим
каталогом стану, вкажіть `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл.
OpenClaw зчитує необов’язкову конфігурацію <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
Активний шлях до конфігурації має вказувати на звичайний файл. Макети
`openclaw.json` із символьними посиланнями не підтримуються для записів, які виконує OpenClaw; атомарний запис може замінити
шлях замість збереження символьного посилання. Якщо ви зберігаєте конфігурацію поза
стандартним каталогом стану, спрямуйте `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл.
Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію:
- Підключити канали та керувати тим, хто може надсилати повідомлення боту
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, хуки)
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks)
- Налаштувати сесії, медіа, мережу або UI
Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля.
Див. [повний довідник](/uk/gateway/configuration-reference) для всіх доступних полів.
<Tip>
**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) для готових конфігурацій, які можна повністю скопіювати й вставити.
**Вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими повними конфігураціями для копіювання й вставлення.
</Tip>
## Мінімальна конфігурація
@ -50,8 +49,8 @@ OpenClaw читає необов’язковий конфігураційний
<Tabs>
<Tab title="Інтерактивний майстер">
```bash
openclaw onboard # повний процес початкового налаштування
openclaw configure # майстер конфігурації
openclaw onboard # full onboarding flow
openclaw configure # config wizard
```
</Tab>
<Tab title="CLI (однорядкові команди)">
@ -63,31 +62,29 @@ OpenClaw читає необов’язковий конфігураційний
</Tab>
<Tab title="Control UI">
Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використайте вкладку **Config**.
Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів
`title` / `description`, а також схемами plugin і каналів, коли вони
доступні, з редактором **Raw JSON** як запасним варіантом. Для інтерфейсів
деталізації та інших інструментів gateway також надає `config.schema.lookup`,
щоб отримати один вузол схеми для певного шляху разом із короткими
відомостями про безпосередні дочірні елементи.
Control UI візуалізує форму на основі живої схеми конфігурації, включно з метаданими документації
полів `title` / `description`, а також схемами plugin і каналів, коли вони
доступні, із редактором **Raw JSON** як запасним варіантом. Для деталізованих
UI та інших інструментів gateway також надає `config.schema.lookup`, щоб
отримати один вузол схеми для конкретного шляху разом із підсумками безпосередніх дочірніх елементів.
</Tab>
<Tab title="Пряме редагування">
Відредагуйте `~/.openclaw/openclaw.json` напряму. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway стежить за файлом і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
</Tab>
</Tabs>
## Сувора валідація
<Warning>
OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema.
OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня`$schema` (рядок), щоб редактори могли підключати метадані JSON Schema.
</Warning>
`openclaw config schema` виводить канонічну JSON Schema, яку використовують Control UI
та валідація. `config.schema.lookup` отримує один вузол для певного шляху разом
із короткими відомостями про дочірні елементи для інструментів деталізації.
Метадані документації полів `title`/`description` поширюються на вкладені об’єкти,
підстановочні символи (`*`), елементи масиву (`[]`) та гілки `anyOf`/
`oneOf`/`allOf`. Схеми runtime plugin і каналів додаються під час завантаження
реєстру маніфестів.
і валідація. `config.schema.lookup` отримує один вузол для конкретного шляху разом
із підсумками дочірніх елементів для інструментів із деталізованою навігацією. Метадані документації полів `title`/`description`
поширюються на вкладені об’єкти, wildcard (`*`), елементи масиву (`[]`) і гілки `anyOf`/
`oneOf`/`allOf`. Схеми plugin і каналів під час виконання додаються, коли
завантажено реєстр маніфестів.
Коли валідація не проходить:
@ -96,21 +93,19 @@ OpenClaw приймає лише конфігурації, що повністю
- Запустіть `openclaw doctor`, щоб побачити точні проблеми
- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення
Після кожного успішного запуску Gateway зберігає довірену останню коректну копію.
Якщо пізніше `openclaw.json` не проходить валідацію (або втрачає `gateway.mode`,
різко зменшується, або на початку з’являється сторонній рядок журналу),
OpenClaw зберігає пошкоджений файл як `.clobbered.*`, відновлює останню коректну
копію та записує причину відновлення в журнал. Під час наступного ходу агента
також надходить попередження про системну подію, щоб основний агент не
перезаписав відновлену конфігурацію без перевірки. Підвищення до статусу
останньої коректної копії пропускається, якщо кандидат містить замасковані
заповнювачі секретів, такі як `***`.
Gateway зберігає довірену останню відому коректну копію після кожного успішного запуску.
Якщо `openclaw.json` згодом не проходить валідацію (або втрачає `gateway.mode`, різко
зменшується, чи до нього випадково додається рядок журналу на початку), OpenClaw зберігає зламаний файл
як `.clobbered.*`, відновлює останню відому коректну копію та записує в журнал причину
відновлення. Наступний хід агента також отримує попередження про системну подію, щоб основний
агент не перезаписав відновлену конфігурацію бездумно. Підвищення до статусу останньої відомої коректної копії
пропускається, якщо кандидат містить замасковані заповнювачі секретів, наприклад `***`.
## Поширені завдання
<AccordionGroup>
<Accordion title="Налаштування каналу (WhatsApp, Telegram, Discord тощо)">
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Кроки налаштування дивіться на окремій сторінці каналу:
<Accordion title="Налаштувати канал (WhatsApp, Telegram, Discord тощо)">
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Див. окрему сторінку каналу для кроків налаштування:
- [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/uk/channels/telegram) — `channels.telegram`
@ -140,7 +135,7 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
</Accordion>
<Accordion title="Вибір і налаштування моделей">
<Accordion title="Вибрати й налаштувати моделі">
Задайте основну модель і необов’язкові резервні варіанти:
```json5
@ -161,30 +156,30 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
```
- `agents.defaults.models` визначає каталог моделей і виконує роль списку дозволених значень для `/model`.
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додати записи до списку дозволених без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`.
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додати записи до списку дозволених значень без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо не передати `--replace`.
- Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`).
- `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскрипті/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю знімків екрана.
- Див. [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover) щодо ротації авторизації та поведінки резервних моделей.
- Для користувацьких/самостійно розміщених провайдерів див. [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 провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику.
</Accordion>
<Accordion title="Керування тим, хто може надсилати повідомлення боту">
Доступ до DM керується окремо для кожного каналу через `dmPolicy`:
<Accordion title="Керувати тим, хто може надсилати повідомлення боту">
Доступ до DM контролюється окремо для кожного каналу через `dmPolicy`:
- `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження
- `"allowlist"`: лише відправники з `allowFrom` (або зі сховища парного списку дозволених)
- `"pairing"` (типово): невідомі відправники отримують одноразовий код спаровування для підтвердження
- `"allowlist"`: лише відправники з `allowFrom` (або зі сховища дозволених спарених користувачів)
- `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`)
- `"disabled"`: ігнорувати всі DM
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або списки дозволених, специфічні для каналу.
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або списки дозволених значень, специфічні для каналу.
Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць щодо кожного каналу.
Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу.
</Accordion>
<Accordion title="Налаштування фільтрації згадок у групових чатах">
За замовчуванням для групових повідомлень **потрібна згадка**. Налаштуйте шаблони для кожного агента:
<Accordion title="Налаштувати фільтрацію згадок у групових чатах">
Повідомлення в групах типово **вимагають згадки**. Налаштуйте шаблони для кожного агента:
```json5
{
@ -207,12 +202,12 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
```
- **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо)
- **Текстові шаблони**: безпечні шаблони regex у `mentionPatterns`
- Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень на рівні каналів і режиму self-chat.
- **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns`
- Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень по каналах і режиму self-chat.
</Accordion>
<Accordion title="Обмеження Skills для агента">
<Accordion title="Обмежити Skills для кожного агента">
Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретних
агентів через `agents.list[].skills`:
@ -231,16 +226,16 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
}
```
- Не вказуйте `agents.defaults.skills`, якщо за замовчуванням Skills не мають бути обмежені.
- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення.
- Установіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills.
- Див. [Skills](/uk/tools/skills), [Skills config](/uk/tools/skills-config) і
[Configuration Reference](/uk/gateway/configuration-reference#agents-defaults-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).
</Accordion>
<Accordion title="Налаштування моніторингу стану каналів gateway">
Керуйте тим, наскільки агресивно gateway перезапускає канали, що виглядають застарілими:
<Accordion title="Налаштувати моніторинг стану каналів gateway">
Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають неактивними:
```json5
{
@ -262,15 +257,15 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
}
```
- Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски через моніторинг стану.
- `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки.
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуск для одного каналу чи облікового запису без вимкнення глобального моніторингу.
- Див. [Health Checks](/uk/gateway/health) для операційної діагностики та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
- Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски через моніторинг стану.
- `channelStaleEventThresholdMinutes` має бути більшим або рівним інтервалу перевірки.
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора.
- Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
</Accordion>
<Accordion title="Налаштування сесій і скидання">
Сесії керують безперервністю та ізоляцією розмов:
<Accordion title="Налаштувати сесії та скидання">
Сесії керують безперервністю розмови та ізоляцією:
```json5
{
@ -291,14 +286,14 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
```
- `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: глобальні типові значення для маршрутизації сесій, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
- Див. [Session Management](/uk/concepts/session) щодо області видимості, зв’язків ідентичностей і політики надсилання.
- `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
- Див. [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання.
- Див. [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів.
</Accordion>
<Accordion title="Увімкнення ізоляції">
Запускайте сесії агентів в ізольованих sandbox runtime:
<Accordion title="Увімкнути ізоляцію">
Запускайте сесії агентів в ізольованих середовищах ізоляції:
```json5
{
@ -315,11 +310,11 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
Спочатку зберіть образ: `scripts/sandbox-setup.sh`
Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів.
Див. [Ізоляція](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів.
</Accordion>
<Accordion title="Увімкнення relay-backed push для офіційних збірок iOS">
<Accordion title="Увімкнути relay-backed push для офіційних збірок iOS">
Relay-backed push налаштовується в `openclaw.json`.
Додайте це в конфігурацію gateway:
@ -348,35 +343,35 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
Що це робить:
- Дає змогу gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay.
- Дає змогу gateway надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній relay.
- Використовує дозвіл на надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потребує relay-токена для всього розгортання.
- Прив’язує кожну реєстрацію з relay-підтримкою до ідентичності gateway, з якою було спарено застосунок iOS, тому інший gateway не зможе повторно використати збережену реєстрацію.
- Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання з relay-підтримкою застосовується лише до офіційних розповсюджуваних збірок, які зареєстровано через relay.
- Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання потрапляв до одного й того самого розгортання relay.
- Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою був спарений застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію.
- Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційних розповсюджених збірок, які зареєструвалися через 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 та квитанції застосунку, а потім публікує payload `push.apns.register` з relay-підтримкою у спарений gateway.
5. Gateway зберігає relay handle і дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та сигналів повторного підключення.
2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway.
3. Спаріть застосунок iOS із gateway і дозвольте підключитися сеансам node та оператора.
4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed корисне навантаження `push.apns.register` у спарений gateway.
5. Gateway зберігає relay handle і дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для повторного підключення.
Операційні примітки:
- Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway.
- Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює кешовану relay-реєстрацію замість повторного використання старого джерела relay.
- Якщо ви випускаєте нову збірку 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_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.
</Accordion>
<Accordion title="Налаштування Heartbeat (періодичні перевірки)">
<Accordion title="Налаштувати Heartbeat (періодичні перевірки)">
```json5
{
agents: {
@ -397,7 +392,7 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
</Accordion>
<Accordion title="Налаштування завдань Cron">
<Accordion title="Налаштувати Cron jobs">
```json5
{
cron: {
@ -412,14 +407,14 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
}
```
- `sessionRetention`: видаляти завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
- `sessionRetention`: очищати завершені ізольовані сеанси запусків із `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю рядків, які слід зберегти.
- Див. [Cron jobs](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI.
</Accordion>
<Accordion title="Налаштування Webhook (хуків)">
Увімкніть HTTP-ендпоїнти Webhook у Gateway:
<Accordion title="Налаштувати Webhook-и (hooks)">
Увімкніть HTTP-ендпоїнти Webhook на Gateway:
```json5
{
@ -443,20 +438,20 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
```
Примітка щодо безпеки:
- Уважайте весь вміст payload hook/Webhook недовіреним введенням.
- Розглядайте весь вміст корисного навантаження 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, де це можливо).
- `hooks.path` не може бути `/`; використовуйте для вхідних Webhook-ів окремий підшлях, наприклад `/hooks`.
- Залишайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо тільки не виконуєте суворо обмежене налагодження.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які вибирає викликач.
- Для агентів, керованих hook-ами, віддавайте перевагу потужним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо).
Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mapping і інтеграції Gmail.
Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів зіставлення та інтеграції з Gmail.
</Accordion>
<Accordion title="Налаштування маршрутизації з кількома агентами">
Запускайте кілька ізольованих агентів з окремими робочими просторами та сесіями:
<Accordion title="Налаштувати маршрутизацію кількох агентів">
Запускайте кількох ізольованих агентів з окремими робочими просторами й сесіями:
```json5
{
@ -473,12 +468,12 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
}
```
Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) щодо правил прив’язки та профілів доступу для кожного агента.
Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил прив’язки й профілів доступу для кожного агента.
</Accordion>
<Accordion title="Розділення конфігурації на кілька файлів ($include)">
Використовуйте `$include`, щоб упорядкувати великі конфігурації:
<Accordion title="Розділити конфігурацію на кілька файлів ($include)">
Використовуйте `$include`, щоб упорядковувати великі конфігурації:
```json5
// ~/.openclaw/openclaw.json
@ -491,47 +486,48 @@ OpenClaw зберігає пошкоджений файл як `.clobbered.*`,
}
```
- **Один файл**: замінює об’єкт, у якому міститься
- **Масив файлів**: глибоко об’єднується за порядком (пізніші мають пріоритет)
- **Сусідні ключі**: об’єднуються після include (перевизначають включені значення)
- **Вкладені include**: підтримуються до 10 рівнів вкладеності
- **Відносні шляхи**: обчислюються відносно файлу, який включає
- **Записи, якими керує OpenClaw**: коли запис змінює лише один розділ верхнього рівня,
що підкріплений include одного файлу, наприклад `plugins: { $include: "./plugins.json5" }`,
- **Один файл**: замінює об’єкт, який його містить
- **Масив файлів**: глибоко зливається по порядку (пізніший має пріоритет)
- **Сусідні ключі**: зливаються після include-ів (перевизначають включені значення)
- **Вкладені include**: підтримуються до 10 рівнів вкладеності
- **Відносні шляхи**: обчислюються відносно файла, який виконує включення
- **Записи, які виконує OpenClaw**: коли запис змінює лише один розділ верхнього рівня,
що підтримується include-ом одного файла, як-от `plugins: { $include: "./plugins.json5" }`,
OpenClaw оновлює цей включений файл і залишає `openclaw.json` без змін
- **Непідтримуваний наскрізний запис**: кореневі include, масиви include та include
із сусідніми перевизначеннями завершуються без змін для записів, якими керує OpenClaw, замість
сплощення конфігурації
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору та циклічних include
- **Непідтримуваний запис через include**: root include-и, масиви include-ів і include-и
із сусідніми перевизначеннями завершуються безпечною відмовою для записів, які виконує OpenClaw, замість
сплющення конфігурації
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору й циклічних include-ів
</Accordion>
</AccordionGroup>
## Гаряче перезавантаження конфігурації
Gateway відстежує `~/.openclaw/openclaw.json` і застосовує зміни автоматично — для більшості параметрів ручний перезапуск не потрібен.
Gateway стежить за `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості параметрів ручний перезапуск не потрібен.
Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач
чекає, поки вщухнуть тимчасові записи/перейменування редактора, читає фінальний файл
і відхиляє некоректні зовнішні зміни, відновлюючи останню коректну конфігурацію. Записи конфігурації,
якими керує OpenClaw, використовують ту саму перевірку схемою перед записом; руйнівні пошкодження, такі
як видалення `gateway.mode` або зменшення файлу більш ніж наполовину, відхиляються
та зберігаються як `.rejected.*` для перевірки.
Прямі редагування файла вважаються недовіреними, доки не пройдуть валідацію. Спостерігач
чекає, поки вщухне активність тимчасових записів/перейменувань редактора,
зчитує фінальний файл і відхиляє недійсні зовнішні редагування, відновлюючи
останню відому коректну конфігурацію. Записи конфігурації, які виконує 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 troubleshooting](/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`, виправте відхилене корисне навантаження, а потім запустіть
`openclaw config validate`. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config)
для контрольного списку відновлення.
### Режими перезавантаження
| Режим | Поведінка |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **`hybrid`** (типово) | Безпечно застосовує зміни одразу. Для критичних змін автоматично виконує перезапуск. |
| **`hot`** | Застосовує лише безпечні зміни без перезапуску. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. |
| Режим | Поведінка |
| ---------------------- | --------------------------------------------------------------------------------------- |
| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Для критичних автоматично перезапускає. |
| **`hot`** | Гаряче застосовує лише безпечні зміни. Пише попередження, коли потрібен перезапуск — ви виконуєте його самі. |
| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. |
| **`off`** | Вимикає відстеження файлу. Зміни набудуть чинності під час наступного ручного перезапуску. |
| **`off`** | Вимикає спостереження за файлами. Зміни набувають чинності під час наступного ручного перезапуску. |
```json5
{
@ -541,53 +537,53 @@ 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` | **Так** |
<Note>
`gateway.reload` і `gateway.remote` — винятки: їх зміна **не** призводить до перезапуску.
`gateway.reload` і `gateway.remote` — винятки: їх зміна **не** спричиняє перезапуск.
</Note>
### Планування перезавантаження
Коли ви редагуєте вихідний файл, на який є посилання через `$include`, OpenClaw планує
перезавантаження на основі структури, визначеної у вихідних файлах, а не сплощеного представлення в пам’яті.
Це робить рішення для гарячого перезавантаження (застосувати без перезапуску чи перезапустити) передбачуваними навіть тоді, коли
один розділ верхнього рівня розміщено у власному включеному файлі, наприклад
`plugins: { $include: "./plugins.json5" }`. Планування перезавантаження завершується без змін, якщо
структура джерела неоднозначна.
перезавантаження на основі макета, заданого у вихідних файлах, а не сплющеного представлення в пам’яті.
Це робить рішення гарячого перезавантаження (гаряче застосування чи перезапуск) передбачуваними, навіть коли
один розділ верхнього рівня живе у власному включеному файлі, наприклад
`plugins: { $include: "./plugins.json5" }`. Планування перезавантаження завершується безпечною відмовою, якщо
вихідний макет неоднозначний.
## RPC конфігурації (програмні оновлення)
## Config RPC (програмні оновлення)
Для інструментів, які записують конфігурацію через API gateway, віддавайте перевагу такому процесу:
Для інструментів, які записують конфігурацію через API gateway, використовуйте такий потік:
- `config.schema.lookup`, щоб перевірити одне піддерево (поверхневий вузол схеми + короткі
відомості про дочірні елементи)
- `config.get`, щоб отримати поточний знімок разом із `hash`
- `config.patch` для часткових оновлень (JSON merge patch: об’єкти об’єднуються, `null`
- `config.schema.lookup`, щоб перевірити одне піддерево (неглибокий вузол схеми + підсумки
дочірніх елементів)
- `config.get`, щоб отримати поточний знімок і `hash`
- `config.patch` для часткових оновлень (JSON merge patch: об’єкти зливаються, `null`
видаляє, масиви замінюються)
- `config.apply` лише тоді, коли ви справді хочете замінити всю конфігурацію
- `update.run` для явного самостійного оновлення з подальшим перезапуском
- `config.apply` лише якщо ви справді хочете замінити всю конфігурацію
- `update.run` для явного самооновлення й перезапуску
<Note>
Записи контрольної площини (`config.apply`, `config.patch`, `update.run`) обмежуються
до 3 запитів на 60 секунд для кожної пари `deviceId+clientIp`. Запити на перезапуск
об’єднуються, а потім між циклами перезапуску застосовується затримка 30 секунд.
Записи control-plane (`config.apply`, `config.patch`, `update.run`)
обмежуються до 3 запитів за 60 секунд на `deviceId+clientIp`. Запити на перезапуск
об’єднуються, а потім примусово застосовують 30-секундний cooldown між циклами перезапуску.
</Note>
Приклад часткового patch:
Приклад часткового патча:
```bash
openclaw gateway call config.get --params '{}' # capture payload.hash
@ -598,17 +594,17 @@ openclaw gateway call config.patch --params '{
```
І `config.apply`, і `config.patch` приймають `raw`, `baseHash`, `sessionKey`,
`note` і `restartDelayMs`. `baseHash` є обов’язковим для `config.patch` і
рекомендованим для `config.apply`, коли конфігурація вже існує.
`note` і `restartDelayMs`. `baseHash` є обов’язковим для обох методів, якщо
конфігурація вже існує.
## Змінні середовища
OpenClaw читає змінні середовища з батьківського процесу, а також з:
OpenClaw зчитує env vars із батьківського процесу, а також із:
- `.env` у поточному робочому каталозі (якщо є)
- `~/.openclaw/.env` (глобальний запасний варіант)
Жоден із цих файлів не перевизначає вже наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації:
Жоден із цих файлів не перевизначає вже наявні env vars. Ви також можете задавати inline env vars у конфігурації:
```json5
{
@ -619,8 +615,8 @@ OpenClaw читає змінні середовища з батьківсько
}
```
<Accordion title="Імпорт змінних середовища оболонки (необов’язково)">
Якщо ввімкнено і очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
<Accordion title="Імпорт env shell (необов’язково)">
Якщо це ввімкнено й очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
```json5
{
@ -630,11 +626,11 @@ OpenClaw читає змінні середовища з батьківсько
}
```
Еквівалентна змінна середовища: `OPENCLAW_LOAD_SHELL_ENV=1`
Еквівалент env var: `OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="Підстановка змінних середовища у значеннях конфігурації">
Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`:
<Accordion title="Підстановка env var у значеннях конфігурації">
Посилайтеся на env vars у будь-якому рядковому значенні конфігурації через `${VAR_NAME}`:
```json5
{
@ -645,15 +641,15 @@ OpenClaw читає змінні середовища з батьківсько
Правила:
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
- Відсутні/порожні змінні спричиняють помилку під час завантаження
- Використовуйте `$${VAR}` для буквального виводу
- Екрануйте через `$${VAR}` для виведення буквального значення
- Працює всередині файлів `$include`
- Вбудована підстановка: `"${BASE}/v1"``"https://api.example.com/v1"`
</Accordion>
<Accordion title="Посилання на секрети (env, file, exec)">
<Accordion title="SecretRef-и (env, file, exec)">
Для полів, які підтримують об’єкти SecretRef, можна використовувати:
```json5
@ -686,16 +682,16 @@ OpenClaw читає змінні середовища з батьківсько
}
```
Подробиці про SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) наведено в [Secrets Management](/uk/gateway/secrets).
Підтримувані шляхи облікових даних перелічено в [SecretRef Credential Surface](/uk/reference/secretref-credential-surface).
Подробиці про SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) наведено в [Керуванні секретами](/uk/gateway/secrets).
Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
</Accordion>
Див. [Environment](/uk/help/environment) для повного опису пріоритетів і джерел.
Див. [Environment](/uk/help/environment) для повного порядку пріоритетів і джерел.
## Повний довідник
Повний довідник по полях див. в **[Configuration Reference](/uk/gateway/configuration-reference)**.
Повний довідник по кожному полю дивіться в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**.
---
овязане: [Configuration Examples](/uk/gateway/configuration-examples) · [Configuration Reference](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_
овязане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_

File diff suppressed because it is too large Load Diff