diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md
index 9856a030b..9e6a0f20f 100644
--- a/docs/uk/gateway/configuration-reference.md
+++ b/docs/uk/gateway/configuration-reference.md
@@ -1,23 +1,23 @@
---
read_when:
- - Вам потрібна точна семантика або значення за замовчуванням для полів конфігурації
- - Ви перевіряєте блоки конфігурації каналів, моделей, шлюзу або інструментів
-summary: Повний довідник для кожного ключа конфігурації OpenClaw, значень за замовчуванням і налаштувань каналів
+ - Вам потрібна точна семантика полів конфігурації або значення за замовчуванням на рівні окремих полів
+ - Ви перевіряєте блоки конфігурації каналу, моделі, шлюзу або інструмента
+summary: Повний довідник для кожного ключа конфігурації OpenClaw, значень за замовчуванням і параметрів каналів
title: Довідник з конфігурації
x-i18n:
- generated_at: "2026-04-06T15:34:37Z"
+ generated_at: "2026-04-07T15:03:53Z"
model: gpt-5.4
provider: openai
- source_hash: 7768cb77e1d3fc483c66f655ea891d2c32f21b247e3c1a56a919b28a37f9b128
+ source_hash: 1eb296bd35db5d26be5a72ce2cbf94c5173d4e8ebeb6eb2d891dddd102511d05
source_path: gateway/configuration-reference.md
workflow: 15
---
# Довідник з конфігурації
-Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
+Кожне поле, доступне в `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration).
-Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено.
+Формат конфігурації — **JSON5** (дозволено коментарі та кінцеві коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні значення за замовчуванням.
---
@@ -25,32 +25,32 @@ x-i18n:
Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`).
-### Доступ до приватних повідомлень і груп
+### Доступ до особистих повідомлень і груп
-Усі канали підтримують політики для приватних повідомлень і груп:
+Усі канали підтримують політики для особистих повідомлень і груп:
-| Політика DM | Поведінка |
-| ------------------- | ------------------------------------------------------------- |
-| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити |
-| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів сполучення) |
-| `open` | Дозволити всі вхідні приватні повідомлення (потребує `allowFrom: ["*"]`) |
-| `disabled` | Ігнорувати всі вхідні приватні повідомлення |
+| Політика особистих повідомлень | Поведінка |
+| ------------------------------ | -------------------------------------------------------------- |
+| `pairing` (за замовчуванням) | Невідомі відправники отримують одноразовий код сполучення; власник має підтвердити |
+| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених після сполучення) |
+| `open` | Дозволити всі вхідні особисті повідомлення (потрібно `allowFrom: ["*"]`) |
+| `disabled` | Ігнорувати всі вхідні особисті повідомлення |
-| Політика груп | Поведінка |
-| -------------------- | ------------------------------------------------------ |
-| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених |
-| `open` | Обійти списки дозволених груп (фільтрація за згадуваннями все одно застосовується) |
-| `disabled` | Блокувати всі повідомлення в групах/кімнатах |
+| Політика груп | Поведінка |
+| ---------------------- | ------------------------------------------------------ |
+| `allowlist` (за замовчуванням) | Лише групи, що відповідають налаштованому списку дозволених |
+| `open` | Обійти списки дозволених для груп (обмеження за згадками все одно застосовується) |
+| `disabled` | Блокувати всі повідомлення груп/кімнат |
-`channels.defaults.groupPolicy` встановлює значення за замовчуванням, коли `groupPolicy` у провайдера не задано.
-Коди сполучення спливають через 1 годину. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**.
-Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп у runtime повертається до `allowlist` (закрито за замовчуванням) із попередженням під час запуску.
+`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` у провайдера не встановлено.
+Коди сполучення спливають через 1 годину. Очікувані запити на сполучення для особистих повідомлень обмежені **3 на канал**.
+Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (відмова за замовчуванням) із попередженням під час запуску.
-### Перевизначення моделі для каналів
+### Перевизначення моделей для каналів
-Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ідентифікатори каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, встановленого через `/model`).
+Використовуйте `channels.modelByChannel`, щоб закріпити певні ідентифікатори каналів за моделлю. Значення можуть бути у форматі `provider/model` або як налаштовані псевдоніми моделей. Відображення каналу застосовується, якщо для сесії ще не встановлено перевизначення моделі (наприклад, через `/model`).
```json5
{
@@ -71,7 +71,7 @@ x-i18n:
}
```
-### Типові значення для каналів і heartbeat
+### Значення каналів за замовчуванням і heartbeat
Використовуйте `channels.defaults` для спільної поведінки політики груп і heartbeat у різних провайдерів:
@@ -91,11 +91,11 @@ x-i18n:
}
```
-- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не задано.
-- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (як `allowlist`, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`.
-- `channels.defaults.heartbeat.showOk`: включати здорові стани каналів у вивід heartbeat.
-- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові стани у вивід heartbeat.
-- `channels.defaults.heartbeat.useIndicator`: відображати компактний heartbeat у стилі індикатора.
+- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено.
+- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (за замовчуванням, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від дозволених відправників), `allowlist_quote` (так само, як allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення на рівні каналу: `channels..contextVisibility`.
+- `channels.defaults.heartbeat.showOk`: включати стани справних каналів у вивід heartbeat.
+- `channels.defaults.heartbeat.showAlerts`: включати стани деградації/помилок у вивід heartbeat.
+- `channels.defaults.heartbeat.useIndicator`: відображати heartbeat у компактному форматі індикатора.
### WhatsApp
@@ -110,7 +110,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
textChunkLimit: 4000,
chunkMode: "length", // length | newline
mediaMaxMb: 50,
- sendReadReceipts: true, // сині галочки (false у режимі self-chat)
+ sendReadReceipts: true, // сині галочки (false у режимі чату із самим собою)
groups: {
"*": { requireMention: true },
},
@@ -150,10 +150,10 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
}
```
-- Вихідні команди типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований `account id` (відсортований).
-- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
-- Застарілий каталог автентифікації Baileys для одного облікового запису переноситься `openclaw doctor` у `whatsapp/default`.
-- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
+- Команди вихідної доставки за замовчуванням використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ідентифікатор облікового запису (після сортування).
+- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
+- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується `openclaw doctor` до `whatsapp/default`.
+- Перевизначення для окремих облікових записів: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
@@ -171,12 +171,12 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
"*": { requireMention: true },
"-1001234567890": {
allowFrom: ["@admin"],
- systemPrompt: "Відповідай коротко.",
+ systemPrompt: "Тримай відповіді короткими.",
topics: {
"99": {
requireMention: false,
skills: ["search"],
- systemPrompt: "Дотримуйся теми.",
+ systemPrompt: "Не відхиляйся від теми.",
},
},
},
@@ -188,7 +188,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
historyLimit: 50,
replyToMode: "first", // off | first | all | batched
linkPreview: true,
- streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникнути обмежень rate limit на попередній перегляд і редагування)
+ streaming: "partial", // off | partial | block | progress (за замовчуванням: off; вмикайте явно, щоб уникнути обмежень швидкості попереднього перегляду під час редагування)
actions: { reactions: true, sendMessage: true },
reactionNotifications: "own", // off | own | all
mediaMaxMb: 100,
@@ -211,13 +211,13 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
}
```
-- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; симлінки відхиляються), з `TELEGRAM_BOT_TOKEN` як резервом для облікового запису за замовчуванням.
-- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
-- У багатооблікових конфігураціях (2+ `account id`) задайте явний типово вибраний обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення невалідне.
-- `configWrites: false` блокує ініційовані Telegram записи в конфігурацію (міграції ID супергруп, `/config set|unset`).
-- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
-- Попередній перегляд стриму в Telegram використовує `sendMessage` + `editMessageText` (працює в приватних і групових чатах).
-- Політика повторних спроб: див. [Retry policy](/uk/concepts/retry).
+- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), із `TELEGRAM_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням.
+- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
+- У конфігураціях із кількома обліковими записами (2+ ідентифікатори облікових записів) встановіть явний обліковий запис за замовчуванням (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо його немає або він недійсний.
+- `configWrites: false` блокує записи конфігурації, ініційовані з Telegram (міграції ідентифікаторів супергруп, `/config set|unset`).
+- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах).
+- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry).
### Discord
@@ -283,7 +283,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
enabled: true,
idleHours: 24,
maxAgeHours: 0,
- spawnSubagentSessions: false, // opt-in для sessions_spawn({ thread: true })
+ spawnSubagentSessions: false, // увімкнення за згодою для sessions_spawn({ thread: true })
},
voice: {
enabled: true,
@@ -319,36 +319,36 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
}
```
-- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервом для облікового запису за замовчуванням.
-- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик для облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime.
-- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
-- Використовуйте `user:` (DM) або `channel:` (канал guild) як цілі доставки; прості числові ID відхиляються.
-- Slug-и guild мають бути в нижньому регістрі з пробілами, заміненими на `-`; ключі каналів використовують slug-ім’я (без `#`). Віддавайте перевагу ID guild.
-- Повідомлення, створені ботами, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення від ботів, які згадують бота (власні повідомлення все одно фільтруються).
-- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here).
-- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення навіть якщо вони менші за 2000 символів.
+- Токен: `channels.discord.token`, із `DISCORD_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням.
+- Прямі вихідні виклики, у яких явно вказано Discord `token`, використовують цей токен для виклику; параметри повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime.
+- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
+- Для цілей доставки використовуйте `user:` (особисті повідомлення) або `channel:` (канал гільдії); голі числові ідентифікатори відхиляються.
+- Slug-и гільдій — у нижньому регістрі з пробілами, заміненими на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ідентифікаторам гільдій.
+- Повідомлення, написані ботом, ігноруються за замовчуванням. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються).
+- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналів) відкидає повідомлення, які згадують іншого користувача чи роль, але не бота (окрім @everyone/@here).
+- `maxLinesPerMessage` (за замовчуванням 17) розбиває довгі повідомлення навіть тоді, коли вони коротші за 2000 символів.
- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до гілок Discord:
- - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація)
- - `idleHours`: перевизначення Discord для автоматичного unfocus через неактивність у годинах (`0` вимикає)
+ - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також прив’язана доставка/маршрутизація)
+ - `idleHours`: перевизначення Discord для автоматичного зняття фокусу через неактивність у годинах (`0` вимикає)
- `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає)
- - `spawnSubagentSessions`: прапорець opt-in для автоматичного створення/прив’язки гілок через `sessions_spawn({ thread: true })`
-- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте channel/thread id у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
-- `channels.discord.ui.components.accentColor` встановлює акцентний колір для контейнерів Discord components v2.
-- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS.
-- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`).
-- OpenClaw також намагається відновити прийом голосу, виходячи й знову приєднуючись до голосової сесії після повторних помилок дешифрування.
-- `channels.discord.streaming` — канонічний ключ режиму стриму. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються.
-- `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу.
+ - `spawnSubagentSessions`: перемикач увімкнення за згодою для автоматичного створення/прив’язки гілок `sessions_spawn({ thread: true })`
+- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте ідентифікатор каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів компонентів Discord v2.
+- `channels.discord.voice` вмикає розмови у голосових каналах Discord та необов’язкове автоматичне приєднання + перевизначення TTS.
+- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` передаються до параметрів DAVE у `@discordjs/voice` (`true` і `24` за замовчуванням).
+- OpenClaw також намагається відновити прийом голосу, виходячи й повторно приєднуючись до голосової сесії після повторних збоїв дешифрування.
+- `channels.discord.streaming` — канонічний ключ режиму потоку. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично.
+- `channels.discord.autoPresence` відображає доступність runtime у статус бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу.
- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним ім’ям/тегом (режим сумісності break-glass).
-- `channels.discord.execApprovals`: доставка схвалень exec у нативному форматі Discord та авторизація схвалювачів.
- - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
- - `approvers`: ID користувачів Discord, яким дозволено схвалювати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`.
- - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо не вказано, пересилаються схвалення для всіх агентів.
+- `channels.discord.execApprovals`: власна доставка підтверджень exec у Discord і авторизація схвалювачів.
+ - `enabled`: `true`, `false` або `"auto"` (за замовчуванням). В автоматичному режимі підтвердження exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
+ - `approvers`: ідентифікатори користувачів Discord, яким дозволено схвалювати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`.
+ - `agentFilter`: необов’язковий список дозволених ідентифікаторів агентів. Не вказуйте, щоб пересилати підтвердження для всіх агентів.
- `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex).
- - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає у DM схвалювачам, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли `target` включає `"channel"`, кнопки можуть використовувати лише визначені схвалювачі.
- - `cleanupAfterResolve`: якщо `true`, видаляє DM зі схваленням після схвалення, відхилення або тайм-ауту.
+ - `target`: куди надсилати запити на підтвердження. `"dm"` (за замовчуванням) надсилає в особисті повідомлення схвалювачам, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли ціль включає `"channel"`, кнопками можуть користуватися лише визначені схвалювачі.
+ - `cleanupAfterResolve`: коли `true`, видаляє особисті повідомлення з підтвердженням після схвалення, відхилення або тайм-ауту.
-**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень).
+**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, за замовчуванням), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень).
### Google Chat
@@ -379,10 +379,10 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
}
```
-- JSON облікового запису сервісу: вбудований (`serviceAccount`) або через файл (`serviceAccountFile`).
+- JSON облікового запису сервісу: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`).
- Також підтримується SecretRef для облікового запису сервісу (`serviceAccountRef`).
- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
-- Використовуйте `spaces/` або `users/` як цілі доставки.
+- Для цілей доставки використовуйте `spaces/` або `users/`.
- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним email principal (режим сумісності break-glass).
### Slack
@@ -434,7 +434,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
textChunkLimit: 4000,
chunkMode: "length",
streaming: "partial", // off | partial | block | progress (режим попереднього перегляду)
- nativeStreaming: true, // використовувати нативний Slack streaming API, коли streaming=partial
+ nativeStreaming: true, // використовувати рідний API потокової передачі Slack, коли streaming=partial
mediaMaxMb: 20,
execApprovals: {
enabled: "auto", // true | false | "auto"
@@ -448,34 +448,34 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві
}
```
-- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резерв із env для облікового запису за замовчуванням).
-- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або на рівні облікового запису).
-- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті
+- **Режим сокетів** вимагає одночасно `botToken` і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для облікового запису за замовчуванням).
+- **HTTP-режим** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису).
+- `botToken`, `appToken`, `signingSecret` і `userToken` приймають прості текстові
рядки або об’єкти SecretRef.
-- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як
- `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP,
+- Знімки облікових записів Slack містять поля джерела/статусу облікових даних, такі як
+ `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP-режимі,
`signingSecretStatus`. `configured_unavailable` означає, що обліковий запис
налаштований через SecretRef, але поточний шлях команди/runtime не зміг
- отримати значення секрету.
-- `configWrites: false` блокує ініційовані Slack записи в конфігурацію.
-- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
-- `channels.slack.streaming` — канонічний ключ режиму стриму. Застарілі значення `streamMode` і булеві `streaming` автоматично мігруються.
-- Використовуйте `user:` (DM) або `channel:` як цілі доставки.
+ розв’язати значення секрету.
+- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack.
+- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
+- `channels.slack.streaming` — канонічний ключ режиму потоку. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично.
+- Для цілей доставки використовуйте `user:` (особисті повідомлення) або `channel:`.
-**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`).
+**Режими сповіщень про реакції:** `off`, `own` (за замовчуванням), `all`, `allowlist` (із `reactionAllowlist`).
-**Ізоляція сесій у гілках:** `thread.historyScope` — на рівні гілки (типово) або спільна в межах каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові гілки.
+**Ізоляція сесій гілок:** `thread.historyScope` — для кожної гілки окремо (за замовчуванням) або спільно в межах каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки.
-- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім прибирає її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`.
-- `channels.slack.execApprovals`: доставка схвалень exec у нативному форматі Slack та авторизація схвалювачів. Та сама схема, що й для Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
+- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а після завершення видаляє її. Використовуйте короткий код emoji Slack, наприклад `"hourglass_flowing_sand"`.
+- `channels.slack.execApprovals`: власна доставка підтверджень exec у Slack і авторизація схвалювачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
-| Група дій | Типово | Примітки |
-| ----------- | ------- | ---------------------- |
-| reactions | увімкнено | Реагувати + перелік реакцій |
-| messages | увімкнено | Читати/надсилати/редагувати/видаляти |
-| pins | увімкнено | Закріпити/відкріпити/перелік |
-| memberInfo | увімкнено | Інформація про учасника |
-| emojiList | увімкнено | Список кастомних emoji |
+| Група дій | За замовчуванням | Примітки |
+| ------------ | ---------------- | ------------------------ |
+| reactions | увімкнено | Реагувати + перелік реакцій |
+| messages | увімкнено | Читання/надсилання/редагування/видалення |
+| pins | увімкнено | Закріпити/відкріпити/перелік |
+| memberInfo | увімкнено | Відомості про учасника |
+| emojiList | увімкнено | Список користувацьких emoji |
### Mattermost
@@ -496,10 +496,10 @@ Mattermost постачається як plugin: `openclaw plugins install @open
"team-channel-id": { requireMention: false },
},
commands: {
- native: true, // opt-in
+ native: true, // увімкнення за згодою
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
- // Необов’язковий явний URL для reverse proxy/публічних розгортань
+ // Необов’язкова явна URL-адреса для розгортань із reverse proxy/public
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
textChunkLimit: 4000,
@@ -509,23 +509,23 @@ Mattermost постачається як plugin: `openclaw plugins install @open
}
```
-Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (на кожне повідомлення), `onchar` (на повідомлення, що починаються з префікса-тригера).
+Режими чату: `oncall` (відповідати на @-згадку, за замовчуванням), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера).
-Коли увімкнені нативні команди Mattermost:
+Коли рідні команди Mattermost увімкнено:
-- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL.
-- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути досяжним із сервера Mattermost.
-- Нативні callback-и slash-команд автентифікуються за допомогою токенів кожної команди, які
- Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдасться або жодні
- команди не будуть активовані, OpenClaw відхилить callback-и з
+- `commands.callbackPath` має бути шляхом (наприклад, `/api/channels/mattermost/command`), а не повною URL-адресою.
+- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути доступною з сервера Mattermost.
+- Рідні зворотні виклики slash-команд автентифікуються за допомогою токенів для кожної команди, які
+ Mattermost повертає під час реєстрації slash-команди. Якщо реєстрація не вдалася або не
+ активовано жодної команди, OpenClaw відхиляє зворотні виклики з
`Unauthorized: invalid command token.`
-- Для приватних/tailnet/внутрішніх хостів callback-ів Mattermost може вимагати,
- щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а.
- Використовуйте значення хоста/домену, а не повні URL.
-- `channels.mattermost.configWrites`: дозволяти або забороняти ініційовані Mattermost записи в конфігурацію.
+- Для приватних/tailnet/internal хостів зворотних викликів Mattermost може вимагати,
+ щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику.
+ Використовуйте значення хоста/домену, а не повні URL-адреси.
+- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost.
- `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах.
-- `channels.mattermost.groups..requireMention`: перевизначення фільтрації за згадуваннями для окремого каналу (`"*"` для типового значення).
-- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
+- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадками для окремого каналу (`"*"` для значення за замовчуванням).
+- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
### Signal
@@ -546,15 +546,15 @@ Mattermost постачається як plugin: `openclaw plugins install @open
}
```
-**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`).
+**Режими сповіщень про реакції:** `off`, `own` (за замовчуванням), `all`, `allowlist` (із `reactionAllowlist`).
- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal.
-- `channels.signal.configWrites`: дозволяти або забороняти ініційовані Signal записи в конфігурацію.
-- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
+- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані із Signal.
+- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
### BlueBubbles
-BlueBubbles — рекомендований шлях для iMessage (на основі plugin, налаштовується під `channels.bluebubbles`).
+BlueBubbles — рекомендований шлях для iMessage (на базі plugin, налаштовується в `channels.bluebubbles`).
```json5
{
@@ -562,21 +562,21 @@ BlueBubbles — рекомендований шлях для iMessage (на ос
bluebubbles: {
enabled: true,
dmPolicy: "pairing",
- // serverUrl, password, webhookPath, керування групами й розширені дії:
+ // serverUrl, password, webhookPath, group controls та розширені дії:
// див. /channels/bluebubbles
},
},
}
```
-- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
-- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
-- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте BlueBubbles handle або target string (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- Ключові шляхи ядра, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
+- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
+- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сесій ACP. Використовуйте handle або цільовий рядок BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
- Повна конфігурація каналу BlueBubbles описана в [BlueBubbles](/uk/channels/bluebubbles).
### iMessage
-OpenClaw запускає `imsg rpc` (JSON-RPC поверх stdio). Демон або порт не потрібні.
+OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Не потрібні ні демон, ні порт.
```json5
{
@@ -600,15 +600,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC поверх stdio). Демон
}
```
-- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
+- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
-- Потребує Full Disk Access до БД Messages.
-- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів.
-- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP.
-- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`).
-- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ relay-хоста вже є в `~/.ssh/known_hosts`.
-- `channels.imessage.configWrites`: дозволяти або забороняти ініційовані iMessage записи в конфігурацію.
-- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- Потрібен Full Disk Access до бази даних Messages.
+- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів.
+- `cliPath` може вказувати на SSH-обгортку; встановіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP.
+- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (за замовчуванням: `/Users/*/Library/Messages/Attachments`).
+- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ ретранслятора вже існує в `~/.ssh/known_hosts`.
+- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage.
+- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
@@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
-Matrix працює через extension і налаштовується під `channels.matrix`.
+Matrix має підтримку через extension і налаштовується в `channels.matrix`.
```json5
{
@@ -651,25 +651,25 @@ Matrix працює через extension і налаштовується під
}
```
-- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем — `userId` + `password`.
-- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`.
-- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей opt-in для мережі — незалежні елементи керування.
-- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях.
-- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення в стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`.
-- `channels.matrix.execApprovals`: доставка схвалень exec у нативному форматі Matrix та авторизація схвалювачів.
- - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
- - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати exec-запити.
- - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо не вказано, пересилаються схвалення для всіх агентів.
+- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`.
+- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`.
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver-и. `proxy` і цей opt-in для мережі — незалежні елементи керування.
+- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами.
+- `channels.matrix.autoJoin` за замовчуванням дорівнює `off`, тому запрошені кімнати та нові запрошення у стилі особистих повідомлень ігноруються, доки ви не встановите `autoJoin: "allowlist"` із `autoJoinAllowlist` або `autoJoin: "always"`.
+- `channels.matrix.execApprovals`: власна доставка підтверджень exec у Matrix і авторизація схвалювачів.
+ - `enabled`: `true`, `false` або `"auto"` (за замовчуванням). В автоматичному режимі підтвердження exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`.
+ - `approvers`: ідентифікатори користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено схвалювати запити exec.
+ - `agentFilter`: необов’язковий список дозволених ідентифікаторів агентів. Не вказуйте, щоб пересилати підтвердження для всіх агентів.
- `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex).
- - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`.
- - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`.
-- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату.
-- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику proxy, що й runtime-трафік.
+ - `target`: куди надсилати запити на підтвердження. `"dm"` (за замовчуванням), `"channel"` (вихідна кімната) або `"both"`.
+ - Перевизначення для окремих облікових записів: `channels.matrix.accounts..execApprovals`.
+- `channels.matrix.dm.sessionScope` керує тим, як особисті повідомлення Matrix групуються в сесії: `per-user` (за замовчуванням) ділить за маршрутизованим співрозмовником, тоді як `per-room` ізолює кожну кімнату особистих повідомлень.
+- Перевірки стану Matrix і пошук у live-directory використовують ту саму політику проксі, що й трафік runtime.
- Повна конфігурація Matrix, правила адресації та приклади налаштування описані в [Matrix](/uk/channels/matrix).
### Microsoft Teams
-Microsoft Teams працює через extension і налаштовується під `channels.msteams`.
+Microsoft Teams має підтримку через extension і налаштовується в `channels.msteams`.
```json5
{
@@ -677,19 +677,19 @@ Microsoft Teams працює через extension і налаштовуєтьс
msteams: {
enabled: true,
configWrites: true,
- // appId, appPassword, tenantId, webhook, політики team/channel:
+ // appId, appPassword, tenantId, webhook, політики команд/каналів:
// див. /channels/msteams
},
},
}
```
-- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`.
-- Повна конфігурація Teams (облікові дані, webhook, політика DM/груп, перевизначення для команди/каналу) описана в [Microsoft Teams](/uk/channels/msteams).
+- Ключові шляхи ядра, описані тут: `channels.msteams`, `channels.msteams.configWrites`.
+- Повна конфігурація Teams (облікові дані, webhook, політика особистих/групових повідомлень, перевизначення для окремих команд/каналів) описана в [Microsoft Teams](/uk/channels/msteams).
### IRC
-IRC працює через extension і налаштовується під `channels.irc`.
+IRC має підтримку через extension і налаштовується в `channels.irc`.
```json5
{
@@ -710,11 +710,11 @@ IRC працює через extension і налаштовується під `ch
}
```
-- Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
-- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з налаштованим `account id`.
-- Повна конфігурація каналу IRC (host/port/TLS/channels/allowlists/фільтрація за згадуваннями) описана в [IRC](/uk/channels/irc).
+- Ключові шляхи ядра, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
+- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ідентифікатору облікового запису.
+- Повна конфігурація каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадками) описана в [IRC](/uk/channels/irc).
-### Багатообліковість (усі канали)
+### Кілька облікових записів (усі канали)
Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`):
@@ -738,27 +738,27 @@ IRC працює через extension і налаштовується під `ch
```
- `default` використовується, коли `accountId` пропущено (CLI + маршрутизація).
-- Токени з env застосовуються лише до облікового запису **default**.
-- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені на рівні облікового запису.
+- Токени середовища застосовуються лише до облікового запису **default**.
+- Базові параметри каналу застосовуються до всіх облікових записів, якщо не перевизначено їх окремо.
- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента.
-- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або онбординг каналу), коли ще використовується однокористувацька конфігурація верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня, що стосуються одного облікового запису, у карту облікових записів каналу, щоб оригінальний обліковий запис продовжив працювати. Для більшості каналів вони переміщуються в `channels..accounts.default`; Matrix може зберегти наявну відповідну іменовану/типову ціль.
-- Наявні прив’язки лише каналу (без `accountId`) і далі збігаються з обліковим записом за замовчуванням; прив’язки на рівні облікового запису лишаються необов’язковими.
-- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня, що належать одному обліковому запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/типову ціль.
+- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або onboarding каналу), залишаючись при цьому на верхньорівневій конфігурації каналу для одного облікового запису, OpenClaw спочатку піднімає верхньорівневі значення для одного облікового запису, прив’язані до облікового запису, у мапу облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщують їх до `channels..accounts.default`; Matrix може зберегти наявну відповідну іменовану/default-ціль.
+- Наявні прив’язки лише до каналу (без `accountId`) і надалі відповідатимуть обліковому запису за замовчуванням; прив’язки, прив’язані до облікового запису, залишаються необов’язковими.
+- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи верхньорівневі значення для одного облікового запису, прив’язані до облікового запису, до підвищеного облікового запису, вибраного для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/default-ціль.
-### Інші extension-канали
+### Інші канали extension
-Багато extension-каналів налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
-Повний індекс каналів: [Channels](/uk/channels).
+Багато каналів extension налаштовуються як `channels.` і описані на окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
+Див. повний індекс каналів: [Канали](/uk/channels).
-### Фільтрація за згадуваннями в групових чатах
+### Обмеження за згадками в групових чатах
-Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-патерни). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage.
+Для групових повідомлень за замовчуванням **потрібна згадка** (згадка в метаданих або безпечні regex-шаблони). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage.
**Типи згадок:**
-- **Metadata mentions**: нативні @-згадки платформи. Ігноруються в режимі self-chat у WhatsApp.
-- **Text patterns**: безпечні regex-патерни в `agents.list[].groupChat.mentionPatterns`. Невалідні патерни й небезпечні вкладені повторення ігноруються.
-- Фільтрація за згадуваннями застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один патерн).
+- **Згадки в метаданих**: рідні @-згадки платформи. Ігноруються в режимі чату із самим собою у WhatsApp.
+- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються.
+- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (рідні згадки або принаймні один шаблон).
```json5
{
@@ -771,9 +771,9 @@ IRC працює через extension і налаштовується під `ch
}
```
-`messages.groupChat.historyLimit` встановлює глобальне значення за замовчуванням. Канали можуть перевизначити його через `channels..historyLimit` (або на рівні облікового запису). Задайте `0`, щоб вимкнути.
+`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Встановіть `0`, щоб вимкнути.
-#### Ліміти історії для DM
+#### Ліміти історії особистих повідомлень
```json5
{
@@ -788,13 +788,13 @@ IRC працює через extension і налаштовується під `ch
}
```
-Розв’язання: перевизначення для конкретного DM → типове значення провайдера → без ліміту (зберігається все).
+Розв’язання: перевизначення для окремого DM → значення провайдера за замовчуванням → без обмеження (зберігається все).
Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
-#### Режим self-chat
+#### Режим чату із самим собою
-Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові патерни):
+Додайте свій власний номер до `allowFrom`, щоб увімкнути режим чату із самим собою (ігнорує рідні @-згадки, реагує лише на текстові шаблони):
```json5
{
@@ -820,9 +820,9 @@ IRC працює через extension і налаштовується під `ch
```json5
{
commands: {
- native: "auto", // реєструвати нативні команди, коли підтримується
+ native: "auto", // реєструвати рідні команди, якщо підтримуються
text: true, // розбирати /commands у повідомленнях чату
- bash: false, // дозволити ! (аліас: /bash)
+ bash: false, // дозволити ! (псевдонім: /bash)
bashForegroundMs: 2000,
config: false, // дозволити /config
debug: false, // дозволити /debug
@@ -839,25 +839,25 @@ IRC працює через extension і налаштовується під `ch
- Текстові команди мають бути **окремими** повідомленнями, що починаються з `/`.
-- `native: "auto"` вмикає нативні команди для Discord/Telegram, але залишає Slack вимкненим.
+- `native: "auto"` вмикає рідні команди для Discord/Telegram, але залишає їх вимкненими для Slack.
- Перевизначення для каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди.
-- `channels.telegram.customCommands` додає додаткові пункти меню бота Telegram.
-- `bash: true` вмикає `! ` для shell хоста. Потребує `tools.elevated.enabled` і того, щоб відправник був у `tools.elevated.allowFrom.`.
-- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи через `/config set|unset` також потребують `operator.admin`; read-only `/config show` лишається доступним для звичайних операторських клієнтів із правом запису.
-- `channels..configWrites` керує мутаціями конфігурації на рівні каналу (типово: true).
-- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`).
-- `allowFrom` задається для кожного провайдера. Якщо вказано, це **єдине** джерело авторизації (списки дозволених/сполучення каналу і `useAccessGroups` ігноруються).
-- `useAccessGroups: false` дозволяє командам обходити політики access group, коли `allowFrom` не задано.
+- `channels.telegram.customCommands` додає додаткові записи меню бота Telegram.
+- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`.
+- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; доступний лише для читання `/config show` залишається доступним звичайним клієнтам оператора з правом запису.
+- `channels..configWrites` керує мутаціями конфігурації для кожного каналу (за замовчуванням: true).
+- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`).
+- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених/сполучення каналу та `useAccessGroups` ігноруються).
+- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено.
---
-## Типові значення агентів
+## Значення агентів за замовчуванням
### `agents.defaults.workspace`
-Типове значення: `~/.openclaw/workspace`.
+За замовчуванням: `~/.openclaw/workspace`.
```json5
{
@@ -867,7 +867,7 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.repoRoot`
-Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt-а. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від workspace.
+Необов’язковий корінь репозиторію, що показується в рядку Runtime системного prompt-а. Якщо не встановлено, OpenClaw автоматично виявляє його, рухаючись вгору від workspace.
```json5
{
@@ -877,7 +877,7 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.skills`
-Необов’язковий типовий список дозволених Skills для агентів, які не задають
+Необов’язковий список дозволених Skills за замовчуванням для агентів, які не встановлюють
`agents.list[].skills`.
```json5
@@ -886,18 +886,18 @@ IRC працює через extension і налаштовується під `ch
defaults: { skills: ["github", "weather"] },
list: [
{ id: "writer" }, // успадковує github, weather
- { id: "docs", skills: ["docs-search"] }, // замінює типові значення
+ { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням
{ id: "locked-down", skills: [] }, // без Skills
],
},
}
```
-- Пропустіть `agents.defaults.skills`, щоб типово дозволити всі Skills без обмежень.
-- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення.
-- Задайте `agents.list[].skills: []`, щоб не було жодних Skills.
-- Непорожній список `agents.list[].skills` є кінцевим набором для цього агента; він
- не об’єднується з типовими значеннями.
+- Пропустіть `agents.defaults.skills`, щоб за замовчуванням не обмежувати Skills.
+- Пропустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
+- Встановіть `agents.list[].skills: []`, щоб не було жодних Skills.
+- Непорожній список `agents.list[].skills` є остаточним набором для цього агента;
+ він не об’єднується зі значеннями за замовчуванням.
### `agents.defaults.skipBootstrap`
@@ -911,9 +911,9 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.contextInjection`
-Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. Типове значення: `"always"`.
+Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. За замовчуванням: `"always"`.
-- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt-а. Запуски heartbeat і повторні спроби після compaction усе одно перебудовують контекст.
+- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt-а. Запуски heartbeat і повторні спроби після компакції все одно перебудовують контекст.
```json5
{
@@ -923,7 +923,7 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.bootstrapMaxChars`
-Максимальна кількість символів на bootstrap-файл workspace перед обрізанням. Типове значення: `20000`.
+Максимальна кількість символів на один bootstrap-файл workspace перед обрізанням. За замовчуванням: `20000`.
```json5
{
@@ -933,7 +933,7 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.bootstrapTotalMaxChars`
-Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типове значення: `150000`.
+Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. За замовчуванням: `150000`.
```json5
{
@@ -943,11 +943,11 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.bootstrapPromptTruncationWarning`
-Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається.
-Типове значення: `"once"`.
+Керує видимим для агента попереджувальним текстом, коли bootstrap-контекст обрізається.
+За замовчуванням: `"once"`.
-- `"off"`: ніколи не вставляти текст попередження в системний prompt.
-- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано).
+- `"off"`: ніколи не вставляти попередження в системний prompt.
+- `"once"`: вставляти попередження один раз для кожного унікального підпису обрізання (рекомендовано).
- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання.
```json5
@@ -958,10 +958,10 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.imageMaxDimensionPx`
-Максимальний розмір у пікселях для найдовшого боку зображення в блоках зображень транскрипту/інструментів перед викликами провайдера.
-Типове значення: `1200`.
+Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера.
+За замовчуванням: `1200`.
-Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скріншотів.
+Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для сценаріїв із великою кількістю скриншотів.
Більші значення зберігають більше візуальних деталей.
```json5
@@ -972,7 +972,7 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.userTimezone`
-Часовий пояс для контексту системного prompt-а (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста.
+Часовий пояс для контексту системного prompt-а (не для міток часу повідомлень). Якщо не встановлено, використовується часовий пояс хоста.
```json5
{
@@ -982,7 +982,7 @@ IRC працює через extension і налаштовується під `ch
### `agents.defaults.timeFormat`
-Формат часу в системному prompt-і. Типове значення: `auto` (налаштування ОС).
+Формат часу в системному prompt-і. За замовчуванням: `auto` (налаштування ОС).
```json5
{
@@ -1020,7 +1020,7 @@ IRC працює через extension і налаштовується під `ch
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
- params: { cacheRetention: "long" }, // глобальні типові параметри провайдера
+ params: { cacheRetention: "long" }, // глобальні параметри провайдера за замовчуванням
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
thinkingDefault: "low",
@@ -1036,63 +1036,63 @@ IRC працює через extension і налаштовується під `ch
```
- `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- - Рядкова форма задає лише основну модель.
- - Об’єктна форма задає основну модель плюс впорядковані резервні моделі.
+ - Рядкова форма встановлює лише основну модель.
+ - Форма об’єкта встановлює основну модель плюс впорядковані резервні моделі.
- `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується шляхом інструмента `image` як конфігурація vision-моделі.
- - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення.
+ - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення.
- `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/plugin, що генерує зображення.
- - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-1` для OpenAI Images.
- - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key для провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`).
- - Якщо поле пропущено, `image_generate` усе одно може вивести типового провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id.
+ - Типові значення: `google/gemini-3.1-flash-image-preview` для рідної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-1` для OpenAI Images.
+ - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`).
+ - Якщо не вказано, `image_generate` все одно може вивести значення за замовчуванням на основі автентифікації провайдера. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id.
- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`.
- Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`.
- - Якщо поле пропущено, `music_generate` усе одно може вивести типового провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики у порядку provider-id.
- - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key для провайдера.
+ - Якщо не вказано, `music_generate` все одно може вивести значення за замовчуванням на основі автентифікації провайдера. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id.
+ - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API key провайдера.
- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`.
- Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`.
- - Якщо поле пропущено, `video_generate` усе одно може вивести типового провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео у порядку provider-id.
- - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key для провайдера.
- - Вбудований провайдер генерації відео Qwen наразі підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`.
+ - Якщо не вказано, `video_generate` все одно може вивести значення за замовчуванням на основі автентифікації провайдера. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id.
+ - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API key провайдера.
+ - Вбудований провайдер генерації відео Qwen наразі підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`.
- `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- - Використовується інструментом `pdf` для маршрутизації моделей.
- - Якщо поле пропущено, інструмент PDF повертається до `imageModel`, а потім до розв’язаної моделі сесії/типової моделі.
-- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику.
-- `pdfMaxPages`: типова максимальна кількість сторінок, які враховуються в режимі резервного витягування в інструменті `pdf`.
-- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`.
-- `elevatedDefault`: типовий рівень elevated output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`.
-- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропустите провайдера, OpenClaw спершу спробує alias, потім унікальний збіг серед налаштованих провайдерів для цього точного model id, і лише після цього повернеться до типового налаштованого провайдера (застаріла поведінка сумісності, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення з видаленого провайдера.
+ - Використовується інструментом `pdf` для маршрутизації моделі.
+ - Якщо не вказано, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сесії/типової моделі.
+- `pdfMaxBytesMb`: ліміт розміру PDF за замовчуванням для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику.
+- `pdfMaxPages`: максимальна кількість сторінок за замовчуванням, яку враховує резервний режим витягування в інструменті `pdf`.
+- `verboseDefault`: рівень verbose для агентів за замовчуванням. Значення: `"off"`, `"on"`, `"full"`. За замовчуванням: `"off"`.
+- `elevatedDefault`: рівень elevated-output для агентів за замовчуванням. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. За замовчуванням: `"on"`.
+- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо ви пропустите провайдера, OpenClaw спочатку спробує псевдонім, потім — унікальний збіг серед налаштованих провайдерів для цього точного model id, і лише після цього повернеться до налаштованого провайдера за замовчуванням (застаріла сумісність, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повернеться до першого налаштованого provider/model замість того, щоб показувати застаріле значення за замовчуванням від видаленого провайдера.
- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
-- `params`: глобальні типові параметри провайдера, застосовані до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`).
-- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Подробиці див. у [Prompt Caching](/uk/reference/prompt-caching).
-- Засоби запису конфігурації, які мутують ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта і за можливості зберігають наявні списки fallback.
-- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4.
+- `params`: глобальні параметри провайдера за замовчуванням, що застосовуються до всіх моделей. Встановлюються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`).
+- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного agent id) перевизначає по ключах. Докладніше див. [Кешування prompt-ів](/uk/reference/prompt-caching).
+- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта і за можливості зберігають наявні списки резервних моделей.
+- `maxConcurrent`: максимальна кількість паралельних запусків агентів у різних сесіях (кожна сесія все одно серіалізується). За замовчуванням: 4.
-**Вбудовані скорочення alias** (застосовуються лише коли модель є в `agents.defaults.models`):
+**Вбудовані скорочені псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
-| Alias | Модель |
-| ------------------- | -------------------------------------- |
-| `opus` | `anthropic/claude-opus-4-6` |
-| `sonnet` | `anthropic/claude-sonnet-4-6` |
-| `gpt` | `openai/gpt-5.4` |
-| `gpt-mini` | `openai/gpt-5.4-mini` |
-| `gpt-nano` | `openai/gpt-5.4-nano` |
-| `gemini` | `google/gemini-3.1-pro-preview` |
-| `gemini-flash` | `google/gemini-3-flash-preview` |
-| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
+| Псевдонім | Модель |
+| ------------------ | -------------------------------------- |
+| `opus` | `anthropic/claude-opus-4-6` |
+| `sonnet` | `anthropic/claude-sonnet-4-6` |
+| `gpt` | `openai/gpt-5.4` |
+| `gpt-mini` | `openai/gpt-5.4-mini` |
+| `gpt-nano` | `openai/gpt-5.4-nano` |
+| `gemini` | `google/gemini-3.1-pro-preview` |
+| `gemini-flash` | `google/gemini-3-flash-preview` |
+| `gemini-flash-lite`| `google/gemini-3.1-flash-lite-preview` |
-Ваші налаштовані alias завжди мають пріоритет над типовими.
+Ваші налаштовані псевдоніми завжди мають пріоритет над типовими.
-Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`.
-Моделі Z.AI типово вмикають `tool_stream` для стримінгу викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це.
-Моделі Anthropic Claude 4.6 типово використовують thinking `adaptive`, коли явний рівень thinking не задано.
+Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самостійно не задасте `agents.defaults.models["zai/"].params.thinking`.
+Моделі Z.AI за замовчуванням вмикають `tool_stream` для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це.
+Моделі Anthropic Claude 4.6 за замовчуванням використовують `adaptive` thinking, коли явний рівень thinking не встановлено.
### `agents.defaults.cliBackends`
-Необов’язкові CLI backends для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють.
+Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють.
```json5
{
@@ -1120,8 +1120,8 @@ IRC працює через extension і налаштовується під `ch
}
```
-- CLI backends орієнтовані на текст; інструменти завжди вимкнені.
-- Сесії підтримуються, коли задано `sessionArg`.
+- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені.
+- Сесії підтримуються, якщо встановлено `sessionArg`.
- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів.
### `agents.defaults.heartbeat`
@@ -1136,12 +1136,12 @@ IRC працює через extension і налаштовується під `ch
every: "30m", // 0m вимикає
model: "openai/gpt-5.4-mini",
includeReasoning: false,
- lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів workspace
- isolatedSession: false, // типово: false; true запускає кожен heartbeat у новій сесії (без історії розмови)
+ lightContext: false, // за замовчуванням: false; true залишає лише HEARTBEAT.md із bootstrap-файлів workspace
+ isolatedSession: false, // за замовчуванням: false; true запускає кожен heartbeat у новій сесії (без історії розмови)
session: "main",
to: "+15555550123",
- directPolicy: "allow", // allow (типово) | block
- target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ...
+ directPolicy: "allow", // allow (за замовчуванням) | block
+ target: "none", // за замовчуванням: none | варіанти: last | whatsapp | telegram | discord | ...
prompt: "Прочитай HEARTBEAT.md, якщо він існує...",
ackMaxChars: 300,
suppressToolErrorWarnings: false,
@@ -1151,13 +1151,13 @@ IRC працює через extension і налаштовується під `ch
}
```
-- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути.
-- `suppressToolErrorWarnings`: якщо true, пригнічує payload-и з попередженнями про помилки інструментів під час запусків heartbeat.
-- `directPolicy`: політика прямої/DM-доставки. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і повертає `reason=dm-blocked`.
-- `lightContext`: якщо true, heartbeat-запуски використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace.
-- `isolatedSession`: якщо true, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у cron `sessionTarget: "isolated"`. Зменшує витрати токенів на heartbeat приблизно зі ~100K до ~2-5K токенів.
-- Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, heartbeat запускається **лише для цих агентів**.
-- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів.
+- `every`: рядок тривалості (ms/s/m/h). За замовчуванням: `30m` (автентифікація через API key) або `1h` (OAuth). Встановіть `0m`, щоб вимкнути.
+- `suppressToolErrorWarnings`: якщо true, пригнічує payload-и попереджень про помилки інструментів під час запусків heartbeat.
+- `directPolicy`: політика доставки напряму/в особисті повідомлення. `allow` (за замовчуванням) дозволяє доставку напряму. `block` пригнічує доставку напряму й видає `reason=dm-blocked`.
+- `lightContext`: якщо true, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів workspace.
+- `isolatedSession`: якщо true, кожен запуск heartbeat відбувається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у cron `sessionTarget: "isolated"`. Зменшує вартість токенів на heartbeat приблизно зі ~100K до ~2-5K токенів.
+- Для окремого агента: встановіть `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, heartbeat запускаються **лише для цих агентів**.
+- Heartbeat виконують повні ходи агента — коротші інтервали спалюють більше токенів.
### `agents.defaults.compaction`
@@ -1173,12 +1173,12 @@ IRC працює через extension і налаштовується під `ch
identifierInstructions: "Точно зберігай deployment ID, ticket ID і пари host:port.", // використовується, коли identifierPolicy=custom
postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторну вставку
model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction
- notifyUser: true, // надсилати коротке повідомлення, коли починається compaction (типово: false)
+ notifyUser: true, // надіслати коротке повідомлення користувачу, коли починається compaction (за замовчуванням: false)
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
- systemPrompt: "Сесія наближається до compaction. Збережи тривалі спогади зараз.",
- prompt: "Запиши будь-які довготривалі нотатки в memory/YYYY-MM-DD.md; відповідай точним silent token NO_REPLY, якщо зберігати нічого.",
+ systemPrompt: "Сесія наближається до compaction. Збережи сталі спогади зараз.",
+ prompt: "Запиши будь-які довготривалі нотатки в memory/YYYY-MM-DD.md; відповідай точним мовчазним токеном NO_REPLY, якщо немає чого зберігати.",
},
},
},
@@ -1186,18 +1186,18 @@ IRC працює через extension і налаштовується під `ch
}
```
-- `mode`: `default` або `safeguard` (підсумовування шматками для довгої історії). Див. [Compaction](/uk/concepts/compaction).
-- `timeoutSeconds`: максимальна кількість секунд, дозволених для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`.
-- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки зі збереження непрозорих ідентифікаторів під час підсумовування compaction.
-- `identifierInstructions`: необов’язковий користувацький текст для збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`.
-- `postCompactionSections`: необов’язкові назви секцій H2/H3 у AGENTS.md, які повторно вставляються після compaction. Типово `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторну вставку. Якщо не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як legacy fallback.
-- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має лишатися на одній моделі, а підсумки compaction мають створюватися на іншій; якщо не задано, compaction використовує основну модель сесії.
-- `notifyUser`: якщо `true`, надсилає користувачу коротке повідомлення, коли починається compaction (наприклад, "Compacting context..."). Типово вимкнено, щоб compaction відбувався тихо.
-- `memoryFlush`: тихий агентний хід перед auto-compaction для збереження довготривалих спогадів. Пропускається, коли workspace доступний лише для читання.
+- `mode`: `default` або `safeguard` (підсумовування великих історій частинами). Див. [Compaction](/uk/concepts/compaction).
+- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, перш ніж OpenClaw її перерве. За замовчуванням: `900`.
+- `identifierPolicy`: `strict` (за замовчуванням), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування в compaction.
+- `identifierInstructions`: необов’язковий користувацький текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`.
+- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md для повторної вставки після compaction. За замовчуванням `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторну вставку. Якщо не встановлено або явно встановлено цю пару за замовчуванням, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант.
+- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки compaction мають створюватися на іншій; якщо не встановлено, compaction використовує основну модель сесії.
+- `notifyUser`: коли `true`, надсилає користувачу коротке повідомлення, коли починається compaction (наприклад, "Compacting context..."). За замовчуванням вимкнено, щоб compaction відбувався безшумно.
+- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалих спогадів. Пропускається, коли workspace лише для читання.
### `agents.defaults.contextPruning`
-Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску.
+Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску.
```json5
{
@@ -1222,24 +1222,24 @@ IRC працює через extension і налаштовується під `ch
- `mode: "cache-ttl"` вмикає проходи обрізання.
-- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу).
-- Обрізання спочатку м’яко підрізає завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів.
+- `ttl` контролює, як часто обрізання може запускатися знову (після останнього торкання кешу).
+- Спочатку обрізання м’яко скорочує завеликі результати інструментів, а потім, якщо потрібно, жорстко очищає старіші результати інструментів.
-**М’яке обрізання** зберігає початок + кінець і вставляє `...` посередині.
+**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині.
**Жорстке очищення** замінює весь результат інструмента на заповнювач.
Примітки:
-- Блоки зображень ніколи не обрізаються/не очищаються.
-- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів.
-- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається.
+- Блоки зображень ніколи не обрізаються й не очищаються.
+- Співвідношення базуються на символах (приблизно), а не на точних підрахунках токенів.
+- Якщо існує менше ніж `keepLastAssistants` повідомлень помічника, обрізання пропускається.
-Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning).
+Докладніше про поведінку див. [Обрізання сесій](/uk/concepts/session-pruning).
-### Блочний стримінг
+### Блокова потокова передача
```json5
{
@@ -1249,19 +1249,19 @@ IRC працює через extension і налаштовується під `ch
blockStreamingBreak: "text_end", // text_end | message_end
blockStreamingChunk: { minChars: 800, maxChars: 1200 },
blockStreamingCoalesce: { idleMs: 1000 },
- humanDelay: { mode: "natural" }, // off | natural | custom (використовує minMs/maxMs)
+ humanDelay: { mode: "natural" }, // off | natural | custom (використовуйте minMs/maxMs)
},
},
}
```
-- Канали, відмінні від Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блочні відповіді.
-- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти на рівні облікового запису). Signal/Slack/Discord/Google Chat типово використовують `minChars: 1500`.
-- `humanDelay`: випадкова пауза між блочними відповідями. `natural` = 800–2500ms. Перевизначення для агента: `agents.list[].humanDelay`.
+- Для каналів, окрім Telegram, потрібне явне `*.blockStreaming: true`, щоб увімкнути блокові відповіді.
+- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Signal/Slack/Discord/Google Chat за замовчуванням використовують `minChars: 1500`.
+- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`.
-Деталі поведінки та розбиття на частини див. у [Streaming](/uk/concepts/streaming).
+Докладніше про поведінку та розбиття на фрагменти див. [Streaming](/uk/concepts/streaming).
-### Індикатори введення
+### Індикатори набору
```json5
{
@@ -1274,16 +1274,16 @@ IRC працює через extension і налаштовується під `ch
}
```
-- Типові значення: `instant` для приватних чатів/згадок, `message` для групових чатів без згадки.
+- За замовчуванням: `instant` для особистих чатів/згадок, `message` для групових чатів без згадки.
- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`.
-Див. [Typing Indicators](/uk/concepts/typing-indicators).
+Див. [Індикатори набору](/uk/concepts/typing-indicators).
### `agents.defaults.sandbox`
-Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing).
+Необов’язкове sandbox-ізолювання для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing).
```json5
{
@@ -1382,47 +1382,47 @@ IRC працює через extension і налаштовується під `ch
**Backend:**
-- `docker`: локальний runtime Docker (типово)
-- `ssh`: загальний віддалений runtime на основі SSH
+- `docker`: локальний Docker runtime (за замовчуванням)
+- `ssh`: загальний віддалений runtime через SSH
- `openshell`: runtime OpenShell
Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до
`plugins.entries.openshell.config`.
-**Конфігурація SSH backend:**
+**Конфігурація backend-а SSH:**
- `target`: SSH-ціль у форматі `user@host[:port]`
-- `command`: команда SSH-клієнта (типово: `ssh`)
-- `workspaceRoot`: абсолютний віддалений корінь, який використовується для workspace кожного scope
-- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH
-- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, який OpenClaw матеріалізує у тимчасові файли під час runtime
+- `command`: команда SSH-клієнта (за замовчуванням: `ssh`)
+- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за областями
+- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH
+- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime
- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH
-**Пріоритет SSH auth:**
+**Пріоритет автентифікації SSH:**
- `identityData` має пріоритет над `identityFile`
- `certificateData` має пріоритет над `certificateFile`
- `knownHostsData` має пріоритет над `knownHostsFile`
-- Значення `*Data`, що використовують SecretRef, розв’язуються з активного знімка runtime секретів до початку sandbox-сесії
+- Значення `*Data`, підкріплені SecretRef, розв’язуються з активного знімка runtime секретів до початку sandbox-сесії
-**Поведінка SSH backend:**
+**Поведінка backend-а SSH:**
-- один раз ініціалізує віддалений workspace після створення або перевідтворення
-- після цього підтримує віддалений SSH workspace як канонічний
-- маршрутизує `exec`, файлові інструменти й шляхи медіа через SSH
-- не синхронізує віддалені зміни назад на хост автоматично
+- один раз ініціалізує віддалений workspace після створення або повторного створення
+- потім підтримує віддалений SSH-workspace як канонічний
+- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH
+- не синхронізує автоматично віддалені зміни назад на хост
- не підтримує browser-контейнери в sandbox
**Доступ до workspace:**
-- `none`: sandbox workspace для кожного scope під `~/.openclaw/sandboxes`
-- `ro`: sandbox workspace у `/workspace`, workspace агента монтується як лише для читання в `/agent`
-- `rw`: workspace агента монтується з читанням/записом у `/workspace`
+- `none`: workspace sandbox за областями під `~/.openclaw/sandboxes`
+- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent`
+- `rw`: workspace агента монтується для читання/запису в `/workspace`
**Scope:**
-- `session`: окремий контейнер + workspace на сесію
-- `agent`: один контейнер + workspace на агента (типово)
+- `session`: окремий контейнер + workspace для кожної сесії
+- `agent`: один контейнер + workspace на агента (за замовчуванням)
- `shared`: спільний контейнер і workspace (без ізоляції між сесіями)
**Конфігурація plugin OpenShell:**
@@ -1440,7 +1440,7 @@ IRC працює через extension і налаштовується під `ch
remoteAgentWorkspaceDir: "/agent",
gateway: "lab", // необов’язково
gatewayEndpoint: "https://lab.example", // необов’язково
- policy: "strict", // необов’язковий ID політики OpenShell
+ policy: "strict", // необов’язковий policy id OpenShell
providers: ["openai"], // необов’язково
autoProviders: true,
timeoutSeconds: 120,
@@ -1453,30 +1453,30 @@ IRC працює через extension і налаштовується під `ch
**Режим OpenShell:**
-- `mirror`: ініціалізує віддалене середовище з локального перед exec, синхронізує назад після exec; локальний workspace лишається канонічним
-- `remote`: один раз ініціалізує віддалене середовище, коли sandbox створюється, а далі віддалений workspace лишається канонічним
+- `mirror`: ініціалізувати віддалене середовище з локального перед exec, синхронізувати назад після exec; локальний workspace залишається канонічним
+- `remote`: один раз ініціалізувати віддалене середовище під час створення sandbox, а потім підтримувати віддалений workspace як канонічний
-У режимі `remote` зміни на хості, зроблені локально поза OpenClaw, не синхронізуються в sandbox автоматично після етапу ініціалізації.
-Транспорт — SSH у sandbox OpenShell, але plugin керує життєвим циклом sandbox та необов’язковою mirror-синхронізацією.
+У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються автоматично в sandbox після етапу ініціалізації.
+Транспортом є SSH до sandbox OpenShell, але plugin керує життєвим циклом sandbox і необов’язковою mirror-синхронізацією.
-**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного root і користувача root.
+**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потрібні вихід у мережу, записуваний root і користувач root.
-**Контейнери типово використовують `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід назовні.
-`"host"` блокується. `"container:"` типово блокується, якщо ви явно не встановите
+**Контейнери за замовчуванням використовують `network: "none"`** — встановіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід у мережу.
+`"host"` заблоковано. `"container:"` заблоковано за замовчуванням, якщо ви явно не встановите
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass).
-**Вхідні вкладення** тимчасово розміщуються в `media/inbound/*` в активному workspace.
+**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace.
-**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки на рівні агента об’єднуються.
+**`docker.binds`** монтує додаткові каталоги хоста; глобальні та прив’язані до агента bind-и об’єднуються.
-**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний prompt. Не потребує `browser.enabled` у `openclaw.json`.
-Доступ для спостереження через noVNC типово використовує VNC auth, і OpenClaw видає короткоживучий token URL (замість того, щоб показувати пароль у спільному URL).
+**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний prompt. Не потребує `browser.enabled` у `openclaw.json`.
+Доступ спостерігача noVNC за замовчуванням використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL).
-- `allowHostControl: false` (типово) блокує sandbox-сесіям доступ до браузера хоста.
-- `network` типово дорівнює `openclaw-sandbox-browser` (окрема bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність.
-- `cdpSourceRange` необов’язково обмежує доступ до CDP на межі контейнера діапазоном CIDR (наприклад `172.21.0.1/32`).
-- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер sandbox browser. Якщо задано (включно з `[]`), замінює `docker.binds` для browser-контейнера.
-- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів із контейнерами:
+- `allowHostControl: false` (за замовчуванням) блокує націлювання sandbox-сесій на браузер хоста.
+- `network` за замовчуванням дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність.
+- `cdpSourceRange` за бажанням обмежує вхід CDP на межі контейнера CIDR-діапазоном (наприклад, `172.21.0.1/32`).
+- `sandbox.browser.binds` монтує додаткові каталоги хоста лише до контейнера браузера sandbox. Якщо встановлено (включно з `[]`), це замінює `docker.binds` для контейнера браузера.
+- Параметри запуску за замовчуванням визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для хостів контейнерів:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=`
- `--user-data-dir=${HOME}/.chrome`
@@ -1493,31 +1493,31 @@ IRC працює через extension і налаштовується під `ch
- `--renderer-process-limit=2`
- `--no-zygote`
- `--metrics-recording-only`
- - `--disable-extensions` (типово ввімкнено)
+ - `--disable-extensions` (за замовчуванням увімкнено)
- `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu`
- типово увімкнені, їх можна вимкнути за допомогою
+ увімкнені за замовчуванням і можуть бути вимкнені через
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо ваш робочий процес
- залежить від них.
+ від них залежить.
- `--renderer-process-limit=2` можна змінити через
- `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; задайте `0`, щоб використовувати
- типове обмеження Chromium.
- - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`.
- - Типові значення — це базова конфігурація образу контейнера; використовуйте власний browser image з власним
- entrypoint, щоб змінити типові параметри контейнера.
+ `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; встановіть `0`, щоб використати
+ стандартне обмеження процесів Chromium.
+ - плюс `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`.
+ - Значення за замовчуванням — це базова конфігурація образу контейнера; використовуйте власний образ браузера з власною
+ entrypoint, щоб змінити поведінку контейнера за замовчуванням.
-Browser sandboxing і `sandbox.docker.binds` наразі працюють лише з Docker.
+Browser sandboxing і `sandbox.docker.binds` наразі доступні лише для Docker.
Зібрати образи:
```bash
-scripts/sandbox-setup.sh # основний sandbox image
-scripts/sandbox-browser-setup.sh # необов’язковий browser image
+scripts/sandbox-setup.sh # основний образ sandbox
+scripts/sandbox-browser-setup.sh # необов’язковий образ браузера
```
-### `agents.list` (перевизначення на рівні агента)
+### `agents.list` (перевизначення для окремого агента)
```json5
{
@@ -1530,11 +1530,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
workspace: "~/.openclaw/workspace",
agentDir: "~/.openclaw/agents/main/agent",
model: "anthropic/claude-opus-4-6", // або { primary, fallbacks }
- thinkingDefault: "high", // перевизначення рівня thinking для агента
- reasoningDefault: "on", // перевизначення видимості reasoning для агента
- fastModeDefault: false, // перевизначення fast mode для агента
- params: { cacheRetention: "none" }, // перевизначає відповідні defaults.models params за ключем
- skills: ["docs-search"], // замінює agents.defaults.skills, коли задано
+ thinkingDefault: "high", // перевизначення рівня thinking для окремого агента
+ reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента
+ fastModeDefault: false, // перевизначення fast mode для окремого агента
+ params: { cacheRetention: "none" }, // перевизначає params відповідного defaults.models за ключами
+ skills: ["docs-search"], // замінює agents.defaults.skills, якщо встановлено
identity: {
name: "Samantha",
theme: "helpful sloth",
@@ -1565,24 +1565,24 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
}
```
-- `id`: стабільний ID агента (обов’язково).
-- `default`: якщо задано для кількох, перший перемагає (у лог записується попередження). Якщо не задано ніде, типовим є перший елемент списку.
-- `model`: рядкова форма перевизначає лише `primary`; об’єктна форма `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback-и). Cron jobs, які перевизначають лише `primary`, усе одно успадковують типові fallback-и, якщо ви не встановите `fallbacks: []`.
-- `params`: параметри потоку на рівні агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень на кшталт `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
-- `skills`: необов’язковий список дозволених Skills для агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли їх задано; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills.
-- `thinkingDefault`: необов’язковий типовий рівень thinking для агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення на рівні повідомлення або сесії.
-- `reasoningDefault`: необов’язкове типове значення видимості reasoning (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning на рівні повідомлення або сесії.
-- `fastModeDefault`: необов’язкове типове значення fast mode (`true | false`). Застосовується, коли не задано перевизначення fast mode на рівні повідомлення або сесії.
-- `runtime`: необов’язковий дескриптор runtime на рівні агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати ACP harness sessions.
-- `identity.avatar`: шлях відносно workspace, `http(s)` URL або `data:` URI.
-- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`.
-- `subagents.allowAgents`: список дозволених ID агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент).
-- Захист успадкування sandbox: якщо сесія-запитувач ізольована в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox.
-- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn` без `agentId` (примушує явно вибирати профіль; типово false).
+- `id`: стабільний ідентифікатор агента (обов’язково).
+- `default`: якщо встановлено кілька, перший має пріоритет (реєструється попередження). Якщо не встановлено жодного, значенням за замовчуванням є перший запис у списку.
+- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Cron-задачі, що перевизначають лише `primary`, усе ще успадковують резервні значення за замовчуванням, якщо не встановити `fallbacks: []`.
+- `params`: параметри потоку для окремого агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, наприклад `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
+- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли його встановлено; явний список замінює значення за замовчуванням замість об’єднання, а `[]` означає відсутність Skills.
+- `thinkingDefault`: необов’язковий рівень thinking за замовчуванням для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не встановлено перевизначення для окремого повідомлення чи сесії.
+- `reasoningDefault`: необов’язкове значення видимості reasoning за замовчуванням для окремого агента (`on | off | stream`). Застосовується, коли не встановлено перевизначення reasoning для окремого повідомлення чи сесії.
+- `fastModeDefault`: необов’язкове значення fast mode за замовчуванням для окремого агента (`true | false`). Застосовується, коли не встановлено перевизначення fast mode для окремого повідомлення чи сесії.
+- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовыми параметрами `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має за замовчуванням використовувати сесії ACP harness.
+- `identity.avatar`: шлях відносно workspace, URL `http(s)` або `data:` URI.
+- `identity` виводить значення за замовчуванням: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`.
+- `subagents.allowAgents`: список дозволених agent id для `sessions_spawn` (`["*"]` = будь-який; за замовчуванням: лише той самий агент).
+- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox.
+- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; за замовчуванням: false).
---
-## Багатоагентна маршрутизація
+## Маршрутизація між кількома агентами
Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
@@ -1601,16 +1601,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
}
```
-### Поля збігу прив’язки
+### Поля збігу прив’язок
-- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` за замовчуванням означає route), `acp` для постійних ACP-прив’язок розмов.
+- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, використовується route), `acp` для постійних прив’язок розмов ACP.
- `match.channel` (обов’язково)
-- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = обліковий запис за замовчуванням)
+- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = обліковий запис за замовчуванням)
- `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`)
- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу)
- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }`
-**Детермінований порядок збігу:**
+**Детермінований порядок збігів:**
1. `match.peer`
2. `match.guildId`
@@ -1619,9 +1619,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
5. `match.accountId: "*"` (на весь канал)
6. Агент за замовчуванням
-У межах кожного рівня перемагає перший відповідний запис `bindings`.
+У межах кожного рівня перший запис `bindings`, що збігається, має пріоритет.
-Для записів `type: "acp"` OpenClaw виконує пошук за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує вищенаведений рівневий порядок прив’язок route.
+Для записів `type: "acp"` OpenClaw визначає збіг за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує наведений вище порядок рівнів route-binding.
### Профілі доступу для окремих агентів
@@ -1643,7 +1643,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
-
+
```json5
{
@@ -1718,11 +1718,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
-Подробиці пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
+Докладніше про пріоритети див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
---
-## Session
+## Сесія
```json5
{
@@ -1744,7 +1744,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
- parentForkMaxTokens: 100000, // пропустити fork від батьківської гілки вище цього числа токенів (0 вимикає)
+ parentForkMaxTokens: 100000, // пропустити розгалуження від батьківської гілки вище цього ліміту токенів (0 вимикає)
maintenance: {
mode: "warn", // warn | enforce
pruneAfter: "30d",
@@ -1756,7 +1756,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
},
threadBindings: {
enabled: true,
- idleHours: 24, // типове автоматичне unfocus через неактивність у годинах (`0` вимикає)
+ idleHours: 24, // типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає)
maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає)
},
mainKey: "main", // застаріле (runtime завжди використовує "main")
@@ -1769,43 +1769,43 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
}
```
-
+
- **`scope`**: базова стратегія групування сесій для контекстів групових чатів.
- - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу.
- - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише коли потрібен спільний контекст).
-- **`dmScope`**: як групуються DM.
- - `main`: усі DM спільно використовують основну сесію.
- - `per-peer`: ізоляція за ID відправника між каналами.
- - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатоадресних inbox).
- - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій).
-- **`identityLinks`**: відображення канонічних ID на peers із префіксом провайдера для спільного використання сесій між каналами.
-- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за локальним часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує той, що спливає першим.
-- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`.
-- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення forked thread session (типово `100000`).
- - Якщо батьківський `totalTokens` вищий за це значення, OpenClaw запускає нову thread session замість успадкування історії транскрипту батьківської сесії.
- - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти форк від батьківської сесії.
-- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для основного кошика direct-chat.
-- **`agentToAgent.maxPingPongTurns`**: максимальна кількість взаємних ходів відповіді між агентами під час agent-to-agent обміну (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining.
-- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, з legacy alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона перемагає.
-- **`maintenance`**: керування очищенням і зберіганням session store.
+ - `per-sender` (за замовчуванням): кожен відправник отримує ізольовану сесію в межах контексту каналу.
+ - `global`: усі учасники контексту каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст).
+- **`dmScope`**: як групуються особисті повідомлення.
+ - `main`: усі особисті повідомлення використовують основну сесію.
+ - `per-peer`: ізолювати за sender id між каналами.
+ - `per-channel-peer`: ізолювати за каналом + відправником (рекомендовано для inbox-ів із багатьма користувачами).
+ - `per-account-channel-peer`: ізолювати за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів).
+- **`identityLinks`**: мапа канонічних id до peer-ів із префіксом провайдера для спільного використання сесій між каналами.
+- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, у кого строк закінчується раніше.
+- **`resetByType`**: перевизначення за типами (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`.
+- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення розгалуженої thread-сесії (за замовчуванням `100000`).
+ - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову thread-сесію замість успадкування історії transcript-а батьківської сесії.
+ - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії.
+- **`mainKey`**: застаріле поле. Runtime тепер завжди використовує `"main"` для основного bucket-а особистого чату.
+- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей туди-назад між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong.
+- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny має пріоритет.
+- **`maintenance`**: очищення сховища сесій + керування зберіганням.
- `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення.
- - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`).
- - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`).
- - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`).
- - `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути.
- - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` лише логує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії.
- - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`.
-- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до гілок.
- - `enabled`: головний прапорець за замовчуванням (провайдери можуть перевизначити; Discord використовує `channels.discord.threadBindings.enabled`)
- - `idleHours`: типове автоматичне unfocus через неактивність у годинах (`0` вимикає; провайдери можуть перевизначити)
+ - `pruneAfter`: граничний вік для застарілих записів (за замовчуванням `30d`).
+ - `maxEntries`: максимальна кількість записів у `sessions.json` (за замовчуванням `500`).
+ - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (за замовчуванням `10mb`).
+ - `resetArchiveRetention`: строк зберігання архівів transcript-а `*.reset.`. За замовчуванням дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути.
+ - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сесій. У режимі `warn` лише реєструє попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії.
+ - `highWaterBytes`: необов’язкова ціль після очищення бюджету. За замовчуванням дорівнює `80%` від `maxDiskBytes`.
+- **`threadBindings`**: глобальні значення за замовчуванням для функцій сесій, прив’язаних до гілок.
+ - `enabled`: головний типовий перемикач (провайдери можуть перевизначити; Discord використовує `channels.discord.threadBindings.enabled`)
+ - `idleHours`: типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає; провайдери можуть перевизначити)
- `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначити)
---
-## Messages
+## Повідомлення
```json5
{
@@ -1837,36 +1837,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
### Префікс відповіді
-Перевизначення на рівні каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`.
+Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`.
-Розв’язання (перемагає найконкретніше): account → channel → global. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`.
+Розв’язання (найспецифічніше має пріоритет): account → channel → global. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`.
-**Шаблонні змінні:**
+**Змінні шаблону:**
-| Змінна | Опис | Приклад |
-| ----------------- | --------------------- | --------------------------- |
-| `{model}` | Коротка назва моделі | `claude-opus-4-6` |
+| Змінна | Опис | Приклад |
+| ----------------- | ---------------------- | --------------------------- |
+| `{model}` | Коротка назва моделі | `claude-opus-4-6` |
| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` |
-| `{provider}` | Назва провайдера | `anthropic` |
-| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` |
-| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) |
+| `{provider}` | Назва провайдера | `anthropic` |
+| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` |
+| `{identity.name}` | Ім’я ідентичності агента | (те саме, що й `"auto"`) |
-Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`.
+Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`.
-### Реакція-підтвердження
+### Реакція підтвердження
-- Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути.
+- За замовчуванням береться з `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути.
- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`.
-- Порядок розв’язання: account → channel → `messages.ackReaction` → резерв із identity.
-- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`.
-- `removeAckAfterReply`: прибирає ack після відповіді в Slack, Discord і Telegram.
-- `messages.statusReactions.enabled`: вмикає реакції життєвого циклу статусу в Slack, Discord і Telegram.
- У Slack і Discord, якщо не задано, статусні реакції залишаються увімкненими, коли активні ack-реакції.
- У Telegram встановіть це явно в `true`, щоб увімкнути статусні реакції життєвого циклу.
+- Порядок розв’язання: account → channel → `messages.ackReaction` → резервне значення з identity.
+- Scope: `group-mentions` (за замовчуванням), `group-all`, `direct`, `all`.
+- `removeAckAfterReply`: видаляє ack після відповіді у Slack, Discord і Telegram.
+- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram.
+ У Slack і Discord, якщо не встановлено, статусні реакції залишаються увімкненими, коли активні ack-реакції.
+ У Telegram встановіть це явно в `true`, щоб увімкнути реакції статусу життєвого циклу.
### Вхідний debounce
-Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаться негайно. Керівні команди обходять debounce.
+Групує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce.
### TTS (text-to-speech)
@@ -1909,18 +1909,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
}
```
-- `auto` керує auto-TTS. `/tts off|always|inbound|tagged` перевизначає значення для сесії.
-- `summaryModel` перевизначає `agents.defaults.model.primary` для авто-підсумку.
-- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (opt-in).
-- API key беруться з резерву `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
+- `auto` керує автоматичним TTS. `/tts off|always|inbound|tagged` перевизначає це для сесії.
+- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку.
+- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням дорівнює `false` (потрібне явне ввімкнення).
+- API key резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок розв’язання: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`.
-- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як сумісний з OpenAI TTS server і послаблює перевірку model/voice.
+- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw розглядає його як OpenAI-сумісний TTS-сервер і послаблює перевірку model/voice.
---
## Talk
-Типові значення для режиму Talk (macOS/iOS/Android).
+Значення за замовчуванням для режиму Talk (macOS/iOS/Android).
```json5
{
@@ -1945,50 +1945,50 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
```
- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька Talk-провайдерів.
-- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються в `talk.providers.`.
-- Voice ID беруться з резерву `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
-- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef.
-- Резерв `ELEVENLABS_API_KEY` застосовується лише коли API key для Talk не налаштовано.
-- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні імена.
-- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після мовчання користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms на macOS і Android, 900 ms на iOS`).
+- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються до `talk.providers.`.
+- Voice ID резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
+- `providers.*.apiKey` приймає прості текстові рядки або об’єкти SecretRef.
+- Резервний `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано.
+- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви.
+- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надіслати transcript. Якщо не встановлено, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`).
---
-## Tools
+## Інструменти
### Профілі інструментів
`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`:
-Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються).
+Під час локального onboarding нові локальні конфігурації за замовчуванням отримують `tools.profile: "coding"`, якщо це поле не встановлено (наявні явні профілі зберігаються).
-| Профіль | Включає |
+| Профіль | Містить |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | лише `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
-| `full` | Без обмежень (те саме, що не задавати) |
+| `full` | Без обмежень (те саме, що не встановлено) |
### Групи інструментів
-| Група | Інструменти |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) |
-| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
+| Група | Інструменти |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) |
+| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
-| `group:memory` | `memory_search`, `memory_get` |
-| `group:web` | `web_search`, `x_search`, `web_fetch` |
-| `group:ui` | `browser`, `canvas` |
-| `group:automation` | `cron`, `gateway` |
-| `group:messaging` | `message` |
-| `group:nodes` | `nodes` |
-| `group:agents` | `agents_list` |
-| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
-| `group:openclaw` | Усі вбудовані інструменти (без provider plugin-ів) |
+| `group:memory` | `memory_search`, `memory_get` |
+| `group:web` | `web_search`, `x_search`, `web_fetch` |
+| `group:ui` | `browser`, `canvas` |
+| `group:automation` | `cron`, `gateway` |
+| `group:messaging` | `message` |
+| `group:nodes` | `nodes` |
+| `group:agents` | `agents_list` |
+| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
+| `group:openclaw` | Усі вбудовані інструменти (без plugin-провайдерів) |
### `tools.allow` / `tools.deny`
-Глобальна політика дозволу/заборони інструментів (заборона перемагає). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть коли Docker sandbox вимкнений.
+Глобальна політика allow/deny для інструментів (deny має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено.
```json5
{
@@ -1998,7 +1998,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
### `tools.byProvider`
-Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny.
+Додатково обмежує інструменти для певних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny.
```json5
{
@@ -2014,7 +2014,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
### `tools.elevated`
-Керує elevated-доступом exec поза sandbox:
+Керує підвищеним доступом exec поза sandbox:
```json5
{
@@ -2030,9 +2030,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
}
```
-- Перевизначення для агента (`agents.list[].tools.elevated`) може лише додатково обмежити.
-- `/elevated on|off|ask|full` зберігає стан для сесії; inline directives застосовуються до одного повідомлення.
-- Elevated `exec` обходить sandbox і використовує налаштований escape path (`gateway` типово або `node`, коли ціллю exec є `node`).
+- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати.
+- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються лише до одного повідомлення.
+- Підвищений `exec` обходить sandboxing і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціллю exec є `node`).
### `tools.exec`
@@ -2056,8 +2056,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
### `tools.loopDetection`
-Перевірки безпеки від циклів інструментів **типово вимкнені**. Встановіть `enabled: true`, щоб увімкнути виявлення.
-Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`.
+Перевірки безпеки циклів інструментів **вимкнено за замовчуванням**. Установіть `enabled: true`, щоб увімкнути виявлення.
+Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента через `agents.list[].tools.loopDetection`.
```json5
{
@@ -2079,13 +2079,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
```
- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів.
-- `warningThreshold`: поріг повторюваного патерна без прогресу для попереджень.
+- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень.
- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів.
- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу.
- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами.
-- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо).
-- `detectors.pingPong`: попереджати/блокувати про чергування пар без прогресу.
-- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою.
+- `detectors.knownPollNoProgress`: попереджати/блокувати для відомих poll-інструментів (`process.poll`, `command_status` тощо).
+- `detectors.pingPong`: попереджати/блокувати для чергувальних парних шаблонів без прогресу.
+- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка валідації не проходить.
### `tools.web`
@@ -2095,14 +2095,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
web: {
search: {
enabled: true,
- apiKey: "brave_api_key", // або BRAVE_API_KEY env
+ apiKey: "brave_api_key", // або змінна середовища BRAVE_API_KEY
maxResults: 5,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
},
fetch: {
enabled: true,
- provider: "firecrawl", // необов’язково; пропустіть для auto-detect
+ provider: "firecrawl", // необов’язково; пропустіть для автоматичного виявлення
maxChars: 50000,
maxCharsCap: 50000,
maxResponseBytes: 2000000,
@@ -2127,7 +2127,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
media: {
concurrency: 2,
asyncCompletion: {
- directSend: false, // opt-in: надсилати завершені асинхронні задачі music/video безпосередньо в канал
+ directSend: false, // увімкнення за згодою: надсилати завершені асинхронні music/video безпосередньо в канал
},
audio: {
enabled: true,
@@ -2155,28 +2155,28 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
**Запис провайдера** (`type: "provider"` або пропущено):
-- `provider`: ID API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо)
+- `provider`: id API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо)
- `model`: перевизначення model id
- `profile` / `preferredProfile`: вибір профілю `auth-profiles.json`
**Запис CLI** (`type: "cli"`):
- `command`: виконуваний файл
-- `args`: шаблонні аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо)
+- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо)
**Спільні поля:**
-- `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
+- `capabilities`: необов’язковий список (`image`, `audio`, `video`). За замовчуванням: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису.
-- Помилки призводять до fallback на наступний запис.
+- У разі збою використовується наступний запис.
-Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`.
+Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`.
-**Поля async completion:**
+**Поля асинхронного завершення:**
-- `asyncCompletion.directSend`: коли `true`, завершені асинхронні задачі `music_generate`
- і `video_generate` спочатку намагаються доставитися прямо в канал. Типове значення: `false`
- (застарілий шлях requester-session wake/model-delivery).
+- `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate`
+ і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. За замовчуванням: `false`
+ (застарілий шлях пробудження сесії запитувача/доставки моделі).
@@ -2195,9 +2195,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
### `tools.sessions`
-Керує тим, на які сесії можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`).
+Керує тим, на які сесії можуть бути націлені інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`).
-Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents).
+За замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти).
```json5
{
@@ -2213,22 +2213,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
Примітки:
- `self`: лише поточний ключ сесії.
-- `tree`: поточна сесія + сесії, породжені поточною сесією (subagents).
-- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента).
+- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти).
+- `agent`: будь-яка сесія, що належить поточному agent id (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим agent id).
- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`.
-- Затискач sandbox: коли поточна сесія ізольована і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово стає `tree`, навіть якщо `tools.sessions.visibility="all"`.
+- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
### `tools.sessions_spawn`
-Керує підтримкою inline-вкладень для `sessions_spawn`.
+Керує підтримкою вбудованих вкладень для `sessions_spawn`.
```json5
{
tools: {
sessions_spawn: {
attachments: {
- enabled: false, // opt-in: встановіть true, щоб дозволити inline-вкладення файлів
- maxTotalBytes: 5242880, // 5 MB сумарно для всіх файлів
+ enabled: false, // увімкнення за згодою: встановіть true, щоб дозволити вбудовані файлові вкладення
+ maxTotalBytes: 5242880, // 5 MB загалом для всіх файлів
maxFiles: 50,
maxFileBytes: 1048576, // 1 MB на файл
retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep"
@@ -2240,16 +2240,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
Примітки:
-- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє.
-- Файли матеріалізуються в дочірньому workspace під `.openclaw/attachments//` з `.manifest.json`.
-- Вміст вкладень автоматично редагується з персистентності транскрипту.
-- Входи Base64 перевіряються зі строгими перевірками алфавіту/падінгу і захистом за розміром до декодування.
+- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP відхиляє їх.
+- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` із `.manifest.json`.
+- Вміст вкладень автоматично редагується під час збереження transcript-а.
+- Входи base64 перевіряються суворою перевіркою алфавіту/паддінгу і захистом від завеликого розміру до декодування.
- Права доступу до файлів: `0700` для каталогів і `0600` для файлів.
-- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
+- Очищення слідує політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`.
### `tools.experimental`
-Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не діє правило auto-enable, специфічне для runtime.
+Експериментальні прапорці для вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоматичного ввімкнення, залежне від runtime.
```json5
{
@@ -2264,8 +2264,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
Примітки:
- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи.
-- Типове значення: `false` для не-OpenAI провайдерів. Запуски OpenAI і OpenAI Codex автоматично вмикають його.
-- Коли він увімкнений, системний prompt також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала максимум один крок у стані `in_progress`.
+- За замовчуванням: `false` для не-OpenAI провайдерів. Запуски OpenAI та OpenAI Codex вмикають його автоматично.
+- Коли увімкнено, системний prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи та тримала не більш як один крок у стані `in_progress`.
### `agents.defaults.subagents`
@@ -2285,21 +2285,21 @@ scripts/sandbox-browser-setup.sh # необов’язковий browser image
}
```
-- `model`: типова модель для породжених sub-agents. Якщо не задано, sub-agents успадковують модель викликувача.
-- `allowAgents`: типовий список дозволених цільових ID агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент).
-- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає без тайм-ауту.
-- Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
+- `model`: модель за замовчуванням для породжених субагентів. Якщо не вказано, субагенти успадковують модель викликача.
+- `allowAgents`: список дозволених цільових agent id за замовчуванням для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент).
+- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність тайм-ауту.
+- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
## Користувацькі провайдери та base URL
-OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`.
+OpenClaw використовує вбудований каталог моделей. Додайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`.
```json5
{
models: {
- mode: "merge", // merge (типово) | replace
+ mode: "merge", // merge (за замовчуванням) | replace
providers: {
"custom-proxy": {
baseUrl: "http://localhost:4000/v1",
@@ -2324,45 +2324,46 @@ OpenClaw використовує вбудований каталог модел
```
- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації.
-- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища).
-- Пріоритет злиття для однакових provider ID:
- - Непорожні значення `baseUrl` в agent `models.json` мають пріоритет.
- - Непорожні значення `apiKey` в agent мають пріоритет лише коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile.
- - Значення `apiKey` провайдера, керовані SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження розв’язаних секретів.
- - Значення заголовків провайдера, керовані SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs).
- - Порожні або відсутні `apiKey`/`baseUrl` в agent повертаються до `models.providers` у конфігурації.
- - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу.
- - Для однакових моделей `contextTokens` зберігає явний runtime cap, коли він заданий; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі.
+- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища).
+- Пріоритет об’єднання для однакових provider ID:
+ - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет.
+ - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile.
+ - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження розв’язаних секретів.
+ - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs).
+ - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації.
+ - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу.
+ - Для однакових моделей `contextTokens` зберігає явну межу runtime, якщо вона є; використовуйте це для обмеження ефективного контексту без зміни нативних метаданих моделі.
- Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`.
- - Персистентність маркерів є авторитетною від джерела: маркери записуються з активного знімка вихідної конфігурації (до розв’язання), а не з розв’язаних runtime-значень секретів.
+ - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень runtime-секретів.
### Деталі полів провайдера
- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`).
-- `models.providers`: карта користувацьких провайдерів за provider id.
+- `models.providers`: мапа користувацьких провайдерів, ключована за provider id.
- `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо).
-- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/env substitution).
+- `models.providers.*.apiKey`: облікові дані провайдера (бажано через SecretRef/env substitution).
- `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`).
-- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions`, вставляє `options.num_ctx` у запити (типово: `true`).
-- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно.
-- `models.providers.*.baseUrl`: базовий URL upstream API.
+- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions`, вставляти `options.num_ctx` у запити (за замовчуванням: `true`).
+- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, якщо це потрібно.
+- `models.providers.*.baseUrl`: базова URL-адреса upstream API.
- `models.providers.*.headers`: додаткові статичні заголовки для proxy/tenant routing.
- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider.
- - `request.headers`: додаткові заголовки (зливаються з типовими заголовками провайдера). Значення приймають SecretRef.
+ - `request.headers`: додаткові заголовки (об’єднуються зі значеннями провайдера за замовчуванням). Значення підтримують SecretRef.
- `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`).
- - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`.
- - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`.
+ - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими підтримують необов’язковий підоб’єкт `tls`.
+ - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі підтримують SecretRef), `serverName`, `insecureSkipVerify`.
- `models.providers.*.models`: явні записи каталогу моделей провайдера.
-- `models.providers.*.models.*.contextWindow`: нативні метадані вікна контексту моделі.
-- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі.
-- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI.
-- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань auto-discovery Bedrock.
-- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для знайдених моделей.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для знайдених моделей.
+- `models.providers.*.models.*.contextWindow`: метадані нативного context window моделі.
+- `models.providers.*.models.*.contextTokens`: необов’язкова runtime-межа контексту. Використовуйте це, якщо хочете менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі.
+- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім не-нативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI.
+- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для string-only OpenAI-сумісних chat-endpoint-ів. Коли `true`, OpenClaw сплющує чисто текстові масиви `messages[].content` у звичайні рядки перед надсиланням запиту.
+- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ налаштувань автоматичного виявлення Bedrock.
+- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне context window для виявлених моделей.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервне максимальне число вихідних токенів для виявлених моделей.
### Приклади провайдерів
@@ -2400,7 +2401,7 @@ OpenClaw використовує вбудований каталог модел
}
```
-Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI.
+Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для Z.AI напряму.
@@ -2417,7 +2418,7 @@ OpenClaw використовує вбудований каталог модел
}
```
-Встановіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`.
+Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`.
@@ -2434,11 +2435,11 @@ OpenClaw використовує вбудований каталог модел
}
```
-Встановіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні alias. Скорочення: `openclaw onboard --auth-choice zai-api-key`.
+Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`.
- Загальний endpoint: `https://api.z.ai/api/paas/v4`
-- Coding endpoint (типовий): `https://api.z.ai/api/coding/paas/v4`
-- Для загального endpoint задайте користувацького провайдера з перевизначенням base URL.
+- Endpoint для кодування (за замовчуванням): `https://api.z.ai/api/coding/paas/v4`
+- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL.
@@ -2477,167 +2478,7 @@ OpenClaw використовує вбудований каталог модел
}
```
-Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`.
+Для endpoint-а в Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`.
-Нативні endpoint-и Moonshot оголошують сумісність використання streaming на спільному
-транспорті `openai-completions`, і OpenClaw тепер визначає це за можливостями endpoint-а,
-а не лише за вбудованим provider id.
-
-
-
-
-
-```json5
-{
- env: { KIMI_API_KEY: "sk-..." },
- agents: {
- defaults: {
- model: { primary: "kimi/kimi-code" },
- models: { "kimi/kimi-code": { alias: "Kimi Code" } },
- },
- },
-}
-```
-
-Сумісний з Anthropic вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`.
-
-
-
-
-
-```json5
-{
- env: { SYNTHETIC_API_KEY: "sk-..." },
- agents: {
- defaults: {
- model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
- models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
- },
- },
- models: {
- mode: "merge",
- providers: {
- synthetic: {
- baseUrl: "https://api.synthetic.new/anthropic",
- apiKey: "${SYNTHETIC_API_KEY}",
- api: "anthropic-messages",
- models: [
- {
- id: "hf:MiniMaxAI/MiniMax-M2.5",
- name: "MiniMax M2.5",
- reasoning: true,
- input: ["text"],
- cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
- contextWindow: 192000,
- maxTokens: 65536,
- },
- ],
- },
- },
- },
-}
-```
-
-Base URL має бути без `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`.
-
-
-
-
-
-```json5
-{
- agents: {
- defaults: {
- model: { primary: "minimax/MiniMax-M2.7" },
- models: {
- "minimax/MiniMax-M2.7": { alias: "Minimax" },
- },
- },
- },
- models: {
- mode: "merge",
- providers: {
- minimax: {
- baseUrl: "https://api.minimax.io/anthropic",
- apiKey: "${MINIMAX_API_KEY}",
- api: "anthropic-messages",
- models: [
- {
- id: "MiniMax-M2.7",
- name: "MiniMax M2.7",
- reasoning: true,
- input: ["text", "image"],
- cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
- contextWindow: 204800,
- maxTokens: 131072,
- },
- ],
- },
- },
- },
-}
-```
-
-Встановіть `MINIMAX_API_KEY`. Скорочення:
-`openclaw onboard --auth-choice minimax-global-api` або
-`openclaw onboard --auth-choice minimax-cn-api`.
-Каталог моделей тепер типово включає лише M2.7.
-На streaming path, сумісному з Anthropic, OpenClaw типово вимикає thinking MiniMax,
-якщо ви явно не задасте `thinking` самі. `/fast on` або
-`params.fastMode: true` переписує `MiniMax-M2.7` на
-`MiniMax-M2.7-highspeed`.
-
-
-
-
-
-Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному залізі; залишайте hosted-моделі злитими як резерв.
-
-
-
----
-
-## Skills
-
-```json5
-{
- skills: {
- allowBundled: ["gemini", "peekaboo"],
- load: {
- extraDirs: ["~/Projects/agent-scripts/skills"],
- },
- install: {
- preferBrew: true,
- nodeManager: "npm", // npm | pnpm | yarn | bun
- },
- entries: {
- "image-lab": {
- apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або відкритий рядок
- env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
- },
- peekaboo: { enabled: true },
- sag: { enabled: false },
- },
- },
-}
-```
-
-- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (managed/workspace Skills не зачіпає).
-- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет).
-- `install.preferBrew`: якщо true, віддавати перевагу встановлювачам Homebrew, коли `brew`
- доступний, перш ніж переходити до інших типів встановлювачів.
-- `install.nodeManager`: пріоритет node installer для специфікацій `metadata.openclaw.install`
- (`npm` | `pnpm` | `yarn` | `bun`).
-- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/installed.
-- `entries..apiKey`: зручне поле API key для Skills, які оголошують основну env var (відкритий рядок або об’єкт SecretRef).
-
----
-
-## Plugins
-
-```json5
-{
- plugins: {
- enabled: true,
- allow: ["voice-call"],
- deny:
\ No newline at end of file
+Нативні endpoint-и Moonshot оголошують сумісність із потоковим використанням на спільному
+транспорті `open
\ No newline at end of file
diff --git a/docs/uk/gateway/local-models.md b/docs/uk/gateway/local-models.md
index 49166345e..53e771d8f 100644
--- a/docs/uk/gateway/local-models.md
+++ b/docs/uk/gateway/local-models.md
@@ -3,26 +3,26 @@ read_when:
- Ви хочете обслуговувати моделі зі свого GPU-сервера
- Ви налаштовуєте LM Studio або OpenAI-сумісний проксі
- Вам потрібні найбезпечніші рекомендації щодо локальних моделей
-summary: Запуск OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, власні OpenAI-сумісні endpoint)
+summary: Запускайте OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, власні OpenAI-сумісні ендпоїнти)
title: Локальні моделі
x-i18n:
- generated_at: "2026-04-05T18:03:36Z"
+ generated_at: "2026-04-07T14:58:36Z"
model: gpt-5.4
provider: openai
- source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6
+ source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8
source_path: gateway/local-models.md
workflow: 15
---
# Локальні моделі
-Локальний запуск можливий, але OpenClaw очікує великий контекст + сильний захист від prompt injection. Невеликі карти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на високий рівень: **≥2 повністю укомплектованих Mac Studio або еквівалентний GPU-риг (~$30k+)**. Одна GPU на **24 GB** підходить лише для легших prompt із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “small” checkpoint підвищують ризик prompt injection (див. [Security](/gateway/security)).
+Локальний запуск можливий, але OpenClaw очікує великий контекст і сильний захист від інʼєкції промптів. Невеликі карти обрізають контекст і послаблюють безпеку. Орієнтуйтеся на серйозне обладнання: **≥2 Mac Studio з максимальною конфігурацією або еквівалентну GPU-систему (~$30k+)**. Один GPU на **24 ГБ** підходить лише для легших промптів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який ви можете запустити**; агресивно квантизовані або “small” чекпойнти підвищують ризик інʼєкції промптів (див. [Безпека](/uk/gateway/security)).
-Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть з [Ollama](/providers/ollama) і `openclaw onboard`. Ця сторінка — практичний посібник для потужніших локальних стеків і власних локальних серверів, сумісних з OpenAI.
+Якщо вам потрібне локальне налаштування з найменшими труднощами, почніть з [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — рекомендаційний посібник для більш потужних локальних стеків і власних OpenAI-сумісних локальних серверів.
## Рекомендовано: LM Studio + велика локальна модель (Responses API)
-Найкращий поточний локальний стек. Завантажте велику модель у LM Studio (наприклад, повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово `http://127.0.0.1:1234`) і використовуйте Responses API, щоб тримати міркування окремо від фінального тексту.
+Найкращий поточний локальний стек. Завантажте велику модель у LM Studio (наприклад, повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово `http://127.0.0.1:1234`) і використовуйте Responses API, щоб відокремити міркування від фінального тексту.
```json5
{
@@ -61,16 +61,16 @@ x-i18n:
**Контрольний список налаштування**
-- Установіть LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
-- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small”/сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` її показує.
-- Замініть `my-local-model` на фактичний ID моделі, показаний у LM Studio.
-- Тримайте модель завантаженою; холодне завантаження додає затримку запуску.
-- За потреби скоригуйте `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється.
-- Для WhatsApp використовуйте Responses API, щоб надсилався лише фінальний текст.
+- Встановіть LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
+- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте варіантів “small”/сильно квантизованих), запустіть сервер, переконайтеся, що `http://127.0.0.1:1234/v1/models` показує її.
+- Замініть `my-local-model` на фактичний ідентифікатор моделі, показаний у LM Studio.
+- Тримайте модель завантаженою; холодне завантаження додає затримку під час запуску.
+- Скоригуйте `contextWindow`/`maxTokens`, якщо у вашій збірці LM Studio вони відрізняються.
+- Для WhatsApp дотримуйтеся Responses API, щоб надсилався лише фінальний текст.
-Тримайте hosted-моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб резервні варіанти залишалися доступними.
+Залишайте хостовані моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб резервні варіанти залишалися доступними.
-### Гібридна конфігурація: hosted primary, локальний fallback
+### Гібридна конфігурація: основна хостована модель, локальний резервний варіант
```json5
{
@@ -111,18 +111,18 @@ x-i18n:
}
```
-### Спочатку локально, із hosted safety net
+### Спочатку локально, із хостованою страховкою
-Поміняйте місцями primary і fallback; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було перейти на Sonnet або Opus, коли локальний сервер недоступний.
+Поміняйте місцями основну модель і резервні варіанти; збережіть той самий блок providers і `models.mode: "merge"`, щоб мати змогу переключитися на Sonnet або Opus, коли локальний сервер недоступний.
### Регіональний хостинг / маршрутизація даних
-- Hosted-варіанти MiniMax/Kimi/GLM також існують на OpenRouter з endpoint, прив’язаними до регіону (наприклад, розміщеними у США). Виберіть там регіональний варіант, щоб трафік залишався у вибраній вами юрисдикції, і водночас використовуйте `models.mode: "merge"` для fallback на Anthropic/OpenAI.
-- Лише локальний запуск залишається найсильнішим варіантом для приватності; регіональна маршрутизація hosted — це проміжний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних.
+- Хостовані варіанти MiniMax/Kimi/GLM також доступні в OpenRouter з ендпоїнтами, привʼязаними до регіону (наприклад, хостинг у США). Виберіть там регіональний варіант, щоб трафік залишався у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для резервних варіантів Anthropic/OpenAI.
+- Лише локальний запуск залишається найсильнішим шляхом до конфіденційності; регіональна хостована маршрутизація — це компромісний варіант, коли вам потрібні можливості провайдера, але ви хочете контролювати потік даних.
## Інші OpenAI-сумісні локальні проксі
-vLLM, LiteLLM, OAI-proxy або власні gateway працюють, якщо вони надають OpenAI-подібний endpoint `/v1`. Замініть блок provider вище своїм endpoint і ID моделі:
+vLLM, LiteLLM, OAI-proxy або власні шлюзи працюють, якщо вони надають OpenAI-подібний ендпоїнт `/v1`. Замініть наведений вище блок provider на свій ендпоїнт та ідентифікатор моделі:
```json5
{
@@ -150,20 +150,40 @@ vLLM, LiteLLM, OAI-proxy або власні gateway працюють, якщо
}
```
-Зберігайте `models.mode: "merge"`, щоб hosted-моделі залишалися доступними як fallback.
+Зберігайте `models.mode: "merge"`, щоб хостовані моделі залишалися доступними як резервні варіанти.
-Примітка щодо поведінки для локальних/проксійованих бекендів `/v1`:
+Примітка щодо поведінки локальних/проксійованих бекендів `/v1`:
-- OpenClaw трактує їх як проксі-подібні OpenAI-сумісні маршрути, а не як нативні endpoint OpenAI
-- нативне формування запитів, доступне лише для OpenAI, тут не застосовується: немає
- `service_tier`, немає Responses `store`, немає формування payload сумісності
- reasoning OpenAI і немає підказок для prompt cache
-- приховані службові заголовки OpenClaw (`originator`, `version`, `User-Agent`)
- не додаються до цих користувацьких проксі-URL
+- OpenClaw розглядає їх як проксі-подібні OpenAI-сумісні маршрути, а не як нативні ендпоїнти OpenAI
+- формування запитів, притаманне лише нативному OpenAI, тут не застосовується: без
+ `service_tier`, без Responses `store`, без формування payload сумісності з OpenAI reasoning
+ і без підказок для кешу промптів
+- приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`)
+ не додаються до цих власних проксі-URL
-## Усунення проблем
+Примітки щодо сумісності для суворіших OpenAI-сумісних бекендів:
+
+- Деякі сервери приймають у Chat Completions лише рядковий `messages[].content`, а не
+ структуровані масиви частин контенту. Для
+ таких ендпоїнтів установіть `models.providers..models[].compat.requiresStringContent: true`.
+- Деякі менші або суворіші локальні бекенди нестабільно працюють із повною
+ формою промптів runtime агента OpenClaw, особливо коли включені схеми інструментів. Якщо
+ бекенд працює для маленьких прямих викликів `/v1/chat/completions`, але збій відбувається на звичайних
+ ходах агента OpenClaw, спочатку спробуйте
+ `models.providers..models[].compat.supportsTools: false`.
+- Якщо бекенд усе ще збоїть лише на більших запусках OpenClaw, то, як правило, проблема
+ у можливостях моделі/сервера на стороні апстріму або в помилці бекенда, а не в транспортному
+ шарі OpenClaw.
+
+## Усунення несправностей
- Gateway може дістатися до проксі? `curl http://127.0.0.1:1234/v1/models`.
-- Модель LM Studio вивантажена? Завантажте її знову; холодний старт — типова причина “зависання”.
+- Модель у LM Studio вивантажена? Завантажте її знову; холодний старт — поширена причина “зависання”.
- Помилки контексту? Зменште `contextWindow` або підвищте ліміт на своєму сервері.
-- Безпека: локальні моделі пропускають фільтри на боці провайдера; тримайте агентів вузькоспеціалізованими, а compaction увімкненим, щоб обмежити радіус ураження від prompt injection.
+- OpenAI-сумісний сервер повертає `messages[].content ... expected a string`?
+ Додайте `compat.requiresStringContent: true` для запису цієї моделі.
+- Прямі маленькі виклики `/v1/chat/completions` працюють, але `openclaw infer model run`
+ завершується з помилкою на Gemma або іншій локальній моделі? Спочатку вимкніть схеми інструментів за допомогою
+ `compat.supportsTools: false`, а потім повторіть перевірку. Якщо сервер і далі падає лише
+ на більших промптах OpenClaw, вважайте це обмеженням моделі/сервера на стороні апстріму.
+- Безпека: локальні моделі пропускають фільтри на боці провайдера; звужуйте агентів і тримайте compaction увімкненим, щоб обмежити радіус впливу інʼєкції промптів.
diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md
index 18f9e3643..288e61e54 100644
--- a/docs/uk/gateway/troubleshooting.md
+++ b/docs/uk/gateway/troubleshooting.md
@@ -1,21 +1,21 @@
---
read_when:
- - Центр усунення несправностей направив вас сюди для поглибленої діагностики
- - Вам потрібні стабільні розділи runbook за симптомами з точними командами
-summary: Поглиблений runbook з усунення несправностей для шлюзу, каналів, автоматизації, вузлів і браузера
+ - Центр усунення несправностей скерував вас сюди для глибшої діагностики
+ - Вам потрібні стабільні розділи посібника за симптомами з точними командами
+summary: Детальний посібник з усунення несправностей для gateway, каналів, автоматизації, вузлів і браузера
title: Усунення несправностей
x-i18n:
- generated_at: "2026-04-06T15:29:04Z"
+ generated_at: "2026-04-07T14:59:22Z"
model: gpt-5.4
provider: openai
- source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729
+ source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba
source_path: gateway/troubleshooting.md
workflow: 15
---
-# Усунення несправностей шлюзу
+# Усунення несправностей gateway
-Ця сторінка — поглиблений runbook.
+Ця сторінка — детальний посібник.
Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік тріажу.
## Послідовність команд
@@ -34,10 +34,10 @@ openclaw channels status --probe
- `openclaw gateway status` показує `Runtime: running` і `RPC probe: ok`.
- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісу.
-- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису і,
- де підтримується, результати probe/audit, наприклад `works` або `audit ok`.
+- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису та,
+ де це підтримується, результати probe/audit, наприклад `works` або `audit ok`.
-## Anthropic 429: потрібне додаткове використання для довгого контексту
+## Для Anthropic 429 для довгого контексту потрібне додаткове використання
Використовуйте це, коли журнали/помилки містять:
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
@@ -50,15 +50,15 @@ openclaw config get agents.defaults.models
Зверніть увагу на таке:
-- Для вибраної моделі Anthropic Opus/Sonnet встановлено `params.context1m: true`.
-- Поточні облікові дані Anthropic не дають права на використання довгого контексту.
-- Запити падають лише на довгих сесіях/запусках моделі, яким потрібен beta-шлях 1M.
+- Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`.
+- Поточні облікові дані Anthropic не мають права на використання довгого контексту.
+- Запити збоять лише в довгих сесіях/запусках моделі, яким потрібен шлях 1M beta.
Варіанти виправлення:
1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту.
-2. Використовуйте облікові дані Anthropic, які дають право на запити з довгим контекстом, або перейдіть на ключ API Anthropic.
-3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли запити Anthropic з довгим контекстом відхиляються.
+2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на Anthropic API key.
+3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли Anthropic відхиляє запити з довгим контекстом.
Пов’язане:
@@ -66,9 +66,62 @@ 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, але збоять agent runs
+
+Використовуйте це, коли:
+
+- `curl ... /v1/models` працює
+- малі прямі виклики `/v1/chat/completions` працюють
+- запуски моделей OpenClaw збоять лише під час звичайних ходів агента
+
+```bash
+curl http://127.0.0.1:1234/v1/models
+curl http://127.0.0.1:1234/v1/chat/completions \
+ -H 'content-type: application/json' \
+ -d '{"model":"","messages":[{"role":"user","content":"hi"}],"stream":false}'
+openclaw infer model run --model --prompt "hi" --json
+openclaw logs --follow
+```
+
+Зверніть увагу на таке:
+
+- прямі малі виклики успішні, але запуски OpenClaw збоять лише на більших prompt
+- backend повертає помилки про те, що `messages[].content` очікує рядок
+- backend падає лише при більшій кількості токенів prompt або на повних prompt середовища агента
+
+Типові ознаки:
+
+- `messages[...].content: invalid type: sequence, expected a string` → backend
+ відхиляє структуровані частини вмісту Chat Completions. Виправлення: задайте
+ `models.providers..models[].compat.requiresStringContent: true`.
+- прямі малі запити успішні, але ходи агента OpenClaw збоять із падіннями backend/моделі
+ (наприклад Gemma у деяких збірках `inferrs`) → транспорт OpenClaw,
+ імовірно, уже налаштований правильно; backend збоїть на більшій формі prompt
+ середовища агента.
+- збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів
+ були частиною навантаження, але решта проблеми все ще в обмеженнях моделі/сервера
+ вищого рівня або в помилці backend.
+
+Варіанти виправлення:
+
+1. Задайте `compat.requiresStringContent: true` для backend Chat Completions, які приймають лише рядки.
+2. Задайте `compat.supportsTools: false` для моделей/backend, які не можуть надійно обробляти
+ поверхню схем інструментів OpenClaw.
+3. За можливості зменште навантаження prompt: менший bootstrap workspace, коротша
+ історія сесії, легша локальна модель або backend із кращою підтримкою довгого контексту.
+4. Якщо малі прямі запити й надалі проходять, а ходи OpenClaw усе ще падають
+ всередині backend, розглядайте це як обмеження upstream server/model і створіть
+ там repro з прийнятою формою payload.
+
+Пов’язане:
+
+- [/gateway/local-models](/uk/gateway/local-models)
+- [/gateway/configuration#models](/uk/gateway/configuration#models)
+- [/gateway/configuration-reference#openai-compatible-endpoints](/uk/gateway/configuration-reference#openai-compatible-endpoints)
+
## Немає відповідей
-Якщо канали підключені, але нічого не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати.
+Якщо канали працюють, але ніхто не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати.
```bash
openclaw status
@@ -80,13 +133,13 @@ openclaw logs --follow
Зверніть увагу на таке:
-- Pairing очікує підтвердження для відправників у DM.
-- Обмеження згадування для груп (`requireMention`, `mentionPatterns`).
-- Невідповідності allowlist для каналу/групи.
+- Очікує pairing для відправників у DM.
+- Фільтрація згадок у групах (`requireMention`, `mentionPatterns`).
+- Невідповідності allowlist каналу/групи.
Типові ознаки:
-- `drop guild message (mention required` → групове повідомлення ігнорується, доки немає згадки.
+- `drop guild message (mention required` → повідомлення в групі ігнорується, доки не буде згадки.
- `pairing request` → відправника потрібно схвалити.
- `blocked` / `allowlist` → відправника/канал відфільтровано політикою.
@@ -96,9 +149,9 @@ openclaw logs --follow
- [/channels/pairing](/uk/channels/pairing)
- [/channels/groups](/uk/channels/groups)
-## Підключення dashboard/control UI
+## Підключення dashboard control UI
-Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо безпечного контексту.
+Коли dashboard/control UI не підключається, перевірте URL, режим auth і припущення щодо secure context.
```bash
openclaw gateway status
@@ -111,45 +164,46 @@ openclaw gateway status --json
Зверніть увагу на таке:
- Правильний URL probe і URL dashboard.
-- Невідповідність режиму/токена автентифікації між клієнтом і шлюзом.
+- Невідповідність режиму auth/token між клієнтом і gateway.
- Використання HTTP там, де потрібна ідентичність пристрою.
Типові ознаки:
-- `device identity required` → небезпечний контекст або відсутня автентифікація пристрою.
+- `device identity required` → небезпечний контекст або відсутня auth пристрою.
- `origin not allowed` → `Origin` браузера відсутній у `gateway.controlUi.allowedOrigins`
- (або ви підключаєтеся з origin браузера, що не є loopback, без явного
+ (або ви підключаєтеся з не-loopback origin браузера без явного
allowlist).
- `device nonce required` / `device nonce mismatch` → клієнт не завершує
- challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`).
+ flow challenge-based device auth (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → клієнт підписав неправильний
- payload (або використав застарілий timestamp) для поточного рукостискання.
+ payload (або використав застарілу часову мітку) для поточного handshake.
- `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою.
-- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із pair-ованим
- токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають
- свій запитаний набір scope.
-- Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: спочатку явний спільний
- токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою,
- потім bootstrap-токен.
-- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для одного й того самого
- `{scope, ip}` серіалізуються до того, як лімітер зафіксує помилку. Тому дві хибні
- одночасні повторні спроби від того самого клієнта можуть призвести до `retry later`
- у другій спробі замість двох звичайних невідповідностей.
-- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin
- → повторні невдалі спроби з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket.
-- повторюване `unauthorized` після цієї повторної спроби → розсинхронізація спільного токена/токена пристрою; оновіть конфігурацію токена та за потреби повторно схваліть/ротуйте токен пристрою.
-- `gateway connect failed:` → неправильний хост/порт/URL призначення.
+- Ця повторна спроба з кешованим токеном повторно використовує набір scope, збережений разом
+ зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають свій
+ запитаний набір scope.
+- Поза цим шляхом повторної спроби пріоритет auth під час підключення такий:
+ спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою,
+ а потім bootstrap token.
+- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого
+ `{scope, ip}` серіалізуються до того, як обмежувач зафіксує невдачу. Тому дві некоректні
+ одночасні повторні спроби від одного клієнта можуть показати `retry later`
+ на другій спробі замість двох звичайних невідповідностей.
+- `too many failed authentication attempts (retry later)` від loopback-клієнта браузерного origin
+ → повторні невдачі від того самого нормалізованого `Origin` тимчасово
+ блокуються; інший localhost origin використовує окремий bucket.
+- повторювані `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена й за потреби повторно схваліть/переверніть токен пристрою.
+- `gateway connect failed:` → неправильний host/port/url призначення.
-### Швидка карта кодів деталей автентифікації
+### Швидка карта кодів деталей auth
-Використовуйте `error.details.code` з невдалого відповіді `connect`, щоб вибрати наступну дію:
+Використовуйте `error.details.code` із невдалого відповіді `connect`, щоб вибрати наступну дію:
-| Код деталей | Значення | Рекомендована дія |
-| ---------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. |
-| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації шлюзу. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явним `deviceToken` / `scopes` зберігають запитувані scope. Якщо все ще не працює, виконайте [контрольний список відновлення після дрейфу токена](/cli/devices#token-drift-recovery-checklist). |
-| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [devices CLI](/cli/devices), потім перепідключіться. |
-| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. |
+| Detail code | Значення | Рекомендована дія |
+| ---------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 `. |
Перевірка міграції device auth v2:
@@ -163,49 +217,49 @@ openclaw gateway status
1. чекає на `connect.challenge`
2. підписує payload, прив’язаний до challenge
-3. надсилає `connect.params.device.nonce` з тим самим challenge nonce
+3. надсилає `connect.params.device.nonce` з тим самим nonce challenge
-Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхиляються:
+Якщо `openclaw devices rotate` / `revoke` / `remove` несподівано заборонено:
-- сесії токена pair-ованого пристрою можуть керувати лише **власним** пристроєм, якщо
- виклик також не має `operator.admin`
-- `openclaw devices rotate --scope ...` може запитувати лише ті scope оператора,
+- сесії paired-device token можуть керувати лише **власним**
+ пристроєм, якщо тільки виклик також не має `operator.admin`
+- `openclaw devices rotate --scope ...` може запитувати лише ті operator scope,
які сесія виклику вже має
Пов’язане:
- [/web/control-ui](/web/control-ui)
-- [/gateway/configuration](/uk/gateway/configuration) (режими автентифікації шлюзу)
+- [/gateway/configuration](/uk/gateway/configuration) (режими auth gateway)
- [/gateway/trusted-proxy-auth](/uk/gateway/trusted-proxy-auth)
- [/gateway/remote](/uk/gateway/remote)
- [/cli/devices](/cli/devices)
-## Сервіс шлюзу не працює
+## Сервіс gateway не працює
-Використовуйте це, коли сервіс установлено, але процес не утримується запущеним.
+Використовуйте це, якщо сервіс встановлено, але процес не утримується в робочому стані.
```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
-openclaw gateway status --deep # також сканувати системні сервіси
+openclaw gateway status --deep # також сканує системні сервіси
```
Зверніть увагу на таке:
-- `Runtime: stopped` з підказками щодо завершення.
+- `Runtime: stopped` з підказками про завершення.
- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`).
-- Конфлікти порту/слухача.
-- Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`.
+- Конфлікти портів/слухачів.
+- Додаткові встановлення launchd/systemd/schtasks при використанні `--deep`.
- Підказки очищення `Other gateway-like services detected (best effort)`.
Типові ознаки:
-- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим шлюзу не ввімкнено, або файл конфігурації було пошкоджено й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації — `~/.openclaw/openclaw.json`.
-- `refusing to bind gateway ... without auth` → bind не на loopback без дійсного шляху автентифікації шлюзу (токен/пароль або 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`, щоб відновити очікувану конфігурацію local-mode. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації — `~/.openclaw/openclaw.json`.
+- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху auth gateway (token/password або trusted-proxy, якщо налаштовано).
- `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту.
-- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks-юнити. У більшості конфігурацій має бути один шлюз на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host).
+- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks units. У більшості конфігурацій слід тримати один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + config/state/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host).
Пов’язане:
@@ -213,9 +267,9 @@ openclaw gateway status --deep # також сканувати системн
- [/gateway/configuration](/uk/gateway/configuration)
- [/gateway/doctor](/uk/gateway/doctor)
-## Попередження probe шлюзу
+## Попередження probe gateway
-Використовуйте це, коли `openclaw gateway probe` досягає цілі, але все одно виводить блок попередження.
+Використовуйте це, коли `openclaw gateway probe` до чогось дістається, але все одно виводить блок попередження.
```bash
openclaw gateway probe
@@ -225,15 +279,15 @@ openclaw gateway probe --ssh user@gateway-host
Зверніть увагу на таке:
-- `warnings[].code` і `primaryTargetId` у JSON-виводі.
-- Чи стосується попередження резервного SSH-шляху, кількох шлюзів, відсутніх scope або нерозв’язаних auth refs.
+- `warnings[].code` і `primaryTargetId` у виводі JSON.
+- Чи пов’язане попередження з резервним SSH, кількома gateway, відсутніми scope або нерозв’язаними auth refs.
Типові ознаки:
-- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-цілі.
-- `multiple reachable gateways detected` → відповіла більш ніж одна ціль. Зазвичай це означає навмисну багатошлюзову конфігурацію або застарілі/дубльовані слухачі.
-- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → connect спрацював, але детальний RPC обмежено scope; pair-уйте ідентичність пристрою або використовуйте облікові дані з `operator.read`.
-- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → матеріали автентифікації були недоступні в цьому шляху команди для цілі, що завершилася помилкою.
+- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-призначення.
+- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисне багатошлюзове налаштування або застарілі/дубльовані слухачі.
+- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але RPC деталей обмежений scope; спарте ідентичність пристрою або використайте облікові дані з `operator.read`.
+- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → auth-матеріал був недоступний у цьому шляху команди для цілі, що не пройшла перевірку.
Пов’язане:
@@ -243,7 +297,7 @@ openclaw gateway probe --ssh user@gateway-host
## Канал підключений, але повідомлення не проходять
-Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу.
+Якщо стан каналу показує, що він підключений, але потік повідомлень мертвий, зосередьтеся на політиці, дозволах і специфічних для каналу правилах доставки.
```bash
openclaw channels status --probe
@@ -256,14 +310,14 @@ openclaw config get channels
Зверніть увагу на таке:
- Політика DM (`pairing`, `allowlist`, `open`, `disabled`).
-- Allowlist групи та вимоги до згадки.
+- Allowlist групи та вимоги до згадок.
- Відсутні дозволи/scopes API каналу.
Типові ознаки:
-- `mention required` → повідомлення ігнорується політикою згадки в групі.
-- `pairing` / сліди очікуваного схвалення → відправника не схвалено.
-- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема автентифікації/дозволів каналу.
+- `mention required` → повідомлення ігнорується через політику згадок у групі.
+- `pairing` / сліди очікування схвалення → відправника не схвалено.
+- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з auth/дозволами каналу.
Пов’язане:
@@ -274,7 +328,7 @@ openclaw config get channels
## Доставка cron і heartbeat
-Якщо cron або heartbeat не спрацювали чи не були доставлені, спочатку перевірте стан планувальника, а потім ціль доставки.
+Якщо cron або heartbeat не запустилися чи не були доставлені, спочатку перевірте стан планувальника, а потім ціль доставки.
```bash
openclaw cron status
@@ -287,18 +341,18 @@ openclaw logs --follow
Зверніть увагу на таке:
- Cron увімкнено і є наступне пробудження.
-- Статус історії запусків завдань (`ok`, `skipped`, `error`).
+- Стан історії запусків завдання (`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` → збій тіку планувальника; перевірте помилки файлів/журналів/runtime.
+- `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 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`.
+- `heartbeat skipped` з `reason=dm-blocked` → ціль heartbeat визначилася як призначення стилю DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`.
Пов’язане:
@@ -306,9 +360,9 @@ openclaw logs --follow
- [/automation/cron-jobs](/uk/automation/cron-jobs)
- [/gateway/heartbeat](/uk/gateway/heartbeat)
-## Збій інструмента pair-ованого вузла
+## Не працює paired tool вузла
-Якщо вузол pair-ований, але інструменти не працюють, окремо перевірте передній план, дозволи та стан схвалення.
+Якщо вузол спарено, але інструменти не працюють, окремо перевірте foreground, дозволи та стан схвалення.
```bash
openclaw nodes status
@@ -320,9 +374,9 @@ openclaw status
Зверніть увагу на таке:
-- Вузол у мережі з очікуваними можливостями.
-- Надані ОС-дозволи для камери/мікрофона/геолокації/екрана.
-- Стан схвалень exec і allowlist.
+- Вузол онлайн з очікуваними можливостями.
+- Надані дозволи ОС для camera/mic/location/screen.
+- Стан exec approvals і allowlist.
Типові ознаки:
@@ -337,9 +391,9 @@ openclaw status
- [/nodes/index](/uk/nodes/index)
- [/tools/exec-approvals](/uk/tools/exec-approvals)
-## Збій browser tool
+## Не працює browser tool
-Використовуйте це, коли дії browser tool не працюють, хоча сам шлюз справний.
+Використовуйте це, коли дії browser tool збоять, хоча сам gateway справний.
```bash
openclaw browser status
@@ -351,41 +405,41 @@ openclaw doctor
Зверніть увагу на таке:
-- Чи встановлено `plugins.allow` і чи містить він `browser`.
-- Дійсний шлях до виконуваного файла браузера.
+- Чи задано `plugins.allow` і чи містить він `browser`.
+- Коректний шлях до виконуваного файла браузера.
- Досяжність профілю CDP.
- Доступність локального Chrome для профілів `existing-session` / `user`.
Типові ознаки:
-- `unknown command "browser"` або `unknown command 'browser'` → вбудований browser plugin виключено через `plugins.allow`.
-- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому плагін ніколи не завантажився.
-- `Failed to start Chrome CDP on port` → не вдалося запустити процес браузера.
+- `unknown command "browser"` або `unknown command 'browser'` → bundled 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 недосяжна з хоста шлюзу.
-- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має досяжної цілі, або HTTP-кінцева точка відповіла, але CDP WebSocket усе одно не вдалося відкрити.
-- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні шлюзу немає повного пакета Playwright; знімки ARIA і базові знімки сторінки все ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селекторами та експорт 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` зі знімка, а не CSS `--element`.
-- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів Chrome MCP потребують посилань зі знімка, а не CSS-селекторів.
-- `existing-session file uploads currently support one file at a time.` → надсилайте по одному завантаженню за виклик у профілях Chrome MCP.
+- `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 відповів, але WebSocket CDP все одно не вдалося відкрити.
+- `Playwright is not available in this gateway build; '' is unsupported.` → поточна інсталяція gateway не містить повного пакета Playwright; ARIA snapshots і базові знімки сторінки все ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-селекторами та експорт 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 refs, а не CSS-селекторів.
+- `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення timeout.
-- `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або сирого профілю CDP.
-- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або віддаленого CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію та звільнити стан емуляції Playwright/CDP без перезапуску всього шлюзу.
+- `response body is not supported for existing-session profiles yet.` → `responsebody` поки що потребує керованого браузера або профілю raw CDP.
+- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування та звільнити стан емуляції Playwright/CDP без перезапуску всього gateway.
Пов’язане:
- [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting)
- [/tools/browser](/uk/tools/browser)
-## Якщо ви оновилися і щось раптом зламалося
+## Якщо ви оновилися і щось раптово зламалося
-Більшість проблем після оновлення пов’язані з дрейфом конфігурації або з жорсткішими типовими значеннями, які тепер застосовуються.
+Більшість проблем після оновлення — це дрейф конфігурації або суворіші типові налаштування, які тепер примусово застосовуються.
-### 1) Змінилася поведінка автентифікації та перевизначення URL
+### 1) Змінилася поведінка auth і перевизначення URL
```bash
openclaw gateway status
@@ -396,15 +450,15 @@ openclaw config get gateway.auth.mode
Що перевірити:
-- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на remote, навіть якщо локальний сервіс працює нормально.
-- Явні виклики `--url` не повертаються до збережених облікових даних.
+- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на remote, тоді як локальний сервіс працює нормально.
+- Явні виклики `--url` не використовують збережені облікові дані як резервний варіант.
Типові ознаки:
- `gateway connect failed:` → неправильна ціль URL.
-- `unauthorized` → кінцева точка досяжна, але автентифікація неправильна.
+- `unauthorized` → endpoint досяжний, але auth неправильна.
-### 2) Guardrails для bind і auth стали суворішими
+### 2) Обмеження bind і auth стали суворішими
```bash
openclaw config get gateway.bind
@@ -416,13 +470,13 @@ openclaw logs --follow
Що перевірити:
-- Bind не на loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації шлюзу: спільна автентифікація токеном/паролем або правильно налаштоване розгортання `trusted-proxy` не на loopback.
-- Старі ключі, як-от `gateway.token`, не замінюють `gateway.auth.token`.
+- Для bind не до loopback (`lan`, `tailnet`, `custom`) потрібен дійсний шлях auth gateway: auth через shared token/password або коректно налаштоване розгортання non-loopback `trusted-proxy`.
+- Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`.
Типові ознаки:
-- `refusing to bind gateway ... without auth` → bind не на loopback без дійсного шляху автентифікації шлюзу.
-- `RPC probe: failed` while runtime is running → шлюз живий, але недоступний із поточними auth/url.
+- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху auth gateway.
+- `RPC probe: failed` while runtime is running → gateway живий, але недоступний з поточною auth/url.
### 3) Змінився стан pairing та ідентичності пристрою
@@ -435,15 +489,15 @@ openclaw doctor
Що перевірити:
-- Очікувані схвалення пристроїв для dashboard/nodes.
-- Очікувані схвалення DM pairing після змін політики або ідентичності.
+- Очікують схвалення пристрої для dashboard/nodes.
+- Очікують схвалення DM pairing після змін політики або ідентичності.
Типові ознаки:
- `device identity required` → вимоги device auth не виконано.
- `pairing required` → відправника/пристрій потрібно схвалити.
-Якщо конфігурація сервісу та runtime все ще не збігаються після перевірок, перевстановіть метадані сервісу з того самого каталогу профілю/стану:
+Якщо після перевірок конфігурація сервісу й runtime усе ще не збігаються, перевстановіть метадані сервісу з того самого каталогу profile/state:
```bash
openclaw gateway install --force
diff --git a/docs/uk/help/troubleshooting.md b/docs/uk/help/troubleshooting.md
index 92316af2c..7463ce96f 100644
--- a/docs/uk/help/troubleshooting.md
+++ b/docs/uk/help/troubleshooting.md
@@ -1,25 +1,25 @@
---
read_when:
- OpenClaw не працює, і вам потрібен найшвидший шлях до виправлення
- - Вам потрібен процес первинної діагностики перед переходом до глибоких runbook
-summary: Центр усунення несправностей OpenClaw з підходом «спершу симптом»
+ - Ви хочете пройти процес тріажу перед зануренням у докладні інструкції
+summary: Центр усунення несправностей OpenClaw зі швидкою діагностикою за симптомами
title: Загальне усунення несправностей
x-i18n:
- generated_at: "2026-04-05T18:06:22Z"
+ generated_at: "2026-04-07T14:58:59Z"
model: gpt-5.4
provider: openai
- source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252
+ source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3
source_path: help/troubleshooting.md
workflow: 15
---
# Усунення несправностей
-Якщо у вас є лише 2 хвилини, використовуйте цю сторінку як вхідну точку для первинної діагностики.
+Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку тріажу.
## Перші 60 секунд
-Виконайте цю точну послідовність команд у такому порядку:
+Запустіть цю точну послідовність команд у вказаному порядку:
```bash
openclaw status
@@ -31,23 +31,36 @@ openclaw channels status --probe
openclaw logs --follow
```
-Хороший результат в один рядок:
+Хороший результат в одному рядку:
-- `openclaw status` → показує налаштовані канали й не має очевидних помилок auth.
-- `openclaw status --all` → повний звіт присутній і ним можна поділитися.
+- `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` → немає блокувальних помилок config/service.
-- `openclaw channels status --probe` → за доступного gateway повертає live-стан транспорту для кожного облікового запису
- плюс результати probe/audit, наприклад `works` або `audit ok`; якщо
- gateway недоступний, команда повертається до зведень лише з config.
+- `openclaw doctor` → немає блокувальних помилок конфігурації/сервісу.
+- `openclaw channels status --probe` → доступний gateway повертає живий стан транспорту для кожного облікового запису разом із результатами probe/audit, такими як `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`,
-перейдіть до [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
+перейдіть до [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
+
+## Локальний OpenAI-compatible backend працює напряму, але не працює в OpenClaw
+
+Якщо ваш локальний або self-hosted backend `/v1` відповідає на малі прямі probe до
+`/v1/chat/completions`, але завершується помилкою в `openclaw infer model run` або під час звичайних
+ходів агента:
+
+1. Якщо помилка згадує, що `messages[].content` має бути рядком, установіть
+ `models.providers..models[].compat.requiresStringContent: true`.
+2. Якщо backend усе ще завершується помилкою лише під час ходів агента OpenClaw, установіть
+ `models.providers..models[].compat.supportsTools: false` і повторіть спробу.
+3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw аварійно завершують роботу
+ backend, розглядайте решту проблеми як обмеження висхідної моделі/сервера та
+ продовжуйте в докладній інструкції:
+ [/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)
## Не вдається встановити plugin через відсутні openclaw extensions
@@ -58,7 +71,7 @@ openclaw logs --follow
1. Додайте `openclaw.extensions` до `package.json`.
2. Спрямуйте записи на зібрані runtime-файли (зазвичай `./dist/index.js`).
-3. Опублікуйте plugin знову й ще раз виконайте `openclaw plugins install `.
+3. Перевидайте plugin і знову виконайте `openclaw plugins install `.
Приклад:
@@ -72,28 +85,28 @@ openclaw logs --follow
}
```
-Довідка: [Архітектура plugins](/plugins/architecture)
+Довідка: [Архітектура plugin](/uk/plugins/architecture)
## Дерево рішень
```mermaid
flowchart TD
- A[OpenClaw не працює] --> B{Що ламається першим}
- B --> C[Немає відповідей]
- B --> D[Dashboard або Control UI не підключається]
- B --> E[Gateway не запускається або service не працює]
- B --> F[Канал підключається, але повідомлення не проходять]
- B --> G[Cron або heartbeat не спрацював чи не доставив]
- B --> H[Node спарено, але camera canvas screen exec не працює]
- B --> I[Не працює інструмент browser]
+ A[OpenClaw is not working] --> B{What breaks first}
+ B --> C[No replies]
+ B --> D[Dashboard or Control UI will not connect]
+ B --> E[Gateway will not start or service not running]
+ B --> F[Channel connects but messages do not flow]
+ B --> G[Cron or heartbeat did not fire or did not deliver]
+ B --> H[Node is paired but camera canvas screen exec fails]
+ B --> I[Browser tool fails]
- C --> C1[/Розділ Немає відповідей/]
- D --> D1[/Розділ Control UI/]
- E --> E1[/Розділ Gateway/]
- F --> F1[/Розділ Потік каналу/]
- G --> G1[/Розділ Автоматизація/]
- H --> H1[/Розділ Інструменти node/]
- I --> I1[/Розділ Browser/]
+ C --> C1[/No replies section/]
+ D --> D1[/Control UI section/]
+ E --> E1[/Gateway section/]
+ F --> F1[/Channel flow section/]
+ G --> G1[/Automation section/]
+ H --> H1[/Node tools section/]
+ I --> I1[/Browser section/]
```
@@ -110,24 +123,24 @@ flowchart TD
- `Runtime: running`
- `RPC probe: ok`
- - Ваш канал показує підключений транспорт і, де це підтримується, `works` або `audit ok` у `channels status --probe`
- - Відправник схвалений (або політика DM має значення open/allowlist)
+ - Ваш канал показує підключений транспорт і, де підтримується, `works` або `audit ok` у `channels status --probe`
+ - Відправник позначений як схвалений (або для DM політика відкрита/allowlist)
Поширені сигнатури в логах:
- - `drop guild message (mention required` → gating згадувань заблокував повідомлення в Discord.
- - `pairing request` → відправник не схвалений і чекає схвалення pairing у DM.
+ - `drop guild message (mention required` → обмеження згадки заблокувало повідомлення в Discord.
+ - `pairing request` → відправника не схвалено, і він очікує схвалення pairing у DM.
- `blocked` / `allowlist` у логах каналу → відправник, кімната або група відфільтровані.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
- - [/channels/troubleshooting](/channels/troubleshooting)
- - [/channels/pairing](/channels/pairing)
+ - [/gateway/troubleshooting#no-replies](/uk/gateway/troubleshooting#no-replies)
+ - [/channels/troubleshooting](/uk/channels/troubleshooting)
+ - [/channels/pairing](/uk/channels/pairing)
-
+
```bash
openclaw status
openclaw gateway status
@@ -138,35 +151,30 @@ flowchart TD
Хороший результат виглядає так:
- - `Dashboard: http://...` показано в `openclaw gateway status`
+ - `Dashboard: http://...` показується в `openclaw gateway status`
- `RPC probe: ok`
- - У логах немає циклу auth
+ - У логах немає циклу автентифікації
Поширені сигнатури в логах:
- - `device identity required` → контекст HTTP/non-secure не може завершити auth пристрою.
+ - `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}` серіалізуються до того, як обмежувач зафіксує невдачу, тож
- друга одночасна хибна повторна спроба вже може показати `retry later`.
- - `too many failed authentication attempts (retry later)` від origin браузера на localhost → повторні невдалі спроби з того самого `Origin` тимчасово
- блокуються; інший origin localhost використовує окремий bucket.
- - повторювані `unauthorized` після цієї повторної спроби → неправильний token/password, невідповідність режиму auth або застарілий токен спареного пристрою.
- - `gateway connect failed:` → UI націлено на неправильний URL/порт або на недоступний gateway.
+ - `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → одна повторна спроба з довіреним токеном пристрою може відбутися автоматично.
+ - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із paired токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний ними набір scope.
+ - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як limiter зафіксує помилку, тому друга одночасна невдала повторна спроба вже може показати `retry later`.
+ - `too many failed authentication attempts (retry later)` з браузерного джерела localhost → повторні невдалі спроби з того самого `Origin` тимчасово блокуються; інше джерело localhost використовує окремий bucket.
+ - повторюване `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий paired токен пристрою.
+ - `gateway connect failed:` → UI спрямовано на неправильний URL/порт або gateway недоступний.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+ - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/uk/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/web/control-ui)
- - [/gateway/authentication](/gateway/authentication)
+ - [/gateway/authentication](/uk/gateway/authentication)
-
+
```bash
openclaw status
openclaw gateway status
@@ -183,15 +191,15 @@ flowchart TD
Поширені сигнатури в логах:
- - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим gateway має значення remote або у файлі config немає позначки local-mode, і це слід виправити.
- - `refusing to bind gateway ... without auth` → bind не на loopback без дійсного шляху auth для gateway (token/password або trusted-proxy, де це налаштовано).
- - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнято.
+ - `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, якщо налаштовано).
+ - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнятий.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
- - [/gateway/background-process](/gateway/background-process)
- - [/gateway/configuration](/gateway/configuration)
+ - [/gateway/troubleshooting#gateway-service-not-running](/uk/gateway/troubleshooting#gateway-service-not-running)
+ - [/gateway/background-process](/uk/gateway/background-process)
+ - [/gateway/configuration](/uk/gateway/configuration)
@@ -206,24 +214,24 @@ flowchart TD
Хороший результат виглядає так:
- - Транспорт каналу підключений.
+ - Транспорт каналу підключено.
- Перевірки pairing/allowlist проходять.
- - Згадування виявляються там, де це потрібно.
+ - Згадки виявляються там, де це потрібно.
Поширені сигнатури в логах:
- - `mention required` → gating згадувань заблокував обробку.
- - `pairing` / `pending` → відправник DM ще не схвалений.
- - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → проблема з token дозволів каналу.
+ - `mention required` → обмеження згадки в групі заблокувало обробку.
+ - `pairing` / `pending` → відправника DM ще не схвалено.
+ - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → проблема з токеном дозволів каналу.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
- - [/channels/troubleshooting](/channels/troubleshooting)
+ - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/uk/gateway/troubleshooting#channel-connected-messages-not-flowing)
+ - [/channels/troubleshooting](/uk/channels/troubleshooting)
-
+
```bash
openclaw status
openclaw gateway status
@@ -235,7 +243,7 @@ flowchart TD
Хороший результат виглядає так:
- - `cron.status` показує, що функцію ввімкнено і є наступне пробудження.
+ - `cron.status` показує, що cron увімкнено і є наступне пробудження.
- `cron runs` показує нещодавні записи `ok`.
- Heartbeat увімкнено і він не поза активними годинами.
@@ -243,20 +251,20 @@ flowchart TD
- `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=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 wake було відкладено. - `unknown accountId` → accountId цілі доставки heartbeat не існує.
+- `requests-in-flight` → основна смуга зайнята; пробудження heartbeat було відкладено. - `unknown accountId` → цільовий account heartbeat для доставки не існує.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
- - [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting)
- - [/gateway/heartbeat](/gateway/heartbeat)
+ - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/uk/gateway/troubleshooting#cron-and-heartbeat-delivery)
+ - [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting)
+ - [/gateway/heartbeat](/uk/gateway/heartbeat)
-
+
```bash
openclaw status
openclaw gateway status
@@ -267,26 +275,26 @@ flowchart TD
Хороший результат виглядає так:
- - Node показано як підключений і спарений для role `node`.
- - Для команди, яку ви викликаєте, існує відповідна capability.
- - Стан permission для інструмента дозволений.
+ - Node вказано як підключений і paired для ролі `node`.
+ - Для команди, яку ви викликаєте, існує capability.
+ - Для інструмента надано стан дозволу.
Поширені сигнатури в логах:
- `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок node на передній план.
- - `*_PERMISSION_REQUIRED` → permission ОС відсутній або був відхилений.
- - `SYSTEM_RUN_DENIED: approval required` → approval для exec очікує рішення.
+ - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено або він відсутній.
+ - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec.
- `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist exec.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
- - [/nodes/troubleshooting](/nodes/troubleshooting)
- - [/tools/exec-approvals](/tools/exec-approvals)
+ - [/gateway/troubleshooting#node-paired-tool-fails](/uk/gateway/troubleshooting#node-paired-tool-fails)
+ - [/nodes/troubleshooting](/uk/nodes/troubleshooting)
+ - [/tools/exec-approvals](/uk/tools/exec-approvals)
-
+
```bash
openclaw config get tools.exec.host
openclaw config get tools.exec.security
@@ -296,14 +304,14 @@ flowchart TD
Що змінилося:
- - Якщо `tools.exec.host` не задано, типовим є `auto`.
- - `host=auto` визначається як `sandbox`, коли активний runtime sandbox, і як `gateway` — в іншому разі.
- - `host=auto` відповідає лише за маршрутизацію; поведінка без запитів у стилі "YOLO" походить від `security=full` плюс `ask=off` на gateway/node.
- - Для `gateway` і `node`, якщо `tools.exec.security` не задано, типове значення — `full`.
- - Якщо `tools.exec.ask` не задано, типове значення — `off`.
- - Підсумок: якщо ви бачите approval, значить якась локальна для хоста або для сесії політика посилила exec порівняно з поточними типовими значеннями.
+ - Якщо `tools.exec.host` не встановлено, значенням за замовчуванням є `auto`.
+ - `host=auto` визначається як `sandbox`, коли активний runtime sandbox, інакше як `gateway`.
+ - `host=auto` відповідає лише за маршрутизацію; поведінка "YOLO" без запиту визначається `security=full` разом із `ask=off` на gateway/node.
+ - Для `gateway` і `node` невстановлений `tools.exec.security` за замовчуванням має значення `full`.
+ - Невстановлений `tools.exec.ask` за замовчуванням має значення `off`.
+ - Результат: якщо ви бачите схвалення, якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням.
- Відновлення поточної типової поведінки без approval:
+ Відновлення поточної поведінки за замовчуванням без схвалень:
```bash
openclaw config set tools.exec.host gateway
@@ -314,25 +322,25 @@ flowchart TD
Безпечніші альтернативи:
- - Задайте лише `tools.exec.host=gateway`, якщо вам просто потрібна стабільна маршрутизація до хоста.
- - Використовуйте `security=allowlist` з `ask=on-miss`, якщо хочете exec на хості, але все одно хочете перевірку при промахах по allowlist.
+ - Встановіть лише `tools.exec.host=gateway`, якщо вам просто потрібна стабільна маршрутизація на хості.
+ - Використовуйте `security=allowlist` з `ask=on-miss`, якщо хочете exec на хості, але також хочете перевірку у разі промахів по allowlist.
- Увімкніть режим sandbox, якщо хочете, щоб `host=auto` знову визначався як `sandbox`.
Поширені сигнатури в логах:
- - `Approval required.` → команда чекає на `/approve ...`.
- - `SYSTEM_RUN_DENIED: approval required` → approval для exec на хості node очікує рішення.
- - `exec host=sandbox requires a sandbox runtime for this session` → неявний/явний вибір sandbox, але режим sandbox вимкнено.
+ - `Approval required.` → команда очікує на `/approve ...`.
+ - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec на хості node.
+ - `exec host=sandbox requires a sandbox runtime for this session` → неявно/явно вибрано sandbox, але режим sandbox вимкнено.
- Детальні сторінки:
+ Докладні сторінки:
- - [/tools/exec](/tools/exec)
- - [/tools/exec-approvals](/tools/exec-approvals)
- - [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift)
+ - [/tools/exec](/uk/tools/exec)
+ - [/tools/exec-approvals](/uk/tools/exec-approvals)
+ - [/gateway/security#runtime-expectation-drift](/uk/gateway/security#runtime-expectation-drift)
-
+
```bash
openclaw status
openclaw gateway status
@@ -343,35 +351,35 @@ flowchart TD
Хороший результат виглядає так:
- - Статус browser показує `running: true` і вибраний browser/profile.
+ - Стан браузера показує `running: true` і вибраний браузер/профіль.
- `openclaw` запускається, або `user` бачить локальні вкладки Chrome.
Поширені сигнатури в логах:
- - `unknown command "browser"` або `unknown command 'browser'` → `plugins.allow` задано, але не містить `browser`.
- - `Failed to start Chrome CDP on port` → не вдалося запустити локальний browser.
- - `browser.executablePath not found` → налаштований шлях до бінарного файлу неправильний.
+ - `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.
- - `Remote CDP for profile "" is not reachable` → налаштований віддалений ендпоїнт CDP недоступний із цього хоста.
+ - `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 недоступна з цього хоста.
- `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.
+ - застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію та скинути стан емуляції без перезапуску gateway.
- Детальні сторінки:
+ Докладні сторінки:
- - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
- - [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool)
- - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
- - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
+ - [/gateway/troubleshooting#browser-tool-fails](/uk/gateway/troubleshooting#browser-tool-fails)
+ - [/tools/browser#missing-browser-command-or-tool](/uk/tools/browser#missing-browser-command-or-tool)
+ - [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting)
+ - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
-## Пов’язане
+## Пов’язані матеріали
-- [FAQ](/help/faq) — часті запитання
-- [Усунення несправностей Gateway](/gateway/troubleshooting) — проблеми, специфічні для gateway
-- [Doctor](/gateway/doctor) — автоматичні перевірки стану та виправлення
-- [Усунення несправностей каналів](/channels/troubleshooting) — проблеми з підключенням каналів
-- [Усунення несправностей автоматизації](/automation/cron-jobs#troubleshooting) — проблеми cron і heartbeat
+- [FAQ](/uk/help/faq) — поширені запитання
+- [Усунення несправностей gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з gateway
+- [Doctor](/uk/gateway/doctor) — автоматичні перевірки стану та виправлення
+- [Усунення несправностей каналів](/uk/channels/troubleshooting) — проблеми з підключенням каналів
+- [Усунення несправностей автоматизації](/uk/automation/cron-jobs#troubleshooting) — проблеми з cron і heartbeat
diff --git a/docs/uk/providers/index.md b/docs/uk/providers/index.md
index 0aa3dc166..2c83ad10a 100644
--- a/docs/uk/providers/index.md
+++ b/docs/uk/providers/index.md
@@ -1,24 +1,23 @@
---
read_when:
- Ви хочете вибрати постачальника моделей
- - Вам потрібен швидкий огляд підтримуваних бекендів LLM
+ - Вам потрібен короткий огляд підтримуваних бекендів LLM
summary: Постачальники моделей (LLM), які підтримує OpenClaw
title: Каталог постачальників
x-i18n:
- generated_at: "2026-04-06T18:54:57Z"
+ generated_at: "2026-04-07T14:58:15Z"
model: gpt-5.4
provider: openai
- source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1
+ source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70
source_path: providers/index.md
workflow: 15
---
# Постачальники моделей
-OpenClaw може використовувати багато постачальників LLM. Виберіть постачальника, пройдіть автентифікацію, а потім задайте
-модель за замовчуванням як `provider/model`.
+OpenClaw може використовувати багато постачальників LLM. Виберіть постачальника, пройдіть автентифікацію, а потім задайте модель за замовчуванням як `provider/model`.
-Шукаєте документацію про канали чату (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? Див. [Канали](/uk/channels).
+Шукаєте документацію щодо каналів чату (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/тощо)? Див. [Канали](/uk/channels).
## Швидкий старт
@@ -37,7 +36,7 @@ OpenClaw може використовувати багато постачаль
- [Amazon Bedrock](/uk/providers/bedrock)
- [Anthropic (API + Claude CLI)](/uk/providers/anthropic)
- [Arcee AI (моделі Trinity)](/uk/providers/arcee)
-- [BytePlus (міжнародний)](/uk/concepts/model-providers#byteplus-international)
+- [BytePlus (міжнародна версія)](/uk/concepts/model-providers#byteplus-international)
- [Chutes](/uk/providers/chutes)
- [ComfyUI](/uk/providers/comfy)
- [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway)
@@ -45,17 +44,18 @@ OpenClaw може використовувати багато постачаль
- [fal](/uk/providers/fal)
- [Fireworks](/uk/providers/fireworks)
- [GitHub Copilot](/uk/providers/github-copilot)
-- [Моделі GLM](/uk/providers/glm)
+- [моделі GLM](/uk/providers/glm)
- [Google (Gemini)](/uk/providers/google)
- [Groq (LPU-інференс)](/uk/providers/groq)
- [Hugging Face (інференс)](/uk/providers/huggingface)
+- [inferrs (локальні моделі)](/uk/providers/inferrs)
- [Kilocode](/uk/providers/kilocode)
- [LiteLLM (уніфікований шлюз)](/uk/providers/litellm)
- [MiniMax](/uk/providers/minimax)
- [Mistral](/uk/providers/mistral)
- [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot)
- [NVIDIA](/uk/providers/nvidia)
-- [Ollama (хмарні + локальні моделі)](/uk/providers/ollama)
+- [Ollama (хмарні та локальні моделі)](/uk/providers/ollama)
- [OpenAI (API + Codex)](/uk/providers/openai)
- [OpenCode](/uk/providers/opencode)
- [OpenCode Go](/uk/providers/opencode-go)
@@ -68,7 +68,7 @@ OpenClaw може використовувати багато постачаль
- [StepFun](/uk/providers/stepfun)
- [Synthetic](/uk/providers/synthetic)
- [Together AI](/uk/providers/together)
-- [Venice (Venice AI, орієнтований на конфіденційність)](/uk/providers/venice)
+- [Venice (Venice AI, орієнтований на приватність)](/uk/providers/venice)
- [Vercel AI Gateway](/uk/providers/vercel-ai-gateway)
- [Vydra](/uk/providers/vydra)
- [vLLM (локальні моделі)](/uk/providers/vllm)
diff --git a/docs/uk/providers/inferrs.md b/docs/uk/providers/inferrs.md
new file mode 100644
index 000000000..4be9ca45d
--- /dev/null
+++ b/docs/uk/providers/inferrs.md
@@ -0,0 +1,161 @@
+---
+read_when:
+ - Ви хочете запускати OpenClaw із локальним сервером inferrs
+ - Ви обслуговуєте Gemma або іншу модель через inferrs
+ - Вам потрібні точні прапорці сумісності OpenClaw для inferrs
+summary: Запускайте OpenClaw через inferrs (локальний сервер, сумісний з OpenAI)
+title: inferrs
+x-i18n:
+ generated_at: "2026-04-07T14:58:20Z"
+ model: gpt-5.4
+ provider: openai
+ source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6
+ source_path: providers/inferrs.md
+ workflow: 15
+---
+
+# inferrs
+
+[inferrs](https://github.com/ericcurtin/inferrs) може обслуговувати локальні моделі через API `/v1`, сумісний з OpenAI. OpenClaw працює з `inferrs` через загальний шлях `openai-completions`.
+
+Наразі `inferrs` найкраще розглядати як користувацький самостійно розміщений бекенд, сумісний з OpenAI, а не як окремий плагін провайдера OpenClaw.
+
+## Швидкий старт
+
+1. Запустіть `inferrs` із моделлю.
+
+Приклад:
+
+```bash
+inferrs serve gg-hf-gg/gemma-4-E2B-it \
+ --host 127.0.0.1 \
+ --port 8080 \
+ --device metal
+```
+
+2. Переконайтеся, що сервер доступний.
+
+```bash
+curl http://127.0.0.1:8080/health
+curl http://127.0.0.1:8080/v1/models
+```
+
+3. Додайте явний запис провайдера OpenClaw і вкажіть на нього свою модель за замовчуванням.
+
+## Повний приклад конфігурації
+
+У цьому прикладі використовується Gemma 4 на локальному сервері `inferrs`.
+
+```json5
+{
+ agents: {
+ defaults: {
+ model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" },
+ models: {
+ "inferrs/gg-hf-gg/gemma-4-E2B-it": {
+ alias: "Gemma 4 (inferrs)",
+ },
+ },
+ },
+ },
+ models: {
+ mode: "merge",
+ providers: {
+ inferrs: {
+ baseUrl: "http://127.0.0.1:8080/v1",
+ apiKey: "inferrs-local",
+ api: "openai-completions",
+ models: [
+ {
+ id: "gg-hf-gg/gemma-4-E2B-it",
+ name: "Gemma 4 E2B (inferrs)",
+ reasoning: false,
+ input: ["text"],
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+ contextWindow: 131072,
+ maxTokens: 4096,
+ compat: {
+ requiresStringContent: true,
+ },
+ },
+ ],
+ },
+ },
+ },
+}
+```
+
+## Чому `requiresStringContent` має значення
+
+Деякі маршрути Chat Completions в `inferrs` приймають лише рядковий `messages[].content`, а не структуровані масиви частин вмісту.
+
+Якщо запуски OpenClaw завершуються помилкою на кшталт:
+
+```text
+messages[1].content: invalid type: sequence, expected a string
+```
+
+встановіть:
+
+```json5
+compat: {
+ requiresStringContent: true
+}
+```
+
+OpenClaw перетворить частини вмісту, що складаються лише з тексту, на звичайні рядки перед надсиланням запиту.
+
+## Застереження щодо Gemma і схеми інструментів
+
+Деякі поточні комбінації `inferrs` + Gemma приймають невеликі прямі запити до `/v1/chat/completions`, але все одно не справляються з повними ходами середовища виконання агента OpenClaw.
+
+Якщо це відбувається, спочатку спробуйте ось це:
+
+```json5
+compat: {
+ requiresStringContent: true,
+ supportsTools: false
+}
+```
+
+Це вимикає поверхню схеми інструментів OpenClaw для моделі й може зменшити навантаження від prompt на суворіших локальних бекендах.
+
+Якщо маленькі прямі запити й далі працюють, але звичайні ходи агента OpenClaw продовжують аварійно завершуватися всередині `inferrs`, то решта проблеми зазвичай пов’язана з поведінкою моделі/сервера на стороні upstream, а не з транспортним шаром OpenClaw.
+
+## Ручний smoke-тест
+
+Після налаштування перевірте обидва шари:
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+ -H 'content-type: application/json' \
+ -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
+
+openclaw infer model run \
+ --model inferrs/gg-hf-gg/gemma-4-E2B-it \
+ --prompt "What is 2 + 2? Reply with one short sentence." \
+ --json
+```
+
+Якщо перша команда працює, а друга — ні, скористайтеся наведеними нижче примітками щодо усунення несправностей.
+
+## Усунення несправностей
+
+- `curl /v1/models` не працює: `inferrs` не запущено, він недоступний або не прив’язаний до очікуваного хоста/порту.
+- `messages[].content ... expected a string`: установіть `compat.requiresStringContent: true`.
+- Прямі маленькі виклики `/v1/chat/completions` проходять, але `openclaw infer model run` не працює: спробуйте `compat.supportsTools: false`.
+- OpenClaw більше не отримує помилок схеми, але `inferrs` все одно аварійно завершується на більших ходах агента: вважайте це обмеженням `inferrs` або моделі на стороні upstream і зменште навантаження від prompt або змініть локальний бекенд/модель.
+
+## Поведінка в стилі проксі
+
+`inferrs` розглядається як бекенд `/v1`, сумісний з OpenAI, у стилі проксі, а не як нативна кінцева точка OpenAI.
+
+- тут не застосовується формування запитів, призначене лише для нативного OpenAI
+- немає `service_tier`, немає `store` у Responses, немає підказок кешу prompt і немає формування payload сумісності з reasoning OpenAI
+- приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) не додаються для користувацьких `inferrs` base URL
+
+## Див. також
+
+- [Локальні моделі](/uk/gateway/local-models)
+- [Усунення несправностей шлюзу](/uk/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
+- [Провайдери моделей](/uk/concepts/model-providers)