From ca718133fb437ac2e4495cd8da956df2eedd84af Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 21 Apr 2026 20:29:27 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/security/index.md | 1183 +++++++++++++++-------------- docs/uk/tools/slash-commands.md | 296 ++++---- 2 files changed, 748 insertions(+), 731 deletions(-) diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index 843ce82f9..464cc5b1d 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,13 +1,13 @@ --- read_when: - - Додавання функцій, що розширюють доступ або автоматизацію -summary: Міркування безпеки та модель загроз для запуску AI Gateway з доступом до оболонки + - Додавання функцій, які розширюють доступ або автоматизацію +summary: Міркування безпеки та модель загроз для запуску AI-шлюзу з доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-21T19:31:23Z" + generated_at: "2026-04-21T20:23:17Z" model: gpt-5.4 provider: openai - source_hash: 6b455ffc197119aaa92306eab03d0762a6778e2779b13de8a5d4affd0690f297 + source_hash: 5b03edb022fac8b0fb4ba6e98a8a07434e46a51056df828bcf0be3f220b63cfe source_path: gateway/security/index.md workflow: 15 --- @@ -15,27 +15,27 @@ x-i18n: # Безпека -**Модель довіри персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри оператора на один Gateway (модель одного користувача / персонального асистента). -OpenClaw **не є** ворожою багатокористувацькою межею безпеки для кількох зловмисних користувачів, які спільно використовують один агент/Gateway. -Якщо вам потрібна робота зі змішаною довірою або зі зловмисними користувачами, розділіть межі довіри (окремий Gateway + облікові дані, в ідеалі окремі користувачі ОС/хости). +**Модель довіри для персонального помічника:** ці рекомендації виходять із припущення про одну межу довіри оператора на Gateway (модель одного користувача / персонального помічника). +OpenClaw **не є** ворожою багатокористувацькою межею безпеки для кількох супротивних користувачів, які спільно використовують одного агента/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 виходять із моделі розгортання **персонального асистента**: одна межа довіри оператора, потенційно багато агентів. +Рекомендації з безпеки OpenClaw передбачають розгортання **персонального помічника**: одна межа довіри оператора, потенційно багато агентів. -- Підтримувана модель безпеки: один користувач/межа довіри на один Gateway (бажано один користувач ОС/хост/VPS на одну межу). -- Непідтримувана межа безпеки: один спільний Gateway/агент, яким користуються взаємно недовірені або зловмисні користувачі. -- Якщо потрібна ізоляція від зловмисних користувачів, розділіть середовища за межами довіри (окремий Gateway + облікові дані, а в ідеалі окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з інструментами, вважайте, що вони спільно використовують ті самі делеговані повноваження цього агента. +- Підтримувана модель безпеки: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на межу). +- Не є підтримуваною межею безпеки: один спільний Gateway/агент, який використовують взаємно недовірені або супротивні користувачі. +- Якщо потрібна ізоляція супротивних користувачів, розділяйте за межами довіри (окремий Gateway + облікові дані, а в ідеалі окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що всі вони спільно використовують однакові делеговані повноваження інструментів цього агента. -Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не заявляє про ворожу багатокористувацьку ізоляцію в одному спільному Gateway. +Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує, що один спільний Gateway забезпечує ізоляцію у ворожому багатокористувацькому середовищі. ## Швидка перевірка: `openclaw security audit` -Див. також: [Formal Verification (Security Models)](/uk/security/formal-verification) +Див. також: [Формальна верифікація (моделі безпеки)](/uk/security/formal-verification) Запускайте це регулярно (особливо після зміни конфігурації або відкриття мережевих поверхонь): @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно має вузький обсяг: він перемикає типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи на стан/конфігурацію/включені файли та використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. +`security audit --fix` навмисно має вузьку дію: він перемикає типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-файлів і використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. -Він виявляє поширені небезпечні конфігурації (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, підвищені allowlist, дозволи файлової системи, надто поблажливі підтвердження виконання та відкритий доступ інструментів у каналах). +Він виявляє поширені небезпечні конфігурації (відкриту експозицію автентифікації Gateway, експозицію керування браузером, підвищені allowlist, дозволи файлової системи, надто ліберальні схвалення exec і відкриту експозицію інструментів у каналах). -OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **«Ідеально безпечної» конфігурації не існує.** Мета — усвідомлено визначити: +OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **«Ідеально безпечної» конфігурації не існує.** Мета — свідомо визначити: -- хто може взаємодіяти з вашим ботом +- хто може звертатися до вашого бота - де боту дозволено діяти -- до чого бот може мати доступ +- до чого бот може торкатися -Починайте з найменших привілеїв, яких достатньо для роботи, і розширюйте їх лише тоді, коли отримаєте впевненість. +Починайте з найменшого доступу, який усе ще працює, і розширюйте його поступово, коли зростатиме ваша впевненість. -### Розгортання та довіра до хоста +### Розгортання і довіра до хоста -OpenClaw припускає, що хост і межа конфігурації є довіреними: +OpenClaw виходить із того, що межа хоста і конфігурації є довіреною: - Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте його довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/зловмисних операторів **не є рекомендованою конфігурацією**. -- Для команд зі змішаним рівнем довіри розділяйте межі довіри через окремі Gateway (або щонайменше окремих користувачів ОС/хости). -- Рекомендований варіант за замовчуванням: один користувач на одну машину/хост (або VPS), один gateway для цього користувача і один або більше агентів у цьому gateway. -- У межах одного екземпляра Gateway автентифікований доступ оператора — це довірена роль контрольної площини, а не роль окремого користувача-орендаря. -- Ідентифікатори сеансів (`sessionKey`, ID сеансів, мітки) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному агенту з інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сеансів/пам’яті на рівні користувача допомагає з приватністю, але не перетворює спільного агента на авторизацію хоста на рівні окремих користувачів. +- Запуск одного Gateway для кількох взаємно недовірених/супротивних операторів **не є рекомендованою конфігурацією**. +- Для команд зі змішаною довірою розділяйте межі довіри окремими Gateway (або щонайменше окремими користувачами ОС/хостами). +- Рекомендована конфігурація за замовчуванням: один користувач на машину/хост (або VPS), один gateway для цього користувача і один або кілька агентів у цьому gateway. +- Усередині одного екземпляра Gateway доступ автентифікованого оператора — це довірена роль площини керування, а не роль орендаря на рівні окремого користувача. +- Ідентифікатори сесій (`sessionKey`, ID сесій, мітки) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні користувача допомагає приватності, але не перетворює спільного агента на авторизацію хоста на рівні окремого користувача. ### Спільний робочий простір Slack: реальний ризик -Якщо «будь-хто в Slack може написати боту», основний ризик — це делеговані повноваження інструментів: +Якщо «кожен у Slack може написати боту», основний ризик — це делеговані повноваження інструментів: -- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) в межах політики агента; +- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) у межах політики агента; - ін’єкція промптів/контенту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; -- якщо один спільний агент має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може організувати їх ексфільтрацію через використання інструментів. +- якщо один спільний агент має чутливі облікові дані/файли, будь-який дозволений відправник потенційно може спрямувати їх ексфільтрацію через використання інструментів. -Для командних сценаріїв використовуйте окремих агентів/Gateway з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. +Для командних процесів використовуйте окремі агенти/Gateway з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. -### Спільний корпоративний агент: прийнятний варіант +### Спільний агент компанії: прийнятний шаблон -Це прийнятно, коли всі, хто користується цим агентом, перебувають в одній межі довіри (наприклад, одна команда в компанії), а сам агент суворо обмежений бізнес-завданнями. +Це прийнятно, коли всі, хто використовує цього агента, належать до однієї межі довіри (наприклад, одна команда в компанії), а сам агент суворо обмежений робочим контекстом. -- запускайте його на виділеній машині/VM/контейнері; -- використовуйте виділеного користувача ОС + окремий браузер/профіль/облікові записи для цього середовища; -- не входьте в цьому середовищі до особистих облікових записів Apple/Google або особистих профілів менеджера паролів/браузера. +- запускайте його на окремій машині/VM/контейнері; +- використовуйте окремого користувача ОС + окремий браузер/профіль/акаунти для цього середовища; +- не входьте в цьому середовищі до особистих облікових записів Apple/Google або особистих профілів браузера/менеджера паролів. -Якщо ви змішуєте особисті та корпоративні ідентичності в одному середовищі, ви руйнуєте це розділення та підвищуєте ризик розкриття персональних даних. +Якщо ви змішуєте особисті та робочі ідентичності в одному середовищі, ви руйнуєте розділення і підвищуєте ризик розкриття персональних даних. ## Концепція довіри до Gateway і Node -Сприймайте Gateway і Node як один домен довіри оператора, але з різними ролями: +Ставтеся до Gateway і Node як до однієї операторської доменної межі довіри, але з різними ролями: -- **Gateway** — це контрольна площина та поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії на пристрої, локальні для хоста можливості). -- Виклик, автентифікований у Gateway, є довіреним у межах Gateway. Після прив’язки дії node вважаються діями довіреного оператора на цьому node. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація окремого користувача. -- Підтвердження `exec` (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. -- Типовий продуктний варіант OpenClaw для довірених конфігурацій з одним оператором — дозволяти host exec на `gateway`/`node` без запитів на підтвердження (`security="full"`, `ask="off"`, якщо ви це не посилите). Це свідоме рішення UX, а не вразливість саме по собі. -- Підтвердження виконання прив’язуються до точного контексту запиту та за можливості до прямих локальних файлових операндів; вони не моделюють семантично всі шляхи завантаження часу виконання/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Gateway** — це площина керування і поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). +- **Node** — це поверхня віддаленого виконання, спарена з цим Gateway (команди, дії на пристрої, можливості, локальні для хоста). +- Викликаючий суб’єкт, автентифікований у Gateway, є довіреним у межах Gateway. Після спарювання дії Node є довіреними операторськими діями на цьому Node. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на рівні користувача. +- Схвалення exec (allowlist + ask) — це запобіжники для намірів оператора, а не ізоляція у ворожому багатокористувацькому середовищі. +- Типове налаштування продукту OpenClaw для довірених конфігурацій з одним оператором — дозволяти host exec на `gateway`/`node` без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви не посилюєте політику). Це навмисне UX-рішення, а не вразливість саме по собі. +- Схвалення exec прив’язуються до точного контексту запиту та, наскільки можливо, до безпосередніх локальних файлових операндів; вони не моделюють семантично кожен шлях завантажувача runtime/інтерпретатора. Для сильних меж використовуйте ізоляцію середовища та ізоляцію хоста. -Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами та запускайте окремі gateway. +Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами та запускайте окремі Gateway. ## Матриця меж довіри -Використовуйте це як швидку модель під час оцінки ризику: +Використовуйте це як швидку модель під час оцінювання ризику: -| Межа або контроль | Що це означає | Типове хибне тлумачення | -| ------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує виклики до API gateway | «Щоб це було безпечно, потрібні підписи кожного повідомлення в кожному кадрі» | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сеансу | «Ключ сеансу є межею автентифікації користувача» | -| Запобіжники промптів/контенту | Зменшують ризик зловживання моделлю | «Одна лише prompt injection уже доводить обхід автентифікації» | -| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли увімкнено | «Будь-яка примітивна `eval` для JS автоматично є вразливістю в цій моделі довіри» | -| Локальна оболонка `!` у TUI | Явний запуск локального виконання оператором | «Зручна локальна команда оболонки — це віддалена ін’єкція» | -| Прив’язка node і команди node | Віддалене виконання на рівні оператора на пов’язаних пристроях | «Керування віддаленим пристроєм слід за замовчуванням вважати доступом недовіреного користувача» | +| Межа або контроль | Що це означає | Поширене хибне тлумачення | +| -------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликаючі сторони до API gateway | «Щоб це було безпечно, потрібні підписи кожного повідомлення на кожному фреймі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії — це межа автентифікації користувача» | +| Запобіжники промптів/контенту | Знижують ризик зловживання моделлю | «Сама лише prompt injection доводить обхід автентифікації» | +| `canvas.eval` / browser evaluate | Навмисна операторська можливість, якщо увімкнена | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна TUI-оболонка `!` | Явно ініційоване оператором локальне виконання | «Зручна локальна shell-команда — це віддалена ін’єкція» | +| Спарювання Node і команди Node | Віддалене виконання на спарених пристроях на рівні оператора | «Керування віддаленим пристроєм слід за замовчуванням вважати доступом недовіреного користувача» | ## Не є вразливостями за задумом -Про ці патерни часто повідомляють, але їх зазвичай закривають без дій, якщо не показано реального обходу межі: +Ці шаблони часто потрапляють у звіти і зазвичай закриваються без дій, якщо не показано реальний обхід межі: -- Ланцюги, що спираються лише на prompt injection без обходу політики/автентифікації/sandbox. -- Твердження, які припускають ворожу багатокористувацьку роботу на одному спільному хості/конфігурації. -- Твердження, які класифікують звичайний операторський доступ на читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним gateway. -- Висновки для розгортань лише на localhost (наприклад, HSTS на gateway, доступному лише через loopback). -- Висновки про підпис inbound webhook Discord для inbound-шляхів, яких у цьому репозиторії не існує. -- Звіти, які трактують метадані прив’язки node як прихований другий шар підтвердження кожної команди для `system.run`, тоді як реальною межею виконання залишається глобальна політика команд node у gateway плюс власні підтвердження `exec` на node. -- Висновки про «відсутню авторизацію на рівні користувача», які трактують `sessionKey` як токен автентифікації. +- Ланцюжки, що спираються лише на prompt injection, без обходу політики/автентифікації/sandbox. +- Твердження, що виходять із припущення про вороже багатокористувацьке використання одного спільного хоста/конфігурації. +- Твердження, які трактують звичайний доступ оператора по шляху читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним gateway. +- Виявлення, що стосуються розгортання тільки на localhost (наприклад, HSTS на gateway, доступному лише через loopback). +- Виявлення щодо підпису вхідного Discord Webhook для вхідних шляхів, яких немає в цьому репозиторії. +- Звіти, які трактують метадані спарювання Node як прихований другий шар схвалення для кожної команди `system.run`, тоді як реальна межа виконання — це все ще глобальна політика команд Node у gateway плюс власні схвалення exec самого node. +- Виявлення про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. -## Контрольний список для дослідника перед поданням +## Контрольний список для дослідників перед поданням -Перш ніж відкривати GHSA, перевірте все з цього списку: +Перш ніж відкривати GHSA, перевірте все з наведеного нижче: -1. Відтворення все ще працює на останньому `main` або в останньому релізі. -2. Звіт містить точний шлях у коді (`file`, function, діапазон рядків) і протестовану версію/коміт. -3. Вплив перетинає задокументовану межу довіри, а не лише prompt injection. -4. Твердження не входить до списку [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). -5. Наявні advisories перевірено на дублікати (використовуйте канонічний GHSA, коли це доречно). -6. Припущення щодо розгортання сформульовано явно (loopback/local чи зовнішній доступ, довірені чи недовірені оператори). +1. Відтворення все ще працює на останньому `main` або останньому релізі. +2. Звіт містить точний шлях коду (`file`, function, діапазон рядків) і протестовану версію/коміт. +3. Вплив перетинає задокументовану межу довіри (а не лише prompt injection). +4. Твердження не входить до списку [Поза межами охоплення](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). +5. Наявні advisory вже перевірено на дублікати (за потреби використовуйте канонічний GHSA). +6. Припущення щодо розгортання явно вказані (loopback/local чи зовнішня експозиція, довірені чи недовірені оператори). -## Посилена базова конфігурація за 60 секунд +## Посилений базовий рівень за 60 секунд -Спочатку використайте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для довірених агентів: +Спочатку використайте цей базовий рівень, а потім вибірково знову вмикайте інструменти для довірених агентів: ```json5 { @@ -167,213 +167,218 @@ OpenClaw припускає, що хост і межа конфігурації } ``` -Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти контрольної площини/часу виконання. +Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти площини керування/runtime. -## Швидке правило для спільної скриньки +## Швидке правило для спільної вхідної скриньки -Якщо більше ніж одна людина може надсилати боту DM: +Якщо більше ніж одна людина може писати вашому боту в DM: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для багатoоблікових каналів). -- Зберігайте `dmPolicy: "pairing"` або суворі allowlist. +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для багатокористувацьких каналів). +- Тримайте `dmPolicy: "pairing"` або суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює захист для кооперативних/спільних вхідних скриньок, але не призначене для ворожої ізоляції співорендарів, коли користувачі мають спільний доступ на запис до хоста/конфігурації. +- Це посилює захист кооперативних/спільних вхідних скриньок, але не призначене для ізоляції ворожих співорендарів, коли користувачі спільно мають доступ на запис до хоста/конфігурації. ## Модель видимості контексту OpenClaw розділяє два поняття: -- **Авторизація тригера**: хто може запускати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги до згадування). -- **Видимість контексту**: який додатковий контекст додається до вхідних даних моделі (тіло відповіді, цитований текст, історія гілки, метадані пересилання). +- **Авторизація тригера**: хто може запускати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги згадки). +- **Видимість контексту**: який додатковий контекст інжектується у вхід моделі (текст відповіді, процитований текст, історія треду, метадані пересланих повідомлень). -Allowlist контролюють запуск і авторизацію команд. Параметр `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені гілок, завантажена історія): +Allowlist обмежують тригери й авторизацію команд. Налаштування `contextVisibility` керує тим, як фільтрується додатковий контекст (цитовані відповіді, корені тредів, отримана історія): -- `contextVisibility: "all"` (типово) зберігає додатковий контекст як отримано. +- `contextVisibility: "all"` (типово) зберігає додатковий контекст таким, як його отримано. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все одно зберігає одну явну цитовану відповідь. +- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все ж зберігає одну явну цитовану відповідь. -Установлюйте `contextVisibility` для каналу або окремо для кімнати/розмови. Докладніше див. у [Group Chats](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` на рівні каналу або окремої кімнати/розмови. Подробиці налаштування див. в [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). -Рекомендації для аналізу advisory: +Рекомендації для triage advisory: -- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників, яких немає в allowlist», є висновками про посилення захисту, що вирішуються через `contextVisibility`, а не самі по собі обходом межі автентифікації чи sandbox. -- Щоб мати вплив на безпеку, звіти все одно мають демонструвати обхід межі довіри (автентифікації, політики, sandbox, підтвердження чи іншої задокументованої межі). +- Твердження, які лише демонструють, що «модель може бачити процитований або історичний текст від відправників, яких немає в allowlist», є результатами посилення захисту, які вирішуються через `contextVisibility`, а не самі по собі свідчать про обхід межі автентифікації чи sandbox. +- Щоб мати вплив на безпеку, звіти все одно мають демонструвати обхід межі довіри (автентифікації, політики, sandbox, схвалення або іншої задокументованої межі). ## Що перевіряє аудит (на високому рівні) -- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні запускати бота? -- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії оболонки/файлів/мережі? -- **Дрейф підтвердження `exec`** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec і далі працюють так, як ви вважаєте? - - `security="full"` — це широке попередження про рівень ризику, а не доказ бага. Це вибраний варіант за замовчуванням для довірених конфігурацій персонального асистента; посилюйте його лише тоді, коли ваша модель загроз вимагає підтверджень або запобіжників allowlist. +- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні люди запускати бота? +- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії з оболонкою/файлами/мережею? +- **Дрейф схвалень exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec усе ще працюють так, як ви очікуєте? + - `security="full"` — це широке попередження про рівень ризику, а не доказ помилки. Це вибране типове значення для довірених конфігурацій персонального помічника; посилюйте його лише тоді, коли ваша модель загроз потребує запитів на схвалення або запобіжників allowlist. - **Мережева експозиція** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). -- **Експозиція керування браузером** (віддалені node, relay-порти, віддалені CDP-ендпоїнти). -- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «синхронізованих папок»). -- **Plugin** (наявні розширення без явного allowlist). -- **Дрейф політики/помилки конфігурації** (параметри sandbox docker задано, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди — наприклад `system.run` — і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначається профілями окремих агентів; інструменти Plugin розширень доступні за надто поблажливої політики інструментів). -- **Дрейф очікувань від часу виконання** (наприклад, припущення, що неявний exec досі означає `sandbox`, коли `tools.exec.host` тепер типово дорівнює `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). -- **Гігієна моделей** (попереджати, коли налаштовані моделі виглядають застарілими; це не жорстке блокування). +- **Експозиція керування браузером** (віддалені Node, relay-порти, віддалені кінцеві точки CDP). +- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «synced folder»). +- **Plugin** (розширення існують без явного allowlist). +- **Дрейф політик/неправильна конфігурація** (налаштування sandbox docker задані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, тому що збіг відбувається лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначається профілями окремих агентів; інструменти Plugin розширень доступні за надто ліберальної політики інструментів). +- **Дрейф очікувань runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, коли `tools.exec.host` тепер типово має значення `auto`, або явне встановлення `tools.exec.host="sandbox"`, коли режим sandbox вимкнено). +- **Гігієна моделей** (попередження, якщо налаштовані моделі виглядають застарілими; це не жорстке блокування). -Якщо ви запускаєте `--deep`, OpenClaw також виконує best-effort живу перевірку Gateway. +Якщо ви запускаєте `--deep`, OpenClaw також виконує найкращу можливу живу перевірку Gateway. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або вирішення, що потрібно резервно копіювати: +Використовуйте це під час аудиту доступу або коли вирішуєте, що резервувати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` - **Токен Telegram-бота**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) -- **Токен Discord-бота**: config/env або SecretRef (постачальники env/file/exec) +- **Токен Discord-бота**: config/env або SecretRef (провайдери env/file/exec) - **Токени Slack**: config/env (`channels.slack.*`) -- **Allowlist pairing**: +- **Pairing allowlist**: - `~/.openclaw/credentials/-allowFrom.json` (обліковий запис за замовчуванням) - - `~/.openclaw/credentials/--allowFrom.json` (облікові записи не за замовчуванням) + - `~/.openclaw/credentials/--allowFrom.json` (неосновні облікові записи) - **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Payload секретів із файлу (необов’язково)**: `~/.openclaw/secrets.json` -- **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` +- **Вміст секретів на основі файлу (необов’язково)**: `~/.openclaw/secrets.json` +- **Застарілий імпорт OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить findings, використовуйте такий порядок пріоритетів: +Коли аудит виводить результати, розглядайте це в такому порядку пріоритету: -1. **Будь-що «відкрите» + увімкнені інструменти**: спочатку закрийте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. -2. **Публічна мережева експозиція** (прив’язка до LAN, Funnel, відсутня автентифікація): виправляйте негайно. -3. **Віддалена експозиція керування браузером**: ставтеся до неї як до операторського доступу (лише tailnet, навмисно прив’язуйте node, уникайте публічної експозиції). -4. **Дозволи**: переконайтеся, що стан/config/облікові дані/auth не доступні на читання групі або всім. +1. **Усе «відкрите» + інструменти ввімкнені**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/ізоляцію sandbox. +2. **Публічна мережева експозиція** (bind у LAN, Funnel, відсутня автентифікація): виправляйте негайно. +3. **Віддалена експозиція керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, свідомо спарюйте Node, уникайте публічної експозиції). +4. **Дозволи**: переконайтеся, що state/config/credentials/auth недоступні для читання групі або всім. 5. **Plugin/розширення**: завантажуйте лише те, чому ви явно довіряєте. -6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним моделям, стійкішим до інструкцій. +6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним, стійким до інструкцій моделям. ## Глосарій аудиту безпеки -Найважливіші значення `checkId`, які ви найімовірніше побачите в реальних розгортаннях (список не вичерпний): +Значення `checkId` з найвищим сигналом, які ви найімовірніше побачите в реальних розгортаннях (список не вичерпний): -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Автовиправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | --------------- | -| `fs.state_dir.perms_world_writable` | critical | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.perms_group_writable` | warn | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.perms_readable` | warn | Каталог стану доступний для читання іншим | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.symlink` | warn | Ціль каталогу стану стає іншою межею довіри | схема файлової системи каталогу стану | ні | -| `fs.config.perms_writable` | critical | Інші можуть змінювати auth/політику інструментів/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | -| `fs.config.symlink` | warn | Ціль config-файлу стає іншою межею довіри | схема файлової системи config-файлу | ні | -| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування config | дозволи файлової системи для config-файлу | так | -| `fs.config.perms_world_readable` | critical | Config може розкрити токени/налаштування | дозволи файлової системи для config-файлу | так | -| `fs.config_include.perms_writable` | critical | Include-файл config може бути змінений іншими | дозволи include-файлу, на який є посилання з `openclaw.json` | так | -| `fs.config_include.perms_group_readable` | warn | Користувачі групи можуть читати включені секрети/налаштування | дозволи include-файлу, на який є посилання з `openclaw.json` | так | -| `fs.config_include.perms_world_readable` | critical | Включені секрети/налаштування доступні для читання всім | дозволи include-файлу, на який є посилання з `openclaw.json` | так | -| `fs.auth_profiles.perms_writable` | critical | Інші можуть підмінити або замінити збережені облікові дані моделей | дозволи для `agents//agent/auth-profiles.json` | так | -| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | так | -| `fs.credentials_dir.perms_writable` | critical | Інші можуть змінювати стан pairing/облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | -| `fs.credentials_dir.perms_readable` | warn | Інші можуть читати стан облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | -| `fs.sessions_store.perms_readable` | warn | Інші можуть читати транскрипти/метадані сеансів | дозволи сховища сеансів | так | -| `fs.log_file.perms_readable` | warn | Інші можуть читати журнали, з яких прибрано частину даних, але які все ще чутливі | дозволи для log-файлу gateway | так | -| `fs.synced_dir` | warn | Стан/config в iCloud/Dropbox/Drive розширює ризик витоку токенів/транскриптів | перемістіть config/стан із синхронізованих папок | ні | -| `gateway.bind_no_auth` | critical | Віддалений bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | -| `gateway.loopback_no_auth` | critical | Loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | -| `gateway.trusted_proxies_missing` | warn | Заголовки reverse proxy присутні, але proxy не довірені | `gateway.trustedProxies` | ні | -| `gateway.http.no_auth` | warn/critical | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні | -| `gateway.http.session_key_override_enabled` | info | Виклики HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні | -| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | Повторно вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні | -| `gateway.nodes.allow_commands_dangerous` | warn/critical | Вмикає node-команди з високим впливом (камера/екран/контакти/календар/SMS) | `gateway.nodes.allowCommands` | ні | -| `gateway.nodes.deny_commands_ineffective` | warn | Записи deny, схожі на шаблони, не зіставляються з текстом оболонки або групами | `gateway.nodes.denyCommands` | ні | -| `gateway.tailscale_funnel` | critical | Публічна експозиція в інтернеті | `gateway.tailscale.mode` | ні | -| `gateway.tailscale_serve` | info | Експозицію в tailnet увімкнено через Serve | `gateway.tailscale.mode` | ні | -| `gateway.control_ui.allowed_origins_required` | critical | Control UI не на loopback без явного allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | -| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` вимикає allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | -| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Вмикає fallback джерела через заголовок Host (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | -| `gateway.control_ui.insecure_auth` | warn | Увімкнено перемикач сумісності insecure-auth | `gateway.controlUi.allowInsecureAuth` | ні | -| `gateway.control_ui.device_auth_disabled` | critical | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | -| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підміну IP-джерела через помилку proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | -| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати bruteforce-методом | `gateway.auth.token` | ні | -| `gateway.auth_no_rate_limit` | warn | Відкрита auth без rate limiting підвищує ризик bruteforce | `gateway.auth.rateLimit` | ні | -| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею auth | `gateway.auth.mode="trusted-proxy"` | ні | -| `gateway.trusted_proxy_no_proxies` | critical | Trusted-proxy auth без IP-адрес довірених proxy є небезпечною | `gateway.trustedProxies` | ні | -| `gateway.trusted_proxy_no_user_header` | critical | Trusted-proxy auth не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | -| `gateway.trusted_proxy_no_allowlist` | warn | Trusted-proxy auth приймає будь-якого автентифікованого користувача вище за потоком | `gateway.auth.trustedProxy.allowUsers` | ні | -| `gateway.probe_auth_secretref_unavailable` | warn | Глибока перевірка не змогла розв’язати auth SecretRef у цьому шляху команди | джерело auth для глибокої перевірки / доступність SecretRef | ні | -| `gateway.probe_failed` | warn/critical | Жива перевірка Gateway не вдалася | доступність/автентифікація gateway | ні | -| `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | -| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні або незахищені debug-прапорці | кілька ключів (див. details finding) | ні | -| `config.secrets.gateway_password_in_config` | warn | Пароль Gateway зберігається безпосередньо в config | `gateway.auth.password` | ні | -| `config.secrets.hooks_token_in_config` | warn | Bearer-токен hook зберігається безпосередньо в config | `hooks.token` | ні | -| `hooks.token_reuse_gateway_token` | critical | Токен входу hook також відкриває auth Gateway | `hooks.token`, `gateway.auth.token` | ні | -| `hooks.token_too_short` | warn | Полегшує bruteforce для входу hook | `hooks.token` | ні | -| `hooks.default_session_key_unset` | warn | Запуски агента з hook розгалужуються в згенеровані сеанси для кожного запиту | `hooks.defaultSessionKey` | ні | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані виклики hook можуть маршрутизуватися до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні | -| `hooks.request_session_key_enabled` | warn/critical | Зовнішній виклик може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | -| `hooks.request_session_key_prefixes_missing` | warn/critical | Немає обмежень на форму зовнішніх ключів сеансу | `hooks.allowedSessionKeyPrefixes` | ні | -| `hooks.path_root` | critical | Шлях hook дорівнює `/`, що полегшує колізії або хибну маршрутизацію входу | `hooks.path` | ні | -| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлень hook не прив’язані до незмінних специфікацій npm | метадані встановлення hook | ні | -| `hooks.installs_missing_integrity` | warn | У записах встановлень hook бракує метаданих цілісності | метадані встановлення hook | ні | -| `hooks.installs_version_drift` | warn | Записи встановлень hook розходяться з установленими пакетами | метадані встановлення hook | ні | -| `logging.redact_off` | warn | Чутливі значення потрапляють у журнали/статус | `logging.redactSensitive` | так | -| `browser.control_invalid_config` | warn | Config керування браузером недійсний ще до запуску | `browser.*` | ні | -| `browser.control_no_auth` | critical | Керування браузером відкрито без auth через token/password | `gateway.auth.*` | ні | -| `browser.remote_cdp_http` | warn | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль браузера `cdpUrl` | ні | -| `browser.remote_cdp_private_host` | warn | Віддалений CDP вказує на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні | -| `sandbox.docker_config_mode_off` | warn | Конфігурація sandbox Docker присутня, але неактивна | `agents.*.sandbox.mode` | ні | -| `sandbox.bind_mount_non_absolute` | warn | Відносні bind mount можуть розв’язуватися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_bind_mount` | critical | Цілі bind mount sandbox потрапляють у заблоковані системні шляхи, шляхи облікових даних або сокета Docker | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_network_mode` | critical | Мережа sandbox Docker використовує режим `host` або `container:*` зі спільним простором імен | `agents.*.sandbox.docker.network` | ні | -| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.browser_cdp_bridge_unrestricted` | warn | Міст браузера sandbox відкрито без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | -| `sandbox.browser_container.non_loopback_publish` | critical | Наявний контейнер браузера публікує CDP на інтерфейсах, відмінних від loopback | конфігурація publish контейнера браузера sandbox | ні | -| `sandbox.browser_container.hash_label_missing` | warn | Наявний контейнер браузера передує поточним міткам хеша config | `openclaw sandbox recreate --browser --all` | ні | -| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний контейнер браузера передує поточній епосі config браузера | `openclaw sandbox recreate --browser --all` | ні | -| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` закривається безпечно, якщо sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні | -| `tools.exec.host_sandbox_no_sandbox_agents` | warn | `exec host=sandbox` для окремого агента закривається безпечно, якщо sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні | -| `tools.exec.security_full_configured` | warn/critical | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні | -| `tools.exec.auto_allow_skills_enabled` | warn | Підтвердження exec неявно довіряють bin-файлам Skills | `~/.openclaw/exec-approvals.json` | ні | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlist інтерпретаторів дозволяє inline eval без примусового повторного підтвердження | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist підтверджень exec | ні | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Bin-файли інтерпретаторів/часу виконання в `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | -| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти з широкою поведінкою в `safeBins` послаблюють модель довіри stdin-filter з низьким ризиком | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні | -| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні | -| `skills.workspace.symlink_escape` | warn | `skills/**/SKILL.md` у workspace розв’язується за межі кореня workspace (дрейф ланцюга symlink) | стан файлової системи workspace `skills/**` | ні | -| `plugins.extensions_no_allowlist` | warn | Розширення встановлено без явного allowlist Plugin | `plugins.allowlist` | ні | -| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлень Plugin не прив’язані до незмінних специфікацій npm | метадані встановлення plugin | ні | -| `plugins.installs_missing_integrity` | warn | У записах встановлень Plugin бракує метаданих цілісності | метадані встановлення plugin | ні | -| `plugins.installs_version_drift` | warn | Записи встановлень Plugin розходяться з установленими пакетами | метадані встановлення plugin | ні | -| `plugins.code_safety` | warn/critical | Сканування коду Plugin виявило підозрілі або небезпечні патерни | код plugin / джерело встановлення | ні | -| `plugins.code_safety.entry_path` | warn | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті plugin | ні | -| `plugins.code_safety.entry_escape` | critical | Точка входу Plugin виходить за межі каталогу plugin | `entry` у маніфесті plugin | ні | -| `plugins.code_safety.scan_failed` | warn | Сканування коду Plugin не вдалося завершити | шлях розширення plugin / середовище сканування | ні | -| `skills.code_safety` | warn/critical | Метадані встановлення/код Skill містять підозрілі або небезпечні патерни | джерело встановлення skill | ні | -| `skills.code_safety.scan_failed` | warn | Сканування коду Skill не вдалося завершити | середовище сканування skill | ні | -| `security.exposure.open_channels_with_exec` | warn/critical | Спільні/публічні кімнати можуть звертатися до агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | -| `security.exposure.open_groups_with_elevated` | critical | Відкриті групи + підвищені інструменти створюють шляхи prompt injection з високим впливом | `channels.*.groupPolicy`, `tools.elevated.*` | ні | -| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | Відкриті групи можуть звертатися до командних/файлових інструментів без захисту sandbox/workspace | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні | -| `security.trust_model.multi_user_heuristic` | warn | Config виглядає багатокористувацьким, тоді як модель довіри gateway — персональний асистент | розділіть межі довіри або посильте захист для спільних користувачів (`sandbox.mode`, deny для інструментів/обмеження workspace) | ні | -| `tools.profile_minimal_overridden` | warn | Перевизначення агента обходять глобальний мінімальний профіль | `agents.list[].tools.profile` | ні | -| `plugins.tools_reachable_permissive_policy` | warn | Інструменти розширень доступні в надто поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | -| `models.legacy` | warn | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | -| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні | -| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + політика sandbox/інструментів | ні | -| `summary.attack_surface` | info | Підсумкове зведення рівня auth, каналів, інструментів і експозиції | кілька ключів (див. details finding) | ні | +| `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` | критично | Інші можуть змінювати політику автентифікації/інструментів/конфігурацію | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | +| `fs.config.symlink` | попередження | Цільовий файл конфігурації стає іншою межею довіри | розміщення файлу конфігурації у файловій системі | ні | +| `fs.config.perms_group_readable` | попередження | Користувачі групи можуть читати токени/налаштування конфігурації | дозволи файлової системи для файлу конфігурації | так | +| `fs.config.perms_world_readable` | критично | Конфігурація може розкрити токени/налаштування | дозволи файлової системи для файлу конфігурації | так | +| `fs.config_include.perms_writable` | критично | Інші можуть змінювати include-файл конфігурації | дозволи 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` | критично | Інші можуть змінювати стан спарювання/облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.credentials_dir.perms_readable` | попередження | Інші можуть читати стан облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.sessions_store.perms_readable` | попередження | Інші можуть читати транскрипти/метадані сесій | дозволи сховища сесій | так | +| `fs.log_file.perms_readable` | попередження | Інші можуть читати логи, у яких хоч і редаговано дані, але вони все ще чутливі | дозволи файлу логу gateway | так | +| `fs.synced_dir` | попередження | Стан/конфігурація в iCloud/Dropbox/Drive розширює ризик розкриття токенів/транскриптів | перемістіть конфігурацію/стан за межі синхронізованих папок | ні | +| `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 з високим впливом (камера/екран/контакти/календар/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` | критично | Не-loopback Control UI без явного allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.allowed_origins_wildcard` | попередження/критично | `allowedOrigins=["*"]` вимикає allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.host_header_origin_fallback` | попередження/критично | Вмикає fallback джерела за заголовком Host (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | +| `gateway.control_ui.insecure_auth` | попередження | Увімкнено перемикач сумісності з небезпечною автентифікацією | `gateway.controlUi.allowInsecureAuth` | ні | +| `gateway.control_ui.device_auth_disabled` | критично | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | +| `gateway.real_ip_fallback_enabled` | попередження/критично | Довіра до fallback `X-Real-IP` може дозволити підміну IP-джерела через хибну конфігурацію proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | +| `gateway.token_too_short` | попередження | Короткий спільний токен легше підібрати | `gateway.auth.token` | ні | +| `gateway.auth_no_rate_limit` | попередження | Відкрита автентифікація без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні | +| `gateway.trusted_proxy_auth` | критично | Ідентичність proxy тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | ні | +| `gateway.trusted_proxy_no_proxies` | критично | Автентифікація через trusted-proxy без IP-адрес довірених proxy є небезпечною | `gateway.trustedProxies` | ні | +| `gateway.trusted_proxy_no_user_header` | критично | Автентифікація через trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | +| `gateway.trusted_proxy_no_allowlist` | попередження | Автентифікація через trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------- | +| `gateway.probe_auth_secretref_unavailable` | попередження | Глибока перевірка не змогла розв’язати SecretRef автентифікації в цьому шляху команди | джерело автентифікації deep-probe / доступність SecretRef | ні | +| `gateway.probe_failed` | попередження/критично | Жива перевірка Gateway завершилася невдачею | доступність/автентифікація gateway | ні | +| `discovery.mdns_full_mode` | попередження/критично | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | +| `config.insecure_or_dangerous_flags` | попередження | Увімкнено небезпечні або ризиковані прапорці налагодження | кілька ключів (див. деталі результату) | ні | +| `config.secrets.gateway_password_in_config` | попередження | Пароль Gateway збережено безпосередньо в конфігурації | `gateway.auth.password` | ні | +| `config.secrets.hooks_token_in_config` | попередження | Bearer-токен hooks збережено безпосередньо в конфігурації | `hooks.token` | ні | +| `hooks.token_reuse_gateway_token` | критично | Токен входу hooks також відкриває автентифікацію Gateway | `hooks.token`, `gateway.auth.token` | ні | +| `hooks.token_too_short` | попередження | Вищий ризик brute force для входу hooks | `hooks.token` | ні | +| `hooks.default_session_key_unset` | попередження | Агент hooks розподіляє виконання по згенерованих сесіях для кожного запиту | `hooks.defaultSessionKey` | ні | +| `hooks.allowed_agent_ids_unrestricted` | попередження/критично | Автентифіковані викликаючі сторони hooks можуть маршрутизувати до будь-якого налаштованого агента | `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-специфікаціями | метадані встановлення hooks | ні | +| `hooks.installs_missing_integrity` | попередження | У записах встановлення hooks бракує метаданих цілісності | метадані встановлення hooks | ні | +| `hooks.installs_version_drift` | попередження | Записи встановлення hooks розходяться зі встановленими пакетами | метадані встановлення hooks | ні | +| `logging.redact_off` | попередження | Чутливі значення потрапляють у логи/статус | `logging.redactSensitive` | так | +| `browser.control_invalid_config` | попередження | Конфігурація керування браузером невалідна ще до runtime | `browser.*` | ні | +| `browser.control_no_auth` | критично | Керування браузером відкрите без автентифікації token/password | `gateway.auth.*` | ні | +| `browser.remote_cdp_http` | попередження | Віддалений CDP через звичайний HTTP не має транспортного шифрування | профіль браузера `cdpUrl` | ні | +| `browser.remote_cdp_private_host` | попередження | Віддалений CDP націлений на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні | +| `sandbox.docker_config_mode_off` | попередження | Конфігурація Docker sandbox присутня, але неактивна | `agents.*.sandbox.mode` | ні | +| `sandbox.bind_mount_non_absolute` | попередження | Відносні bind mount можуть розв’язуватися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_bind_mount` | критично | Bind mount sandbox націлено на заблоковані системні шляхи, облікові дані або сокет Docker | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_network_mode` | критично | Мережа Docker sandbox використовує режим приєднання простору імен `host` або `container:*` | `agents.*.sandbox.docker.network` | ні | +| `sandbox.dangerous_seccomp_profile` | критично | Профіль seccomp sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.dangerous_apparmor_profile` | критично | Профіль AppArmor sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.browser_cdp_bridge_unrestricted` | попередження | Міст CDP sandbox браузера відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | +| `sandbox.browser_container.non_loopback_publish` | критично | Наявний контейнер браузера публікує CDP на інтерфейсах, відмінних від loopback | конфігурація publish контейнера sandbox браузера | ні | +| `sandbox.browser_container.hash_label_missing` | попередження | Наявний контейнер браузера створено до поточних міток hash конфігурації | `openclaw sandbox recreate --browser --all` | ні | +| `sandbox.browser_container.hash_epoch_stale` | попередження | Наявний контейнер браузера створено до поточної епохи конфігурації браузера | `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` для окремого агента безпечно завершується відмовою, якщо 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 неявно довіряють skill bins | `~/.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` | попередження | Бінарники інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | +| `tools.exec.safe_bins_broad_behavior` | попередження | Інструменти з широкою поведінкою у `safeBins` послаблюють модель довіри low-risk stdin-filter | `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` | попередження | Розширення встановлено без явного allowlist Plugin | `plugins.allowlist` | ні | +| `plugins.installs_unpinned_npm_specs` | попередження | Записи встановлення Plugin не закріплені за незмінними npm-специфікаціями | метадані встановлення Plugin | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------- | +| `plugins.installs_missing_integrity` | попередження | У записах встановлення Plugin бракує метаданих цілісності | метадані встановлення Plugin | ні | +| `plugins.installs_version_drift` | попередження | Записи встановлення Plugin розходяться зі встановленими пакетами | метадані встановлення 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` | попередження/критично | Метадані інсталятора/code Skills містять підозрілі або небезпечні шаблони | джерело встановлення skill | ні | +| `skills.code_safety.scan_failed` | попередження | Сканування коду Skills не вдалося завершити | середовище сканування skill | ні | +| `security.exposure.open_channels_with_exec` | попередження/критично | Спільні/публічні кімнати можуть досягати агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | +| `security.exposure.open_groups_with_elevated` | критично | Відкриті групи + підвищені інструменти створюють високоризикові шляхи prompt injection | `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` | попередження | Конфігурація схожа на багатокористувацьку, тоді як модель довіри gateway — персональний помічник | розділіть межі довіри або посильте спільний сценарій (`sandbox.mode`, deny інструментів/обмеження workspace) | ні | +| `tools.profile_minimal_overridden` | попередження | Перевизначення агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | +| `plugins.tools_reachable_permissive_policy` | попередження | Інструменти розширень доступні в надто ліберальних контекстах | `tools.profile` + allow/deny інструментів | ні | +| `models.legacy` | попередження | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | +| `models.weak_tier` | попередження | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні | +| `models.small_params` | критично/інформація | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + політика sandbox/інструментів | ні | +| `summary.attack_surface` | інформація | Зведений підсумок щодо автентифікації, каналів, інструментів та рівня експозиції | кілька ключів (див. деталі результату) | ні | ## Control UI через HTTP -Для Control UI потрібен **безпечний контекст** (HTTPS або localhost), щоб генерувати -ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: +Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати +ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний +перемикач сумісності: -- На localhost він дозволяє auth для Control UI без ідентичності пристрою, коли сторінка - завантажена через незахищений HTTP. +- На localhost він дозволяє автентифікацію 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.auth.mode: "trusted-proxy"` -може допускати **операторські** сеанси Control UI без ідентичності пристрою. Це -навмисна поведінка режиму auth, а не скорочений шлях через `allowInsecureAuth`, і це все одно -не поширюється на сеанси Control UI з роллю node. +може допускати **операторські** сесії Control UI без ідентичності пристрою. Це +навмисна поведінка режиму автентифікації, а не скорочений шлях через `allowInsecureAuth`, і вона все одно +не поширюється на сесії Control UI з роллю node. -`openclaw security audit` попереджає, коли це налаштування увімкнено. +`openclaw security audit` попереджає, коли це налаштування ввімкнено. -## Підсумок небезпечних або незахищених прапорців +## Підсумок небезпечних або ризикованих прапорців `openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли -увімкнено відомі незахищені/небезпечні debug-перемикачі. Наразі ця перевірка +відомі небезпечні/ризиковані перемикачі налагодження ввімкнено. Наразі ця перевірка агрегує: - `gateway.controlUi.allowInsecureAuth=true` @@ -384,7 +389,8 @@ Allowlist контролюють запуск і авторизацію кома - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` -Повний список ключів config з `dangerous*` / `dangerously*`, визначених у схемі config OpenClaw: +Повний список ключів конфігурації `dangerous*` / `dangerously*`, визначених у схемі +конфігурації OpenClaw: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` @@ -417,141 +423,142 @@ Allowlist контролюють запуск і авторизацію кома ## Конфігурація reverse proxy Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для правильної обробки пересланої IP-адреси клієнта. +`gateway.trustedProxies` для коректної обробки пересланої IP-адреси клієнта. -Коли Gateway виявляє заголовки proxy від адреси, якої **немає** в `trustedProxies`, він **не** вважатиме ці підключення локальними клієнтами. Якщо auth gateway вимкнено, такі підключення відхиляються. Це запобігає обходу автентифікації, коли з’єднання через proxy інакше могли б виглядати як такі, що надходять із localhost, і автоматично отримувати довіру. +Коли Gateway виявляє заголовки proxy з адреси, якої **немає** в `trustedProxies`, він **не** вважає такі з’єднання локальними клієнтами. Якщо автентифікацію gateway вимкнено, такі з’єднання відхиляються. Це запобігає обходу автентифікації, коли проксовані з’єднання інакше могли б виглядати як такі, що походять із localhost, і автоматично отримували б довіру. -`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: +`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим автентифікації суворіший: -- auth trusted-proxy **закривається безпечно для proxy з джерелом loopback** -- reverse proxy з loopback на тому самому хості все ще можуть використовувати `gateway.trustedProxies` для визначення локального клієнта та обробки пересланого IP -- для reverse proxy з loopback на тому самому хості використовуйте auth через token/password замість `gateway.auth.mode: "trusted-proxy"` +- автентифікація trusted-proxy **завершується безпечним відмовленням для proxy з джерелом loopback** +- reverse proxy на тому самому хості з loopback усе ще можуть використовувати `gateway.trustedProxies` для визначення локального клієнта й обробки пересланої IP-адреси +- для reverse proxy на тому самому хості з loopback використовуйте автентифікацію token/password замість `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - - "10.0.0.1" # IP reverse proxy - # Необов’язково. Типово false. - # Увімкніть лише якщо ваш proxy не може надавати X-Forwarded-For. + - "10.0.0.1" # IP-адреса reverse proxy + # Необов’язково. Типове значення 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 насамперед орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштуйте HSTS на HTTPS-домені з боку proxy. +- 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 auth на loopback усе одно обмежуються через rate limiting, навіть коли - увімкнено загальне виключення для loopback, але ключ блокування визначається окремо для - нормалізованого значення `Origin`, а не через один спільний bucket localhost. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin через заголовок Host; вважайте це небезпечною політикою, яку свідомо вибирає оператор. -- Розглядайте DNS rebinding і поведінку заголовка host у proxy як питання посилення захисту розгортання; тримайте `trustedProxies` вузькими та уникайте прямого відкриття gateway у публічний інтернет. +- Детальні рекомендації щодо розгортання наведено в [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 limiting, навіть коли + загальний виняток для loopback увімкнено, але ключ блокування обмежується + нормалізованим значенням `Origin`, а не одним спільним кошиком localhost. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin за заголовком Host; ставтеся до цього як до небезпечної політики, свідомо вибраної оператором. +- Розглядайте DNS rebinding і поведінку proxy щодо заголовка host як питання посилення безпеки розгортання; тримайте `trustedProxies` вузьким і уникайте прямої публічної експозиції gateway в інтернеті. -## Локальні журнали сеансів зберігаються на диску +## Локальні логи сесій зберігаються на диску -OpenClaw зберігає транскрипти сеансів на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сеансів і (за бажанням) індексації пам’яті сеансів, але це також означає, -що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Розглядайте доступ до диска як -межу довіри та жорстко обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна -сильніша ізоляція між агентами, запускайте їх від окремих користувачів ОС або на окремих хостах. +OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. +Це потрібно для безперервності сесій і (необов’язково) індексації пам’яті сесій, але це також означає, +що **будь-який процес/користувач із доступом до файлової системи може читати ці логи**. Вважайте доступ до диска +межею довіри й жорстко обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. ## Виконання на Node (`system.run`) -Якщо прив’язано node на macOS, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: +Якщо Node macOS спарено, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: -- Потребує pairing node (підтвердження + token). -- Pairing node у Gateway не є поверхнею підтвердження кожної команди. Воно встановлює ідентичність/довіру до node та випуск токена. +- Потребує 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 не може точно визначити один прямий локальний файл для команди інтерпретатора/часу виконання, виконання з підтвердженням буде заборонено, а не оголошено повне семантичне покриття. -- Для `host=node` виконання з підтвердженням також зберігає канонічний підготовлений - `systemRunPlan`; подальші схвалені переспрямування повторно використовують цей збережений план, а gateway - відхиляє зміни від викликача до command/cwd/session context після створення запиту на підтвердження. -- Якщо вам не потрібне віддалене виконання, установіть security у **deny** і видаліть pairing node для цього Mac. +- Політика `system.run` для кожного node — це власний файл схвалень exec цього node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ID команд gateway. +- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо лише ваше розгортання явно не потребує суворішого режиму схвалення або allowlist. +- Режим схвалення прив’язується до точного контексту запиту і, коли можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання з опорою на схвалення забороняється, замість того щоб обіцяти повне семантичне покриття. +- Для `host=node` виконання з опорою на схвалення також зберігає канонічний підготовлений + `systemRunPlan`; пізніші схвалені пересилання повторно використовують цей збережений план, а gateway + відхиляє зміни викликача до command/cwd/session context після створення + запиту на схвалення. +- Якщо ви не хочете віддаленого виконання, установіть security у **deny** і видаліть pairing node для цього Mac. -Це розрізнення важливе для аналізу: +Це розрізнення важливе для triage: -- Повторне підключення прив’язаного node, який оголошує інший список команд, саме по собі не є вразливістю, якщо глобальна політика Gateway і локальні підтвердження exec на node усе ще забезпечують реальну межу виконання. -- Звіти, які трактують метадані pairing node як другий прихований шар підтвердження кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. +- Повторне підключення спареного node, який оголошує інший список команд, само по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec node усе ще забезпечують фактичну межу виконання. +- Звіти, які трактують метадані pairing node як другий прихований шар схвалення для кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. -## Динамічні Skills (watcher / віддалені node) +## Динамічні Skills (watcher / віддалені Node) -OpenClaw може оновлювати список Skills посеред сеансу: +OpenClaw може оновлювати список Skills посеред сесії: -- **Watcher Skills**: зміни в `SKILL.md` можуть оновити snapshot Skills на наступному ході агента. -- **Віддалені node**: підключення node на macOS може зробити доступними Skills лише для macOS (на основі перевірки bin). +- **Watcher Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході агента. +- **Віддалені Node**: підключення macOS node може зробити доступними Skills лише для macOS (на основі перевірки bin). -Розглядайте папки skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. +Ставтеся до папок skill як до **довіреного коду** й обмежуйте, хто може їх змінювати. ## Модель загроз -Ваш AI-асистент може: +Ваш AI-помічник може: - Виконувати довільні команди оболонки - Читати/записувати файли - Отримувати доступ до мережевих сервісів -- Надсилати повідомлення будь-кому (якщо ви надали йому доступ до WhatsApp) +- Надсилати повідомлення будь-кому (якщо ви надасте йому доступ до WhatsApp) -Люди, які надсилають вам повідомлення, можуть: +Люди, які пишуть вам, можуть: -- Намагатися обдурити ваш AI, щоб він зробив щось погане +- Намагатися обманом змусити ваш AI зробити щось шкідливе - Використовувати соціальну інженерію для доступу до ваших даних -- Збирати відомості про вашу інфраструктуру +- Зондувати деталі інфраструктури -## Базова концепція: контроль доступу перед інтелектом +## Основна ідея: контроль доступу перед інтелектом -Більшість збоїв тут — не витончені експлойти, а «хтось написав боту, і бот зробив те, що його попросили». +Більшість збоїв тут — це не витончені експлойти, а ситуації на кшталт «хтось написав боту, і бот зробив те, що його попросили». Позиція OpenClaw: -- **Спочатку ідентичність:** визначте, хто може взаємодіяти з ботом (DM pairing / allowlist / явний режим “open”). -- **Потім межі:** визначте, де боту дозволено діяти (group allowlist + вимога згадування, інструменти, sandboxing, дозволи пристрою). -- **Модель наприкінці:** виходьте з того, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляції були обмеженими. +- **Спочатку ідентичність:** визначте, хто може звертатися до бота (pairing DM / allowlist / явний режим “open”). +- **Потім межі:** визначте, де боту дозволено діяти (allowlist груп + вимога згадки, інструменти, sandboxing, дозволи пристрою). +- **Модель наприкінці:** припускайте, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляції мали обмежений радіус. ## Модель авторизації команд -Slash-команди та директиви обробляються лише для **авторизованих відправників**. Авторизація визначається через -allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) +Slash-команди та директиви обробляються лише для **авторизованих відправників**. Авторизація визначається +через allowlist/pairing каналу разом із `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, команди фактично відкриті для цього каналу. -`/exec` — це зручна функція лише для сеансів авторизованих операторів. Вона **не** записує config і -не змінює інші сеанси. +`/exec` — це зручна команда лише для сесії для авторизованих операторів. Вона **не** записує конфігурацію і +не змінює інші сесії. -## Ризики інструментів контрольної площини +## Ризики інструментів площини керування -Два вбудовані інструменти можуть вносити постійні зміни в контрольну площину: +Два вбудовані інструменти можуть вносити постійні зміни до площини керування: -- `gateway` може переглядати config через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. +- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get`, а також робити постійні зміни через `config.apply`, `config.patch` і `update.run`. - `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. -Інструмент часу виконання `gateway`, доступний лише власнику, усе ще відмовляється переписувати +Інструмент runtime `gateway`, доступний лише власнику, усе ще відмовляється переписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого агента/поверхні, що обробляє недовірений контент, типово забороняйте їх: +Для будь-якого агента/поверхні, що працює з недовіреним контентом, забороняйте це за замовчуванням: ```json5 { @@ -561,35 +568,35 @@ allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Con } ``` -`commands.restart=false` блокує лише дії перезапуску. Це не вимикає дії config/update інструмента `gateway`. +`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії конфігурації/оновлення `gateway`. ## Plugin/розширення -Plugin працюють **у тому самому процесі**, що й Gateway. Розглядайте їх як довірений код: +Plugins працюють **у тому самому процесі**, що й Gateway. Ставтеся до них як до довіреного коду: -- Встановлюйте лише Plugin із джерел, яким довіряєте. -- Віддавайте перевагу явним allowlist `plugins.allow`. -- Перевіряйте config Plugin перед увімкненням. +- Встановлюйте Plugins лише з джерел, яким довіряєте. +- Надавайте перевагу явним allowlist `plugins.allow`. +- Перевіряйте конфігурацію Plugin перед увімкненням. - Перезапускайте Gateway після змін Plugin. -- Якщо ви встановлюєте або оновлюєте Plugin (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: - - Шлях встановлення — це каталог окремого plugin у межах активного кореня встановлення plugin. - - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Findings рівня `critical` типово блокують операцію. - - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (скрипти життєвого циклу npm можуть виконувати код під час встановлення). - - Віддавайте перевагу точним, зафіксованим версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. - - `--dangerously-force-unsafe-install` — лише для аварійних випадків, коли вбудоване сканування дає хибнопозитивні результати в потоках встановлення/оновлення plugin. Це не обходить блокування політики hook `before_install` plugin і не обходить збої сканування. - - Встановлення залежностей Skills через Gateway дотримується того самого поділу на dangerous/suspicious: вбудовані findings рівня `critical` блокують операцію, якщо викликаючий явно не встановить `dangerouslyForceUnsafeInstall`, тоді як findings рівня suspicious лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills через ClawHub. +- Якщо ви встановлюєте або оновлюєте Plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: + - Шлях встановлення — це каталог кожного Plugin у межах активного кореня встановлення Plugin. + - OpenClaw запускає вбудоване сканування небезпечного коду перед встановленням/оновленням. Результати `critical` типово блокують операцію. + - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (lifecycle-скрипти npm можуть виконувати код під час встановлення). + - Надавайте перевагу закріпленим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` — лише для аварійних сценаріїв у разі хибнопозитивних результатів вбудованого сканування під час встановлення/оновлення Plugin. Він не обходить блокування політики хука Plugin `before_install` і не обходить збої сканування. + - Встановлення залежностей Skills через Gateway дотримується того самого поділу на dangerous/suspicious: вбудовані результати `critical` блокують операцію, якщо тільки викликаюча сторона явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі результати все ще лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. -Докладніше: [Plugins](/uk/tools/plugin) +Подробиці: [Plugins](/uk/tools/plugin) -## Модель доступу через DM (pairing / allowlist / open / disabled) +## Модель доступу до DM (pairing / allowlist / open / disabled) -Усі поточні канали з підтримкою DM підтримують політику DM (`dmPolicy` або `*.dm.policy`), яка обмежує вхідні DM **до** обробки повідомлення: +Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка обмежує вхідні DM **до** обробки повідомлення: -- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди діють 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість запитів в очікуванні типово обмежена до **3 на канал**. +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди діють 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість незавершених запитів типово обмежена до **3 на канал**. - `allowlist`: невідомі відправники блокуються (без handshake pairing). -- `open`: дозволити будь-кому писати в DM (публічно). **Потрібно**, щоб allowlist каналу містив `"*"` (явна згода). +- `open`: дозволити будь-кому надсилати DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явна згода). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -599,11 +606,11 @@ openclaw pairing list openclaw pairing approve ``` -Докладніше + файли на диску: [Pairing](/uk/channels/pairing) +Подробиці + файли на диску: [Pairing](/uk/channels/pairing) -## Ізоляція сеансів DM (багатокористувацький режим) +## Ізоляція DM-сесій (багатокористувацький режим) -Типово OpenClaw маршрутизує **усі DM в основний сеанс**, щоб ваш асистент зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть писати боту в DM (відкриті DM або allowlist із кількох осіб), розгляньте ізоляцію сеансів DM: +Типово OpenClaw маршрутизує **усі DM в основну сесію**, щоб ваш помічник зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати боту DM (відкриті DM або allowlist із кількома людьми), розгляньте ізоляцію DM-сесій: ```json5 { @@ -613,61 +620,61 @@ openclaw pairing approve Це запобігає витоку контексту між користувачами, зберігаючи при цьому ізоляцію групових чатів. -Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі взаємно зловмисні та використовують спільний хост/config Gateway, запускайте окремі gateway для кожної межі довіри. +Це межа контексту повідомлень, а не межа адміністрування хоста. Якщо користувачі взаємно супротивні та спільно використовують той самий хост/конфігурацію Gateway, натомість запускайте окремі Gateway для кожної межі довіри. ### Безпечний режим DM (рекомендовано) Сприймайте наведений вище фрагмент як **безпечний режим DM**: -- Типово: `session.dmScope: "main"` (усі DM використовують один сеанс для безперервності). -- Типовий варіант локального онбордингу CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (наявні явні значення не змінюються). +- Типово: `session.dmScope: "main"` (усі DM спільно використовують одну сесію для безперервності). +- Типове значення для локального онбордингу CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (зберігає вже наявні явні значення). - Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). -- Ізоляція відправника між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує один сеанс у всіх каналах одного типу). +- Ізоляція користувача між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). -Якщо ви використовуєте кілька облікових записів в одному каналі, замість цього використовуйте `per-account-channel-peer`. Якщо одна й та сама людина звертається до вас через кілька каналів, використовуйте `session.identityLinks`, щоб звести ці сеанси DM до однієї канонічної ідентичності. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). +Якщо ви використовуєте кілька облікових записів в одному каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина звертається до вас через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). -## Allowlist (DM + групи) — термінологія +## 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 бот узагалі прийматиме повідомлення. - - Типові патерни: - - `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 для кожної поверхні + типові параметри згадування. - - Group-перевірки виконуються в такому порядку: спочатку `groupPolicy`/group allowlist, потім активація через згадування/відповідь. - - Відповідь на повідомлення бота (неявне згадування) **не** обходить allowlist відправників, такі як `groupAllowFrom`. - - **Примітка щодо безпеки:** розглядайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування останнього вибору. Їх варто використовувати вкрай рідко; віддавайте перевагу pairing + allowlist, якщо ви не довіряєте повністю кожному учаснику кімнати. +- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в особистих повідомленнях. + - Коли `dmPolicy="pairing"`, схвалення записуються до сховища pairing allowlist з прив’язкою до облікового запису в `~/.openclaw/credentials/` (`-allowFrom.json` для облікового запису за замовчуванням, `--allowFrom.json` для неосновних облікових записів), а потім об’єднуються з allowlist із конфігурації. +- **Group allowlist** (специфічний для каналу): з яких саме груп/каналів/guild бот взагалі прийматиме повідомлення. + - Поширені шаблони: + - `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, якщо тільки ви повністю не довіряєте кожному учаснику кімнати. -Докладніше: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) +Подробиці: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) ## Prompt injection (що це таке і чому це важливо) -Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю, змушуючи її зробити щось небезпечне («ігноруй свої інструкції», «виведи вміст файлової системи», «перейди за цим посиланням і виконай команди» тощо). +Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «виведи вміст файлової системи», «перейди за цим посиланням і виконай команди» тощо). -Навіть із сильними системними промптами **prompt injection не вирішено**. Запобіжники в системному промпті — це лише м’які рекомендації; жорстке забезпечення дають політика інструментів, підтвердження exec, sandboxing і allowlist каналів (і оператори можуть свідомо це вимикати). Що реально допомагає на практиці: +Навіть із сильними системними промптами **prompt injection не вирішено**. Запобіжники системного промпту — це лише м’які рекомендації; жорстке забезпечення походить із політики інструментів, схвалень exec, sandboxing і allowlist каналів (і оператори за задумом можуть їх вимкнути). Що допомагає на практиці: - Тримайте вхідні DM закритими (pairing/allowlist). -- У групах віддавайте перевагу активації через згадування; уникайте «завжди активних» ботів у публічних кімнатах. +- У групах надавайте перевагу активації згадкою; уникайте «завжди активних» ботів у публічних кімнатах. - Вважайте посилання, вкладення та вставлені інструкції ворожими за замовчуванням. -- Запускайте чутливе виконання інструментів у sandbox; тримайте секрети поза файловою системою, доступною агенту. -- Примітка: sandboxing є опціональним. Якщо режим sandbox вимкнений, неявний `host=auto` визначається як хост gateway. Явний `host=sandbox` усе одно закривається безпечно, бо середовище sandbox недоступне. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно зафіксована в config. -- Обмежуйте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) довіреними агентами або явними allowlist. -- Якщо ви додаєте інтерпретатори в allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval усе одно вимагали явного підтвердження. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і неправильного використання інструментів. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. +- Запускайте чутливі інструменти виконання в sandbox; тримайте секрети поза досяжною для агента файловою системою. +- Примітка: sandboxing вмикається за бажанням. Якщо режим sandbox вимкнено, неявний `host=auto` розв’язується до хоста gateway. Явний `host=sandbox` усе одно безпечно завершується відмовою, оскільки runtime sandbox недоступний. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно відображена в конфігурації. +- Обмежуйте високоризикові інструменти (`exec`, `browser`, `web_fetch`, `web_search`) довіреними агентами або явними allowlist. +- Якщо ви використовуєте allowlist для інтерпретаторів (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval усе одно потребували явного схвалення. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і зловживання інструментами. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. Червоні прапорці, які слід вважати недовіреними: -- «Прочитай цей файл/URL і зроби рівно те, що там сказано.» -- «Ігноруй свій системний промпт або правила безпеки.» -- «Розкрий свої приховані інструкції або результати інструментів.» -- «Встав повний вміст `~/.openclaw` або своїх журналів.» +- «Прочитай цей файл/URL і зроби точно те, що там сказано». +- «Ігноруй свій системний промпт або правила безпеки». +- «Розкрий свої приховані інструкції або вивід інструментів». +- «Встав повний вміст ~/.openclaw або своїх логів». ## Прапорці обходу небезпечного зовнішнього контенту -OpenClaw містить явні прапорці обходу, які вимикають захисне обгортання зовнішнього контенту: +OpenClaw містить явні прапорці обходу, які вимикають безпечне обгортання зовнішнього контенту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -675,61 +682,61 @@ OpenClaw містить явні прапорці обходу, які вими Рекомендації: -- У production залишайте їх не встановленими/false. -- Вмикайте лише тимчасово для вузько обмеженого налагодження. -- Якщо ввімкнено, ізолюйте цього агента (sandbox + мінімум інструментів + окремий простір імен сеансів). +- Залишайте їх unset/false у production. +- Умикайте лише тимчасово для вузько обмеженого налагодження. +- Якщо їх увімкнено, ізолюйте такого агента (sandbox + мінімальні інструменти + окремий простір імен сесій). Примітка про ризики hooks: -- Payload hooks — це недовірений контент, навіть коли доставка походить із систем, які ви контролюєте (пошта/документи/вебконтент можуть нести prompt injection). -- Слабкіші рівні моделей збільшують цей ризик. Для автоматизації на основі hooks віддавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing там, де це можливо. +- Payload hooks — це недовірений контент, навіть коли доставка надходить із систем, які ви контролюєте (пошта/документи/вебконтент можуть нести prompt injection). +- Слабкі рівні моделей підвищують цей ризик. Для автоматизації на основі hooks надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів жорсткою (`tools.profile: "messaging"` або суворіше), а де можливо — додавайте sandboxing. ### Prompt injection не потребує публічних DM Навіть якщо **лише ви** можете писати боту, prompt injection усе одно може статися через будь-який **недовірений контент**, який читає бот (результати web search/fetch, сторінки браузера, -листи, документи, вкладення, вставлені журнали/код). Інакше кажучи: загрозою є не лише -відправник; сам **контент** також може містити ворожі інструкції. +листи, документи, вкладення, вставлені логи/код). Іншими словами: відправник — не +єдина поверхня загрози; **сам контент** також може містити супротивні інструкції. Коли інструменти ввімкнено, типовий ризик — це ексфільтрація контексту або запуск -викликів інструментів. Зменшити радіус ураження можна так: +викликів інструментів. Зменшуйте радіус ураження так: -- Використовуйте **агента-читача** лише для читання або без інструментів, щоб узагальнювати недовірений контент, - а потім передавайте підсумок основному агенту. -- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з інструментами, якщо в них немає потреби. -- Для URL-входів OpenResponses (`input_file` / `input_image`) установіть жорсткі +- Використовуйте **агента-читача** лише для читання або без інструментів, щоб підсумовувати недовірений контент, + а потім передавайте підсумок вашому основному агенту. +- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами, якщо в них немає потреби. +- Для URL-входів OpenResponses (`input_file` / `input_image`) установлюйте суворі `gateway.http.endpoints.responses.files.urlAllowlist` і `gateway.http.endpoints.responses.images.urlAllowlist`, а також тримайте `maxUrlParts` низьким. - Порожні allowlist трактуються як не встановлені; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, - якщо хочете повністю вимкнути завантаження URL. -- Для файлових входів OpenResponses декодований текст `input_file` усе одно ін’єктується як + Порожні allowlist трактуються як unset; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + якщо хочете повністю вимкнути отримання даних за URL. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно інжектується як **недовірений зовнішній контент**. Не покладайтеся на те, що текст файлу є довіреним лише тому, - що Gateway декодував його локально. Ін’єктований блок усе одно містить явні + що Gateway декодував його локально. Інжектований блок усе одно містить явні маркери меж `<<>>` плюс метадані `Source: External`, - хоча в цьому шляху і немає довшого банера `SECURITY NOTICE:`. + хоча цей шлях і пропускає довший банер `SECURITY NOTICE:`. - Те саме обгортання на основі маркерів застосовується, коли розуміння медіа витягує текст із прикріплених документів перед додаванням цього тексту до медіапромпту. -- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, який працює з недовіреним вводом. +- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, що працює з недовіреним вводом. - Тримайте секрети поза промптами; передавайте їх через env/config на хості gateway. -### Self-hosted бекенди LLM +### Самостійно розміщені бекенди LLM -Self-hosted бекенди, сумісні з OpenAI, такі як vLLM, SGLang, TGI, LM Studio -або власні стеки токенізаторів Hugging Face, можуть відрізнятися від хостованих провайдерів тим, -як обробляються спеціальні токени chat-template. Якщо бекенд токенізує буквальні рядки +Самостійно розміщені OpenAI-сумісні бекенди, такі як vLLM, SGLang, TGI, LM Studio +або власні стеки токенізації Hugging Face, можуть відрізнятися від хостованих провайдерів тим, +як обробляються спеціальні токени шаблонів чату. Якщо бекенд токенізує буквальні рядки на кшталт `<|im_start|>`, `<|start_header_id|>` або `` як -структурні токени chat-template всередині користувацького контенту, недовірений текст може спробувати -підробити межі ролей на рівні токенізатора. +структурні токени шаблону чату всередині контенту користувача, недовірений текст може +спробувати підробити межі ролей на рівні токенізатора. -OpenClaw видаляє типові літерали спеціальних токенів сімейств моделей із обгорнутого -зовнішнього контенту перед відправленням його моделі. Залишайте обгортання зовнішнього контенту -увімкненим і, коли це можливо, віддавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні +OpenClaw видаляє поширені літерали спеціальних токенів сімейств моделей із обгорнутого +зовнішнього контенту перед передаванням його моделі. Тримайте обгортання зовнішнього +контенту ввімкненим і, де це доступно, надавайте перевагу налаштуванням бекенда, які розділяють або екранують спеціальні токени в контенті, наданому користувачем. Хостовані провайдери, такі як OpenAI -та Anthropic, уже застосовують власну санітизацію на боці запиту. +та Anthropic, уже застосовують власну санітизацію на стороні запиту. -### Сила моделі (примітка щодо безпеки) +### Сила моделі (примітка з безпеки) -Стійкість до prompt injection **не є однаковою** для всіх рівнів моделей. Менші/дешевші моделі загалом більш вразливі до неправильного використання інструментів і захоплення інструкцій, особливо під ворожими промптами. +Стійкість до prompt injection **не** є однаковою на різних рівнях моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та захоплення інструкцій, особливо за супротивних промптів. Для агентів з увімкненими інструментами або агентів, які читають недовірений контент, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. @@ -737,81 +744,81 @@ OpenClaw видаляє типові літерали спеціальних т Рекомендації: -- **Використовуйте найновішу модель найкращого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених inbox; ризик prompt injection занадто високий. -- Якщо вам усе ж потрібно використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). -- Під час запуску малих моделей **увімкніть sandboxing для всіх сеансів** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються дуже жорстко. -- Для особистих асистентів лише для чату з довіреним вводом і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених вхідних скриньок; ризик prompt injection надто високий. +- Якщо вам все ж доводиться використовувати меншу модель, **зменшуйте радіус ураження** (інструменти лише для читання, жорсткий sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Коли запускаєте малі моделі, **увімкніть sandboxing для всіх сесій** і **вимкніть web_search/web_fetch/browser**, якщо тільки вхідні дані не контролюються дуже жорстко. +- Для особистих помічників лише для чату з довіреним вводом і без інструментів менші моделі зазвичай підходять. -## Міркування та докладний вивід у групах +## Reasoning і verbose-вивід у групах -`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішні міркування, вивід -інструментів або діагностику Plugin, які -не були призначені для публічного каналу. У групових середовищах вважайте їх **лише -для налагодження** і тримайте вимкненими, якщо тільки вони вам явно не потрібні. +`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє reasoning, вивід +інструментів або діагностику Plugin, що +не призначалося для публічного каналу. У групових середовищах ставтеся до них як до **лише налагоджувальних** +і тримайте вимкненими, якщо тільки вони вам явно не потрібні. Рекомендації: - Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. -- Якщо вмикаєте їх, робіть це лише в довірених DM або жорстко контрольованих кімнатах. -- Пам’ятайте: вивід verbose і trace може містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. +- Якщо ви їх увімкнули, робіть це лише в довірених DM або жорстко контрольованих кімнатах. +- Пам’ятайте: verbose- і trace-вивід можуть містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. ## Посилення конфігурації (приклади) -### 0) Дозволи на файли +### 0) Дозволи файлів -Тримайте config і стан приватними на хості gateway: +Тримайте конфігурацію і стан приватними на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) -- `~/.openclaw`: `700` (лише для користувача) +- `~/.openclaw`: `700` (лише користувач) -`openclaw doctor` може попередити про це і запропонувати посилити дозволи. +`openclaw doctor` може попередити про це й запропонувати посилити ці дозволи. ### 0.4) Мережева експозиція (bind + port + firewall) Gateway мультиплексує **WebSocket + HTTP** на одному порту: -- Типово: `18789` +- Типове значення: `18789` - Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` Ця HTTP-поверхня включає Control UI і хост canvas: - Control UI (ресурси SPA) (типовий базовий шлях `/`) -- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільні HTML/JS; вважайте це недовіреним контентом) +- Хост canvas: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільні HTML/JS; ставтеся до них як до недовіреного контенту) -Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: +Якщо ви відкриваєте контент canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: - Не відкривайте хост canvas для недовірених мереж/користувачів. -- Не робіть так, щоб вміст canvas мав той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. +- Не змушуйте контент canvas використовувати той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідків. -Режим bind визначає, де Gateway слухає з’єднання: +Режим bind визначає, де Gateway слухає підключення: -- `gateway.bind: "loopback"` (типово): можуть підключатися лише локальні клієнти. -- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише разом з auth gateway (спільний token/password або правильно налаштований trusted proxy не на loopback) і справжнім firewall. +- `gateway.bind: "loopback"` (типово): підключатися можуть лише локальні клієнти. +- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише з автентифікацією gateway (спільний token/password або коректно налаштований trusted proxy не на loopback) і справжнім firewall. Практичні правила: -- Віддавайте перевагу Tailscale Serve замість bind до LAN (Serve зберігає Gateway на loopback, а доступом керує Tailscale). -- Якщо вам усе ж потрібен bind до LAN, обмежте порт у firewall жорстким allowlist IP-адрес джерела; не робіть широке перенаправлення порту. +- Надавайте перевагу Tailscale Serve замість bind у LAN (Serve залишає Gateway на loopback, а Tailscale обробляє доступ). +- Якщо все ж потрібен bind у LAN, обмежте порт через firewall жорстким allowlist IP-джерел; не робіть широке port-forwarding. - Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. ### 0.4.1) Публікація портів Docker + UFW (`DOCKER-USER`) Якщо ви запускаєте OpenClaw у Docker на VPS, пам’ятайте, що опубліковані порти контейнера -(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги forwarding Docker, -а не лише через правила `INPUT` хоста. +(`-p HOST:CONTAINER` або `ports:` у Compose) маршрутизуються через ланцюги пересилання Docker, +а не лише через правила host `INPUT`. -Щоб узгодити трафік Docker із вашою політикою firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюг перевіряється раніше за власні правила дозволу Docker). -На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` -і все одно застосовують ці правила до backend nftables. +Щоб трафік Docker відповідав вашій політиці firewall, застосовуйте правила в +`DOCKER-USER` (цей ланцюг обробляється до власних правил accept Docker). +На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують фронтенд `iptables-nft` +і все одно застосовують ці правила до бекенда nftables. Мінімальний приклад allowlist (IPv4): ```bash -# /etc/ufw/after.rules (додайте як окремий розділ *filter) +# /etc/ufw/after.rules (додайте як окрему секцію *filter) *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN @@ -827,12 +834,12 @@ Gateway мультиплексує **WebSocket + HTTP** на одному пор COMMIT ``` -Для IPv6 є окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо +IPv6 має окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо увімкнено Docker IPv6. -Уникайте жорсткого зашивання назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів -різняться між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково -обійти ваше правило deny. +Уникайте жорсткого задання назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів +відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідності можуть випадково +пропустити ваше правило deny. Швидка перевірка після перезавантаження: @@ -843,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 (розкриває ім’я користувача та місце встановлення) +- `cliPath`: повний шлях файлової системи до бінарника CLI (розкриває ім’я користувача та місце встановлення) - `sshPort`: рекламує доступність SSH на хості - `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування операційної безпеки:** трансляція деталей інфраструктури полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація на кшталт шляхів файлової системи та доступності SSH допомагає зловмисникам картографувати ваше середовище. +**Міркування операційної безпеки:** трансляція деталей інфраструктури полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та доступність SSH, допомагає зловмисникам картографувати ваше середовище. **Рекомендації:** -1. **Мінімальний режим** (типовий, рекомендований для відкритих gateway): не включає чутливі поля до трансляцій mDNS: +1. **Мінімальний режим** (типово, рекомендовано для відкритих gateway): опускає чутливі поля з трансляцій mDNS: ```json5 { @@ -868,7 +875,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Повністю вимкніть**, якщо вам не потрібне виявлення локальними пристроями: +2. **Повністю вимкнути**, якщо вам не потрібне локальне виявлення пристроїв: ```json5 { @@ -888,19 +895,20 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін config. +4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін у конфігурації. -У мінімальному режимі Gateway усе ще транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане підключення WebSocket. +У мінімальному режимі Gateway усе ще транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане з’єднання WebSocket. -### 0.5) Захистіть Gateway WebSocket (локальна auth) +### 0.5) Захистіть WebSocket Gateway (локальна автентифікація) -Auth Gateway **обов’язкова за замовчуванням**. Якщо не налаштовано -жодного дійсного шляху auth gateway, Gateway відмовляє в підключеннях WebSocket (fail‑closed). +Автентифікація Gateway **обов’язкова за замовчуванням**. Якщо не налаштовано +жодного валідного шляху автентифікації gateway, Gateway відмовляє у з’єднаннях WebSocket +(безпечна відмова). -Під час онбордингу типово генерується token (навіть для loopback), тому -локальні клієнти повинні проходити автентифікацію. +Онбординг типово генерує token (навіть для loopback), тож +локальні клієнти мають автентифікуватися. -Установіть token, щоб **усі** WS-клієнти мали проходити автентифікацію: +Установіть token, щоб **усі** WS-клієнти мусили автентифікуватися: ```json5 { @@ -917,31 +925,31 @@ Doctor може згенерувати його для вас: `openclaw doctor Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не встановлено. Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через -SecretRef і його не вдається розв’язати, розв’язання завершується fail closed (без маскування через fallback remote). -Необов’язково: зафіксуйте віддалений TLS через `gateway.remote.tlsFingerprint` під час використання `wss://`. -Нешифрований `ws://` типово дозволений лише для loopback. Для довірених шляхів у приватній мережі -встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. +SecretRef і його не вдається розв’язати, розв’язання завершується безпечним відмовленням (жоден fallback remote не маскує проблему). +Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint` при використанні `wss://`. +Відкритий `ws://` типово дозволено лише для loopback. Для довірених шляхів +у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний обхід. Локальне pairing пристроїв: -- Pairing пристроїв автоматично схвалюється для прямих локальних loopback-підключень, щоб - спростити роботу клієнтів на тому самому хості. +- Pairing пристрою автоматично схвалюється для прямих локальних loopback-з’єднань, щоб + забезпечити зручну роботу клієнтів на тому самому хості. - OpenClaw також має вузький шлях backend/container-local self-connect для - довірених потоків допоміжних засобів зі спільним секретом. -- Підключення через tailnet і LAN, включно з bind tailnet на тому самому хості, вважаються - віддаленими для pairing і все одно потребують схвалення. + довірених допоміжних потоків зі спільним секретом. +- Підключення через tailnet і LAN, включно з bind через tailnet на тому самому хості, розглядаються як + віддалені для pairing і все одно потребують схвалення. -Режими 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)). +- `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)). Контрольний список ротації (token/password): 1. Згенеруйте/встановіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). -2. Перезапустіть Gateway (або програму macOS, якщо вона керує Gateway). -3. Оновіть усіх віддалених клієнтів (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). +2. Перезапустіть Gateway (або перезапустіть програму macOS, якщо вона керує Gateway). +3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які викликають Gateway). 4. Переконайтеся, що зі старими обліковими даними підключитися більше не можна. ### 0.6) Заголовки ідентичності Tailscale Serve @@ -949,98 +957,107 @@ SecretRef і його не вдається розв’язати, розв’я Коли `gateway.auth.allowTailscale` має значення `true` (типово для Serve), OpenClaw приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації Control UI/WebSocket. OpenClaw перевіряє ідентичність, розв’язуючи адресу -`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і звіряючи її +`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і зіставляючи її із заголовком. Це спрацьовує лише для запитів, що потрапляють на loopback -і містять `x-forwarded-for`, `x-forwarded-proto` і `x-forwarded-host`, як -їх додає Tailscale. -Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` -серіалізуються до того, як limiter зафіксує помилку. Тому паралельні хибні повторні спроби -від одного клієнта Serve можуть заблокувати другу спробу негайно, -а не пройти паралельно як дві звичайні невідповідності. -HTTP API-ендпоїнти (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують auth через заголовки ідентичності Tailscale. Вони й надалі дотримуються -налаштованого режиму HTTP auth gateway. +і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, як +їх інжектує Tailscale. +Для цього асинхронного шляху перевірки ідентичності невдалі спроби для однакових `{scope, ip}` +серіалізуються до того, як лімітатор зафіксує невдачу. Тому одночасні хибні повторні спроби +від одного клієнта Serve можуть одразу заблокувати другу спробу, +а не пройти гонкою як дві звичайні невідповідності. +Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) +**не** використовують автентифікацію через заголовки ідентичності Tailscale. Вони й надалі дотримуються +налаштованого режиму HTTP-автентифікації gateway. -Важлива примітка про межі: +Важлива примітка щодо меж: -- HTTP bearer auth Gateway фактично дає повний або нульовий операторський доступ. -- Сприймайте облікові дані, що можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як повносекретні операторські секрети для цього gateway. -- На HTTP-поверхні, сумісній з OpenAI, bearer auth зі спільним секретом відновлює повний типовий набір операторських областей (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. -- Семантика областей для кожного окремого HTTP-запиту застосовується лише тоді, коли запит надходить із режиму з носієм ідентичності, як-от trusted proxy auth або `gateway.auth.mode="none"` на приватному вході. -- У таких режимах із носієм ідентичності пропуск `x-openclaw-scopes` повертає стандартний типовий набір операторських областей; надсилайте цей заголовок явно, якщо хочете вужчий набір областей. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password і там теж вважається повним операторським доступом, тоді як режими з носієм ідентичності й далі поважають оголошені області. -- Не передавайте ці облікові дані недовіреним викликаючим; віддавайте перевагу окремим 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`) і семантику owner для ходів агента; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. +- Семантика областей доступу для кожного запиту в HTTP застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як автентифікація trusted proxy або `gateway.auth.mode="none"` на приватному вході. +- У цих режимах, що несуть ідентичність, пропуск `x-openclaw-scopes` повертає звичайний типовий набір операторських областей; надсилайте цей заголовок явно, коли хочете вужчий набір областей. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer-автентифікація token/password також вважається повним операторським доступом, тоді як режими, що несуть ідентичність, усе ще поважають оголошені області доступу. +- Не діліться цими обліковими даними з недовіреними викликаючими сторонами; натомість використовуйте окремі Gateway для кожної межі довіри. -**Припущення довіри:** auth Serve без token припускає, що хост gateway є довіреним. +**Припущення довіри:** автентифікація Serve без token припускає, що хост gateway є довіреним. Не вважайте це захистом від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явну auth зі спільним секретом через `gateway.auth.mode: "token"` або +і вимагайте явну автентифікацію зі спільним секретом через `gateway.auth.mode: "token"` або `"password"`. **Правило безпеки:** не пересилайте ці заголовки зі свого reverse proxy. Якщо -ви завершуєте TLS або використовуєте proxy перед gateway, вимкніть -`gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: -"token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) -натомість. +ви завершуєте TLS або проксіюєте трафік перед gateway, вимкніть +`gateway.auth.allowTailscale` і використовуйте автентифікацію зі спільним секретом (`gateway.auth.mode: +"token"` або `"password"`) або натомість [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). -Trusted proxy: +Довірені 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-перевірок автентифікації. - Переконайтеся, що ваш proxy **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. -Див. [Tailscale](/uk/gateway/tailscale) і [Web overview](/web). +Див. [Tailscale](/uk/gateway/tailscale) і [Огляд вебінтерфейсу](/web). -### 0.6.1) Керування браузером через хост node (рекомендовано) +### 0.6.1) Керування браузером через host node (рекомендовано) -Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **хост node** +Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запускайте **host node** на машині з браузером і дозвольте Gateway проксувати дії браузера (див. [Browser tool](/uk/tools/browser)). Ставтеся до pairing node як до адміністративного доступу. Рекомендований шаблон: -- Тримайте Gateway і хост node в одній tailnet (Tailscale). -- Виконуйте pairing node свідомо; вимикайте маршрутизацію проксі браузера, якщо вона вам не потрібна. +- Тримайте Gateway і host node в одній tailnet (Tailscale). +- Pairing node виконуйте свідомо; вимкніть маршрутизацію проксі браузера, якщо вона вам не потрібна. Уникайте: -- Відкривати relay/control-порти через LAN або публічний інтернет. -- Tailscale Funnel для ендпоїнтів керування браузером (публічна експозиція). +- Відкриття relay/control-портів у LAN або публічному інтернеті. +- Tailscale Funnel для кінцевих точок керування браузером (публічна експозиція). ### 0.7) Секрети на диску (чутливі дані) -Виходьте з того, що будь-що в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: +Вважайте, що все під `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: config може містити токени (gateway, віддалений gateway), налаштування провайдера та allowlist. -- `credentials/**`: облікові дані каналів (наприклад, creds WhatsApp), allowlist pairing, імпорти застарілого OAuth. +- `openclaw.json`: конфігурація може містити токени (gateway, віддалений gateway), налаштування провайдерів і allowlist. +- `credentials/**`: облікові дані каналів (приклад: облікові дані WhatsApp), pairing allowlist, застарілі імпорти OAuth. - `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени та необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): payload секретів із файлу, який використовується провайдерами SecretRef типу `file` (`secrets.providers`). -- `agents//agent/auth.json`: файл сумісності зі застарілими версіями. Статичні записи `api_key` очищаються, коли їх виявлено. -- `agents//sessions/**`: транскрипти сеансів (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. -- вбудовані пакети plugin: установлені Plugin (разом із їхніми `node_modules/`). -- `sandboxes/**`: workspace sandbox інструментів; там можуть накопичуватися копії файлів, які ви читаєте/записуєте всередині sandbox. +- `secrets.json` (необов’язково): вміст секретів на основі файлу, який використовується провайдерами SecretRef типу `file` (`secrets.providers`). +- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються, коли їх виявлено. +- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та вивід інструментів. +- пакети вбудованих Plugin: встановлені Plugins (разом з їхніми `node_modules/`). +- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте всередині sandbox. Поради щодо посилення захисту: - Тримайте дозволи жорсткими (`700` для каталогів, `600` для файлів). -- Використовуйте повне шифрування диска на хості gateway. -- Якщо хост спільний, віддавайте перевагу виділеному обліковому запису користувача ОС для Gateway. +- Використовуйте повнодискове шифрування на хості gateway. +- Якщо хост спільний, бажано виділити окремий обліковий запис користувача ОС для Gateway. -### 0.8) Журнали + транскрипти (редагування + зберігання) +### 0.8) Файли `.env` у workspace -Журнали та транскрипти можуть призводити до витоку чутливої інформації, навіть коли контроль доступу налаштовано правильно: +OpenClaw завантажує локальні для workspace файли `.env` для агентів та інструментів, але ніколи не дозволяє цим файлам непомітно перевизначати елементи керування runtime gateway. -- Журнали Gateway можуть містити підсумки інструментів, помилки та URL. -- Транскрипти сеансів можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. +- Будь-який ключ, що починається з `OPENCLAW_*`, блокується в недовірених файлах `.env` workspace. +- Блокування працює за принципом fail-closed: нова змінна керування runtime, додана в майбутньому релізі, не зможе успадковуватися з `.env`, що потрапив у репозиторій або був наданий зловмисником; ключ ігнорується, а gateway зберігає власне значення. +- Довірені змінні середовища процесу/ОС (власна оболонка gateway, launchd/systemd unit, app bundle) усе ще застосовуються — це обмеження стосується лише завантаження файлів `.env`. + +Чому: файли `.env` workspace часто лежать поруч із кодом агента, випадково комітяться або створюються інструментами. Блокування всього префікса `OPENCLAW_*` означає, що додавання нового прапорця `OPENCLAW_*` у майбутньому ніколи не призведе до регресії через тихе успадкування зі стану workspace. + +### 0.9) Логи + транскрипти (редагування + зберігання) + +Логи та транскрипти можуть розкривати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: + +- Логи Gateway можуть містити зведення інструментів, помилки й URL. +- Транскрипти сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. Рекомендації: -- Залишайте ввімкненим редагування підсумків інструментів (`logging.redactSensitive: "tools"`; типово). -- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). -- Коли ділитеся діагностикою, віддавайте перевагу `openclaw status --all` (можна вставляти, секрети приховано) замість сирих журналів. -- Очищайте старі транскрипти сеансів і log-файли, якщо вам не потрібне довге зберігання. +- Тримайте редагування зведень інструментів увімкненим (`logging.redactSensitive: "tools"`; типово). +- Додавайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). +- Коли ділитеся діагностикою, надавайте перевагу `openclaw status --all` (можна вставляти, секрети відредаговано), а не сирим логам. +- Видаляйте старі транскрипти сесій і файли логів, якщо вам не потрібне довготривале зберігання. -Докладніше: [Logging](/uk/gateway/logging) +Подробиці: [Logging](/uk/gateway/logging) ### 1) DM: pairing за замовчуванням @@ -1050,7 +1067,7 @@ Trusted proxy: } ``` -### 2) Групи: всюди вимагати згадування +### 2) Групи: усюди вимагати згадку ```json { @@ -1072,31 +1089,31 @@ Trusted proxy: } ``` -У групових чатах відповідайте лише за явного згадування. +У групових чатах відповідайте лише тоді, коли є явна згадка. ### 3) Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі номера телефону розгляньте запуск вашого AI на окремому номері, а не на вашому особистому: +Для каналів на основі телефонного номера розгляньте запуск вашого AI на окремому номері телефону від особистого: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: цим займається AI, із відповідними межами +- Номер бота: AI обробляє їх у відповідних межах -### 4) Режим лише для читання (через sandbox + tools) +### 4) Режим лише для читання (через sandbox + інструменти) -Ви можете побудувати профіль лише для читання, поєднавши: +Ви можете створити профіль лише для читання, поєднавши: - `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` для повної відсутності доступу до workspace) -- списки allow/deny інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо. +- 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` і шляхи автозавантаження зображень у нативних промптах каталогом workspace (корисно, якщо сьогодні ви дозволяєте абсолютні шляхи й хочете одну запобіжну межу). -- Тримайте корені файлової системи вузькими: уникайте широких коренів на кшталт вашого домашнього каталогу для workspace агента/workspace sandbox. Широкі корені можуть відкрити файловим інструментам доступ до чутливих локальних файлів (наприклад, стан/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 каталогом workspace (корисно, якщо ви сьогодні дозволяєте абсолютні шляхи й хочете один загальний запобіжник). +- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от ваш домашній каталог, для workspace агента/робочих просторів sandbox. Широкі корені можуть відкрити чутливі локальні файли (наприклад state/config під `~/.openclaw`) для файлових інструментів. -### 5) Безпечна базова конфігурація (копіювати/вставити) +### 5) Безпечний базовий рівень (копіювати/вставити) -Одна «безпечна конфігурація за замовчуванням», яка тримає Gateway приватним, вимагає DM pairing і уникає завжди активних ботів у групах: +Одна «безпечна за замовчуванням» конфігурація, яка тримає Gateway приватним, вимагає pairing для DM і уникає завжди активних ботів у групах: ```json5 { @@ -1115,9 +1132,9 @@ Trusted proxy: } ``` -Якщо ви також хочете «безпечніше за замовчуванням» для виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого агента, який не є власником (приклад нижче в розділі «Профілі доступу на рівні агентів»). +Якщо ви хочете також «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого агента, який не є owner (приклад нижче в розділі «Профілі доступу на рівні агента»). -Вбудована базова конфігурація для chat-driven ходів агента: відправники, які не є власниками, не можуть використовувати інструменти `cron` або `gateway`. +Вбудований базовий рівень для ходів агента, керованих чатом: відправники, які не є owner, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) @@ -1125,59 +1142,59 @@ Trusted proxy: Два взаємодоповнювальні підходи: -- **Запуск усього Gateway в Docker** (межа контейнера): [Docker](/uk/install/docker) -- **Sandbox інструментів** (`agents.defaults.sandbox`, gateway на хості + інструменти, ізольовані sandbox; Docker — типовий backend): [Sandboxing](/uk/gateway/sandboxing) +- **Запустити весь Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) +- **Sandbox для інструментів** (`agents.defaults.sandbox`, host gateway + інструменти, ізольовані sandbox; Docker — типовий бекенд): [Sandboxing](/uk/gateway/sandboxing) -Примітка: щоб запобігти доступу між агентами, тримайте `agents.defaults.sandbox.scope` на `"agent"` (типово) -або `"session"` для суворішої ізоляції сеансів. `scope: "shared"` використовує +Примітка: щоб запобігти доступу між агентами, тримайте `agents.defaults.sandbox.scope` у значенні `"agent"` (типово) +або `"session"` для суворішої ізоляції на рівні сесій. `scope: "shared"` використовує один контейнер/workspace. Також враховуйте доступ агента до workspace всередині sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) не дає доступу до workspace агента; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` -- `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента як лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) тримає workspace агента поза доступом; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace агента для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонічними шляхами джерела. Трюки із symlink батьківського каталогу та канонічні псевдоніми home усе одно завершуються fail closed, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у home ОС. +- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонічними шляхами джерел. Хитрощі з батьківськими symlink і канонічними псевдонімами домашнього каталогу все одно безпечно завершуються відмовою, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у home ОС. -Важливо: `tools.elevated` — це глобальний базовий шлях виходу, який запускає exec поза sandbox. Ефективним host типово є `gateway`, або `node`, коли ціль exec налаштована на `node`. Тримайте `tools.elevated.allowFrom` вузьким і не вмикайте його для сторонніх. Ви можете додатково обмежити elevated для окремого агента через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). +Важливо: `tools.elevated` — це глобальний аварійний вихід із базового рівня, який запускає exec поза sandbox. Ефективний host типово `gateway`, або `node`, коли ціль exec налаштована на `node`. Тримайте `tools.elevated.allowFrom` жорстким і не вмикайте його для сторонніх людей. Ви також можете додатково обмежити elevated для окремих агентів через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). ### Запобіжник делегування субагентів -Якщо ви дозволяєте session tools, ставтеся до делегованих запусків субагентів як до ще одного рішення про межі: +Якщо ви дозволяєте інструменти сесій, ставтеся до делегованих запусків субагентів як до ще одного рішення про межу доступу: - Забороняйте `sessions_spawn`, якщо агенту справді не потрібне делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агента обмеженими до відомо безпечних цільових агентів. -- Для будь-якого потоку, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). -- `sandbox: "require"` завершується з помилкою одразу, якщо цільове дочірнє середовище не ізольоване sandbox. +- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агента обмеженими відомо безпечними цільовими агентами. +- Для будь-якого процесу, який повинен залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` швидко завершується помилкою, якщо цільовий дочірній runtime не перебуває в sandbox. ## Ризики керування браузером -Увімкнення керування браузером дає моделі змогу керувати справжнім браузером. -Якщо профіль цього браузера вже містить активні сеанси входу, модель може -отримати доступ до цих облікових записів і даних. Розглядайте профілі браузера як **чутливий стан**: +Увімкнення керування браузером дає моделі можливість керувати реальним браузером. +Якщо цей профіль браузера вже містить виконані входи в акаунти, модель може +отримувати доступ до цих акаунтів і даних. Ставтеся до профілів браузера як до **чутливого стану**: -- Віддавайте перевагу виділеному профілю для агента (типовий профіль `openclaw`). -- Не спрямовуйте агента на ваш особистий щоденний профіль. -- Для агентів у sandbox тримайте host browser control вимкненим, якщо ви їм не довіряєте. -- Окремий loopback API керування браузером приймає лише auth зі спільним секретом - (bearer auth через token gateway або пароль gateway). Він не використовує +- Надавайте перевагу окремому профілю для агента (типовий профіль `openclaw`). +- Уникайте спрямовувати агента на ваш особистий щоденний профіль. +- Тримайте керування браузером на host вимкненим для агентів у sandbox, якщо ви їм не довіряєте. +- Окремий loopback API керування браузером приймає лише автентифікацію зі спільним секретом + (bearer-автентифікацію токеном gateway або паролем gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Розглядайте завантаження браузера як недовірений ввід; віддавайте перевагу ізольованому каталогу завантажень. +- Ставтеся до завантажень браузера як до недовіреного вводу; бажано використовувати ізольований каталог завантажень. - Якщо можливо, вимкніть синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). -- Для віддалених gateway вважайте, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. -- Тримайте Gateway і хости node доступними лише в tailnet; уникайте відкриття портів керування браузером у LAN або публічний інтернет. -- Вимикайте маршрутизацію проксі браузера, коли вона вам не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим existing-session у Chrome MCP **не є** «безпечнішим»; він може діяти від вашого імені там, куди має доступ цей профіль Chrome на хості. +- Для віддалених Gateway припускайте, що «керування браузером» дорівнює «операторському доступу» до всього, до чого має доступ цей профіль. +- Тримайте Gateway і host node лише в tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. +- Вимикайте маршрутизацію проксі браузера, коли вона не потрібна (`gateway.nodes.browser.mode="off"`). +- Режим Chrome MCP existing-session **не** є «безпечнішим»; він може діяти від вашого імені в усьому, до чого має доступ цей профіль Chrome на хості. -### Політика SSRF браузера (типово сувора) +### Політика SSRF браузера (сувора за замовчуванням) -Політика навігації браузера OpenClaw типово сувора: приватні/внутрішні призначення залишаються заблокованими, якщо ви явно не дозволите їх. +Політика навігації браузера OpenClaw сувора за замовчуванням: приватні/внутрішні призначення залишаються заблокованими, якщо ви явно не дозволите їх. -- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера зберігає блокування для приватних/внутрішніх/special-use призначень. +- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тож навігація браузера блокує приватні/внутрішні/спеціального призначення адреси. - Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. -- Режим явного ввімкнення: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use призначення. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки хостів, включно із заблокованими іменами, як-от `localhost`) для явних винятків. -- Навігація перевіряється до запиту й повторно перевіряється best-effort за фінальним URL `http(s)` після навігації, щоб зменшити можливість pivot через редиректи. +- Режим явного ввімкнення: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/спеціального призначення адреси. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для хостів, зокрема заблоковані імена, такі як `localhost`) для явних винятків. +- Навігація перевіряється до запиту й повторно перевіряється, наскільки можливо, на фінальному URL `http(s)` після навігації, щоб зменшити можливість pivot через редиректи. Приклад суворої політики: @@ -1193,13 +1210,13 @@ Trusted proxy: } ``` -## Профілі доступу на рівні агентів (multi-agent) +## Профілі доступу на рівні агента (multi-agent) -У разі маршрутизації multi-agent кожен агент може мати власну політику sandbox + tools: -використовуйте це, щоб надавати **повний доступ**, **лише читання** або **жодного доступу** для окремих агентів. -Повні подробиці та правила пріоритетності див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +За маршрутизації multi-agent кожен агент може мати власну політику sandbox + інструментів: +використовуйте це, щоб надавати **повний доступ**, **лише читання** або **жодного доступу** для кожного агента. +Повні подробиці та правила пріоритету див. в [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). -Типові сценарії використання: +Поширені сценарії використання: - Особистий агент: повний доступ, без sandbox - Сімейний/робочий агент: sandbox + інструменти лише для читання @@ -1245,7 +1262,7 @@ Trusted proxy: } ``` -### Приклад: без доступу до файлової системи/оболонки (дозволено обмін повідомленнями через провайдера) +### Приклад: без доступу до файлової системи/оболонки (дозволено обмін повідомленнями провайдера) ```json5 { @@ -1259,9 +1276,9 @@ Trusted proxy: scope: "agent", workspaceAccess: "none", }, - // Інструменти сеансів можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти - // поточним сеансом + сеансами запущених субагентів, але за потреби ви можете затиснути їх ще сильніше. - // Див. `tools.sessions.visibility` у довіднику з конфігурації. + // Інструменти сесій можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти + // поточною сесією + сесіями запущених субагентів, але за потреби ви можете обмежити ще сильніше. + // Див. `tools.sessions.visibility` у довідці з конфігурації. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1296,57 +1313,57 @@ Trusted proxy: } ``` -## Що сказати своєму AI +## Що сказати вашому AI -Додайте рекомендації з безпеки до системного промпту свого агента: +Додайте рекомендації з безпеки до системного промпту вашого агента: ``` ## Правила безпеки -- Ніколи не показуй стороннім списки каталогів або шляхи до файлів -- Ніколи не розкривай API-ключі, облікові дані або деталі інфраструктури -- Перевіряй запити на зміну config системи з власником -- Якщо є сумніви, спочатку запитай -- Зберігай приватні дані приватними, якщо немає явної авторизації +- Ніколи не діліться списками каталогів або шляхами до файлів із незнайомцями +- Ніколи не розкривайте API-ключі, облікові дані або деталі інфраструктури +- Перевіряйте із власником запити, що змінюють конфігурацію системи +- Якщо є сумніви, перепитайте перед дією +- Тримайте приватні дані приватними, якщо немає явного дозволу ``` ## Реагування на інциденти -Якщо ваш AI зробив щось погане: +Якщо ваш AI робить щось погане: -### Локалізація +### Стримування -1. **Зупиніть це:** зупиніть програму macOS (якщо вона керує Gateway) або завершіть процес `openclaw gateway`. +1. **Зупиніть його:** зупиніть програму macOS (якщо вона керує Gateway) або завершіть процес `openclaw gateway`. 2. **Закрийте експозицію:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** переведіть ризиковані DM/групи в `dmPolicy: "disabled"` / вимагайте згадування і приберіть записи `"*"`, що дозволяють усім, якщо вони у вас були. +3. **Заморозьте доступ:** переведіть ризиковані DM/групи на `dmPolicy: "disabled"` / вимагайте згадки, і приберіть записи `"*"` із режимом «дозволити все», якщо вони були. ### Ротація (припускайте компрометацію, якщо секрети витекли) -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 (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. +2. Замініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на всіх машинах, які можуть викликати Gateway. +3. Замініть облікові дані провайдерів/API (облікові дані 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/group, `tools.elevated`, зміни Plugin). -4. Повторно запустіть `openclaw security audit --deep` і підтвердьте, що findings рівня critical усунено. +3. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни Plugin). +4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні результати усунено. -### Зберіть дані для звіту +### Що зібрати для звіту - Часову позначку, ОС хоста gateway + версію OpenClaw -- Транскрипти сеансів + короткий tail журналу (після редагування) +- Транскрипти сесій + короткий хвіст логів (після редагування) - Що надіслав зловмисник + що зробив агент -- Чи був Gateway доступний за межами loopback (LAN/Tailscale Funnel/Serve) +- Чи був Gateway відкритий за межі loopback (LAN/Tailscale Funnel/Serve) -## Secret Scanning (`detect-secrets`) +## Сканування секретів (detect-secrets) CI запускає pre-commit hook `detect-secrets` у job `secrets`. Push у `main` завжди запускає сканування всіх файлів. Pull request використовують -швидкий шлях для змінених файлів, коли доступний базовий коміт, і переходять до -сканування всіх файлів в іншому разі. Якщо перевірка не пройшла, з’явилися нові кандидати, яких ще немає в baseline. +швидкий шлях за зміненими файлами, коли доступний базовий коміт, і переходять +до сканування всіх файлів в іншому разі. Якщо перевірка не проходить, є нові кандидати, яких ще немає в baseline. -### Якщо CI не пройшов +### Якщо CI не проходить 1. Відтворіть локально: @@ -1354,10 +1371,10 @@ Push у `main` завжди запускає сканування всіх фа pre-commit run --all-files detect-secrets ``` -2. Розберіться з інструментами: - - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з - baseline та винятками репозиторію. - - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline +2. Зрозумійте інструменти: + - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з baseline + і виключеннями репозиторію. + - `detect-secrets audit` відкриває інтерактивну перевірку, щоб позначити кожен елемент baseline як справжній секрет або хибнопозитивний результат. 3. Для справжніх секретів: замініть/видаліть їх, потім повторно запустіть сканування, щоб оновити baseline. 4. Для хибнопозитивних результатів: запустіть інтерактивний аудит і позначте їх як хибні: @@ -1366,16 +1383,16 @@ Push у `main` завжди запускає сканування всіх фа detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові винятки, додайте їх до `.detect-secrets.cfg` і перегенеруйте - baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (config-файл - є лише довідковим; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові виключення, додайте їх до `.detect-secrets.cfg` і перегенеруйте + baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл + конфігурації тут лише довідковий; detect-secrets не читає його автоматично). -Закомітьте оновлений `.secrets.baseline`, коли він відображатиме бажаний стан. +Закомітьте оновлений `.secrets.baseline`, щойно він відображатиме бажаний стан. ## Повідомлення про проблеми безпеки -Знайшли вразливість в OpenClaw? Повідомте відповідально: +Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте її публічно до виправлення -3. Ми зазначимо вас у подяках (якщо ви не віддаєте перевагу анонімності) +2. Не публікуйте її до виправлення +3. Ми вкажемо вас у подяках (якщо тільки ви не віддаєте перевагу анонімності) diff --git a/docs/uk/tools/slash-commands.md b/docs/uk/tools/slash-commands.md index 5c16570fa..ca21a05bc 100644 --- a/docs/uk/tools/slash-commands.md +++ b/docs/uk/tools/slash-commands.md @@ -5,32 +5,32 @@ read_when: summary: 'Слеш-команди: текстові проти нативних, конфігурація та підтримувані команди' title: Слеш-команди x-i18n: - generated_at: "2026-04-21T15:19:36Z" + generated_at: "2026-04-21T20:23:17Z" model: gpt-5.4 provider: openai - source_hash: 26923608329ba2aeece2d4bc8edfa40ae86e03719a9f590f26ff79f57d97521d + source_hash: 43cc050149de60ca39083009fd6ce566af3bfa79d455e2e0f44e2d878bf4d2d9 source_path: tools/slash-commands.md workflow: 15 --- # Слеш-команди -Команди обробляє Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. +Команди обробляються Gateway. Більшість команд треба надсилати як **окреме** повідомлення, що починається з `/`. Команда чату bash лише для хоста використовує `! ` (із `/bash ` як псевдонімом). Є дві пов’язані системи: - **Команди**: окремі повідомлення `/...`. - **Директиви**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - - Директиви видаляються з повідомлення до того, як його побачить модель. + - Директиви видаляються з повідомлення до того, як модель його побачить. - У звичайних повідомленнях чату (не лише з директивами) вони трактуються як «вбудовані підказки» і **не** зберігають налаштування сесії. - - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та повертають підтвердження. + - У повідомленнях, що містять лише директиви (повідомлення складається тільки з директив), вони зберігаються в сесії та повертають підтвердження. - Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, це єдиний - використовуваний список дозволу; інакше авторизація надходить зі списків дозволу/сполучення каналу разом із `commands.useAccessGroups`. + allowlist, який використовується; інакше авторизація походить із allowlist каналів/парингу та `commands.useAccessGroups`. Неавторизовані відправники бачать директиви як звичайний текст. -Також є кілька **вбудованих скорочень** (лише для відправників зі списку дозволу/авторизованих): `/help`, `/commands`, `/status`, `/whoami` (`/id`). -Вони виконуються негайно, видаляються до того, як повідомлення побачить модель, а решта тексту продовжує оброблятися звичайним шляхом. +Також є кілька **вбудованих скорочень** (лише для allowlisted/авторизованих відправників): `/help`, `/commands`, `/status`, `/whoami` (`/id`). +Вони запускаються негайно, видаляються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайним шляхом. ## Конфігурація @@ -60,107 +60,107 @@ x-i18n: ``` - `commands.text` (типово `true`) вмикає розбір `/...` у повідомленнях чату. - - На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення в `false`. + - На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це в `false`. - `commands.native` (типово `"auto"`) реєструє нативні команди. - - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash commands); ігнорується для провайдерів без нативної підтримки. - - Щоб перевизначити параметр для конкретного провайдера, задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native` (bool або `"auto"`). - - `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і не видаляються автоматично. -- `commands.nativeSkills` (типово `"auto"`) реєструє нативно команди **Skills**, коли це підтримується. - - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення окремої slash command для кожної навички). - - Щоб перевизначити параметр для конкретного провайдера, задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills` (bool або `"auto"`). -- `commands.bash` (типово `false`) вмикає `! ` для виконання команд оболонки хоста (`/bash ` — псевдонім; потребує списків дозволу `tools.elevated`). + - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash-команди); ігнорується для провайдерів без нативної підтримки. + - Щоб перевизначити для окремого провайдера, встановіть `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native` (bool або `"auto"`). + - `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і автоматично не видаляються. +- `commands.nativeSkills` (типово `"auto"`) реєструє команди **Skills** нативно, коли це підтримується. + - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створювати slash-команду для кожної навички). + - Щоб перевизначити для окремого провайдера, встановіть `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills` (bool або `"auto"`). +- `commands.bash` (типово `false`) вмикає `! ` для запуску shell-команд хоста (`/bash ` — псевдонім; потребує allowlist у `tools.elevated`). - `commands.bashForegroundMs` (типово `2000`) визначає, як довго bash чекає перед переходом у фоновий режим (`0` одразу переводить у фон). - `commands.config` (типово `false`) вмикає `/config` (читання/запис `openclaw.json`). - `commands.mcp` (типово `false`) вмикає `/mcp` (читання/запис конфігурації MCP, якою керує OpenClaw, у `mcp.servers`). -- `commands.plugins` (типово `false`) вмикає `/plugins` (виявлення/стан плагінів, а також керування встановленням і ввімкненням/вимкненням). -- `commands.debug` (типово `false`) вмикає `/debug` (лише перевизначення під час виконання). -- `commands.restart` (типово `true`) вмикає `/restart`, а також дії інструментів перезапуску gateway. -- `commands.ownerAllowFrom` (необов’язково) задає явний список дозволу власника для поверхонь команд/інструментів лише для власника. Це окремо від `commands.allowFrom`. -- `commands.ownerDisplay` керує тим, як ідентифікатори власника відображаються в системному промпті: `raw` або `hash`. -- `commands.ownerDisplaySecret` необов’язково задає секрет HMAC, що використовується, коли `commands.ownerDisplay="hash"`. -- `commands.allowFrom` (необов’язково) задає список дозволу для кожного провайдера для авторизації команд. Якщо налаштовано, це - єдине джерело авторизації для команд і директив (списки дозволу/сполучення каналу та `commands.useAccessGroups` - ігноруються). Використовуйте `"*"` як глобальне типове значення; ключі для конкретних провайдерів його перевизначають. -- `commands.useAccessGroups` (типово `true`) застосовує списки дозволу/політики для команд, якщо `commands.allowFrom` не задано. +- `commands.plugins` (типово `false`) вмикає `/plugins` (пошук/статус plugin-ів, а також керування встановленням і ввімкненням/вимкненням). +- `commands.debug` (типово `false`) вмикає `/debug` (перевизначення лише під час виконання). +- `commands.restart` (типово `true`) вмикає `/restart`, а також дії інструмента перезапуску gateway. +- `commands.ownerAllowFrom` (необов’язково) задає явний owner allowlist для поверхонь команд/інструментів лише для власника. Це окремо від `commands.allowFrom`. +- `channels..commands.enforceOwnerForCommands` для окремого каналу (необов’язково, типово `false`) змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Коли `true`, відправник має або відповідати визначеному кандидату у власники (наприклад, запису в `commands.ownerAllowFrom` або нативним метаданим власника провайдера), або мати внутрішню область `operator.admin` на внутрішньому каналі повідомлень. Запис wildcard у `allowFrom` каналу або порожній/невизначений список кандидатів у власники **не** є достатнім — команди лише для власника на цьому каналі закриваються за замовчуванням. Залишайте це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними allowlist команд. +- `commands.ownerDisplay` керує тим, як ідентифікатори власника з’являються в системному prompt: `raw` або `hash`. +- `commands.ownerDisplaySecret` необов’язково задає HMAC secret, який використовується, коли `commands.ownerDisplay="hash"`. +- `commands.allowFrom` (необов’язково) задає allowlist для кожного провайдера для авторизації команд. Коли налаштовано, це + єдине джерело авторизації для команд і директив (`commands.useAccessGroups` та allowlist каналів/парингу ігноруються). Використовуйте `"*"` як глобальне типове значення; ключі окремих провайдерів мають пріоритет. +- `commands.useAccessGroups` (типово `true`) застосовує allowlist-и/політики до команд, коли `commands.allowFrom` не задано. ## Список команд Поточне джерело істини: -- вбудовані в ядро команди надходять із `src/auto-reply/commands-registry.shared.ts` -- згенеровані команди dock надходять із `src/auto-reply/commands-registry.data.ts` -- команди плагінів надходять із викликів `registerCommand()` у плагінах -- фактична доступність у вашому gateway усе одно залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених плагінів +- вбудовані в ядро команди походять із `src/auto-reply/commands-registry.shared.ts` +- згенеровані команди dock походять із `src/auto-reply/commands-registry.data.ts` +- команди plugin-ів походять із викликів `registerCommand()` plugin-ів +- фактична доступність на вашому gateway усе ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugin-ів ### Вбудовані команди ядра -Вбудовані команди, доступні зараз: +Доступні сьогодні вбудовані команди: -- `/new [model]` починає нову сесію; `/reset` — це псевдонім скидання. -- `/reset soft [message]` зберігає поточний транскрипт, скидає повторно використані ідентифікатори сесій бекенда CLI та повторно запускає завантаження startup/system-prompt на місці. +- `/new [model]` починає нову сесію; `/reset` — псевдонім скидання. +- `/reset soft [message]` зберігає поточний transcript, скидає повторно використані ідентифікатори сесій CLI backend і повторно запускає завантаження startup/system prompt на місці. - `/compact [instructions]` виконує Compaction контексту сесії. Див. [/concepts/compaction](/uk/concepts/compaction). - `/stop` перериває поточний запуск. -- `/session idle ` і `/session max-age ` керують строком дії прив’язки до потоку. -- `/think ` встановлює рівень мислення. Параметри надходять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а користувацькі рівні, як-от `xhigh`, `adaptive`, `max`, або лише двійковий `on`, доступні тільки там, де це підтримується. Псевдоніми: `/thinking`, `/t`. +- `/session idle ` і `/session max-age ` керують строком дії прив’язки до треду. +- `/think ` задає рівень мислення. Опції походять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а спеціальні рівні, як-от `xhigh`, `adaptive`, `max` або двійкове `on`, доступні лише там, де це підтримується. Псевдоніми: `/thinking`, `/t`. - `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`. -- `/trace on|off` перемикає вивід трасування плагіна для поточної сесії. -- `/fast [status|on|off]` показує або встановлює швидкий режим. -- `/reasoning [on|off|stream]` перемикає видимість міркувань. Псевдонім: `/reason`. -- `/elevated [on|off|ask|full]` перемикає підвищений режим. Псевдонім: `/elev`. -- `/exec host= security= ask= node=` показує або встановлює типові параметри exec. -- `/model [name|#|status]` показує або встановлює модель. -- `/models [provider] [page] [limit=|size=|all]` виводить список провайдерів або моделей для провайдера. -- `/queue ` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`), а також параметрами на кшталт `debounce:2s cap:25 drop:summarize`. -- `/help` показує короткий довідковий підсумок. +- `/trace on|off` перемикає вивід трасування plugin-ів для поточної сесії. +- `/fast [status|on|off]` показує або задає швидкий режим. +- `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`. +- `/elevated [on|off|ask|full]` перемикає режим elevated. Псевдонім: `/elev`. +- `/exec host= security= ask= node=` показує або задає типові значення exec. +- `/model [name|#|status]` показує або задає модель. +- `/models [provider] [page] [limit=|size=|all]` перелічує провайдерів або моделі для провайдера. +- `/queue ` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) плюс опції на кшталт `debounce:2s cap:25 drop:summarize`. +- `/help` показує коротке резюме довідки. - `/commands` показує згенерований каталог команд. - `/tools [compact|verbose]` показує, що поточний агент може використовувати прямо зараз. -- `/status` показує стан під час виконання, зокрема використання/квоту провайдера, якщо доступно. -- `/tasks` виводить список активних/нещодавніх фонових завдань для поточної сесії. +- `/status` показує статус runtime, зокрема використання/квоту провайдера, коли доступно. +- `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії. - `/context [list|detail|json]` пояснює, як збирається контекст. - `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`. -- `/whoami` показує ваш ідентифікатор відправника. Псевдонім: `/id`. +- `/whoami` показує ваш sender id. Псевдонім: `/id`. - `/skill [input]` запускає навичку за назвою. -- `/allowlist [list|add|remove] ...` керує записами списку дозволу. Лише текстова команда. -- `/approve ` розв’язує запити на схвалення exec. +- `/allowlist [list|add|remove] ...` керує записами allowlist. Лише текстова. +- `/approve ` вирішує запити на погодження exec. - `/btw ` ставить побічне запитання без зміни майбутнього контексту сесії. Див. [/tools/btw](/uk/tools/btw). -- `/subagents list|kill|log|info|send|steer|spawn` керує запусками субагентів для поточної сесії. -- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP та параметрами часу виконання. -- `/focus ` прив’язує поточний потік Discord або тему/розмову Telegram до цілі сесії. +- `/subagents list|kill|log|info|send|steer|spawn` керує запусками підагентів для поточної сесії. +- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP та параметрами runtime. +- `/focus ` прив’язує поточний тред Discord або тему/розмову Telegram до цілі сесії. - `/unfocus` видаляє поточну прив’язку. -- `/agents` виводить список агентів, прив’язаних до потоку, для поточної сесії. -- `/kill ` перериває одного або всіх запущених субагентів. -- `/steer ` надсилає керування запущеному субагенту. Псевдонім: `/tell`. +- `/agents` перелічує агентів, прив’язаних до треду, для поточної сесії. +- `/kill ` перериває одного або всі запущені підагенти. +- `/steer ` надсилає керування запущеному підагенту. Псевдонім: `/tell`. - `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потребує `commands.config: true`. -- `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, якою керує OpenClaw, у `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`. -- `/plugins list|inspect|show|get|install|enable|disable` переглядає або змінює стан плагінів. `/plugin` — псевдонім. Запис — лише для власника. Потребує `commands.plugins: true`. -- `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише під час виконання. Лише для власника. Потребує `commands.debug: true`. -- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальний підсумок вартості. +- `/mcp show|get|set|unset` читає або записує конфігурацію MCP server, якою керує OpenClaw, у `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`. +- `/plugins list|inspect|show|get|install|enable|disable` переглядає або змінює стан plugin-ів. `/plugin` — псевдонім. Запис — лише для власника. Потребує `commands.plugins: true`. +- `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише під час runtime. Лише для власника. Потребує `commands.debug: true`. +- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальне резюме вартості. - `/tts on|off|status|provider|limit|summary|audio|help` керує TTS. Див. [/tools/tts](/uk/tools/tts). -- `/restart` перезапускає OpenClaw, якщо ввімкнено. Типово: увімкнено; задайте `commands.restart: false`, щоб вимкнути. -- `/activation mention|always` встановлює режим активації групи. -- `/send on|off|inherit` встановлює політику надсилання. Лише для власника. -- `/bash ` виконує команду оболонки хоста. Лише текстова команда. Псевдонім: `! `. Потребує `commands.bash: true` та списків дозволу `tools.elevated`. -- `!poll [sessionId]` перевіряє фонове завдання bash. -- `!stop [sessionId]` зупиняє фонове завдання bash. +- `/restart` перезапускає OpenClaw, коли це ввімкнено. Типово: увімкнено; встановіть `commands.restart: false`, щоб вимкнути. +- `/activation mention|always` задає режим активації групи. +- `/send on|off|inherit` задає політику надсилання. Лише для власника. +- `/bash ` запускає shell-команду хоста. Лише текстова. Псевдонім: `! `. Потребує `commands.bash: true` плюс allowlist у `tools.elevated`. +- `!poll [sessionId]` перевіряє фонове bash-завдання. +- `!stop [sessionId]` зупиняє фонове bash-завдання. -### Згенеровані команди dock +### Згенеровані dock-команди -Команди dock генеруються з плагінів каналів із підтримкою нативних команд. Поточний вбудований набір: +Dock-команди генеруються з plugin-ів каналів із підтримкою нативних команд. Поточний вбудований набір: - `/dock-discord` (псевдонім: `/dock_discord`) - `/dock-mattermost` (псевдонім: `/dock_mattermost`) - `/dock-slack` (псевдонім: `/dock_slack`) - `/dock-telegram` (псевдонім: `/dock_telegram`) -### Команди вбудованих плагінів +### Команди вбудованих plugin-ів -Вбудовані плагіни можуть додавати більше слеш-команд. Поточні вбудовані команди в цьому репозиторії: +Вбудовані plugin-и можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії: - `/dreaming [on|off|status|help]` перемикає Dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming). -- `/pair [qr|status|pending|approve|cleanup|notify]` керує процесом сполучення/налаштування пристроїв. Див. [Pairing](/uk/channels/pairing). -- `/phone status|arm [duration]|disarm` тимчасово вмикає високоризикові команди вузла телефона. +- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком парингу/налаштування пристрою. Див. [Pairing](/uk/channels/pairing). +- `/phone status|arm [duration]|disarm` тимчасово вмикає високоризикові команди phone node. - `/voice status|list [limit]|set ` керує конфігурацією голосу Talk. У Discord нативна назва команди — `/talkvoice`. -- `/card ...` надсилає шаблони LINE rich card. Див. [LINE](/uk/channels/line). +- `/card ...` надсилає готові пресети LINE rich card. Див. [LINE](/uk/channels/line). - `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє та керує вбудованим harness app-server Codex. Див. [Codex Harness](/uk/plugins/codex-harness). - Команди лише для QQBot: - `/bot-ping` @@ -169,73 +169,73 @@ x-i18n: - `/bot-upgrade` - `/bot-logs` -### Динамічні команди навичок +### Динамічні команди Skills -Навички, які може викликати користувач, також доступні як слеш-команди: +Навички, які може викликати користувач, також доступні як slash-команди: -- `/skill [input]` завжди працює як загальна точка входу. -- навички також можуть з’являтися як прямі команди, наприклад `/prose`, коли їх реєструє навичка/плагін. -- реєстрація нативних команд навичок керується через `commands.nativeSkills` і `channels..commands.nativeSkills`. +- `/skill [input]` завжди працює як універсальна точка входу. +- навички також можуть з’являтися як прямі команди, наприклад `/prose`, коли навичка/plugin їх реєструє. +- реєстрація нативних команд Skills керується через `commands.nativeSkills` і `channels..commands.nativeSkills`. Примітки: -- Команди приймають необов’язковий символ `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). +- Команди приймають необов’язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). - `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст трактується як тіло повідомлення. -- Для повного розподілу використання провайдера використовуйте `openclaw status --usage`. -- `/allowlist add|remove` вимагає `commands.config=true` і враховує `configWrites` каналу. -- У каналах із кількома обліковими записами `/allowlist --account `, націлений на конфігурацію, та `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. -- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальний підсумок вартості з журналів сесій OpenClaw. -- `/restart` увімкнено типово; задайте `commands.restart: false`, щоб вимкнути його. -- `/plugins install ` приймає ті самі специфікації плагінів, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет або `clawhub:`. -- `/plugins enable|disable` оновлює конфігурацію плагіна і може запропонувати перезапуск. +- Для повної деталізації використання провайдера використовуйте `openclaw status --usage`. +- `/allowlist add|remove` потребує `commands.config=true` і враховує `configWrites` каналу. +- У каналах із кількома акаунтами `/allowlist --account `, націлений на конфігурацію, і `/config set channels..accounts....` також враховують `configWrites` цільового акаунта. +- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальне резюме вартості з журналів сесій OpenClaw. +- `/restart` увімкнено типово; встановіть `commands.restart: false`, щоб вимкнути його. +- `/plugins install ` приймає ті самі специфікації plugin-ів, що й `openclaw plugins install`: локальний шлях/архів, npm package або `clawhub:`. +- `/plugins enable|disable` оновлює конфігурацію plugin-ів і може запропонувати перезапуск. - Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (потребує `channels.discord.voice` і нативних команд; недоступна як текстова). -- Команди прив’язки потоку Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) вимагають, щоб ефективні прив’язки потоку були ввімкнені (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). -- Довідник команд ACP і поведінка під час виконання: [ACP Agents](/uk/tools/acp-agents). +- Команди прив’язки до тредів Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив’язок до тредів (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). +- Довідник команд ACP і поведінка runtime: [ACP Agents](/uk/tools/acp-agents). - `/verbose` призначено для налагодження та додаткової видимості; у звичайному використанні тримайте його **вимкненим**. -- `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать плагіну, і не вмикає звичайний докладний вивід інструментів. -- `/fast on|off` зберігає перевизначення сесії. Щоб очистити його й повернутися до типових значень конфігурації, використовуйте параметр `inherit` в інтерфейсі Sessions. -- `/fast` залежить від провайдера: OpenAI/OpenAI Codex відображають його в `service_tier=priority` на нативних endpoints Responses, тоді як прямі публічні запити Anthropic, зокрема трафік з OAuth-автентифікацією, надісланий до `api.anthropic.com`, відображають його в `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). -- Підсумки збоїв інструментів усе одно показуються, коли це доречно, але докладний текст збоїв включається лише тоді, коли `/verbose` має значення `on` або `full`. -- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішні міркування, вивід інструментів або діагностику плагінів, яку ви не планували показувати. Краще залишати їх вимкненими, особливо в групових чатах. +- `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать plugin-ам, і не вмикає звичайний докладний вивід інструментів. +- `/fast on|off` зберігає перевизначення сесії. Щоб очистити його й повернутися до типових значень конфігурації, використовуйте опцію `inherit` в інтерфейсі Sessions. +- `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних endpoint Responses, тоді як прямі публічні запити Anthropic, зокрема трафік з OAuth-автентифікацією, надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). +- Резюме збоїв інструментів усе ще показуються, коли це доречно, але детальний текст помилки включається лише коли `/verbose` має значення `on` або `full`. +- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику plugin-ів, які ви не планували показувати. Краще залишати їх вимкненими, особливо в групових чатах. - `/model` негайно зберігає нову модель сесії. -- Якщо агент неактивний, наступний запуск одразу її використає. -- Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускає з новою моделлю лише в чистій точці повторної спроби. -- Якщо активність інструментів або вивід відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача. -- **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволу обробляються негайно (в обхід черги й моделі). -- **Фільтрація згадок у групі:** повідомлення лише з командами від відправників зі списку дозволу обходять вимоги щодо згадок. -- **Вбудовані скорочення (лише для відправників зі списку дозволу):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і видаляються до того, як модель побачить решту тексту. - - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту далі проходить звичайним шляхом. +- Якщо агент неактивний, наступний запуск використає її одразу. +- Якщо запуск уже активний, OpenClaw позначає перемикання на льоту як відкладене й перезапускається в нову модель лише в чистій точці повторної спроби. +- Якщо активність інструментів або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої нагоди повторної спроби або до наступного ходу користувача. +- **Швидкий шлях:** повідомлення лише з командами від allowlisted відправників обробляються негайно (обхід черги + моделі). +- **Керування згадками в групі:** повідомлення лише з командами від allowlisted відправників обходять вимоги щодо згадок. +- **Вбудовані скорочення (лише для allowlisted відправників):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і видаляються до того, як модель побачить решту тексту. + - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує проходити звичайним шляхом. - Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - Неавторизовані повідомлення лише з командами тихо ігноруються, а вбудовані токени `/...` трактуються як звичайний текст. -- **Команди Skills:** навички `user-invocable` доступні як слеш-команди. Назви санітизуються до `a-z0-9_` (макс. 32 символи); у разі колізій додаються числові суфікси (наприклад, `_2`). - - `/skill [input]` запускає навичку за назвою (корисно, коли обмеження нативних команд не дозволяють окремі команди для кожної навички). - - Типово команди навичок пересилаються моделі як звичайний запит. - - Навички можуть необов’язково оголошувати `command-dispatch: tool`, щоб спрямовувати команду безпосередньо до інструмента (детерміновано, без моделі). - - Приклад: `/prose` (плагін OpenProse) — див. [OpenProse](/uk/prose). -- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. +- **Команди Skills:** навички `user-invocable` доступні як slash-команди. Назви очищуються до `a-z0-9_` (максимум 32 символи); у разі конфліктів додаються числові суфікси (наприклад, `_2`). + - `/skill [input]` запускає навичку за назвою (корисно, коли обмеження нативних команд не дозволяють створити окремі команди для кожної навички). + - Типово команди навичок пересилаються до моделі як звичайний запит. + - Навички можуть необов’язково оголошувати `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі). + - Приклад: `/prose` (plugin OpenProse) — див. [OpenProse](/uk/prose). +- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних опцій (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує вибір і ви пропускаєте аргумент. ## `/tools` -`/tools` відповідає на запитання про час виконання, а не про конфігурацію: **що цей агент може використовувати прямо зараз у +`/tools` відповідає на запитання про runtime, а не про конфігурацію: **що цей агент може використовувати прямо зараз у цій розмові**. -- Типове `/tools` є компактним і оптимізованим для швидкого перегляду. +- Типовий `/tools` компактний і оптимізований для швидкого перегляду. - `/tools verbose` додає короткі описи. -- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму як `compact|verbose`. -- Результати прив’язані до сесії, тому зміна агента, каналу, потоку, авторизації відправника або моделі може +- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму `compact|verbose`. +- Результати обмежені сесією, тому зміна агента, каналу, треду, авторизації відправника або моделі може змінити вивід. -- `/tools` включає інструменти, які реально доступні під час виконання, зокрема інструменти ядра, підключені - інструменти плагінів і інструменти, що належать каналу. +- `/tools` включає інструменти, які реально доступні під час runtime, зокрема інструменти ядра, підключені + інструменти plugin-ів і інструменти, що належать каналу. -Для редагування профілю та перевизначень використовуйте панель Tools у Control UI або поверхні конфігурації/каталогу, +Для редагування профілів і перевизначень використовуйте панель Tools у Control UI або поверхні конфігурації/каталогу, а не сприймайте `/tools` як статичний каталог. ## Поверхні використання (що де показується) -- **Використання/квота провайдера** (приклад: «Claude 80% left») показується в `/status` для провайдера поточної моделі, коли відстеження використання ввімкнено. OpenClaw нормалізує вікна провайдера до `% left`; для MiniMax поля відсотка лише із залишком інвертуються перед показом, а відповіді `model_remains` надають перевагу запису chat-model разом із міткою плану з тегом моделі. -- **Рядки token/cache** у `/status` можуть повертатися до останнього запису використання транскрипту, коли живий знімок сесії бідний на дані. Наявні ненульові живі значення все одно мають пріоритет, а fallback до транскрипту також може відновити мітку активної моделі часу виконання разом із більшим загальним значенням, орієнтованим на промпт, коли збережені підсумки відсутні або менші. -- **Токени/вартість для кожної відповіді** керуються через `/usage off|tokens|full` (додається до звичайних відповідей). -- `/model status` стосується **моделей/автентифікації/endpoints**, а не використання. +- **Використання/квота провайдера** (наприклад, «Claude 80% left») показується в `/status` для провайдера поточної моделі, коли відстеження використання увімкнено. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax відсоткові поля лише із залишком інвертуються перед показом, а відповіді `model_remains` віддають перевагу запису моделі чату плюс мітці плану з позначенням моделі. +- Рядки **token/cache** у `/status` можуть повертатися до останнього запису використання в transcript, якщо знімок живої сесії містить мало даних. Наявні ненульові живі значення все одно мають пріоритет, а fallback до transcript також може відновити мітку активної runtime-моделі та більший загальний обсяг, орієнтований на prompt, коли збережених сумарних значень немає або вони менші. +- **Tokens/cost для кожної відповіді** керуються через `/usage off|tokens|full` (додається до звичайних відповідей). +- `/model status` стосується **моделей/auth/endpoints**, а не використання. ## Вибір моделі (`/model`) @@ -255,13 +255,13 @@ x-i18n: Примітки: - `/model` і `/model list` показують компактний нумерований вибір (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний вибір зі спадними списками провайдера та моделі, а також кроком Submit. -- `/model <#>` вибирає зі списку цього вибору (і за можливості надає перевагу поточному провайдеру). -- `/model status` показує докладне подання, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), якщо доступно. +- У Discord `/model` і `/models` відкривають інтерактивний вибір зі списками провайдера й моделі та кроком Submit. +- `/model <#>` вибирає зі списку (і за можливості надає перевагу поточному провайдеру). +- `/model status` показує докладний вигляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли доступно. -## Перевизначення для налагодження +## Налагоджувальні перевизначення -`/debug` дає змогу встановлювати **перевизначення конфігурації лише під час виконання** (у пам’яті, не на диску). Лише для власника. Вимкнено типово; увімкніть через `commands.debug: true`. +`/debug` дає змогу задавати перевизначення конфігурації **лише під час runtime** (у пам’яті, не на диску). Лише для власника. Типово вимкнено; увімкніть через `commands.debug: true`. Приклади: @@ -278,9 +278,9 @@ x-i18n: - Перевизначення застосовуються негайно до нових читань конфігурації, але **не** записуються в `openclaw.json`. - Використовуйте `/debug reset`, щоб очистити всі перевизначення та повернутися до конфігурації на диску. -## Вивід трасування плагіна +## Вивід trace plugin-ів -`/trace` дає змогу перемикати **рядки трасування/налагодження плагіна в межах сесії** без увімкнення повного докладного режиму. +`/trace` дає змогу перемикати **рядки trace/debug plugin-ів на рівні сесії** без увімкнення повного докладного режиму. Приклади: @@ -292,16 +292,16 @@ x-i18n: Примітки: -- `/trace` без аргументу показує поточний стан трасування сесії. -- `/trace on` вмикає рядки трасування плагіна для поточної сесії. -- `/trace off` знову їх вимикає. -- Рядки трасування плагіна можуть з’являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді помічника. -- `/trace` не замінює `/debug`; `/debug` і далі керує перевизначеннями конфігурації лише під час виконання. -- `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/статусу все ще належить `/verbose`. +- `/trace` без аргументу показує поточний стан trace для сесії. +- `/trace on` вмикає рядки trace plugin-ів для поточної сесії. +- `/trace off` знову вимикає їх. +- Рядки trace plugin-ів можуть з’являтися в `/status` і як додаткове діагностичне повідомлення після звичайної відповіді асистента. +- `/trace` не замінює `/debug`; `/debug` і далі керує перевизначеннями конфігурації лише під час runtime. +- `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/статусу й далі належить `/verbose`. ## Оновлення конфігурації -`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Вимкнено типово; увімкніть через `commands.config: true`. +`/config` записує дані у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Типово вимкнено; увімкніть через `commands.config: true`. Приклади: @@ -315,12 +315,12 @@ x-i18n: Примітки: -- Конфігурація перевіряється перед записом; недійсні зміни відхиляються. -- Оновлення `/config` зберігаються після перезапусків. +- Перед записом конфігурація проходить валідацію; недійсні зміни відхиляються. +- Оновлення `/config` зберігаються після перезапуску. ## Оновлення MCP -`/mcp` записує визначення MCP-серверів, якими керує OpenClaw, у `mcp.servers`. Лише для власника. Вимкнено типово; увімкніть через `commands.mcp: true`. +`/mcp` записує означення MCP server, якими керує OpenClaw, у `mcp.servers`. Лише для власника. Типово вимкнено; увімкніть через `commands.mcp: true`. Приклади: @@ -333,12 +333,12 @@ x-i18n: Примітки: -- `/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. -- Адаптери часу виконання визначають, які транспорти реально можна виконати. +- `/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, якими володіє Pi. +- Адаптери runtime вирішують, які транспорти реально можна виконати. -## Оновлення плагінів +## Оновлення plugin-ів -`/plugins` дає змогу операторам переглядати виявлені плагіни й перемикати їхнє ввімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено типово; увімкніть через `commands.plugins: true`. +`/plugins` дає операторам змогу переглядати виявлені plugin-и й перемикати стан увімкнення в конфігурації. Для сценаріїв лише читання можна використовувати `/plugin` як псевдонім. Типово вимкнено; увімкніть через `commands.plugins: true`. Приклади: @@ -352,20 +352,20 @@ x-i18n: Примітки: -- `/plugins list` і `/plugins show` використовують реальне виявлення плагінів у поточному робочому просторі разом із конфігурацією на диску. -- `/plugins enable|disable` оновлює лише конфігурацію плагінів; він не встановлює і не видаляє плагіни. +- `/plugins list` і `/plugins show` використовують реальне виявлення plugin-ів у поточному workspace разом із конфігурацією на диску. +- `/plugins enable|disable` оновлює лише конфігурацію plugin-ів; це не встановлює і не видаляє plugin-и. - Після змін `enable/disable` перезапустіть gateway, щоб застосувати їх. ## Примітки щодо поверхонь -- **Текстові команди** працюють у звичайній сесії чату (DM ділять `main`, групи мають власну сесію). +- **Текстові команди** виконуються у звичайній сесії чату (DM ділять `main`, групи мають власну сесію). - **Нативні команди** використовують ізольовані сесії: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`) - Telegram: `telegram:slash:` (націлюється на сесію чату через `CommandTargetSessionKey`) -- **`/stop`** націлюється на активну сесію чату, щоб мати змогу перервати поточний запуск. -- **Slack:** `channels.slack.slashCommand` усе ще підтримується для однієї команди у стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash command у Slack для кожної вбудованої команди (з тими самими назвами, що й у `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. - - Виняток для нативних команд Slack: зареєструйте `/agentstatus` (а не `/status`), оскільки Slack резервує `/status`. Текстова `/status` у повідомленнях Slack усе одно працює. +- **`/stop`** націлюється на активну сесію чату, щоб перервати поточний запуск. +- **Slack:** `channels.slack.slashCommand` усе ще підтримується для єдиної команди стилю `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash-команду Slack для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. + - Виняток для нативних команд Slack: зареєструйте `/agentstatus` (не `/status`), тому що Slack резервує `/status`. Текстова `/status` у повідомленнях Slack усе одно працює. ## Побічні запитання BTW @@ -374,10 +374,10 @@ x-i18n: На відміну від звичайного чату: - воно використовує поточну сесію як фоновий контекст, -- запускається як окремий **одноразовий** виклик **без інструментів**, +- виконується як окремий **одноразовий** виклик без інструментів, - не змінює майбутній контекст сесії, -- не записується в історію транскрипту, -- доставляється як живий побічний результат, а не як звичайне повідомлення помічника. +- не записується в історію transcript, +- доставляється як живий побічний результат, а не як звичайне повідомлення асистента. Це робить `/btw` корисним, коли вам потрібне тимчасове уточнення, поки основне завдання триває. @@ -388,5 +388,5 @@ x-i18n: /btw what are we doing right now? ``` -Див. [BTW Side Questions](/uk/tools/btw), щоб дізнатися повну поведінку та подробиці -UX клієнта. +Див. [BTW Side Questions](/uk/tools/btw) для повного опису поведінки та деталей UX +клієнта.