From c50e47614aff9b11b4a06d512cc6345495253b4f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 05:50:37 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/configuration-reference.md | 2252 ++++++++++++++------ 1 file changed, 1638 insertions(+), 614 deletions(-) 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)_