From ee3ff8537874baf97394ab0e2324e0d8b5dfb4bc Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 21 Apr 2026 21:51:31 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/configuration-reference.md | 1446 ++++++++++---------- docs/uk/gateway/configuration.md | 347 ++--- docs/uk/gateway/security/index.md | 1214 ++++++++-------- 3 files changed, 1507 insertions(+), 1500 deletions(-) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index f71700842..f54dd3794 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник з конфігурації +summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник із конфігурації x-i18n: - generated_at: "2026-04-21T20:52:32Z" + generated_at: "2026-04-21T21:40:52Z" model: gpt-5.4 provider: openai - source_hash: ee1fc48831793d8e751ae86cff414faa36290a86d7bf64ac3e5d8eade2ec8a44 + source_hash: 0313f47079536b93385b4e9c7680a896098ac05dce4e368d389a33e31b4649ac source_path: gateway/configuration-reference.md workflow: 15 --- -# Довідник з конфігурації +# Довідник із конфігурації -Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). +Довідник із базової конфігурації для `~/.openclaw/openclaw.json`. Для огляду за сценаріями див. [Configuration](/uk/gateway/configuration). -На цій сторінці описано основні поверхні конфігурації OpenClaw і наведено посилання назовні, коли підсистема має власний детальніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр memory/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, якщо підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та UI керування, з об’єднаними метаданими bundled/Plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з областю дії шляху для інструментів деталізації -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc на відповідність поточній поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із вбудованими метаданими plugin/каналів, об’єднаними за наявності +- `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` -- [Slash Commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки каналу/Plugin-власника для поверхонь команд, специфічних для каналу +- [Довідник із конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` +- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + комплектного каталогу команд +- сторінки відповідного каналу/Plugin для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволено коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі + коми в кінці). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). +Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`). ### Доступ до DM і груп -Усі канали підтримують політики DM і політики груп: +Усі канали підтримують політики DM і групові політики: -| Політика DM | Поведінка | -| ------------------- | -------------------------------------------------------------- | +| Політика DM | Поведінка | +| ------------------- | ---------------------------------------------------------------- | | `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має підтвердити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища paired allow) | -| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| `allowlist` | Лише відправники в `allowFrom` (або у спареному сховищі дозволів) | +| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні DM | -| Політика груп | Поведінка | +| Групова політика | Поведінка | | --------------------- | ------------------------------------------------------ | | `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених груп (контроль згадок усе ще застосовується) | +| `open` | Обійти списки дозволених груп (фільтрація за згадуванням усе ще застосовується) | | `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. -Коди сполучення закінчують дію через 1 годину. Очікувальні запити на сполучення DM обмежено **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає типове значення, якщо `groupPolicy` провайдера не встановлено. +Коди сполучення спливають через 1 годину. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**. +Якщо блок провайдера відсутній повністю (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. ### Перевизначення моделі для каналу -Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, установленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `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 працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через web-канал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. ```json5 { @@ -164,9 +164,9 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований ID облікового запису (відсортований). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. -- Застарілий каталог авторизації Baileys для одного облікового запису мігрується командою `openclaw doctor` до `whatsapp/default`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (після сортування). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується `openclaw doctor` у `whatsapp/default`. - Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (типово: off; вмикайте явно, щоб уникнути обмежень rate limit для редагування прев’ю) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,12 +225,12 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. -- У багатооблікових конфігураціях (2+ ID облікових записів) установіть явний обліковий запис за замовчуванням (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення некоректне. -- `configWrites: false` блокує запис конфігурації, ініційований через Telegram (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередні перегляди потоків Telegram використовують `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символічні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- У багатооблікових конфігураціях (2+ ID облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо він відсутній або некоректний. +- `configWrites: false` блокує ініційовані з Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). +- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Прев’ю потоку в Telegram використовують `sendMessage` + `editMessageText` (працює в прямих і групових чатах). - Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). ### Discord @@ -286,7 +286,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress відповідає partial у Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in для sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -333,34 +333,34 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням. -- Прямі вихідні виклики, що надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. +- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. - Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються. -- Slug guild — у нижньому регістрі, де пробіли замінено на `-`; ключі каналів використовують slug-ім’я (без `#`). Перевагу слід надавати ID guild. +- 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 для авто-unfocus через бездіяльність у годинах (`0` вимикає) +- `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`: перемикач opt-in для автоматичного створення/прив’язки тредів `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і тредів (використовуйте id каналу/треду в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). + - `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 components v2. - `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). -- OpenClaw додатково намагається відновити прийом голосу, виходячи з голосової сесії та повторно приєднуючись до неї після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві значення `streaming` мігруються автоматично. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` наскрізно передаються в параметри DAVE `@discordjs/voice` (`true` і `24` типово). +- OpenClaw також намагається відновити прийом голосу, виходячи та повторно входячи в голосову сесію після повторних збоїв дешифрування. +- `channels.discord.streaming` — це канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` мігруються автоматично. - `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінними іменами/тегами (режим сумісності break-glass). -- `channels.discord.execApprovals`: доставка схвалень exec у стилі Discord і авторизація тих, хто може схвалювати. - - `enabled`: `true`, `false` або `"auto"` (типово). В auto-режимі схвалення exec активуються, коли тих, хто може схвалювати, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено схвалювати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, схвалення передаватимуться для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). - - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в DM тим, хто може схвалювати, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target містить `"channel"`, кнопки можуть використовувати лише визначені користувачі, які можуть схвалювати. - - `cleanupAfterResolve`: коли `true`, видаляє DM зі схваленням після схвалення, відхилення або тайм-ауту. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними ім’ям/тегом (режим сумісності break-glass). +- `channels.discord.execApprovals`: нативна для Discord доставка підтверджень exec і авторизація тих, хто підтверджує. + - `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` для всіх повідомлень). @@ -393,11 +393,11 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- JSON service account: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). -- Також підтримується SecretRef service account (`serviceAccountRef`). -- Резервні значення середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). +- Також підтримується SecretRef облікового запису служби (`serviceAccountRef`). +- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Використовуйте `spaces/` або `users/` для цілей доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінним email principal (режим сумісності break-glass). +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). ### Slack @@ -449,7 +449,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // use Slack native streaming API when mode=partial + nativeTransport: true, // використовувати нативний API потокової передачі Slack, коли mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,35 +464,35 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта середовища облікового запису за замовчуванням). -- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або на рівні облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті +- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта змінних середовища типового облікового запису). +- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для кожного облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають текстові рядки або об’єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/стану для кожних облікових даних, такі як - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, +- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як + `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef, але поточний шлях команди/runtime не зміг визначити значення секрету. -- `configWrites: false` блокує записи конфігурації, ініційовані через Slack. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. -- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потоків Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. +- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- `channels.slack.streaming.mode` — це канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потокової передачі Slack. Застарілі значення `streamMode`, булеві `streaming` і `nativeStreaming` мігруються автоматично. - Використовуйте `user:` (DM) або `channel:` для цілей доставки. -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій тредів:** `thread.historyScope` — на рівні треду (типово) або спільно для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові треди. +**Ізоляція сесій гілок:** `thread.historyScope` є для кожної гілки окремо (типово) або спільним для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки. -- Нативний потоковий режим Slack разом зі статусом треду Slack у стилі assistant "is typing..." потребують ціль відповіді-треду. Верхньорівневі DM типово залишаються поза тредом, тому замість попереднього перегляду в стилі треду вони використовують `typingReaction` або звичайну доставку. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: доставка схвалень exec у стилі Slack і авторизація тих, хто може схвалювати. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Нативна потокова передача Slack разом зі статусом гілки Slack у стилі помічника «is typing...» вимагають ціль відповіді у гілці. DM верхнього рівня типово залишаються поза гілкою, тому вони використовують `typingReaction` або звичайну доставку замість прев’ю у стилі гілки. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: нативна для Slack доставка підтверджень exec і авторизація тих, хто підтверджує. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ----------- | -------- | ------------------------ | -| reactions | увімкнено | Реакції + список реакцій | +| Група дій | Типово | Примітки | +| ----------- | ------- | ----------------------- | +| reactions | увімкнено | Реагування + список реакцій | | messages | увімкнено | Читання/надсилання/редагування/видалення | | pins | увімкнено | Закріпити/відкріпити/список | | memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список власних emoji | +| emojiList | увімкнено | Список власних емодзі | ### Mattermost @@ -516,7 +516,7 @@ Mattermost постачається як Plugin: `openclaw plugins install @open native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // Необов’язкова явна URL-адреса для розгортань із reverse proxy/публічним доступом callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +526,23 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на згадку @, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). +Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). -Коли нативні команди Mattermost увімкнені: +Коли нативні команди Mattermost увімкнено: -- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL. +- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. - `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути досяжним із сервера Mattermost. - Нативні зворотні виклики slash-команд автентифікуються токенами для кожної команди, які Mattermost повертає - під час реєстрації slash-команди. Якщо реєстрація не вдалася або жодну - команду не активовано, OpenClaw відхиляє зворотні виклики з повідомленням + під час реєстрації slash-команд. Якщо реєстрація не вдається або жодні + команди не активовані, OpenClaw відхиляє зворотні виклики з помилкою `Unauthorized: invalid command token.` - Для приватних/tailnet/internal хостів зворотних викликів Mattermost може вимагати, - щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. - Використовуйте значення хоста/домену, а не повні URL. -- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані через Mattermost. + щоб `ServiceSettings.AllowedUntrustedInternalConnections` включав хост/домен зворотного виклику. + Використовуйте значення хоста/домену, а не повні URL-адреси. +- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення контролю згадок для каналу (`"*"` для значення за замовчуванням). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення фільтрації за згадуванням для конкретного каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. ### Signal @@ -551,7 +551,7 @@ Mattermost постачається як Plugin: `openclaw plugins install @open channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // необов’язкова прив’язка облікового запису dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -563,11 +563,11 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані через Signal. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. +- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. ### BlueBubbles @@ -580,15 +580,15 @@ BlueBubbles — рекомендований шлях для iMessage (на ос enabled: true, dmPolicy: "pairing", // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // див. /channels/bluebubbles }, }, } ``` -- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сесій ACP. Використовуйте рядок handle або target BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- Елементи верхнього рівня `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,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. - Потрібен Full Disk Access до БД Messages. -- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб отримати список чатів. +- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. - `cliPath` може вказувати на SSH-обгортку; установіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ relay-хоста вже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані через iMessage. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- SCP використовує сувору перевірку host key, тому переконайтеся, що ключ relay-host уже існує в `~/.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). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix підтримується розширенням і налаштовується в `channels.matrix`. +Matrix працює через Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -669,24 +669,24 @@ Matrix підтримується розширенням і налаштовує ``` - Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити це через `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і цей opt-in мережі є незалежними керуваннями. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і цей opt-in для мережі — незалежні елементи керування. - `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у багатооблікових конфігураціях. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення у стилі 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.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення в стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` разом із `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: нативна для Matrix доставка підтверджень exec і авторизація тих, хто підтверджує. + - `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 і живі пошуки в каталозі використовують ту саму політику проксі, що й трафік runtime. -- Повну конфігурацію Matrix, правила адресації та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). +- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільне за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і живі запити до каталогу використовують ту саму політику проксі, що й runtime-трафік. +- Повну конфігурацію Matrix, правила націлювання й приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams підтримується розширенням і налаштовується в `channels.msteams`. +Microsoft Teams працює через Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -695,18 +695,18 @@ Microsoft Teams підтримується розширенням і налаш enabled: true, configWrites: true, // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // див. /channels/msteams }, }, } ``` -- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення на рівні команди/каналу) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC підтримується розширенням і налаштовується в `channels.irc`. +IRC працює через Plugin і налаштовується в `channels.irc`. ```json5 { @@ -727,9 +727,9 @@ IRC підтримується розширенням і налаштовуєт } ``` -- Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ID облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/контроль згадок) задокументовано в [IRC](/uk/channels/irc). +- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- Повну конфігурацію IRC-каналу (host/port/TLS/канали/списки дозволених/фільтрація за згадуванням) задокументовано в [IRC](/uk/channels/irc). ### Багатообліковість (усі канали) @@ -755,27 +755,27 @@ IRC підтримується розширенням і налаштовуєт ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени середовища застосовуються лише до облікового запису **default**. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено на рівні облікового запису. +- Токени змінних середовища застосовуються лише до облікового запису **default**. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для конкретного облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або під час онбордингу каналу), залишаючись у топ-рівневій конфігурації каналу для одного облікового запису, OpenClaw спочатку підвищує top-level значення для одного облікового запису, прив’язані до цього облікового запису, до мапи облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. -- Наявні прив’язки лише до каналу (без `accountId`) продовжують відповідати обліковому запису default; прив’язки на рівні облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення top-level для одного облікового запису, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або onboarding каналу), залишаючись у конфігурації каналу верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переносить їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише до каналу (без `accountId`) і далі зіставляються з типовим обліковим записом; прив’язки з прив’язкою до облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи верхньорівневі значення для одного облікового запису, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовує `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -### Інші канали розширень +### Інші канали Plugin -Багато каналів розширень налаштовуються як `channels.` і задокументовані на їхніх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів Plugin налаштовуються як `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. -**Типи згадок:** +**Типи згадувань:** -- **Згадки в метаданих**: Нативні згадки @ платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: Безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечні вкладені повторення ігноруються. -- Контроль згадок застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Згадування в метаданих**: нативні @-згадування платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечне вкладене повторення ігноруються. +- Фільтрація за згадуванням застосовується лише тоді, коли виявлення можливе (нативні згадування або принаймні один шаблон). ```json5 { @@ -788,7 +788,7 @@ IRC підтримується розширенням і налаштовуєт } ``` -`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або на рівні облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або на рівні облікового запису). Установіть `0`, щоб вимкнути. #### Обмеження історії DM @@ -805,13 +805,13 @@ IRC підтримується розширенням і налаштовуєт } ``` -Порядок визначення: перевизначення для окремого DM → значення за замовчуванням провайдера → без обмеження (зберігається все). +Розв’язання: перевизначення для конкретного DM → типове значення провайдера → без обмеження (зберігається все). -Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте свій власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні згадки @, відповідає лише на текстові шаблони): +Додайте свій власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадування, відповідає лише на текстові шаблони): ```json5 { @@ -832,21 +832,21 @@ IRC підтримується розширенням і налаштовуєт } ``` -### Команди (обробка команд у чаті) +### Команди (обробка команд чату) ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // реєструвати нативні команди, коли це підтримується + nativeSkills: "auto", // реєструвати нативні команди Skills, коли це підтримується + text: true, // розбирати /commands у повідомленнях чату + bash: false, // дозволити ! (псевдонім: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // дозволити /config + mcp: false, // дозволити /mcp + plugins: false, // дозволити /plugins + debug: false, // дозволити /debug + restart: true, // дозволити /restart + інструмент перезапуску gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -859,44 +859,44 @@ IRC підтримується розширенням і налаштовуєт } ``` - + -- Цей блок налаштовує поверхні команд. Для поточного вбудованого + bundled каталогу команд див. [Slash Commands](/uk/tools/slash-commands). -- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовано на сторінках їхніх каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands). +- Цей блок налаштовує поверхні команд. Для поточного каталогу вбудованих + комплектних команд див. [Слеш-команди](/uk/tools/slash-commands). +- Ця сторінка — це **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках їхніх каналів/Plugin, а також у [Слеш-команди](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. -- `native: "auto"` вмикає нативні команди для Discord/Telegram, а для Slack залишає їх вимкненими. -- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, а для Slack залишає їх вимкненими. +- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. +- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. - Перевизначення для каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначайте реєстрацію нативних команд Skills для каналу через `channels..commands.nativeSkills`. -- `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. -- `bash: true` вмикає `! ` для shell хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів Gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; `/config show` лише для читання залишається доступним для звичайних клієнтів operator з правом запису. -- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення Plugin, встановлення та керування ввімкненням/вимкненням. -- `channels..configWrites` контролює мутації конфігурації для кожного каналу (типово: true). -- Для багатооблікових каналів `channels..accounts..configWrites` також контролює записи, націлені на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). -- `restart: false` вимикає `/restart` і дії інструмента перезапуску Gateway. Типово: `true`. -- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. -- `ownerDisplay: "hash"` хешує ID власників у system prompt. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених для каналу/сполучення та `useAccessGroups` ігноруються). +- Перевизначуйте реєстрацію нативних команд Skills для каналу через `channels..commands.nativeSkills`. +- `channels.telegram.customCommands` додає додаткові пункти меню бота Telegram. +- `bash: true` вмикає `! ` для shell хоста. Потребує `tools.elevated.enabled` і щоб відправник був у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; лише для читання `/config show` лишається доступним для звичайних клієнтів operator із правами запису. +- `mcp: true` вмикає `/mcp` для конфігурації MCP-серверів, якими керує OpenClaw, у `mcp.servers`. +- `plugins: true` вмикає `/plugins` для пошуку Plugin, встановлення та керування ввімкненням/вимкненням. +- `channels..configWrites` керує змінами конфігурації для кожного каналу (типово: true). +- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. Типово: `true`. +- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`. +- `ownerDisplay: "hash"` гешує ID власників у системному prompt. Установіть `ownerDisplaySecret`, щоб керувати гешуванням. +- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених каналу/сполучення і `useAccessGroups` ігноруються). - `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено. - Карта документації команд: - - вбудований + bundled каталог: [Slash Commands](/uk/tools/slash-commands) + - вбудований + комплектний каталог: [Слеш-команди](/uk/tools/slash-commands) - поверхні команд, специфічні для каналу: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - команди сполучення: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - memory dreaming: [Dreaming](/uk/concepts/dreaming) + - Dreaming для memory: [Dreaming](/uk/concepts/dreaming) --- -## Типові значення агента +## Типові значення агентів ### `agents.defaults.workspace` -Типово: `~/.openclaw/workspace`. +Типове значення: `~/.openclaw/workspace`. ```json5 { @@ -906,7 +906,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що відображається в рядку Runtime system prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від workspace. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись вгору від workspace. ```json5 { @@ -916,7 +916,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.skills` -Необов’язковий список дозволених Skills за замовчуванням для агентів, які не задають +Необов’язковий типовий список дозволених Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -932,9 +932,9 @@ IRC підтримується розширенням і налаштовуєт } ``` -- Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. +- Пропустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills. - Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не мати Skills. +- Установіть `agents.list[].skills: []`, щоб не використовувати Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -950,9 +950,9 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли workspace вбудовуються в system prompt. Типово: `"always"`. +Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. Типово: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction однаково перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. ```json5 { @@ -972,7 +972,7 @@ IRC підтримується розширенням і налаштовуєт ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються в усі bootstrap-файли workspace. Типово: `60000`. +Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типово: `60000`. ```json5 { @@ -985,9 +985,9 @@ IRC підтримується розширенням і налаштовуєт Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. Типово: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в system prompt. -- `"once"`: вбудовувати попередження один раз для кожної унікальної сигнатури обрізання (рекомендовано). -- `"always"`: вбудовувати попередження під час кожного запуску, коли є обрізання. +- `"off"`: ніколи не вставляти текст попередження в системний prompt. +- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: вставляти попередження на кожному запуску, коли є обрізання. ```json5 { @@ -995,26 +995,26 @@ IRC підтримується розширенням і налаштовуєт } ``` -### Карта власності бюджетів контексту +### Карта відповідальності за бюджет контексту -OpenClaw має кілька великих бюджетів prompt/контексту, і вони -навмисно розділені за підсистемами, а не проходять через один загальний -параметр. +OpenClaw має кілька високонавантажених бюджетів prompt/контексту, і вони +навмисно розділені за підсистемами, а не проходять через один універсальний +перемикач. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне вбудовування bootstrap workspace. + звичайна вставка bootstrap workspace. - `agents.defaults.startupContext.*`: - одноразовий стартовий прелюд `/new` і `/reset`, включно з нещодавніми - файлами `memory/*.md` за день. + одноразова стартова преамбула для `/new` і `/reset`, включно з останніми щоденними + файлами `memory/*.md`. - `skills.limits.*`: - компактний список Skills, вбудований у system prompt. + компактний список Skills, що вставляється в системний prompt. - `agents.defaults.contextLimits.*`: - обмежені уривки runtime і вбудовані блоки, що належать runtime. + обмежені витяги runtime та вставлені блоки, що належать runtime. - `memory.qmd.limits.*`: - індексовані уривки пошуку в пам’яті та розміри вбудовування. + розмір фрагментів індексованого пошуку пам’яті та їх вставки. -Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший +Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1022,7 +1022,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `agents.defaults.startupContext` -Керує стартовим прелюдом першого ходу, що вбудовується у звичайні запуски `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, що вставляється в запусках із порожнім `/new` і `/reset`. ```json5 { @@ -1060,18 +1060,18 @@ OpenClaw має кілька великих бюджетів prompt/контек } ``` -- `memoryGetMaxChars`: типове обмеження уривка `memory_get` перед додаванням - метаданих обрізання та повідомлення про продовження. +- `memoryGetMaxChars`: типове обмеження витягу `memory_get` перед додаванням + метаданих обрізання і повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` пропущено. - `toolResultMaxChars`: поточне обмеження результатів інструментів, що використовується для збережених результатів і відновлення при переповненні. -- `postCompactionMaxChars`: обмеження уривка AGENTS.md, що використовується під час вбудовування +- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час вставки оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення для конкретного агента для спільних перемикачів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -1098,8 +1098,8 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, вбудованого в system prompt. Це -не впливає на читання файлів `SKILL.md` за потреби. +Глобальне обмеження для компактного списку Skills, що вставляється в системний prompt. Це +не впливає на читання файлів `SKILL.md` на вимогу. ```json5 { @@ -1113,7 +1113,7 @@ OpenClaw має кілька великих бюджетів prompt/контек #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету prompt Skills. +Перевизначення для конкретного агента для бюджету prompt Skills. ```json5 { @@ -1132,11 +1132,11 @@ OpenClaw має кілька великих бюджетів prompt/контек ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшого боку зображення в блоках зображень transcript/tool перед викликами провайдера. +Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. Типово: `1200`. -Нижчі значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту для запусків із великою кількістю скриншотів. -Вищі значення зберігають більше візуальних деталей. +Менші значення зазвичай зменшують використання vision-token і розмір payload запиту в сценаріях із великою кількістю скриншотів. +Більші значення зберігають більше візуальних деталей. ```json5 { @@ -1146,7 +1146,7 @@ OpenClaw має кілька великих бюджетів prompt/контек ### `agents.defaults.userTimezone` -Часовий пояс для контексту system prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного prompt (не для часових позначок повідомлень). Якщо не встановлено, використовується часовий пояс хоста. ```json5 { @@ -1156,7 +1156,7 @@ OpenClaw має кілька великих бюджетів prompt/контек ### `agents.defaults.timeFormat` -Формат часу в system prompt. Типово: `auto` (налаштування ОС). +Формат часу в системному prompt. Типово: `auto` (налаштування ОС). ```json5 { @@ -1194,7 +1194,7 @@ OpenClaw має кілька великих бюджетів prompt/контек primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1214,48 +1214,48 @@ OpenClaw має кілька великих бюджетів prompt/контек ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс упорядковані моделі failover. + - Рядкова форма задає лише основну модель. + - Форма об’єкта задає основну модель плюс упорядковані резервні моделі для failover. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як його конфігурація vision-model. + - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/Plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну авторизацію/API key провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо пропущено, `image_generate` усе одно може вивести типове значення провайдера з авторизацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо пропущено, `music_generate` усе одно може вивести типове значення провайдера з авторизацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики у порядку provider-id. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну авторизацію/API key провайдера. + - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо пропущено, `video_generate` усе одно може вивести типове значення провайдера з авторизацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео у порядку provider-id. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну авторизацію/API key провайдера. - - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо поле пропущено, `video_generate` усе одно може визначити типове значення провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. + - Комплектний провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо пропущено, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сесії/типової моделі. + - Використовується інструментом `pdf` для маршрутизації моделей. + - Якщо поле пропущено, інструмент PDF використовує резервно `imageModel`, а потім визначену модель сесії/типову модель. - `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються режимом резервного витягування в інструменті `pdf`. +- `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 спочатку пробує псевдонім, потім унікальний збіг exact model id серед налаштованих провайдерів і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model, замість того щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг серед налаштованих провайдерів для точного id моделі, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (config): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (відповідний agent id) перевизначає за ключем. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). -- `embeddedHarness`: типова низькорівнева політика runtime для вбудованого агента. Використовуйте `runtime: "auto"`, щоб зареєстровані harness Plugin могли брати підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. -- Конфігураційні writers, що змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізована). Типово: 4. +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). +- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness Plugin перехоплювати підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. +- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних моделей. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled -app-server harness Codex. +У більшості розгортань варто залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте його, коли довірений Plugin надає нативний harness, наприклад комплектний +harness app-server Codex. ```json5 { @@ -1271,13 +1271,13 @@ app-server harness Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Bundled Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резерв сумісності. `"none"` призводить до помилки, якщо вибір harness Plugin відсутній або не підтримується, замість тихого використання 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. +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Комплектний Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант. `"none"` змушує помилково завершувати вибір відсутнього або непідтримуваного harness Plugin замість тихого використання PI. +- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. +- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим harness чату. Генерація медіа, vision, PDF, музика, відео і TTS все одно використовують свої налаштування provider/model. -**Скорочення вбудованих псевдонімів** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення псевдонімів** (застосовуються лише коли модель є в `agents.defaults.models`): | Псевдонім | Модель | | ------------------- | -------------------------------------- | @@ -1292,13 +1292,13 @@ app-server harness Codex. Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x thinking mode вмикається автоматично, якщо ви не встановите `--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 { @@ -1326,13 +1326,13 @@ app-server harness Codex. } ``` -- Бекенди CLI орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли задано `sessionArg`. -- Передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. +- Сесії підтримуються, коли встановлено `sessionArg`. +- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь system prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt. +Замінює весь системний prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt. ```json5 { @@ -1353,16 +1353,16 @@ app-server harness Codex. agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + 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 (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (типово) | block + target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1373,14 +1373,14 @@ app-server harness Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація через API-key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли false, прибирає розділ Heartbeat із system prompt і пропускає вбудовування `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-файлів workspace. -- `isolatedSession`: коли true, кожен запуск Heartbeat виконується у свіжій сесії без попередньої історії розмови. Та сама схема ізоляції, що й для Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].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` @@ -1395,15 +1395,15 @@ app-server harness Codex. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Зберігайте deployment ID, ticket ID і пари host:port точно без змін.", // used when identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Сесія наближається до Compaction. Збережіть тривалі спогади зараз.", - prompt: "Запишіть усі довготривалі нотатки в memory/YYYY-MM-DD.md; дайте точну безмовну відповідь токеном NO_REPLY, якщо зберігати нічого.", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1411,19 +1411,19 @@ app-server harness Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування шматками для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого provider Plugin для Compaction. Якщо встановлено, викликається `summarize()` цього провайдера замість вбудованого LLM-підсумовування. У разі помилки повертається до вбудованого. Установлення provider примусово задає `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 починається і коли завершується (наприклад, "Виконується Compaction контексту..." і "Compaction завершено"). Типово вимкнено, щоб Compaction залишався безшумним. -- `memoryFlush`: безшумний агентний хід перед авто-Compaction для збереження довготривалих спогадів. Пропускається, коли workspace доступний лише для читання. +- `mode`: `default` або `safeguard` (узагальнення частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо встановлено, замість вбудованого узагальнення LLM викликається `summarize()` цього провайдера. У разі помилки використовується вбудований варіант. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, перш ніж OpenClaw її перерве. Типово: `900`. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів на початку узагальнення під час Compaction. +- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які потрібно повторно вставити після Compaction. Типово: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторну вставку. Якщо поле не задано або явно задано цю типову пару, як застарілий резервний варіант також приймаються старіші заголовки `Every Session`/`Safety`. +- `model`: необов’язкове перевизначення `provider/model-id` лише для узагальнення Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а узагальнення Compaction — виконуватися на іншій; якщо не задано, Compaction використовує основну модель сесії. +- `notifyUser`: коли `true`, надсилає користувачеві короткі сповіщення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction відбувався безшумно. +- `memoryFlush`: тихий агентний хід перед авто-Compaction для збереження тривалих спогадів. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням у LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1437,7 +1437,7 @@ app-server harness Codex. hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Вміст старого результату інструмента очищено]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1448,24 +1448,24 @@ app-server harness Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує надто великі результати інструментів, а потім, за потреби, жорстко очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Жорстке очищення** замінює весь результат інструмента плейсхолдером. +**Повне очищення** замінює весь результат інструмента плейсхолдером. Примітки: -- Блоки зображень ніколи не обрізаються і не очищаються. -- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. -- Якщо повідомлень assistant менше, ніж `keepLastAssistants`, обрізання пропускається. +- Блоки зображень ніколи не обрізаються й не очищаються. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. +- Якщо є менше ніж `keepLastAssistants` повідомлень помічника, обрізання пропускається. -Докладніше про поведінку див. [Session Pruning](/uk/concepts/session-pruning). +Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). -### Блокове потокове передавання +### Блокова потокова передача ```json5 { @@ -1481,13 +1481,13 @@ app-server harness Codex. } ``` -- Канали, крім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти на рівні облікового запису). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, потрібно явно вказати `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для кожного облікового запису). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для конкретного агента: `agents.list[].humanDelay`. -Докладніше про поведінку та chunking див. [Streaming](/uk/concepts/streaming). +Деталі поведінки та розбиття на частини див. у [Streaming](/uk/concepts/streaming). -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -1500,7 +1500,7 @@ app-server harness Codex. } ``` -- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. +- Типові значення: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадування. - Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Typing Indicators](/uk/concepts/typing-indicators). @@ -1509,7 +1509,7 @@ app-server harness Codex. ### `agents.defaults.sandbox` -Необов’язкове ізолювання для вбудованого агента. Повний посібник див. в [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1604,7 +1604,7 @@ app-server harness Codex. } ``` - + **Бекенд:** @@ -1612,43 +1612,43 @@ app-server harness Codex. - `ssh`: загальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в `plugins.entries.openshell.config`. -**Конфігурація SSH backend:** +**Конфігурація SSH-бекенда:** -- `target`: SSH-ціль у форматі `user@host[:port]` +- `target`: SSH-ціль у формі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за scope -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує в тимчасові файли під час runtime -- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за кожною областю +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час runtime +- `strictHostKeyChecking` / `updateHostKeys`: перемикачі політики host key в OpenSSH -**Пріоритет SSH auth:** +**Пріоритет SSH-автентифікації:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку sandbox-сесії +- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів перед запуском sandbox-сесії -**Поведінка SSH backend:** +**Поведінка SSH-бекенда:** -- один раз ініціалізує віддалений workspace після створення або повторного створення -- потім зберігає віддалений SSH workspace як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH -- не синхронізує віддалені зміни назад до хоста автоматично -- не підтримує браузерні контейнери sandbox +- один раз ініціалізує віддалений workspace після створення або перевідтворення +- потім зберігає віддалений SSH-workspace як канонічний +- маршрутизує `exec`, файлові інструменти та медіашляхи через SSH +- не синхронізує віддалені зміни назад на хост автоматично +- не підтримує browser-контейнери sandbox **Доступ до workspace:** -- `none`: workspace sandbox за scope у `~/.openclaw/sandboxes` -- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` +- `none`: workspace sandbox за кожною областю в `~/.openclaw/sandboxes` +- `ro`: workspace sandbox у `/workspace`, workspace агента монтується тільки для читання в `/agent` - `rw`: workspace агента монтується для читання/запису в `/workspace` -**Scope:** +**Область:** -- `session`: контейнер + workspace на сесію -- `agent`: один контейнер + workspace на агента (типово) +- `session`: контейнер + workspace для кожної сесії +- `agent`: один контейнер + workspace для кожного агента (типово) - `shared`: спільний контейнер і workspace (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -1679,30 +1679,30 @@ app-server harness Codex. **Режим OpenShell:** -- `mirror`: перед `exec` ініціалізує віддалений стан із локального, після `exec` синхронізує назад; локальний workspace залишається канонічним -- `remote`: один раз ініціалізує віддалений стан під час створення sandbox, потім віддалений workspace залишається канонічним +- `mirror`: ініціалізує віддалене середовище з локального перед exec, синхронізує назад після exec; локальний workspace лишається канонічним +- `remote`: ініціалізує віддалене середовище один раз під час створення sandbox, після чого канонічним лишається віддалений workspace -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою sync у режимі mirror. +У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, автоматично не синхронізуються в sandbox після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але Plugin володіє життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, root, доступного для запису, і користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореня з можливістю запису та користувача root. -**Контейнери типово використовують `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. `"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). **Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні монтування та монтування для окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для конкретного агента об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в system prompt. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача через noVNC типово використовує VNC auth, а OpenClaw видає URL із короткоживучим токеном (замість показу пароля у спільному URL). +**Browser у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. noVNC URL вставляється в системний 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 на browser хоста. +- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. +- `cdpSourceRange` необов’язково обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser у sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера browser. +- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для хостів із контейнерами: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1721,26 +1721,26 @@ app-server harness Codex. - `--metrics-recording-only` - `--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` знову вмикає розширення, якщо ваш workflow залежить від них. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - - плюс `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення — це базова лінія образу контейнера; щоб змінити типові значення контейнера, використовуйте власний - образ браузера з власним entrypoint. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. + - Типові значення є базовими для образу контейнера; використовуйте власний образ browser із власною + entrypoint, щоб змінити типові значення контейнера. -Ізолювання браузера та `sandbox.docker.binds` доступні лише для Docker. +Ізоляція browser і `sandbox.docker.binds` підтримуються лише для Docker. Зберіть образи: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-browser-setup.sh # необов’язковий образ browser ``` ### `agents.list` (перевизначення для окремого агента) @@ -1793,20 +1793,20 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: стабільний id агента (обов’язково). -- `default`: якщо встановлено для кількох, перший має пріоритет (записується попередження). Якщо не встановлено ніде, типовим є перший запис списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-завдання, які перевизначають лише `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 | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення на рівні повідомлення або сесії. -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning на рівні повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast-mode на рівні повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення низькорівневої політики harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, поки інші агенти зберігають типовий fallback PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент повинен типово використовувати ACP harness-сесії. +- `default`: якщо встановлено для кількох, перемагає перший (записується попередження). Якщо не встановлено ні для кого, типовим є перший елемент списку. +- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку для конкретного агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для конкретного агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо його задано; явний список замінює типові значення, а не зливається з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для конкретного агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `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`), коли агент має типово використовувати сесії harness ACP. - `identity.avatar`: шлях відносно workspace, `http(s)` URL або `data:` URI. -- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` з `name`/`emoji`. - `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які виконувалися б без sandbox. -- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, які пропускають `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, які не вказують `agentId` (примушує до явного вибору профілю; типово: false). --- @@ -1829,27 +1829,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля відповідності прив’язки +### Поля зіставлення прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній type типово означає route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних ACP-прив’язок розмов. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = обліковий запис за замовчуванням) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) -- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (необов’язково; лише для елементів `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок відповідності:** +**Детермінований порядок зіставлення:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (точний, без peer/guild/team) -5. `match.accountId: "*"` (на весь канал) -6. Агент за замовчуванням +4. `match.accountId` (точний збіг, без peer/guild/team) +5. `match.accountId: "*"` (на рівні всього каналу) +6. Типовий агент У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки route. +Для елементів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route-прив’язок. ### Профілі доступу для окремого агента @@ -1900,7 +1900,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1946,7 +1946,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -Докладніше про пріоритети див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Докладно про пріоритетність див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- @@ -1997,7 +1997,7 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. @@ -2005,29 +2005,29 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`dmScope`**: як групуються DM. - `main`: усі DM спільно використовують основну сесію. - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для вхідних скриньок багатьох користувачів). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості). -- **`identityLinks`**: зіставляє канонічні id з peer, префіксованими провайдером, для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає той, що спливає раніше. + - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для вхідних скриньок із кількома користувачами). + - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для багатообліковості). +- **`identityLinks`**: зіставляє канонічні id з peer-ідентифікаторами з префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, перемагає той, що спливає раніше. - **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії треду (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає свіжу сесію треду замість успадкування історії стенограми батьківської сесії. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії гілки (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію гілки замість успадкування історії стенограми батьківської сесії. - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика direct-chat. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обмінів agent-to-agent (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжки. -- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: керування очищенням сховища сесій і зберіганням. +- **`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`). - `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`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. +- **`threadBindings`**: глобальні типові значення для функцій сесій із прив’язкою до гілок. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове авто-unfocus через бездіяльність у годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типове жорстке максимальне значення віку в годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типове жорстке обмеження максимального віку в годинах (`0` вимикає; провайдери можуть перевизначати) @@ -2065,36 +2065,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення на рівні каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення (найбільш специфічне має пріоритет): обліковий запис → канал → глобально. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Порядок визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. -**Шаблонні змінні:** +**Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | +| `{identity.name}` | Ім’я ідентичності агента | (те саме, що `"auto"`) | Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. ### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення на рівні каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. -- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: прибирає підтвердження після відповіді у Slack, Discord і Telegram. +- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення ідентичності. +- Область: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: прибирає підтвердження після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо значення не встановлено, реакції статусу залишаються увімкненими, коли активні реакції підтвердження. - У Telegram явно встановіть `true`, щоб увімкнути реакції статусу життєвого циклу. + У Slack і Discord, якщо не задано, реакції статусу лишаються ввімкненими, коли активні реакції підтвердження. + У Telegram установіть це поле явно в `true`, щоб увімкнути реакції статусу життєвого циклу. -### Вхідний debounce +### Дебаунс вхідних повідомлень -Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. +Об’єднує швидку послідовність текстових повідомлень від одного й того ж відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування оминають дебаунс. ### TTS (text-to-speech) @@ -2137,12 +2137,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. +- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. - `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. - `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in). -- API-ключі використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: config, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw розглядає його як OpenAI-сумісний TTS-сервер і послаблює перевірку model/voice. +- 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-сервер і послаблює валідацію model/voice. --- @@ -2172,13 +2172,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. - Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. -- Для Voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key для Talk не налаштовано. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача, перш ніж надсилати транскрипт. Якщо не встановлено, зберігається типове вікно паузи платформи (`700 ms` на macOS і Android, `900 ms` на iOS). +- Voice ID використовують резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk. +- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. +- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2186,37 +2186,37 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Профілі інструментів -`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволених значень перед `tools.allow`/`tools.deny`: -Локальний онбординг типово задає для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не встановлено (наявні явні профілі зберігаються). +Локальний onboarding типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). -| Профіль | Містить | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | лише `session_status` | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (те саме, що не встановлено) | +| Профіль | Містить | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `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` | Без обмежень (те саме, що й без значення) | ### Групи інструментів -| Група | Інструменти | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation`| `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без provider Plugin) | +| Група | Інструменти | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group: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` | Усі вбудовані інструменти (без провайдерських Plugin) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнений. ```json5 { @@ -2242,7 +2242,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує elevated-доступом до `exec` поза sandbox: +Керує доступом elevated exec поза sandbox: ```json5 { @@ -2258,9 +2258,9 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. +- Перевизначення для конкретного агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). +- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово, або `node`, коли ціль exec — `node`). ### `tools.exec` @@ -2285,7 +2285,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для конкретного агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2306,13 +2306,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `historySize`: максимальна історія викликів інструментів, яка зберігається для аналізу циклів. - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. +- `criticalThreshold`: вищий поріг повторень для блокування критичних циклів. +- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого виконання без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати для відомих poll-інструментів (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати для чергування шаблонів пар без прогресу. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати шаблони чергування пар без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2395,16 +2395,16 @@ scripts/sandbox-browser-setup.sh # optional browser image **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилок використовується наступний запис. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для конкретного запису. +- У разі помилки використовується наступний запис. -Авторизація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. +Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. -**Поля async completion:** +**Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставляти безпосередньо в канал. Типово: `false` - (застарілий шлях пробудження requester-session / доставки моделі). + і `video_generate` спочатку намагаються доставити результат прямо в канал. Типово: `false` + (застарілий шлях пробудження requester-session/доставки через модель). @@ -2423,9 +2423,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -Керує тим, на які сесії можна націлюватися інструментами сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можна націлюватися через інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). -Типово: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). +Типово: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). ```json5 { @@ -2441,10 +2441,10 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `self`: лише ключ поточної сесії. -- `tree`: поточна сесія + сесії, породжені поточною сесією (subagents). +- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). - `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` @@ -2469,15 +2469,15 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. -- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` із `.manifest.json`. -- Вміст вкладень автоматично редагується з persistence стенограми. -- Вхідні дані base64 перевіряються суворою перевіркою алфавіту/відступів і захистом розміру до декодування. -- Права файлів: `0700` для каталогів і `0600` для файлів. -- Очищення виконується за політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. +- Файли матеріалізуються в дочірньому workspace в `.openclaw/attachments//` із `.manifest.json`. +- Вміст вкладень автоматично редагується під час збереження стенограми. +- Входи Base64 перевіряються суворою перевіркою алфавіту/відступів і захистом розміру до декодування. +- Права доступу до файлів: `0700` для каталогів і `0600` для файлів. +- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапорці експериментальних вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. +Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не спрацьовує правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -2491,9 +2491,9 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатоетапної роботи. -- Типово: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. -- Коли інструмент увімкнено, system prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й утримувала не більш як один крок у стані `in_progress`. +- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. +- Типово: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для конкретного агента) не встановлено в `"strict-agentic"` для запуску сімейства GPT-5 від OpenAI або OpenAI Codex. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб лишити його вимкненим навіть для strict-agentic запусків GPT-5. +- Коли ввімкнено, системний prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`. ### `agents.defaults.subagents` @@ -2513,16 +2513,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: типова модель для породжених sub-agents. Якщо пропущено, sub-agents успадковують модель викликача. +- `model`: типова модель для створених субагентів. Якщо пропущено, субагенти успадковують модель викликача. - `allowAgents`: типовий список дозволених id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. +- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## Власні провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у config або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2551,42 +2551,42 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для власних потреб авторизації. -- Перевизначайте корінь config агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). -- Пріоритет злиття для однакових id провайдерів: - - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет. - - Непорожні значення `apiKey` з агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` для провайдерів під керуванням SecretRef оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження визначених секретів. - - Значення заголовків провайдера під керуванням SecretRef оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). - - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у config. - - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явним config і неявними значеннями каталогу. - - Для однакових моделей `contextTokens` зберігає явне runtime-обмеження, якщо воно є; використовуйте його, щоб обмежити ефективний контекст без зміни рідних метаданих моделі. - - Використовуйте `models.mode: "replace"`, коли хочете, щоб config повністю переписав `models.json`. - - Збереження маркерів керується джерелом: маркери записуються з активного знімка source config (до визначення), а не з визначених значень секретів runtime. +- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. +- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). +- Пріоритет злиття для однакових ID провайдерів: + - Непорожні значення `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. -### Деталі полів провайдера +### Докладно про поля провайдера - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: мапа власних провайдерів з ключем за id провайдера. +- `models.providers`: карта власних провайдерів, де ключем є id провайдера. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/підстановку env). -- `models.providers.*.auth`: стратегія авторизації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовує `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.apiKey`: облікові дані провайдера (рекомендується SecretRef/підстановка через env). +- `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL API upstream. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. - - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії авторизації. Режими: `"provider-default"` (використовувати вбудовану авторизацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). +- `models.providers.*.baseUrl`: базова URL-адреса API upstream. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації проксі/tenant. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. + - `request.headers`: додаткові заголовки (зливаються з типовими заголовками провайдера). Значення приймають SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - `request.proxy`: перевизначення HTTP-проксі. Режими: `"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 або подібні діапазони, через захист fetch SSRF провайдера HTTP (opt-in оператора для довірених self-hosted endpoint, сумісних з OpenAI). WebSocket використовує той самий `request` для заголовків/TLS, але не цей захист fetch SSRF. Типово `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (opt-in оператора для довірених self-hosted OpenAI-сумісних endpoint). 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` (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`: корінь налаштувань авто-виявлення Bedrock. +- `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`: кореневий розділ налаштувань авто-виявлення Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. @@ -2630,7 +2630,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. @@ -2667,7 +2667,7 @@ OpenClaw використовує вбудований каталог модел Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` -- Coding endpoint (типово): `https://api.z.ai/api/coding/paas/v4` +- Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` - Для загального endpoint визначте власного провайдера з перевизначенням base URL. @@ -2709,9 +2709,9 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot оголошують сумісність використання потокового передавання на спільному +Нативні endpoint Moonshot заявляють сумісність зі streaming на спільному транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, -а не лише до id вбудованого провайдера. +а не лише до вбудованого id провайдера. @@ -2729,7 +2729,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Anthropic-сумісний, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2768,11 +2768,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2811,8 +2811,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й Установіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. -Каталог моделей типово містить лише M2.7. -На шляху потокового передавання, сумісному з Anthropic, OpenClaw типово вимикає thinking MiniMax, +Каталог моделей типово обмежується лише M2.7. +На Anthropic-сумісному streaming-шляху OpenClaw типово вимикає thinking MiniMax, якщо ви явно не встановите `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2821,7 +2821,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted-моделі об’єднаними для резервного переходу. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; для резервного варіанта залишайте злитими розміщені моделі. @@ -2852,18 +2852,18 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (керовані Skills/workspace Skills не зачіпаються). -- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). +- `allowBundled`: необов’язковий список дозволених лише для комплектних skills (керовані/workspace skills це не зачіпає). +- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). - `install.preferBrew`: коли true, надавати перевагу встановлювачам Homebrew, якщо `brew` доступний, перш ніж переходити до інших типів встановлювачів. -- `install.nodeManager`: пріоритет node-встановлювача для специфікацій `metadata.openclaw.install` +- `install.nodeManager`: пріоритетний node-менеджер для специфікацій встановлення `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: зручне поле для Skills, які оголошують основну env-змінну (відкритий рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він комплектний/встановлений. +- `entries..apiKey`: зручне поле для skills, які оголошують основну env-змінну (текстовий рядок або об’єкт SecretRef). --- -## Plugins +## Plugin ```json5 { @@ -2887,41 +2887,41 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні бандли Codex і Claude, включно з бандлами Claude стандартної структури без manifest. -- **Зміни config потребують перезапуску Gateway.** +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. +- Виявлення приймає нативні Plugin OpenClaw, а також сумісні комплекти Codex і Claude, включно з комплектами Claude стандартного макета без manifest. +- **Зміни конфігурації потребують перезапуску gateway.** - `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет. - `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: мапа env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook Plugin і до підтримуваних каталогів hook, наданих бандлами. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли ви свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт config, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, коли вона доступна). +- `plugins.entries..env`: карта env-змінних у межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля зі зміною prompt від застарілого `before_agent_start`, зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих комплектами. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових субагентів. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна). - `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). + - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервно `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. + - `baseUrl`: базова URL-адреса API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). + - `timeoutSeconds`: тайм-аут scrape-запиту в секундах (типово: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Фази й пороги див. у [Dreaming](/uk/concepts/dreaming). - - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: Cron-інтервал для кожного повного проходу dreaming (типово `"0 3 * * *"`). - - політика фаз і пороги — це деталі реалізації (не ключі config для користувача). -- Повна конфігурація memory міститься в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config): + - `model`: модель Grok, яку слід використовувати для пошуку (наприклад `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: налаштування memory Dreaming. Фази й пороги див. у [Dreaming](/uk/concepts/dreaming). + - `enabled`: головний перемикач Dreaming (типово `false`). + - `frequency`: Cron-ритм для кожного повного проходу Dreaming (типово `"0 3 * * *"`). + - політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації). +- Повна конфігурація memory міститься в [Довідник із конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені бандл-Plugin Claude також можуть додавати типові значення embedded Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі config OpenClaw. +- Увімкнені Plugin-комплекти Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. - `plugins.slots.memory`: вибрати id активного Plugin memory або `"none"`, щоб вимкнути Plugin memory. -- `plugins.slots.contextEngine`: вибрати id активного Plugin context engine; типово `"legacy"`, якщо ви не встановите й не виберете інший engine. -- `plugins.installs`: метадані встановлення, керовані CLI, які використовує `openclaw plugins update`. - - Містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI, а не ручним редагуванням. +- `plugins.slots.contextEngine`: вибрати id активного Plugin context engine; типово `"legacy"`, якщо ви не встановите та не виберете інший engine. +- `plugins.installs`: метадані встановлення, якими керує CLI і які використовуються `openclaw plugins update`. + - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI, а не ручному редагуванню. Див. [Plugins](/uk/tools/plugin). @@ -2964,26 +2964,26 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не встановлено, тому навігація Browser типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації Browser у приватній мережі. -- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок досяжності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як legacy-псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` у невстановленому стані вимкнено, тому навігація browser типово лишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. +- У суворому режимі віддалені endpoint профілів CDP (`profiles.*.cdpUrl`) підлягають такому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` усе ще підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). +- Віддалені профілі підтримують лише під’єднання (запуск/зупинка/скидання вимкнені). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає вам прямий DevTools WebSocket URL. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), + коли ваш провайдер дає вам пряму URL-адресу DevTools WebSocket. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть під’єднуватися на вибраному хості або через підключений browser Node. - Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний - профіль браузера на базі Chromium, наприклад Brave або Edge. + профіль browser на базі Chromium, як-от Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії через snapshot/ref замість націлювання за CSS-selector, хуки завантаження одного файла, - без перевизначення тайм-ауту діалогів, без `wait --load networkidle`, а також без + дії на основі snapshot/ref замість націлювання CSS-селекторами, hooks завантаження одного файла, + без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. -- Локально керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно +- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок авто-виявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Порядок автовиявлення: browser за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Служба керування: лише local loopback (порт визначається з `gateway.port`, типово `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад `--disable-gpu`, розмір вікна або прапорці налагодження). @@ -3004,8 +3004,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `seamColor`: колір акценту для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення identity для UI керування. Якщо не задано, використовується identity активного агента. +- `seamColor`: колір акценту для chrome нативного UI застосунку (тон бульбашки Talk Mode тощо). +- `assistant`: перевизначення ідентичності Control UI. Використовує резервно ідентичність активного агента. --- @@ -3072,66 +3072,66 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` - + - `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. -- `port`: один мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `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`), а не псевдоніми 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 або identity-aware reverse proxy з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, коли налаштовано обидва значення, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених конфігурацій local loopback; цей варіант навмисно не пропонується у підказках онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з awareness до identity і довіряє заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **джерело proxy не на loopback**; reverse proxy того самого хоста на loopback не задовольняють вимог trusted-proxy auth. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для UI керування/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint **не** використовують цю auth через заголовки Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокенний потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожного IP клієнта і для кожної області auth (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху UI керування Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово `true`; установіть `false`, коли свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих proxy-розгортань). -- Спроби auth до WS з походженням browser завжди обмежуються без винятку для loopback (додатковий захист від browser-based brute force для localhost). -- На loopback ці блокування для browser-origin ізольовано для кожного нормалізованого значення `Origin`, - тому повторні невдалі спроби з одного localhost origin не блокують автоматично +- **Застарілі псевдоніми 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`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Non-loopback bind потребує auth gateway. На практиці це означає спільний token/password або reverse proxy з підтримкою identity-aware із `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. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в підказках onboarding. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy із підтримкою identity-aware і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело проксі; reverse proxy loopback на тому ж хості не задовольняють trusted-proxy auth. +- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint **не** використовують цю auth через заголовки Tailscale; вони дотримуються звичайного HTTP auth mode gateway. Цей потік без token припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітер невдалих спроб auth. Застосовується для кожної IP-адреси клієнта і для кожної області auth (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для однакового `{scope, clientIp}` серіалізуються перед записом невдачі. Тому паралельні хибні спроби від одного клієнта можуть спровокувати лімітер на другому запиті, замість того щоб обидві одночасно пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово `true`; установіть `false`, коли ви свідомо хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих розгортань із проксі). +- Спроби browser-origin WS auth завжди throttled із вимкненим винятком для loopback (додатковий захист від браузерного brute force на localhost). +- На loopback ці блокування для browser-origin ізольовані для кожного нормалізованого значення `Origin`, + тому повторні невдачі з одного localhost origin не блокують автоматично інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потрібна auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для WebSocket-підключень Gateway. Обов’язковий, коли очікуються browser-клієнти з origin не на loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin за заголовком Host для розгортань, що свідомо покладаються на політику origin за Host-header. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення на боці клієнта, що дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово незашифровані з’єднання залишаються дозволеними лише для loopback. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли browser-клієнти очікуються з non-loopback origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для розгортань, що свідомо покладаються на політику origin за заголовком Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське break-glass перевизначення, яке дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово plaintext лишається дозволеним лише для loopback. - `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовують офіційні/TestFlight-збірки iOS після публікації в gateway реєстрацій на основі relay. Цей URL має збігатися з URL relay, скомпільованим у збірці iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. -- Реєстрації на основі relay делегуються конкретній identity gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю identity до реєстрації relay і пересилає в gateway дозвіл на надсилання, прив’язаний до реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеного вище config relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback HTTP relay URL. URL relay у production мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал монітора здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора здоров’я. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора здоров’я на канал/обліковий запис за ковзну годину. Типово: `10`. -- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків монітора здоров’я, при цьому глобальний монітор залишається увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для багатооблікових каналів. Якщо задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не встановлено. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і вони не визначені, визначення завершується fail-closed (без маскування резервним remote). -- `trustedProxies`: IP reverse proxy, які завершують TLS або додають forwarded-client headers. Перелічуйте лише ті proxy, які ви контролюєте. Записи loopback усе ще валідні для конфігурацій proxy того самого хоста/локального виявлення (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed у gateway. Ця URL-адреса має збігатися з URL relay, скомпільованою в збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типово `10000`. +- Реєстрації relay-backed делегуються конкретній 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`: лише для розробки, аварійний дозвіл на loopback HTTP relay URL. У production URL relay мають лишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора здоров’я. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора здоров’я для каналу/облікового запису за ковзну годину. Типово: `10`. +- `channels..healthMonitor.enabled`: відмова для окремого каналу від перезапусків монітора здоров’я, залишаючи глобальний монітор увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не визначено, визначення завершується fail-closed (без маскування через резервний remote fallback). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Перелічуйте лише проксі, які ви контролюєте. Записи loopback усе ще дійсні для конфігурацій проксі на тому ж хості/локального виявлення (наприклад 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.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). +- `gateway.tools.allow`: вилучає назви інструментів із типового HTTP-списку заборон. -### Endpoint, сумісні з OpenAI +### OpenAI-сумісні endpoint -- Chat Completions: типово вимкнені. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилення захисту URL-входу Responses: +- Захист URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlist вважаються невстановленими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посилення захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні списки дозволених трактуються як відсутні; використовуйте `gateway.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 на одному хості з унікальними портами й каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3160,10 +3160,10 @@ openclaw gateway --port 19001 ``` - `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях файлової системи до файла сертифіката TLS. -- `keyPath`: шлях файлової системи до приватного ключа TLS; обмежуйте дозволи на нього. -- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або власних ланцюжків довіри. +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовані; лише для локального/dev використання. +- `certPath`: шлях у файловій системі до файла TLS-сертифіката. +- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежте доступ правами. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або власних ланцюгів довіри. ### `gateway.reload` @@ -3179,13 +3179,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: керує тим, як зміни config застосовуються під час runtime. - - `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску. - - `"restart"`: завжди перезапускати процес gateway при зміні config. +- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. + - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. -- `debounceMs`: вікно debounce в мс перед застосуванням змін config (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). + - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно — переходити до restart. +- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3223,7 +3223,7 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook у query-string відхиляються. +Hook-токени в query string відхиляються. Примітки щодо валідації та безпеки: @@ -3231,38 +3231,38 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонізований `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping цього opt-in не потребують. +- Якщо mapping або preset використовує шаблонізований `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. **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`). + - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані через шаблон, вважаються наданими ззовні й також потребують `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо переданими і також потребують `hooks.allowRequestSessionKey=true`. - + -- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`). -- `match.source` відповідає полю корисного навантаження для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читаються з корисного навантаження. +- `match.path` зіставляється з підшляхом після `/hooks` (наприклад `/hooks/gmail` → `gmail`). +- `match.source` зіставляється з полем payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. - `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити все, `[]` = заборонити все). + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID використовують резервно типового агента. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). - `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і sessionKey у mapping на основі шаблонів задавати `sessionKey` (типово: `false`). +- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і session key у mapping, керованих шаблонами, встановлювати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо каталог моделей задано). +- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо налаштовано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого значення. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. ```json5 { @@ -3285,12 +3285,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- -## Canvas host +## Хост canvas ```json5 { @@ -3302,22 +3302,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Обслуговує HTML/CSS/JS, що редагуються агентом, і A2UI через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Для bind не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після сполучення й підключення Node Gateway оголошує URL можливостей із областю дії Node для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії Node і швидко спливають. Резервний варіант на основі IP не використовується. -- Вбудовує клієнт live-reload в HTML, що обслуговується. -- Автоматично створює початковий `index.html`, коли каталог порожній. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для non-loopback bind: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- WebView Node зазвичай не надсилають заголовки auth; після сполучення та підключення node Gateway оголошує URL можливостей, прив’язані до node, для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Вставляє клієнт live-reload у HTML, що обслуговується. +- Автоматично створює початковий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. -- Вимикайте live reload для великих каталогів або при помилках `EMFILE`. +- Вимкніть live reload для великих каталогів або при помилках `EMFILE`. --- -## Discovery +## Виявлення ### mDNS (Bonjour) @@ -3345,7 +3345,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує unicast DNS-SD zone у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. +Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -3370,14 +3370,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в env процесу немає цього ключа. -- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній цей ключ. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). +- Повний порядок пріоритету див. у [Environment](/uk/help/environment). ### Підстановка env-змінних -Посилайтеся на env-змінні в будь-якому рядку config через `${VAR_NAME}`: +Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3387,8 +3387,8 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. -- Відсутні/порожні змінні спричиняють помилку під час завантаження config. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Відсутні/порожні змінні викликають помилку під час завантаження конфігурації. - Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. @@ -3396,7 +3396,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Секрети -Посилання на секрети є адитивними: відкриті значення все ще працюють. +Посилання на секрети є додатковими: текстові значення також продовжують працювати. ### `SecretRef` @@ -3412,13 +3412,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` `id`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється) +- `id` для `source: "exec"` не повинні містити сегментів шляху `.` або `..`, розділених `/` (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включені до визначення під час runtime та до покриття audit. +- Посилання з `auth-profiles.json` включені у визначення під час runtime і покриття аудиту. ### Конфігурація провайдерів секретів @@ -3451,12 +3451,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: - Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). -- Провайдер `exec` потребує абсолютний шлях `command` і використовує корисні навантаження протоколу через stdin/stdout. -- Типово шляхи команд-символьних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символьні посилання з перевіркою шляху до визначеної цілі. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі. +- Провайдер `exec` потребує абсолютного шляху в `command` і використовує протокольні payload через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink, перевіряючи шлях до визначеної цілі. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до шляху визначеної цілі. - Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети визначаються під час активації в знімок у пам’яті, а потім шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях спричиняють помилку запуску/reload, тоді як неактивні поверхні пропускаються з діагностикою. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, а далі шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -3481,8 +3481,8 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - Профілі для окремого агента зберігаються в `/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`. +- Статичні runtime-облікові дані беруться з визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищуються при виявленні. +- Застарілий імпорт OAuth із `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). - Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). @@ -3507,21 +3507,19 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - billing/insufficient-credit помилки (типово: `5`). Явний текст про billing - усе ще може потрапити сюди навіть для відповідей `401`/`403`, але - matcher-и тексту, специфічні для провайдера, залишаються в межах провайдера, - якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані `402` для вікна використання або - повідомлення про ліміт витрат organization/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 того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми provider-busy, такі як `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою перевантаженого провайдера/ротації профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). До цього кошика rate-limit входить текст у стилі провайдерів, такий як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. + billing/insufficient-credit помилки (типово: `5`). Явний текст billing може + потрапити сюди навіть при відповідях `401`/`403`, але текстові + зіставлювачі для конкретних провайдерів лишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або + organization/workspace spend-limit натомість лишаються в гілці `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих провайдерів. +- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для high-confidence збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `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`. --- @@ -3542,8 +3540,8 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` з `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 МБ). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -3580,20 +3578,20 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: головний перемикач для виводу інструментації (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикає цільовий вивід журналу (підтримує шаблони з `*`, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг давності в мс для виведення попереджень про завислу сесію, поки сесія залишається у стані обробки. +- `enabled`: головний перемикач для виводу інструментування (типово: `true`). +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує шаблони з `*`, наприклад `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія лишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. - `otel.serviceName`: назва сервісу для атрибутів ресурсу. -- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або log. -- `otel.sampleRate`: частота семплювання trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного flush telemetry у мс. -- `cacheTrace.enabled`: журналювати знімки trace кешу для embedded-запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усі типово: `true`). +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. +- `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.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усе типово: `true`). --- @@ -3617,10 +3615,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `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`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу stable-каналу в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). --- @@ -3654,21 +3652,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. -- `backend`: id типового backend runtime ACP (має відповідати зареєстрованому ACP runtime Plugin). -- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явної цілі. -- `allowedAgents`: список дозволених id агентів для сесій runtime ACP; порожній список означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. +- `dispatch.enabled`: незалежний gate для dispatch ходів ACP-сесій (типово: `true`). Установіть `false`, щоб лишити ACP-команди доступними, але блокувати виконання. +- `backend`: id типового runtime-бекенда ACP (має відповідати зареєстрованому ACP runtime Plugin). +- `defaultAgent`: резервний id цільового агента ACP, коли spawns не задають явну ціль. +- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткового обмеження. +- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. +- `stream.coalesceIdleMs`: вікно скидання idle у мс для потокового тексту. - `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів на хід (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах одного ходу (типово: `true`). +- `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу assistant, що проєктується на один хід ACP. +- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один ACP-хід. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис, що зіставляє імена тегів з булевими перевизначеннями видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до моменту, коли вони підлягають очищенню. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP. +- `stream.tagVisibility`: запис назв тегів у зіставленні з булевими перевизначеннями видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів ACP-сесій до моменту, коли вони стають придатними до очищення. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP. --- @@ -3684,17 +3682,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `cli.banner.taglineMode` керує стилем tagline банера: - - `"random"` (типово): змінні кумедні/сезонні tagline. - - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). - - `"off"`: без тексту tagline (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише tagline), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана banner: + - `"random"` (типово): ротаційні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). + - `"off"`: без тексту слогана (заголовок/версія banner усе одно показуються). +- Щоб приховати весь banner (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записують потоки покрокового налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, які записуються потоками покрокового налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3712,15 +3710,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Identity -Див. поля identity в `agents.list` у розділі [Типові значення агента](#agent-defaults). +Див. поля identity у `agents.list` у розділі [Типові значення агентів](#agent-defaults). --- -## Bridge (legacy, вилучено) +## Bridge (застарілий, вилучений) -Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми config (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не включають TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -3758,11 +3756,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед обрізанням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типово: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/.jsonl`) перед обрізанням. Типово: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, що зберігаються, коли спрацьовує обрізання run-log. Типово: `2000`. -- `webhookToken`: bearer token, який використовується для доставки POST до webhook у Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. -- `webhook`: застарілий legacy fallback 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, що використовується для доставки webhook POST у Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. +- `webhook`: застаріла legacy fallback URL-адреса webhook (http/https), що використовується лише для збережених завдань, у яких досі встановлено `notify: true`. ### `cron.retry` @@ -3780,9 +3778,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `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. Повторювані завдання мають окрему обробку збоїв. ### `cron.failureAlert` @@ -3801,10 +3799,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). +- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST до налаштованого webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження області доставки сповіщення. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -3822,40 +3820,40 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Типова ціль для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. +- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобальну, ні окрему ціль для збоїв, завдання, які вже доставляють через `announce`, при збої повертаються до цієї основної announce-цілі. -- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` самого завдання не дорівнює `"webhook"`. +- `delivery.failureDestination` для конкретного завдання перевизначає це глобальне типове значення. +- Якщо не задано ні глобальну, ні окрему ціль збоїв, завдання, які вже доставляють через `announce`, у разі збою використовують резервно цю основну ціль announce. +- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). --- -## Шаблонні змінні моделі медіа +## Змінні шаблону моделі медіа -Плейсхолдери шаблонів, які розгортаються в `tools.media.models[].args`: +Плейсхолдери шаблону, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ----------------- | ----------------------------------------------- | | `{{Body}}` | Повний текст вхідного повідомлення | | `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Текст без згадок у групі | +| `{{BodyStripped}}`| Текст без згадувань у групі | | `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор цілі | +| `{{To}}` | Ідентифікатор одержувача | | `{{MessageSid}}` | ID повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | | `{{IsNewSession}}`| `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіотранскрипт | -| `{{Prompt}}` | Визначений prompt медіа для записів CLI | -| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | +| `{{Transcript}}` | Аудіостенограма | +| `{{Prompt}}` | Визначений media prompt для записів CLI | +| `{{MaxChars}}` | Визначена максимальна кількість вихідних символів для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Назва групи (best effort) | +| `{{GroupSubject}}`| Тема групи (best effort) | | `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | | `{{SenderName}}` | Відображуване ім’я відправника (best effort) | | `{{SenderE164}}` | Номер телефону відправника (best effort) | @@ -3863,9 +3861,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. --- -## Include config (`$include`) +## Include конфігурації (`$include`) -Розбийте config на кілька файлів: +Розбивайте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -3881,11 +3879,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка злиття:** - Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається за порядком (пізніші перевизначають раніші). +- Масив файлів: глибоко зливається по порядку (пізніші перевизначають попередні). - Сусідні ключі: зливаються після include (перевизначають включені значення). - Вкладені include: до 10 рівнів глибини. -- Шляхи: визначаються відносно файла, який виконує include, але мають залишатися всередині каталогу config верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/форми `../` дозволені лише тоді, коли вони все одно визначаються в межах цієї межі. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу й циклічних include. +- Шляхи: визначаються відносно файла, який включає, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цього кордону. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних include. --- diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index 2e5cf4ad4..57423465c 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -2,32 +2,32 @@ read_when: - Перше налаштування OpenClaw - Пошук поширених шаблонів конфігурації - - Перехід до певних розділів конфігурації + - Перехід до конкретних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-20T18:29:28Z" + generated_at: "2026-04-21T21:40:53Z" model: gpt-5.4 provider: openai - source_hash: 479e59fb8b57c5228ef1c6076cf80a4ce6064d3f6fad5f38ea9d75eeb92811dc + source_hash: c627ccf9f17087e0b71663fe3086d637aeaa8cd1d6d34d816bfcbc0f0cc6f07c source_path: gateway/configuration.md workflow: 15 --- # Конфігурація -OpenClaw зчитує необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. +OpenClaw читає необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Поширені причини додати конфігурацію: - Підключити канали та керувати тим, хто може надсилати повідомлення боту -- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, hooks) +- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks) - Налаштувати сесії, медіа, мережу або UI -Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля. +Перегляньте [повний довідник](/uk/gateway/configuration-reference) для всіх доступних полів. -**Новачок у конфігурації?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з повними конфігураціями для копіювання й вставлення. +**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання. ## Мінімальна конфігурація @@ -57,44 +57,44 @@ OpenClaw зчитує необов’язкову конфігурацію - Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**. - Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів - `title` / `description`, а також схемами Plugin і каналів, коли вони - доступні, із редактором **Raw JSON** як запасним варіантом. Для деталізованих - UI та інших інструментів gateway також надає `config.schema.lookup`, щоб - отримати один вузол схеми для певного шляху разом із підсумками безпосередніх дочірніх елементів. + Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використайте вкладку **Config**. + Control UI відображає форму на основі актуальної схеми конфігурації, включно з + метаданими документації полів `title` / `description`, а також схемами Plugin і каналів, + коли вони доступні, із редактором **Raw JSON** як запасним варіантом. Для UI + з деталізацією та інших інструментів Gateway також надає `config.schema.lookup` для + отримання одного вузла схеми, обмеженого шляхом, разом із короткими зведеннями безпосередніх дочірніх елементів. - Редагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). + Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). ## Сувора валідація -OpenClaw приймає лише конфігурації, що повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли приєднувати метадані JSON Schema. +OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на кореневому рівні — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. Примітки щодо інструментів схеми: - `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI і валідація конфігурації. -- Вважайте цей вивід схеми канонічним машиночитаним контрактом для - `openclaw.json`; цей огляд і довідник конфігурації її узагальнюють. -- Значення полів `title` і `description` переносяться у вивід схеми для - інструментів редактора та форм. -- Вкладені об’єкти, шаблонні (`*`) і елементи масивів (`[]`) успадковують ті самі - метадані документації там, де існує відповідна документація поля. -- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі - метадані документації, тож варіанти union/intersection зберігають ту саму довідку по полях. +- Вважайте цей вивід схеми канонічним машинозчитуваним контрактом для + `openclaw.json`; цей огляд і довідник конфігурації його узагальнюють. +- Значення полів `title` і `description` переносяться до виводу схеми для + редакторів і інструментів побудови форм. +- Вкладені об’єкти, шаблони (`*`) і елементи масивів (`[]`) успадковують ті самі + метадані документації там, де є відповідна документація поля. +- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані + документації, тож варіанти union/intersection зберігають однакові підказки для полів. - `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, типові межі - та подібні поля валідації), відповідні метадані підказок UI і короткі описи + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження + та подібні поля валідації), відповідними метаданими UI-підказок і короткими зведеннями безпосередніх дочірніх елементів для інструментів деталізації. - Схеми Plugin/каналів під час виконання об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розбіжності між базовими артефактами конфігурації - для документації та поточною поверхнею схеми. +- `pnpm config:docs:check` виявляє розбіжності між артефактами базової конфігурації, + видимими в документації, і поточною поверхнею схеми. Коли валідація не проходить: @@ -103,22 +103,22 @@ OpenClaw приймає лише конфігурації, що повністю - Запустіть `openclaw doctor`, щоб побачити точні проблеми - Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway також зберігає довірену останню справну копію після успішного запуску. Якщо -`openclaw.json` пізніше змінено поза OpenClaw і він більше не проходить валідацію, під час запуску -і гарячого перезавантаження пошкоджений файл зберігається як знімок `.clobbered.*` із часовою позначкою, -відновлюється остання справна копія, а в журнал записується помітне попередження з причиною відновлення. -Під час наступного ходу головного агента він також отримує попередження системної події про те, що -конфігурацію було відновлено і її не можна бездумно перезаписувати. Просування останньої справної копії -оновлюється після перевіреного запуску та після прийнятих гарячих перезавантажень, зокрема -для записів конфігурації, виконаних самим OpenClaw, якщо хеш збереженого файла все ще збігається з прийнятим -записом. Просування пропускається, коли кандидат містить відредаговані заповнювачі секретів +Gateway також зберігає довірену останню відому коректну копію після успішного запуску. Якщо +`openclaw.json` згодом буде змінено поза OpenClaw і він більше не проходитиме валідацію, під час запуску +та гарячого перезавантаження пошкоджений файл буде збережено як `.clobbered.*` зі штампом часу, +відновлено останню відому коректну копію та записано помітне попередження з причиною відновлення. +Під час наступного ходу головного агента він також отримає попередження про системну подію з повідомленням, що +конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої відомої коректної +копії відбувається після запуску з успішною валідацією і після прийнятих гарячих перезавантажень, включно з +записами конфігурації, виконаними OpenClaw, якщо хеш збереженого файлу все ще відповідає прийнятому +запису. Оновлення пропускається, якщо кандидат містить замасковані заповнювачі секретів на кшталт `***` або скорочені значення токенів. ## Поширені завдання - - Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу, щоб виконати налаштування: + + Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу для кроків налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` - [Telegram](/uk/channels/telegram) — `channels.telegram` @@ -131,7 +131,7 @@ Gateway також зберігає довірену останню справн - [iMessage](/uk/channels/imessage) — `channels.imessage` - [Mattermost](/uk/channels/mattermost) — `channels.mattermost` - Усі канали використовують однаковий шаблон політики приватних повідомлень: + Усі канали мають спільний шаблон політики приватних повідомлень: ```json5 { @@ -148,8 +148,8 @@ Gateway також зберігає довірену останню справн - - Вкажіть основну модель і необов’язкові резервні варіанти: + + Укажіть основну модель і необов’язкові резервні варіанти: ```json5 { @@ -170,28 +170,28 @@ Gateway також зберігає довірену останню справн - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням масштабу зображень у транскрипті/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю знімків екрана. - - Перегляньте [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover), щоб дізнатися про ротацію автентифікації та поведінку резервних варіантів. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. + - Див. [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації та поведінки резервних моделей. - Для користувацьких/self-hosted провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. - - Доступ до приватних повідомлень контролюється окремо для кожного каналу через `dmPolicy`: + + Доступ до приватних повідомлень керується окремо для кожного каналу через `dmPolicy`: - `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження - - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища дозволених сполучених користувачів) - - `"open"`: дозволити всі вхідні приватні повідомлення (потрібно `allowFrom: ["*"]`) + - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow) + - `"open"`: дозволити всі вхідні приватні повідомлення (потребує `allowFrom: ["*"]`) - `"disabled"`: ігнорувати всі приватні повідомлення Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. - Докладні відомості для кожного каналу див. у [повному довіднику](/uk/gateway/configuration-reference#dm-and-group-access). + Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для деталей по кожному каналу. - - Повідомлення в групах за замовчуванням **вимагають згадки**. Налаштуйте шаблони для кожного агента: + + Для повідомлень у групах типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -213,15 +213,15 @@ Gateway також зберігає довірену останню справн } ``` - - **Метадані згадок**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) + - **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) - **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns` - - Докладніше про перевизначення для кожного каналу та режим self-chat див. у [повному довіднику](/uk/gateway/configuration-reference#group-chat-mention-gating). + - Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень по каналах і режиму self-chat. - - Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте - окремих агентів через `agents.list[].skills`: + + Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте конкретних + агентів через `agents.list[].skills`: ```json5 { @@ -238,16 +238,16 @@ Gateway також зберігає довірену останню справн } ``` - - Не вказуйте `agents.defaults.skills`, якщо за замовчуванням Skills не мають бути обмежені. - - Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. - - Установіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. + - Не вказуйте `agents.defaults.skills`, щоб Skills за замовчуванням не були обмежені. + - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. + - Установіть `agents.list[].skills: []`, щоб не було жодних Skills. - Див. [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і [довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). - - Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають застарілими: + + Керуйте тим, наскільки активно gateway перезапускає канали, які виглядають застарілими: ```json5 { @@ -271,12 +271,12 @@ Gateway також зберігає довірену останню справн - Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски моніторингу стану. - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. - - Див. [Health Checks](/uk/gateway/health) для операційної діагностики та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального монітора. + - Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - + Сесії керують безперервністю розмови та ізоляцією: ```json5 @@ -298,14 +298,14 @@ Gateway також зберігає довірену останню справн ``` - `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: глобальні типові значення для маршрутизації сесій, прив’язаних до тредів (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Див. [Керування сесіями](/uk/concepts/session) для відомостей про області дії, зв’язки ідентичностей і політику надсилання. - - Усі поля див. у [повному довіднику](/uk/gateway/configuration-reference#session). + - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Див. [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання. + - Див. [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. - - Запускайте сесії агента в ізольованих runtime ізолятора: + + Запускайте сесії агента в ізольованих sandbox-середовищах виконання: ```json5 { @@ -322,14 +322,14 @@ Gateway також зберігає довірену останню справн Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing), а всі параметри — у [повному довіднику](/uk/gateway/configuration-reference#agentsdefaultssandbox). + Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. - - Push через relay налаштовується в `openclaw.json`. + + Relay-backed push налаштовується в `openclaw.json`. - Укажіть це в конфігурації gateway: + Установіть це в конфігурації gateway: ```json5 { @@ -347,7 +347,7 @@ Gateway також зберігає довірену останню справн } ``` - Еквівалент у CLI: + Еквівалент для CLI: ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com @@ -355,35 +355,35 @@ Gateway також зберігає довірену останню справн Що це робить: - - Дозволяє gateway надсилати `push.test`, сигнали пробудження і сигнали повторного підключення через зовнішній relay. - - Використовує grant на надсилання в межах реєстрації, який пересилає сполучений застосунок iOS. Gateway не потребує relay-токена рівня всього розгортання. - - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою було сполучено застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційно розповсюджених збірок, що зареєструвалися через relay. - - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. + - Дозволяє gateway надсилати `push.test`, імпульси пробудження та пробудження для повторного підключення через зовнішній relay. + - Використовує право надсилання, прив’язане до реєстрації, яке пересилає спарений застосунок iOS. Gateway не потрібен relay-токен на рівні всього розгортання. + - Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою було спарено застосунок iOS, тому інший gateway не зможе повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційно поширюваних збірок, які зареєструвалися через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до одного й того ж розгортання relay. - Наскрізний процес: + Наскрізний потік: 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. - 2. Налаштуйте `gateway.push.apns.relay.baseUrl` у gateway. - 3. Сполучіть застосунок iOS із gateway і дайте змогу підключитися як сесіям node, так і сесіям оператора. - 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay до сполученого gateway. - 5. Gateway зберігає relay handle і grant на надсилання, а потім використовує їх для `push.test`, сигналів пробудження і сигналів повторного підключення. + 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. + 3. Спарте застосунок iOS із gateway і дозвольте підключитися як сесії Node, так і сесії оператора. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` до спареного gateway. + 5. Gateway зберігає relay handle і право надсилання, а потім використовує їх для `push.test`, імпульсів пробудження та пробуджень для повторного підключення. Операційні примітки: - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. - - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свій кешований relay-реєстраційний запис замість повторного використання старого джерела relay. + - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свій кешований relay-registration замість повторного використання старого relay origin. Примітка щодо сумісності: - - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` як і раніше працюють як тимчасові перевизначення через env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається тимчасовим засобом розробки лише для loopback; не зберігайте HTTP URL relay у конфігурації. + - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` лишається винятком для розробки лише для loopback; не зберігайте HTTP URL relay у конфігурації. - Див. [застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу і [процес автентифікації та довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. + Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного потоку та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. - + ```json5 { agents: { @@ -400,11 +400,11 @@ Gateway також зберігає довірену останню справн - `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`) - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM - - Повний посібник див. у [Heartbeat](/uk/gateway/heartbeat). + - Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника. - + ```json5 { cron: { @@ -419,14 +419,14 @@ Gateway також зберігає довірену останню справн } ``` - - `sessionRetention`: видаляти завершені ізольовані сесії виконання з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). - - `runLog`: обрізати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Огляд можливостей і приклади CLI див. у [Cron jobs](/uk/automation/cron-jobs). + - `sessionRetention`: видаляти завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. - - Увімкніть HTTP-ендпоїнти Webhook у Gateway: + + Увімкніть HTTP-ендпойнти Webhook на Gateway: ```json5 { @@ -450,20 +450,20 @@ Gateway також зберігає довірену останню справн ``` Примітка щодо безпеки: - - Вважайте весь вміст payload hook/Webhook недовіреним введенням. + - Розглядайте весь вміст payload hook/Webhook як недовірений ввід. - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - - Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. - - `hooks.path` не може бути `/`; тримайте вхідний трафік Webhook на окремому підшляху, наприклад `/hooks`. - - Залишайте прапори обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які вибирає викликач. - - Для агентів, що запускаються через hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). + - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. + - `hooks.path` не може бути `/`; використовуйте для вхідних Webhook окремий підшлях, наприклад `/hooks`. + - Залишайте прапори обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо тільки не виконуєте вузькоспрямоване налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які можуть вибирати викликаючі сторони. + - Для агентів, керованих hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де це можливо). - Усі параметри мапінгу та інтеграцію Gmail див. у [повному довіднику](/uk/gateway/configuration-reference#hooks). + Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mapping і інтеграції Gmail. - - Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями: + + Запускайте кілька ізольованих агентів з окремими робочими просторами та сесіями: ```json5 { @@ -480,12 +480,12 @@ Gateway також зберігає довірену останню справн } ``` - Правила binding та профілі доступу для кожного агента див. у [Multi-Agent](/uk/concepts/multi-agent) і [повному довіднику](/uk/gateway/configuration-reference#multi-agent-routing). + Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил binding і профілів доступу для кожного агента. - - Використовуйте `$include`, щоб упорядковувати великі конфігурації: + + Використовуйте `$include` для організації великих конфігурацій: ```json5 // ~/.openclaw/openclaw.json @@ -498,40 +498,41 @@ Gateway також зберігає довірену останню справн } ``` - - **Один файл**: замінює об’єкт-контейнер - - **Масив файлів**: глибоко зливається по порядку (пізніший має пріоритет) - - **Сусідні ключі**: зливаються після include-ів (перевизначають включені значення) - - **Вкладені include-и**: підтримуються до 10 рівнів вкладеності + - **Один файл**: замінює об’єкт, у якому міститься + - **Масив файлів**: об’єднується глибоким злиттям у вказаному порядку (пізніший має пріоритет) + - **Сусідні ключі**: об’єднуються після include (перевизначають включені значення) + - **Вкладені include**: підтримуються до 10 рівнів вкладеності - **Відносні шляхи**: обчислюються відносно файла, що включає - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include-ів + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include ## Гаряче перезавантаження конфігурації -Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. +Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості параметрів ручний перезапуск не потрібен. Прямі редагування файла вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, -поки завершаться тимчасові записи/перейменування редактора, зчитує фінальний файл і відхиляє -некоректні зовнішні зміни, відновлюючи останню справну конфігурацію. Власні записи конфігурації OpenClaw -використовують той самий бар’єр схеми перед записом; руйнівні перезаписи на кшталт -видалення `gateway.mode` або зменшення файла більш ніж наполовину відхиляються +поки завершиться тимчасовий запис/перейменування файла редактором, читає фінальний файл і відхиляє +некоректні зовнішні редагування, відновлюючи останню відому коректну конфігурацію. Записи конфігурації, +виконані самим OpenClaw, проходять ту саму перевірку схемою перед записом; руйнівні перезаписи, +наприклад видалення `gateway.mode` або зменшення файла більш ніж удвічі, відхиляються і зберігаються як `.rejected.*` для перевірки. Якщо ви бачите `Config auto-restored from last-known-good` або -`config reload restored last-known-good config` у логах, перегляньте відповідний +`config reload restored last-known-good config` у логах, перевірте відповідний файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте -`openclaw config validate`. Контрольний список відновлення див. у [усуненні несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config). +`openclaw config validate`. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) +для контрольного списку відновлення. ### Режими перезавантаження | Режим | Поведінка | | ---------------------- | ---------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | -| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — ви обробляєте це самі. | -| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | -| **`off`** | Вимикає відстеження файла. Зміни набирають чинності під час наступного ручного перезапуску. | +| **`hybrid`** (типово) | Миттєво застосовує безпечні зміни. Автоматично перезапускає для критичних змін. | +| **`hot`** | Застосовує лише безпечні зміни без перезапуску. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. | +| **`restart`** | Перезапускає Gateway після будь-якої зміни конфігурації, безпечної чи ні. | +| **`off`** | Вимикає відстеження файла. Зміни набудуть чинності під час наступного ручного перезапуску. | ```json5 { @@ -541,60 +542,60 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично } ``` -### Що застосовується гаряче, а що потребує перезапуску +### Що застосовується без перезапуску, а що потребує перезапуску -Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. +Більшість полів застосовуються без перезапуску й без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. -| Категорія | Поля | Потрібен перезапуск? | -| ------------------- | -------------------------------------------------------------------- | -------------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали й канали розширень | Ні | -| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | -| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сесії та повідомлення | `session`, `messages` | Ні | -| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | -| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | -| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | -| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | +| Категорія | Поля | Потрібен перезапуск? | +| ------------------- | ----------------------------------------------------------------- | -------------------- | +| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали Plugin | Ні | +| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | +| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | +| Сесії та повідомлення | `session`, `messages` | Ні | +| Інструменти та медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | +| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | +| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | +| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` є винятками — їх зміна **не** спричиняє перезапуск. +`gateway.reload` і `gateway.remote` є винятками — їхня зміна **не** спричиняє перезапуск. ## Config RPC (програмні оновлення) -RPC керуючої площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити за 60 секунд** на `deviceId+clientIp`. У разі обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. +RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. -Безпечний/типовий процес: +Безпечний/типовий потік: -- `config.schema.lookup`: переглянути одне піддерево конфігурації з певною областю шляху з неглибоким - вузлом схеми, відповідними метаданими підказок і короткими описами безпосередніх дочірніх елементів -- `config.get`: отримати поточний знімок + хеш -- `config.patch`: рекомендований шлях часткового оновлення +- `config.schema.lookup`: переглянути одне піддерево конфігурації, обмежене шляхом, із неглибоким + вузлом схеми, відповідними метаданими підказок і короткими зведеннями безпосередніх дочірніх елементів +- `config.get`: отримати поточний snapshot + hash +- `config.patch`: бажаний шлях часткового оновлення - `config.apply`: лише повна заміна конфігурації - `update.run`: явне самооновлення + перезапуск -Якщо ви не замінюєте всю конфігурацію повністю, надавайте перевагу `config.schema.lookup`, -а потім `config.patch`. +Якщо ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup` +потім `config.patch`. - Перевіряє + записує повну конфігурацію і перезапускає Gateway за один крок. + Перевіряє + записує повну конфігурацію та перезапускає Gateway за один крок. - `config.apply` замінює **всю конфігурацію**. Для часткових оновлень використовуйте `config.patch`, а для окремих ключів — `openclaw config set`. + `config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів. Параметри: - `raw` (string) — payload JSON5 для всієї конфігурації - - `baseHash` (optional) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) - - `sessionKey` (optional) — ключ сесії для ping пробудження після перезапуску - - `note` (optional) — примітка для restart sentinel - - `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000) + - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язково, якщо конфігурація існує) + - `sessionKey` (необов’язково) — ключ сесії для ping пробудження після перезапуску + - `note` (необов’язково) — примітка для restart sentinel + - `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний період охолодження. + Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундна пауза. ```bash openclaw gateway call config.get --params '{}' # capture payload.hash @@ -608,19 +609,19 @@ RPC керуючої площини для запису (`config.apply`, `config - Зливає часткове оновлення в наявну конфігурацію (семантика JSON merge patch): + Об’єднує часткове оновлення з наявною конфігурацією (семантика JSON merge patch): - - Об’єкти зливаються рекурсивно + - Об’єкти об’єднуються рекурсивно - `null` видаляє ключ - Масиви замінюються Параметри: - - `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити - - `baseHash` (required) — хеш конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — те саме, що й у `config.apply` + - `raw` (string) — JSON5 лише з ключами, які потрібно змінити + - `baseHash` (обов’язково) — хеш конфігурації з `config.get` + - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` - Поведінка перезапуску відповідає `config.apply`: об’єднання відкладених перезапусків плюс 30-секундний період охолодження між циклами перезапуску. + Поведінка перезапуску збігається з `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундна пауза між циклами перезапуску. ```bash openclaw gateway call config.patch --params '{ @@ -634,12 +635,12 @@ RPC керуючої площини для запису (`config.apply`, `config ## Змінні середовища -OpenClaw зчитує змінні середовища з батьківського процесу, а також із: +OpenClaw читає env vars із батьківського процесу, а також із: -- `.env` у поточному робочому каталозі (якщо наявний) +- `.env` з поточного робочого каталогу (якщо є) - `~/.openclaw/.env` (глобальний резервний варіант) -Жоден із цих файлів не перевизначає вже наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: +Жоден із цих файлів не перевизначає вже наявні env vars. Ви також можете задавати вбудовані env vars у конфігурації: ```json5 { @@ -651,7 +652,7 @@ OpenClaw зчитує змінні середовища з батьківськ ``` - Якщо це ввімкнено і очікувані ключі не задані, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + Якщо ввімкнено і потрібні ключі не задані, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: ```json5 { @@ -661,11 +662,11 @@ OpenClaw зчитує змінні середовища з батьківськ } ``` -Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1` +Еквівалент env var: `OPENCLAW_LOAD_SHELL_ENV=1` - - Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: + + Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -676,16 +677,16 @@ OpenClaw зчитує змінні середовища з батьківськ Правила: -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` -- Відсутні/порожні змінні спричиняють помилку під час завантаження -- Екрануйте як `$${VAR}` для буквального виводу +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Відсутні/порожні vars спричиняють помилку під час завантаження +- Використовуйте `$${VAR}` для буквального виводу - Працює всередині файлів `$include` - Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - - Для полів, що підтримують об’єкти SecretRef, ви можете використовувати: + + Для полів, які підтримують об’єкти SecretRef, можна використовувати: ```json5 { @@ -717,15 +718,15 @@ OpenClaw зчитує змінні середовища з батьківськ } ``` -Докладно про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) див. у [Керування секретами](/uk/gateway/secrets). -Підтримувані шляхи облікових даних наведено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Подробиці щодо SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведено в [Керування секретами](/uk/gateway/secrets). +Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Повний пріоритет і джерела див. у розділі [Середовище](/uk/help/environment). +Див. [Середовище](/uk/help/environment) для повного опису пріоритетів і джерел. ## Повний довідник -Повний довідник по полях див. у **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. +Повний довідник поле за полем дивіться в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. --- diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index 76269d01e..71148c53a 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,13 +1,13 @@ --- read_when: - Додавання функцій, які розширюють доступ або автоматизацію -summary: Міркування безпеки та модель загроз для запуску AI-шлюзу з доступом до оболонки +summary: Міркування щодо безпеки та модель загроз для запуску AI-шлюзу з доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-21T20:52:27Z" + generated_at: "2026-04-21T21:40:50Z" model: gpt-5.4 provider: openai - source_hash: 1031e4ba0865f4109c92461ff6c4597928f3aeddfa7ac377a968fb1f16a642d9 + source_hash: f4cf3b71c6c22b8c0b06855de7496265d23b4e7510e339301c85b2438ed94b3b source_path: gateway/security/index.md workflow: 15 --- @@ -15,23 +15,23 @@ x-i18n: # Безпека -**Модель довіри персонального помічника:** ці рекомендації виходять із припущення про одну межу довіри оператора на один Gateway (модель одного користувача / персонального помічника). -OpenClaw **не** є ворожою багатокористувацькою межею безпеки для кількох зловмисних користувачів, які спільно використовують один agent/Gateway. -Якщо вам потрібна робота зі змішаною довірою або з користувачами-супротивниками, розділіть межі довіри (окремий Gateway + облікові дані, в ідеалі окремі користувачі ОС/хости). +**Модель довіри для персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри для одного оператора на Gateway (модель одного користувача / персонального асистента). +OpenClaw **не є** ворожою багатокористувацькою межею безпеки для кількох змагальних користувачів, які ділять один agent/Gateway. +Якщо вам потрібна робота зі змішаною довірою або змагальними користувачами, розділіть межі довіри (окремий Gateway + облікові дані, бажано також окремі користувачі ОС/хости). -**На цій сторінці:** [Модель довіри](#scope-first-personal-assistant-security-model) | [Швидкий аудит](#quick-check-openclaw-security-audit) | [Посилена базова конфігурація](#hardened-baseline-in-60-seconds) | [Модель доступу DM](#dm-access-model-pairing-allowlist-open-disabled) | [Посилення конфігурації](#configuration-hardening-examples) | [Реагування на інциденти](#incident-response) +**На цій сторінці:** [Модель довіри](#scope-first-personal-assistant-security-model) | [Швидкий аудит](#quick-check-openclaw-security-audit) | [Посилений базовий захист](#hardened-baseline-in-60-seconds) | [Модель доступу DM](#dm-access-model-pairing-allowlist-open-disabled) | [Посилення конфігурації](#configuration-hardening-examples) | [Реагування на інциденти](#incident-response) -## Спочатку про межі: модель безпеки персонального помічника +## Спочатку межі застосування: модель безпеки персонального асистента -Рекомендації з безпеки OpenClaw передбачають розгортання у режимі **персонального помічника**: одна межа довіри оператора, потенційно багато agent. +Рекомендації з безпеки OpenClaw виходять із моделі розгортання **персонального асистента**: одна межа довіри для одного оператора, потенційно багато agent. -- Підтримувана безпекова модель: один користувач/межа довіри на один Gateway (бажано один користувач ОС/хост/VPS на одну межу). -- Непідтримувана межа безпеки: один спільний Gateway/agent, який використовують взаємно недовірені або зловмисні користувачі. -- Якщо потрібна ізоляція від зловмисних користувачів, розділяйте за межами довіри (окремий Gateway + облікові дані, а в ідеалі окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть писати одному agent із доступом до інструментів, вважайте, що всі вони спільно використовують той самий делегований рівень повноважень цього agent. +- Підтримувана безпекова модель: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на межу). +- Модель, яка не підтримується як межа безпеки: один спільний Gateway/agent, яким користуються взаємно недовірені або змагальні користувачі. +- Якщо потрібна ізоляція змагальних користувачів, розділяйте за межами довіри (окремий Gateway + облікові дані, і бажано окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному agent з увімкненими інструментами, вважайте, що вони спільно використовують однакові делеговані повноваження цього agent щодо інструментів. -Ця сторінка пояснює посилення безпеки **в межах цієї моделі**. Вона не стверджує, що один спільний Gateway забезпечує ізоляцію в умовах ворожого багатокористувацького середовища. +Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ворожої багатокористувацької ізоляції на одному спільному Gateway. ## Швидка перевірка: `openclaw security audit` @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно має вузьку дію: він перемикає типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-file і використовує скидання Windows ACL замість POSIX `chmod` під час роботи в Windows. +`security audit --fix` навмисно має вузьку дію: він перемикає типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи на state/config/include-файли та використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. -Він позначає типові небезпечні конфігурації (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, розширені allowlist, дозволи файлової системи, надто м’які підтвердження exec і відкритий доступ каналів до інструментів). +Він виявляє типові небезпечні помилки конфігурації (відкритий доступ до Gateway auth, відкритий доступ до керування браузером, підвищені allowlist, дозволи файлової системи, надто ліберальні схвалення exec та відкритий доступ до інструментів через channel). -OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-model до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — усвідомлено визначити: +OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — свідомо визначити: -- хто може спілкуватися з вашим ботом -- де бот має право діяти -- до чого бот може отримати доступ +- хто може звертатися до вашого бота +- де боту дозволено діяти +- чого бот може торкатися -Починайте з мінімального доступу, який усе ще працює, а потім розширюйте його в міру зростання впевненості. +Починайте з найменшого доступу, який усе ще працює, а потім розширюйте його в міру зростання впевненості. -### Розгортання і довіра до хоста +### Розгортання та довіра до хоста -OpenClaw виходить із того, що хост і межа конфігурації є довіреними: +OpenClaw виходить із того, що межа хоста та конфігурації є довіреною: -- Якщо хтось може змінювати state/config хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте його довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/зловмисних операторів **не є рекомендованою конфігурацією**. -- Для команд зі змішаною довірою розділяйте межі довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). -- Рекомендований типовий варіант: один користувач на машину/хост (або VPS), один gateway для цього користувача і один або більше agent у цьому gateway. -- Усередині одного екземпляра Gateway автентифікований операторський доступ є довіреною роллю control plane, а не роллю орендаря на рівні окремого користувача. -- Ідентифікатори сеансів (`sessionKey`, ID сеансів, мітки) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть писати одному agent із доступом до інструментів, кожен із них може керувати тим самим набором дозволів. Ізоляція сеансів/пам’яті на рівні користувача допомагає приватності, але не перетворює спільний agent на механізм авторизації хоста для кожного користувача окремо. +- Якщо хтось може змінювати state/config хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте цю людину довіреним оператором. +- Запуск одного Gateway для кількох взаємно недовірених/змагальних операторів **не є рекомендованою конфігурацією**. +- Для команд зі змішаним рівнем довіри розділяйте межі довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). +- Рекомендована типова схема: один користувач на машину/хост (або VPS), один Gateway для цього користувача та один або кілька agent у межах цього Gateway. +- Усередині одного екземпляра Gateway доступ автентифікованого оператора — це довірена роль control plane, а не роль орендаря на рівні окремого користувача. +- Ідентифікатори сесій (`sessionKey`, session IDs, labels) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть надсилати повідомлення одному agent з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні окремого користувача допомагає приватності, але не перетворює спільний agent на авторизацію хоста для окремих користувачів. -### Спільний Slack workspace: реальний ризик +### Спільний робочий простір Slack: реальний ризик -Якщо «кожен у Slack може написати боту», основний ризик — це делеговані повноваження інструментів: +Якщо «кожен у Slack може написати боту», ключовий ризик — це делеговані повноваження щодо інструментів: -- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) у межах політики agent; -- ін’єкція prompt/вмісту від одного відправника може спричинити дії, що впливають на спільний state, пристрої або результати; -- якщо один спільний agent має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може спрямувати їх витік через використання інструментів. +- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, browser, мережеві/файлові інструменти) у межах політики agent; +- ін’єкція prompt/контенту від одного відправника може спричинити дії, що впливають на спільний state, пристрої або результати; +- якщо один спільний agent має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може спрямувати їх ексфільтрацію через використання інструментів. -Для командних сценаріїв використовуйте окремі agent/Gateway з мінімальним набором інструментів; agent із персональними даними тримайте приватними. +Для командних сценаріїв використовуйте окремі agent/Gateway з мінімальним набором інструментів; agent, що працюють з персональними даними, тримайте приватними. ### Спільний корпоративний agent: прийнятний шаблон -Це прийнятно, коли всі, хто користується цим agent, перебувають в одній межі довіри (наприклад, одна корпоративна команда), а сам agent суворо обмежений бізнес-контекстом. +Це прийнятно, коли всі, хто користується цим agent, перебувають у тій самій межі довіри (наприклад, одна команда в компанії), а agent суворо обмежений бізнес-контекстом. -- запускайте його на виділеній машині/VM/container; -- використовуйте окремого користувача ОС + окремий браузер/профіль/акаунти для цього runtime; -- не входьте в цьому runtime у персональні облікові записи Apple/Google або персональні профілі браузера/менеджера паролів. +- запускайте його на окремій машині/VM/container; +- використовуйте окремого користувача ОС + окремий browser/profile/accounts для цього runtime; +- не входьте в цьому runtime у персональні облікові записи Apple/Google або персональні профілі password manager/browser. -Якщо ви змішуєте персональні й корпоративні ідентичності в одному runtime, ви руйнуєте це розділення та підвищуєте ризик розкриття персональних даних. +Якщо ви змішуєте персональні та корпоративні ідентичності в одному runtime, ви руйнуєте розділення та збільшуєте ризик витоку персональних даних. -## Концепція довіри до Gateway і node +## Концепція довіри до Gateway і Node -Розглядайте Gateway і node як один домен довіри оператора з різними ролями: +Сприймайте Gateway і Node як одну операторську доменну область довіри з різними ролями: - **Gateway** — це control plane і поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії на пристрої, локальні для хоста можливості). -- Клієнт, автентифікований у Gateway, є довіреним у межах Gateway. Після pairing дії node вважаються довіреними операторськими діями на цьому node. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на рівні користувача. -- Підтвердження exec (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожого багатокористувацького середовища. -- Типовий варіант OpenClaw для довірених конфігурацій із одним оператором полягає в тому, що host exec на `gateway`/`node` дозволено без запитів на підтвердження (`security="full"`, `ask="off"`, якщо ви це не посилите). Цей типово встановлений UX є навмисним, а не вразливістю сам по собі. -- Підтвердження exec прив’язуються до точного контексту запиту та, за можливості, до прямих локальних файлових операндів; вони не моделюють семантично кожен шлях завантаження runtime/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Node** — це поверхня віддаленого виконання, спарена з цим Gateway (команди, дії з пристроєм, локальні для хоста можливості). +- Клієнт, автентифікований у Gateway, є довіреним у межах Gateway. Після спарювання дії Node є діями довіреного оператора на цьому Node. +- `sessionKey` — це вибір маршруту/контексту, а не auth окремого користувача. +- Схвалення exec (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожого багатокористувацького використання. +- Типова модель OpenClaw для довірених сценаріїв з одним оператором полягає в тому, що host exec на `gateway`/`node` дозволено без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви не посилите налаштування). Ця типова поведінка — свідоме UX-рішення, а не вразливість сама по собі. +- Схвалення exec прив’язуються до точного контексту запиту та best-effort прямих локальних файлових операндів; вони не моделюють семантично всі шляхи завантаження runtime/interpreter. Для сильних меж використовуйте sandboxing та ізоляцію хоста. -Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами та запускайте окремі Gateway. +Якщо вам потрібна ізоляція від ворожих користувачів, розділіть межі довіри за користувачами ОС/хостами та запускайте окремі Gateway. ## Матриця меж довіри Використовуйте це як швидку модель під час оцінки ризику: -| Межа або контроль | Що це означає | Типове хибне тлумачення | -| ------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує виклики до API gateway | «Щоб це було безпечно, потрібні підписи для кожного повідомлення в кожному кадрі» | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сеансу | «Ключ сеансу є межею автентифікації користувача» | -| Запобіжники prompt/вмісту | Зменшують ризик зловживання моделлю | «Лише prompt injection уже доводить обхід автентифікації» | -| `canvas.eval` / browser evaluate | Навмисна операторська можливість, коли ввімкнена | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | -| Локальна оболонка `!` у TUI | Явно ініційоване оператором локальне виконання | «Зручна локальна shell-команда — це віддалена ін’єкція» | -| Pairing node і команди node | Віддалене виконання на paired devices на рівні оператора | «Керування віддаленим пристроєм слід типово вважати доступом недовіреного користувача» | +| Межа або контроль | Що це означає | Типове хибне тлумачення | +| -------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує клієнтів для API Gateway | «Щоб бути безпечним, потрібні підписи для кожного повідомлення в кожному кадрі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії є межею auth користувача» | +| Запобіжники prompt/контенту | Зменшують ризик зловживання моделлю | «Сама лише prompt-ін’єкція вже доводить обхід auth» | +| `canvas.eval` / browser evaluate | Навмисна операторська можливість, якщо ввімкнена | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна оболонка TUI `!` | Явне локальне виконання, ініційоване оператором | «Зручна локальна shell-команда — це віддалена ін’єкція» | +| Pairing Node і команди Node | Віддалене виконання на рівні оператора на спарених пристроях | «Керування віддаленим пристроєм за замовчуванням слід вважати доступом недовіреного користувача» | ## Не є вразливостями за задумом -Про ці шаблони часто повідомляють, і зазвичай їх закривають без дій, якщо не показано реального обходу межі: +Ці шаблони часто потрапляють у звіти й зазвичай закриваються без дій, якщо не показано реальний обхід межі: -- Ланцюжки, що спираються лише на prompt injection без обходу політики/автентифікації/sandbox. -- Твердження, які виходять із припущення про ворожу багатокористувацьку роботу на одному спільному хості/config. -- Твердження, які класифікують звичайний операторський доступ до шляху читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним gateway. -- Виявлені проблеми в розгортанні лише на localhost (наприклад, HSTS на gateway, доступному лише через loopback). -- Зауваження щодо підпису вхідного Discord Webhook для вхідних шляхів, яких у цьому репозиторії не існує. -- Звіти, які трактують метадані pairing node як прихований другий шар підтвердження кожної команди для `system.run`, хоча реальною межею виконання лишається глобальна політика команд node у gateway плюс власні підтвердження exec на node. -- Зауваження про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. +- Ланцюжки лише з prompt-ін’єкцією без обходу політик/auth/sandbox. +- Твердження, що спираються на припущення про ворожу багатокористувацьку роботу на одному спільному хості/config. +- Заяви, які трактують звичайний операторський доступ для читання (наприклад `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним Gateway. +- Висновки для розгортань лише на localhost (наприклад HSTS на Gateway, доступному тільки через loopback). +- Знахідки про підписи вхідних Webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. +- Звіти, які трактують metadata pairing Node як прихований другий рівень схвалення для кожної команди `system.run`, коли реальною межею виконання все ще є глобальна політика команд Node на рівні gateway плюс власні схвалення exec на Node. +- Знахідки про «відсутню авторизацію на рівні окремого користувача», які трактують `sessionKey` як auth-token. -## Контрольний список дослідника перед поданням +## Контрольний список для дослідника перед поданням -Перш ніж відкривати GHSA, перевірте все наведене нижче: +Перш ніж відкривати GHSA, перевірте все з наведеного нижче: -1. Відтворення все ще працює на найновішій `main` або в останньому релізі. -2. У звіті вказано точний шлях у коді (`file`, function, line range) і протестовану версію/commit. -3. Вплив перетинає задокументовану межу довіри, а не лише prompt injection. +1. Відтворення все ще працює на останньому `main` або в останньому релізі. +2. Звіт містить точний шлях у коді (`file`, function, line range) і перевірену версію/commit. +3. Вплив перетинає задокументовану межу довіри, а не зводиться лише до prompt-ін’єкції. 4. Твердження не входить до [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). -5. Існуючі advisory перевірено на дублікати (за потреби повторно використовуйте канонічний GHSA). -6. Припущення щодо розгортання явно зазначені (loopback/local чи відкритий доступ, довірені чи недовірені оператори). +5. Існуючі advisories перевірено на дублікати (використовуйте канонічний GHSA, якщо застосовно). +6. Припущення щодо розгортання явно зазначені (loopback/local чи зовнішнє відкриття, довірені чи недовірені оператори). -## Посилена базова конфігурація за 60 секунд +## Посилений базовий захист за 60 секунд -Спочатку використовуйте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для довірених agent: +Спочатку використовуйте цей базовий профіль, а потім вибірково знову вмикайте інструменти для довірених agent: ```json5 { @@ -167,209 +167,209 @@ OpenClaw виходить із того, що хост і межа конфіг } ``` -Це залишає Gateway доступним лише локально, ізолює DM і типово вимикає інструменти control plane/runtime. +Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти control plane/runtime. -## Швидке правило для спільної вхідної скриньки +## Швидке правило для спільної скриньки Якщо більше ніж одна людина може писати вашому боту в DM: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома акаунтами). +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для channel з кількома обліковими записами). - Залишайте `dmPolicy: "pairing"` або суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює безпеку спільних/кооперативних вхідних скриньок, але не призначене для ізоляції ворожих співорендарів, коли користувачі мають спільний доступ на запис до host/config. +- Це посилює захист для кооперативних/спільних inbox, але не призначене як ізоляція ворожих співорендарів, коли користувачі мають спільний доступ на запис до host/config. ## Модель видимості контексту -OpenClaw розділяє дві концепції: +OpenClaw розділяє два поняття: - **Авторизація запуску**: хто може запускати agent (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадки). -- **Видимість контексту**: який додатковий контекст ін’єктується у вхід моделі (текст відповіді, цитований текст, історія треду, метадані пересилання). +- **Видимість контексту**: який додатковий контекст вбудовується у вхід моделі (тіло відповіді, процитований текст, історія треду, metadata пересилання). -Allowlists керують тим, хто може запускати обробку та авторизацією команд. Параметр `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені тредів, отримана історія): +Allowlist керують запуском і авторизацією команд. Налаштування `contextVisibility` керує тим, як фільтрується додатковий контекст (процитовані відповіді, кореневі повідомлення треду, отримана історія): -- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, у якому його отримано. -- `contextVisibility: "allowlist"` фільтрує додатковий контекст за відправниками, дозволеними активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явно цитовану відповідь. +- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, в якому його отримано. +- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну процитовану відповідь. -Установлюйте `contextVisibility` на рівні каналу або кімнати/розмови. Докладніше див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` на рівні channel або окремої room/conversation. Докладніше про налаштування див. у [Group Chats](/uk/channels/groups#context-visibility-and-allowlists). -Рекомендації для оцінки advisory: +Рекомендації для оцінки advisories: -- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників, яких немає в allowlist», є висновками про посилення безпеки, які вирішуються через `contextVisibility`, а не самі по собі є обходом межі автентифікації чи sandbox. -- Щоб вважатися значущими для безпеки, такі звіти все одно мають демонструвати обхід межі довіри (автентифікації, політики, sandbox, підтвердження або іншої задокументованої межі). +- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників поза allowlist», є знахідками з посилення захисту, які вирішуються через `contextVisibility`, а не обходом меж auth чи sandbox самі по собі. +- Щоб мати вплив на безпеку, звіт усе одно має демонструвати обхід межі довіри (auth, policy, sandbox, approval або іншої задокументованої межі). ## Що перевіряє аудит (на високому рівні) -- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні люди запускати бота? -- **Радіус ураження інструментів** (розширені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії з оболонкою/файлами/мережею? -- **Дрейф підтверджень exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec усе ще працюють так, як ви думаєте? - - `security="full"` — це широке попередження про рівень захисту, а не доказ наявності помилки. Це обраний типовий варіант для довірених конфігурацій персонального помічника; посилюйте його лише тоді, коли ваша модель загроз потребує підтвердження або запобіжників allowlist. -- **Мережева експозиція** (прив’язка/автентифікація Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). -- **Експозиція керування браузером** (віддалені node, relay-порти, віддалені кінцеві точки CDP). -- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «synced folder»). -- **Plugins** (розширення існують без явного allowlist). -- **Дрейф політик/помилки конфігурації** (налаштування sandbox docker задані, але режим sandbox вимкнений; неефективні шаблони `gateway.nodes.denyCommands`, оскільки збіг відбувається лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначається профілями на рівні agent; інструменти Plugin розширень доступні за надто дозволяючої політики інструментів). -- **Дрейф очікувань runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, коли `tools.exec.host` тепер типово має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` за вимкненого режиму sandbox). -- **Гігієна моделей** (попередження, якщо налаштовані моделі виглядають застарілими; не є жорстким блокуванням). +- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні користувачі запускати бота? +- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt-ін’єкція перетворитися на дії оболонки/файлів/мережі? +- **Дрейф схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec досі працюють так, як ви очікуєте? + - `security="full"` — це широке попередження про безпекову модель, а не доказ помилки. Це обрана типова поведінка для довірених конфігурацій персонального асистента; посилюйте її лише тоді, коли ваша модель загроз потребує схвалення або запобіжників allowlist. +- **Мережеве відкриття** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі auth-token). +- **Відкриття керування браузером** (віддалені Node, relay-порти, віддалені кінцеві точки CDP). +- **Гігієна локального диска** (дозволи, symlink, includes конфігурації, шляхи «синхронізованих папок»). +- **Plugins** (plugins завантажуються без явного allowlist). +- **Дрейф політик/помилки конфігурації** (налаштування sandbox docker задані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями окремих agent; інструменти, що належать Plugin, доступні за надто ліберальної політики інструментів). +- **Дрейф очікувань runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, коли `tools.exec.host` тепер типово має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). +- **Гігієна моделей** (попереджає, якщо налаштовані моделі виглядають застарілими; це не жорстке блокування). -Якщо ви запускаєте `--deep`, OpenClaw також виконує probe live Gateway за принципом best-effort. +Якщо ви запускаєте `--deep`, OpenClaw також виконує best-effort живу перевірку Gateway. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або коли вирішуєте, що резервувати: +Використовуйте це під час аудиту доступу або вирішення, що саме резервувати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Токен Telegram-бота**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) -- **Токен Discord-бота**: config/env або SecretRef (провайдери env/file/exec) +- **Токен Telegram bot**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) +- **Токен Discord bot**: config/env або SecretRef (провайдери env/file/exec) - **Токени Slack**: config/env (`channels.slack.*`) -- **Allowlists pairing**: - - `~/.openclaw/credentials/-allowFrom.json` (типовий акаунт) - - `~/.openclaw/credentials/--allowFrom.json` (нетипові акаунти) -- **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Payload секретів із файлу (необов’язково)**: `~/.openclaw/secrets.json` +- **Allowlist pairing**: + - `~/.openclaw/credentials/-allowFrom.json` (типовий обліковий запис) + - `~/.openclaw/credentials/--allowFrom.json` (нетипові облікові записи) +- **Профілі auth моделей**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Вміст секретів у файлі (необов’язково)**: `~/.openclaw/secrets.json` - **Застарілий імпорт OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить findings, сприймайте це як порядок пріоритетів: +Коли аудит виводить результати, використовуйте такий порядок пріоритетів: -1. **Будь-що “open” + увімкнені інструменти**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. -2. **Публічна мережева експозиція** (прив’язка до LAN, Funnel, відсутня автентифікація): виправляйте негайно. -3. **Віддалена експозиція керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, pairing node навмисно, уникайте публічного доступу). -4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні на читання групі або всім. -5. **Plugins/розширення**: завантажуйте лише те, чому явно довіряєте. -6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним, стійким до інструкцій моделям. +1. **Усе, що “open” + увімкнені інструменти**: спочатку закрийте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. +2. **Публічне мережеве відкриття** (bind у LAN, Funnel, відсутній auth): виправляйте негайно. +3. **Віддалене відкриття керування браузером**: розглядайте це як операторський доступ (лише tailnet, pairing Node навмисно, уникайте публічного відкриття). +4. **Дозволи**: переконайтеся, що state/config/облікові дані/auth не доступні на читання групі чи всім. +5. **Plugins**: завантажуйте лише те, чому явно довіряєте. +6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним, посиленим щодо інструкцій моделям. ## Глосарій аудиту безпеки -checkId з високим сигналом, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний список): +Значення `checkId` з високим сигналом, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний список): -| `checkId` | Severity | Чому це важливо | Основний ключ/шлях для виправлення | Auto-fix | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | -| `fs.state_dir.perms_world_writable` | critical | Інші користувачі/процеси можуть змінювати весь state OpenClaw | дозволи файлової системи для `~/.openclaw` | yes | -| `fs.state_dir.perms_group_writable` | warn | Користувачі групи можуть змінювати весь state OpenClaw | дозволи файлової системи для `~/.openclaw` | yes | -| `fs.state_dir.perms_readable` | warn | Каталог state доступний для читання іншими | дозволи файлової системи для `~/.openclaw` | yes | -| `fs.state_dir.symlink` | warn | Ціль каталогу state стає іншою межею довіри | схема файлової системи для каталогу state | no | -| `fs.config.perms_writable` | critical | Інші можуть змінити автентифікацію/політику інструментів/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | yes | -| `fs.config.symlink` | warn | Ціль config стає іншою межею довіри | схема файлової системи для config-файлу | no | -| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування config | дозволи файлової системи для config-файлу | yes | -| `fs.config.perms_world_readable` | critical | Config може розкрити токени/налаштування | дозволи файлової системи для config-файлу | yes | -| `fs.config_include.perms_writable` | critical | Include-file config може бути змінений іншими | дозволи include-file, на який є посилання з `openclaw.json` | yes | -| `fs.config_include.perms_group_readable` | warn | Користувачі групи можуть читати включені секрети/налаштування | дозволи include-file, на який є посилання з `openclaw.json` | yes | -| `fs.config_include.perms_world_readable` | critical | Включені секрети/налаштування доступні всім для читання | дозволи include-file, на який є посилання з `openclaw.json` | yes | -| `fs.auth_profiles.perms_writable` | critical | Інші можуть ін’єктувати або замінити збережені облікові дані моделі | дозволи для `agents//agent/auth-profiles.json` | yes | -| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | yes | -| `fs.credentials_dir.perms_writable` | critical | Інші можуть змінювати state pairing/облікових даних каналу | дозволи файлової системи для `~/.openclaw/credentials` | yes | -| `fs.credentials_dir.perms_readable` | warn | Інші можуть читати state облікових даних каналу | дозволи файлової системи для `~/.openclaw/credentials` | yes | -| `fs.sessions_store.perms_readable` | warn | Інші можуть читати транскрипти/метадані сеансів | дозволи сховища сеансів | yes | -| `fs.log_file.perms_readable` | warn | Інші можуть читати журнали, де дані замасковано, але вони все ще чутливі | дозволи для лог-файлу gateway | yes | -| `fs.synced_dir` | warn | State/config в iCloud/Dropbox/Drive розширює ризик витоку токенів/транскриптів | перенесіть config/state із синхронізованих папок | no | -| `gateway.bind_no_auth` | critical | Віддалена прив’язка без спільного секрету | `gateway.bind`, `gateway.auth.*` | no | -| `gateway.loopback_no_auth` | critical | Loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | no | -| `gateway.trusted_proxies_missing` | warn | Заголовки reverse proxy присутні, але proxy не позначено як trusted | `gateway.trustedProxies` | no | -| `gateway.http.no_auth` | warn/critical | До HTTP API Gateway можна звертатися з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | no | -| `gateway.http.session_key_override_enabled` | info | Клієнти HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | no | -| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | Знову вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | no | -| `gateway.nodes.allow_commands_dangerous` | warn/critical | Вмикає high-impact команди node (camera/screen/contacts/calendar/SMS) | `gateway.nodes.allowCommands` | no | -| `gateway.nodes.deny_commands_ineffective` | warn | Шаблоноподібні записи deny не збігаються з shell-текстом або групами | `gateway.nodes.denyCommands` | no | -| `gateway.tailscale_funnel` | critical | Публічна експозиція в інтернет | `gateway.tailscale.mode` | no | -| `gateway.tailscale_serve` | info | Експозицію в tailnet увімкнено через Serve | `gateway.tailscale.mode` | no | -| `gateway.control_ui.allowed_origins_required` | critical | Control UI поза loopback без явного allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | no | -| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` вимикає allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | no | -| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Вмикає fallback джерела через Host-header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | no | -| `gateway.control_ui.insecure_auth` | warn | Увімкнено перемикач сумісності insecure-auth | `gateway.controlUi.allowInsecureAuth` | no | -| `gateway.control_ui.device_auth_disabled` | critical | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | no | -| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підміну IP-джерела через помилку proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | no | -| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | no | -| `gateway.auth_no_rate_limit` | warn | Відкрита автентифікація без обмеження частоти підвищує ризик brute-force | `gateway.auth.rateLimit` | no | -| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | no | -| `gateway.trusted_proxy_no_proxies` | critical | Автентифікація trusted-proxy без IP trusted proxy є небезпечною | `gateway.trustedProxies` | no | -| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | no | -| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | no | -| `checkId` | Severity | Чому це важливо | Основний ключ/шлях для виправлення | Auto-fix | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | -| `gateway.probe_auth_secretref_unavailable` | warn | Deep probe не зміг розв’язати auth SecretRef у цьому шляху команди | джерело auth для deep probe / доступність SecretRef | no | -| `gateway.probe_failed` | warn/critical | Live Gateway probe завершився невдало | доступність/автентифікація gateway | no | -| `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | no | -| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні/незахищені debug-прапори | кілька ключів (див. деталі finding) | no | -| `config.secrets.gateway_password_in_config` | warn | Пароль Gateway зберігається безпосередньо в config | `gateway.auth.password` | no | -| `config.secrets.hooks_token_in_config` | warn | Bearer-токен hook зберігається безпосередньо в config | `hooks.token` | no | -| `hooks.token_reuse_gateway_token` | critical | Токен вхідних hook також розблоковує автентифікацію Gateway | `hooks.token`, `gateway.auth.token` | no | -| `hooks.token_too_short` | warn | Легше виконати brute force для вхідних hook | `hooks.token` | no | -| `hooks.default_session_key_unset` | warn | Розподіл запусків hook agent відбувається у згенеровані сеанси для кожного запиту | `hooks.defaultSessionKey` | no | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані виклики hook можуть маршрутизуватися до будь-якого налаштованого agent | `hooks.allowedAgentIds` | no | -| `hooks.request_session_key_enabled` | warn/critical | Зовнішній виклик може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | no | -| `hooks.request_session_key_prefixes_missing` | warn/critical | Відсутні обмеження на форму зовнішніх ключів сеансу | `hooks.allowedSessionKeyPrefixes` | no | -| `hooks.path_root` | critical | Шлях hook дорівнює `/`, що полегшує колізії або помилкову маршрутизацію вхідного трафіку | `hooks.path` | no | -| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлення hook не зафіксовані до незмінних специфікацій npm | метадані встановлення hook | no | -| `hooks.installs_missing_integrity` | warn | У записах встановлення hook відсутні метадані integrity | метадані встановлення hook | no | -| `hooks.installs_version_drift` | warn | Записи встановлення hook розходяться зі встановленими пакетами | метадані встановлення hook | no | -| `logging.redact_off` | warn | Чутливі значення потрапляють у логи/status | `logging.redactSensitive` | yes | -| `browser.control_invalid_config` | warn | Конфігурація керування браузером невалідна ще до runtime | `browser.*` | no | -| `browser.control_no_auth` | critical | Керування браузером відкрите без автентифікації token/password | `gateway.auth.*` | no | -| `browser.remote_cdp_http` | warn | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль браузера `cdpUrl` | no | -| `browser.remote_cdp_private_host` | warn | Віддалений CDP націлений на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | no | -| `sandbox.docker_config_mode_off` | warn | Конфігурація Sandbox Docker присутня, але неактивна | `agents.*.sandbox.mode` | no | -| `sandbox.bind_mount_non_absolute` | warn | Відносні bind mount можуть розв’язуватися непередбачувано | `agents.*.sandbox.docker.binds[]` | no | -| `sandbox.dangerous_bind_mount` | critical | Bind mount Sandbox націлено на заблоковані системні шляхи, шляхи облікових даних або Docker socket | `agents.*.sandbox.docker.binds[]` | no | -| `sandbox.dangerous_network_mode` | critical | Мережа Sandbox Docker використовує режим `host` або `container:*` із приєднанням до namespace | `agents.*.sandbox.docker.network` | no | -| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp Sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | no | -| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor Sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | no | -| `sandbox.browser_cdp_bridge_unrestricted` | warn | Browser bridge Sandbox відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | no | -| `sandbox.browser_container.non_loopback_publish` | critical | Наявний browser container публікує CDP на інтерфейсах, відмінних від loopback | конфігурація publish browser sandbox container | no | -| `sandbox.browser_container.hash_label_missing` | warn | Наявний browser container передує поточним міткам hash конфігурації | `openclaw sandbox recreate --browser --all` | no | -| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний browser container передує поточній epoch конфігурації браузера | `openclaw sandbox recreate --browser --all` | no | -| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` переходить у безпечну відмову, коли sandbox вимкнений | `tools.exec.host`, `agents.defaults.sandbox.mode` | no | -| `tools.exec.host_sandbox_no_sandbox_agents` | warn | `exec host=sandbox` для окремого agent переходить у безпечну відмову, коли sandbox вимкнений | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | no | -| `tools.exec.security_full_configured` | warn/critical | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | no | -| `tools.exec.auto_allow_skills_enabled` | warn | Підтвердження exec неявно довіряють skill bins | `~/.openclaw/exec-approvals.json` | no | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlists інтерпретаторів дозволяють inline eval без примусового повторного підтвердження | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist підтверджень exec | no | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Біни інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | no | -| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти широкої поведінки в `safeBins` послаблюють модель довіри з низьким ризиком для stdin-filter | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | no | -| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | no | -| `skills.workspace.symlink_escape` | warn | `skills/**/SKILL.md` у workspace розв’язується за межі кореня workspace (дрейф ланцюга symlink) | стан файлової системи `skills/**` у workspace | no | -| `plugins.extensions_no_allowlist` | warn | Розширення встановлено без явного allowlist Plugin | `plugins.allowlist` | no | -| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення Plugin не зафіксовані до незмінних специфікацій npm | метадані встановлення Plugin | no | -| `checkId` | Severity | Чому це важливо | Основний ключ/шлях для виправлення | Auto-fix | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- | -| `plugins.installs_missing_integrity` | warn | У записах встановлення Plugin відсутні метадані integrity | метадані встановлення Plugin | no | -| `plugins.installs_version_drift` | warn | Записи встановлення Plugin розходяться зі встановленими пакетами | метадані встановлення Plugin | no | -| `plugins.code_safety` | warn/critical | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код Plugin / джерело встановлення | no | -| `plugins.code_safety.entry_path` | warn | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті Plugin | no | -| `plugins.code_safety.entry_escape` | critical | Точка входу Plugin виходить за межі каталогу Plugin | `entry` у маніфесті Plugin | no | -| `plugins.code_safety.scan_failed` | warn | Сканування коду Plugin не вдалося завершити | шлях до розширення Plugin / середовище сканування | no | -| `skills.code_safety` | warn/critical | Метадані інсталятора/код Skill містять підозрілі або небезпечні шаблони | джерело встановлення Skill | no | -| `skills.code_safety.scan_failed` | warn | Сканування коду Skill не вдалося завершити | середовище сканування Skill | no | -| `security.exposure.open_channels_with_exec` | warn/critical | Спільні/публічні кімнати можуть звертатися до agent з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | no | -| `security.exposure.open_groups_with_elevated` | critical | Відкриті групи + розширені інструменти створюють шляхи prompt injection із високим впливом | `channels.*.groupPolicy`, `tools.elevated.*` | no | -| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | Відкриті групи можуть отримати доступ до інструментів команд/файлів без sandbox/обмежень workspace | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | no | -| `security.trust_model.multi_user_heuristic` | warn | Config виглядає багатокористувацьким, тоді як модель довіри gateway — персональний помічник | розділіть межі довіри або посильте захист для спільного використання (`sandbox.mode`, deny інструментів/обмеження workspace) | no | -| `tools.profile_minimal_overridden` | warn | Перевизначення agent обходять глобальний профіль minimal | `agents.list[].tools.profile` | no | -| `plugins.tools_reachable_permissive_policy` | warn | Інструменти розширень доступні в надто дозволяючих контекстах | `tools.profile` + allow/deny інструментів | no | -| `models.legacy` | warn | Застарілі сімейства моделей досі налаштовані | вибір моделі | no | -| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточно рекомендовані рівні | вибір моделі | no | -| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик injection | вибір моделі + політика sandbox/інструментів | no | -| `summary.attack_surface` | info | Зведений підсумок стану автентифікації, каналів, інструментів і рівня експозиції | кілька ключів (див. деталі finding) | no | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | +| `fs.state_dir.perms_world_writable` | критична | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.perms_group_writable` | попередження | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.perms_readable` | попередження | Каталог стану доступний для читання іншим | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.symlink` | попередження | Цільовий каталог стану стає іншою межею довіри | структура файлової системи каталогу стану | ні | +| `fs.config.perms_writable` | критична | Інші можуть змінювати auth/політику інструментів/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | +| `fs.config.symlink` | попередження | Ціль config стає іншою межею довіри | структура файлової системи файлу config | ні | +| `fs.config.perms_group_readable` | попередження | Користувачі групи можуть читати токени/налаштування config | дозволи файлової системи для файлу config | так | +| `fs.config.perms_world_readable` | критична | Config може розкривати токени/налаштування | дозволи файлової системи для файлу config | так | +| `fs.config_include.perms_writable` | критична | Файл include config може змінюватися іншими | дозволи на include-файл, на який посилається `openclaw.json` | так | +| `fs.config_include.perms_group_readable` | попередження | Користувачі групи можуть читати включені секрети/налаштування | дозволи на include-файл, на який посилається `openclaw.json` | так | +| `fs.config_include.perms_world_readable` | критична | Включені секрети/налаштування доступні для читання всім | дозволи на include-файл, на який посилається `openclaw.json` | так | +| `fs.auth_profiles.perms_writable` | критична | Інші можуть підмінити або замінити збережені облікові дані моделі | дозволи для `agents//agent/auth-profiles.json` | так | +| `fs.auth_profiles.perms_readable` | попередження | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | так | +| `fs.credentials_dir.perms_writable` | критична | Інші можуть змінювати стан pairing/облікових даних channel | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.credentials_dir.perms_readable` | попередження | Інші можуть читати стан облікових даних channel | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.sessions_store.perms_readable` | попередження | Інші можуть читати транскрипти/metadata сесій | дозволи для сховища сесій | так | +| `fs.log_file.perms_readable` | попередження | Інші можуть читати журнали, у яких дані хоч і редаговані, але все ще чутливі | дозволи для файлу журналу Gateway | так | +| `fs.synced_dir` | попередження | State/config в iCloud/Dropbox/Drive розширює ризик розкриття токенів/транскриптів | перемістіть config/state за межі синхронізованих папок | ні | +| `gateway.bind_no_auth` | критична | Віддалений bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | +| `gateway.loopback_no_auth` | критична | Loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | +| `gateway.trusted_proxies_missing` | попередження | Заголовки reverse proxy присутні, але proxy не довірені | `gateway.trustedProxies` | ні | +| `gateway.http.no_auth` | попередження/критична | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні | +| `gateway.http.session_key_override_enabled` | інформація | Клієнти HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні | +| `gateway.tools_invoke_http.dangerous_allow` | попередження/критична | Знову вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні | +| `gateway.nodes.allow_commands_dangerous` | попередження/критична | Увімкнено високоризикові команди Node (camera/screen/contacts/calendar/SMS) | `gateway.nodes.allowCommands` | ні | +| `gateway.nodes.deny_commands_ineffective` | попередження | Записи deny, схожі на шаблони, не зіставляються з текстом оболонки або групами | `gateway.nodes.denyCommands` | ні | +| `gateway.tailscale_funnel` | критична | Публічне відкриття в інтернет | `gateway.tailscale.mode` | ні | +| `gateway.tailscale_serve` | інформація | Увімкнено доступ через tailnet через Serve | `gateway.tailscale.mode` | ні | +| `gateway.control_ui.allowed_origins_required` | критична | Control UI поза loopback без явного allowlist browser-origin | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.allowed_origins_wildcard` | попередження/критична | `allowedOrigins=["*"]` вимикає allowlist browser-origin | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.host_header_origin_fallback` | попередження/критична | Увімкнено fallback origin через Host header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | +| `gateway.control_ui.insecure_auth` | попередження | Увімкнено режим сумісності з небезпечним auth | `gateway.controlUi.allowInsecureAuth` | ні | +| `gateway.control_ui.device_auth_disabled` | критична | Вимкнено перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | +| `gateway.real_ip_fallback_enabled` | попередження/критична | Довіра до fallback `X-Real-IP` може дозволити підміну source IP через помилку proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | +| `gateway.token_too_short` | попередження | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | +| `gateway.auth_no_rate_limit` | попередження | Відкритий auth без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні | +| `gateway.trusted_proxy_auth` | критична | Ідентичність proxy тепер стає межею auth | `gateway.auth.mode="trusted-proxy"` | ні | +| `gateway.trusted_proxy_no_proxies` | критична | Trusted-proxy auth без IP довірених proxy є небезпечним | `gateway.trustedProxies` | ні | +| `gateway.trusted_proxy_no_user_header` | критична | Trusted-proxy auth не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | +| `gateway.trusted_proxy_no_allowlist` | попередження | Trusted-proxy auth приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | +| `gateway.probe_auth_secretref_unavailable` | попередження | Глибока перевірка не змогла визначити auth SecretRef у цьому шляху команди | джерело auth для deep-probe / доступність SecretRef | ні | +| `gateway.probe_failed` | попередження/критична | Жива перевірка Gateway завершилася невдачею | доступність/автентифікація gateway | ні | +| `discovery.mdns_full_mode` | попередження/критична | Повний режим mDNS рекламує metadata `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | +| `config.insecure_or_dangerous_flags` | попередження | Увімкнено будь-які небезпечні або ризиковані прапорці налагодження | кілька ключів (див. деталі результату) | ні | +| `config.secrets.gateway_password_in_config` | попередження | Пароль Gateway зберігається безпосередньо в config | `gateway.auth.password` | ні | +| `config.secrets.hooks_token_in_config` | попередження | Bearer-токен hooks зберігається безпосередньо в config | `hooks.token` | ні | +| `hooks.token_reuse_gateway_token` | критична | Токен входу hooks також відкриває auth Gateway | `hooks.token`, `gateway.auth.token` | ні | +| `hooks.token_too_short` | попередження | Легший brute force для входу hooks | `hooks.token` | ні | +| `hooks.default_session_key_unset` | попередження | Agent hooks розподіляє запуски по згенерованих сесіях для кожного запиту | `hooks.defaultSessionKey` | ні | +| `hooks.allowed_agent_ids_unrestricted` | попередження/критична | Автентифіковані викликачі hooks можуть маршрутизувати до будь-якого налаштованого agent | `hooks.allowedAgentIds` | ні | +| `hooks.request_session_key_enabled` | попередження/критична | Зовнішній викликач може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | +| `hooks.request_session_key_prefixes_missing` | попередження/критична | Немає обмеження на форму зовнішніх ключів сесій | `hooks.allowedSessionKeyPrefixes` | ні | +| `hooks.path_root` | критична | Шлях hooks дорівнює `/`, що полегшує колізії або помилкову маршрутизацію входу | `hooks.path` | ні | +| `hooks.installs_unpinned_npm_specs` | попередження | Записи встановлення hooks не прив’язані до незмінних специфікацій npm | metadata встановлення hooks | ні | +| `hooks.installs_missing_integrity` | попередження | У записах встановлення hooks відсутні metadata цілісності | metadata встановлення hooks | ні | +| `hooks.installs_version_drift` | попередження | Записи встановлення hooks відхиляються від установлених пакетів | metadata встановлення hooks | ні | +| `logging.redact_off` | попередження | Чутливі значення потрапляють у журнали/status | `logging.redactSensitive` | так | +| `browser.control_invalid_config` | попередження | Config керування browser є невалідним ще до runtime | `browser.*` | ні | +| `browser.control_no_auth` | критична | Керування browser відкрито без auth через token/password | `gateway.auth.*` | ні | +| `browser.remote_cdp_http` | попередження | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль browser `cdpUrl` | ні | +| `browser.remote_cdp_private_host` | попередження | Віддалений CDP націлений на приватний/внутрішній хост | профіль browser `cdpUrl`, `browser.ssrfPolicy.*` | ні | +| `sandbox.docker_config_mode_off` | попередження | Config Docker для sandbox присутній, але неактивний | `agents.*.sandbox.mode` | ні | +| `sandbox.bind_mount_non_absolute` | попередження | Відносні bind mount можуть визначатися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_bind_mount` | критична | Bind mount sandbox націлено на заблоковані системні шляхи, облікові дані або шляхи Docker socket | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_network_mode` | критична | Docker network для sandbox використовує `host` або режим приєднання до простору назв `container:*` | `agents.*.sandbox.docker.network` | ні | +| `sandbox.dangerous_seccomp_profile` | критична | Профіль seccomp для sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.dangerous_apparmor_profile` | критична | Профіль AppArmor для sandbox послаблює ізоляцію container | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.browser_cdp_bridge_unrestricted` | попередження | Міст CDP browser у sandbox відкрито без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | +| `sandbox.browser_container.non_loopback_publish` | критична | Наявний container browser публікує CDP на інтерфейсах поза loopback | config публікації container browser для sandbox | ні | +| `sandbox.browser_container.hash_label_missing` | попередження | Наявний container browser передує поточним міткам хешу config | `openclaw sandbox recreate --browser --all` | ні | +| `sandbox.browser_container.hash_epoch_stale` | попередження | Наявний container browser передує поточній епосі config browser | `openclaw sandbox recreate --browser --all` | ні | +| `tools.exec.host_sandbox_no_sandbox_defaults` | попередження | `exec host=sandbox` безпечно відмовляє, якщо sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні | +| `tools.exec.host_sandbox_no_sandbox_agents` | попередження | `exec host=sandbox` для окремого agent безпечно відмовляє, якщо sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні | +| `tools.exec.security_full_configured` | попередження/критична | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні | +| `tools.exec.auto_allow_skills_enabled` | попередження | Схвалення exec неявно довіряють bin з Skills | `~/.openclaw/exec-approvals.json` | ні | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | попередження | Allowlist інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist схвалень exec | ні | +| `tools.exec.safe_bins_interpreter_unprofiled` | попередження | Bin інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | +| `tools.exec.safe_bins_broad_behavior` | попередження | Інструменти широкої поведінки в `safeBins` послаблюють модель довіри низького ризику для фільтра stdin | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні | +| `tools.exec.safe_bin_trusted_dirs_risky` | попередження | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні | +| `skills.workspace.symlink_escape` | попередження | `skills/**/SKILL.md` у workspace визначається за межами кореня workspace (дрейф ланцюжка symlink) | стан файлової системи `skills/**` у workspace | ні | +| `plugins.extensions_no_allowlist` | попередження | Plugins встановлені без явного allowlist plugins | `plugins.allowlist` | ні | +| `plugins.installs_unpinned_npm_specs` | попередження | Записи встановлення Plugin не прив’язані до незмінних специфікацій npm | metadata встановлення Plugin | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | --------------- | +| `plugins.installs_missing_integrity` | попередження | У записах встановлення Plugin відсутні metadata цілісності | metadata встановлення Plugin | ні | +| `plugins.installs_version_drift` | попередження | Записи встановлення Plugin відхиляються від установлених пакетів | metadata встановлення Plugin | ні | +| `plugins.code_safety` | попередження/критична | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код Plugin / джерело встановлення | ні | +| `plugins.code_safety.entry_path` | попередження | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті Plugin | ні | +| `plugins.code_safety.entry_escape` | критична | Точка входу Plugin виходить за межі каталогу Plugin | `entry` у маніфесті Plugin | ні | +| `plugins.code_safety.scan_failed` | попередження | Сканування коду Plugin не вдалося завершити | шлях Plugin / середовище сканування | ні | +| `skills.code_safety` | попередження/критична | Metadata/код інсталятора Skill містить підозрілі або небезпечні шаблони | джерело встановлення Skill | ні | +| `skills.code_safety.scan_failed` | попередження | Сканування коду Skill не вдалося завершити | середовище сканування Skill | ні | +| `security.exposure.open_channels_with_exec` | попередження/критична | Спільні/публічні кімнати можуть звертатися до agent з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | +| `security.exposure.open_groups_with_elevated` | критична | Відкриті групи + підвищені інструменти створюють високоризикові шляхи prompt-ін’єкції | `channels.*.groupPolicy`, `tools.elevated.*` | ні | +| `security.exposure.open_groups_with_runtime_or_fs` | критична/попередження | Відкриті групи можуть отримати доступ до командних/файлових інструментів без захисту sandbox/workspace | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні | +| `security.trust_model.multi_user_heuristic` | попередження | Config виглядає як багатокористувацька, тоді як модель довіри Gateway — персональний асистент | розділіть межі довіри або посильте захист для спільного користувача (`sandbox.mode`, deny інструментів / обмеження workspace) | ні | +| `tools.profile_minimal_overridden` | попередження | Перевизначення agent обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | +| `plugins.tools_reachable_permissive_policy` | попередження | Інструменти extensions доступні в надто ліберальних контекстах | `tools.profile` + allow/deny інструментів | ні | +| `models.legacy` | попередження | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | +| `models.weak_tier` | попередження | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні | +| `models.small_params` | критична/інформація | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + sandbox/політика інструментів | ні | +| `summary.attack_surface` | інформація | Зведений підсумок щодо auth, channel, інструментів і рівня відкриття | кілька ключів (див. деталі результату) | ні | ## Control UI через HTTP Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: -- На localhost він дозволяє автентифікацію Control UI без ідентичності пристрою, коли сторінку завантажено через незахищений HTTP. +- На localhost він дозволяє auth для Control UI без ідентичності пристрою, коли сторінку завантажено через незахищений HTTP. - Він не обходить перевірки pairing. - Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень. -Надавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. +Віддавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. -Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; тримайте його вимкненим, якщо тільки ви не налагоджуєте проблему й не можете швидко повернути зміни назад. +Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; тримайте цей параметр вимкненим, якщо тільки ви не займаєтеся активним налагодженням і можете швидко повернути зміни. -Окремо від цих небезпечних прапорів, успішний `gateway.auth.mode: "trusted-proxy"` може допустити **операторські** сеанси Control UI без ідентичності пристрою. Це навмисна поведінка режиму автентифікації, а не обхід через `allowInsecureAuth`, і вона все одно не поширюється на сеанси Control UI із роллю node. +Окремо від цих небезпечних прапорців, успішний `gateway.auth.mode: "trusted-proxy"` може допускати **операторські** сесії Control UI без ідентичності пристрою. Це навмисна поведінка режиму auth, а не обхід через `allowInsecureAuth`, і вона все одно не поширюється на сесії Control UI з роллю node. `openclaw security audit` попереджає, коли цей параметр увімкнено. -## Підсумок незахищених або небезпечних прапорів +## Підсумок щодо небезпечних або ризикованих прапорців -`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли ввімкнено відомі незахищені/небезпечні debug-перемикачі. Зараз ця перевірка агрегує: +`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли ввімкнено відомі небезпечні або ризиковані перемикачі налагодження. Наразі ця перевірка агрегує: - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` @@ -391,15 +391,15 @@ Control UI потребує **безпечного контексту** (HTTPS - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.googlechat.accounts..dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` -- `channels.synology-chat.dangerouslyAllowNameMatching` (канал розширення) -- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (канал розширення) -- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (канал розширення) -- `channels.zalouser.dangerouslyAllowNameMatching` (канал розширення) -- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (канал розширення) -- `channels.irc.dangerouslyAllowNameMatching` (канал розширення) -- `channels.irc.accounts..dangerouslyAllowNameMatching` (канал розширення) -- `channels.mattermost.dangerouslyAllowNameMatching` (канал розширення) -- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (канал розширення) +- `channels.synology-chat.dangerouslyAllowNameMatching` (Plugin channel) +- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (Plugin channel) +- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (Plugin channel) +- `channels.zalouser.dangerouslyAllowNameMatching` (Plugin channel) +- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (Plugin channel) +- `channels.irc.dangerouslyAllowNameMatching` (Plugin channel) +- `channels.irc.accounts..dangerouslyAllowNameMatching` (Plugin channel) +- `channels.mattermost.dangerouslyAllowNameMatching` (Plugin channel) +- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (Plugin channel) - `channels.telegram.network.dangerouslyAllowPrivateNetwork` - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` @@ -411,135 +411,141 @@ Control UI потребує **безпечного контексту** (HTTPS ## Конфігурація reverse proxy -Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте `gateway.trustedProxies` для коректної обробки пересланого IP клієнта. +Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте +`gateway.trustedProxies` для коректної обробки пересланих IP-адрес клієнтів. -Коли Gateway виявляє заголовки proxy від адреси, якої **немає** в `trustedProxies`, він **не** трактує з’єднання як локальні клієнтські. Якщо автентифікацію gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли proxied-з’єднання інакше могли б виглядати як такі, що походять із localhost, і автоматично отримувати довіру. +Коли Gateway виявляє заголовки proxy від адреси, якої **немає** у `trustedProxies`, він **не** вважає такі з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли з’єднання через proxy інакше виглядали б як такі, що надходять із localhost, і отримували б автоматичну довіру. -`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим автентифікації суворіший: +`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: -- автентифікація trusted-proxy **переходить у безпечну відмову для proxy із джерелом loopback** -- reverse proxy з loopback на тому самому хості все одно можуть використовувати `gateway.trustedProxies` для виявлення локального клієнта та обробки пересланого IP -- для reverse proxy з loopback на тому самому хості використовуйте автентифікацію token/password замість `gateway.auth.mode: "trusted-proxy"` +- trusted-proxy auth **завершується безпечним блокуванням для proxy із джерелом loopback** +- reverse proxy loopback на тому самому хості все одно можуть використовувати `gateway.trustedProxies` для виявлення локальних клієнтів і обробки пересланого IP +- для reverse proxy loopback на тому самому хості використовуйте auth через token/password замість `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - "10.0.0.1" # IP reverse proxy - # Необов’язково. Типово false. - # Увімкніть лише якщо ваш proxy не може надавати X-Forwarded-For. + # Необов’язково. Типове значення false. + # Увімкніть лише якщо ваш proxy не може передавати X-Forwarded-For. allowRealIpFallback: false auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -Коли налаштовано `trustedProxies`, Gateway використовує `X-Forwarded-For` для визначення IP клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. +Коли налаштовано `trustedProxies`, Gateway використовує `X-Forwarded-For` для визначення IP-адреси клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. -Правильна поведінка reverse proxy (перезапис вхідних заголовків forwarding): +Коректна поведінка reverse proxy (перезапис вхідних заголовків переспрямування): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Неправильна поведінка reverse proxy (додавання/збереження недовірених forwarding-заголовків): +Некоректна поведінка reverse proxy (додавання/збереження недовірених заголовків переспрямування): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` -## Примітки щодо HSTS і origin +## Примітки щодо HSTS та origin -- Gateway OpenClaw орієнтований насамперед на локальну/loopback-роботу. Якщо ви завершуєте TLS на reverse proxy, налаштовуйте HSTS там, на HTTPS-домені, який бачить proxy. -- Якщо HTTPS завершує сам gateway, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. +- Gateway OpenClaw насамперед орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, встановлюйте HSTS там, на HTTPS-домені з боку proxy. +- Якщо сам gateway завершує HTTPS, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. - Детальні рекомендації щодо розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Для розгортань Control UI поза loopback `gateway.controlUi.allowedOrigins` типово є обов’язковим. -- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика браузерного origin «дозволити все», а не посилений типовий варіант. Уникайте її поза жорстко контрольованим локальним тестуванням. -- Збої автентифікації browser-origin на loopback усе одно мають rate limit, навіть коли ввімкнено загальне виключення для loopback, але ключ блокування обмежується нормалізованим значенням `Origin`, а не одним спільним кошиком localhost. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin через Host-header; ставтеся до цього як до небезпечної політики, навмисно обраної оператором. -- Розглядайте DNS rebinding і поведінку proxy-host header як питання посилення безпеки розгортання; тримайте `trustedProxies` суворо обмеженим і не відкривайте gateway безпосередньо в публічний інтернет. +- Для розгортань Control UI поза loopback `gateway.controlUi.allowedOrigins` за замовчуванням є обов’язковим. +- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика browser-origin «дозволити все», а не посилене типове налаштування. Уникайте її поза межами жорстко контрольованого локального тестування. +- Збої auth за browser-origin на loopback усе одно обмежуються rate limiting, навіть коли загальний виняток для loopback увімкнено, але ключ блокування визначається для кожного нормалізованого значення `Origin`, а не для одного спільного сегмента localhost. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin через Host header; розглядайте це як небезпечну політику, свідомо вибрану оператором. +- Розглядайте DNS rebinding і поведінку proxy щодо заголовка Host як питання посилення розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. -## Локальні журнали сеансів зберігаються на диску +## Локальні журнали сесій зберігаються на диску -OpenClaw зберігає транскрипти сеансів на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сеансів і (необов’язково) індексації пам’яті сеансів, але це також означає, що +OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. +Це потрібно для безперервності сесій і (за бажанням) індексації пам’яті сесій, але це також означає, що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска -межею довіри й обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +межею довіри та обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна сильніша ізоляція між agent, запускайте їх під окремими користувачами ОС або на окремих хостах. -## Виконання на node (`system.run`) +## Виконання на Node (`system.run`) -Якщо paired macOS node підключено, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: +Якщо спарено macOS Node, Gateway може викликати `system.run` на цьому Node. Це **віддалене виконання коду** на Mac: -- Потребує pairing node (підтвердження + токен). -- Pairing node в Gateway не є поверхнею підтвердження кожної окремої команди. Воно встановлює ідентичність/довіру node і видачу токена. -- Gateway застосовує грубу глобальну політику команд node через `gateway.nodes.allowCommands` / `denyCommands`. -- На Mac це контролюється через **Settings → Exec approvals** (`security` + `ask` + allowlist). -- Політика `system.run` для кожного node — це власний файл підтверджень exec цього node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ID команд gateway. -- Node, який працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не вимагає суворішого підходу до підтверджень або allowlist. -- Режим підтвердження прив’язується до точного контексту запиту і, коли можливо, до одного конкретного локального script/file-операнда. Якщо OpenClaw не може точно визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання через механізм підтвердження забороняється, а не обіцяється повне семантичне покриття. -- Для `host=node` виконання через підтвердження також зберігає канонічний підготовлений `systemRunPlan`; подальші схвалені переспрямування повторно використовують цей збережений план, а валідація gateway відхиляє зміни команди/cwd/контексту сеансу з боку виклику після створення запиту на підтвердження. -- Якщо ви не хочете віддаленого виконання, установіть security у значення **deny** і приберіть pairing node для цього Mac. +- Потребує pairing Node (схвалення + token). +- Pairing Node на Gateway не є поверхнею схвалення для кожної окремої команди. Воно встановлює ідентичність/довіру до Node та видачу токена. +- Gateway застосовує грубу глобальну політику команд Node через `gateway.nodes.allowCommands` / `denyCommands`. +- На Mac це керується через **Settings → Exec approvals** (security + ask + allowlist). +- Політика `system.run` для конкретного Node — це власний файл схвалень exec цього Node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ідентифікаторів команд на gateway. +- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не потребує суворішого режиму схвалення або allowlist. +- Режим схвалення прив’язується до точного контексту запиту і, коли можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може однозначно визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання зі схваленням забороняється, замість того щоб обіцяти повне семантичне покриття. +- Для `host=node` виконання зі схваленням також зберігає канонічний підготовлений + `systemRunPlan`; подальші схвалені переспрямування повторно використовують цей збережений план, а + валідація gateway відхиляє зміни команди/cwd/контексту сесії з боку викликача після + створення запиту на схвалення. +- Якщо вам не потрібне віддалене виконання, установіть security у значення **deny** та видаліть pairing Node для цього Mac. Ця відмінність важлива для оцінки: -- Повторне підключення paired node, який рекламує інший список команд, саме по собі не є вразливістю, якщо глобальна політика Gateway та локальні підтвердження exec на node усе ще забезпечують фактичну межу виконання. -- Звіти, які трактують метадані pairing node як другий прихований шар підтвердження кожної команди, зазвичай є плутаниною щодо політики/UX, а не обходом межі безпеки. +- Повторно підключений спарений Node, який оголошує інший список команд, сам по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec на Node усе ще забезпечують фактичну межу виконання. +- Звіти, які трактують metadata pairing Node як другий прихований рівень схвалення для кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. -## Динамічні Skills (watcher / remote nodes) +## Динамічні Skills (watcher / віддалені Node) -OpenClaw може оновлювати список Skills посеред сеансу: +OpenClaw може оновлювати список Skills посеред сесії: -- **Skills watcher**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході agent. -- **Віддалені node**: підключення macOS node може зробити Skills лише для macOS доступними для використання (на основі перевірки bin). +- **Watcher Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході agent. +- **Віддалені Node**: підключення macOS Node може зробити доступними Skills лише для macOS (на основі перевірки bin). -Ставтеся до папок Skill як до **довіреного коду** й обмежуйте коло тих, хто може їх змінювати. +Сприймайте папки Skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. ## Модель загроз -Ваш AI-помічник може: +Ваш AI-асистент може: -- Виконувати довільні shell-команди +- Виконувати довільні команди оболонки - Читати/записувати файли - Отримувати доступ до мережевих сервісів - Надсилати повідомлення будь-кому (якщо ви надали йому доступ до WhatsApp) -Люди, які пишуть вам, можуть: +Люди, які можуть вам писати, можуть: -- Намагатися обдурити ваш AI, щоб він зробив щось погане -- Соціально інженерити доступ до ваших даних -- Досліджувати деталі вашої інфраструктури +- Намагатися обдурити ваш AI і змусити його зробити щось погане +- Соціальною інженерією намагатися отримати доступ до ваших даних +- Досліджувати інфраструктурні деталі -## Основна концепція: контроль доступу перед інтелектом +## Ключова ідея: контроль доступу перед інтелектом -Більшість збоїв тут — не хитрі експлойти, а сценарій «хтось написав боту, і бот зробив те, що його попросили». +Більшість збоїв тут — не вишукані експлойти, а ситуації на кшталт: «хтось написав боту, і бот зробив те, що його попросили». Позиція OpenClaw: -- **Спочатку ідентичність:** вирішіть, хто може спілкуватися з ботом (pairing у DM / allowlist / явний режим “open”). -- **Потім межі:** вирішіть, де бот має право діяти (allowlist груп + вимога згадки, інструменти, sandboxing, дозволи пристрою). -- **Модель — насамкінець:** виходьте з того, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляції мали обмежений радіус ураження. +- **Спочатку ідентичність:** вирішіть, хто може писати боту (pairing DM / allowlist / явний режим “open”). +- **Потім межі:** вирішіть, де боту дозволено діяти (allowlist груп + вимога згадки, інструменти, sandboxing, дозволи пристрою). +- **Модель — останньою:** виходьте з того, що моделлю можна маніпулювати; проєктуйте систему так, щоб маніпуляція мала обмежений радіус ураження. ## Модель авторизації команд -Slash-команди та директиви враховуються лише для **авторизованих відправників**. Авторизація визначається через allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Конфігурація](/uk/gateway/configuration) -і [Slash-команди](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, команди фактично відкриті для цього каналу. +Slash-команди та директиви виконуються лише для **авторизованих відправників**. Авторизація визначається через +allowlist/pairing channel плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) +і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist channel порожній або містить `"*"`, +команди фактично відкриті для цього channel. -`/exec` — це зручний механізм лише для сеансів авторизованих операторів. Він **не** записує config і не -змінює інші сеанси. +`/exec` — це зручна команда лише для сесії, призначена для авторизованих операторів. Вона **не** записує config і +не змінює інші сесії. -## Ризик інструментів control plane +## Ризики інструментів control plane Два вбудовані інструменти можуть вносити постійні зміни в control plane: -- `gateway` може перевіряти config через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. -- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. +- `gateway` може переглядати config через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. +- `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового chat/task. -Інструмент runtime `gateway`, доступний лише власнику, усе ще відмовляється переписувати +Інструмент runtime `gateway`, доступний лише власнику, усе одно відмовляється переписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого agent/поверхні, що обробляє недовірений вміст, типово забороняйте таке: +Для будь-якого agent/поверхні, що обробляє недовірений контент, забороняйте їх за замовчуванням: ```json5 { @@ -549,23 +555,23 @@ Slash-команди та директиви враховуються лише } ``` -`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії config/update інструмента `gateway`. +`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії `gateway` щодо config/update. -## Plugins/розширення +## Plugins -Plugins працюють **у межах того самого процесу**, що й Gateway. Ставтеся до них як до довіреного коду: +Plugins працюють **у тому самому процесі**, що й Gateway. Сприймайте їх як довірений код: -- Встановлюйте лише Plugins із джерел, яким довіряєте. -- Надавайте перевагу явним allowlist `plugins.allow`. +- Установлюйте plugins лише з джерел, яким довіряєте. +- Віддавайте перевагу явним allowlist `plugins.allow`. - Переглядайте config Plugin перед увімкненням. - Перезапускайте Gateway після змін Plugin. -- Якщо ви встановлюєте або оновлюєте Plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: +- Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: - Шлях встановлення — це каталог окремого Plugin у межах активного кореня встановлення Plugin. - - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Findings рівня `critical` типово блокують операцію. - - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (lifecycle scripts npm можуть виконувати код під час встановлення). - - Надавайте перевагу зафіксованим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. - - `--dangerously-force-unsafe-install` — лише аварійний варіант для хибнопозитивних результатів вбудованого сканування у потоках встановлення/оновлення Plugin. Він не обходить блокування політики hook `before_install` Plugin і не обходить збої сканування. - - Встановлення залежностей Skill через Gateway дотримується того самого поділу на dangerous/suspicious: вбудовані findings рівня `critical` блокують операцію, якщо виклик явно не задає `dangerouslyForceUnsafeInstall`, тоді як findings рівня suspicious, як і раніше, лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skill із ClawHub. + - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Знахідки рівня `critical` типово блокують процес. + - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (скрипти життєвого циклу npm можуть виконувати код під час встановлення). + - Віддавайте перевагу зафіксованим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` — лише для аварійних випадків, коли вбудоване сканування дає хибнопозитивний результат у потоках встановлення/оновлення Plugin. Цей прапорець не обходить блокування політики хука Plugin `before_install` і не обходить збої сканування. + - Встановлення залежностей Skill через Gateway дотримуються того самого поділу на небезпечне/підозріле: вбудовані знахідки `critical` блокують процес, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі знахідки, як і раніше, лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills з ClawHub. Докладніше: [Plugins](/uk/tools/plugin) @@ -573,11 +579,11 @@ Plugins працюють **у межах того самого процесу**, ## Модель доступу DM (pairing / allowlist / open / disabled) -Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка блокує вхідні DM **до** обробки повідомлення: +Усі поточні channel з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка відсікає вхідні DM **до** обробки повідомлення: -- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість очікуваних запитів типово обмежена **3 на канал**. +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди діють 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість запитів у стані очікування типово обмежена до **3 на channel**. - `allowlist`: невідомі відправники блокуються (без handshake pairing). -- `open`: дозволити будь-кому писати в DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явне підтвердження). +- `open`: дозволити будь-кому писати в DM (публічно). **Потребує**, щоб allowlist channel містив `"*"` (явне підтвердження). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -589,9 +595,9 @@ openclaw pairing approve Докладніше + файли на диску: [Pairing](/uk/channels/pairing) -## Ізоляція DM-сеансів (багатокористувацький режим) +## Ізоляція сесій DM (багатокористувацький режим) -Типово OpenClaw маршрутизує **усі DM в основний сеанс**, щоб ваш помічник зберігав безперервність між пристроями та каналами. Якщо боту можуть писати в DM **кілька людей** (відкриті DM або allowlist із кількох осіб), розгляньте ізоляцію DM-сеансів: +Типово OpenClaw спрямовує **усі DM в основну сесію**, щоб ваш асистент мав безперервність між пристроями й channel. Якщо **кілька людей** можуть писати боту в DM (відкриті DM або allowlist із кількома особами), розгляньте ізоляцію сесій DM: ```json5 { @@ -599,76 +605,76 @@ openclaw pairing approve } ``` -Це запобігає витоку контексту між користувачами, зберігаючи при цьому ізоляцію групових чатів. +Це запобігає витоку контексту між користувачами, зберігаючи при цьому ізоляцію групових chat. -Це межа контексту повідомлень, а не межа адміністрування хоста. Якщо користувачі є взаємно ворожими й ділять один host/config Gateway, запускайте окремі Gateway для кожної межі довіри. +Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі є взаємно змагальними й ділять той самий host/config Gateway, запускайте окремі Gateway для кожної межі довіри. ### Безпечний режим DM (рекомендовано) -Сприймайте наведений вище фрагмент як **безпечний режим DM**: +Сприймайте фрагмент вище як **безпечний режим DM**: -- Типовий варіант: `session.dmScope: "main"` (усі DM ділять один сеанс для безперервності). -- Типовий варіант локального onboarding у CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (зберігає вже наявні явні значення). -- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). -- Ізоляція одержувача між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує один сеанс у всіх каналах одного типу). +- Типово: `session.dmScope: "main"` (усі DM ділять одну сесію заради безперервності). +- Типове значення локального onboarding через CLI: записує `session.dmScope: "per-channel-peer"`, якщо параметр не задано (наявні явні значення зберігаються). +- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара channel+відправник отримує ізольований контекст DM). +- Ізоляція користувача між channel: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх channel одного типу). -Якщо ви запускаєте кілька акаунтів в одному каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина зв’язується з вами через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сеанси в одну канонічну ідентичність. Див. [Керування сеансами](/uk/concepts/session) і [Конфігурація](/uk/gateway/configuration). +Якщо ви використовуєте кілька облікових записів в одному channel, використовуйте натомість `per-account-channel-peer`. Якщо одна й та сама людина звертається до вас через кілька channel, використовуйте `session.identityLinks`, щоб об’єднати ці сесії DM в одну канонічну ідентичність. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). ## Allowlists (DM + групи) — термінологія OpenClaw має два окремі шари «хто може мене запускати?»: -- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в особисті повідомлення. - - Коли `dmPolicy="pairing"`, схвалення записуються до сховища allowlist pairing з прив’язкою до акаунта в `~/.openclaw/credentials/` (`-allowFrom.json` для типового акаунта, `--allowFrom.json` для нетипових акаунтів), а потім об’єднуються з allowlist із config. -- **Group allowlist** (специфічний для каналу): з яких саме груп/каналів/guild бот узагалі прийматиме повідомлення. +- **Allowlist DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в direct messages. + - Коли `dmPolicy="pairing"`, схвалення записуються в прив’язане до облікового запису сховище allowlist pairing у `~/.openclaw/credentials/` (`-allowFrom.json` для типового облікового запису, `--allowFrom.json` для нетипових облікових записів), а потім об’єднуються з allowlist із config. +- **Allowlist груп** (специфічний для channel): з яких груп/channel/guilds бот узагалі прийматиме повідомлення. - Типові шаблони: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові налаштування для груп на кшталт `requireMention`; коли їх задано, вони також діють як group allowlist (додайте `"*"` для збереження поведінки «дозволити всі»). - - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може запускати бота _всередині_ групового сеансу (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - - `channels.discord.guilds` / `channels.slack.channels`: allowlist для окремих поверхонь + типові правила для згадок. - - Групові перевірки виконуються в такому порядку: спочатку `groupPolicy`/group allowlist, потім активація за згадкою/відповіддю. - - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправників, такі як `groupAllowFrom`. - - **Примітка з безпеки:** ставтеся до `dmPolicy="open"` і `groupPolicy="open"` як до налаштувань останньої інстанції. Вони мають використовуватися вкрай рідко; надавайте перевагу pairing + allowlist, якщо ви не довіряєте повністю кожному учаснику кімнати. + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові налаштування для окремої групи, наприклад `requireMention`; якщо задано, це також працює як allowlist груп (додайте `"*"`, щоб зберегти поведінку «дозволити всі»). + - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може запускати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: allowlist для окремих поверхонь + типові правила згадок. + - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/allowlist груп, потім активація через згадку/відповідь. + - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправника, як-от `groupAllowFrom`. + - **Примітка щодо безпеки:** сприймайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування крайнього випадку. Їх слід використовувати якомога рідше; віддавайте перевагу pairing + allowlist, якщо тільки ви повністю не довіряєте кожному учаснику кімнати. -Докладніше: [Конфігурація](/uk/gateway/configuration) і [Групи](/uk/channels/groups) +Докладніше: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) -## Prompt injection (що це таке і чому це важливо) +## Prompt-ін’єкція (що це, чому це важливо) -Prompt injection — це коли атакувальник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «виведи вміст файлової системи», «перейди за цим посиланням і виконай команди» тощо). +Prompt-ін’єкція — це коли зловмисник створює повідомлення, яке маніпулює моделлю, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «виведи файлову систему», «перейди за цим посиланням і виконай команди» тощо). -Навіть із сильними system prompt **prompt injection не є розв’язаною проблемою**. Запобіжники у system prompt — це лише м’які рекомендації; жорстке забезпечення надходить через політику інструментів, підтвердження exec, sandboxing і allowlist каналів (і оператори можуть навмисно вимикати все це). Що реально допомагає: +Навіть за наявності сильних системних prompt, **prompt-ін’єкцію не вирішено**. Запобіжники на рівні системного prompt — це лише м’які вказівки; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlist channel (а оператори можуть вимкнути їх за задумом). Що реально допомагає на практиці: - Тримайте вхідні DM закритими (pairing/allowlist). -- У групах надавайте перевагу активації через згадку; уникайте «завжди активних» ботів у публічних кімнатах. -- Ставтеся до посилань, вкладень і вставлених інструкцій як до ворожих за замовчуванням. -- Виконуйте чутливі інструменти в sandbox; не тримайте секрети у файловій системі, доступній agent. -- Примітка: sandboxing є опційним. Якщо режим sandbox вимкнено, неявний `host=auto` розв’язується до хоста gateway. Явний `host=sandbox` усе одно переходить у безпечну відмову, бо sandbox runtime недоступний. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно відображена в config. +- У групах віддавайте перевагу активації через згадку; уникайте ботів, які «завжди слухають» у публічних кімнатах. +- За замовчуванням ставтеся до посилань, вкладень і вставлених інструкцій як до ворожих. +- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза досяжною для agent файловою системою. +- Примітка: sandboxing є opt-in. Якщо режим sandbox вимкнено, неявний `host=auto` визначається як хост gateway. Явний `host=sandbox` усе одно безпечно відмовляє, бо runtime sandbox недоступний. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно зафіксована в config. - Обмежуйте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) довіреними agent або явними allowlist. -- Якщо ви додаєте інтерпретатори в allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб inline eval-форми все одно вимагали явного підтвердження. -- Аналіз підтверджень shell також відхиляє форми POSIX parameter-expansion (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) усередині **нецитованих heredoc**, тому allowlist для тіла heredoc не зможе непомітно провести shell-розширення під виглядом звичайного тексту. Цитуйте термінатор heredoc (наприклад, `<<'EOF'`), щоб увімкнути буквальну семантику тіла; нецитовані heredoc, у яких відбулося б розширення змінних, відхиляються. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і зловживання інструментами. Для agent з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. +- Якщо ви додаєте в allowlist інтерпретатори (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval усе одно вимагали явного схвалення. +- Аналіз схвалення shell також відхиляє форми розширення параметрів POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) усередині **нецитованих heredoc**, тож allowlist-тіло heredoc не зможе непомітно провести розширення shell повз перевірку allowlist як звичайний текст. Щоб увімкнути буквальну семантику тіла, беріть термінатор heredoc у лапки (наприклад, `<<'EOF'`); нецитовані heredoc, у яких відбулося б розширення змінних, відхиляються. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt-ін’єкції та зловживання інструментами. Для agent з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, посилену щодо інструкцій. -Сигнали небезпеки, які слід вважати недовіреними: +Ознаки, які слід вважати недовіреними: - «Прочитай цей файл/URL і зроби точно те, що там написано.» -- «Ігноруй свій system prompt або правила безпеки.» -- «Розкрий свої приховані інструкції або результати інструментів.» -- «Встав повний вміст ~/.openclaw або свої журнали.» +- «Ігноруй свій системний prompt або правила безпеки.» +- «Розкрий свої приховані інструкції або результати роботи інструментів.» +- «Встав повний вміст `~/.openclaw` або свої журнали.» -## Санітарна обробка спеціальних токенів у зовнішньому вмісті +## Санітизація спеціальних токенів у зовнішньому контенті -OpenClaw видаляє поширені літерали спеціальних токенів шаблонів чату self-hosted LLM із обгорнутого зовнішнього вмісту та метаданих до того, як вони потрапляють до моделі. До охоплених сімейств маркерів входять токени ролей/ходів Qwen/ChatML, Llama, Gemma, Mistral, Phi і GPT-OSS. +OpenClaw видаляє поширені літерали спеціальних токенів шаблонів chat для self-hosted LLM із обгорнутого зовнішнього контенту та metadata до того, як вони потрапляють у модель. До покритих сімейств маркерів належать токени ролей/ходів Qwen/ChatML, Llama, Gemma, Mistral, Phi і GPT-OSS. Чому: -- Сумісні з OpenAI бекенди, які стоять перед self-hosted моделями, іноді зберігають спеціальні токени, що з’являються в тексті користувача, замість того щоб їх маскувати. Атакувальник, який може записати дані у вхідний зовнішній вміст (отриману сторінку, тіло email, вміст файлу з інструмента читання), інакше міг би ін’єктувати штучну межу ролі `assistant` або `system` і вийти за межі запобіжників обгорнутого вмісту. -- Санітарна обробка відбувається на рівні обгортання зовнішнього вмісту, тому застосовується однаково до інструментів fetch/read і до вхідного вмісту каналів, а не на рівні окремого провайдера. -- Вихідні відповіді моделі вже мають окремий санітайзер, який прибирає витоки ``, `` та подібний службовий каркас із відповідей, видимих користувачу. Санітарна обробка зовнішнього вмісту є вхідним відповідником цього механізму. +- Backends, сумісні з OpenAI, які працюють поверх self-hosted моделей, інколи зберігають спеціальні токени, що з’являються в тексті користувача, замість того щоб їх маскувати. Зловмисник, який може записати дані у вхідний зовнішній контент (завантажена сторінка, тіло email, результат інструмента читання вмісту файлу), інакше міг би вставити синтетичну межу ролі `assistant` або `system` і вийти за межі запобіжників обгорнутого контенту. +- Санітизація відбувається на рівні обгортання зовнішнього контенту, тому вона однаково застосовується до інструментів fetch/read та вхідного контенту channel, а не реалізується окремо для кожного провайдера. +- Вихідні відповіді моделі вже мають окремий санітайзер, який прибирає з видимих користувачу відповідей витік `tool_call`, `` і подібної службової структури. Санітайзер зовнішнього контенту — це вхідний відповідник цього механізму. -Це не замінює інші механізми посилення безпеки на цій сторінці — `dmPolicy`, allowlists, підтвердження exec, sandboxing і `contextVisibility` усе ще виконують основну роботу. Це закриває один конкретний обхід на рівні токенізатора у self-hosted стеках, які передають текст користувача зі спеціальними токенами без змін. +Це не замінює інші засоби посилення захисту на цій сторінці — `dmPolicy`, allowlist, схвалення exec, sandboxing і `contextVisibility` усе ще виконують основну роботу. Це закриває один конкретний обхід на рівні tokenizer для self-hosted стеків, які передають текст користувача зі збереженими спеціальними токенами. -## Прапори обходу небезпечного зовнішнього вмісту +## Прапорці обходу небезпечного зовнішнього контенту -OpenClaw містить явні прапори обходу, які вимикають безпечне обгортання зовнішнього вмісту: +OpenClaw містить явні прапорці обходу, які вимикають безпечне обгортання зовнішнього контенту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -676,138 +682,138 @@ OpenClaw містить явні прапори обходу, які вимик Рекомендації: -- У production залишайте їх не заданими/false. -- Увімкнюйте лише тимчасово для вузько обмеженого налагодження. -- Якщо ввімкнено, ізолюйте цей agent (sandbox + мінімум інструментів + окремий простір імен сеансів). +- Тримайте їх не встановленими/false у production. +- Увімкнюйте лише тимчасово для вузькоспрямованого налагодження. +- Якщо увімкнено, ізолюйте цей agent (sandbox + мінімум інструментів + окремий простір імен сесій). -Примітка щодо ризиків hooks: +Примітка про ризики hooks: -- Payload hooks — це недовірений вміст, навіть якщо доставлення відбувається із систем під вашим контролем (пошта/документи/web-вміст можуть нести prompt injection). -- Слабші рівні моделей збільшують цей ризик. Для автоматизації, керованої hooks, надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або ще суворіше), а де можливо — додавайте sandboxing. +- Payload hooks — це недовірений контент, навіть якщо доставка надходить із систем, які ви контролюєте (mail/docs/web-контент може нести prompt-ін’єкцію). +- Слабкі рівні моделей збільшують цей ризик. Для автоматизації на основі hooks віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing там, де це можливо. -### Prompt injection не потребує публічних DM +### Prompt-ін’єкція не потребує публічних DM -Навіть якщо писати боту можете **лише ви**, prompt injection усе одно може відбутися через -будь-який **недовірений вміст**, який читає бот (результати web search/fetch, сторінки браузера, -email, документи, вкладення, вставлені журнали/код). Інакше кажучи: відправник — не -єдина поверхня загрози; сам **вміст** також може містити ворожі інструкції. +Навіть якщо **лише ви** можете писати боту, prompt-ін’єкція все одно може статися через +будь-який **недовірений контент**, який читає бот (результати web search/fetch, сторінки browser, +email, docs, вкладення, вставлені журнали/код). Іншими словами: відправник — не +єдина поверхня загрози; сама **сутність контенту** також може містити ворожі інструкції. -Коли інструменти ввімкнено, типовий ризик — це витік контексту або запуск +Коли інструменти увімкнені, типовий ризик — це ексфільтрація контексту або запуск викликів інструментів. Зменшуйте радіус ураження так: -- Використовуйте **agent для читання** без інструментів або лише для читання, щоб підсумовувати недовірений вміст, - а потім передавайте резюме головному agent. +- Використовуйте **agent-читач** лише для читання або без інструментів, щоб стисло викладати недовірений контент, + а потім передавайте стислий виклад вашому основному agent. - Тримайте `web_search` / `web_fetch` / `browser` вимкненими для agent з інструментами, якщо вони не потрібні. -- Для URL-входів OpenResponses (`input_file` / `input_image`) встановлюйте жорсткі +- Для URL-входів OpenResponses (`input_file` / `input_image`) установлюйте жорсткі `gateway.http.endpoints.responses.files.urlAllowlist` і - `gateway.http.endpoints.responses.images.urlAllowlist`, а також тримайте `maxUrlParts` низьким. - Порожні allowlists трактуються як незадані; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + `gateway.http.endpoints.responses.images.urlAllowlist`, а також зберігайте мале значення `maxUrlParts`. + Порожні allowlist трактуються як не встановлені; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, якщо хочете повністю вимкнути отримання за URL. -- Для файлових входів OpenResponses декодований текст `input_file` усе одно ін’єктується як - **недовірений зовнішній вміст**. Не вважайте текст файлу довіреним лише тому, - що Gateway декодував його локально. Ін’єктований блок усе одно містить явні - маркери межі `<<>>` плюс метадані `Source: External`, - хоча на цьому шляху пропускається довший банер `SECURITY NOTICE:`. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно вбудовується як + **недовірений зовнішній контент**. Не покладайтеся на те, що текст файлу є довіреним лише тому, + що Gateway декодував його локально. Вбудований блок усе одно містить явні + маркери меж `<<>>` плюс metadata `Source: External`, + хоча цей шлях і пропускає довший банер `SECURITY NOTICE:`. - Те саме обгортання на основі маркерів застосовується, коли розуміння медіа витягує текст - із вкладених документів перед додаванням цього тексту до prompt медіа. -- Увімкнення sandboxing і суворих allowlist інструментів для будь-якого agent, що працює з недовіреним вводом. -- Не передавайте секрети в prompt; передавайте їх через env/config на хості gateway. + із прикріплених документів перед додаванням цього тексту до prompt медіа. +- Увімкнення sandboxing і суворих allowlist інструментів для будь-якого agent, який працює з недовіреним введенням. +- Тримайте секрети поза prompt; передавайте їх через env/config на хості gateway. -### Self-hosted LLM-бекенди +### Self-hosted backends LLM -Сумісні з OpenAI self-hosted бекенди, такі як vLLM, SGLang, TGI, LM Studio -або власні стеки токенізаторів Hugging Face, можуть відрізнятися від хостованих провайдерів у тому, -як обробляються спеціальні токени шаблонів чату. Якщо бекенд токенізує буквальні рядки +Backends self-hosted, сумісні з OpenAI, такі як vLLM, SGLang, TGI, LM Studio, +або власні стеки tokenizer Hugging Face, можуть відрізнятися від хостингових провайдерів у тому, +як обробляються спеціальні токени шаблонів chat. Якщо backend токенізує буквальні рядки на кшталт `<|im_start|>`, `<|start_header_id|>` або `` як -структурні токени шаблону чату всередині користувацького вмісту, недовірений текст може спробувати -підробити межі ролей на рівні токенізатора. +структурні токени шаблону chat усередині користувацького контенту, недовірений текст може спробувати +підробити межі ролей на рівні tokenizer. -OpenClaw видаляє поширені літерали спеціальних токенів сімейств моделей із обгорнутого -зовнішнього вмісту перед передаванням його моделі. Залишайте обгортання зовнішнього вмісту -увімкненим і, за можливості, надавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні -токени у вмісті, наданому користувачем. Хостовані провайдери, такі як OpenAI -і Anthropic, уже застосовують власну санітарну обробку на боці запиту. +OpenClaw видаляє поширені літерали спеціальних токенів сімейств моделей з обгорнутого +зовнішнього контенту перед передаванням його в модель. Тримайте обгортання зовнішнього +контенту увімкненим і, за можливості, віддавайте перевагу налаштуванням backend, які розділяють або екранують спеціальні +токени в контенті, наданому користувачем. Хостингові провайдери, такі як OpenAI +та Anthropic, уже застосовують власну санітизацію на стороні запиту. -### Сила моделі (примітка з безпеки) +### Сила моделі (примітка щодо безпеки) -Стійкість до prompt injection **не** є однаковою в усіх рівнях моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та викрадення інструкцій, особливо за наявності ворожих prompt. +Стійкість до prompt-ін’єкцій **не** є однаковою для всіх рівнів моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та перехоплення інструкцій, особливо за наявності змагальних prompt. -Для agent з увімкненими інструментами або agent, які читають недовірений вміст, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. +Для agent з увімкненими інструментами або agent, які читають недовірений контент, ризик prompt-ін’єкції зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте модель останнього покоління найкращого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для agent з увімкненими інструментами або недовірених inbox; ризик prompt injection занадто високий. -- Якщо ви змушені використовувати меншу модель, **зменшуйте радіус ураження** (інструменти лише для читання, сильний sandboxing, мінімальний доступ до файлової системи, суворі allowlist). -- Під час роботи з малими моделями **увімкніть sandboxing для всіх сеансів** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються дуже жорстко. -- Для персональних помічників лише для чату з довіреним вводом і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для agent з увімкненими інструментами або недовірених inbox; ризик prompt-ін’єкції надто високий. +- Якщо ви змушені використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Під час роботи з малими моделями **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються жорстко. +- Для персональних асистентів лише для chat із довіреним входом і без інструментів менші моделі зазвичай підходять. ## Reasoning і докладний вивід у групах -`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє reasoning, вивід +`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішні міркування, вивід інструментів або діагностику Plugin, які -не призначалися для публічного каналу. У групових середовищах ставтеся до них як до **режимів налагодження** -і тримайте вимкненими, якщо тільки вони вам явно не потрібні. +не призначалися для публічного channel. У групових сценаріях сприймайте їх як **лише +для налагодження** і тримайте вимкненими, якщо вони вам явно не потрібні. Рекомендації: - Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. - Якщо ви їх увімкнули, робіть це лише в довірених DM або жорстко контрольованих кімнатах. -- Пам’ятайте: докладний вивід і trace можуть містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. +- Пам’ятайте: вивід verbose і trace може містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. ## Посилення конфігурації (приклади) -### 0) Дозволи на файли +### 0) Дозволи файлів Тримайте config + state приватними на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) -- `~/.openclaw`: `700` (лише користувач) +- `~/.openclaw`: `700` (лише для користувача) -`openclaw doctor` може попередити про це та запропонувати посилити ці дозволи. +`openclaw doctor` може попередити та запропонувати посилити ці дозволи. -### 0.4) Мережева експозиція (bind + port + firewall) +### 0.4) Мережеве відкриття (bind + порт + firewall) Gateway мультиплексує **WebSocket + HTTP** на одному порту: -- Типово: `18789` +- Типовий: `18789` - Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` -Ця HTTP-поверхня включає Control UI і хост canvas: +Ця поверхня HTTP включає Control UI і хост canvas: - Control UI (ресурси SPA) (типовий базовий шлях `/`) -- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; ставтеся до цього як до недовіреного вмісту) +- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; ставтеся до цього як до недовіреного контенту) -Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної web-сторінки: +Якщо ви завантажуєте контент canvas у звичайному browser, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: - Не відкривайте хост canvas для недовірених мереж/користувачів. -- Не змушуйте вміст canvas ділити той самий origin із привілейованими web-поверхнями, якщо ви повністю не розумієте наслідків. +- Не змушуйте контент canvas використовувати той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. Режим bind визначає, де Gateway слухає з’єднання: - `gateway.bind: "loopback"` (типово): можуть підключатися лише локальні клієнти. -- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише разом з автентифікацією gateway (спільний token/password або правильно налаштований non-loopback trusted proxy) і справжнім firewall. +- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише з auth gateway (спільний token/password або правильно налаштований trusted proxy поза loopback) і справжнім firewall. Практичні правила: -- Надавайте перевагу Tailscale Serve замість bind до LAN (Serve тримає Gateway на loopback, а доступом керує Tailscale). -- Якщо вам обов’язково потрібен bind до LAN, обмежте порт у firewall суворим allowlist IP-джерел; не робіть широкий port-forward. +- Віддавайте перевагу Tailscale Serve замість bind у LAN (Serve залишає Gateway на loopback, а доступ обробляє Tailscale). +- Якщо ви все ж маєте виконати bind у LAN, обмежте порт через firewall вузьким allowlist вихідних IP-адрес; не робіть широке порт-форвардинг-відкриття. - Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. -### 0.4.1) Публікація Docker-портів + UFW (`DOCKER-USER`) +### 0.4.1) Публікація портів Docker + UFW (`DOCKER-USER`) -Якщо ви запускаєте OpenClaw у Docker на VPS, пам’ятайте, що опубліковані порти container -(`-p HOST:CONTAINER` або `ports:` у Compose) маршрутизуються через ланцюги переспрямування Docker, +Якщо ви запускаєте OpenClaw з Docker на VPS, пам’ятайте, що опубліковані порти container +(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги переспрямування Docker, а не лише через правила `INPUT` хоста. -Щоб трафік Docker відповідав вашій політиці firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюг обробляється до власних правил accept Docker). -На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` -і все одно застосовують ці правила до бекенда nftables. +Щоб трафік Docker відповідав політиці вашого firewall, застосовуйте правила в +`DOCKER-USER` (цей ланцюг перевіряється до власних правил дозволу Docker). +У багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` +і все одно застосовують ці правила до backend nftables. Мінімальний приклад allowlist (IPv4): @@ -828,12 +834,12 @@ Gateway мультиплексує **WebSocket + HTTP** на одному пор COMMIT ``` -Для IPv6 є окремі таблиці. Додайте відповідну політику до `/etc/ufw/after6.rules`, якщо +Для IPv6 використовуються окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо Docker IPv6 увімкнено. Уникайте жорсткого задання назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково -обійти ваше правило deny. +обійти ваше правило заборони. Швидка перевірка після перезавантаження: @@ -844,22 +850,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -Очікувані зовнішні порти мають бути лише ті, які ви навмисно відкрили (для більшості +Очікувані зовнішні порти мають бути лише тими, які ви навмисно відкрили (для більшості конфігурацій: SSH + порти вашого reverse proxy). -### 0.4.2) Виявлення через mDNS/Bonjour (розкриття інформації) +### 0.4.2) Виявлення mDNS/Bonjour (розкриття інформації) -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для виявлення локальними пристроями. У повному режимі це включає записи TXT, які можуть розкривати операційні деталі: - `cliPath`: повний шлях файлової системи до бінарного файла CLI (розкриває ім’я користувача та місце встановлення) - `sshPort`: рекламує доступність SSH на хості - `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування операційної безпеки:** трансляція інфраструктурних деталей полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи у файловій системі та доступність SSH, допомагає атакувальникам картографувати ваше середовище. +**Міркування щодо операційної безпеки:** трансляція інфраструктурних деталей полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та доступність SSH, допомагає зловмисникам картографувати ваше середовище. **Рекомендації:** -1. **Мінімальний режим** (типовий, рекомендований для відкритих gateway): не включає чутливі поля до трансляцій mDNS: +1. **Мінімальний режим** (типовий, рекомендований для відкритих gateway): не включає чутливі поля в трансляції mDNS: ```json5 { @@ -869,7 +875,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Повністю вимкніть**, якщо вам не потрібне локальне виявлення пристроїв: +2. **Повністю вимкніть**, якщо вам не потрібне виявлення локальними пристроями: ```json5 { @@ -879,7 +885,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Повний режим** (опційно): включає `cliPath` + `sshPort` у TXT-записи: +3. **Повний режим** (opt-in): включає `cliPath` + `sshPort` у записи TXT: ```json5 { @@ -889,20 +895,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін config. +4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін у config. -У мінімальному режимі Gateway усе одно транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Apps, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане WebSocket-з’єднання. +У мінімальному режимі Gateway усе ще транслює достатньо інформації для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Apps, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане з’єднання WebSocket. -### 0.5) Захистіть WebSocket Gateway (локальна автентифікація) +### 0.5) Захистіть WebSocket Gateway (локальний auth) -Автентифікація Gateway **типово обов’язкова**. Якщо не налаштовано -жодного коректного шляху автентифікації gateway, Gateway відхиляє WebSocket-з’єднання -(безпечна відмова). +Auth Gateway **обов’язковий за замовчуванням**. Якщо не налаштовано коректний шлях auth gateway, +Gateway відмовляє у з’єднаннях WebSocket (безпечна відмова). Onboarding типово генерує token (навіть для loopback), тому -локальні клієнти повинні проходити автентифікацію. +локальні клієнти мають проходити автентифікацію. -Установіть token, щоб **усі** WS-клієнти мусили автентифікуватися: +Установіть token, щоб **усі** клієнти WS мали проходити автентифікацію: ```json5 { @@ -914,143 +919,146 @@ Onboarding типово генерує token (навіть для loopback), т Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. -Примітка: `gateway.remote.token` / `.password` — це джерела клієнтських облікових даних. Вони -самі по собі **не** захищають локальний WS-доступ. +Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. +Самі по собі вони **не** захищають локальний доступ WS. Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. -Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, -розв’язання переходить у безпечну відмову (без маскування через fallback remote). -Необов’язково: зафіксуйте віддалений TLS через `gateway.remote.tlsFingerprint` під час використання `wss://`. -Нешифрований `ws://` типово дозволений лише для loopback. Для довірених шляхів у приватній мережі +Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через +SecretRef і його не вдається визначити, визначення завершується безпечним блокуванням (без маскування через remote fallback). +Необов’язково: фіксуйте віддалений TLS через `gateway.remote.tlsFingerprint` під час використання `wss://`. +Нешифрований `ws://` типово дозволено лише для loopback. Для довірених шляхів у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. -Локальне pairing пристрою: +Локальне pairing пристроїв: -- Pairing пристрою автоматично схвалюється для прямих локальних loopback-з’єднань, щоб - робота клієнтів на тому самому хості була безперешкодною. -- OpenClaw також має вузький шлях backend/container-local self-connect для - довірених допоміжних потоків зі спільним секретом. -- Підключення через tailnet і LAN, включно з bind до tailnet на тому самому хості, розглядаються як +- Pairing пристроїв автоматично схвалюється для прямих локальних підключень loopback, щоб + забезпечити зручність для клієнтів на тому самому хості. +- OpenClaw також має вузький шлях самопідключення для локального backend/container + для довірених helper-потоків зі спільним секретом. +- Підключення через tailnet і LAN, включно з bind через tailnet на тому самому хості, розглядаються як віддалені для pairing і все одно потребують схвалення. -Режими автентифікації: +Режими auth: -- `gateway.auth.mode: "token"`: спільний bearer token (рекомендовано для більшості конфігурацій). -- `gateway.auth.mode: "password"`: автентифікація паролем (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). -- `gateway.auth.mode: "trusted-proxy"`: довіра до reverse proxy з контролем ідентичності, який автентифікує користувачів і передає ідентичність через заголовки (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "token"`: спільний bearer-token (рекомендовано для більшості конфігурацій). +- `gateway.auth.mode: "password"`: auth за паролем (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). +- `gateway.auth.mode: "trusted-proxy"`: довіряти reverse proxy з підтримкою ідентичності, який автентифікує користувачів і передає ідентичність через заголовки (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (token/password): -1. Згенеруйте/встановіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). +1. Згенеруйте/установіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). 2. Перезапустіть Gateway (або перезапустіть застосунок macOS, якщо він керує Gateway). 3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). -4. Перевірте, що зі старими обліковими даними підключитися більше неможливо. +4. Переконайтеся, що зі старими обліковими даними підключитися більше не можна. ### 0.6) Заголовки ідентичності Tailscale Serve Коли `gateway.auth.allowTailscale` має значення `true` (типово для Serve), OpenClaw -приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації Control -UI/WebSocket. OpenClaw перевіряє ідентичність, розв’язуючи адресу -`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і -зіставляючи її із заголовком. Це спрацьовує лише для запитів, які потрапляють на loopback -і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, ін’єктовані Tailscale. +приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації +Control UI/WebSocket. OpenClaw перевіряє ідентичність, визначаючи +адресу `x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) +і зіставляючи її із заголовком. Це спрацьовує лише для запитів, які потрапляють на loopback +і містять `x-forwarded-for`, `x-forwarded-proto` і `x-forwarded-host`, як +додає Tailscale. Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` -серіалізуються до того, як лімітер зафіксує помилку. Тому одночасні неправильні повторні спроби -від одного клієнта Serve можуть негайно заблокувати другу спробу, -а не «проскочити» як дві звичайні невідповідності. +серіалізуються до того, як лімітер зафіксує збій. Тому паралельні невдалі повторні спроби +від одного клієнта Serve можуть одразу заблокувати другу спробу, +а не пройти як дві звичайні невідповідності. + Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують автентифікацію через заголовки ідентичності Tailscale. Вони й далі дотримуються -налаштованого в gateway режиму автентифікації HTTP. +**не** використовують auth через заголовки ідентичності Tailscale. Вони, як і раніше, дотримуються +налаштованого режиму auth HTTP gateway. Важлива примітка щодо меж: -- Bearer-автентифікація HTTP у Gateway фактично дає доступ оператора за принципом «усе або нічого». -- Ставтеся до облікових даних, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як до повноцінних операторських секретів із повним доступом до цього gateway. -- На сумісній з OpenAI HTTP-поверхні bearer-автентифікація зі спільним секретом відновлює повні типові області повноважень оператора (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів agent; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. -- Семантика областей повноважень на HTTP на рівні окремого запиту застосовується лише тоді, коли запит надходить із режиму з ідентичністю, такого як автентифікація trusted proxy або `gateway.auth.mode="none"` на приватному ingress. -- У цих режимах з ідентичністю, якщо `x-openclaw-scopes` не задано, використовується типовий набір областей повноважень оператора; надсилайте цей заголовок явно, якщо хочете вужчий набір. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer-автентифікація token/password там теж трактуються як повний операторський доступ, тоді як режими з ідентичністю все ще враховують оголошені області повноважень. -- Не діліться цими обліковими даними з недовіреними викликами; надавайте перевагу окремим Gateway для кожної межі довіри. +- Bearer auth HTTP Gateway фактично дає повний або нульовий операторський доступ. +- Ставтеся до облікових даних, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як до повноцінних операторських секретів повного доступу для цього gateway. +- На OpenAI-сумісній поверхні HTTP bearer auth зі спільним секретом відновлює повні типові операторські області (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів agent; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. +- Семантика областей на рівні окремого запиту в HTTP застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як auth через trusted proxy або `gateway.auth.mode="none"` на приватному вході. +- У цих режимах, що несуть ідентичність, якщо `x-openclaw-scopes` не задано, використовується типовий набір операторських областей; надсилайте цей заголовок явно, коли хочете вужчий набір областей. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там також вважається повним операторським доступом, тоді як режими з ідентичністю, як і раніше, дотримуються оголошених областей. +- Не діліться цими обліковими даними з недовіреними викликачами; віддавайте перевагу окремим Gateway для кожної межі довіри. -**Припущення довіри:** автентифікація Serve без token виходить із того, що хост gateway є довіреним. -Не вважайте це захистом від ворожих процесів на тому самому хості. Якщо на хості gateway +**Припущення довіри:** auth Serve без token виходить із того, що хост gateway є довіреним. +Не розглядайте це як захист від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явну автентифікацію зі спільним секретом через `gateway.auth.mode: "token"` або +і вимагайте явний auth зі спільним секретом через `gateway.auth.mode: "token"` або `"password"`. -**Правило безпеки:** не пересилайте ці заголовки зі свого reverse proxy. Якщо +**Правило безпеки:** не пересилайте ці заголовки через власний reverse proxy. Якщо ви завершуєте TLS або ставите proxy перед gateway, вимкніть -`gateway.auth.allowTailscale` і використовуйте автентифікацію зі спільним секретом (`gateway.auth.mode: -"token"` або `"password"`) або натомість [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). +`gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: +"token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) +натомість. Довірені proxy: -- Якщо ви завершуєте TLS перед Gateway, задайте `gateway.trustedProxies` як IP-адреси вашого proxy. -- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP для визначення IP клієнта під час локальних перевірок pairing і HTTP auth/local checks. +- Якщо ви завершуєте TLS перед Gateway, установіть `gateway.trustedProxies` на IP-адреси вашого proxy. +- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP-адрес, щоб визначати IP клієнта для перевірок локального pairing і перевірок HTTP auth/local. - Переконайтеся, що ваш proxy **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. Див. [Tailscale](/uk/gateway/tailscale) і [Огляд Web](/web). -### 0.6.1) Керування браузером через host node (рекомендовано) +### 0.6.1) Керування browser через хост node (рекомендовано) -Якщо ваш Gateway є віддаленим, але браузер працює на іншій машині, запускайте **host node** -на машині з браузером і дозвольте Gateway проксіювати браузерні дії (див. [Інструмент browser](/uk/tools/browser)). -Ставтеся до pairing node як до адміністраторського доступу. +Якщо ваш Gateway є віддаленим, але browser працює на іншій машині, запускайте **хост node** +на машині з browser і дозвольте Gateway проксувати дії browser (див. [Інструмент browser](/uk/tools/browser)). +Сприймайте pairing node як адміністративний доступ. Рекомендований шаблон: -- Тримайте Gateway і host node в одній tailnet (Tailscale). -- Pair node навмисно; вимкніть проксі-маршрутизацію браузера, якщо вона вам не потрібна. +- Тримайте Gateway і хост node в одній tailnet (Tailscale). +- Виконуйте pairing node свідомо; вимикайте проксі-маршрутизацію browser, якщо вона вам не потрібна. Уникайте: - Відкриття relay/control-портів у LAN або публічному інтернеті. -- Tailscale Funnel для кінцевих точок керування браузером (публічна експозиція). +- Tailscale Funnel для кінцевих точок керування browser (публічне відкриття). ### 0.7) Секрети на диску (чутливі дані) -Вважайте, що будь-що в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: +Вважайте, що все в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: config може містити токени (gateway, remote gateway), налаштування провайдерів і allowlist. -- `credentials/**`: облікові дані каналів (приклад: облікові дані WhatsApp), allowlist pairing, застарілі імпорти OAuth. +- `openclaw.json`: config може містити токени (gateway, віддалений gateway), налаштування провайдерів і allowlist. +- `credentials/**`: облікові дані channel (наприклад, creds WhatsApp), allowlist pairing, застарілі імпорти OAuth. - `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени та необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): payload секретів із файлу, який використовують провайдери SecretRef типу `file` (`secrets.providers`). +- `secrets.json` (необов’язково): вміст секретів у файлі, який використовують провайдери SecretRef типу `file` (`secrets.providers`). - `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються під час виявлення. -- `agents//sessions/**`: транскрипти сеансів (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. -- пакети вбудованих Plugin: встановлені Plugins (разом із їхніми `node_modules/`). -- `sandboxes/**`: workspace sandbox інструментів; там можуть накопичуватися копії файлів, які ви читаєте/записуєте всередині sandbox. +- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + metadata маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. +- пакети bundled Plugin: встановлені plugins (разом із їхніми `node_modules/`). +- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читали/записували всередині sandbox. -Поради щодо посилення: +Поради щодо посилення захисту: - Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). - Використовуйте повне шифрування диска на хості gateway. -- Якщо хост спільний, надавайте перевагу окремому обліковому запису користувача ОС для Gateway. +- Якщо хост є спільним, віддавайте перевагу окремому обліковому запису користувача ОС для Gateway. -### 0.8) Файли `.env` workspace +### 0.8) Файли `.env` у workspace OpenClaw завантажує локальні для workspace файли `.env` для agent та інструментів, але ніколи не дозволяє цим файлам непомітно перевизначати керування runtime gateway. - Будь-який ключ, що починається з `OPENCLAW_*`, блокується в недовірених файлах `.env` workspace. -- Блокування працює за принципом fail-closed: нова змінна керування runtime, додана в майбутньому релізі, не може бути успадкована з закоміченого або підкладеного атакувальником `.env`; ключ ігнорується, а gateway зберігає власне значення. -- Довірені змінні середовища процесу/ОС (власна shell gateway, модуль launchd/systemd, app bundle) усе ще застосовуються — це обмеження стосується лише завантаження файлів `.env`. +- Блокування працює в режимі fail-closed: нова змінна керування runtime, додана в майбутньому релізі, не може бути успадкована з `.env`, що потрапив до репозиторію або був наданий зловмисником; такий ключ ігнорується, а gateway зберігає власне значення. +- Довірені змінні середовища процесу/ОС (власна shell gateway, модуль launchd/systemd, app bundle) як і раніше застосовуються — це обмеження стосується лише завантаження файлів `.env`. -Чому: файли `.env` workspace часто лежать поруч із кодом agent, випадково потрапляють у commit або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапора `OPENCLAW_*` у майбутньому ніколи не призведе до регресії в тихе успадкування зі стану workspace. +Чому: файли `.env` workspace часто лежать поруч із кодом agent, випадково потрапляють у коміти або записуються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` у майбутньому ніколи не призведе до регресії у вигляді тихого успадкування зі стану workspace. -### 0.9) Логи + транскрипти (редагування + зберігання) +### 0.9) Журнали + транскрипти (редагування + зберігання) -Логи та транскрипти можуть розкривати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: +Журнали та транскрипти можуть призводити до витоку чутливої інформації, навіть якщо контроль доступу налаштовано правильно: -- Логи Gateway можуть містити зведення інструментів, помилки та URL. -- Транскрипти сеансів можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. +- Журнали Gateway можуть містити підсумки інструментів, помилки та URL. +- Транскрипти сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. Рекомендації: -- Залишайте ввімкненим редагування зведень інструментів (`logging.redactSensitive: "tools"`; типово). -- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). -- Під час поширення діагностики надавайте перевагу `openclaw status --all` (зручно для вставлення, секрети приховано) замість сирих логів. -- Видаляйте старі транскрипти сеансів і лог-файли, якщо вам не потрібно довге зберігання. +- Тримайте ввімкненим редагування підсумків інструментів (`logging.redactSensitive: "tools"`; типово). +- Додавайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). +- Коли ділитеся діагностикою, віддавайте перевагу `openclaw status --all` (зручно вставляти, секрети відредаговано), а не сирим журналам. +- Якщо вам не потрібне довге зберігання, очищуйте старі транскрипти сесій і файли журналів. -Докладніше: [Логування](/uk/gateway/logging) +Докладніше: [Журналювання](/uk/gateway/logging) ### 1) DM: pairing за замовчуванням @@ -1082,31 +1090,31 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -У групових чатах відповідайте лише за явної згадки. +У групових chat відповідайте лише за явної згадки. ### 3) Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі номера телефону розгляньте запуск вашого AI на окремому номері, відмінному від особистого: +Для channel на основі телефонного номера розгляньте запуск вашого AI на окремому номері телефону, відмінному від особистого: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: AI обробляє ці розмови з відповідними межами +- Номер бота: AI обробляє їх із відповідними межами -### 4) Режим лише для читання (через sandbox + інструменти) +### 4) Режим лише читання (через sandbox + інструменти) -Ви можете побудувати профіль лише для читання, поєднавши: +Ви можете створити профіль лише для читання, поєднавши: -- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` без доступу до workspace) -- allow/deny-списки інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо. +- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` для повної відсутності доступу до workspace) +- списки allow/deny інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо -Додаткові варіанти посилення: +Додаткові варіанти посилення захисту: -- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти поза каталогом workspace, навіть якщо sandboxing вимкнено. Встановлюйте `false` лише якщо ви навмисно хочете, щоб `apply_patch` торкався файлів поза workspace. -- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автозавантаження зображень у native prompt каталогом workspace (корисно, якщо ви сьогодні дозволяєте абсолютні шляхи і хочете мати один спільний запобіжник). -- Звужуйте корені файлової системи: уникайте широких коренів, таких як ваш домашній каталог, для workspace agent/workspace sandbox. Широкі корені можуть відкрити інструментам файлової системи доступ до чутливих локальних файлів (наприклад state/config у `~/.openclaw`). +- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти поза каталогом workspace, навіть коли sandboxing вимкнено. Установлюйте `false` лише тоді, коли ви свідомо хочете, щоб `apply_patch` працював із файлами поза workspace. +- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автозавантаження native prompt image каталогом workspace (корисно, якщо ви зараз дозволяєте абсолютні шляхи й хочете один загальний запобіжник). +- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от ваш домашній каталог, для workspace agent/робочих просторів sandbox. Широкі корені можуть відкривати доступ до чутливих локальних файлів (наприклад, state/config у `~/.openclaw`) для файлових інструментів. -### 5) Безпечна базова конфігурація (скопіювати/вставити) +### 5) Безпечний базовий профіль (скопіювати/вставити) -Один «безпечний типовий» config, який зберігає Gateway приватним, вимагає pairing у DM і уникає завжди активних групових ботів: +Одна «безпечна типова» config, яка тримає Gateway приватним, вимагає pairing для DM і уникає ботів, що завжди активні в групах: ```json5 { @@ -1125,69 +1133,69 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого agent, який не є власником (приклад нижче в розділі «Профілі доступу на рівні agent»). +Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого agent, що не є власником (приклад нижче в розділі «Профілі доступу для окремих agent»). -Вбудована базова конфігурація для ходів agent, керованих чатом: відправники, які не є власником, не можуть використовувати інструменти `cron` або `gateway`. +Вбудований базовий профіль для ходів agent, керованих chat: відправники, які не є власниками, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) -Окрема документація: [Sandboxing](/uk/gateway/sandboxing) +Окремий документ: [Sandboxing](/uk/gateway/sandboxing) Два взаємодоповнювальні підходи: -- **Запускайте весь Gateway у Docker** (межа container): [Docker](/uk/install/docker) -- **Sandbox інструментів** (`agents.defaults.sandbox`, host gateway + інструменти, ізольовані sandbox; Docker — типовий бекенд): [Sandboxing](/uk/gateway/sandboxing) +- **Запуск усього Gateway в Docker** (межа container): [Docker](/uk/install/docker) +- **Sandbox для інструментів** (`agents.defaults.sandbox`, gateway на хості + інструменти, ізольовані sandbox; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) -Примітка: щоб запобігти міжагентному доступу, залишайте `agents.defaults.sandbox.scope` у значенні `"agent"` (типово) -або використовуйте `"session"` для суворішої ізоляції на рівні сеансу. `scope: "shared"` використовує +Примітка: щоб запобігти доступу між agent, тримайте `agents.defaults.sandbox.scope` на `"agent"` (типово) +або `"session"` для суворішої ізоляції кожної сесії. `scope: "shared"` використовує один спільний container/workspace. Також враховуйте доступ agent до workspace всередині sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) не дає доступу до workspace agent; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) тримає workspace agent недоступним; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` - `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace agent лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace agent для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими та канонізованими шляхами джерела. Трюки з батьківськими symlink і канонічними псевдонімами домашнього каталогу все одно переходять у безпечну відмову, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у home ОС. +- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонізованими шляхами джерела. Трюки з батьківськими symlink і канонічними псевдонімами домашнього каталогу все одно безпечно блокуються, якщо вони визначаються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у домашньому каталозі ОС. -Важливо: `tools.elevated` — це глобальний аварійний вихід із базового режиму, який запускає exec поза sandbox. Ефективний host типово дорівнює `gateway`, або `node`, якщо ціль exec налаштовано як `node`. Тримайте `tools.elevated.allowFrom` суворо обмеженим і не вмикайте його для сторонніх. Ви можете додатково обмежити elevated для окремих agent через `agents.list[].tools.elevated`. Див. [Режим Elevated](/uk/tools/elevated). +Важливо: `tools.elevated` — це глобальний аварійний вихід із базового профілю, який запускає exec поза sandbox. Ефективний хост за замовчуванням — `gateway`, або `node`, коли ціль exec налаштовано на `node`. Тримайте `tools.elevated.allowFrom` вузьким і не вмикайте його для сторонніх. Ви також можете додатково обмежити elevated для окремих agent через `agents.list[].tools.elevated`. Див. [Режим Elevated](/uk/tools/elevated). -### Запобіжник делегування підagent +### Запобіжник делегування субагентів -Якщо ви дозволяєте інструменти сеансів, ставтеся до делегованих запусків підagent як до ще одного рішення про межі: +Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як ще одне рішення щодо меж: - Забороняйте `sessions_spawn`, якщо agent справді не потребує делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні agent обмеженими відомо безпечними цільовими agent. -- Для будь-якого workflow, який обов’язково має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). -- `sandbox: "require"` швидко завершується помилкою, якщо дочірній runtime не працює в sandbox. +- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` для окремих agent обмеженими до відомо безпечних цільових agent. +- Для будь-якого процесу, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` негайно завершується помилкою, якщо цільовий дочірній runtime не працює в sandbox. -## Ризики керування браузером +## Ризики керування browser -Увімкнення керування браузером дає моделі можливість керувати реальним браузером. -Якщо в цьому профілі браузера вже є активні сеанси входу, модель може -отримати доступ до цих акаунтів і даних. Ставтеся до профілів браузера як до **чутливого стану**: +Увімкнення керування browser дає моделі можливість керувати реальним browser. +Якщо цей профіль browser уже містить активні сеанси входу, модель може +отримати доступ до цих облікових записів і даних. Сприймайте профілі browser як **чутливий стан**: -- Надавайте перевагу окремому профілю для agent (типовий профіль `openclaw`). +- Віддавайте перевагу окремому профілю для agent (типовий профіль `openclaw`). - Не спрямовуйте agent на ваш особистий щоденний профіль. -- Тримайте керування браузером на host вимкненим для agent у sandbox, якщо ви їм не довіряєте. -- Окремий loopback API керування браузером враховує лише автентифікацію зі спільним секретом - (bearer-автентифікація token gateway або пароль gateway). Він не використовує +- Тримайте керування browser на хості вимкненим для agent у sandbox, якщо ви їм не довіряєте. +- Автономний loopback API керування browser приймає лише auth зі спільним секретом + (bearer auth через token gateway або пароль gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Ставтеся до завантажень браузера як до недовіреного вводу; надавайте перевагу ізольованому каталогу завантажень. -- За можливості вимикайте синхронізацію браузера/менеджери паролів у профілі agent (це зменшує радіус ураження). -- Для віддалених Gateway вважайте, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. -- Тримайте Gateway і host node доступними лише через tailnet; не відкривайте порти керування браузером у LAN або публічному інтернеті. -- Вимикайте проксі-маршрутизацію браузера, якщо вона вам не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим Chrome MCP existing-session **не** є «безпечнішим»; він може діяти від вашого імені всюди, куди має доступ цей профіль Chrome на host. +- Сприймайте завантаження browser як недовірений вхід; віддавайте перевагу ізольованому каталогу завантажень. +- Якщо можливо, вимикайте синхронізацію browser/password managers у профілі agent (це зменшує радіус ураження). +- Для віддалених gateway вважайте, що «керування browser» еквівалентне «операторському доступу» до всього, до чого може дістатися цей профіль. +- Тримайте Gateway і хости node лише в tailnet; уникайте відкриття портів керування browser у LAN або публічному інтернеті. +- Вимикайте проксі-маршрутизацію browser, якщо вона вам не потрібна (`gateway.nodes.browser.mode="off"`). +- Режим Chrome MCP existing-session **не є** «безпечнішим»; він може діяти від вашого імені в усьому, до чого має доступ профіль Chrome цього хоста. -### Політика SSRF браузера (сувора за замовчуванням) +### Політика SSRF browser (сувора за замовчуванням) -Політика навігації браузера в OpenClaw сувора за замовчуванням: приватні/внутрішні призначення залишаються заблокованими, якщо ви явно не дозволите їх. +Політика навігації browser в OpenClaw є суворою за замовчуванням: приватні/внутрішні адреси залишаються заблокованими, якщо ви явно не виконали opt-in. -- Типовий варіант: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація браузера продовжує блокувати приватні/внутрішні/спеціальні адреси. +- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація browser і далі блокує приватні/внутрішні/спеціальні адреси призначення. - Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. -- Режим із явним дозволом: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/спеціальні адреси. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки хостів, включно із заблокованими іменами на кшталт `localhost`) для явних винятків. -- Навігація перевіряється до запиту та повторно перевіряється за принципом best-effort на фінальному `http(s)` URL після навігації, щоб зменшити ризик pivot через redirect. +- Режим opt-in: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/спеціальні адреси призначення. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для хостів, включно із заблокованими іменами, такими як `localhost`) для явних винятків. +- Навігація перевіряється до запиту і повторно перевіряється в режимі best-effort за фінальним URL `http(s)` після навігації, щоб зменшити можливості обходу через redirect. Приклад суворої політики: @@ -1203,17 +1211,17 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -## Профілі доступу на рівні agent (multi-agent) +## Профілі доступу для окремих agent (multi-agent) -За маршрутизації multi-agent кожен agent може мати власні sandbox і політику інструментів: +Для маршрутизації multi-agent кожен agent може мати власні sandbox + політику інструментів: використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного agent. -Повні подробиці та правила пріоритету див. у [Sandbox і інструменти Multi-Agent](/uk/tools/multi-agent-sandbox-tools). +Повні відомості та правила пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). Типові сценарії використання: - Персональний agent: повний доступ, без sandbox -- Сімейний/робочий agent: sandbox + інструменти лише для читання -- Публічний agent: sandbox + без інструментів файлової системи/оболонки +- Сімейний/робочий agent: у sandbox + інструменти лише для читання +- Публічний agent: у sandbox + без інструментів файлової системи/оболонки ### Приклад: повний доступ (без sandbox) @@ -1255,7 +1263,7 @@ OpenClaw завантажує локальні для workspace файли `.env } ``` -### Приклад: без доступу до файлової системи/оболонки (дозволено повідомлення провайдера) +### Приклад: без доступу до файлової системи/оболонки (дозволено messaging провайдера) ```json5 { @@ -1269,9 +1277,9 @@ OpenClaw завантажує локальні для workspace файли `.env scope: "agent", workspaceAccess: "none", }, - // Інструменти сеансів можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти - // поточним сеансом + сеансами запущених підagent, але за потреби ви можете ще більше це обмежити. - // Див. `tools.sessions.visibility` у довіднику з конфігурації. + // Інструменти сесій можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти + // поточною сесією + сесіями запущених субагентів, але за потреби ви можете затиснути межі ще сильніше. + // Див. `tools.sessions.visibility` у довіднику конфігурації. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1308,15 +1316,15 @@ OpenClaw завантажує локальні для workspace файли `.env ## Що сказати вашому AI -Включіть рекомендації з безпеки до system prompt вашого agent: +Додайте рекомендації з безпеки до системного prompt вашого agent: ``` -## Правила безпеки -- Ніколи не діліться списками каталогів або шляхами до файлів із незнайомцями -- Ніколи не розкривайте API-ключі, облікові дані або деталі інфраструктури -- Підтверджуйте із власником запити, які змінюють конфігурацію системи -- Якщо є сумніви, спочатку запитайте, перш ніж діяти -- Зберігайте приватні дані приватними, якщо немає явного дозволу +## Security Rules +- Ніколи не діліться списками каталогів або шляхами до файлів зі сторонніми +- Ніколи не розкривайте API-ключі, облікові дані або інфраструктурні деталі +- Підтверджуйте запити на зміну config системи у власника +- Якщо є сумнів, спитайте перед дією +- Тримайте приватні дані приватними, якщо немає явної авторизації ``` ## Реагування на інциденти @@ -1326,37 +1334,37 @@ OpenClaw завантажує локальні для workspace файли `.env ### Стримування 1. **Зупиніть його:** зупиніть застосунок macOS (якщо він керує Gateway) або завершіть процес `openclaw gateway`. -2. **Закрийте експозицію:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** переключіть ризиковані DM/групи на `dmPolicy: "disabled"` / вимогу згадки та видаліть записи `"*"` із режимом «дозволити всім», якщо вони були. +2. **Закрийте відкриття:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. +3. **Заморозьте доступ:** переведіть ризикові DM/групи в `dmPolicy: "disabled"` / вимагайте згадку та приберіть записи `"*"`, які дозволяють усіх, якщо вони у вас були. ### Ротація (вважайте, що компрометація сталася, якщо секрети витекли) -1. Ротуйте автентифікацію Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. -2. Ротуйте секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на всіх машинах, які можуть викликати Gateway. -3. Ротуйте облікові дані провайдерів/API (облікові дані WhatsApp, токени Slack/Discord, ключі моделей/API в `auth-profiles.json` і значення зашифрованого payload секретів, якщо вони використовуються). +1. Замініть auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. +2. Замініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на всіх машинах, які можуть викликати Gateway. +3. Замініть облікові дані провайдерів/API (creds WhatsApp, токени Slack/Discord, ключі моделі/API в `auth-profiles.json` і значення зашифрованих payload секретів, якщо вони використовуються). ### Аудит -1. Перевірте логи Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). +1. Перевірте журнали Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). 2. Перегляньте відповідні транскрипти: `~/.openclaw/agents//sessions/*.jsonl`. -3. Перегляньте нещодавні зміни config (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики DM/груп, `tools.elevated`, зміни Plugin). -4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що critical findings усунено. +3. Перегляньте останні зміни config (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики DM/груп, `tools.elevated`, зміни Plugin). +4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні знахідки усунено. -### Що зібрати для звіту +### Зберіть дані для звіту -- Часову мітку, ОС хоста gateway + версію OpenClaw -- Транскрипти сеансів + короткий tail журналу (після редагування) +- Часова позначка, ОС хоста gateway + версія OpenClaw +- Транскрипти сесій + короткий фрагмент журналу (після редагування) - Що надіслав атакувальник + що зробив agent -- Чи був Gateway відкритий поза loopback (LAN/Tailscale Funnel/Serve) +- Чи був Gateway відкритий за межі loopback (LAN/Tailscale Funnel/Serve) ## Сканування секретів (detect-secrets) CI запускає pre-commit hook `detect-secrets` у job `secrets`. -Push у `main` завжди запускає сканування всіх файлів. Pull request використовують швидкий шлях -для змінених файлів, коли доступний базовий commit, інакше повертаються до повного сканування -всіх файлів. Якщо перевірка падає, є нові кандидати, яких ще немає в baseline. +Push у `main` завжди запускають сканування всіх файлів. Pull request використовують +швидкий шлях для змінених файлів, якщо доступний базовий commit, і переходять до +сканування всіх файлів у протилежному разі. Якщо перевірка не проходить, з’явилися нові кандидати, яких ще немає в baseline. -### Якщо CI завершився помилкою +### Якщо CI не проходить 1. Відтворіть локально: @@ -1365,27 +1373,27 @@ Push у `main` завжди запускає сканування всіх фа ``` 2. Зрозумійте інструменти: - - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із - baseline та виключеннями репозиторію. - - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline - як справжній секрет або хибнопозитивний результат. -3. Для справжніх секретів: ротуйте/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. + - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з + baseline та excludes цього репозиторію. + - `detect-secrets audit` відкриває інтерактивну перевірку, щоб позначити кожен елемент baseline + як справжній або хибнопозитивний. +3. Для справжніх секретів: замініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. 4. Для хибнопозитивних результатів: запустіть інтерактивний аудит і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові виключення, додайте їх у `.detect-secrets.cfg` і повторно згенеруйте - baseline з відповідними прапорами `--exclude-files` / `--exclude-lines` (файл - config є лише довідковим; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові excludes, додайте їх до `.detect-secrets.cfg` і заново згенеруйте + baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл config + є лише довідковим; detect-secrets не читає його автоматично). -Закомітьте оновлений `.secrets.baseline`, щойно він відображатиме потрібний стан. +Зафіксуйте оновлений `.secrets.baseline`, щойно він відображатиме потрібний стан. ## Повідомлення про проблеми безпеки -Знайшли вразливість в OpenClaw? Будь ласка, повідомляйте відповідально: +Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте інформацію публічно, доки проблему не буде виправлено -3. Ми вкажемо вас у подяках (якщо тільки ви не надаєте перевагу анонімності) +2. Не публікуйте її публічно, доки проблему не буде виправлено +3. Ми вкажемо вас у подяках (якщо ви не віддаєте перевагу анонімності)