From 8d22ae27da0a44c41e86c36852dbb7a20d5e9697 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 12:44:34 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/configuration-reference.md | 1552 ++++++++++---------- docs/uk/reference/rich-output-protocol.md | 60 + 2 files changed, 838 insertions(+), 774 deletions(-) create mode 100644 docs/uk/reference/rich-output-protocol.md diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 525df6008..6dc45b77b 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -5,66 +5,66 @@ read_when: summary: Довідник конфігурації шлюзу для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник конфігурації x-i18n: - generated_at: "2026-04-10T23:44:31Z" + generated_at: "2026-04-11T12:34:18Z" model: gpt-5.4 provider: openai - source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 + source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c source_path: gateway/configuration-reference.md workflow: 15 --- # Довідник конфігурації -Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду за завданнями див. [Конфігурація](/uk/gateway/configuration). +Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одну сторінку кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну схему JSON, що використовується для валідації та Control UI, з об’єднаними метаданими вбудованих/плагінів/каналів, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з областю шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базової лінії документації конфігурації щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми з обмеженням за шляхом для інструментів деталізації +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації щодо поточної поверхні схеми Окремі поглиблені довідники: -- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Команди зі слешем](/uk/tools/slash-commands) для поточного каталогу вбудованих + комплектних команд -- сторінки власників каналів/плагінів для поверхонь команд, специфічних для каналу +- [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) для поточного каталогу вбудованих + bundled команд +- сторінки відповідного каналу/плагіну для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. --- ## Канали -Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо тільки не вказано `enabled: false`). +Кожен канал запускається автоматично, коли його розділ конфігурації існує (якщо не вказано `enabled: false`). ### Доступ до особистих повідомлень і груп -Усі канали підтримують політики для особистих повідомлень і політики для груп: +Усі канали підтримують політики особистих повідомлень і політики груп: -| Політика для особистих повідомлень | Поведінка | -| ------------------- | --------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має підтвердити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів сполучених) | +| Політика DM | Поведінка | +| ------------------- | -------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів після сполучення) | | `open` | Дозволити всі вхідні особисті повідомлення (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні особисті повідомлення | +| `disabled` | Ігнорувати всі вхідні особисті повідомлення | -| Політика для груп | Поведінка | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених для груп (обмеження за згадками все одно застосовується) | -| `disabled` | Заблокувати всі повідомлення груп/кімнат | +| Політика груп | Поведінка | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволів | +| `open` | Обійти списки дозволів груп (контроль за згадуванням усе ще застосовується) | +| `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. -Коди сполучення спливають через 1 годину. Очікувані запити на сполучення для особистих повідомлень обмежені **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (закрито за замовчуванням) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` постачальника не встановлено. +Коди сполучення спливають через 1 годину. Очікувальні запити на сполучення DM обмежені **3 на канал**. +Якщо блок постачальника повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. ### Перевизначення моделі для каналів -Використовуйте `channels.modelByChannel`, щоб закріпити певні ідентифікатори каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, установленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ідентифікатори каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, встановленого через `/model`). ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### Значення каналів за замовчуванням і heartbeat +### Типові значення каналу та heartbeat -Використовуйте `channels.defaults` для спільної поведінки політики груп і heartbeat між провайдерами: +Використовуйте `channels.defaults` для спільної поведінки політики груп і heartbeat між постачальниками: ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна політика для груп, коли `groupPolicy` на рівні провайдера не встановлено. -- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/ланцюжків/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати здорові стани каналів у вивід heartbeat. -- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові стани у вивід heartbeat. +- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні постачальника не встановлено. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь цитований/гілковий/історичний контекст), `allowlist` (включати контекст лише від відправників зі списку дозволів), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення на рівні каналу: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: включати статуси справних каналів у вивід heartbeat. +- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід heartbeat. - `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через вебканал шлюзу (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс. +WhatsApp працює через web-канал шлюзу (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс. ```json5 { @@ -124,7 +124,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // сині галочки (false у режимі чату із собою) + sendReadReceipts: true, // сині галочки (false у режимі чату із самим собою) groups: { "*": { requireMention: true }, }, @@ -164,10 +164,10 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований ідентифікатор облікового запису (відсортований). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується `openclaw doctor` до `whatsapp/default`. -- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Команди на вихід типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований ідентифікатор облікового запису (відсортований). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. +- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (типово: off; явно вмикайте, щоб уникнути обмежень частоти для редагування попереднього перегляду) + streaming: "partial", // off | partial | block | progress (типово: off; увімкніть явно, щоб уникнути обмежень частоти preview-edit) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,12 +226,12 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві ``` - Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. -- У багатооблікових конфігураціях (2+ ідентифікаторів облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення недійсне. -- `configWrites: false` блокує записи конфігурації, ініційовані з Telegram (міграції ідентифікаторів супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потоків у Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). -- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- У багатооблікових конфігураціях (2+ ідентифікаторів облікових записів) задайте явний типово вибраний обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо його немає або він некоректний. +- `configWrites: false` блокує ініційовані з Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` із `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів є спільною в [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потокової передачі в Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Політика повторних спроб: див. [Retry policy](/uk/concepts/retry). ### Discord @@ -297,7 +297,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // явне ввімкнення для sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // увімкнення за бажанням для sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,35 +334,35 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві ``` - Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політики облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал гільдії) для цілей доставки; прості числові ідентифікатори відхиляються. -- Slug-и гільдій мають нижній регістр із заміненими на `-` пробілами; ключі каналів використовують slug-овану назву (без `#`). Надавайте перевагу ідентифікаторам гільдій. -- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення для каналів) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (окрім @everyone/@here). -- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до потоків Discord: - - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до потоків (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і пов’язана доставка/маршрутизація) +- Прямі вихідні виклики, що надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- Використовуйте `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: + - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація) - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач явного ввімкнення для автоматичного створення/прив’язки потоків у `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і потоків (використовуйте ідентифікатор каналу/потоку в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів компонентів Discord v2. + - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки гілок у `sessions_spawn({ thread: true })` +- Записи верхнього рівня `bindings[]` із `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів є спільною в [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів компонентів Discord 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` знову вмикає зіставлення за змінюваними іменами/тегами (режим аварійної сумісності). -- `channels.discord.execApprovals`: доставка схвалень exec, нативна для Discord, і авторизація тих, хто схвалює. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ідентифікатори користувачів Discord, яким дозволено схвалювати запити exec. Якщо пропущено, використовується резервне значення з `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий список дозволених ідентифікаторів агентів. Пропустіть, щоб пересилати схвалення для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сеансу (підрядок або regex). - - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в особисті повідомлення тим, хто схвалює, `"channel"` надсилає в початковий канал, `"both"` надсилає в обидва місця. Коли ціль включає `"channel"`, кнопками можуть користуватися лише визначені ті, хто схвалює. - - `cleanupAfterResolve`: коли `true`, видаляє особисті повідомлення зі схваленням після схвалення, відхилення або тайм-ауту. +- OpenClaw також намагається відновити голосовий прийом, виходячи та повторно приєднуючись до голосового сеансу після повторних збоїв дешифрування. +- `channels.discord.streaming` — це канонічний ключ режиму потоку. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично. +- `channels.discord.autoPresence` відображає доступність runtime на присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). +- `channels.discord.execApprovals`: доставка схвалень exec у стилі Discord і авторизація тих, хто схвалює. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Discord, яким дозволено схвалювати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий список дозволених ID агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. + - `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 працює через вебканал шлюзу (Baileys Web). Ві } ``` -- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`). +- JSON облікового запису служби: вбудований (`serviceAccount`) або з файла (`serviceAccountFile`). - Також підтримується SecretRef облікового запису служби (`serviceAccountRef`). -- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Резервні варіанти через env: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Використовуйте `spaces/` або `users/` для цілей доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим аварійної сумісності). +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). ### Slack @@ -449,7 +449,7 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // використовувати нативний потоковий API Slack, коли mode=partial + nativeTransport: true, // використовувати власний streaming API Slack, коли mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,35 +464,35 @@ WhatsApp працює через вебканал шлюзу (Baileys Web). Ві } ``` -- **Режим socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта змінних середовища типового облікового запису). -- **Режим HTTP** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). +- **Режим Socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервний варіант env для типового облікового запису). +- **Режим HTTP** вимагає `botToken` плюс `signingSecret` (у корені або для кожного облікового запису). - `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті рядки або об’єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/статусу для окремих облікових даних, як-от - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, +- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового даного, наприклад + `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в режимі HTTP — `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштовано через SecretRef, але поточний шлях команди/runtime не зміг + налаштований через SecretRef, але поточний шлях команди/runtime не зміг визначити значення секрету. - `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. -- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` автоматично мігруються. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує власним транспортом потокової передачі Slack. Застарілі `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. - Використовуйте `user:` (DM) або `channel:` для цілей доставки. **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). -**Ізоляція сеансів потоку:** `thread.historyScope` — для окремого потоку (типово) або спільно для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові потоки. +**Ізоляція сеансів гілок:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно на рівні каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки. -- Нативний потоковий режим Slack плюс статус потоку Slack у стилі помічника "is typing..." вимагають цілі відповіді в потоці. Особисті повідомлення верхнього рівня типово залишаються поза потоком, тому використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі потоку. +- Власна потокова передача Slack разом зі статусом гілки Slack у стилі помічника "is typing..." вимагають ціль відповіді у гілці. DM верхнього рівня типово залишаються поза гілкою, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі гілки. - `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: доставка схвалень exec, нативна для Slack, і авторизація тих, хто схвалює. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- `channels.slack.execApprovals`: доставка схвалень exec у стилі Slack і авторизація тих, хто схвалює. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------ | ------- | ---------------------- | -| reactions | увімкнено | Реагування + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріплення/відкріплення/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список користувацьких емодзі | +| Група дій | Типово | Примітки | +| ----------- | -------- | ------------------------- | +| reactions | увімкнено | Реакції + список реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріпити/відкріпити/список | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких емодзі | ### Mattermost @@ -513,10 +513,10 @@ Mattermost постачається як плагін: `openclaw plugins install "team-channel-id": { requireMention: false }, }, commands: { - native: true, // явне ввімкнення + native: true, // увімкнення за бажанням nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Необов’язковий явний URL для розгортань із reverse proxy/публічним доступом + // Необов’язкова явна URL-адреса для розгортань із reverse proxy/публічним доступом callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +526,24 @@ Mattermost постачається як плагін: `openclaw plugins install } ``` -Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). +Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера). -Коли нативні команди Mattermost увімкнено: +Коли власні команди Mattermost увімкнено: -- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL. -- `commands.callbackUrl` має вказувати на кінцеву точку шлюзу OpenClaw і бути доступним із сервера Mattermost. -- Нативні зворотні виклики slash-команд автентифікуються за допомогою токенів - для окремих команд, які Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або жодні - команди не активовано, OpenClaw відхиляє зворотні виклики з +- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. +- `commands.callbackUrl` має вказувати на endpoint шлюзу OpenClaw і бути доступною з сервера Mattermost. +- Власні slash callback-обробники автентифікуються за токенами кожної + команди, які Mattermost повертає під час реєстрації slash command. Якщо + реєстрація не вдається або жодну команду не активовано, OpenClaw відхиляє + callback-и з помилкою `Unauthorized: invalid command token.` -- Для приватних/tailnet/внутрішніх хостів зворотних викликів Mattermost може вимагати, - щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. - Використовуйте значення хоста/домену, а не повні 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`: перевизначення обмеження за згадкою для окремого каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення контролю згадування для конкретного каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. ### Signal @@ -565,9 +566,9 @@ Mattermost постачається як плагін: `openclaw plugins install **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). -- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. +- `channels.signal.configWrites`: дозволяти або забороняти записи конфігурації, ініційовані з Signal. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. ### BlueBubbles @@ -586,10 +587,10 @@ BlueBubbles — рекомендований шлях для iMessage (на ос } ``` -- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сеансів. Використовуйте BlueBubbles handle або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles). +- Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- Записи верхнього рівня `bindings[]` із `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сеансів ACP. Використовуйте handle BlueBubbles або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage @@ -617,17 +618,17 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. - Потрібен Full Disk Access до БД Messages. - Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на SSH-обгортку; установіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключів хоста, тому переконайтеся, що ключ хоста ретранслятора вже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сеансів. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ relay-хоста вже існує в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволяти або забороняти записи конфігурації, ініційовані з iMessage. +- Записи верхнього рівня `bindings[]` із `type: "acp"` можуть прив’язувати розмови iMessage до постійних сеансів ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -668,21 +669,21 @@ Matrix підтримується розширенням і налаштовує } ``` -- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити його за допомогою `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver. `proxy` і це явне ввімкнення мережі — незалежні елементи керування. -- `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у багатооблікових конфігураціях. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення в стилі особистих повідомлень ігноруються, доки ви не встановите `autoJoin: "allowlist"` із `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: доставка схвалень exec, нативна для Matrix, і авторизація тих, хто схвалює. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ідентифікатори користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати запити exec. - - `agentFilter`: необов’язковий список дозволених ідентифікаторів агентів. Пропустіть, щоб пересилати схвалення для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сеансу (підрядок або regex). - - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`. - - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як особисті повідомлення Matrix групуються в сеанси: `per-user` (типово) спільне групування за маршрутизованим співрозмовником, тоді як `per-room` ізолює кожну кімнату особистих повідомлень. -- Перевірки стану Matrix і живі пошуки в каталозі використовують ту саму політику проксі, що й runtime-трафік. -- Повну конфігурацію Matrix, правила націлювання та приклади налаштування задокументовано в [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` і цей мережевий opt-in — незалежні елементи керування. +- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` разом із `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: доставка схвалень exec у стилі Matrix і авторизація тих, хто схвалює. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли тих, хто схвалює, можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати запити exec. + - `agentFilter`: необов’язковий список дозволених ID агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex). + - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - Перевизначення для облікового запису: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як DM у Matrix групуються в сеанси: `per-user` (типово) спільний для маршрутизованого peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і live-пошуки в каталозі використовують ту саму політику proxy, що й runtime-трафік. +- Повну конфігурацію Matrix, правила таргетингу й приклади налаштування описано в [Matrix](/uk/channels/matrix). ### Microsoft Teams @@ -701,8 +702,8 @@ Microsoft Teams підтримується розширенням і налаш } ``` -- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політику DM/груп, перевизначення для окремих команд/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) описано в [Microsoft Teams](/uk/channels/msteams). ### IRC @@ -727,13 +728,13 @@ IRC підтримується розширенням і налаштовуєт } ``` -- Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/mention gating) задокументовано в [IRC](/uk/channels/irc). +- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/контроль згадувань) описано в [IRC](/uk/channels/irc). -### Багатообліковість (усі канали) +### Багато облікових записів (усі канали) -Запускайте кілька облікових записів на канал (кожен із власним `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -755,27 +756,27 @@ IRC підтримується розширенням і налаштовуєт ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени середовища застосовуються лише до облікового запису **default**. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для окремого облікового запису. +- Токени env застосовуються лише до облікового запису **default**. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для конкретного облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або через онбординг каналу), коли все ще використовується конфігурація каналу верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, що мають область облікового запису, до карти облікових записів каналу, щоб початковий обліковий запис продовжував працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -- Наявні прив’язки лише каналу (без `accountId`) продовжують відповідати типовому обліковому запису; прив’язки з областю облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису з областю облікового запису в підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або onboarding каналу), залишаючись у топології одноканальної конфігурації верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переносять їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Наявні прив’язки лише для каналу (без `accountId`) і далі відповідатимуть default обліковому запису; прив’язки з областю дії облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у promoted account, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. ### Інші канали розширень -Багато каналів розширень налаштовуються як `channels.` і задокументовані на своїх окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів розширень налаштовуються як `channels.` і описані на їхніх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Обмеження за згадкою в групових чатах +### Контроль згадувань у групових чатах -Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage. +Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage. **Типи згадок:** -- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі чату із собою у WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечне вкладене повторення ігноруються. -- Обмеження за згадкою застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони й небезпечні вкладені повторення ігноруються. +- Контроль згадувань застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). ```json5 { @@ -788,9 +789,9 @@ IRC підтримується розширенням і налаштовуєт } ``` -`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або для окремого облікового запису). Встановіть `0`, щоб вимкнути. -#### Ліміти історії особистих повідомлень +#### Ліміти історії DM ```json5 { @@ -805,13 +806,13 @@ IRC підтримується розширенням і налаштовуєт } ``` -Визначення значення: перевизначення для окремого DM → типове значення провайдера → без обмеження (зберігається все). +Вирішення: перевизначення для конкретного DM → типове значення постачальника → без ліміту (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Режим чату із собою +#### Режим self-chat -Додайте власний номер до `allowFrom`, щоб увімкнути режим чату із собою (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): +Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): ```json5 { @@ -832,7 +833,7 @@ IRC підтримується розширенням і налаштовуєт } ``` -### Команди (обробка команд у чаті) +### Команди (обробка команд чату) ```json5 { @@ -840,13 +841,13 @@ IRC підтримується розширенням і налаштовуєт native: "auto", // реєструвати нативні команди, коли це підтримується nativeSkills: "auto", // реєструвати нативні команди Skills, коли це підтримується text: true, // розбирати /commands у повідомленнях чату - bash: false, // дозволити ! (псевдонім: /bash) + bash: false, // дозволяти ! (псевдонім: /bash) bashForegroundMs: 2000, - config: false, // дозволити /config - mcp: false, // дозволити /mcp - plugins: false, // дозволити /plugins - debug: false, // дозволити /debug - restart: true, // дозволити /restart + інструмент перезапуску шлюзу + config: false, // дозволяти /config + mcp: false, // дозволяти /mcp + plugins: false, // дозволяти /plugins + debug: false, // дозволяти /debug + restart: true, // дозволяти /restart + інструмент перезапуску шлюзу ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,27 +862,27 @@ IRC підтримується розширенням і налаштовуєт -- Цей блок налаштовує поверхні команд. Для поточного каталогу вбудованих + комплектних команд див. [Команди зі слешем](/uk/tools/slash-commands). -- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/плагінів, а також у [Командах зі слешем](/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-бота. +- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + 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` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних операторських клієнтів з областю запису. -- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення плагінів, установлення та елементів керування ввімкненням/вимкненням. -- `channels..configWrites` керує мутаціями конфігурації для окремого каналу (типово: true). +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів шлюзу `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів оператора з областю запису. +- `mcp: true` вмикає `/mcp` для конфігурації сервера MCP, яким керує OpenClaw, у `mcp.servers`. +- `plugins: true` вмикає `/plugins` для виявлення плагінів, встановлення та елементів керування ввімкненням/вимкненням. +- `channels..configWrites` керує мутаціями конфігурації для каналу (типово: true). - Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). - `restart: false` вимикає `/restart` і дії інструмента перезапуску шлюзу. Типове значення: `true`. -- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`. -- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених/сполучення каналу та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено. +- `ownerAllowFrom` — це явний список дозволів власника для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. +- `ownerDisplay: "hash"` хешує id власника в системному prompt. Встановіть `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` задається для кожного постачальника. Якщо встановлено, це **єдине** джерело авторизації (списки дозволів/сполучення каналу та `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено. - Карта документації команд: - - вбудований + комплектний каталог: [Команди зі слешем](/uk/tools/slash-commands) + - вбудований + bundled каталог: [Slash Commands](/uk/tools/slash-commands) - поверхні команд, специфічні для каналу: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - команди сполучення: [Pairing](/uk/channels/pairing) @@ -892,7 +893,7 @@ IRC підтримується розширенням і налаштовуєт --- -## Типові значення агентів +## Типові значення агента ### `agents.defaults.workspace` @@ -906,7 +907,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, показаний у рядку Runtime системного запиту. Якщо не встановлено, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від workspace. ```json5 { @@ -916,7 +917,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.skills` -Необов’язковий типовий список дозволених Skills для агентів, які не задають +Необов’язковий типовий список дозволів Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -934,13 +935,13 @@ IRC підтримується розширенням і налаштовуєт - Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. - Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не було Skills. +- Встановіть `agents.list[].skills: []`, щоб не використовувати Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` -Вимикає автоматичне створення bootstrap-файлів робочого простору (`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 +951,9 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору вбудовуються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторне вбудовування bootstrap робочого простору, зменшуючи розмір запиту. Запуски heartbeat і повторні спроби після ущільнення все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt. Запуски heartbeat і повторні спроби після ущільнення все одно перебудовують контекст. ```json5 { @@ -962,7 +963,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл робочого простору до обрізання. Типове значення: `20000`. +Максимальна кількість символів на bootstrap-файл workspace до обрізання. Типове значення: `20000`. ```json5 { @@ -972,7 +973,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються в усі bootstrap-файли робочого простору. Типове значення: `150000`. +Максимальна сумарна кількість символів, що вставляються через всі bootstrap-файли workspace. Типове значення: `150000`. ```json5 { @@ -985,9 +986,9 @@ IRC підтримується розширенням і налаштовуєт Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний запит. -- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). -- `"always"`: вбудовувати попередження при кожному запуску, коли існує обрізання. +- `"off"`: ніколи не вставляти текст попередження в системний prompt. +- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. ```json5 { @@ -997,10 +998,10 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшого боку зображення в блоках зображень transcript/tool перед викликами провайдера. +Максимальний розмір у пікселях для найдовшого боку зображення в блоках зображень transcript/tool перед викликами постачальника. Типове значення: `1200`. -Нижчі значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту для запусків із великою кількістю знімків екрана. +Нижчі значення зазвичай зменшують використання vision-token і розмір payload запиту для сценаріїв із великою кількістю знімків екрана. Вищі значення зберігають більше візуальних деталей. ```json5 @@ -1011,7 +1012,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1021,7 +1022,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.timeFormat` -Формат часу в системному запиті. Типове значення: `auto` (уподобання ОС). +Формат часу в системному prompt. Типове значення: `auto` (параметр ОС). ```json5 { @@ -1059,9 +1060,9 @@ IRC підтримується розширенням і налаштовуєт primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // глобальні типові параметри провайдера + params: { cacheRetention: "long" }, // глобальні типові параметри постачальника embeddedHarness: { - runtime: "auto", // auto | pi | registered harness id, e.g. codex + runtime: "auto", // auto | pi | зареєстрований id harness, наприклад codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1080,47 +1081,47 @@ IRC підтримується розширенням і налаштовуєт - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Рядкова форма задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядковані резервні моделі для failover. + - Об’єктна форма задає основну модель плюс упорядковані failover-моделі. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/плагіна, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-1` для OpenAI Images. - - Якщо ви напряму вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо поле пропущено, `image_generate` все одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію постачальника/API key (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо не вказано, `image_generate` усе одно може визначити типове значення постачальника з автентифікацією. Спочатку він пробує поточного типового постачальника, а потім — решту зареєстрованих постачальників генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо поле пропущено, `music_generate` все одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. - - Якщо ви напряму вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо не вказано, `music_generate` усе одно може визначити типове значення постачальника з автентифікацією. Спочатку він пробує поточного типового постачальника, а потім — решту зареєстрованих постачальників генерації музики в порядку provider-id. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію постачальника/API key. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо поле пропущено, `video_generate` все одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. - - Якщо ви напряму вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - - Комплектний провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо не вказано, `video_generate` усе одно може визначити типове значення постачальника з автентифікацією. Спочатку він пробує поточного типового постачальника, а потім — решту зареєстрованих постачальників генерації відео в порядку provider-id. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію постачальника/API key. + - Вбудований постачальник генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня постачальника `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо поле пропущено, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сеансу/типової моделі. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується в режимі резервного вилучення для інструмента `pdf`. + - Якщо не вказано, інструмент 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 спочатку пробує псевдонім, потім — унікальний збіг точно для цього ідентифікатора моделі серед налаштованих провайдерів, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). -- `embeddedHarness`: типова політика низькорівневого вбудованого runtime агента. Використовуйте `runtime: "auto"`, щоб зареєстровані harness плагінів могли заявляти підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. -- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та за можливості зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів у різних сеансах (кожен окремий сеанс усе одно серіалізується). Типове значення: 4. +- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте постачальника, OpenClaw спочатку намагається знайти псевдонім, потім — унікальний збіг точно цього model id серед налаштованих постачальників, і лише після цього резервно використовує налаштованого типового постачальника (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей постачальник більше не надає налаштовану типову модель, OpenClaw резервно переходить до першого налаштованого `provider/model` замість показу застарілого типового значення видаленого постачальника. +- `models`: налаштований каталог моделей і список дозволів для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для постачальника, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: глобальні типові параметри постачальника, які застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Prompt Caching](/uk/reference/prompt-caching). +- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим plugin harness-ам перехоплювати підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований PI harness, або зареєстрований id harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. +- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну об’єктну форму та за можливості зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізується). Типове значення: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. -У більшості розгортань слід залишати типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте це, коли довірений плагін надає нативний harness, наприклад комплектний -harness сервера застосунку Codex. +`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. +Для більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте це, коли довірений плагін надає нативний harness, наприклад bundled +harness app-server Codex. ```json5 { @@ -1136,15 +1137,15 @@ harness сервера застосунку Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness плагіна. Комплектний плагін Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резервний варіант сумісності. `"none"` змушує вибір відсутнього або непідтримуваного harness плагіна завершуватися помилкою замість тихого використання PI. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. -- Для розгортань лише з Codex установіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS усе ще використовують свої налаштування провайдера/моделі. +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого plugin harness. Bundled плагін Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований PI harness як резервний варіант сумісності. `"none"` змушує помилку при відсутньому або непідтримуваному виборі plugin harness замість тихого переходу на PI. +- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід на PI для цього процесу. +- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS усе одно використовують власні налаштування `provider/model`. -**Скорочення вбудованих псевдонімів** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення псевдонімів** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Псевдонім | Модель | +| Псевдонім | Модель | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1157,13 +1158,13 @@ harness сервера застосунку Codex. Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x автоматично вмикається режим thinking, якщо ви не вкажете `--thinking off` або самостійно не задасте `agents.defaults.models["zai/"].params.thinking`. -Для моделей Z.AI типово вмикається `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, коли явно не задано рівень thinking. +Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не встановите `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. +Для моделей Z.AI `tool_stream` типово ввімкнено для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути його. +Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-постачальники не працюють. ```json5 { @@ -1192,12 +1193,12 @@ harness сервера застосунку Codex. ``` - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сеанси підтримуються, коли задано `sessionArg`. -- Пряма передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Сеанси підтримуються, коли встановлено `sessionArg`. +- Передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на рівні типових значень (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний prompt, зібраний OpenClaw, на фіксований рядок. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із prompt. ```json5 { @@ -1221,9 +1222,9 @@ harness сервера застосунку Codex. every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типово: true; false прибирає розділ Heartbeat із системного запиту - lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору - isolatedSession: false, // типово: false; true запускає кожен heartbeat у новому сеансі (без історії розмови) + includeSystemPromptSection: true, // типово: true; false прибирає розділ Heartbeat із системного prompt + lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів workspace + isolatedSession: false, // типово: false; true запускає кожен heartbeat у новому сеансі (без історії розмов) session: "main", to: "+15555550123", directPolicy: "allow", // allow (типово) | block @@ -1238,15 +1239,15 @@ harness сервера застосунку Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API-ключем) або `1h` (автентифікація OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли false, прибирає розділ Heartbeat із системного запиту та пропускає вбудовування `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли true, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для ходу агента heartbeat до його переривання. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/доставки в DM. `allow` (типово) дозволяє доставку з прямою ціллю. `block` пригнічує доставку з прямою ціллю та створює `reason=dm-blocked`. -- `lightContext`: коли true, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `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 із системного prompt і пропускає вставку `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо true, пригнічує payload-и попереджень про помилки інструментів під час запусків heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для ходу агента heartbeat до його примусового переривання. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`. +- `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` @@ -1256,19 +1257,19 @@ harness сервера застосунку Codex. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // ідентифікатор зареєстрованого плагіна провайдера compaction (необов’язково) + provider: "my-provider", // id зареєстрованого плагіна-постачальника compaction (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Точно зберігайте ідентифікатори розгортання, ідентифікатори квитків і пари host:port.", // використовується, коли identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + identifierInstructions: "Точно зберігайте ID розгортань, ID квитків і пари host:port.", // використовується, коли identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторну вставку model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction - notifyUser: true, // надсилати коротке сповіщення, коли починається compaction (типово: false) + notifyUser: true, // надіслати коротке сповіщення, коли починається compaction (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Сеанс наближається до compaction. Збережіть довготривалі спогади зараз.", - prompt: "Запишіть усі довготривалі нотатки до memory/YYYY-MM-DD.md; дайте відповідь точним тихим токеном NO_REPLY, якщо зберігати нічого.", + systemPrompt: "Сеанс наближається до compaction. Збережіть тривалі спогади зараз.", + prompt: "Запишіть усі довготривалі нотатки в memory/YYYY-MM-DD.md; дайте відповідь точним тихим токеном NO_REPLY, якщо нічого зберігати.", }, }, }, @@ -1276,15 +1277,15 @@ harness сервера застосунку Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: ідентифікатор зареєстрованого плагіна провайдера compaction. Якщо встановлено, замість вбудованого LLM-підсумовування викликається `summarize()` провайдера. У разі збою повертається до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `mode`: `default` або `safeguard` (підсумовування шматками для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого плагіна-постачальника 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`: тихий агентний хід перед автоматичним compaction для збереження довготривалих спогадів. Пропускається, якщо робочий простір доступний лише для читання. +- `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`: тихий агентний хід перед auto-compaction для збереження довготривалих спогадів. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` @@ -1313,24 +1314,24 @@ harness сервера застосунку Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищує старіші результати інструментів. -**М’яке скорочення** зберігає початок і кінець та вставляє `...` посередині. +**М’яке обрізання** зберігає початок і кінець та вставляє посередині `...`. **Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не скорочуються й не очищаються. -- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень помічника, обрізання пропускається. +- Блоки зображень ніколи не обрізаються й не очищуються. +- Співвідношення рахуються за символами (приблизно), а не за точною кількістю токенів. +- Якщо повідомлень assistant менше, ніж `keepLastAssistants`, обрізання пропускається. -Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). +Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning). -### Блокове потокове передавання +### Блокова потокова передача ```json5 { @@ -1346,13 +1347,13 @@ harness сервера застосунку Codex. } ``` -- Для каналів, відмінних від Telegram, потрібне явне `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. +- Канали, крім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. - `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Деталі поведінки та розбиття на фрагменти див. у [Streaming](/uk/concepts/streaming). +Докладніше про поведінку й поділ на фрагменти див. у [Streaming](/uk/concepts/streaming). -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -1366,7 +1367,7 @@ harness сервера застосунку Codex. ``` - Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для окремого сеансу: `session.typingMode`, `session.typingIntervalSeconds`. +- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Typing Indicators](/uk/concepts/typing-indicators). @@ -1374,7 +1375,7 @@ harness сервера застосунку Codex. ### `agents.defaults.sandbox` -Необов’язкова пісочниця для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1473,19 +1474,19 @@ harness сервера застосунку Codex. **Бекенд:** -- `docker`: локальний runtime Docker (типово) -- `ssh`: загальний віддалений runtime на основі SSH +- `docker`: локальний Docker runtime (типово) +- `ssh`: універсальний віддалений runtime на базі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в `plugins.entries.openshell.config`. **Конфігурація SSH-бекенда:** - `target`: SSH-ціль у форматі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів кожної області -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються до OpenSSH +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за кожною областю +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH @@ -1494,27 +1495,27 @@ harness сервера застосунку Codex. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сеансу sandbox +- Значення `*Data` на базі SecretRef визначаються з активного знімка runtime secrets до початку сеансу sandbox **Поведінка SSH-бекенда:** -- один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім зберігає віддалений SSH-робочий простір канонічним -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH +- один раз ініціалізує віддалений workspace після створення або повторного створення +- далі зберігає віддалений SSH-workspace як канонічний +- маршрутизує `exec`, файлові інструменти й шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично - не підтримує браузерні контейнери sandbox -**Доступ до робочого простору:** +**Доступ до workspace:** -- `none`: робочий простір sandbox для кожної області в `~/.openclaw/sandboxes` -- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` -- `rw`: робочий простір агента змонтовано для читання й запису в `/workspace` +- `none`: workspace sandbox для кожної області в `~/.openclaw/sandboxes` +- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` +- `rw`: workspace агента монтується для читання/запису в `/workspace` **Область:** -- `session`: окремий контейнер + робочий простір для кожного сеансу -- `agent`: один контейнер + робочий простір на агента (типово) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сеансами) +- `session`: контейнер + workspace для кожного сеансу +- `agent`: один контейнер + workspace на агента (типово) +- `shared`: спільний контейнер і workspace (без міжсеансової ізоляції) **Конфігурація плагіна OpenShell:** @@ -1531,7 +1532,7 @@ harness сервера застосунку Codex. remoteAgentWorkspaceDir: "/agent", gateway: "lab", // необов’язково gatewayEndpoint: "https://lab.example", // необов’язково - policy: "strict", // необов’язковий ідентифікатор політики OpenShell + policy: "strict", // необов’язковий id політики OpenShell providers: ["openai"], // необов’язково autoProviders: true, timeoutSeconds: 120, @@ -1544,30 +1545,30 @@ harness сервера застосунку Codex. **Режим OpenShell:** -- `mirror`: ініціалізувати віддалене середовище з локального перед `exec`, синхронізувати назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізувати віддалене середовище під час створення sandbox, потім зберігати віддалений робочий простір канонічним +- `mirror`: ініціалізувати віддалений із локального перед exec, синхронізувати назад після exec; локальний workspace залишається канонічним +- `remote`: один раз ініціалізувати віддалений при створенні sandbox, далі віддалений workspace залишається канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються автоматично до sandbox після етапу ініціалізації. -Транспорт — SSH до sandbox OpenShell, але плагін керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` локальні правки на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після етапу початкової ініціалізації. +Транспорт — SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою синхронізацією mirror керує плагін. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного мережевого доступу, записуваного кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу в мережу, кореневої файлової системи для запису та користувача root. -**Для контейнерів типово використовується `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +**Контейнери типово мають `network: "none"`** — встановіть `"bridge"` (або користувацьку bridge-мережу), якщо агенту потрібен вихідний доступ. `"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремих агентів об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість розкриття пароля у спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість розкриття пароля в спільному URL). -- `allowHostControl: false` (типово) блокує націлювання sandbox-сеансів на браузер хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. -- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера діапазоном CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), це замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів із контейнерами: +- `allowHostControl: false` (типово) блокує для сеансів у sandbox націлювання на браузер хоста. +- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. +- `cdpSourceRange` за бажанням обмежує вхідний CDP-трафік на межі контейнера діапазоном CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо встановлено (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів контейнерів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1587,21 +1588,21 @@ harness сервера застосунку Codex. - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` типово ввімкнені, і їх можна вимкнути через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо вони - потрібні вашому робочому процесу. + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + залежить від них. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати - типове обмеження процесів Chromium. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; встановіть `0`, щоб використовувати + типове обмеження кількості процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення — це базовий рівень образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний - образ браузера з власним entrypoint. + - Типові значення є базовим рівнем образу контейнера; використовуйте власний образ браузера з власним + entrypoint, щоб змінити типові значення контейнера. -Пісочниця браузера та `sandbox.docker.binds` доступні лише для Docker. +Ізоляція браузера та `sandbox.docker.binds` підтримуються лише для Docker. -Збірка образів: +Зібрати образи: ```bash scripts/sandbox-setup.sh # основний образ sandbox @@ -1621,12 +1622,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б 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 для окремого агента + thinkingDefault: "high", // перевизначення рівня thinking для окремого агента + reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента + fastModeDefault: false, // перевизначення fast mode для окремого агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає ключі відповідних defaults.models params - skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано + params: { cacheRetention: "none" }, // перевизначає params відповідних defaults.models за ключем + skills: ["docs-search"], // замінює agents.defaults.skills, якщо встановлено identity: { name: "Samantha", theme: "helpful sloth", @@ -1657,25 +1658,25 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `id`: стабільний ідентифікатор агента (обов’язково). -- `default`: коли задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. -- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові `fallbacks`, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли вони задані; явний список замінює типові значення, а не зливається з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сеансу. -- `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сеансу. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для окремого повідомлення або сеансу. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент тільки Codex, тоді як інші агенти зберігають типовий резервний варіант PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент типово має використовувати ACP harness-сеанси. -- `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. -- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сеанс запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які виконувалися б без sandbox. -- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, які пропускають `agentId` (примушує до явного вибору профілю; типово: false). +- `id`: стабільний id агента (обов’язково). +- `default`: якщо встановлено для кількох агентів, перемагає перший (записується попередження). Якщо не встановлено ніде, типово використовується перший елемент списку. +- `model`: рядкова форма перевизначає лише `primary`; об’єктна форма `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback-и). Cron jobs, які перевизначають лише `primary`, усе ще успадковують типові fallback-и, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `skills`: необов’язковий список дозволів Skills для окремого агента. Якщо не вказано, агент успадковує `agents.defaults.skills`, коли їх задано; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для повідомлення або сеансу. +- `reasoningDefault`: необов’язковий типовий рівень видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сеансу. +- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast-mode для повідомлення або сеансу. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний варіант PI. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сеанси ACP harness. +- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`. +- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сеанс-запитувач виконується в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує явний вибір профілю; типово: false). --- -## Маршрутизація між кількома агентами +## Маршрутизація кількох агентів Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). @@ -1694,13 +1695,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля відповідності прив’язок +### Поля відповідності binding -- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних ACP-прив’язок розмов. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, використовується route), `acp` для постійних ACP-прив’язок розмов. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічні для каналу) +- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок відповідності:** @@ -1708,13 +1709,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (точний, без peer/guild/team) -5. `match.accountId: "*"` (для всього каналу) +4. `match.accountId` (точний збіг, без peer/guild/team) +5. `match.accountId: "*"` (на рівні каналу) 6. Типовий агент У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route-прив’язок. +Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding. ### Профілі доступу для окремих агентів @@ -1736,7 +1737,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1811,7 +1812,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Деталі пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- @@ -1837,7 +1838,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропустити fork батьківського потоку понад цю кількість токенів (0 вимикає) + parentForkMaxTokens: 100000, // пропустити fork батьківської гілки вище цього ліміту токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1866,33 +1867,33 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - **`scope`**: базова стратегія групування сеансів для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли спільний контекст справді задумано). -- **`dmScope`**: як групуються особисті повідомлення. - - `main`: усі особисті повідомлення спільно використовують основний сеанс. - - `per-peer`: ізоляція за ідентифікатором відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для вхідних скриньок з кількома користувачами). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості). -- **`identityLinks`**: зіставлення канонічних ідентифікаторів із peer-значеннями з префіксом провайдера для спільного використання сеансів між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що настане раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення розгалуженого сеансу потоку (типово `100000`). - - Якщо значення `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс потоку замість успадкування історії стенограми батьківського сеансу. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківського сеансу. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у зворотному напрямку між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. -- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сеансів + керування зберіганням. - - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг давності для застарілих записів (типово `30d`). + - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст). +- **`dmScope`**: спосіб групування DM. + - `main`: усі DM використовують спільний основний сеанс. + - `per-peer`: ізоляція за id відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних вхідних скриньок кількох користувачів). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій). +- **`identityLinks`**: відображає канонічні id на peers із префіксом постачальника для спільного використання сеансів між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає те, що спливає раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення fork-сеансу гілки (типово `100000`). + - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс гілки замість успадкування історії стенограми батьківського сеансу. + - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти fork від батьківського сеансу. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного сегмента прямого чату. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона перемагає. +- **`maintenance`**: керування очищенням сховища сеансів + збереженням. + - `mode`: `warn` видає лише попередження; `enforce` застосовує очищення. + - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: обертати `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: термін зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сеансів. У режимі `warn` записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси. + - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`). + - `resetArchiveRetention`: строк зберігання для архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет диска для каталогу сеансів. У режимі `warn` записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси. - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до потоків. - - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) +- **`threadBindings`**: глобальні типові значення для функцій сеансу, прив’язаних до гілок. + - `enabled`: головний типовий перемикач (постачальники можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) + - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; постачальники можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; постачальники можуть перевизначати) @@ -1930,36 +1931,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Префікс відповіді -Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскадування. `"auto"` виводить `[{identity.name}]`. +Вирішення (перемагає найспецифічніше): обліковий запис → канал → глобальний. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | +| Змінна | Опис | Приклад | | ----------------- | ---------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | +| `{provider}` | Назва постачальника | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) | +| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. -### Реакція підтвердження +### Реакція-підтвердження -- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. +- Типово береться з `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`, щоб увімкнути реакції статусу життєвого циклу. +- `removeAckAfterReply`: видаляє ack після відповіді у Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції життєвого циклу статусу у Slack, Discord і Telegram. + У Slack і Discord, якщо не встановлено, реакції статусу залишаються ввімкненими, коли активні реакції ack. + У Telegram встановіть це явно в `true`, щоб увімкнути реакції життєвого циклу статусу. -### Вхідний debounce +### Debounce для вхідних повідомлень -Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce. ### TTS (перетворення тексту на мовлення) @@ -2002,12 +2003,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (явне ввімкнення). -- API-ключі використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на не-OpenAI кінцеву точку, OpenClaw трактує її як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. +- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує ефективний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для auto-summary. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібне явне увімкнення). +- Для API key використовуються резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок вирішення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює валідацію моделі/голосу. --- @@ -2037,13 +2038,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `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`. +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька постачальників Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. +- Для Voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. - `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після тиші користувача, перш ніж надсилати стенограму. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key для Talk. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні імена. +- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не встановлено, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2051,37 +2052,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### Профілі інструментів -`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволів перед `tools.allow`/`tools.deny`: -Локальний онбординг типово встановлює для нових локальних конфігурацій `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` приймається як псевдонім для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Група | Інструменти | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без плагінів провайдерів) | +| `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` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли sandbox Docker вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -2091,7 +2092,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.byProvider` -Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny. +Додатково обмежує інструменти для конкретних постачальників або моделей. Порядок: базовий профіль → профіль постачальника → allow/deny. ```json5 { @@ -2107,7 +2108,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.elevated` -Керує підвищеним доступом до exec поза sandbox: +Керує elevated-доступом `exec` поза sandbox: ```json5 { @@ -2125,7 +2126,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожного сеансу; вбудовані директиви застосовуються до одного повідомлення. -- Підвищений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціль exec — `node`). +- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2149,8 +2150,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.loopDetection` -Перевірки безпеки для циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **типово вимкнені**. Встановіть `enabled: true`, щоб увімкнути виявлення. +Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2171,13 +2172,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `historySize`: максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів. - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторень для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. +- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. +- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. - `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергування пар шаблонів без прогресу. +- `detectors.pingPong`: попереджати/блокувати шаблони чергування пар без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2188,7 +2189,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б web: { search: { enabled: true, - apiKey: "brave_api_key", // або змінна середовища BRAVE_API_KEY + apiKey: "brave_api_key", // або env BRAVE_API_KEY maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, @@ -2220,7 +2221,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б media: { concurrency: 2, asyncCompletion: { - directSend: false, // явне ввімкнення: надсилати готову асинхронну музику/відео безпосередньо в канал + directSend: false, // опціонально: надсилати готові асинхронні музичні/відео результати безпосередньо в канал }, audio: { enabled: true, @@ -2246,30 +2247,30 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -**Запис провайдера** (`type: "provider"` або пропущено): +**Запис постачальника** (`type: "provider"` або пропущено): -- `provider`: ідентифікатор API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) -- `model`: перевизначення ідентифікатора моделі +- `provider`: id API-постачальника (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) +- `model`: перевизначення id моделі - `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` -**Запис CLI** (`type: "cli"`): +**CLI-запис** (`type: "cli"`): - `command`: виконуваний файл для запуску -- `args`: аргументи з шаблонами (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: шаблонізовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилки виконується перехід до наступного запису. +- У разі збою використовується наступний запис. -Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. +Автентифікація постачальника дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` і `video_generate` спочатку намагаються доставлятися безпосередньо в канал. Типове значення: `false` - (застарілий шлях пробудження сеансу запитувача/доставки моделлю). + (застарілий шлях пробудження requester-session/model-delivery). @@ -2288,9 +2289,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ### `tools.sessions` -Керує тим, на які сеанси можна націлюватися за допомогою інструментів сеансів (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, які сеанси можуть бути ціллю для session tools (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточний сеанс + сеанси, породжені ним, наприклад субагенти). +Типове значення: `tree` (поточний сеанс + сеанси, породжені ним, наприклад subagents). ```json5 { @@ -2306,10 +2307,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Примітки: - `self`: лише ключ поточного сеансу. -- `tree`: поточний сеанс + сеанси, породжені поточним сеансом (субагенти). -- `agent`: будь-який сеанс, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сеанси per-sender під тим самим ідентифікатором агента). +- `tree`: поточний сеанс + сеанси, породжені поточним сеансом (subagents). +- `agent`: будь-який сеанс, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сеанси per-sender під тим самим id агента). - `all`: будь-який сеанс. Націлювання між агентами все одно потребує `tools.agentToAgent`. -- Обмеження sandbox: коли поточний сеанс працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. +- Обмеження sandbox: коли поточний сеанс виконується в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2320,10 +2321,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б tools: { sessions_spawn: { attachments: { - enabled: false, // явне ввімкнення: установіть true, щоб дозволити вбудовані файлові вкладення - maxTotalBytes: 5242880, // загалом 5 МБ для всіх файлів + enabled: false, // opt-in: встановіть true, щоб дозволити вбудовані файлові вкладення + maxTotalBytes: 5242880, // загалом 5 MB для всіх файлів maxFiles: 50, - maxFileBytes: 1048576, // 1 МБ на файл + maxFileBytes: 1048576, // 1 MB на файл retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep" }, }, @@ -2334,15 +2335,15 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. -- Файли матеріалізуються в дочірньому робочому просторі за шляхом `.openclaw/attachments//` із `.manifest.json`. +- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` разом із `.manifest.json`. - Вміст вкладень автоматично редагується під час збереження стенограми. -- Входи Base64 перевіряються суворими перевірками алфавіту/доповнення та захистом розміру до декодування. +- Входи base64 перевіряються з суворою перевіркою алфавіту/відступів і попереднім обмеженням розміру до декодування. - Права доступу до файлів: `0700` для каталогів і `0600` для файлів. -- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. +- Очищення підпорядковується політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5. +Експериментальні прапорці вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5. ```json5 { @@ -2357,8 +2358,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для strict-agentic запусків GPT-5. -- Коли інструмент увімкнено, системний запит також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи й підтримувала не більш як один крок у стані `in_progress`. +- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Встановіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. +- Коли інструмент увімкнено, системний prompt також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи і тримала не більше одного кроку `in_progress`. ### `agents.defaults.subagents` @@ -2378,16 +2379,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `model`: типова модель для породжених субагентів. Якщо пропущено, субагенти успадковують модель викликача. -- `allowAgents`: типовий список дозволених цільових ідентифікаторів агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика інструментів для окремого субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: типова модель для породжених sub-agents. Якщо не вказано, sub-agents успадковують модель викликача. +- `allowAgents`: типовий список дозволених id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. +- Політика інструментів для окремого subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Користувацькі провайдери та base URL +## Власні постачальники та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте власних постачальників через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2416,50 +2417,50 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для користувацьких потреб автентифікації. -- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). -- Пріоритет злиття для відповідних ідентифікаторів провайдерів: - - Непорожні значення `baseUrl` у `models.json` агента мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/auth-profile. - - Значення `apiKey` провайдера, що керуються через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження розгорнутих секретів. - - Значення заголовків провайдера, що керуються через 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. +- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. +- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). +- Пріоритет злиття для provider ID, що збігаються: + - Непорожні значення `baseUrl` в agent `models.json` мають пріоритет. + - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей постачальник не керується через SecretRef у поточному контексті config/auth-profile. + - Значення `apiKey` постачальника, керовані SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. + - Значення заголовків постачальника, керовані 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. -### Деталі полів провайдера +### Деталі полів постачальника -- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: карта користувацьких провайдерів, ключована за ідентифікатором провайдера. +- `models.mode`: поведінка каталогу постачальників (`merge` або `replace`). +- `models.providers`: карта власних постачальників, ключем якої є id постачальника. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати підстановку SecretRef/env). +- `models.providers.*.apiKey`: облікові дані постачальника (надавайте перевагу SecretRef/env substitution). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions`, вбудовувати `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL висхідного API. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. - - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP-proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. +- `models.providers.*.baseUrl`: базова URL-адреса API upstream. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. + - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями постачальника). Значення приймають SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію постачальника), `"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`. - - `request.allowPrivateNetwork`: коли `true`, дозволяти HTTPS до `baseUrl`, якщо DNS розв’язується в приватні, CGNAT або подібні діапазони, через SSRF-захист HTTP fetch для провайдера (явне ввімкнення оператором для довірених самохостингових OpenAI-сумісних кінцевих точок). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типове значення `false`. -- `models.providers.*.models`: явні записи каталогу моделей провайдера. -- `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли вам потрібен менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat endpoint лише з рядковим вмістом. Коли `true`, OpenClaw сплющує масиви `messages[].content`, що містять лише текст, у звичайні рядки перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань auto-discovery для Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути або вимкнути неявне виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр за ідентифікатором провайдера для цільового виявлення. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS резолвиться в приватні, CGNAT або подібні діапазони, через HTTP fetch guard постачальника (operator opt-in для довірених self-hosted OpenAI-сумісних endpoint-ів). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF gate fetch. Типове значення `false`. +- `models.providers.*.models`: явні записи каталогу моделей постачальника. +- `models.providers.*.models.*.contextWindow`: метадані нативного контекстного вікна моделі. +- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативне `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (host не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожнє/пропущене `baseUrl` зберігає типову поведінку OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat endpoint-ів, що приймають лише рядок. Коли `true`, OpenClaw сплющує масиви `messages[].content`, що містять лише текст, у звичайні рядки перед надсиланням запиту. +- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ налаштувань auto-discovery Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. +- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS region для виявлення. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне контекстне вікно для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервний максимум вихідних токенів для виявлених моделей. -### Приклади провайдерів +### Приклади постачальників @@ -2512,7 +2513,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочений варіант: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -2529,11 +2530,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочений варіант: `openclaw onboard --auth-choice zai-api-key`. +Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. -- Загальна кінцева точка: `https://api.z.ai/api/paas/v4` -- Кінцева точка для кодування (типова): `https://api.z.ai/api/coding/paas/v4` -- Для загальної кінцевої точки визначте користувацького провайдера з перевизначенням base URL. +- Загальний endpoint: `https://api.z.ai/api/paas/v4` +- Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint визначте власного постачальника з перевизначенням base URL. @@ -2572,11 +2573,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Для китайської кінцевої точки: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. +Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні кінцеві точки Moonshot рекламують сумісність із потоковим використанням на спільному -транспорті `openai-completions`, і OpenClaw визначає це за можливостями кінцевої точки, -а не лише за вбудованим ідентифікатором провайдера. +Нативні endpoint-и Moonshot оголошують сумісність використання потокової передачі на спільному +транспорті `openai-completions`, і OpenClaw спирається на можливості endpoint-а, +а не лише на вбудований id постачальника. @@ -2594,11 +2595,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний, вбудований провайдер. Скорочений варіант: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований постачальник. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2633,11 +2634,11 @@ Anthropic-сумісний, вбудований провайдер. Скоро } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2673,12 +2674,12 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -Установіть `MINIMAX_API_KEY`. Скорочені варіанти: +Установіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. -На Anthropic-сумісному потоковому шляху OpenClaw типово вимикає thinking для MiniMax, -якщо ви явно не задасте `thinking` самостійно. `/fast on` або +На Anthropic-сумісному шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, +якщо ви явно не встановите `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2686,7 +2687,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте злиті хостингові моделі для резервного варіанта. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted models об’єднаними для резервного використання. @@ -2717,14 +2718,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий список дозволених лише для комплектних Skills (не впливає на керовані/робочі Skills). +- `allowBundled`: необов’язковий список дозволів лише для 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, навіть якщо він комплектний/установлений. -- `entries..apiKey`: зручне поле для Skills, які оголошують основну змінну середовища (відкритий рядок або об’єкт SecretRef). +- `install.nodeManager`: перевага node-інсталятора для специфікацій `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручний спосіб для Skills, які оголошують основну env-змінну (відкритий рядок або об’єкт SecretRef). --- @@ -2752,47 +2753,47 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні плагіни OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного макета без маніфеста. +- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. +- Виявлення приймає нативні плагіни OpenClaw, а також сумісні bundles Codex і Claude, включно з bundle Claude стандартного макета без маніфесту. - **Зміни конфігурації потребують перезапуску шлюзу.** -- `allow`: необов’язковий список дозволених (завантажуються лише вказані плагіни). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API-ключа на рівні плагіна (коли плагін це підтримує). -- `plugins.entries..env`: карта змінних середовища в області плагіна. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють запит, із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів плагінів і підтримуваних каталогів hook-ів, наданих пакетами. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому плагіну запитувати перевизначення `provider` і `model` для окремого запуску фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений плагіном (валідується схемою нативного плагіна OpenClaw, якщо вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або змінної середовища `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). +- `allow`: необов’язковий список дозволів (завантажуються лише перелічені плагіни). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API key на рівні плагіна (коли це підтримує плагін). +- `plugins.entries..env`: карта env-змінних в області плагіна. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, зі застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних plugin hooks і підтримуваних каталогів hooks, наданих bundle. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому плагіну запитувати перевизначення `provider` і `model` для одного запуску фонових subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений плагіном (валідується за схемою нативного плагіна 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` або env var `FIRECRAWL_API_KEY`. + - `baseUrl`: базова URL-адреса API Firecrawl (типово: `https://api.firecrawl.dev`). - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту скрапінгу в секундах (типово: `60`). + - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдера X Search. + - `enabled`: увімкнути постачальника X Search. - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming (експериментально). Докладніше про фази й пороги див. у [Dreaming](/uk/concepts/dreaming). +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming (експериментально). Фази й пороги див. у [Dreaming](/uk/concepts/dreaming). - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: cron-каденс для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - `frequency`: cron-каденція для кожного повного проходу dreaming (`"0 3 * * *"` типово). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті описана в [Довіднику конфігурації пам’яті](/uk/reference/memory-config): +- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені плагіни-пакети Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати ідентифікатор активного плагіна пам’яті або `"none"`, щоб вимкнути плагіни пам’яті. -- `plugins.slots.contextEngine`: вибрати ідентифікатор активного плагіна context engine; типово `"legacy"`, якщо ви не встановите й не виберете інший engine. -- `plugins.installs`: метадані встановлення, якими керує CLI і які використовує `openclaw plugins update`. +- Увімкнені Claude bundle plugins також можуть вносити вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного плагіна пам’яті або `"none"`, щоб вимкнути плагіни пам’яті. +- `plugins.slots.contextEngine`: вибрати id активного плагіна рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- `plugins.installs`: метадані встановлення, керовані CLI, які використовує `openclaw plugins update`. - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Сприймайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручного редагування. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI над ручним редагуванням. Див. [Plugins](/uk/tools/plugin). --- -## Браузер +## Browser ```json5 { @@ -2801,7 +2802,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі + // dangerouslyAllowPrivateNetwork: true, // увімкнення лише для довіреного доступу до приватної мережі // allowPrivateNetwork: true, // застарілий псевдонім // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2829,26 +2830,26 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, коли не задано, тож навігація браузера типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не встановлено, тому навігація browser типово залишається суворою. +- Встановлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. +- У суворому режимі endpoint-и віддалених CDP-профілів (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок досяжності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі є attach-only (start/stop/reset вимкнені). +- Віддалені профілі є лише attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає прямий URL DevTools WebSocket. -- Профілі `existing-session` доступні лише на хості й використовують Chrome MCP замість CDP. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний - профіль браузера на основі Chromium, наприклад Brave або Edge. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), + коли ваш постачальник дає вам пряму URL DevTools WebSocket. +- Профілі `existing-session` працюють лише на хості та використовують Chrome MCP замість CDP. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний + профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання CSS-селекторами, hook-и - завантаження одного файлу, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. + дії на основі snapshot/ref замість націлювання CSS-селекторами, хуки для + завантаження одного файла, відсутність перевизначення тайм-аутів діалогів, відсутність + `wait --load networkidle`, а також відсутність `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок auto-detect: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Служба керування: лише local loopback (порт виводиться з `gateway.port`, типово `18791`). +- Порядок auto-detect: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад `--disable-gpu`, розміри вікна або прапорці налагодження). @@ -2862,18 +2863,18 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji, короткий текст, URL зображення або data URI }, }, } ``` -- `seamColor`: акцентний колір для chrome нативного застосунку UI (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. +- `seamColor`: колір акценту для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). +- `assistant`: перевизначення identity для Control UI. Якщо не задано, використовується identity активного агента. --- -## Шлюз +## Gateway ```json5 { @@ -2902,8 +2903,10 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // потрібно для не-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // небезпечний резервний режим origin через заголовок Host + // embedSandbox: "scripts", // strict | scripts | trusted + // allowExternalEmbedUrls: false, // небезпечно: дозволити абсолютні зовнішні URL вбудовування http(s) + // allowedOrigins: ["https://control.example.com"], // обов’язково для не-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // небезпечний режим резервного визначення origin через Host-header // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2914,12 +2917,12 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Необов’язково. Типове значення false. + // Необов’язково. Типово false. allowRealIpFallback: false, tools: { // Додаткові HTTP-заборони для /tools/invoke deny: ["browser"], - // Прибрати інструменти з типового HTTP-списку заборон + // Прибрати інструменти зі стандартного HTTP-списку заборон allow: ["gateway"], }, push: { @@ -2934,51 +2937,51 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` - + -- `mode`: `local` (запустити шлюз) або `remote` (підключитися до віддаленого шлюзу). Шлюз відмовляється запускатися, якщо не `local`. -- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `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` (лише IP Tailscale) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка для Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. Із bridge-мережею Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому шлюз недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Bind-и не на loopback вимагають автентифікації шлюзу. На практиці це означає спільний токен/пароль або reverse proxy з awareness про ідентичність із `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва, а `mode` не задано. -- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в запитах онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегувати автентифікацію reverse proxy з awareness про ідентичність і довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на тому ж хості через loopback не задовольняють автентифікацію trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю автентифікацію заголовками Tailscale; вони дотримуються звичайного режиму HTTP-автентифікації шлюзу. Цей безтокеновий потік припускає, що хост шлюзу є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожної IP-адреси клієнта і для кожної області автентифікації (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом про невдачу. Тому конкурентні хибні спроби від одного клієнта можуть спрацювати на обмежувач уже на другому запиті замість того, щоб обидві пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих розгортань через proxy). -- Спроби WS-автентифікації з походження браузера завжди обмежуються без винятку для loopback (додатковий захист від брутфорсу localhost через браузер). -- На loopback ці блокування походження браузера ізольовані для кожного нормалізованого значення `Origin`, - тож повторні невдачі з одного localhost-origin не блокують автоматично - інше origin. -- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Потрібний, коли очікуються клієнти браузера з origin не на loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для розгортань, що навмисно покладаються на політику origin за заголовком Host. +- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка про Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. Із bridge-мережею Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Для bind, відмінного від loopback, потрібна auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Під час запуску та у потоках встановлення/відновлення сервісу виникає помилка, якщо обидва налаштовані, а mode не встановлено. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій loopback; цей варіант навмисно не пропонується в підказках onboarding. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням 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`). Endpoint-и HTTP API **не** використовують цю auth за заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується для кожної IP-адреси клієнта і для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Control UI через Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом про збій. Тому паралельні хибні спроби від одного клієнта можуть спровокувати лімітатор на другому запиті, замість того щоб обидва пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо ви свідомо хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих розгортань через proxy). +- Спроби WS auth із browser-origin завжди обмежуються без винятку для loopback (захист у глибину від брутфорсу localhost через браузер). +- На loopback ці блокування для browser-origin ізолюються за нормалізованим значенням `Origin`, + тому повторні збої з одного localhost origin не блокують автоматично + інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний доступ, потрібна auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли клієнти браузера очікуються не з loopback-origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через Host-header для розгортань, що навмисно покладаються на політику origin на основі Host-header. - `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, яке дозволяє незашифрований `ws://` до довірених IP-адрес приватної мережі; типовим лишається дозвіл plaintext лише для loopback. -- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію шлюзу. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього ретранслятора APNs, який використовують офіційні/TestFlight збірки iOS після того, як вони публікують реєстрації на основі ретранслятора до шлюзу. Цей URL має відповідати URL ретранслятора, зібраному в iOS-збірці. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання шлюз→ретранслятор у мілісекундах. Типове значення: `10000`. -- Реєстрації на основі ретранслятора делегуються конкретній ідентичності шлюзу. Сполучений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію ретранслятора та пересилає шлюзу право надсилання, обмежене цією реєстрацією. Інший шлюз не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через середовище для наведеної вище конфігурації ретранслятора. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний шлях для loopback URL ретранслятора через HTTP. Промислові URL ретранслятора мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис за ковзну годину. Типове значення: `10`. -- `channels..healthMonitor.enabled`: відмова для окремого каналу від перезапусків монітора стану при збереженні глобального монітора ввімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику шлюзу можуть використовувати `gateway.remote.*` як резервне значення лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується в закритий бік (без маскування резервним віддаленим варіантом). -- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки пересланого клієнта. Указуйте лише proxy, якими ви керуєте. Записи loopback усе ще дійсні для конфігурацій виявлення локального proxy/того самого хоста (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, шлюз приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типове значення `false` для поведінки fail-closed. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське перевизначення break-glass, яке дозволяє відкритий `ws://` до довірених IP приватної мережі; типовим значенням для відкритого з’єднання залишається лише 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`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типове значення: `10000`. +- Реєстрації на основі relay делегуються конкретній identity gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю identity в реєстрацію relay і передає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch лише для розробки для loopback HTTP relay URL. У production URL relay мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналів у хвилинах. Встановіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис у ковзній годині. Типове значення: `10`. +- `channels..healthMonitor.enabled`: відмова для конкретного каналу від перезапусків health-monitor зі збереженням глобального монітора. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо встановлено, воно має пріоритет над перевизначенням рівня каналу. +- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не встановлено. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не визначено, визначення завершується fail-closed (без маскування резервним переходом на remote). +- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Додавайте лише proxy, якими ви керуєте. Записи loopback усе ще коректні для налаштувань proxy на тому самому хості/локального виявлення (наприклад 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` (розширює типовий список заборон). -- `gateway.tools.allow`: вилучити назви інструментів із типового HTTP-списку заборон. +- `gateway.tools.allow`: прибрати назви інструментів із типового HTTP-списку заборон. -### OpenAI-сумісні кінцеві точки +### OpenAI-сумісні endpoint-и - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. @@ -2986,14 +2989,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні списки дозволених трактуються як не задані; використовуйте `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)) + Порожні 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 \ @@ -3003,7 +3006,7 @@ openclaw gateway --port 19001 Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Кілька шлюзів](/uk/gateway/multiple-gateways). +Див. [Multiple Gateways](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -3021,11 +3024,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі шлюзу (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовані; лише для локального використання/розробки. -- `certPath`: шлях файлової системи до файла TLS-сертифіката. -- `keyPath`: шлях файлової системи до приватного TLS-ключа; обмежуйте права доступу. -- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або власних ланцюжків довіри. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. +- `certPath`: шлях файлової системи до файла сертифіката TLS. +- `keyPath`: шлях файлової системи до файла приватного ключа TLS; обмежте доступ правами. +- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнта або власних ланцюжків довіри. ### `gateway.reload` @@ -3042,12 +3045,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати живі зміни; потрібен явний перезапуск. - - `"restart"`: завжди перезапускати процес шлюзу при зміні конфігурації. + - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби повернутися до перезапуску. -- `debounceMs`: вікно debounce в мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). + - `"hybrid"` (типово): спочатку намагатися виконати hot reload; за потреби переходити до перезапуску. +- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: максимальний час у мс очікування завершення активних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3084,41 +3087,41 @@ openclaw gateway --port 19001 } ``` -Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook-ів у рядку запиту відхиляються. +Auth: `Authorization: Bearer ` або `x-openclaw-token: `. +Токени hook у рядку запиту відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожнього `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. +- `hooks.enabled=true` вимагає непорожній `hooks.token`. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання Gateway token відхиляється. - `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` із тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). -- `POST /hooks/` → розв’язується через `hooks.mappings` + - `sessionKey` з payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). +- `POST /hooks/` → визначається через `hooks.mappings` -- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`). -- `match.source` відповідає полю payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. +- `match.path` зіставляє підшлях після `/hooks` (наприклад `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле payload для узагальнених шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читаються з payload. - `transform` може вказувати на модуль JS/TS, що повертає дію hook. - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ідентифікатори повертаються до типового агента. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або відсутнє значення = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сеансу для запусків hook-агента без явного `sessionKey`. +- `agentId` маршрутизує до конкретного агента; невідомі ID резервно переходять до типового. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити все, `[]` = заборонити все). +- `defaultSessionKey`: необов’язковий фіксований ключ сеансу для запусків hook agent без явного `sessionKey`. - `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` задавати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. - `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо каталог моделей задано). +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо налаштовано каталог моделей). -### Інтеграція з Gmail +### Інтеграція Gmail ```json5 { @@ -3141,12 +3144,12 @@ openclaw gateway --port 19001 } ``` -- Шлюз автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. -- Не запускайте окремий `gog gmail watch serve` паралельно зі шлюзом. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо його налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- -## Хост Canvas +## Canvas host ```json5 { @@ -3158,22 +3161,22 @@ openclaw gateway --port 19001 } ``` -- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту шлюзу: +- Обслуговує HTML/CSS/JS, які може редагувати агент, і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Лише локально: залишайте `gateway.bind: "loopback"` (типово). -- Для bind не на loopback: маршрути canvas потребують auth шлюзу (token/password/trusted-proxy), як і інші HTTP-поверхні шлюзу. -- Node WebViews зазвичай не надсилають заголовки auth; після сполучення та підключення вузла шлюз рекламує URL можливостей в області вузла для доступу до canvas/A2UI. -- URL можливостей прив’язані до активного WS-сеансу вузла й швидко спливають. Резервний варіант на основі IP не використовується. -- Вбудовує клієнт live-reload у відданий HTML. +- Для bind, відмінних від loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки auth; після сполучення та підключення вузла Gateway рекламує URL можливостей, прив’язані до вузла, для доступу до canvas/A2UI. +- URL можливостей прив’язані до активного WS-сеансу вузла і швидко спливають. Резервний варіант на основі IP не використовується. +- Вставляє клієнт live-reload в HTML, що обслуговується. - Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни потребують перезапуску шлюзу. -- Вимикайте live reload для великих каталогів або при помилках `EMFILE`. +- Зміни потребують перезапуску gateway. +- Вимкніть live reload для великих каталогів або при помилках `EMFILE`. --- -## Виявлення +## Discovery ### mDNS (Bonjour) @@ -3187,9 +3190,9 @@ openclaw gateway --port 19001 } ``` -- `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. -- `full`: включати `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): пропускає `cliPath` + `sshPort` із TXT-записів. +- `full`: включає `cliPath` + `sshPort`. +- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3201,15 +3204,15 @@ openclaw gateway --port 19001 } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. +Записує unicast DNS-SD zone у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. Налаштування: `openclaw dns setup --apply`. --- -## Середовище +## Environment -### `env` (вбудовані змінні середовища) +### `env` (вбудовані env vars) ```json5 { @@ -3226,14 +3229,14 @@ openclaw gateway --port 19001 } ``` -- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу відсутній ключ. -- Файли `.env`: `.env` у поточному робочому каталозі + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої оболонки входу. +- Вбудовані env vars застосовуються лише тоді, коли у process env відсутній ключ. +- Файли `.env`: `.env` поточної робочої теки + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. - Повний пріоритет див. у [Environment](/uk/help/environment). -### Підстановка змінних середовища +### Підстановка env var -Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на env vars у будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3243,16 +3246,16 @@ openclaw gateway --port 19001 } ``` -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте як `$${VAR}` для буквального `${VAR}`. +- Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети адитивні: відкриті значення й далі працюють. +Посилання на секрети є адитивними: відкриті значення теж продовжують працювати. ### `SecretRef` @@ -3265,24 +3268,24 @@ openclaw gateway --port 19001 Валідація: - шаблон `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}$` -- `source: "exec"` `id` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад `a/../b` відхиляється) +- шаблон 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}$` +- `source: "exec"` id не мають містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання `auth-profiles.json` включені в розв’язання runtime і покриття аудиту. +- Посилання `auth-profiles.json` включені у визначення під час runtime та в покриття аудиту. -### Конфігурація провайдерів секретів +### Конфігурація постачальників секретів ```json5 { secrets: { providers: { - default: { source: "env" }, // необов’язковий явний env-провайдер + default: { source: "env" }, // необов’язковий явний env-постачальник filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3306,13 +3309,13 @@ openclaw gateway --port 19001 Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). -- Провайдер `exec` вимагає абсолютного шляху `command` і використовує протокольні payload у stdin/stdout. -- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання, водночас перевіряючи шлях розв’язаного цільового файла. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху розв’язаного цільового файла. -- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Постачальник `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). +- Постачальник `exec` вимагає абсолютний шлях `command` і використовує протокольні payload-и через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою визначеного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до визначеного цільового шляху. +- Середовище дочірнього процесу `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -3336,11 +3339,11 @@ openclaw gateway --port 19001 - Профілі для окремого агента зберігаються в `/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 (`auth.profiles..mode = "oauth"`) не підтримують облікові дані `auth-profile` на базі SecretRef. +- Статичні облікові дані runtime беруться з визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. +- Застарілий імпорт OAuth — з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). +- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -3362,20 +3365,21 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: базове відкладення в годинах, коли профіль зазнає збою через справжні +- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг - може все одно потрапляти сюди навіть за відповідей `401`/`403`, але текстові - зіставлювачі, специфічні для провайдера, залишаються в межах провайдера, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані повідомлення `402` про вікно використання або - про ліміт витрат організації/робочого простору залишаються натомість у шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин відкладення білінгу для окремих провайдерів. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання відкладення білінгу (типово: `24`). -- `authPermanentBackoffMinutes`: базове відкладення в хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). -- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання відкладення `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників відкладення (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile одного провайдера для перевантажених помилок перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, що означають зайнятість провайдера. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile одного провайдера для помилок rate limit перед переходом до резервної моделі (типово: `1`). До цього кошика rate limit входить текст, характерний для провайдерів, наприклад `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. + усе ще може потрапляти сюди навіть при відповідях `401`/`403`, але + зіставлення тексту, специфічне для постачальника, залишається обмеженим + постачальником, якому воно належить (наприклад OpenRouter + `Key limit exceeded`). Повідомлення retryable HTTP `402` про вікно використання або + ліміт витрат організації/workspace натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих постачальників. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високодовірених збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого постачальника для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли постачальник зайнятий. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого постачальника/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого постачальника для помилок rate-limit перед переходом до резервної моделі (типово: `1`). Цей bucket rate-limit включає текстові форми, характерні для постачальника, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3395,9 +3399,9 @@ openclaw gateway --port 19001 ``` - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` з `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 МБ). Для промислових розгортань використовуйте зовнішню ротацію журналів. +- Встановіть `logging.file` для стабільного шляху. +- `consoleLevel` підвищується до `debug` при `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -3434,8 +3438,8 @@ openclaw gateway --port 19001 } ``` -- `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналів (підтримує шаблони з підстановкою, як-от `"telegram.*"` або `"*"`). +- `enabled`: головний перемикач виводу інструментування (типово: `true`). +- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналів (підтримує шаблони з підстановкою, як-от `"telegram.*"` або `"*"`). - `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислий сеанс, поки сеанс залишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. @@ -3443,10 +3447,10 @@ openclaw gateway --port 19001 - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. - `otel.serviceName`: назва сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. -- `otel.sampleRate`: частота семплювання trace `0`–`1`. +- `otel.sampleRate`: частота вибірки trace `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. - `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`). --- @@ -3469,12 +3473,12 @@ openclaw gateway --port 19001 } ``` -- `channel`: канал релізу для інсталяцій npm/git — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску шлюзу (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для пакетних інсталяцій (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням у stable-каналі (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`). +- `channel`: канал випусків для npm/git-установок — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних установок (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу в годинах для розгортання stable-каналу (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). --- @@ -3508,21 +3512,21 @@ openclaw gateway --port 19001 ``` - `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для диспетчеризації ходів ACP-сеансів (типово: `true`). Установіть `false`, щоб залишити ACP-команди доступними, але блокувати виконання. -- `backend`: типовий ідентифікатор бекенда ACP runtime (має відповідати зареєстрованому плагіну ACP runtime). -- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawn не задає явної цілі. -- `allowedAgents`: список дозволених ідентифікаторів агентів для ACP runtime-сеансів; порожнє значення означає відсутність додаткових обмежень. +- `dispatch.enabled`: незалежний перемикач для диспетчеризації ходів ACP-сеансу (типово: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося. +- `backend`: id типового runtime-бекенда ACP (має збігатися із зареєстрованим плагіном ACP runtime). +- `defaultAgent`: резервний id цільового агента ACP, коли spawn-и не задають явну ціль. +- `allowedAgents`: список дозволених id агентів для ACP runtime-сеансів; порожнє значення означає відсутність додаткових обмежень. - `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сеансів. - `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. - `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах одного ходу (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік інкрементально; `"final_only"` буферизує до термінальних подій ходу. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів на хід (типово: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один ACP-хід. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих ACP-рядків статусу/оновлення. -- `stream.tagVisibility`: запис відповідностей назв тегів до булевих перевизначень видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для worker-ів ACP-сеансів до того, як вони стануть придатними для очищення. -- `runtime.installCommand`: необов’язкова команда встановлення, яку слід запускати під час bootstrap середовища ACP runtime. +- `stream.maxOutputChars`: максимальна кількість символів виводу assistant, проєктованих на хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. +- `stream.tagVisibility`: запис відповідності назв тегів булевим перевизначенням видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для робітників ACP-сеансу до можливого очищення. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час початкового налаштування середовища ACP runtime. --- @@ -3538,17 +3542,17 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` керує стилем підзаголовка банера: - - `"random"` (типово): змінні кумедні/сезонні підзаголовки. - - `"default"`: фіксований нейтральний підзаголовок (`All your chats, one OpenClaw.`). - - `"off"`: без тексту підзаголовка (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише підзаголовки), установіть змінну середовища `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): змінні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`). + - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), встановіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записують керовані CLI потоки налаштування (`onboard`, `configure`, `doctor`): +Метадані, які записують потоки покрокового налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3564,15 +3568,15 @@ openclaw gateway --port 19001 --- -## Ідентичність +## Identity -Див. поля ідентичності `agents.list` у розділі [Типові значення агентів](#agent-defaults). +Див. поля identity в `agents.list` у розділі [Типові значення агента](#agent-defaults). --- ## Bridge (застарілий, вилучений) -Поточні збірки більше не містять TCP bridge. Вузли підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Вузли підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -3601,8 +3605,8 @@ openclaw gateway --port 19001 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // застарілий резервний варіант для збережених завдань із notify:true - webhookToken: "replace-with-dedicated-token", // необов’язковий bearer token для вихідної webhook-автентифікації + webhook: "https://example.invalid/legacy", // застарілий резервний варіант для збережених завдань notify:true + webhookToken: "replace-with-dedicated-token", // необов’язковий bearer token для вихідної webhook auth sessionRetention: "24h", // рядок тривалості або false runLog: { maxBytes: "2mb", // типово 2_000_000 байтів @@ -3612,11 +3616,11 @@ openclaw gateway --port 19001 } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сеанси cron-запусків перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених cron-стенограм. Типове значення: `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`. +- `sessionRetention`: як довго зберігати завершені сеанси ізольованих запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених стенограм cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються під час очищення журналу запуску. Типове значення: `2000`. +- `webhookToken`: bearer token, який використовується для доставлення cron webhook через POST (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. +- `webhook`: застаріла резервна URL webhook (http/https), яка використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -3634,9 +3638,9 @@ openclaw gateway --port 19001 - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів. +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових cron-завдань. Для повторюваних завдань використовується окрема обробка помилок. +Застосовується лише до одноразових cron jobs. Повторювані jobs використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -3654,11 +3658,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: увімкнути сповіщення про збої для cron-завдань (типово: `false`). +- `enabled`: увімкнути сповіщення про збої для cron jobs (типово: `false`). - `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). -- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST на налаштований webhook. -- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщення. +- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для тієї самої job. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження області доставки сповіщення. ### `cron.failureDestination` @@ -3675,16 +3679,16 @@ openclaw gateway --port 19001 } ``` -- Типове місце призначення для сповіщень про збої cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо цільових даних. +- Типова ціль для сповіщень про збої cron для всіх jobs. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. - `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. -- Коли не задано ані глобальне, ані для окремого завдання місце призначення збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної announce-цілі. -- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. +- `delivery.failureDestination` для конкретної job перевизначає це глобальне типове значення. +- Коли не задано ні глобальної, ні специфічної для job цілі збою, jobs, які вже доставляють через `announce`, у разі збою резервно використовують цю основну announce-ціль. +- `delivery.failureDestination` підтримується лише для jobs із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` job не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). --- @@ -3692,28 +3696,28 @@ openclaw gateway --port 19001 Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Текст без групових згадок | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор отримувача | -| `{{MessageSid}}` | Ідентифікатор повідомлення каналу | -| `{{SessionId}}` | UUID поточного сеансу | -| `{{IsNewSession}}` | `"true"`, коли створено новий сеанс | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіостенограма | -| `{{Prompt}}` | Визначений медіа-запит для записів CLI | -| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}` | Назва групи (best effort) | -| `{{GroupMembers}}` | Попередній список учасників групи (best effort) | -| `{{SenderName}}` | Ім’я відображення відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | +| Змінна | Опис | +| ----------------- | --------------------------------------------------- | +| `{{Body}}` | Повне тіло вхідного повідомлення | +| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | +| `{{BodyStripped}}`| Тіло без згадок у групі | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | ID повідомлення каналу | +| `{{SessionId}}` | UUID поточного сеансу | +| `{{IsNewSession}}`| `"true"`, коли створено новий сеанс | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Стенограма аудіо | +| `{{Prompt}}` | Визначений media prompt для записів CLI | +| `{{MaxChars}}` | Визначений максимум вихідних символів для записів CLI | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}`| Назва групи (best effort) | +| `{{GroupMembers}}`| Попередній список учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| `{{Provider}}` | Підказка постачальника (whatsapp, telegram, discord тощо) | --- @@ -3734,13 +3738,13 @@ openclaw gateway --port 19001 **Поведінка злиття:** -- Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається в заданому порядку (пізніші перевизначають попередні). +- Один файл: замінює об’єкт, у якому міститься. +- Масив файлів: глибоко зливається по порядку (пізніші перевизначають раніші). - Сусідні ключі: зливаються після включень (перевизначають включені значення). - Вкладені включення: до 10 рівнів глибини. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цього обмеження. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних включень. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли вони все одно визначаються в межах цієї границі. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних включень. --- -_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ diff --git a/docs/uk/reference/rich-output-protocol.md b/docs/uk/reference/rich-output-protocol.md new file mode 100644 index 000000000..1f9f69198 --- /dev/null +++ b/docs/uk/reference/rich-output-protocol.md @@ -0,0 +1,60 @@ +--- +x-i18n: + generated_at: "2026-04-11T12:34:12Z" + model: gpt-5.4 + provider: openai + source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035 + source_path: reference/rich-output-protocol.md + workflow: 15 +--- + +# Протокол розширеного виводу + +Відповідь помічника може містити невеликий набір директив доставки/рендерингу: + +- `MEDIA:` для доставки вкладень +- `[[audio_as_voice]]` для підказок щодо аудіоподання +- `[[reply_to_current]]` / `[[reply_to:]]` для метаданих відповіді +- `[embed ...]` для розширеного рендерингу в Control UI + +Ці директиви є окремими. `MEDIA:` і теги відповіді/голосу залишаються метаданими доставки; `[embed ...]` — це веб-орієнтований шлях розширеного рендерингу. + +## `[embed ...]` + +`[embed ...]` — це єдиний агентський синтаксис розширеного рендерингу для Control UI. + +Приклад самозакривного тега: + +```text +[embed ref="cv_123" title="Status" /] +``` + +Правила: + +- `[view ...]` більше не є чинним для нового виводу. +- Шорткоди embed рендеряться лише на поверхні повідомлень помічника. +- Рендеряться лише embed-елементи, прив’язані до URL. Використовуйте `ref="..."` або `url="..."`. +- Шорткоди embed у формі блоку з вбудованим HTML не рендеряться. +- Вебінтерфейс прибирає шорткод із видимого тексту та рендерить embed вбудовано. +- `MEDIA:` не є псевдонімом embed і не має використовуватися для розширеного рендерингу. + +## Збережена форма рендерингу + +Нормалізований/збережений блок вмісту відповіді помічника — це структурований елемент `canvas`: + +```json +{ + "type": "canvas", + "preview": { + "kind": "canvas", + "surface": "assistant_message", + "render": "url", + "viewId": "cv_123", + "url": "/__openclaw__/canvas/documents/cv_123/index.html", + "title": "Status", + "preferredHeight": 320 + } +} +``` + +Збережені/відрендерені розширені блоки безпосередньо використовують цю форму `canvas`. `present_view` не розпізнається.