diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md
index 937e71ba3..a3eac8fa6 100644
--- a/docs/uk/gateway/configuration-reference.md
+++ b/docs/uk/gateway/configuration-reference.md
@@ -1,37 +1,37 @@
---
read_when:
- - Вам потрібні точні семантики або значення за замовчуванням для конфігурації на рівні полів
- - Ви перевіряєте блоки конфігурації каналу, моделі, gateway або інструментів
-summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем
-title: Довідник конфігурації
+ - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням
+ - Ви перевіряєте блоки конфігурації каналу, моделі, шлюзу або інструмента
+summary: Довідник з конфігурації шлюзу для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем
+title: Довідник з конфігурації
x-i18n:
- generated_at: "2026-04-08T19:05:31Z"
+ generated_at: "2026-04-10T05:42:37Z"
model: gpt-5.4
provider: openai
- source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c
+ source_hash: c6aa34e3a9096c4dabef26b9cdfda4bd7693e16da43a88c1641cfad8ba1ec237
source_path: gateway/configuration-reference.md
workflow: 15
---
-# Довідник конфігурації
+# Довідник з конфігурації
-Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
+Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
-Ця сторінка охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одну сторінку кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD.
+Ця сторінка охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний докладніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр memory/QMD.
Джерело істини в коді:
-- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із злитими метаданими bundled/plugin/channel, коли вони доступні
-- `config.schema.lookup` повертає один вузол схеми з областю шляху для інструментів деталізації
-- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють baseline hash документації конфігурації відносно поточної поверхні схеми
+- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, якщо вони доступні
+- `config.schema.lookup` повертає один вузол схеми з областю дії шляху для інструментів детального перегляду
+- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації відносно поточної поверхні схеми
-Окремі глибокі довідники:
+Окремі докладні довідники:
- [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming`
-- [Slash Commands](/uk/tools/slash-commands) для поточного каталогу built-in + bundled команд
-- сторінки власника каналу/плагіна для поверхонь команд, специфічних для каналу
+- [Slash Commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд
+- сторінки відповідних каналів/плагінів для поверхонь команд, специфічних для каналів
-Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено.
+Формат конфігурації — **JSON5** (дозволено коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано.
---
@@ -39,32 +39,32 @@ x-i18n:
Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`).
-### Доступ до DM і груп
+### Доступ до приватних повідомлень і груп
-Усі канали підтримують політики DM і групові політики:
+Усі канали підтримують політики для приватних повідомлень і політики для груп:
-| Політика DM | Поведінка |
-| ------------------- | -------------------------------------------------------------- |
-| `pairing` (типово) | Невідомі відправники отримують одноразовий код pair; власник має схвалити |
-| `allowlist` | Лише відправники в `allowFrom` (або в paired allow store) |
-| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) |
-| `disabled` | Ігнорувати всі вхідні DM |
+| Політика приватних повідомлень | Поведінка |
+| ------------------------------ | -------------------------------------------------------------- |
+| `pairing` (типово) | Невідомі відправники отримують одноразовий код pairing; власник має схвалити |
+| `allowlist` | Лише відправники з `allowFrom` (або зі сховища paired allow) |
+| `open` | Дозволити всі вхідні приватні повідомлення (потрібно `allowFrom: ["*"]`) |
+| `disabled` | Ігнорувати всі вхідні приватні повідомлення |
-| Групова політика | Поведінка |
-| --------------------- | ------------------------------------------------------ |
-| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist |
-| `open` | Обходить group allowlist-и (gating за згадками все ще застосовується) |
-| `disabled` | Блокує всі повідомлення груп/кімнат |
+| Політика груп | Поведінка |
+| ---------------------- | ------------------------------------------------------ |
+| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist |
+| `open` | Обійти allowlists для груп (gating за згадками все ще застосовується) |
+| `disabled` | Блокувати всі повідомлення груп/кімнат |
`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено.
-Коди pair-ing спливають через 1 годину. Непідтверджені запити на DM pairing обмежені **3 на канал**.
-Якщо блок провайдера відсутній повністю (немає `channels.`), політика груп під час виконання повертається до `allowlist` (fail-closed) з попередженням під час запуску.
+Коди pairing дійсні 1 годину. Кількість очікуваних запитів на pairing для приватних повідомлень обмежено **3 на канал**.
+Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску.
-### Перевизначення моделі для каналів
+### Перевизначення моделі для каналу
-Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Прив’язка каналу застосовується, коли в сесії ще немає перевизначення моделі (наприклад, встановленого через `/model`).
+Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ідентифікатори каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, встановленого через `/model`).
```json5
{
@@ -85,9 +85,9 @@ x-i18n:
}
```
-### Значення каналів за замовчуванням і heartbeat
+### Типові значення каналів і heartbeat
-Використовуйте `channels.defaults` для спільної поведінки group-policy і heartbeat між провайдерами:
+Використовуйте `channels.defaults` для спільної політики груп і поведінки heartbeat між провайдерами:
```json5
{
@@ -105,15 +105,15 @@ x-i18n:
}
```
-- `channels.defaults.groupPolicy`: запасна групова політика, коли `groupPolicy` на рівні провайдера не встановлено.
-- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь quoted/thread/history контекст), `allowlist` (включати контекст лише від allowlisted відправників), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст quote/reply). Перевизначення на рівні каналу: `channels..contextVisibility`.
-- `channels.defaults.heartbeat.showOk`: включати стани справних каналів у вивід heartbeat.
-- `channels.defaults.heartbeat.showAlerts`: включати стани з деградацією/помилками у вивід heartbeat.
+- `channels.defaults.groupPolicy`: резервна політика групи, коли `groupPolicy` на рівні провайдера не встановлено.
+- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників з allowlist), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитування/відповіді). Перевизначення для каналу: `channels..contextVisibility`.
+- `channels.defaults.heartbeat.showOk`: включати статуси справних каналів у вивід heartbeat.
+- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід heartbeat.
- `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід heartbeat у стилі індикатора.
### WhatsApp
-WhatsApp працює через web channel gateway (`Baileys Web`). Він запускається автоматично, коли існує пов’язана сесія.
+WhatsApp працює через web-канал шлюзу (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс.
```json5
{
@@ -124,7 +124,7 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
textChunkLimit: 4000,
chunkMode: "length", // length | newline
mediaMaxMb: 50,
- sendReadReceipts: true, // сині галочки (false у режимі self-chat)
+ sendReadReceipts: true, // blue ticks (false in self-chat mode)
groups: {
"*": { requireMention: true },
},
@@ -165,9 +165,9 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
```
- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований id облікового запису (відсортований).
-- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей вибір запасного облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
-- Застарілий однообліковий Baileys auth dir мігрується `openclaw doctor` у `whatsapp/default`.
-- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
+- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він відповідає id налаштованого облікового запису.
+- Застарілий auth dir Baileys для одного облікового запису мігрується командою `openclaw doctor` до `whatsapp/default`.
+- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
@@ -202,7 +202,7 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
historyLimit: 50,
replyToMode: "first", // off | first | all | batched
linkPreview: true,
- streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникати rate limits preview-edit)
+ streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
actions: { reactions: true, sendMessage: true },
reactionNotifications: "own", // off | own | all
mediaMaxMb: 100,
@@ -225,13 +225,13 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
}
```
-- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються), з `TELEGRAM_BOT_TOKEN` як fallback для облікового запису за замовчуванням.
-- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
-- У багатооблікових конфігураціях (2+ id облікових записів) задайте явний обліковий запис за замовчуванням (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути запасної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або це недійсно.
-- `configWrites: false` блокує записи конфігурації, ініційовані через Telegram (міграції ID supergroup, `/config set|unset`).
-- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP bindings для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна в [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
-- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах).
-- Політика retry: див. [Retry policy](/uk/concepts/retry).
+- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису.
+- Необов’язковий `channels.telegram.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
+- У конфігураціях із кількома обліковими записами (2+ id облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення некоректне.
+- `configWrites: false` блокує ініційовані з Telegram записи конфігурації (міграції ID supergroup, `/config set|unset`).
+- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP bindings для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- Попередній перегляд потокової передачі в Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах).
+- Політика повторних спроб: див. [Retry policy](/uk/concepts/retry).
### Discord
@@ -286,7 +286,7 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
historyLimit: 20,
textChunkLimit: 2000,
chunkMode: "length", // length | newline
- streaming: "off", // off | partial | block | progress (progress відображається як partial у Discord)
+ streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
maxLinesPerMessage: 17,
ui: {
components: {
@@ -297,7 +297,7 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
enabled: true,
idleHours: 24,
maxAgeHours: 0,
- spawnSubagentSessions: false, // opt-in для `sessions_spawn({ thread: true })`
+ spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
},
voice: {
enabled: true,
@@ -333,36 +333,36 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
}
```
-- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як fallback для облікового запису за замовчуванням.
-- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування retry/policy облікового запису все одно беруться з вибраного облікового запису в активному runtime snapshot.
-- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
-- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються.
-- Slug guild-ів мають нижній регістр із пробілами, заміненими на `-`; ключі каналів використовують slugged name (без `#`). Надавайте перевагу ID guild.
-- Повідомлення, написані ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються).
-- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення каналу) відкидає повідомлення, які згадують іншого користувача чи роль, але не бота (за винятком @everyone/@here).
-- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів.
-- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до Discord thread:
- - `enabled`: перевизначення Discord для можливостей сесій, прив’язаних до thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також bound delivery/routing)
- - `idleHours`: перевизначення Discord для автоматичного unfocus через бездіяльність у годинах (`0` вимикає)
+- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису.
+- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime.
+- Необов’язковий `channels.discord.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає 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.threadBindings` керує маршрутизацією, прив’язаною до Discord threads:
+ - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також прив’язана доставка/маршрутизація)
+ - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає)
- `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає)
- - `spawnSubagentSessions`: opt-in перемикач для автоматичного створення/прив’язки thread у `sessions_spawn({ thread: true })`
-- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP bindings для каналів і thread-ів (використовуйте id каналу/thread у `match.peer.id`). Семантика полів спільна в [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
-- `channels.discord.ui.components.accentColor` задає accent color для контейнерів Discord components v2.
-- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові auto-join + TTS overrides.
-- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються до параметрів DAVE у `@discordjs/voice` (типово `true` і `24`).
-- OpenClaw додатково намагається відновити voice receive, залишаючи/повторно приєднуючись до voice session після повторних помилок дешифрування.
-- `channels.discord.streaming` — канонічний ключ режиму stream. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично.
-- `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення status text.
-- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення mutable name/tag (режим сумісності break-glass).
-- `channels.discord.execApprovals`: нативна доставка exec approval у Discord і авторизація approver.
- - `enabled`: `true`, `false` або `"auto"` (типово). В auto mode exec approvals активуються, коли approver-ів можна визначити з `approvers` або `commands.ownerAllowFrom`.
- - `approvers`: ID користувачів Discord, яким дозволено схвалювати запити exec. Якщо пропущено, fallback до `commands.ownerAllowFrom`.
- - `agentFilter`: необов’язковий allowlist ID агентів. Пропустіть, щоб пересилати approvals для всіх агентів.
- - `sessionFilter`: необов’язкові шаблони ключів сесій (substring або regex).
- - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в DM approver-ам, `"channel"` надсилає в початковий канал, `"both"` надсилає в обидва місця. Коли target включає `"channel"`, кнопки можуть використовувати лише визначені approver-и.
- - `cleanupAfterResolve`: коли `true`, видаляє approval DM після схвалення, відхилення або тайм-ауту.
+ - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язування thread через `sessions_spawn({ thread: true })`
+- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP bindings для каналів і threads (використовуйте id каналу/thread у `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) і дозволяє необов’язкові перевизначення тексту статусу.
+- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними name/tag (режим сумісності break-glass).
+- `channels.discord.execApprovals`: власна доставка погоджень exec для Discord і авторизація користувачів, що погоджують.
+ - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли користувачів, що погоджують, можна визначити з `approvers` або `commands.ownerAllowFrom`.
+ - `approvers`: Discord user ID, яким дозволено погоджувати exec-запити. Якщо не вказано, використовується резервний варіант `commands.ownerAllowFrom`.
+ - `agentFilter`: необов’язковий allowlist id агентів. Не вказуйте, щоб пересилати погодження для всіх агентів.
+ - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex).
+ - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM користувачам, що погоджують, `"channel"` надсилає в початковий канал, `"both"` надсилає в обидва місця. Коли `target` включає `"channel"`, кнопками можуть користуватися лише визначені користувачі, що погоджують.
+ - `cleanupAfterResolve`: якщо `true`, видаляє DM із погодженням після погодження, відмови або тайм-ауту.
-**Режими сповіщень про реакції:** `off` (жодних), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` на всіх повідомленнях).
+**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень).
### Google Chat
@@ -393,11 +393,11 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
}
```
-- JSON service account: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`).
-- Також підтримується Service account SecretRef (`serviceAccountRef`).
-- Fallback-и середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
-- Використовуйте `spaces/` або `users/` для цілей доставки.
-- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення mutable email principal (режим сумісності break-glass).
+- JSON сервісного облікового запису: inline (`serviceAccount`) або через файл (`serviceAccountFile`).
+- Також підтримується SecretRef сервісного облікового запису (`serviceAccountRef`).
+- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
+- Для цілей доставки використовуйте `spaces/` або `users/`.
+- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass).
### Slack
@@ -449,7 +449,7 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
chunkMode: "length",
streaming: {
mode: "partial", // off | partial | block | progress
- nativeTransport: true, // використовувати рідний streaming API Slack, коли mode=partial
+ nativeTransport: true, // use Slack native streaming API when mode=partial
},
mediaMaxMb: 20,
execApprovals: {
@@ -464,39 +464,39 @@ WhatsApp працює через web channel gateway (`Baileys Web`). Він з
}
```
-- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для env fallback облікового запису за замовчуванням).
-- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для конкретного облікового запису).
+- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного значення зі змінних середовища типового облікового запису).
+- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису).
- `botToken`, `appToken`, `signingSecret` і `userToken` приймають plaintext
рядки або об’єкти SecretRef.
-- Slack account snapshot-и надають поля джерела/стану для кожного credential, такі як
- `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode —
+- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як
+ `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode,
`signingSecretStatus`. `configured_unavailable` означає, що обліковий запис
- налаштовано через SecretRef, але поточний шлях command/runtime не зміг
+ налаштовано через SecretRef, але поточний шлях команди/runtime не зміг
визначити значення секрету.
-- `configWrites: false` блокує записи конфігурації, ініційовані через Slack.
-- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
-- `channels.slack.streaming.mode` — канонічний ключ режиму stream для Slack. `channels.slack.streaming.nativeTransport` керує рідним transport streaming у Slack. Застарілі `streamMode`, булеві `streaming` і `nativeStreaming` мігруються автоматично.
-- Використовуйте `user:` (DM) або `channel:` для цілей доставки.
+- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack.
+- Необов’язковий `channels.slack.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
+- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує власним транспортом потокової передачі Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично.
+- Для цілей доставки використовуйте `user:` (DM) або `channel:`.
-**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`).
+**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`).
-**Ізоляція thread session:** `thread.historyScope` — окремо для thread (типово) або спільно в межах каналу. `thread.inheritParent` копіює transcript батьківського каналу в нові thread-и.
+**Ізоляція сеансів thread:** `thread.historyScope` — для окремого thread (типово) або спільно для каналу. `thread.inheritParent` копіює стенограму батьківського каналу до нових threads.
-- Рідний streaming у Slack плюс статус thread у стилі Slack assistant "is typing..." потребують ціль reply thread. DM верхнього рівня типово залишаються поза thread, тому вони використовують `typingReaction` або звичайну доставку замість preview у стилі thread.
-- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім прибирає її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`.
-- `channels.slack.execApprovals`: нативна доставка exec approval у Slack і авторизація approver. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
+- Власна потокова передача Slack разом зі статусом Slack у стилі асистента "is typing..." для thread потребують ціль відповіді в thread. DM верхнього рівня типово залишаються поза thread, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі thread.
+- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`.
+- `channels.slack.execApprovals`: власна доставка погоджень exec для Slack і авторизація користувачів, що погоджують. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack user ID), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
-| Група дій | Типово | Примітки |
-| ------------ | -------- | ------------------------ |
-| reactions | enabled | Реакції + список реакцій |
-| messages | enabled | Читання/надсилання/редагування/видалення |
-| pins | enabled | Закріпити/відкріпити/список |
-| memberInfo | enabled | Інформація про учасника |
-| emojiList | enabled | Список користувацьких emoji |
+| Група дій | Типово | Примітки |
+| ----------- | -------- | ----------------------- |
+| reactions | увімкнено | Реакції + список реакцій |
+| messages | увімкнено | Читання/надсилання/редагування/видалення |
+| pins | увімкнено | Закріплення/відкріплення/список |
+| memberInfo | увімкнено | Інформація про учасника |
+| emojiList | увімкнено | Список користувацьких emoji |
### Mattermost
-Mattermost постачається як плагін: `openclaw plugins install @openclaw/mattermost`.
+Mattermost постачається як plugin: `openclaw plugins install @openclaw/mattermost`.
```json5
{
@@ -516,7 +516,7 @@ Mattermost постачається як плагін: `openclaw plugins install
native: true, // opt-in
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
- // Необов’язковий явний URL для reverse-proxy/public deployments
+ // Optional explicit URL for reverse-proxy/public deployments
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
textChunkLimit: 4000,
@@ -526,23 +526,23 @@ Mattermost постачається як плагін: `openclaw plugins install
}
```
-Режими чату: `oncall` (відповідати на @-згадки, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з trigger prefix).
+Режими чату: `oncall` (відповідати на @-згадки, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера).
-Коли рідні команди Mattermost увімкнено:
+Коли власні команди Mattermost увімкнені:
- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL.
-- `commands.callbackUrl` має резолвитися до endpoint OpenClaw gateway і бути доступним із сервера Mattermost.
-- Native slash callbacks автентифікуються за допомогою токенів для кожної команди, які
+- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути доступним із сервера Mattermost.
+- Власні slash callback-и автентифікуються per-command токенами, які
Mattermost повертає під час реєстрації slash command. Якщо реєстрація не вдається або
- не активовано жодної команди, OpenClaw відхиляє callbacks із
+ не активовано жодних команд, OpenClaw відхиляє callback-и з повідомленням
`Unauthorized: invalid command token.`
-- Для private/tailnet/internal callback hosts Mattermost може вимагати,
- щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив callback host/domain.
- Використовуйте значення host/domain, а не повні URL.
-- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані через Mattermost.
+- Для приватних/tailnet/internal хостів callback-ів Mattermost може вимагати, щоб
+ `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а.
+ Використовуйте значення хоста/домену, а не повні URL.
+- `channels.mattermost.configWrites`: дозволяти або забороняти записи конфігурації, ініційовані з Mattermost.
- `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах.
-- `channels.mattermost.groups..requireMention`: перевизначення mention-gating для окремого каналу (`"*"` для типового значення).
-- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
+- `channels.mattermost.groups..requireMention`: перевизначення gating за згадкою для окремого каналу (`"*"` для типового значення).
+- Необов’язковий `channels.mattermost.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
### Signal
@@ -551,7 +551,7 @@ Mattermost постачається як плагін: `openclaw plugins install
channels: {
signal: {
enabled: true,
- account: "+15555550123", // необов’язкова прив’язка облікового запису
+ account: "+15555550123", // optional account binding
dmPolicy: "pairing",
allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
configWrites: true,
@@ -563,15 +563,15 @@ Mattermost постачається як плагін: `openclaw plugins install
}
```
-**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`).
+**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`).
-- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal.
-- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані через Signal.
-- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
+- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal.
+- `channels.signal.configWrites`: дозволяти або забороняти записи конфігурації, ініційовані із Signal.
+- Необов’язковий `channels.signal.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
### BlueBubbles
-BlueBubbles — рекомендований шлях для iMessage (на базі плагіна, налаштовується в `channels.bluebubbles`).
+BlueBubbles — рекомендований шлях для iMessage (підтримується plugin, налаштовується в `channels.bluebubbles`).
```json5
{
@@ -579,21 +579,21 @@ BlueBubbles — рекомендований шлях для iMessage (на ба
bluebubbles: {
enabled: true,
dmPolicy: "pairing",
- // serverUrl, password, webhookPath, керування групами та розширені дії:
- // див. /channels/bluebubbles
+ // serverUrl, password, webhookPath, group controls, and advanced actions:
+ // see /channels/bluebubbles
},
},
}
```
- Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
-- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
-- Елементи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP sessions. Використовуйте handle або target string BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
+- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP sessions. Використовуйте рядок handle або target 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). Жоден daemon або port не потрібен.
+OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні.
```json5
{
@@ -617,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Жоден dae
}
```
-- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
+- Необов’язковий `channels.imessage.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
-- Потрібен Full Disk Access до Messages DB.
-- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів.
+- Потрібен Full Disk Access до бази даних Messages.
+- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів.
- `cliPath` може вказувати на SSH wrapper; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP.
- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`).
-- SCP використовує сувору перевірку host-key, тому переконайтеся, що ключ relay host уже існує в `~/.ssh/known_hosts`.
-- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані через iMessage.
-- Елементи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP sessions. Використовуйте нормалізований handle або явну chat target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
+- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ хоста relay уже є в `~/.ssh/known_hosts`.
+- `channels.imessage.configWrites`: дозволяти або забороняти записи конфігурації, ініційовані через iMessage.
+- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP sessions. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
@@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
-Matrix працює через extension і налаштовується в `channels.matrix`.
+Matrix підтримується extension і налаштовується в `channels.matrix`.
```json5
{
@@ -668,25 +668,25 @@ Matrix працює через extension і налаштовується в `cha
}
```
-- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`.
-- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`.
-- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей network opt-in — незалежні механізми.
-- `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у багатооблікових конфігураціях.
-- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові DM-подібні запрошення ігноруються, доки ви не встановите `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`.
-- `channels.matrix.execApprovals`: нативна доставка exec approval у Matrix і авторизація approver.
- - `enabled`: `true`, `false` або `"auto"` (типово). В auto mode exec approvals активуються, коли approver-ів можна визначити з `approvers` або `commands.ownerAllowFrom`.
- - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати exec requests.
- - `agentFilter`: необов’язковий allowlist ID агентів. Пропустіть, щоб пересилати approvals для всіх агентів.
- - `sessionFilter`: необов’язкові шаблони ключів сесій (substring або regex).
- - `target`: куди надсилати approval prompts. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`.
- - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`.
-- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в sessions: `per-user` (типово) спільно використовує routed peer, тоді як `per-room` ізолює кожну DM room.
-- Matrix status probes і live directory lookups використовують ту саму proxy policy, що й runtime traffic.
-- Повну конфігурацію Matrix, правила targeting і приклади налаштування задокументовано в [Matrix](/uk/channels/matrix).
+- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`.
+- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`.
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver-и. `proxy` і цей network opt-in — незалежні механізми керування.
+- `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у конфігураціях із кількома обліковими записами.
+- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`.
+- `channels.matrix.execApprovals`: власна доставка погоджень exec для Matrix і авторизація користувачів, що погоджують.
+ - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли користувачів, що погоджують, можна визначити з `approvers` або `commands.ownerAllowFrom`.
+ - `approvers`: Matrix user ID (наприклад `@owner:example.org`), яким дозволено погоджувати exec-запити.
+ - `agentFilter`: необов’язковий allowlist id агентів. Не вказуйте, щоб пересилати погодження для всіх агентів.
+ - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex).
+ - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (кімната-джерело) або `"both"`.
+ - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`.
+- `channels.matrix.dm.sessionScope` керує тим, як DM у Matrix групуються в сеанси: `per-user` (типово) об’єднує за маршрутизованим peer, а `per-room` ізолює кожну DM-кімнату.
+- Перевірки статусу Matrix і live directory lookups використовують ту саму політику proxy, що й runtime-трафік.
+- Повну конфігурацію Matrix, правила таргетингу та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix).
### Microsoft Teams
-Microsoft Teams працює через extension і налаштовується в `channels.msteams`.
+Microsoft Teams підтримується extension і налаштовується в `channels.msteams`.
```json5
{
@@ -694,19 +694,19 @@ Microsoft Teams працює через extension і налаштовуєтьс
msteams: {
enabled: true,
configWrites: true,
- // appId, appPassword, tenantId, webhook, політики team/channel:
- // див. /channels/msteams
+ // appId, appPassword, tenantId, webhook, team/channel policies:
+ // see /channels/msteams
},
},
}
```
- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`.
-- Повну конфігурацію Teams (облікові дані, webhook, політика DM/group, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams).
+- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams).
### IRC
-IRC працює через extension і налаштовується в `channels.irc`.
+IRC підтримується extension і налаштовується в `channels.irc`.
```json5
{
@@ -728,12 +728,12 @@ IRC працює через extension і налаштовується в `channe
```
- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
-- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він збігається з id налаштованого облікового запису.
-- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/mention gating) задокументовано в [IRC](/uk/channels/irc).
+- Необов’язковий `channels.irc.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає id налаштованого облікового запису.
+- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/gating за згадками) задокументовано в [IRC](/uk/channels/irc).
-### Багатообліковість (усі канали)
+### Кілька облікових записів (усі канали)
-Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`):
+Запускайте кілька облікових записів для одного каналу (кожен зі своїм `accountId`):
```json5
{
@@ -754,28 +754,28 @@ IRC працює через extension і налаштовується в `channe
}
```
-- `default` використовується, коли `accountId` пропущено (CLI + routing).
-- Env tokens застосовуються лише до облікового запису **default**.
-- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для конкретного облікового запису.
+- `default` використовується, коли `accountId` не вказано (CLI + routing).
+- Токени зі змінних середовища застосовуються лише до облікового запису **default**.
+- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису.
- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента.
-- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або onboarding каналу), все ще перебуваючи в однообліковій top-level конфігурації каналу, OpenClaw спочатку переносить однооблікові top-level значення з областю облікового запису в map облікових записів каналу, щоб вихідний обліковий запис продовжив працювати. Для більшості каналів вони переходять у `channels..accounts.default`; Matrix може натомість зберегти наявну відповідну іменовану/default ціль.
-- Наявні bindings лише для каналу (без `accountId`) продовжують відповідати обліковому запису за замовчуванням; bindings з областю облікового запису залишаються необов’язковими.
-- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи однооблікові top-level значення з областю облікового запису у promoted account, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може зберегти наявну відповідну іменовану/default ціль.
+- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або onboarding каналу), поки все ще використовуєте конфігурацію каналу верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису з областю дії облікового запису в мапу облікових записів каналу, щоб початковий обліковий запис продовжував працювати. Для більшості каналів вони переносяться в `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль.
+- Наявні bindings лише для каналу (без `accountId`) продовжують відповідати обліковому запису default; bindings із областю дії облікового запису залишаються необов’язковими.
+- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису з областю дії облікового запису в promoted account, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль.
-### Інші канали extension
+### Інші extension channels
-Багато каналів extension налаштовуються як `channels.` і задокументовані на власних окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
+Багато extension channels налаштовуються як `channels.` і задокументовані на окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
Див. повний індекс каналів: [Channels](/uk/channels).
-### Mention gating у групових чатах
+### Gating за згадками в групових чатах
-Для групових повідомлень типово **потрібна згадка** (згадка в метаданих або безпечні regex patterns). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage.
+Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні шаблони regex). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage.
**Типи згадок:**
-- **Metadata mentions**: рідні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp.
-- **Text patterns**: безпечні regex patterns у `agents.list[].groupChat.mentionPatterns`. Недійсні patterns і небезпечні вкладені повторення ігноруються.
-- Mention gating застосовується лише тоді, коли виявлення можливе (рідні згадки або принаймні один pattern).
+- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp.
+- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечне вкладене повторення ігноруються.
+- Gating за згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон).
```json5
{
@@ -788,9 +788,9 @@ IRC працює через extension і налаштовується в `channe
}
```
-`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або на рівні облікового запису). Встановіть `0`, щоб вимкнути.
+`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Встановіть `0`, щоб вимкнути.
-#### Ліміти історії DM
+#### Обмеження історії для DM
```json5
{
@@ -805,13 +805,13 @@ IRC працює через extension і налаштовується в `channe
}
```
-Порядок визначення: перевизначення для окремого DM → значення провайдера за замовчуванням → без ліміту (зберігається все).
+Визначення значення: перевизначення для окремого DM → типове значення провайдера → без обмеження (зберігається все).
-Підтримується для: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
+Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Режим self-chat
-Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує рідні @-згадки, відповідає лише на text patterns):
+Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони):
```json5
{
@@ -832,21 +832,21 @@ IRC працює через extension і налаштовується в `channe
}
```
-### Commands (обробка chat command)
+### Команди (обробка команд у чаті)
```json5
{
commands: {
- native: "auto", // реєструвати native commands, коли підтримується
- nativeSkills: "auto", // реєструвати native skill commands, коли підтримується
- text: true, // розбирати /commands у chat messages
- bash: false, // дозволити ! (alias: /bash)
+ native: "auto", // register native commands when supported
+ nativeSkills: "auto", // register native skill commands when supported
+ text: true, // parse /commands in chat messages
+ bash: false, // allow ! (alias: /bash)
bashForegroundMs: 2000,
- config: false, // дозволити /config
- mcp: false, // дозволити /mcp
- plugins: false, // дозволити /plugins
- debug: false, // дозволити /debug
- restart: true, // дозволити /restart + інструмент restart gateway
+ config: false, // allow /config
+ mcp: false, // allow /mcp
+ plugins: false, // allow /plugins
+ debug: false, // allow /debug
+ restart: true, // allow /restart + gateway restart tool
ownerAllowFrom: ["discord:123456789012345678"],
ownerDisplay: "raw", // raw | hash
ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
@@ -859,30 +859,30 @@ IRC працює через extension і налаштовується в `channe
}
```
-
+
-- Цей блок налаштовує поверхні команд. Для поточного каталогу built-in + bundled команд див. [Slash Commands](/uk/tools/slash-commands).
-- Ця сторінка — це **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/плагінів та в [Slash Commands](/uk/tools/slash-commands).
-- Текстові команди мають бути **окремими** повідомленнями, що починаються з `/`.
-- `native: "auto"` вмикає native commands для Discord/Telegram, залишає Slack вимкненим.
-- `nativeSkills: "auto"` вмикає native skill commands для Discord/Telegram, залишає Slack вимкненим.
-- Перевизначення на рівні каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані commands.
-- Перевизначайте native skill registration для каналу через `channels..commands.nativeSkills`.
-- `channels.telegram.customCommands` додає додаткові елементи меню Telegram bot.
-- `bash: true` вмикає `! ` для host shell. Потрібно `tools.elevated.enabled`, а відправник має бути в `tools.elevated.allowFrom.`.
-- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; лише читання `/config show` залишається доступним для звичайних operator clients із правом запису.
-- `mcp: true` вмикає `/mcp` для конфігурації MCP server під керуванням OpenClaw у `mcp.servers`.
-- `plugins: true` вмикає `/plugins` для виявлення плагінів, встановлення та керування enable/disable.
-- `channels..configWrites` керує мутаціями конфігурації для кожного каналу (типово: true).
-- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, що націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`).
-- `restart: false` вимикає `/restart` і дії інструмента restart gateway. Типове значення: `true`.
-- `ownerAllowFrom` — це явний owner allowlist для owner-only commands/tools. Він окремий від `allowFrom`.
-- `ownerDisplay: "hash"` хешує owner id у system prompt. Задайте `ownerDisplaySecret`, щоб керувати хешуванням.
-- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (channel allowlists/pairing і `useAccessGroups` ігноруються).
-- `useAccessGroups: false` дозволяє commands обходити політики access-group, коли `allowFrom` не встановлено.
-- Мапа документації команд:
- - built-in + bundled каталог: [Slash Commands](/uk/tools/slash-commands)
- - поверхні команд, специфічні для каналу: [Channels](/uk/channels)
+- Цей блок налаштовує поверхні команд. Для поточного вбудованого + bundled каталогу команд див. [Slash Commands](/uk/tools/slash-commands).
+- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/плагінів, а також у [Slash Commands](/uk/tools/slash-commands).
+- Текстові команди мають бути **окремими** повідомленнями з початковим `/`.
+- `native: "auto"` вмикає нативні команди для Discord/Telegram, а для Slack залишає їх вимкненими.
+- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, а для Slack залишає їх вимкненими.
+- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди.
+- Перевизначайте реєстрацію нативних команд Skills для окремого каналу через `channels..commands.nativeSkills`.
+- `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`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів operator з правом запису.
+- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`.
+- `plugins: true` вмикає `/plugins` для виявлення plugin, встановлення та керування ввімкненням/вимкненням.
+- `channels..configWrites` керує мутаціями конфігурації для окремого каналу (типово: true).
+- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, спрямованими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`).
+- `restart: false` вимикає `/restart` і дії інструмента перезапуску шлюзу. Типове значення: `true`.
+- `ownerAllowFrom` — це явний allowlist власника для команд/інструментів лише для власника. Він відокремлений від `allowFrom`.
+- `ownerDisplay: "hash"` хешує id власника в system prompt. Установіть `ownerDisplaySecret`, щоб керувати хешуванням.
+- `allowFrom` задається окремо для кожного provider. Якщо його встановлено, це **єдине** джерело авторизації (allowlists/pairing каналу та `useAccessGroups` ігноруються).
+- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено.
+- Карта документації команд:
+ - вбудований + bundled каталог: [Slash Commands](/uk/tools/slash-commands)
+ - поверхні команд, специфічні для каналів: [Channels](/uk/channels)
- команди QQ Bot: [QQ Bot](/uk/channels/qqbot)
- команди pairing: [Pairing](/uk/channels/pairing)
- команда картки LINE: [LINE](/uk/channels/line)
@@ -892,7 +892,7 @@ IRC працює через extension і налаштовується в `channe
---
-## Типові значення агентів
+## Типові значення агента
### `agents.defaults.workspace`
@@ -906,7 +906,7 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.repoRoot`
-Необов’язковий корінь репозиторію, який показується в рядку Runtime system prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись вгору від workspace.
+Необов’язковий корінь репозиторію, який показується в рядку Runtime system prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від workspace.
```json5
{
@@ -924,23 +924,23 @@ IRC працює через extension і налаштовується в `channe
agents: {
defaults: { skills: ["github", "weather"] },
list: [
- { id: "writer" }, // успадковує github, weather
- { id: "docs", skills: ["docs-search"] }, // замінює типові
- { id: "locked-down", skills: [] }, // без skills
+ { id: "writer" }, // inherits github, weather
+ { id: "docs", skills: ["docs-search"] }, // replaces defaults
+ { id: "locked-down", skills: [] }, // no 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`
-Вимикає автоматичне створення файлів bootstrap workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
+Вимикає автоматичне створення bootstrap-файлів workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@@ -950,9 +950,9 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.contextInjection`
-Керує тим, коли файли bootstrap workspace вбудовуються в system prompt. Типове значення: `"always"`.
+Керує тим, коли bootstrap-файли workspace вбудовуються в system prompt. Типове значення: `"always"`.
-- `"continuation-skip"`: безпечні continuation turns (після завершеної відповіді assistant) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски heartbeat і повторні спроби після compaction усе одно перебудовують контекст.
+- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски heartbeat і повторні спроби після compaction усе одно перебудовують контекст.
```json5
{
@@ -962,7 +962,7 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.bootstrapMaxChars`
-Максимальна кількість символів у файлі bootstrap workspace перед обрізанням. Типове значення: `20000`.
+Максимальна кількість символів на bootstrap-файл workspace перед обрізанням. Типове значення: `20000`.
```json5
{
@@ -972,7 +972,7 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.bootstrapTotalMaxChars`
-Максимальна загальна кількість символів, що вбудовуються з усіх файлів bootstrap workspace. Типове значення: `150000`.
+Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів workspace. Типове значення: `150000`.
```json5
{
@@ -982,12 +982,12 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.bootstrapPromptTruncationWarning`
-Керує текстом попередження, видимим агенту, коли bootstrap context обрізано.
+Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається.
Типове значення: `"once"`.
- `"off"`: ніколи не вбудовувати текст попередження в system prompt.
-- `"once"`: вбудовувати попередження один раз для кожного унікального підпису обрізання (рекомендовано).
-- `"always"`: вбудовувати попередження під час кожного запуску, якщо є обрізання.
+- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано).
+- `"always"`: вбудовувати попередження під час кожного запуску, коли існує обрізання.
```json5
{
@@ -997,10 +997,10 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.imageMaxDimensionPx`
-Максимальний розмір у пікселях для найдовшої сторони зображення в блоках image transcript/tool перед викликами провайдера.
+Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами provider.
Типове значення: `1200`.
-Менші значення зазвичай зменшують використання vision-token і розмір request payload для запусків із великою кількістю скриншотів.
+Менші значення зазвичай зменшують використання vision-token і розмір payload запиту для запусків із великою кількістю знімків екрана.
Більші значення зберігають більше візуальних деталей.
```json5
@@ -1011,7 +1011,7 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.userTimezone`
-Часовий пояс для контексту system prompt (не для timestamps повідомлень). Якщо не задано, використовується часовий пояс хоста.
+Часовий пояс для контексту system prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста.
```json5
{
@@ -1059,7 +1059,7 @@ IRC працює через extension і налаштовується в `channe
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
- params: { cacheRetention: "long" }, // глобальні типові provider params
+ params: { cacheRetention: "long" }, // global default provider params
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
thinkingDefault: "low",
@@ -1075,44 +1075,44 @@ IRC працює через extension і налаштовується в `channe
```
- `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- - Рядкова форма задає лише primary model.
- - Форма об’єкта задає primary плюс упорядковані failover models.
+ - Рядкова форма задає лише основну модель.
+ - Форма об’єкта задає основну модель плюс упорядковані failover-моделі.
- `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується шляхом інструмента `image` як конфігурація його vision-model.
- - Також використовується як fallback routing, коли вибрана/типова модель не може приймати image input.
+ - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення.
- `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 напряму, також налаштуйте відповідну auth/API key провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`).
- - Якщо пропущено, `image_generate` усе одно може вивести типове значення провайдера з auth. Спочатку він намагається використати поточного провайдера за замовчуванням, а потім інші зареєстровані провайдери image-generation у порядку provider-id.
+ - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею 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` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточний типовий провайдер, потім решту зареєстрованих провайдерів генерації зображень у порядку їхніх id.
- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- - Використовується спільною можливістю генерації музики та built-in інструментом `music_generate`.
+ - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`.
- Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`.
- - Якщо пропущено, `music_generate` усе одно може вивести типове значення провайдера з auth. Спочатку він намагається використати поточного провайдера за замовчуванням, а потім інші зареєстровані провайдери music-generation у порядку provider-id.
- - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну auth/API key провайдера.
+ - Якщо поле не задано, `music_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточний типовий провайдер, потім решту зареєстрованих провайдерів генерації музики в порядку їхніх id.
+ - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key.
- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- - Використовується спільною можливістю генерування відео та built-in інструментом `video_generate`.
+ - Використовується спільною можливістю генерації відео та вбудованим інструментом `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` усе одно може вивести типове значення провайдера з auth. Спочатку він намагається використати поточного провайдера за замовчуванням, а потім інші зареєстровані провайдери video-generation у порядку provider-id.
- - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну auth/API key провайдера.
- - Bundled провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`.
+ - Якщо поле не задано, `video_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточний типовий провайдер, потім решту зареєстрованих провайдерів генерації відео в порядку їхніх id.
+ - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key.
+ - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`.
- `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- - Використовується інструментом `pdf` для маршрутизації моделей.
- - Якщо пропущено, інструмент PDF повертається до `imageModel`, а потім до визначеної session/default model.
-- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передається під час виклику.
-- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується режимом extraction fallback в інструменті `pdf`.
+ - Використовується інструментом `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, потім унікальний configured-provider match для точного model id, і лише після цього повертається до налаштованого default provider (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повертається до першої налаштованої provider/model, а не показує застаріле типове значення видаленого провайдера.
-- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен елемент може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
-- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Встановлюються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`).
-- Пріоритет злиття `params` (config): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), потім `agents.list[].params` (для відповідного agent id) перевизначає за ключем. Див. [Prompt Caching](/uk/reference/prompt-caching) для подробиць.
-- Конфігураційні записувачі, що змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну об’єктну форму й по змозі зберігають наявні fallback lists.
-- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4.
+- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо не вказати provider, OpenClaw спочатку пробує alias, потім унікальний збіг exact model id серед налаштованих provider, і лише потім повертається до налаштованого типового provider (застаріла поведінка сумісності, тому віддавайте перевагу явному `provider/model`). Якщо цей provider більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення для видаленого provider.
+- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
+- `params`: глобальні типові параметри provider, що застосовуються до всіх моделей. Задаються в `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.
-**Вбудовані shorthand-псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
+**Вбудовані alias-скорочення** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
-| Alias | Model |
+| Alias | Модель |
| ------------------- | -------------------------------------- |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
@@ -1123,15 +1123,15 @@ IRC працює через extension і налаштовується в `channe
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
-Ваші налаштовані alias-и завжди мають пріоритет над типовими.
+Ваші налаштовані alias завжди мають пріоритет над типовими значеннями.
-Моделі Z.AI GLM-4.x автоматично вмикають thinking mode, якщо ви не задасте `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно.
-Моделі Z.AI типово вмикають `tool_stream` для stream-ing викликів інструментів. Встановіть `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 типово використовується thinking `adaptive`, коли явний рівень thinking не встановлено.
### `agents.defaults.cliBackends`
-Необов’язкові CLI backends для резервних text-only запусків (без викликів інструментів). Корисно як backup, коли API providers зазнають невдачі.
+Необов’язкові CLI backends для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли провайдери API не працюють.
```json5
{
@@ -1159,13 +1159,13 @@ IRC працює через extension і налаштовується в `channe
}
```
-- CLI backends орієнтовані насамперед на текст; tools завжди вимкнені.
-- Sessions підтримуються, коли задано `sessionArg`.
-- Передавання зображень підтримується, коли `imageArg` приймає file paths.
+- CLI backends орієнтовані на текст; інструменти завжди вимкнені.
+- Сеанси підтримуються, якщо задано `sessionArg`.
+- Пряма передача зображень підтримується, коли `imageArg` приймає шляхи до файлів.
### `agents.defaults.systemPromptOverride`
-Замінює весь system prompt, зібраний OpenClaw, на фіксований рядок. Встановлюється на рівні default (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє або таке, що складається лише з пробілів, значення ігнорується. Корисно для контрольованих експериментів із prompt.
+Замінює весь system prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt.
```json5
{
@@ -1179,23 +1179,23 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.heartbeat`
-Періодичні heartbeat runs.
+Періодичні запуски heartbeat.
```json5
{
agents: {
defaults: {
heartbeat: {
- every: "30m", // 0m вимикає
+ every: "30m", // 0m disables
model: "openai/gpt-5.4-mini",
includeReasoning: false,
- includeSystemPromptSection: true, // типово: true; false прибирає секцію Heartbeat із system prompt
- lightContext: false, // типово: false; true залишає лише HEARTBEAT.md з bootstrap files workspace
- isolatedSession: false, // типово: false; true запускає кожен heartbeat у свіжій сесії (без історії розмови)
+ includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
+ lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
+ isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
session: "main",
to: "+15555550123",
- directPolicy: "allow", // allow (типово) | block
- target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ...
+ directPolicy: "allow", // allow (default) | block
+ target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
prompt: "Read HEARTBEAT.md if it exists...",
ackMaxChars: 300,
suppressToolErrorWarnings: false,
@@ -1205,14 +1205,14 @@ IRC працює через extension і налаштовується в `channe
}
```
-- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API key) або `1h` (OAuth auth). Встановіть `0m`, щоб вимкнути.
-- `includeSystemPromptSection`: коли false, прибирає секцію Heartbeat із system prompt і пропускає вбудовування `HEARTBEAT.md` у bootstrap context. Типове значення: `true`.
-- `suppressToolErrorWarnings`: коли true, приглушує payload-и попереджень про помилки інструментів під час heartbeat runs.
-- `directPolicy`: політика direct/DM delivery. `allow` (типово) дозволяє direct-target delivery. `block` приглушує direct-target delivery і виводить `reason=dm-blocked`.
-- `lightContext`: коли true, heartbeat runs використовують полегшений bootstrap context і залишають лише `HEARTBEAT.md` із bootstrap files 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`, щоб вимкнути.
+- `includeSystemPromptSection`: якщо false, пропускає секцію Heartbeat у system prompt і не вбудовує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`.
+- `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 виконують повні ходи агента — коротші інтервали витрачають більше токенів.
### `agents.defaults.compaction`
@@ -1222,14 +1222,14 @@ IRC працює через extension і налаштовується в `channe
defaults: {
compaction: {
mode: "safeguard", // default | safeguard
- provider: "my-provider", // id зареєстрованого compaction provider plugin (необов’язково)
+ provider: "my-provider", // id of a registered compaction provider plugin (optional)
timeoutSeconds: 900,
reserveTokensFloor: 24000,
identifierPolicy: "strict", // strict | off | custom
- identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom
- postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування
- model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction
- notifyUser: true, // надсилати коротке повідомлення, коли починається compaction (типово: false)
+ identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
+ postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
+ model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
+ notifyUser: true, // send a brief notice when compaction starts (default: false)
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
@@ -1242,19 +1242,19 @@ IRC працює через extension і налаштовується в `channe
}
```
-- `mode`: `default` або `safeguard` (узагальнення частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction).
-- `provider`: id зареєстрованого compaction provider plugin. Якщо встановлено, викликається `summarize()` провайдера замість built-in LLM summarization. У разі помилки виконується fallback до built-in. Встановлення provider примушує `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction).
-- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction перед тим, як OpenClaw перерве її. Типове значення: `900`.
-- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає built-in guidance для збереження opaque identifier перед compaction summarization.
-- `identifierInstructions`: необов’язковий користувацький текст для збереження identifier, який використовується, коли `identifierPolicy=custom`.
-- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які треба повторно вбудувати після compaction. Типове значення — `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Якщо значення не задано або явно встановлено саме цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як legacy fallback.
-- `model`: необов’язкове перевизначення `provider/model-id` лише для compaction summarization. Використовуйте це, коли основна сесія має залишатися на одній моделі, а compaction summaries повинні виконуватися на іншій; якщо не задано, compaction використовує primary model сесії.
-- `notifyUser`: коли `true`, надсилає користувачу коротке повідомлення, коли починається compaction (наприклад, "Compacting context..."). Типово вимкнено, щоб compaction був безшумним.
-- `memoryFlush`: тихий agentic turn перед auto-compaction для збереження довготривалої пам’яті. Пропускається, коли workspace доступний лише для читання.
+- `mode`: `default` або `safeguard` (підсумовування великих історій чанками). Див. [Compaction](/uk/concepts/compaction).
+- `provider`: id зареєстрованого plugin провайдера compaction. Якщо встановлено, замість вбудованого LLM-підсумовування викликається `summarize()` цього провайдера. У разі помилки використовується вбудований варіант. Встановлення провайдера примусово задає `mode: "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`: тихий agentic-хід перед автоматичною compaction для збереження довготривалих спогадів. Пропускається, якщо workspace доступний лише для читання.
### `agents.defaults.contextPruning`
-Обрізає **старі tool results** з in-memory context перед надсиланням до LLM. **Не** змінює історію сесії на диску.
+Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням у LLM. **Не** змінює історію сеансу на диску.
```json5
{
@@ -1262,7 +1262,7 @@ IRC працює через extension і налаштовується в `channe
defaults: {
contextPruning: {
mode: "cache-ttl", // off | cache-ttl
- ttl: "1h", // тривалість (ms/s/m/h), одиниця за замовчуванням: хвилини
+ ttl: "1h", // duration (ms/s/m/h), default unit: minutes
keepLastAssistants: 3,
softTrimRatio: 0.3,
hardClearRatio: 0.5,
@@ -1278,25 +1278,25 @@ IRC працює через extension і налаштовується в `channe
-- `mode: "cache-ttl"` вмикає проходи pruning.
-- `ttl` керує тим, як часто pruning може запускатися повторно (після останнього cache touch).
-- Pruning спочатку м’яко обрізає завеликі результати інструментів, а потім жорстко очищує старіші результати, якщо це потрібно.
+- `mode: "cache-ttl"` вмикає проходи обрізання.
+- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу).
+- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів.
-**Soft-trim** зберігає початок + кінець і вставляє `...` посередині.
+**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині.
-**Hard-clear** замінює весь результат інструмента placeholder-ом.
+**Повне очищення** замінює весь результат інструмента placeholder-ом.
Примітки:
-- Image blocks ніколи не обрізаються/очищуються.
-- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів.
-- Якщо є менше ніж `keepLastAssistants` assistant messages, pruning пропускається.
+- Блоки зображень ніколи не обрізаються і не очищаються.
+- Співвідношення рахуються за символами (приблизно), а не за точною кількістю токенів.
+- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається.
-Див. [Session Pruning](/uk/concepts/session-pruning) для подробиць поведінки.
+Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning).
-### Block streaming
+### Блокова потокова передача
```json5
{
@@ -1306,19 +1306,19 @@ IRC працює через extension і налаштовується в `channe
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 (use minMs/maxMs)
},
},
}
```
-- Канали, окрім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути block replies.
-- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`.
-- `humanDelay`: випадкова пауза між block replies. `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) для поведінки та подробиць chunking.
+Докладніше про поведінку й чанкування див. у [Streaming](/uk/concepts/streaming).
-### Typing indicators
+### Індикатори введення
```json5
{
@@ -1331,8 +1331,8 @@ IRC працює через extension і налаштовується в `channe
}
```
-- Типові значення: `instant` для direct chats/mentions, `message` для group chats без згадки.
-- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`.
+- Типові значення: `instant` для особистих чатів/згадок, `message` для групових чатів без згадки.
+- Перевизначення для окремого сеансу: `session.typingMode`, `session.typingIntervalSeconds`.
Див. [Typing Indicators](/uk/concepts/typing-indicators).
@@ -1340,7 +1340,7 @@ IRC працює через extension і налаштовується в `channe
### `agents.defaults.sandbox`
-Необов’язкове sandboxing для вбудованого агента. Повний посібник див. в [Sandboxing](/uk/gateway/sandboxing).
+Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing).
```json5
{
@@ -1386,7 +1386,7 @@ IRC працює через extension і налаштовується в `channe
identityFile: "~/.ssh/id_ed25519",
certificateFile: "~/.ssh/id_ed25519-cert.pub",
knownHostsFile: "~/.ssh/known_hosts",
- // Також підтримуються SecretRef / inline contents:
+ // SecretRefs / inline contents also supported:
// identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
// certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
// knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
@@ -1435,52 +1435,52 @@ IRC працює через extension і налаштовується в `channe
}
```
-
+
**Backend:**
-- `docker`: локальний Docker runtime (типово)
-- `ssh`: загальний віддалений runtime на базі SSH
+- `docker`: локальний runtime Docker (типово)
+- `ssh`: універсальний віддалений runtime на основі SSH
- `openshell`: runtime OpenShell
-Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до
+Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в
`plugins.entries.openshell.config`.
-**Конфігурація SSH backend:**
+**Конфігурація backend SSH:**
-- `target`: SSH target у форматі `user@host[:port]`
-- `command`: команда SSH client (типово: `ssh`)
-- `workspaceRoot`: абсолютний віддалений root, що використовується для workspace-ів кожного scope
-- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH
-- `identityData` / `certificateData` / `knownHostsData`: inline contents або SecretRef, які OpenClaw матеріалізує у temp files під час виконання
-- `strictHostKeyChecking` / `updateHostKeys`: параметри політики host-key OpenSSH
+- `target`: SSH-ціль у форматі `user@host[:port]`
+- `command`: команда SSH-клієнта (типово: `ssh`)
+- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace з різною областю дії
+- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH
+- `identityData` / `certificateData` / `knownHostsData`: inline-вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime
+- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH
-**Пріоритет SSH auth:**
+**Пріоритет SSH-автентифікації:**
- `identityData` має пріоритет над `identityFile`
- `certificateData` має пріоритет над `certificateFile`
- `knownHostsData` має пріоритет над `knownHostsFile`
-- Значення `*Data` на базі SecretRef визначаються з активного secrets runtime snapshot перед запуском sandbox session
+- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сеансу sandbox
-**Поведінка SSH backend:**
+**Поведінка backend SSH:**
-- ініціалізує remote workspace один раз після create або recreate
-- потім зберігає remote SSH workspace як канонічний
-- маршрутизує `exec`, file tools і media paths через SSH
-- не синхронізує remote changes назад на host автоматично
-- не підтримує sandbox browser containers
+- один раз ініціалізує віддалений workspace після створення або повторного створення
+- потім зберігає віддалений SSH workspace як канонічний
+- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH
+- не синхронізує віддалені зміни назад на хост автоматично
+- не підтримує браузерні контейнери sandbox
**Доступ до workspace:**
-- `none`: workspace sandbox для кожного scope у `~/.openclaw/sandboxes`
-- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent`
-- `rw`: workspace агента монтується для читання/запису в `/workspace`
+- `none`: workspace sandbox з різною областю дії у `~/.openclaw/sandboxes`
+- `ro`: workspace sandbox у `/workspace`, workspace агента змонтовано лише для читання в `/agent`
+- `rw`: workspace агента змонтовано для читання/запису в `/workspace`
-**Scope:**
+**Область дії:**
-- `session`: container + workspace для кожної сесії
-- `agent`: один container + workspace на агента (типово)
-- `shared`: спільний container і workspace (без ізоляції між сесіями)
+- `session`: контейнер + workspace для кожного сеансу
+- `agent`: один контейнер + workspace для кожного агента (типово)
+- `shared`: спільний контейнер і workspace (без міжсеансової ізоляції)
**Конфігурація plugin OpenShell:**
@@ -1495,10 +1495,10 @@ IRC працює через extension і налаштовується в `channe
from: "openclaw",
remoteWorkspaceDir: "/sandbox",
remoteAgentWorkspaceDir: "/agent",
- gateway: "lab", // необов’язково
- gatewayEndpoint: "https://lab.example", // необов’язково
- policy: "strict", // необов’язковий id політики OpenShell
- providers: ["openai"], // необов’язково
+ gateway: "lab", // optional
+ gatewayEndpoint: "https://lab.example", // optional
+ policy: "strict", // optional OpenShell policy id
+ providers: ["openai"], // optional
autoProviders: true,
timeoutSeconds: 120,
},
@@ -1510,30 +1510,30 @@ IRC працює через extension і налаштовується в `channe
**Режим OpenShell:**
-- `mirror`: ініціалізувати remote з local перед exec, синхронізувати назад після exec; local workspace лишається канонічним
-- `remote`: ініціалізувати remote один раз під час створення sandbox, потім зберігати remote workspace канонічним
+- `mirror`: ініціалізувати віддалене середовище з локального перед `exec`, синхронізувати назад після `exec`; локальний workspace залишається канонічним
+- `remote`: один раз ініціалізувати віддалене середовище під час створення sandbox, потім зберігати віддалений workspace як канонічний
-У режимі `remote` локальні зміни на host, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після етапу ініціалізації.
-Transport здійснюється через SSH у sandbox OpenShell, але plugin володіє життєвим циклом sandbox та необов’язковою mirror sync.
+У режимі `remote` зміни на локальному хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації.
+Транспорт — це SSH до sandbox OpenShell, але plugin володіє життєвим циклом sandbox і необов’язковою синхронізацією mirror.
-**`setupCommand`** виконується один раз після створення container (через `sh -lc`). Потрібні network egress, writable root, root user.
+**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потрібні мережевий вихід, кореневий файловий розділ із записом і користувач root.
-**Типово containers використовують `network: "none"`** — встановіть `"bridge"` (або custom bridge network), якщо агенту потрібен вихід назовні.
-`"host"` блокується. `"container:"` типово блокується, якщо ви явно не встановите
-`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass).
+**Для контейнерів типово встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ.
+`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите
+`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass).
-**Вхідні вкладення** staging-уються в `media/inbound/*` в активному workspace.
+**Вхідні вкладення** розміщуються в `media/inbound/*` активного workspace.
-**`docker.binds`** монтує додаткові каталоги host; global і per-agent binds зливаються.
+**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються.
-**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP у container. URL noVNC вбудовується в system prompt. Не потребує `browser.enabled` в `openclaw.json`.
-Observer access через noVNC типово використовує VNC auth, а OpenClaw видає short-lived token URL (замість того, щоб показувати пароль у спільному URL).
+**Ізольований браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в system prompt. Не потребує `browser.enabled` у `openclaw.json`.
+Доступ спостерігача noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL).
-- `allowHostControl: false` (типово) блокує націлення sandboxed sessions на browser host.
-- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge network). Встановлюйте `bridge` лише тоді, коли вам явно потрібне глобальне bridge connectivity.
-- `cdpSourceRange` необов’язково обмежує CDP ingress на краю container до CIDR range (наприклад `172.21.0.1/32`).
-- `sandbox.browser.binds` монтує додаткові каталоги host лише в container sandbox browser. Якщо задано (включно з `[]`), він замінює `docker.binds` для container browser.
-- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для container hosts:
+- `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`
@@ -1554,24 +1554,23 @@ Observer access через noVNC типово використовує VNC auth,
- `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu`
типово увімкнені й можуть бути вимкнені через
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно.
- - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо вони
- потрібні у вашому робочому процесі.
+ - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш workflow
+ залежить від них.
- `--renderer-process-limit=2` можна змінити через
- `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати
- типовий ліміт process Chromium.
- - плюс `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`.
- - Типові значення — це baseline container image; використовуйте custom browser image з custom
- entrypoint, щоб змінити типові значення container.
+ `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; встановіть `0`, щоб використовувати
+ типовий ліміт процесів Chromium.
+ - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`.
+ - Ці значення за замовчуванням є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний образ браузера з власним entrypoint.
-Browser sandboxing і `sandbox.docker.binds` доступні лише для Docker.
+Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker.
-Збірка образів:
+Зберіть образи:
```bash
-scripts/sandbox-setup.sh # основний образ sandbox
-scripts/sandbox-browser-setup.sh # необов’язковий образ browser
+scripts/sandbox-setup.sh # main sandbox image
+scripts/sandbox-browser-setup.sh # optional browser image
```
### `agents.list` (перевизначення для окремого агента)
@@ -1586,12 +1585,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
name: "Main Agent",
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" }, // перевизначає matching defaults.models params за ключем
- skills: ["docs-search"], // замінює agents.defaults.skills, коли задано
+ model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
+ thinkingDefault: "high", // per-agent thinking level override
+ reasoningDefault: "on", // per-agent reasoning visibility override
+ fastModeDefault: false, // per-agent fast mode override
+ params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
+ skills: ["docs-search"], // replaces agents.defaults.skills when set
identity: {
name: "Samantha",
theme: "helpful sloth",
@@ -1623,23 +1622,23 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
```
- `id`: стабільний id агента (обов’язково).
-- `default`: якщо встановлено для кількох, перший має пріоритет (реєструється попередження). Якщо не встановлено жодного, типовим є перший елемент списку.
-- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає global fallbacks). Cron jobs, що перевизначають лише `primary`, усе ще успадковують default fallbacks, якщо ви не задасте `fallbacks: []`.
-- `params`: stream params для окремого агента, злиті поверх вибраного елемента моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей.
-- `skills`: необов’язковий allowlist 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`: необов’язковий descriptor runtime для окремого агента. Використовуйте `type: "acp"` з defaults у `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати ACP harness sessions.
-- `identity.avatar`: шлях відносно workspace, `http(s)` URL або `data:` URI.
+- `default`: якщо встановлено кілька, використовується перший (з попередженням у журналі). Якщо не встановлено жодного, типовим є перший запис у списку.
+- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron jobs, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо ви не встановите `fallbacks: []`.
+- `params`: параметри потоку для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
+- `skills`: необов’язковий allowlist 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, URL `http(s)` або URI `data:`.
- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`.
- `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент).
-- Захист успадкування sandbox: якщо requester session sandboxed, `sessions_spawn` відхиляє цілі, які працювали б без sandbox.
-- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує явно вибирати profile; типово: false).
+- Захист успадкування sandbox: якщо сеанс-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox.
+- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false).
---
-## Маршрутизація між кількома агентами
+## Маршрутизація кількох агентів
Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
@@ -1660,27 +1659,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
### Поля відповідності binding
-- `type` (необов’язково): `route` для звичайної маршрутизації (якщо type відсутній, типово використовується route), `acp` для постійних ACP conversation bindings.
+- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних ACP bindings розмов.
- `match.channel` (обов’язково)
-- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = обліковий запис за замовчуванням)
+- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис)
- `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`)
-- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу)
-- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }`
+- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу)
+- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }`
**Детермінований порядок відповідності:**
1. `match.peer`
2. `match.guildId`
3. `match.teamId`
-4. `match.accountId` (точний, без peer/guild/team)
-5. `match.accountId: "*"` (у межах усього каналу)
-6. Агент за замовчуванням
+4. `match.accountId` (точний збіг, без peer/guild/team)
+5. `match.accountId: "*"` (для всього каналу)
+6. Типовий агент
-У межах кожного рівня перемагає перший запис `bindings`, що збігається.
+У межах кожного рівня перемагає перший запис `bindings`, що збігся.
-Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю conversation (`match.channel` + account + `match.peer.id`) і не використовує наведену вище tier order для route binding.
+Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding.
-### Профілі доступу для окремих агентів
+### Профілі доступу для окремого агента
@@ -1700,7 +1699,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
-
+
```json5
{
@@ -1729,7 +1728,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
-
+
```json5
{
@@ -1775,7 +1774,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
-Див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools) для подробиць щодо пріоритетів.
+Подробиці про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
---
@@ -1801,22 +1800,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
- parentForkMaxTokens: 100000, // пропустити parent-thread fork вище цього ліміту токенів (0 вимикає)
+ parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
maintenance: {
mode: "warn", // warn | enforce
pruneAfter: "30d",
maxEntries: 500,
rotateBytes: "10mb",
- resetArchiveRetention: "30d", // тривалість або false
- maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет
- highWaterBytes: "400mb", // необов’язкова ціль очищення
+ resetArchiveRetention: "30d", // duration or false
+ maxDiskBytes: "500mb", // optional hard budget
+ highWaterBytes: "400mb", // optional cleanup target
},
threadBindings: {
enabled: true,
- idleHours: 24, // типове автоматичне unfocus через бездіяльність у годинах (`0` вимикає)
- maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає)
+ idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
+ maxAgeHours: 0, // default hard max age in hours (`0` disables)
},
- mainKey: "main", // legacy (runtime завжди використовує "main")
+ mainKey: "main", // legacy (runtime always uses "main")
agentToAgent: { maxPingPongTurns: 5 },
sendPolicy: {
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
@@ -1826,48 +1825,48 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
-
+
-- **`scope`**: базова стратегія групування sessions для контекстів групового чату.
- - `per-sender` (типово): кожен відправник отримує ізольовану session у межах контексту каналу.
- - `global`: усі учасники контексту каналу поділяють одну session (використовуйте лише тоді, коли задумано спільний контекст).
+- **`scope`**: базова стратегія групування сеансів для контекстів групового чату.
+ - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу.
+ - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли спільний контекст справді потрібен).
- **`dmScope`**: як групуються DM.
- - `main`: усі DM використовують спільну main session.
+ - `main`: усі DM спільно використовують основний сеанс.
- `per-peer`: ізоляція за id відправника між каналами.
- - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox-ів із багатьма користувачами).
- - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості).
-- **`identityLinks`**: мапа канонічних id до peer-ів із префіксом провайдера для спільного використання сесій між каналами.
-- **`reset`**: основна політика reset. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Коли налаштовано обидва варіанти, перемагає той, чий термін настане раніше.
+ - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для inbox з кількома користувачами).
+ - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для кількох облікових записів).
+- **`identityLinks`**: зіставляє канонічні id з peer-и з префіксом provider для спільного використання сеансів між каналами.
+- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що завершується раніше.
- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`.
-- **`parentForkMaxTokens`**: максимальне значення `totalTokens` parent session, дозволене під час створення forked thread session (типово `100000`).
- - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає свіжу thread session замість успадкування parent transcript history.
- - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти parent forking.
+- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення розгалуженого сеансу thread (типове значення `100000`).
+ - Якщо значення `totalTokens` батьківського сеансу вище за це, OpenClaw починає новий сеанс thread замість успадкування історії transcript батьківського сеансу.
+ - Установіть `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`. Перший deny має пріоритет.
-- **`maintenance`**: очищення + керування утриманням session-store.
- - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення.
- - `pruneAfter`: поріг віку для застарілих записів (типово `30d`).
+- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді у відповідь між агентами під час обмінів agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong.
+- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny має пріоритет.
+- **`maintenance`**: керування очищенням сховища сеансів і строками зберігання.
+ - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення.
+ - `pruneAfter`: граничний вік для застарілих записів (типово `30d`).
- `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`).
- - `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`).
- - `resetArchiveRetention`: термін зберігання archive transcript `*.reset.`. Типово дорівнює `pruneAfter`; задайте `false`, щоб вимкнути.
- - `maxDiskBytes`: необов’язковий дисковий бюджет для каталогу sessions. У режимі `warn` просто журналює попередження; у режимі `enforce` спочатку видаляє найстаріші artifacts/sessions.
+ - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`).
+ - `resetArchiveRetention`: строк зберігання архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути.
+ - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сеансів. У режимі `warn` виводить попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси.
- `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`.
-- **`threadBindings`**: глобальні типові значення для можливостей сесій, прив’язаних до thread.
- - `enabled`: основний типовий перемикач (провайдери можуть перевизначити; Discord використовує `channels.discord.threadBindings.enabled`)
- - `idleHours`: типове автоматичне unfocus через бездіяльність у годинах (`0` вимикає; провайдери можуть перевизначити)
- - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначити)
+- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до thread.
+ - `enabled`: головний перемикач типового значення (provider можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`)
+ - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; provider можуть перевизначати)
+ - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; provider можуть перевизначати)
---
-## Messages
+## Повідомлення
```json5
{
messages: {
- responsePrefix: "🦞", // або "auto"
+ responsePrefix: "🦞", // or "auto"
ackReaction: "👀",
ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
removeAckAfterReply: false,
@@ -1882,7 +1881,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
},
},
inbound: {
- debounceMs: 2000, // 0 вимикає
+ debounceMs: 2000, // 0 disables
byChannel: {
whatsapp: 5000,
slack: 1500,
@@ -1894,36 +1893,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
### Префікс відповіді
-Перевизначення на рівні каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`.
+Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`.
-Порядок визначення (найспецифічніше перемагає): account → channel → global. `""` вимикає й зупиняє cascade. `"auto"` виводить `[{identity.name}]`.
+Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне значення. `""` вимикає префікс і зупиняє каскад. `"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}`| Назва identity агента | (те саме, що `"auto"`) |
+| `{provider}` | Назва provider | `anthropic` |
+| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` |
+| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) |
Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`.
-### Ack reaction
+### Реакція підтвердження
-- Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути.
-- Перевизначення на рівні каналу: `channels..ackReaction`, `channels..accounts..ackReaction`.
-- Порядок визначення: account → channel → `messages.ackReaction` → fallback identity.
-- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`.
-- `removeAckAfterReply`: прибирає ack після reply у Slack, Discord і Telegram.
-- `messages.statusReactions.enabled`: вмикає lifecycle status reactions у Slack, Discord і Telegram.
- У Slack і Discord, якщо не встановлено, status reactions залишаються увімкненими, коли активні ack reactions.
- У Telegram явно встановіть `true`, щоб увімкнути lifecycle status reactions.
+- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути.
+- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`.
+- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity.
+- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`.
+- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram.
+- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram.
+ У Slack і Discord, якщо не задано, реакції статусу залишаються увімкненими, коли активні реакції підтвердження.
+ У Telegram установіть це поле явно в `true`, щоб увімкнути реакції статусу життєвого циклу.
-### Inbound debounce
+### Вхідний debounce
-Об’єднує швидкі text-only messages від того самого відправника в один хід агента. Media/attachments скидаються негайно. Команди керування обходять debouncing.
+Об’єднує швидкі текстові повідомлення від одного й того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce.
### TTS (text-to-speech)
@@ -1966,12 +1965,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
-- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні prefs, а `/tts status` показує фактичний стан.
-- `summaryModel` перевизначає `agents.defaults.model.primary` для auto-summary.
-- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібне явне увімкнення).
-- API keys повертаються до `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
-- `openai.baseUrl` перевизначає endpoint TTS OpenAI. Порядок визначення: config, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`.
-- Коли `openai.baseUrl` вказує на не-OpenAI endpoint, OpenClaw розглядає його як OpenAI-compatible TTS server і послаблює перевірку model/voice.
+- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан.
+- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку.
+- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in).
+- 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` вказує на не-OpenAI endpoint, OpenClaw розглядає його як OpenAI-compatible TTS-сервер і послаблює перевірку model/voice.
---
@@ -2001,51 +2000,51 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
-- `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` приймає plaintext strings або об’єкти SecretRef.
-- Fallback `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано Talk API key.
-- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви.
-- `silenceTimeoutMs` керує тим, скільки Talk mode чекає після тиші користувача перед надсиланням transcript. Якщо не встановлено, зберігається типове platform pause window (`700 ms на macOS і Android, 900 ms на iOS`).
+- `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` приймає plaintext-рядки або об’єкти SecretRef.
+- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk.
+- `providers.*.voiceAliases` дозволяє директивам Talk використовувати зручні для читання назви.
+- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після тиші користувача, перш ніж надіслати transcript. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`).
---
-## Tools
+## Інструменти
### Профілі інструментів
`tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`:
-Під час локального onboarding нові локальні конфігурації типово отримують `tools.profile: "coding"`, якщо значення не встановлено (наявні явні профілі зберігаються).
+Локальний onboarding типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються).
-| Профіль | Містить |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `minimal` | лише `session_status` |
+| Профіль | Містить |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `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` | Без обмежень (так само, як і коли не задано) |
+| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
+| `full` | Без обмежень (те саме, що й коли не задано) |
### Групи інструментів
-| Група | Інструменти |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) |
-| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
+| Група | Інструменти |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `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` | Усі built-in tools (без provider plugins) |
+| `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 plugins) |
### `tools.allow` / `tools.deny`
-Глобальна політика allow/deny для інструментів (deny має пріоритет). Нечутлива до регістру, підтримує wildcard-и `*`. Застосовується, навіть коли Docker sandbox вимкнено.
+Глобальна політика дозволу/заборони інструментів (deny має пріоритет). Нечутлива до регістру, підтримує wildcard-и `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено.
```json5
{
@@ -2055,7 +2054,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
### `tools.byProvider`
-Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: base profile → provider profile → allow/deny.
+Додатково обмежує інструменти для конкретних provider або моделей. Порядок: базовий профіль → профіль provider → allow/deny.
```json5
{
@@ -2071,7 +2070,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
### `tools.elevated`
-Керує elevated exec access поза sandbox:
+Керує підвищеним доступом до `exec` поза sandbox:
```json5
{
@@ -2087,9 +2086,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
-- Перевизначення на рівні агента (`agents.list[].tools.elevated`) може лише додатково обмежувати.
-- `/elevated on|off|ask|full` зберігає стан для кожної сесії; inline directives застосовуються до одного повідомлення.
-- Elevated `exec` обходить sandboxing і використовує налаштований escape path (`gateway` типово або `node`, коли exec target дорівнює `node`).
+- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати.
+- `/elevated on|off|ask|full` зберігає стан для кожного сеансу; inline-директиви застосовуються до одного повідомлення.
+- Підвищений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово, або `node`, коли ціль `exec` — `node`).
### `tools.exec`
@@ -2113,8 +2112,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
### `tools.loopDetection`
-Перевірки безпеки loop для інструментів **типово вимкнені**. Встановіть `enabled: true`, щоб активувати виявлення.
-Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`.
+Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення.
+Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`.
```json5
{
@@ -2135,14 +2134,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
-- `historySize`: максимальна історія викликів інструментів, яка зберігається для аналізу loop.
-- `warningThreshold`: поріг повторюваних шаблонів без прогресу для попереджень.
-- `criticalThreshold`: вищий поріг повторень для блокування критичних loop.
-- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу.
-- `detectors.genericRepeat`: попереджати про повторні виклики одного й того самого інструмента з однаковими аргументами.
-- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll tools (`process.poll`, `command_status` тощо).
+- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів.
+- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень.
+- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів.
+- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу.
+- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами.
+- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо).
- `detectors.pingPong`: попереджати/блокувати чергування парних шаблонів без прогресу.
-- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою.
+- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація не проходить.
### `tools.web`
@@ -2152,14 +2151,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
web: {
search: {
enabled: true,
- apiKey: "brave_api_key", // або env BRAVE_API_KEY
+ apiKey: "brave_api_key", // or BRAVE_API_KEY env
maxResults: 5,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
},
fetch: {
enabled: true,
- provider: "firecrawl", // необов’язково; пропустіть для auto-detect
+ provider: "firecrawl", // optional; omit for auto-detect
maxChars: 50000,
maxCharsCap: 50000,
maxResponseBytes: 2000000,
@@ -2176,7 +2175,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
### `tools.media`
-Налаштовує розуміння вхідних медіа (image/audio/video):
+Налаштовує розуміння вхідних медіа (зображення/аудіо/відео):
```json5
{
@@ -2184,7 +2183,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
media: {
concurrency: 2,
asyncCompletion: {
- directSend: false, // opt-in: надсилати завершені async music/video напряму в канал
+ directSend: false, // opt-in: send finished async music/video directly to the channel
},
audio: {
enabled: true,
@@ -2208,32 +2207,32 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br
}
```
-
+
-**Запис провайдера** (`type: "provider"` або пропущено):
+**Запис provider** (`type: "provider"` або пропущено):
-- `provider`: id API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо)
-- `model`: перевизначення model id
-- `profile` / `preferredProfile`: вибір profile з `auth-profiles.json`
+- `provider`: id API provider (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо)
+- `model`: перевизначення id моделі
+- `profile` / `preferredProfile`: вибір профілю `auth-profiles.json`
-**CLI entry** (`type: "cli"`):
+**Запис CLI** (`type: "cli"`):
-- `command`: executable для запуску
-- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо)
+- `command`: виконуваний файл для запуску
+- `args`: шаблонізовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо)
**Спільні поля:**
- `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
-- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для конкретного entry.
-- У разі помилки виконується fallback до наступного entry.
+- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису.
+- У разі помилки використовується наступний запис.
-Provider auth дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`.
+Автентифікація provider дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`.
**Поля async completion:**
-- `asyncCompletion.directSend`: коли `true`, завершені async-завдання `music_generate`
- і `video_generate` спочатку намагаються доставити результат напряму в канал. Типове значення: `false`
- (legacy шлях requester-session wake/model-delivery).
+- `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate`
+ і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типове значення: `false`
+ (застарілий шлях пробудження requester-session/model-delivery).
@@ -2252,9 +2251,9 @@ Provider auth дотримується стандартного порядку:
### `tools.sessions`
-Керує тим, на які sessions можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`).
+Керує тим, на які сеанси можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`).
-Типове значення: `tree` (поточна session + sessions, породжені нею, наприклад subagents).
+Типове значення: `tree` (поточний сеанс + сеанси, породжені ним, наприклад subagents).
```json5
{
@@ -2269,26 +2268,26 @@ Provider auth дотримується стандартного порядку:
Примітки:
-- `self`: лише поточний session key.
-- `tree`: поточна session + sessions, породжені поточною session (subagents).
-- `agent`: будь-яка session, що належить поточному agent id (може включати інших користувачів, якщо ви запускаєте per-sender sessions під тим самим agent id).
-- `all`: будь-яка session. Націлення між агентами все одно потребує `tools.agentToAgent`.
-- Sandbox clamp: коли поточна session sandboxed і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
+- `self`: лише ключ поточного сеансу.
+- `tree`: поточний сеанс + сеанси, породжені поточним сеансом (subagents).
+- `agent`: будь-який сеанс, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сеанси per-sender під тим самим id агента).
+- `all`: будь-який сеанс. Націлювання між агентами все одно потребує `tools.agentToAgent`.
+- Обмеження sandbox: коли поточний сеанс працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
### `tools.sessions_spawn`
-Керує підтримкою inline attachments для `sessions_spawn`.
+Керує підтримкою inline-вкладень для `sessions_spawn`.
```json5
{
tools: {
sessions_spawn: {
attachments: {
- enabled: false, // opt-in: встановіть true, щоб дозволити inline file attachments
- maxTotalBytes: 5242880, // 5 MB загалом для всіх файлів
+ enabled: false, // opt-in: set true to allow inline file attachments
+ maxTotalBytes: 5242880, // 5 MB total across all files
maxFiles: 50,
- maxFileBytes: 1048576, // 1 MB на файл
- retainOnSessionKeep: false, // зберігати attachments, коли cleanup="keep"
+ maxFileBytes: 1048576, // 1 MB per file
+ retainOnSessionKeep: false, // keep attachments when cleanup="keep"
},
},
},
@@ -2297,22 +2296,22 @@ Provider auth дотримується стандартного порядку:
Примітки:
-- Attachments підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє.
-- Файли матеріалізуються в child workspace у `.openclaw/attachments//` з `.manifest.json`.
-- Вміст attachment автоматично редагується в transcript persistence.
-- Base64 inputs перевіряються за допомогою суворих перевірок alphabet/padding і guard-а розміру до декодування.
-- Дозволи на файли: `0700` для каталогів і `0600` для файлів.
-- Очищення дотримується політики `cleanup`: `delete` завжди видаляє attachments; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`.
+- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє.
+- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` разом із `.manifest.json`.
+- Вміст вкладень автоматично редагується в збереженні transcript.
+- Base64-вхідні дані перевіряються з суворою перевіркою алфавіту/відступів і попередньою перевіркою розміру до декодування.
+- Для каталогів використовуються права `0700`, а для файлів — `0600`.
+- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
### `tools.experimental`
-Експериментальні built-in flags для інструментів. Типово вимкнено, якщо не діє runtime-specific правило auto-enable.
+Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоувімкнення, специфічне для runtime.
```json5
{
tools: {
experimental: {
- planTool: true, // увімкнути експериментальний update_plan
+ planTool: true, // enable experimental update_plan
},
},
}
@@ -2321,8 +2320,8 @@ Provider auth дотримується стандартного порядку:
Примітки:
- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи.
-- Типове значення: `false` для не-OpenAI провайдерів. Запуски OpenAI і OpenAI Codex автоматично вмикають його, якщо значення не задано; встановіть `false`, щоб вимкнути це автоувімкнення.
-- Коли увімкнено, system prompt також додає guidance щодо використання, щоб модель використовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`.
+- Типове значення: `false` для не-OpenAI provider. Для запусків OpenAI і OpenAI Codex він автоувімкнений, якщо не задано явно; установіть `false`, щоб вимкнути це автоувімкнення.
+- Коли увімкнено, system prompt також додає інструкції з використання, щоб модель використовувала його лише для суттєвої роботи і тримала не більше одного кроку `in_progress`.
### `agents.defaults.subagents`
@@ -2342,21 +2341,21 @@ Provider auth дотримується стандартного порядку:
}
```
-- `model`: типова модель для spawned sub-agents. Якщо пропущено, sub-agents успадковують модель викликача.
-- `allowAgents`: типовий allowlist target agent ids для `sessions_spawn`, коли requester agent не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент).
-- `runTimeoutSeconds`: типовий timeout (секунди) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає відсутність timeout.
+- `model`: типова модель для породжених sub-agents. Якщо не задано, sub-agents успадковують модель виклику.
+- `allowAgents`: типовий allowlist id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент).
+- `runTimeoutSeconds`: типовий timeout (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність timeout.
- Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
-## Custom providers і base URLs
+## Користувацькі provider і base URL
-OpenClaw використовує built-in model catalog. Додавайте custom providers через `models.providers` у config або `~/.openclaw/agents//agent/models.json`.
+OpenClaw використовує вбудований каталог моделей. Додавайте користувацькі provider через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`.
```json5
{
models: {
- mode: "merge", // merge (типово) | replace
+ mode: "merge", // merge (default) | replace
providers: {
"custom-proxy": {
baseUrl: "http://localhost:4000/v1",
@@ -2380,49 +2379,50 @@ OpenClaw використовує built-in model catalog. Додавайте cus
}
```
-- Використовуйте `authHeader: true` + `headers` для custom auth.
-- Перевизначайте корінь agent config через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias environment variable).
-- Пріоритет злиття для однакових provider IDs:
- - Непорожні значення `baseUrl` в agent `models.json` мають пріоритет.
- - Непорожні значення `apiKey` в agent мають пріоритет лише тоді, коли цим provider-ом не керує SecretRef у поточному контексті config/auth-profile.
- - Значення `apiKey` provider-а під керуванням SecretRef оновлюються з source markers (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження визначених секретів.
- - Значення header provider-а під керуванням SecretRef оновлюються з source markers (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs).
- - Порожні або відсутні значення `apiKey`/`baseUrl` в agent повертаються до `models.providers` у config.
- - Однакові значення `contextWindow`/`maxTokens` для model використовують вище значення між явним config і неявними значеннями catalog.
- - Для однакових model `contextTokens` зберігається явний runtime cap, якщо він присутній; використовуйте його, щоб обмежити фактичний context без зміни native model metadata.
- - Використовуйте `models.mode: "replace"`, коли хочете, щоб config повністю переписав `models.json`.
- - Marker persistence є source-authoritative: markers записуються з active source config snapshot (до resolution), а не з визначених runtime secret values.
+- Використовуйте `authHeader: true` + `headers` для потреб користувацької автентифікації.
+- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища).
+- Пріоритет злиття для відповідних id provider:
+ - Непорожні значення `baseUrl` з агентського `models.json` мають пріоритет.
+ - Непорожні значення `apiKey` з агента мають пріоритет лише тоді, коли цей provider не керується через SecretRef у поточному контексті конфігурації/auth-profile.
+ - Значення `apiKey` для provider, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів.
+ - Значення заголовків provider, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань).
+ - Порожні або відсутні значення `apiKey`/`baseUrl` агента використовують резервні значення з `models.providers` у конфігурації.
+ - Для відповідних моделей `contextWindow`/`maxTokens` використовується більше значення між явною конфігурацією та неявними значеннями каталогу.
+ - Для відповідних моделей `contextTokens` зберігається явне runtime-обмеження, якщо воно задано; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі.
+ - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`.
+ - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з визначених runtime-значень секретів.
-### Деталі полів provider
+### Відомості про поля provider
-- `models.mode`: поведінка provider catalog (`merge` або `replace`).
-- `models.providers`: мапа custom provider-ів за ключем provider id.
-- `models.providers.*.api`: request adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо).
-- `models.providers.*.apiKey`: credential провайдера (краще використовувати SecretRef/env substitution).
-- `models.providers.*.auth`: стратегія auth (`api-key`, `token`, `oauth`, `aws-sdk`).
-- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додає `options.num_ctx` у requests (типово: `true`).
-- `models.providers.*.authHeader`: примусово передавати credential у заголовку `Authorization`, коли це потрібно.
-- `models.providers.*.baseUrl`: base URL upstream API.
-- `models.providers.*.headers`: додаткові статичні заголовки для proxy/tenant routing.
-- `models.providers.*.request`: transport overrides для HTTP-запитів провайдера моделей.
- - `request.headers`: додаткові заголовки (зливаються з типовими заголовками провайдера). Значення приймають SecretRef.
- - `request.auth`: перевизначення auth strategy. Режими: `"provider-default"` (використовувати built-in auth провайдера), `"authorization-bearer"` (із `token`), `"header"` (із `headerName`, `value`, необов’язковим `prefix`).
- - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (із `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`.
+- `models.mode`: поведінка каталогу provider (`merge` або `replace`).
+- `models.providers`: мапа користувацьких provider, ключована за id provider.
+- `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо).
+- `models.providers.*.apiKey`: облікові дані provider (переважно використовуйте SecretRef/підстановку env).
+- `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 API upstream.
+- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant.
+- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider.
+ - `request.headers`: додаткові заголовки (зливаються з типовими значеннями provider). Значення приймають SecretRef.
+ - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію provider), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value` і необов’язковим `prefix`).
+ - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`.
- `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`.
-- `models.providers.*.models`: явні записи model catalog провайдера.
-- `models.providers.*.models.*.contextWindow`: метадані native model context window.
-- `models.providers.*.models.*.contextTokens`: необов’язковий runtime context cap. Використовуйте це, коли вам потрібен менший фактичний budget context, ніж native `contextWindow` моделі.
-- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (host не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час виконання. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI.
-- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint-ів, що підтримують лише рядки. Коли `true`, OpenClaw сплющує чисто текстові масиви `messages[].content` у звичайні рядки перед надсиланням request.
+ - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS розв’язується в приватні, CGNAT або подібні діапазони, через захист HTTP fetch provider від SSRF (opt-in оператора для довірених self-hosted OpenAI-compatible endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типове значення `false`.
+- `models.providers.*.models`: явні записи каталогу моделей provider.
+- `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.
+- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint, які підтримують лише рядки. Коли `true`, OpenClaw перед надсиланням запиту сплющує масиви `messages[].content`, що містять лише текст, у звичайні рядки.
- `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`: інтервал polling для оновлення discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: fallback context window для виявлених моделей.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: fallback max output tokens для виявлених моделей.
+- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр id provider для цільового виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей.
-### Приклади provider-ів
+### Приклади provider
@@ -2458,7 +2458,7 @@ OpenClaw використовує built-in model catalog. Додавайте cus
}
```
-Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI.
+Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI.
@@ -2475,7 +2475,7 @@ OpenClaw використовує built-in model catalog. Додавайте cus
}
```
-Встановіть `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`.
@@ -2492,11 +2492,11 @@ OpenClaw використовує built-in model catalog. Додавайте cus
}
```
-Встановіть `ZAI_API_KEY`. Приймаються alias-и `z.ai/*` і `z-ai/*`. Скорочення: `openclaw onboard --auth-choice zai-api-key`.
+Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні alias. Скорочення: `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 визначте custom provider із перевизначенням base URL.
+- Endpoint для кодування (типово): `https://api.z.ai/api/coding/paas/v4`
+- Для загального endpoint визначте користувацький provider з перевизначенням base URL.
@@ -2537,9 +2537,9 @@ OpenClaw використовує built-in model catalog. Додавайте cus
Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`.
-Нативні endpoint-и Moonshot оголошують сумісність використання streaming на спільному
-transport `openai-completions`, і OpenClaw визначає це за можливостями endpoint-а,
-а не лише за built-in provider id.
+Нативні endpoint-и Moonshot оголошують сумісність використання потокової передачі на спільному
+транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint,
+а не лише до вбудованого id provider.
@@ -2557,7 +2557,7 @@ transport `openai-completions`, і OpenClaw визначає це за можл
}
```
-Сумісний з Anthropic, built-in provider. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`.
+Сумісний з Anthropic, вбудований provider. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`.
@@ -2596,7 +2596,7 @@ transport `openai-completions`, і OpenClaw визначає це за можл
}
```
-Base URL має не містити `/v1` (client Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`.
+Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`.
@@ -2636,11 +2636,11 @@ Base URL має не містити `/v1` (client Anthropic додає його
}
```
-Встановіть `MINIMAX_API_KEY`. Скорочення:
+Установіть `MINIMAX_API_KEY`. Скорочення:
`openclaw onboard --auth-choice minimax-global-api` або
`openclaw onboard --auth-choice minimax-cn-api`.
Каталог моделей типово містить лише M2.7.
-На Anthropic-compatible streaming path OpenClaw типово вимикає thinking MiniMax,
+На шляху потокової передачі, сумісному з Anthropic, OpenClaw типово вимикає thinking MiniMax,
якщо ви явно не задасте `thinking` самостійно. `/fast on` або
`params.fastMode: true` переписує `MiniMax-M2.7` на
`MiniMax-M2.7-highspeed`.
@@ -2649,7 +2649,7 @@ Base URL має не містити `/v1` (client Anthropic додає його
-Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте hosted models у merged стані для fallback.
+Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted моделі об’єднаними для резервного використання.
@@ -2670,7 +2670,7 @@ Base URL має не містити `/v1` (client Anthropic додає його
},
entries: {
"image-lab": {
- apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // або plaintext string
+ apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
},
peekaboo: { enabled: true },
@@ -2680,5 +2680,1029 @@ Base URL має не містити `/v1` (client Anthropic додає його
}
```
-- `allowBundled`: необов’язковий allowlist лише для bundled Skills (managed/workspace skills не зачіпаються).
-- `load.extraDirs`: додаткові сп
\ No newline at end of file
+- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills не зачіпаються).
+- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет).
+- `install.preferBrew`: коли true, віддає перевагу інсталяторам Homebrew, якщо `brew`
+ доступний, перш ніж переходити до інших типів інсталяторів.
+- `install.nodeManager`: бажаний менеджер інсталяції node для специфікацій `metadata.openclaw.install`
+ (`npm` | `pnpm` | `yarn` | `bun`).
+- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений.
+- `entries..apiKey`: зручне поле для Skills, які оголошують основну env-змінну (plaintext-рядок або об’єкт SecretRef).
+
+---
+
+## Plugins
+
+```json5
+{
+ plugins: {
+ enabled: true,
+ allow: ["voice-call"],
+ deny: [],
+ load: {
+ paths: ["~/Projects/oss/voice-call-extension"],
+ },
+ entries: {
+ "voice-call": {
+ enabled: true,
+ hooks: {
+ allowPromptInjection: false,
+ },
+ config: { provider: "twilio" },
+ },
+ },
+ },
+}
+```
+
+- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`.
+- Виявлення приймає нативні plugins OpenClaw, а також сумісні набори Codex і Claude, включно з наборами Claude зі стандартним макетом без manifest.
+- **Зміни конфігурації потребують перезапуску gateway.**
+- `allow`: необов’язковий allowlist (завантажуються лише перелічені plugins). `deny` має пріоритет.
+- `plugins.entries..apiKey`: зручне поле API key на рівні plugin (коли plugin це підтримує).
+- `plugins.entries..env`: мапа змінних середовища в області plugin.
+- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, зі застарілого `before_agent_start`, при цьому зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних plugin hooks і підтримуваних каталогів hooks, наданих bundle.
+- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent.
+- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель.
+- `plugins.entries..config`: об’єкт конфігурації, визначений plugin (перевіряється за схемою нативного plugin OpenClaw, якщо вона доступна).
+- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl.
+ - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або змінної середовища `FIRECRAWL_API_KEY`.
+ - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`).
+ - `onlyMainContent`: витягувати зі сторінок лише основний вміст (типово: `true`).
+ - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні).
+ - `timeoutSeconds`: timeout запиту scraping у секундах (типово: `60`).
+- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok).
+ - `enabled`: увімкнути провайдера X Search.
+ - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`).
+- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming (експериментально). Фази та пороги див. у [Dreaming](/uk/concepts/dreaming).
+ - `enabled`: головний перемикач dreaming (типово `false`).
+ - `frequency`: cron-каденс для кожного повного проходу dreaming (`"0 3 * * *"` типово).
+ - політика фаз і пороги — це деталі реалізації (не ключі конфігурації, орієнтовані на користувача).
+- Повна конфігурація memory знаходиться в [Memory configuration reference](/uk/reference/memory-config):
+ - `agents.defaults.memorySearch.*`
+ - `memory.backend`
+ - `memory.citations`
+ - `memory.qmd.*`
+ - `plugins.entries.memory-core.config.dreaming`
+- Увімкнені Claude bundle plugins також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі patch-і конфігурації OpenClaw.
+- `plugins.slots.memory`: вибрати id активного plugin пам’яті або `"none"`, щоб вимкнути plugins пам’яті.
+- `plugins.slots.contextEngine`: вибрати id активного plugin рушія контексту; типово `"legacy"`, якщо ви не встановите і не виберете інший рушій.
+- `plugins.installs`: метадані встановлення, якими керує CLI і які використовуються `openclaw plugins update`.
+ - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
+ - Сприймайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI, а не ручним редагуванням.
+
+Див. [Plugins](/uk/tools/plugin).
+
+---
+
+## Browser
+
+```json5
+{
+ browser: {
+ enabled: true,
+ evaluateEnabled: true,
+ defaultProfile: "user",
+ ssrfPolicy: {
+ dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
+ // allowPrivateNetwork: true, // legacy alias
+ // hostnameAllowlist: ["*.example.com", "example.com"],
+ // allowedHostnames: ["localhost"],
+ },
+ profiles: {
+ openclaw: { cdpPort: 18800, color: "#FF4500" },
+ work: { cdpPort: 18801, color: "#0066CC" },
+ user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
+ brave: {
+ driver: "existing-session",
+ attachOnly: true,
+ userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+ color: "#FB542B",
+ },
+ remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
+ },
+ color: "#FF4500",
+ // headless: false,
+ // noSandbox: false,
+ // extraArgs: [],
+ // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+ // attachOnly: false,
+ },
+}
+```
+
+- `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`.
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` типово має значення `true`, якщо не задано (модель довіреної мережі).
+- Установіть `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` для суворої навігації браузера лише по публічній мережі.
+- У суворому режимі до endpoint-ів віддалених CDP-профілів (`profiles.*.cdpUrl`) застосовується те саме блокування приватної мережі під час перевірок досяжності/виявлення.
+- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий alias.
+- У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
+- Віддалені профілі підтримують лише attach-only (start/stop/reset вимкнено).
+- `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`.
+ Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S),
+ коли ваш provider надає прямий DevTools WebSocket URL.
+- Профілі `existing-session` працюють лише на хості й використовують Chrome MCP замість CDP.
+- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний
+ профіль браузера на базі Chromium, наприклад Brave або Edge.
+- Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP:
+ дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks
+ для завантаження одного файлу, без перевизначення timeout для діалогів, без `wait --load networkidle`,
+ а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій.
+- Керовані локальні профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно
+ задавайте `cdpUrl` лише для віддаленого CDP.
+- Порядок автоматичного виявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
+- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`).
+- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад
+ `--disable-gpu`, розмір вікна або прапорці налагодження).
+
+---
+
+## UI
+
+```json5
+{
+ ui: {
+ seamColor: "#FF4500",
+ assistant: {
+ name: "OpenClaw",
+ avatar: "CB", // emoji, short text, image URL, or data URI
+ },
+ },
+}
+```
+
+- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки режиму Talk тощо).
+- `assistant`: перевизначення identity для Control UI. Використовує резервне значення з identity активного агента.
+
+---
+
+## Gateway
+
+```json5
+{
+ gateway: {
+ mode: "local", // local | remote
+ port: 18789,
+ bind: "loopback",
+ auth: {
+ mode: "token", // none | token | password | trusted-proxy
+ token: "your-token",
+ // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
+ // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
+ allowTailscale: true,
+ rateLimit: {
+ maxAttempts: 10,
+ windowMs: 60000,
+ lockoutMs: 300000,
+ exemptLoopback: true,
+ },
+ },
+ tailscale: {
+ mode: "off", // off | serve | funnel
+ resetOnExit: false,
+ },
+ controlUi: {
+ enabled: true,
+ basePath: "/openclaw",
+ // root: "dist/control-ui",
+ // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
+ // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
+ // allowInsecureAuth: false,
+ // dangerouslyDisableDeviceAuth: false,
+ },
+ remote: {
+ url: "ws://gateway.tailnet:18789",
+ transport: "ssh", // ssh | direct
+ token: "your-token",
+ // password: "your-password",
+ },
+ trustedProxies: ["10.0.0.1"],
+ // Optional. Default false.
+ allowRealIpFallback: false,
+ tools: {
+ // Additional /tools/invoke HTTP denies
+ deny: ["browser"],
+ // Remove tools from the default HTTP deny list
+ allow: ["gateway"],
+ },
+ push: {
+ apns: {
+ relay: {
+ baseUrl: "https://relay.example.com",
+ timeoutMs: 10000,
+ },
+ },
+ },
+ },
+}
+```
+
+
+
+- `mode`: `local` (запускати gateway) або `remote` (підключатися до віддаленого gateway). Gateway відмовляється запускатися, якщо не встановлено `local`.
+- `port`: один мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
+- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `custom`.
+- **Застарілі alias bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не alias хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
+- **Примітка для Docker**: типове прив’язування `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік приходить на `eth0`, тож gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах.
+- **Auth**: типово обов’язкова. Прив’язування не до loopback потребують auth gateway. На практиці це означає спільний token/password або reverse proxy з awareness про identity з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token.
+- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Запуск і потоки встановлення/відновлення service завершуються помилкою, коли налаштовано обидва поля, а режим не задано.
+- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій loopback; цей варіант навмисно не пропонується в prompt-ах onboarding.
+- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з awareness про identity і довіряє заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на loopback того самого хоста не задовольняють auth trusted-proxy.
+- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint-и **не** використовують цю auth за заголовками Tailscale; вони дотримуються звичайного HTTP-режиму auth gateway. Цей безтокенний потік припускає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`.
+- `gateway.auth.rateLimit`: необов’язковий лімітер невдалих спроб auth. Застосовується для кожної IP-адреси клієнта і для кожної області auth окремо (спільний секрет і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`.
+ - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для одного й того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати на лімітер уже на другому запиті, а не пройти обидві як звичайні невідповідності.
+ - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли свідомо хочете, щоб і localhost-трафік теж потрапляв під rate-limit (для тестових конфігурацій або суворих розгортань proxy).
+- Спроби browser-origin WS auth завжди throttled без винятку для loopback (захист у глибину від browser-based brute force на localhost).
+- На loopback такі блокування для browser-origin ізолюються за нормалізованим значенням `Origin`,
+ тож повторні невдалі спроби з одного localhost origin не блокують автоматично
+ інше origin.
+- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, потребує auth).
+- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти не з loopback origin.
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення origin за заголовком Host для розгортань, які свідомо покладаються на політику origin на основі заголовка Host.
+- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`.
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне клієнтське перевизначення break-glass, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типово plaintext дозволений лише для loopback.
+- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway.
+- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після того, як публікують у gateway реєстрації на основі relay. Цей URL має збігатися з URL relay, зібраним у збірці iOS.
+- `gateway.push.apns.relay.timeoutMs`: timeout надсилання gateway-to-relay у мілісекундах. Типове значення: `10000`.
+- Реєстрації на основі relay делегуються конкретній identity gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю identity до реєстрації relay і пересилає в gateway grant надсилання з областю реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
+- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay.
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний механізм лише для розробки, що дозволяє loopback HTTP URL-и relay. У production URL-и relay мають залишатися на HTTPS.
+- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типове значення: `5`.
+- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`.
+- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис за ковзну годину. Типове значення: `10`.
+- `channels..healthMonitor.enabled`: opt-out для окремого каналу від перезапусків монітора стану при збереженні глобального монітора увімкненим.
+- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в каналах із кількома обліковими записами. Якщо встановлено, має пріоритет над перевизначенням на рівні каналу.
+- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервне значення лише тоді, коли `gateway.auth.*` не задано.
+- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не визначено, визначення завершується fail-closed (без маскування резервним значенням remote).
+- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають переслані клієнтські заголовки. Додавайте лише proxy, які ви контролюєте. Записи loopback усе ще валідні для конфігурацій з proxy/local-detection на тому самому хості (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
+- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типове значення `false` для fail-closed поведінки.
+- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny).
+- `gateway.tools.allow`: прибирає назви інструментів зі стандартного HTTP deny list.
+
+
+
+### OpenAI-compatible endpoint-и
+
+- Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
+- Responses API: `gateway.http.endpoints.responses.enabled`.
+- Захист URL-input для Responses:
+ - `gateway.http.endpoints.responses.maxUrlParts`
+ - `gateway.http.endpoints.responses.files.urlAllowlist`
+ - `gateway.http.endpoints.responses.images.urlAllowlist`
+ Порожні allowlist-и трактуються як невстановлені; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false`
+ і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL.
+- Необов’язковий заголовок захисту відповіді:
+ - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
+
+### Ізоляція кількох інстансів
+
+Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану:
+
+```bash
+OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
+OPENCLAW_STATE_DIR=~/.openclaw-a \
+openclaw gateway --port 19001
+```
+
+Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`).
+
+Див. [Multiple Gateways](/uk/gateway/multiple-gateways).
+
+### `gateway.tls`
+
+```json5
+{
+ gateway: {
+ tls: {
+ enabled: false,
+ autoGenerate: false,
+ certPath: "/etc/openclaw/tls/server.crt",
+ keyPath: "/etc/openclaw/tls/server.key",
+ caPath: "/etc/openclaw/tls/ca-bundle.crt",
+ },
+ },
+}
+```
+
+- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`).
+- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для local/dev.
+- `certPath`: шлях у файловій системі до файлу TLS certificate.
+- `keyPath`: шлях у файловій системі до файлу TLS private key; тримайте його з обмеженим доступом.
+- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюжків довіри.
+
+### `gateway.reload`
+
+```json5
+{
+ gateway: {
+ reload: {
+ mode: "hybrid", // off | restart | hot | hybrid
+ debounceMs: 500,
+ deferralTimeoutMs: 300000,
+ },
+ },
+}
+```
+
+- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime.
+ - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску.
+ - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації.
+ - `"hot"`: застосовувати зміни в процесі без перезапуску.
+ - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно, переходити до перезапуску.
+- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
+- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типове значення: `300000` = 5 хвилин).
+
+---
+
+## Hooks
+
+```json5
+{
+ hooks: {
+ enabled: true,
+ token: "shared-secret",
+ path: "/hooks",
+ maxBodyBytes: 262144,
+ defaultSessionKey: "hook:ingress",
+ allowRequestSessionKey: false,
+ allowedSessionKeyPrefixes: ["hook:"],
+ allowedAgentIds: ["hooks", "main"],
+ presets: ["gmail"],
+ transformsDir: "~/.openclaw/hooks/transforms",
+ mappings: [
+ {
+ match: { path: "gmail" },
+ action: "agent",
+ agentId: "hooks",
+ wakeMode: "now",
+ name: "Gmail",
+ sessionKey: "hook:gmail:{{messages[0].id}}",
+ messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
+ deliver: true,
+ channel: "last",
+ model: "openai/gpt-5.4-mini",
+ },
+ ],
+ },
+}
+```
+
+Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
+Токени hook у query string відхиляються.
+
+Примітки щодо валідації та безпеки:
+
+- `hooks.enabled=true` вимагає непорожнього `hooks.token`.
+- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється.
+- `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`.
+- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`).
+
+**Endpoint-и:**
+
+- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
+- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
+ - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`).
+- `POST /hooks/` → визначається через `hooks.mappings`
+
+
+
+- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`).
+- `match.source` відповідає полю payload для узагальнених шляхів.
+- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload.
+- `transform` може вказувати на модуль JS/TS, що повертає дію hook.
+ - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються).
+- `agentId` маршрутизує до конкретного агента; невідомі id використовують резервний типовий агент.
+- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущене значення = дозволити всі, `[]` = заборонити всі).
+- `defaultSessionKey`: необов’язковий фіксований ключ сеансу для запусків hook-агента без явного `sessionKey`.
+- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` задавати `sessionKey` (типово: `false`).
+- `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`.
+- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`.
+- `model` перевизначає LLM для цього запуску hook (має бути дозволений, якщо налаштовано каталог моделей).
+
+
+
+### Інтеграція Gmail
+
+```json5
+{
+ hooks: {
+ gmail: {
+ account: "openclaw@gmail.com",
+ topic: "projects//topics/gog-gmail-watch",
+ subscription: "gog-gmail-watch-push",
+ pushToken: "shared-push-token",
+ hookUrl: "http://127.0.0.1:18789/hooks/gmail",
+ includeBody: true,
+ maxBytes: 20000,
+ renewEveryMinutes: 720,
+ serve: { bind: "127.0.0.1", port: 8788, path: "/" },
+ tailscale: { mode: "funnel", path: "/gmail-pubsub" },
+ model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+ thinking: "off",
+ },
+ },
+}
+```
+
+- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути.
+- Не запускайте окремий `gog gmail watch serve` паралельно з Gateway.
+
+---
+
+## Canvas host
+
+```json5
+{
+ canvasHost: {
+ root: "~/.openclaw/workspace/canvas",
+ liveReload: true,
+ // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
+ },
+}
+```
+
+- Обслуговує HTML/CSS/JS і A2UI, які агент може редагувати, через HTTP на порту Gateway:
+ - `http://:/__openclaw__/canvas/`
+ - `http://:/__openclaw__/a2ui/`
+- Лише локально: зберігайте `gateway.bind: "loopback"` (типово).
+- Для bind не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway.
+- Node WebViews зазвичай не надсилають заголовки auth; після pairing і підключення node Gateway рекламує URL-адреси можливостей з областю node для доступу до canvas/A2UI.
+- URL-адреси можливостей прив’язані до активного WS-сеансу node і швидко закінчуються. Резервний варіант на основі IP не використовується.
+- Вбудовує клієнт live reload в HTML, що обслуговується.
+- Автоматично створює початковий `index.html`, якщо каталог порожній.
+- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`.
+- Зміни потребують перезапуску gateway.
+- Вимкніть live reload для великих каталогів або при помилках `EMFILE`.
+
+---
+
+## Discovery
+
+### mDNS (Bonjour)
+
+```json5
+{
+ discovery: {
+ mdns: {
+ mode: "minimal", // minimal | full | off
+ },
+ },
+}
+```
+
+- `minimal` (типово): не включає `cliPath` + `sshPort` у TXT records.
+- `full`: включає `cliPath` + `sshPort`.
+- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`.
+
+### Wide-area (DNS-SD)
+
+```json5
+{
+ discovery: {
+ wideArea: { enabled: true },
+ },
+}
+```
+
+Записує unicast-зону DNS-SD у `~/.openclaw/dns/`. Для discovery між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS.
+
+Налаштування: `openclaw dns setup --apply`.
+
+---
+
+## Environment
+
+### `env` (inline env vars)
+
+```json5
+{
+ env: {
+ OPENROUTER_API_KEY: "sk-or-...",
+ vars: {
+ GROQ_API_KEY: "gsk-...",
+ },
+ shellEnv: {
+ enabled: true,
+ timeoutMs: 15000,
+ },
+ },
+}
+```
+
+- Inline env vars застосовуються лише тоді, коли в env процесу бракує ключа.
+- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні).
+- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell.
+- Повний порядок пріоритетів див. у [Environment](/uk/help/environment).
+
+### Підстановка env var
+
+Посилайтеся на env vars у будь-якому рядку конфігурації через `${VAR_NAME}`:
+
+```json5
+{
+ gateway: {
+ auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
+ },
+}
+```
+
+- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
+- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації.
+- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`.
+- Працює з `$include`.
+
+---
+
+## Secrets
+
+Посилання на secrets є адитивними: plaintext-значення також продовжують працювати.
+
+### `SecretRef`
+
+Використовуйте один формат об’єкта:
+
+```json5
+{ source: "env" | "file" | "exec", provider: "default", id: "..." }
+```
+
+Валідація:
+
+- шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$`
+- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
+- `source: "file"` `id`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
+- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
+- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється)
+
+### Підтримувана поверхня облікових даних
+
+- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface)
+- `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`.
+- Посилання в `auth-profiles.json` включено в покриття визначення під час runtime та аудиту.
+
+### Конфігурація providers secret
+
+```json5
+{
+ secrets: {
+ providers: {
+ default: { source: "env" }, // optional explicit env provider
+ filemain: {
+ source: "file",
+ path: "~/.openclaw/secrets.json",
+ mode: "json",
+ timeoutMs: 5000,
+ },
+ vault: {
+ source: "exec",
+ command: "/usr/local/bin/openclaw-vault-resolver",
+ passEnv: ["PATH", "VAULT_ADDR"],
+ },
+ },
+ defaults: {
+ env: "default",
+ file: "filemain",
+ exec: "vault",
+ },
+ },
+}
+```
+
+Примітки:
+
+- provider `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`).
+- provider `exec` вимагає абсолютний шлях `command` і використовує protocol payloads через stdin/stdout.
+- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою шляху визначеної цілі.
+- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до шляху визначеної цілі.
+- Дочірнє env для `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`.
+- Посилання на secrets визначаються під час активації в знімок у пам’яті, а потім шляхи запитів читають лише цей знімок.
+- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях спричиняють збій запуску/reload, тоді як неактивні поверхні пропускаються з діагностикою.
+
+---
+
+## Сховище auth
+
+```json5
+{
+ auth: {
+ profiles: {
+ "anthropic:default": { provider: "anthropic", mode: "api_key" },
+ "anthropic:work": { provider: "anthropic", mode: "api_key" },
+ "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
+ },
+ order: {
+ anthropic: ["anthropic:default", "anthropic:work"],
+ "openai-codex": ["openai-codex:personal"],
+ },
+ },
+}
+```
+
+- Профілі для окремого агента зберігаються в `/auth-profiles.json`.
+- `auth-profiles.json` підтримує посилання на рівні значення (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних.
+- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef.
+- Статичні runtime-облікові дані надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються, коли їх виявлено.
+- Застарілі імпорти OAuth беруться з `~/.openclaw/credentials/oauth.json`.
+- Див. [OAuth](/uk/concepts/oauth).
+- Поведінка runtime для secrets і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets).
+
+### `auth.cooldowns`
+
+```json5
+{
+ auth: {
+ cooldowns: {
+ billingBackoffHours: 5,
+ billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
+ billingMaxHours: 24,
+ authPermanentBackoffMinutes: 10,
+ authPermanentMaxMinutes: 60,
+ failureWindowHours: 24,
+ overloadedProfileRotations: 1,
+ overloadedBackoffMs: 0,
+ rateLimitedProfileRotations: 1,
+ },
+ },
+}
+```
+
+- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні помилки billing/нестачі кредитів (типово: `5`). Явний текст про billing усе ще може
+ потрапляти сюди навіть за відповідей `401`/`403`, але provider-specific
+ засоби зіставлення тексту залишаються в межах provider, якому вони належать (наприклад OpenRouter
+ `Key limit exceeded`). Придатні до повторної спроби HTTP `402` повідомлення про usage-window або
+ ліміти витрат organization/workspace натомість залишаються в шляху `rate_limit`.
+- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих provider.
+- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (типово: `24`).
+- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`).
+- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`).
+- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`).
+- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого provider для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Форми provider-busy, такі як `ModelNotReadyException`, потрапляють сюди.
+- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого provider/profile (типово: `0`).
+- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого provider для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей кошик rate-limit включає provider-shaped текст на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
+
+---
+
+## Logging
+
+```json5
+{
+ logging: {
+ level: "info",
+ file: "/tmp/openclaw/openclaw.log",
+ consoleLevel: "info",
+ consoleStyle: "pretty", // pretty | compact | json
+ redactSensitive: "tools", // off | tools
+ redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
+ },
+}
+```
+
+- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
+- Установіть `logging.file`, щоб мати стабільний шлях.
+- `consoleLevel` підвищується до `debug`, коли задано `--verbose`.
+- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 МБ). Для production-розгортань використовуйте зовнішню ротацію журналів.
+
+---
+
+## Diagnostics
+
+```json5
+{
+ diagnostics: {
+ enabled: true,
+ flags: ["telegram.*"],
+ stuckSessionWarnMs: 30000,
+
+ otel: {
+ enabled: false,
+ endpoint: "https://otel-collector.example.com:4318",
+ protocol: "http/protobuf", // http/protobuf | grpc
+ headers: { "x-tenant-id": "my-org" },
+ serviceName: "openclaw-gateway",
+ traces: true,
+ metrics: true,
+ logs: false,
+ sampleRate: 1.0,
+ flushIntervalMs: 5000,
+ },
+
+ cacheTrace: {
+ enabled: false,
+ filePath: "~/.openclaw/logs/cache-trace.jsonl",
+ includeMessages: true,
+ includePrompt: true,
+ includeSystem: true,
+ },
+ },
+}
+```
+
+- `enabled`: головний перемикач для виводу інструментування (типово: `true`).
+- `flags`: масив рядків прапорців, які вмикають цільовий вивід журналу (підтримує wildcard-и, як-от `"telegram.*"` або `"*"`).
+- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про застряглий сеанс, поки сеанс залишається в стані обробки.
+- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`).
+- `otel.endpoint`: URL колектора для експорту OTel.
+- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`.
+- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, які надсилаються із запитами експорту OTel.
+- `otel.serviceName`: назва сервісу для атрибутів ресурсу.
+- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs.
+- `otel.sampleRate`: коефіцієнт семплювання trace `0`–`1`.
+- `otel.flushIntervalMs`: інтервал періодичного скидання telemetry у мс.
+- `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (типово: `false`).
+- `cacheTrace.filePath`: вихідний шлях для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`).
+
+---
+
+## Update
+
+```json5
+{
+ update: {
+ channel: "stable", // stable | beta | dev
+ checkOnStart: true,
+
+ auto: {
+ enabled: false,
+ stableDelayHours: 6,
+ stableJitterHours: 12,
+ betaCheckIntervalHours: 1,
+ },
+ },
+}
+```
+
+- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`.
+- `checkOnStart`: перевіряти наявність оновлень npm під час запуску gateway (типово: `true`).
+- `auto.enabled`: увімкнути фонове автооновлення для package-встановлень (типово: `false`).
+- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для stable-каналу (типово: `6`; максимум: `168`).
+- `auto.stableJitterHours`: додаткове вікно розподілу розгортання для stable-каналу в годинах (типово: `12`; максимум: `168`).
+- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`).
+
+---
+
+## ACP
+
+```json5
+{
+ acp: {
+ enabled: false,
+ dispatch: { enabled: true },
+ backend: "acpx",
+ defaultAgent: "main",
+ allowedAgents: ["main", "ops"],
+ maxConcurrentSessions: 10,
+
+ stream: {
+ coalesceIdleMs: 50,
+ maxChunkChars: 1000,
+ repeatSuppression: true,
+ deliveryMode: "live", // live | final_only
+ hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
+ maxOutputChars: 50000,
+ maxSessionUpdateChars: 500,
+ },
+
+ runtime: {
+ ttlMinutes: 30,
+ },
+ },
+}
+```
+
+- `enabled`: глобальний feature gate ACP (типово: `false`).
+- `dispatch.enabled`: незалежний перемикач для dispatch ходів ACP-сеансів (типово: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося.
+- `backend`: id типового ACP runtime backend (має відповідати зареєстрованому ACP runtime plugin).
+- `defaultAgent`: резервний id цільового агента ACP, коли spawn-и не вказують явну ціль.
+- `allowedAgents`: allowlist id агентів, дозволених для ACP runtime-сеансів; порожнє значення означає відсутність додаткового обмеження.
+- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сеансів.
+- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту.
+- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блока.
+- `stream.repeatSuppression`: пригнічувати повторювані рядки status/tool на хід (типово: `true`).
+- `stream.deliveryMode`: `"live"` передає потоково інкрементально; `"final_only"` буферизує до термінальних подій ходу.
+- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих tool-подій (типово: `"paragraph"`).
+- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за один хід ACP.
+- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків status/update ACP.
+- `stream.tagVisibility`: запис, що зіставляє назви тегів із булевими перевизначеннями видимості для потокових подій.
+- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів ACP-сеансів перед можливим очищенням.
+- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP.
+
+---
+
+## CLI
+
+```json5
+{
+ cli: {
+ banner: {
+ taglineMode: "off", // random | default | off
+ },
+ },
+}
+```
+
+- `cli.banner.taglineMode` керує стилем слогана в банері:
+ - `"random"` (типово): ротаційні кумедні/сезонні слогани.
+ - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`).
+ - `"off"`: без тексту слогана (назва банера/версія все одно показуються).
+- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`.
+
+---
+
+## Wizard
+
+Метадані, які записують керовані CLI-потоки налаштування (`onboard`, `configure`, `doctor`):
+
+```json5
+{
+ wizard: {
+ lastRunAt: "2026-01-01T00:00:00.000Z",
+ lastRunVersion: "2026.1.4",
+ lastRunCommit: "abc1234",
+ lastRunCommand: "configure",
+ lastRunMode: "local",
+ },
+}
+```
+
+---
+
+## Identity
+
+Див. поля identity в `agents.list` у розділі [Agent defaults](#agent-defaults).
+
+---
+
+## Bridge (застаріле, видалене)
+
+Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
+
+
+
+```json
+{
+ "bridge": {
+ "enabled": true,
+ "port": 18790,
+ "bind": "tailnet",
+ "tls": {
+ "enabled": true,
+ "autoGenerate": true
+ }
+ }
+}
+```
+
+
+
+---
+
+## Cron
+
+```json5
+{
+ cron: {
+ enabled: true,
+ maxConcurrentRuns: 2,
+ webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
+ webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
+ sessionRetention: "24h", // duration string or false
+ runLog: {
+ maxBytes: "2mb", // default 2_000_000 bytes
+ keepLines: 2000, // default 2000
+ },
+ },
+}
+```
+
+- `sessionRetention`: скільки часу зберігати завершені ізольовані сеанси запусків cron до їх очищення з `sessions.json`. Також керує очищенням архівованих видалених cron transcript. Типове значення: `24h`; установіть `false`, щоб вимкнути.
+- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів.
+- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запуску. Типове значення: `2000`.
+- `webhookToken`: bearer token, що використовується для POST-доставки cron webhook (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається.
+- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`.
+
+### `cron.retry`
+
+```json5
+{
+ cron: {
+ retry: {
+ maxAttempts: 3,
+ backoffMs: [30000, 60000, 300000],
+ retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
+ },
+ },
+}
+```
+
+- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`).
+- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів).
+- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Якщо не вказано, повторюються всі тимчасові типи.
+
+Застосовується лише до одноразових cron jobs. Для повторюваних завдань використовується окрема логіка обробки помилок.
+
+### `cron.failureAlert`
+
+```json5
+{
+ cron: {
+ failureAlert: {
+ enabled: false,
+ after: 3,
+ cooldownMs: 3600000,
+ mode: "announce",
+ accountId: "main",
+ },
+ },
+}
+```
+
+- `enabled`: увімкнути сповіщення про помилки для cron jobs (типово: `false`).
+- `after`: кількість послідовних помилок, після якої спрацьовує сповіщення (додатне ціле число, мінімум: `1`).
+- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число).
+- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований webhook.
+- `accountId`: необов’язковий id облікового запису або каналу для визначення області доставки сповіщення.
+
+### `cron.failureDestination`
+
+```json5
+{
+ cron: {
+ failureDestination: {
+ mode: "announce",
+ channel: "last",
+ to: "channel:C1234567890",
+ accountId: "main",
+ },
+ },
+}
+```
+
+- Типове місце призначення для сповіщень про помилки cron у всіх завданнях.
+- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль.
+- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки.
+- `to`: явна announce-ціль або URL webhook. Обов’язкове для режиму webhook.
+- `accountId`: необов’язкове перевизначення облікового запису для доставки.
+- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення.
+- Коли не задано ні глобальне, ні per-job місце призначення помилки, завдання, які вже доставляють через `announce`, у разі помилки використовують як резервний варіант цю основну announce-ціль.
+- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`.
+
+Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks).
+
+---
+
+## Змінні шаблону моделі медіа
+
+Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`:
+
+| Змінна | Опис |
+| ----------------- | ----------------------------------------------- |
+| `{{Body}}` | Повний текст вхідного повідомлення |
+| `{{RawBody}}` | Сирий текст повідомлення (без обгорток історії/відправника) |
+| `{{BodyStripped}}`| Текст повідомлення з прибраними згадками групи |
+| `{{From}}` | Ідентифікатор відправника |
+| `{{To}}` | Ідентифікатор отримувача |
+| `{{MessageSid}}` | ID повідомлення каналу |
+| `{{SessionId}}` | UUID поточного сеансу |
+| `{{IsNewSession}}`| `"true"`, коли створено новий сеанс |
+| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
+| `{{MediaPath}}` | Локальний шлях до медіа |
+| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
+| `{{Transcript}}` | Аудіотранскрипт |
+| `{{Prompt}}` | Визначений prompt для медіа для записів CLI |
+| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI |
+| `{{ChatType}}` | `"direct"` або `"group"` |
+| `{{GroupSubject}}`| Назва групи (best effort) |
+| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) |
+| `{{SenderName}}` | Відображуване ім’я відправника (best effort) |
+| `{{SenderE164}}` | Номер телефону відправника (best effort) |
+| `{{Provider}}` | Підказка provider (`whatsapp`, `telegram`, `discord` тощо) |
+
+---
+
+## Include-и конфігурації (`$include`)
+
+Розбивайте конфігурацію на кілька файлів:
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+ gateway: { port: 18789 },
+ agents: { $include: "./agents.json5" },
+ broadcast: {
+ $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
+ },
+}
+```
+
+**Поведінка злиття:**
+
+- Один файл: замінює об’єкт-контейнер.
+- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні).
+- Сусідні ключі: зливаються після include-ів (перевизначають включені значення).
+- Вкладені include-и: до 10 рівнів глибини.
+- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після визначення вони все одно залишаються в межах цієї межі.
+- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних include-ів.
+
+---
+
+_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_