diff --git a/docs/uk/automation/cron-jobs.md b/docs/uk/automation/cron-jobs.md index 50e50178c..37e4cfa42 100644 --- a/docs/uk/automation/cron-jobs.md +++ b/docs/uk/automation/cron-jobs.md @@ -1,15 +1,15 @@ --- read_when: - - Налаштування фонових завдань або пробуджень + - Планування фонових завдань або пробуджень - Підключення зовнішніх тригерів (вебхуків, Gmail) до OpenClaw - Вибір між heartbeat і cron для запланованих завдань summary: Заплановані завдання, вебхуки та тригери Gmail PubSub для планувальника Gateway title: Заплановані завдання x-i18n: - generated_at: "2026-04-05T17:57:54Z" + generated_at: "2026-04-10T20:41:25Z" model: gpt-5.4 provider: openai - source_hash: 43b906914461aba9af327e7e8c22aa856f65802ec2da37ed0c4f872d229cfde6 + source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665 source_path: automation/cron-jobs.md workflow: 15 --- @@ -39,105 +39,107 @@ openclaw cron runs --id ## Як працює cron -- Cron працює **всередині процесу Gateway** (не всередині моделі). +- Cron працює **всередині процесу Gateway** (а не всередині моделі). - Завдання зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів. -- Усі виконання cron створюють записи [фонових завдань](/automation/tasks). -- Одноразові завдання (`--at`) за замовчуванням автоматично видаляються після успішного виконання. -- Ізольовані запуски cron у межах best-effort закривають відстежувані вкладки/процеси браузера для своєї сесії `cron:` після завершення запуску, щоб відокремлена автоматизація браузера не залишала осиротілі процеси. +- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks). +- Одноразові завдання (`--at`) після успішного виконання автоматично видаляються за замовчуванням. +- Ізольовані запуски cron після завершення намагаються в найкращий спосіб закрити відстежувані вкладки/процеси браузера для своєї сесії `cron:`, щоб відокремлена автоматизація браузера не залишала після себе осиротілі процеси. - Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо - перший результат — це лише проміжне оновлення стану (`on it`, `pulling everything + перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск subagent більше не - відповідає за фінальну відповідь, OpenClaw повторно надсилає запит один раз для отримання фактичного + відповідає за фінальну відповідь, OpenClaw ще раз надсилає запит на отримання фактичного результату перед доставкою. -Узгодження завдань для cron належить до runtime: активне завдання cron залишається активним, доки -runtime cron усе ще відстежує це завдання як запущене, навіть якщо старий рядок дочірньої сесії все ще існує. -Щойно runtime перестає володіти завданням і спливає 5-хвилинне вікно пільги, обслуговування може + + +Узгодження завдань для cron належить до runtime: активне завдання cron залишається активним, поки +runtime cron все ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. +Щойно runtime перестає володіти завданням і спливає 5-хвилинне вікно очікування, обслуговування може позначити завдання як `lost`. ## Типи розкладу -| Тип | Прапорець CLI | Опис | +| Вид | Прапорець CLI | Опис | | ------- | ------------- | ------------------------------------------------------- | -| `at` | `--at` | Одноразова мітка часу (ISO 8601 або відносна, наприклад `20m`) | +| `at` | `--at` | Одноразова мітка часу (ISO 8601 або відносно, наприклад `20m`) | | `every` | `--every` | Фіксований інтервал | -| `cron` | `--cron` | Cron-вираз із 5 або 6 полів із необов'язковим `--tz` | +| `cron` | `--cron` | 5-польовий або 6-польовий cron-вираз з необов’язковим `--tz` | -Мітки часу без часової зони трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним часом. +Мітки часу без часового поясу обробляються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом. -Повторювані вирази на початок години автоматично зсуваються до 5 хвилин, щоб зменшити пікове навантаження. Використовуйте `--exact`, щоб примусово ввімкнути точний час, або `--stagger 30s` для явного вікна. +Повторювані вирази на початок години автоматично розподіляються зі зсувом до 5 хвилин, щоб зменшити пікове навантаження. Використовуйте `--exact`, щоб примусово ввімкнути точний час, або `--stagger 30s` для явного вікна. ## Стилі виконання -| Стиль | Значення `--session` | Запускається в | Найкраще підходить для | -| --------------- | -------------------- | ------------------------- | ------------------------------- | -| Основна сесія | `main` | Наступний цикл heartbeat | Нагадувань, системних подій | -| Ізольований | `isolated` | Виділена `cron:` | Звітів, фонових завдань | -| Поточна сесія | `current` | Прив'язується під час створення | Повторюваної роботи з урахуванням контексту | -| Користувацька сесія | `session:custom-id` | Постійна іменована сесія | Процесів, що спираються на історію | +| Стиль | Значення `--session` | Виконується в | Найкраще підходить для | +| -------------- | -------------------- | ------------------------ | -------------------------------- | +| Основна сесія | `main` | Наступний heartbeat-цикл | Нагадувань, системних подій | +| Ізольований | `isolated` | Виділений `cron:` | Звітів, фонових задач | +| Поточна сесія | `current` | Прив’язується під час створення | Повторюваної роботи з урахуванням контексту | +| Користувацька сесія | `session:custom-id` | Постійна іменована сесія | Робочих процесів, що спираються на історію | -Завдання **основної сесії** ставлять у чергу системну подію й за потреби пробуджують heartbeat (`--wake now` або `--wake next-heartbeat`). **Ізольовані** завдання запускають окремий цикл агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу будувати процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. +Завдання **основної сесії** ставлять системну подію в чергу та за потреби пробуджують heartbeat (`--wake now` або `--wake next-heartbeat`). **Ізольовані** завдання запускають окремий цикл агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу створювати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки. -Для ізольованих завдань teardown runtime тепер також включає best-effort очищення браузера для цієї сесії cron. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет. +Для ізольованих завдань teardown runtime тепер включає найкращу спробу очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет. -Коли ізольовані запуски cron оркеструють subagent, доставка також надає перевагу -фінальному результату дочірнього процесу над застарілим проміжним текстом батьківського. Якщо дочірні процеси все ще -виконуються, OpenClaw пригнічує це часткове оновлення батьківського процесу замість того, щоб оголошувати його. +Коли ізольовані запуски cron оркеструють subagents, доставка також надає перевагу +фінальному результату нащадка над застарілим проміжним текстом батьківського запуску. Якщо нащадки все ще +виконуються, OpenClaw пригнічує це часткове оновлення від батьківського запуску замість того, щоб його оголошувати. ### Параметри payload для ізольованих завдань -- `--message`: текст запиту (обов'язковий для isolated) +- `--message`: текст запиту (обов’язково для isolated) - `--model` / `--thinking`: перевизначення моделі та рівня thinking -- `--light-context`: пропустити ін'єкцію файлів bootstrap робочого простору +- `--light-context`: пропустити ін’єкцію файлів bootstrap робочого простору - `--tools exec,read`: обмежити, які інструменти може використовувати завдання `--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель -не дозволена, cron записує попередження в журнал і повертається до вибору моделі -агента/типової моделі для цього завдання. Налаштовані ланцюжки fallback усе ще застосовуються, але просте +не дозволена, cron записує попередження в журнал і повертається до вибору моделі агента/за замовчуванням для цього завдання. +Налаштовані ланцюжки fallback усе ще застосовуються, але звичайне перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль для повторної спроби. -Пріоритет вибору моделі для ізольованих завдань такий: +Пріоритет вибору моделі для ізольованих завдань: -1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене) +1. Перевизначення моделі Gmail hook (коли запуск походить із Gmail і це перевизначення дозволене) 2. `model` у payload конкретного завдання -3. Збережене перевизначення моделі сесії cron -4. Вибір моделі агента/типової моделі +3. Збережене перевизначення моделі cron-сесії +4. Вибір моделі агента/за замовчуванням -Швидкий режим також наслідує вибраний поточний варіант. Якщо в конфігурації вибраної моделі -є `params.fastMode`, ізольований cron використовує його за замовчуванням. Збережене перевизначення -сесії `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках. +Швидкий режим також дотримується визначеного активного вибору. Якщо конфігурація вибраної моделі +має `params.fastMode`, ізольований cron використовує це за замовчуванням. Збережене перевизначення +`fastMode` у сесії все одно має пріоритет над конфігурацією в будь-якому напрямку. -Якщо ізольований запуск потрапляє на передачу керування під час живого перемикання моделі, cron повторює спробу з -перемкнутим provider/model і зберігає цей поточний вибір перед повторною спробою. Коли -перемикання також несе новий профіль auth, cron зберігає і це перевизначення -профілю auth. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб -перемикання cron перериває виконання замість нескінченного циклу. +Якщо ізольований запуск стикається з передачею на іншу модель під час live-перемикання, cron повторює спробу з +перемкненим provider/model і зберігає цей live-вибір перед повторною спробою. Якщо +перемикання також несе новий профіль автентифікації, cron теж зберігає це перевизначення профілю автентифікації. +Кількість повторних спроб обмежена: після початкової спроби та ще 2 повторних спроб через перемикання +cron перериває виконання замість того, щоб зациклитися назавжди. ## Доставка та вивід -| Режим | Що відбувається | -| -------- | --------------------------------------------------------- | -| `announce` | Доставити підсумок у цільовий канал (типово для isolated) | -| `webhook` | Надіслати payload події завершення через POST на URL | -| `none` | Лише внутрішньо, без доставки | +| Режим | Що відбувається | +| --------- | -------------------------------------------------------- | +| `announce` | Доставити підсумок у цільовий канал (за замовчуванням для isolated) | +| `webhook` | Надіслати payload події про завершення методом POST на URL | +| `none` | Лише внутрішнє використання, без доставки | -Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:`, `user:`). +Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Цілі Slack/Discord/Mattermost повинні використовувати явні префікси (`channel:`, `user:`). -Для ізольованих завдань, якими володіє cron, runner керує фінальним шляхом доставки. Агент -отримує запит повернути текстовий підсумок, а потім цей підсумок надсилається через -`announce`, `webhook` або зберігається внутрішньо для `none`. `--no-deliver` -не повертає доставку агенту; воно залишає запуск внутрішнім. +Для ізольованих завдань, що належать cron, runner володіє фінальним шляхом доставки. Агента +просять повернути текстовий підсумок у звичайному форматі, а потім цей підсумок надсилається через +`announce`, `webhook` або залишається внутрішнім для `none`. `--no-deliver` не +повертає доставку назад агенту; він залишає запуск внутрішнім. -Якщо оригінальне завдання явно вказує написати якомусь зовнішньому отримувачу, агент -має зазначити виводом, кому/куди має бути надіслано це повідомлення, замість -спроби відправити його безпосередньо. +Якщо початкове завдання явно вказує на необхідність надіслати повідомлення якомусь зовнішньому одержувачу, +агент повинен зазначити у своєму виводі, кому/куди має піти це повідомлення, замість того щоб +намагатися надіслати його безпосередньо. -Сповіщення про збої йдуть окремим маршрутом призначення: +Сповіщення про збої використовують окремий шлях призначення: -- `cron.failureDestination` задає глобальне типове призначення для сповіщень про збої. -- `job.delivery.failureDestination` перевизначає його для конкретного завдання. -- Якщо не задано жодного з них, а завдання вже доставляє через `announce`, сповіщення про збої тепер за замовчуванням повертаються до цієї основної цілі announce. +- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про збої. +- `job.delivery.failureDestination` перевизначає його для окремого завдання. +- Якщо не задано жодного з них, а завдання вже доставляє результат через `announce`, сповіщення про збої тепер за замовчуванням надсилаються до тієї самої основної цілі announce. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`. ## Приклади CLI @@ -183,7 +185,7 @@ openclaw cron add \ ## Вебхуки -Gateway може відкривати endpoint-и HTTP вебхуків для зовнішніх тригерів. Увімкніть у конфігурації: +Gateway може відкривати HTTP endpoint вебхуків для зовнішніх тригерів. Увімкніть у конфігурації: ```json5 { @@ -202,7 +204,7 @@ Gateway може відкривати endpoint-и HTTP вебхуків для - `Authorization: Bearer ` (рекомендовано) - `x-openclaw-token: ` -Токени в query string відхиляються. +Токени в рядку запиту відхиляються. ### POST /hooks/wake @@ -215,8 +217,8 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ -d '{"text":"New email received","mode":"now"}' ``` -- `text` (обов'язково): опис події -- `mode` (необов'язково): `now` (типово) або `next-heartbeat` +- `text` (обов’язково): опис події +- `mode` (необов’язково): `now` (за замовчуванням) або `next-heartbeat` ### POST /hooks/agent @@ -229,27 +231,27 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}' ``` -Поля: `message` (обов'язково), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`. +Поля: `message` (обов’язково), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`. -### Зіставлені hook-и (POST /hooks/\) +### Зіставлені hooks (POST /hooks/\) -Користувацькі назви hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільний payload на дії `wake` або `agent` за допомогою шаблонів чи трансформацій коду. +Користувацькі назви hook визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload у дії `wake` або `agent` за допомогою шаблонів чи кодових перетворень. ### Безпека -- Тримайте endpoint-и hook-ів за loopback, tailnet або довіреним reverse proxy. -- Використовуйте окремий токен hook; не використовуйте повторно токени auth gateway. +- Тримайте endpoint вебхуків за loopback, tailnet або довіреним reverse proxy. +- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway. - Тримайте `hooks.path` на окремому підшляху; `/` відхиляється. -- Установіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. -- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, що обираються викликачем. -- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесії. -- Payload-и hook-ів за замовчуванням обгортаються межами безпеки. +- Налаштуйте `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`. +- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем. +- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також налаштуйте `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесії. +- Payload hooks за замовчуванням обгортаються захисними межами. ## Інтеграція Gmail PubSub -Підключіть тригери вхідної Gmail до OpenClaw через Google PubSub. +Підключіть тригери вхідних Gmail до OpenClaw через Google PubSub. -**Передумови**: `gcloud` CLI, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint. +**Передумови**: CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint. ### Налаштування через майстер (рекомендовано) @@ -257,15 +259,15 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Це записує конфігурацію `hooks.gmail`, вмикає пресет Gmail і використовує Tailscale Funnel для push endpoint. +Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для endpoint push. ### Автозапуск Gateway -Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час запуску стартує `gog gmail watch serve` і автоматично поновлює watch. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися від цього. +Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час завантаження запускає `gog gmail watch serve` і автоматично поновлює watch. Встановіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися від цього. ### Ручне одноразове налаштування -1. Виберіть проєкт GCP, який володіє OAuth client, що використовується `gog`: +1. Виберіть проєкт GCP, якому належить OAuth client, що використовується `gog`: ```bash gcloud auth login @@ -330,14 +332,16 @@ openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --mes openclaw cron edit --clear-agent ``` -Примітка про перевизначення моделі: +Примітка щодо перевизначення моделі: - `openclaw cron add|edit --model ...` змінює вибрану модель завдання. -- Якщо модель дозволена, саме цей provider/model потрапляє до ізольованого запуску агента. -- Якщо ні, cron попереджає та повертається до вибору моделі агента/типової моделі завдання. -- Налаштовані ланцюжки fallback усе ще застосовуються, але просте перевизначення `--model` без - явного списку fallback для конкретного завдання більше не переходить до основної моделі агента - як до тихої додаткової цілі повторної спроби. +- Якщо модель дозволена, саме цей provider/model передається ізольованому + запуску агента. +- Якщо вона не дозволена, cron видає попередження і повертається до вибору + моделі агента/за замовчуванням для завдання. +- Налаштовані ланцюжки fallback усе ще застосовуються, але звичайне перевизначення `--model` + без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента + як до мовчазної додаткової цілі для повторної спроби. ## Конфігурація @@ -359,13 +363,13 @@ openclaw cron edit --clear-agent } ``` -Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. +Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`. -**Повторна спроба для одноразових завдань**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційною затримкою. Постійні помилки негайно вимикаються. +**Повторні спроби для одноразових завдань**: тимчасові помилки (обмеження швидкості, перевантаження, мережеві помилки, помилки сервера) повторюються до 3 разів з експоненційною затримкою. Постійні помилки одразу вимикають завдання. -**Повторна спроба для повторюваних завдань**: експоненційна затримка (від 30 с до 60 хв) між спробами. Затримка скидається після наступного успішного запуску. +**Повторні спроби для повторюваних завдань**: експоненційна затримка (від 30 с до 60 хв) між повторними спробами. Після наступного успішного запуску затримка скидається. -**Обслуговування**: `cron.sessionRetention` (типово `24h`) видаляє записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналу запусків. +**Обслуговування**: `cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналу запусків. ## Усунення несправностей @@ -385,31 +389,31 @@ openclaw doctor ### Cron не спрацьовує - Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`. -- Підтвердьте, що Gateway працює безперервно. -- Для розкладів `cron` перевірте часовий пояс (`--tz`) у порівнянні з часовим поясом хоста. +- Переконайтеся, що Gateway працює безперервно. +- Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста. - `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run --due`, але час виконання завдання ще не настав. ### Cron спрацював, але доставки немає - Режим доставки `none` означає, що зовнішнє повідомлення не очікується. -- Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено. -- Помилки auth каналу (`unauthorized`, `Forbidden`) означають, що доставку заблоковано обліковими даними. +- Відсутня або недійсна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено. +- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку було заблоковано обліковими даними. - Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), - OpenClaw пригнічує пряме вихідне надсилання, а також запасний + OpenClaw пригнічує пряме вихідне надсилання, а також резервний шлях доставки підсумку через чергу, тому назад у чат нічого не публікується. -- Для ізольованих завдань, якими володіє cron, не очікуйте, що агент використовуватиме інструмент message - як запасний варіант. Runner керує фінальною доставкою; `--no-deliver` залишає її - внутрішньою, а не дозволяє пряме надсилання. +- Для ізольованих завдань, що належать cron, не очікуйте, що агент використовуватиме інструмент message + як резервний варіант. Runner володіє фінальною доставкою; `--no-deliver` зберігає її + внутрішньою замість дозволу на пряме надсилання. ### Особливості часових поясів - Cron без `--tz` використовує часовий пояс хоста gateway. -- Розклади `at` без часового поясу трактуються як UTC. -- `activeHours` для heartbeat використовує налаштоване визначення часового поясу. +- Розклади `at` без часового поясу обробляються як UTC. +- Heartbeat `activeHours` використовує налаштоване визначення часового поясу. -## Пов'язане +## Пов’язане -- [Автоматизація та завдання](/automation) — огляд усіх механізмів автоматизації -- [Фонові завдання](/automation/tasks) — журнал завдань для виконань cron -- [Heartbeat](/gateway/heartbeat) — періодичні цикли основної сесії -- [Часовий пояс](/concepts/timezone) — налаштування часового поясу +- [Автоматизація та завдання](/uk/automation) — огляд усіх механізмів автоматизації +- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron +- [Heartbeat](/uk/gateway/heartbeat) — періодичні цикли основної сесії +- [Часовий пояс](/uk/concepts/timezone) — налаштування часового поясу diff --git a/docs/uk/automation/hooks.md b/docs/uk/automation/hooks.md index dbe919daa..5baaab272 100644 --- a/docs/uk/automation/hooks.md +++ b/docs/uk/automation/hooks.md @@ -1,62 +1,62 @@ --- read_when: - Вам потрібна автоматизація на основі подій для /new, /reset, /stop і подій життєвого циклу агента - - Ви хочете створювати, встановлювати або налагоджувати хуки + - Вам потрібно створити, встановити або налагодити хуки summary: 'Хуки: автоматизація на основі подій для команд і подій життєвого циклу' title: Хуки x-i18n: - generated_at: "2026-04-05T17:57:08Z" + generated_at: "2026-04-10T20:41:23Z" model: gpt-5.4 provider: openai - source_hash: 66eb75bb2b3b2ad229bf3da24fdb0fe021ed08f812fd1d13c69b3bd9df0218e5 + source_hash: 14296398e4042d442ebdf071a07c6be99d4afda7cbf3c2b934e76dc5539742c7 source_path: automation/hooks.md workflow: 15 --- # Хуки -Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Вони автоматично виявляються в каталогах, і їх можна переглянути за допомогою `openclaw hooks`. +Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Вони автоматично виявляються в каталогах, і їх можна переглядати за допомогою `openclaw hooks`. В OpenClaw є два типи хуків: - **Внутрішні хуки** (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от `/new`, `/reset`, `/stop` або події життєвого циклу. -- **Вебхуки**: зовнішні HTTP-ендпоїнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Вебхуки](/automation/cron-jobs#webhooks). +- **Вебхуки**: зовнішні HTTP-ендпоїнти, які дозволяють іншим системам запускати роботу в OpenClaw. Див. [Вебхуки](/uk/automation/cron-jobs#webhooks). -Хуки також можуть постачатися всередині plugins. `openclaw hooks list` показує як окремі хуки, так і хуки, керовані plugin. +Хуки також можуть бути вбудовані в плагіни. `openclaw hooks list` показує як окремі хуки, так і хуки, якими керують плагіни. ## Швидкий старт ```bash -# List available hooks +# Список доступних хуків openclaw hooks list -# Enable a hook +# Увімкнути хук openclaw hooks enable session-memory -# Check hook status +# Перевірити стан хуків openclaw hooks check -# Get detailed information +# Отримати докладну інформацію openclaw hooks info session-memory ``` ## Типи подій -| Подія | Коли спрацьовує | -| ------------------------ | --------------------------------------------- | -| `command:new` | Надіслано команду `/new` | -| `command:reset` | Надіслано команду `/reset` | -| `command:stop` | Надіслано команду `/stop` | -| `command` | Будь-яка подія команди (загальний слухач) | -| `session:compact:before` | Перед тим, як стиснення підсумує історію | -| `session:compact:after` | Після завершення стиснення | -| `session:patch` | Коли властивості сесії змінюються | -| `agent:bootstrap` | Перед інʼєкцією bootstrap-файлів робочої теки | -| `gateway:startup` | Після запуску каналів і завантаження хуків | -| `message:received` | Вхідне повідомлення з будь-якого каналу | -| `message:transcribed` | Після завершення транскрибування аудіо | -| `message:preprocessed` | Після завершення обробки всіх медіа і посилань | -| `message:sent` | Вихідне повідомлення доставлено | +| Подія | Коли спрацьовує | +| ------------------------ | ---------------------------------------------- | +| `command:new` | Видано команду `/new` | +| `command:reset` | Видано команду `/reset` | +| `command:stop` | Видано команду `/stop` | +| `command` | Будь-яка подія команди (загальний слухач) | +| `session:compact:before` | Перед тим, як ущільнення підсумовує історію | +| `session:compact:after` | Після завершення ущільнення | +| `session:patch` | Коли властивості сесії змінюються | +| `agent:bootstrap` | Перед вставленням bootstrap-файлів workspace | +| `gateway:startup` | Після запуску каналів і завантаження хуків | +| `message:received` | Вхідне повідомлення з будь-якого каналу | +| `message:transcribed` | Після завершення транскрибування аудіо | +| `message:preprocessed` | Після завершення обробки медіа та посилань | +| `message:sent` | Вихідне повідомлення доставлено | ## Написання хуків @@ -75,27 +75,27 @@ my-hook/ ```markdown --- name: my-hook -description: "Short description of what this hook does" +description: "Короткий опис того, що робить цей хук" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- # My Hook -Detailed documentation goes here. +Тут розміщується докладна документація. ``` **Поля метаданих** (`metadata.openclaw`): -| Поле | Опис | -| ---------- | ---------------------------------------------------- | -| `emoji` | Емодзі для відображення в CLI | -| `events` | Масив подій для прослуховування | -| `export` | Іменований експорт для використання (типово `"default"`) | -| `os` | Обовʼязкові платформи (наприклад, `["darwin", "linux"]`) | -| `requires` | Обовʼязкові шляхи `bins`, `anyBins`, `env` або `config` | -| `always` | Обходити перевірки відповідності (boolean) | -| `install` | Методи встановлення | +| Поле | Опис | +| ---------- | ------------------------------------------------------------ | +| `emoji` | Emoji для відображення в CLI | +| `events` | Масив подій для прослуховування | +| `export` | Іменований експорт для використання (типово `"default"`) | +| `os` | Потрібні платформи (наприклад, `["darwin", "linux"]`) | +| `requires` | Потрібні `bins`, `anyBins`, `env` або шляхи `config` | +| `always` | Обійти перевірки відповідності (boolean) | +| `install` | Методи встановлення | ### Реалізація обробника @@ -115,9 +115,9 @@ const handler = async (event) => { export default handler; ``` -Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте через push, щоб надсилати користувачу), і `context` (дані, специфічні для події). +Кожна подія містить: `type`, `action`, `sessionKey`, `timestamp`, `messages` (додавайте через push, щоб надіслати користувачу), і `context` (дані, специфічні для події). -### Ключові моменти контексту подій +### Основні елементи контексту подій **Події команд** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`. @@ -127,53 +127,57 @@ export default handler; **Події повідомлень** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. -**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточне збагачене тіло), `context.from`, `context.channelId`. +**Події повідомлень** (`message:preprocessed`): `context.bodyForAgent` (остаточний збагачений вміст), `context.from`, `context.channelId`. **Події bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (змінюваний масив), `context.agentId`. -**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Тільки привілейовані клієнти можуть запускати події patch. +**Події patch сесії** (`session:patch`): `context.sessionEntry`, `context.patch` (лише змінені поля), `context.cfg`. Лише привілейовані клієнти можуть запускати події patch. -**Події стиснення**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додає `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. +**Події ущільнення**: `session:compact:before` включає `messageCount`, `tokenCount`. `session:compact:after` додає `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. ## Виявлення хуків -Хуки виявляються в таких каталогах у порядку зростання пріоритету перевизначення: +Хуки виявляються з таких каталогів у порядку зростання пріоритету перевизначення: -1. **Вбудовані хуки**: постачаються з OpenClaw -2. **Plugin-хуки**: хуки, вбудовані у встановлені plugins -3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх робочих тек). Додаткові каталоги з `hooks.internal.load.extraDirs` мають той самий пріоритет. -4. **Хуки робочої теки**: `/hooks/` (для кожного агента окремо, типово вимкнені, доки їх явно не ввімкнути) +1. **Вбудовані хуки**: постачаються разом з OpenClaw +2. **Хуки плагінів**: хуки, вбудовані у встановлені плагіни +3. **Керовані хуки**: `~/.openclaw/hooks/` (встановлені користувачем, спільні для всіх workspace). Додаткові каталоги з `hooks.internal.load.extraDirs` мають той самий пріоритет. +4. **Хуки workspace**: `/hooks/` (для окремого агента, типово вимкнені, доки їх явно не увімкнути) -Хуки робочої теки можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані plugin хуки з тією самою назвою. +Хуки workspace можуть додавати нові назви хуків, але не можуть перевизначати вбудовані, керовані або надані плагінами хуки з тією ж назвою. -### Пакети хуків +### Набори хуків -Пакети хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення: +Набори хуків — це npm-пакети, які експортують хуки через `openclaw.hooks` у `package.json`. Встановлення: ```bash openclaw plugins install ``` -Npm-специфікації підтримують лише реєстр (назва пакета + необовʼязкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються. +Npm-специфікації підтримують лише реєстр (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються. ## Вбудовані хуки -| Хук | Події | Що робить | +| Хук | Події | Що він робить | | --------------------- | ------------------------------ | ----------------------------------------------------- | | session-memory | `command:new`, `command:reset` | Зберігає контекст сесії в `/memory/` | -| bootstrap-extra-files | `agent:bootstrap` | Інʼєктує додаткові bootstrap-файли за glob-шаблонами | +| bootstrap-extra-files | `agent:bootstrap` | Вставляє додаткові bootstrap-файли з glob-шаблонів | | command-logger | `command` | Логує всі команди в `~/.openclaw/logs/commands.log` | -| boot-md | `gateway:startup` | Запускає `BOOT.md` під час старту gateway | +| boot-md | `gateway:startup` | Запускає `BOOT.md`, коли запускається gateway | -Увімкнення будь-якого вбудованого хука: +Увімкнути будь-який вбудований хук: ```bash openclaw hooks enable ``` + + ### Докладніше про session-memory -Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файлу через LLM і зберігає в `/memory/YYYY-MM-DD-slug.md`. Потрібно, щоб `workspace.dir` було налаштовано. +Витягує останні 15 повідомлень користувача/асистента, генерує описовий slug імені файлу через LLM і зберігає його в `/memory/YYYY-MM-DD-slug.md`. Потрібно, щоб було налаштовано `workspace.dir`. + + ### Конфігурація bootstrap-extra-files @@ -192,13 +196,25 @@ openclaw hooks enable } ``` -Шляхи обчислюються відносно робочої теки. Завантажуються лише розпізнавані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). +Шляхи обчислюються відносно workspace. Завантажуються лише розпізнані базові назви bootstrap-файлів (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). -## Plugin-хуки + -Plugins можуть реєструвати хуки через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, зміни промптів, керування потоком повідомлень тощо. Plugin SDK надає 28 хуків, що охоплюють визначення моделі, життєвий цикл агента, потік повідомлень, виконання інструментів, координацію субагентів і життєвий цикл gateway. +### Докладніше про command-logger -Повний довідник з plugin-хуків, включно з `before_tool_call`, `before_agent_reply`, `before_install` та всіма іншими plugin-хуками, див. у [Архітектура plugins](/plugins/architecture#provider-runtime-hooks). +Логує кожну slash-команду в `~/.openclaw/logs/commands.log`. + + + +### Докладніше про boot-md + +Запускає `BOOT.md` з активного workspace під час запуску gateway. + +## Хуки плагінів + +Плагіни можуть реєструвати хуки через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, зміни промптів, керування потоком повідомлень тощо. Plugin SDK надає 28 хуків, що охоплюють визначення моделі, життєвий цикл агента, потік повідомлень, виконання інструментів, координацію субагентів і життєвий цикл gateway. + +Повний довідник із хуків плагінів, включно з `before_tool_call`, `before_agent_reply`, `before_install` та всіма іншими хуками плагінів, див. у [Архітектура плагінів](/uk/plugins/architecture#provider-runtime-hooks). ## Конфігурація @@ -254,37 +270,37 @@ Plugins можуть реєструвати хуки через Plugin SDK дл ## Довідка CLI ```bash -# List all hooks (add --eligible, --verbose, or --json) +# Список усіх хуків (додайте --eligible, --verbose або --json) openclaw hooks list -# Show detailed info about a hook +# Показати докладну інформацію про хук openclaw hooks info -# Show eligibility summary +# Показати зведення про відповідність openclaw hooks check -# Enable/disable +# Увімкнути/вимкнути openclaw hooks enable openclaw hooks disable ``` ## Рекомендовані практики -- **Зберігайте обробники швидкими.** Хуки запускаються під час обробки команд. Для важкої роботи використовуйте fire-and-forget через `void processInBackground(event)`. +- **Робіть обробники швидкими.** Хуки запускаються під час обробки команд. Для важких задач використовуйте fire-and-forget через `void processInBackground(event)`. - **Коректно обробляйте помилки.** Обгортайте ризиковані операції в try/catch; не викидайте винятки, щоб інші обробники могли виконатися. - **Рано фільтруйте події.** Одразу повертайтеся, якщо тип/дія події не є релевантними. -- **Використовуйте конкретні ключі подій.** Віддавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати. +- **Використовуйте конкретні ключі подій.** Надавайте перевагу `"events": ["command:new"]` замість `"events": ["command"]`, щоб зменшити накладні витрати. -## Усунення несправностей +## Усунення неполадок -### Хук не виявляється +### Хук не виявлено ```bash -# Verify directory structure +# Перевірте структуру каталогу ls -la ~/.openclaw/hooks/my-hook/ -# Should show: HOOK.md, handler.ts +# Має показати: HOOK.md, handler.ts -# List all discovered hooks +# Список усіх виявлених хуків openclaw hooks list ``` @@ -294,7 +310,7 @@ openclaw hooks list openclaw hooks info my-hook ``` -Перевірте, чи не бракує бінарних файлів (PATH), змінних середовища, значень конфігурації або сумісності з ОС. +Перевірте відсутні бінарні файли (PATH), змінні середовища, значення конфігурації або сумісність з ОС. ### Хук не виконується @@ -302,9 +318,9 @@ openclaw hooks info my-hook 2. Перезапустіть процес gateway, щоб хуки перезавантажилися. 3. Перевірте логи gateway: `./scripts/clawlog.sh | grep hook` -## Повʼязане +## Пов’язане - [Довідка CLI: hooks](/cli/hooks) -- [Вебхуки](/automation/cron-jobs#webhooks) -- [Архітектура plugins](/plugins/architecture#provider-runtime-hooks) — повний довідник з plugin-хуків -- [Конфігурація](/gateway/configuration-reference#hooks) +- [Вебхуки](/uk/automation/cron-jobs#webhooks) +- [Архітектура плагінів](/uk/plugins/architecture#provider-runtime-hooks) — повний довідник із хуків плагінів +- [Конфігурація](/uk/gateway/configuration-reference#hooks) diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index 63479c708..50d798a4e 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -1,15 +1,15 @@ --- read_when: - Перше налаштування OpenClaw - - Пошук поширених шаблонів конфігурації - - Перехід до конкретних розділів конфігурації + - Шукаєте поширені шаблони конфігурації + - Перехід до певних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-08T05:15:04Z" + generated_at: "2026-04-10T20:41:24Z" model: gpt-5.4 provider: openai - source_hash: 199a1e515bd4003319e71593a2659bb883299a76ff67e273d92583df03c96604 + source_hash: e874be80d11b9123cac6ce597ec02667fbc798f622a076f68535a1af1f0e399c source_path: gateway/configuration.md workflow: 15 --- @@ -22,12 +22,12 @@ OpenClaw читає необов’язкову конфігурацію -**Новачок у конфігурації?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими повними конфігураціями для копіювання. +**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) для готових конфігурацій, які можна повністю скопіювати й вставити. ## Мінімальна конфігурація @@ -58,43 +58,43 @@ OpenClaw читає необов’язкову конфігурацію Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**. - Control UI відображає форму на основі актуальної схеми конфігурації, зокрема метадані документації полів - `title` / `description`, а також схеми plugins і каналів, коли вони - доступні, із редактором **Raw JSON** як запасним варіантом. Для деталізованих - UI та інших інструментів gateway також надає `config.schema.lookup`, щоб - отримати один вузол схеми, обмежений шляхом, разом із короткими зведеннями безпосередніх дочірніх елементів. + Control UI відображає форму на основі актуальної схеми конфігурації, включно з + метаданими документації полів `title` / `description`, а також схемами плагінів і каналів, + якщо вони доступні, з редактором **Raw JSON** як запасним варіантом. Для + UI із поглибленою навігацією та інших інструментів gateway також надає `config.schema.lookup`, + щоб отримати один вузол схеми, обмежений шляхом, а також зведення для його безпосередніх дочірніх елементів. - Відредагуйте `~/.openclaw/openclaw.json` напряму. Gateway стежить за файлом і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). + Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway стежить за файлом і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). ## Сувора валідація -OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. +OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, неправильні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. -Примітки щодо інструментів схеми: +Примітки щодо інструментів схем: -- `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI +- `openclaw config schema` виводить ту саму родину JSON Schema, яку використовують Control UI і валідація конфігурації. -- Вважайте цей вивід схеми канонічним машинозчитуваним контрактом для - `openclaw.json`; цей огляд і довідник конфігурації її узагальнюють. +- Сприймайте цей вивід схеми як канонічний машиночитний контракт для + `openclaw.json`; цей огляд і довідник конфігурації узагальнюють його. - Значення полів `title` і `description` переносяться у вивід схеми для - редакторів і формових інструментів. -- Вкладені об’єкти, записи з шаблоном (`*`) і елементи масивів (`[]`) успадковують ті самі - метадані документації там, де існує відповідна документація поля. -- Гілки композицій `anyOf` / `oneOf` / `allOf` також успадковують ті самі - метадані документації, тож варіанти union/intersection зберігають ту саму довідку для поля. -- `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі - та подібні поля валідації), відповідними метаданими UI-підказок і короткими зведеннями безпосередніх дочірніх - елементів для інструментів деталізації. -- Схеми plugins/каналів під час виконання додаються через злиття, коли gateway може завантажити + редакторів та інструментів форм. +- Вкладені об’єкти, записи з шаблоном (`*`) і елементи масиву (`[]`) успадковують ті самі + метадані документації там, де існує відповідна документація для полів. +- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі + метадані документації, тож варіанти union/intersection зберігають ту саму довідку для полів. +- `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження + та подібні поля валідації), відповідними метаданими підказок UI і зведеннями + для безпосередніх дочірніх елементів для інструментів із поглибленою навігацією. +- Схеми плагінів/каналів під час виконання об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розходження між артефактами базової конфігурації, орієнтованими на документацію, - і поточною поверхнею схеми. +- `pnpm config:docs:check` виявляє розбіжності між артефактами базової конфігурації для документації + та поточною поверхнею схеми. Коли валідація не проходить: @@ -107,7 +107,7 @@ OpenClaw приймає лише конфігурації, які повніст - Кожен канал має власний розділ конфігурації в `channels.`. Див. окрему сторінку каналу для кроків налаштування: + Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу для кроків налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` - [Telegram](/uk/channels/telegram) — `channels.telegram` @@ -129,7 +129,7 @@ OpenClaw приймає лише конфігурації, які повніст enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled - allowFrom: ["tg:123"], // лише для allowlist/open + allowFrom: ["tg:123"], // only for allowlist/open }, }, } @@ -138,7 +138,7 @@ OpenClaw приймає лише конфігурації, які повніст - Налаштуйте основну модель і необов’язкові резервні: + Вкажіть основну модель і необов’язкові резервні варіанти: ```json5 { @@ -157,30 +157,30 @@ OpenClaw приймає лише конфігурації, які повніст } ``` - - `agents.defaults.models` визначає каталог моделей і діє як allowlist для `/model`. + - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у стенограмах/інструментах (типове значення `1200`); нижчі значення зазвичай зменшують використання vision-token у сесіях із великою кількістю знімків екрана. - - Див. [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервного перемикання. - - Для користувацьких/self-hosted providers див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. + - Див. [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover) щодо ротації автентифікації та поведінки резервних варіантів. + - Для власних/self-hosted провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. - Доступ до DM керується окремо для кожного каналу через `dmPolicy`: + Доступ до DM налаштовується окремо для кожного каналу через `dmPolicy`: - `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для підтвердження - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow) - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) - `"disabled"`: ігнорувати всі DM - Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlists, специфічні для каналу. + Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. - Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для деталей по кожному каналу. + Перегляньте [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу. - - Для групових повідомлень типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: + + Для повідомлень у групах типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -202,15 +202,15 @@ OpenClaw приймає лише конфігурації, які повніст } ``` - - **Metadata mentions**: нативні @-згадування (WhatsApp tap-to-mention, Telegram @bot тощо) - - **Text patterns**: безпечні regex-шаблони в `mentionPatterns` + - **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) + - **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns` - Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень по каналах і режиму self-chat. - Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретних - агентів через `agents.list[].skills`: + Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте + окремих агентів через `agents.list[].skills`: ```json5 { @@ -219,24 +219,24 @@ OpenClaw приймає лише конфігурації, які повніст skills: ["github", "weather"], }, list: [ - { id: "writer" }, // успадковує github, weather - { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням - { id: "locked-down", skills: [] }, // без Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` - - Не вказуйте `agents.defaults.skills`, якщо типово Skills мають бути без обмежень. + - Не вказуйте `agents.defaults.skills`, якщо типово Skills не мають бути обмежені. - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. - - Встановіть `agents.list[].skills: []`, щоб не було жодних Skills. + - Укажіть `agents.list[].skills: []`, якщо Skills не потрібні. - Див. [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і - [Довідник конфігурації](/uk/gateway/configuration-reference#agentsdefaultsskills). + [Довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). - Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають застарілими: + Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають неактивними: ```json5 { @@ -258,20 +258,20 @@ OpenClaw приймає лише конфігурації, які повніст } ``` - - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски health-monitor. + - Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски health-monitor. - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. - - Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоматичні перезапуски для одного каналу або облікового запису без вимкнення глобального монітора. + - Див. [Health Checks](/uk/gateway/health) для операційного налагодження і [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - Сесії керують безперервністю та ізоляцією розмов: + Сесії керують безперервністю розмов і ізоляцією: ```json5 { session: { - dmScope: "per-channel-peer", // рекомендовано для багатьох користувачів + dmScope: "per-channel-peer", // recommended for multi-user threadBindings: { enabled: true, idleHours: 24, @@ -287,14 +287,14 @@ OpenClaw приймає лише конфігурації, які повніст ``` - `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Див. [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання. + - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Див. [Керування сесіями](/uk/concepts/session) щодо області видимості, зв’язків ідентичностей і політики надсилання. - Див. [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. - Запускайте сесії агентів в ізольованих контейнерах Docker: + Запускайте сесії агентів в ізольованих Docker-контейнерах: ```json5 { @@ -311,14 +311,14 @@ OpenClaw приймає лише конфігурації, які повніст Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. + Див. [Ізоляція](/uk/gateway/sandboxing) для повного посібника і [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. Push через relay налаштовується в `openclaw.json`. - Додайте це до конфігурації gateway: + Укажіть це в конфігурації gateway: ```json5 { @@ -327,7 +327,7 @@ OpenClaw приймає лише конфігурації, які повніст apns: { relay: { baseUrl: "https://relay.example.com", - // Необов’язково. Типове значення: 10000 + // Optional. Default: 10000 timeoutMs: 10000, }, }, @@ -344,35 +344,35 @@ OpenClaw приймає лише конфігурації, які повніст Що це робить: - - Дозволяє gateway надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній relay. - - Використовує право надсилання, прив’язане до реєстрації, яке пересилає paired iOS app. Gateway не потребує relay-токена рівня всього розгортання. - - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою було paired iOS app, тому інший gateway не може повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційних розповсюджуваних збірок, що зареєструвалися через relay. - - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до одного й того самого розгортання relay. + - Дозволяє gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay. + - Використовує дозвіл на надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен токен relay для всього розгортання. + - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою було спарено застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію. + - Зберігає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційних поширюваних збірок, які зареєструвалися через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. - Повний потік роботи: + Повний потік: - 1. Встановіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. + 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. - 3. Виконайте pairing iOS app із gateway і дочекайтеся підключення сесій вузла й оператора. - 4. iOS app отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції app, а потім публікує payload `push.apns.register` через relay до paired gateway. - 5. Gateway зберігає relay handle і право надсилання, а потім використовує їх для `push.test`, сигналів пробудження й пробуджень повторного підключення. + 3. Спарте застосунок iOS із gateway і дайте підключитися сесіям вузла та оператора. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay на спарений gateway. + 5. Gateway зберігає дескриптор relay і дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та сигналів повторного підключення. Операційні примітки: - - Якщо ви перемикаєте iOS app на інший gateway, перепідключіть app, щоб воно могло опублікувати нову реєстрацію relay, прив’язану до цього gateway. - - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, app оновлює кешовану реєстрацію relay замість повторного використання старого походження relay. + - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway. + - Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює кешовану реєстрацію relay замість повторного використання старого джерела relay. Примітка щодо сумісності: - - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові env-перевизначення. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається лише для loopback як шлях обходу в середовищі розробки; не зберігайте HTTP URL relay у конфігурації. + - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається варіантом обходу лише для розробки на loopback; не зберігайте HTTP URL relay у конфігурації. - Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного потоку й [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. + Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного потоку та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. - + ```json5 { agents: { @@ -386,9 +386,9 @@ OpenClaw приймає лише конфігурації, які повніст } ``` - - `every`: рядок тривалості (`30m`, `2h`). Встановіть `0m`, щоб вимкнути. + - `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`) - - `directPolicy`: `allow` (типово) або `block` для heartbeat-цілей у стилі DM + - `directPolicy`: `allow` (типово) або `block` для цілей heartbeat у стилі DM - Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника. @@ -408,14 +408,14 @@ OpenClaw приймає лише конфігурації, які повніст } ``` - - `sessionRetention`: очищати завершені ізольовані сесії запуску з `sessions.json` (типове значення `24h`; встановіть `false`, щоб вимкнути). - - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Див. [Cron jobs](/uk/automation/cron-jobs) для огляду функції та прикладів CLI. + - `sessionRetention`: видаляти завершені ізольовані сесії запусків із `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: обрізати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Див. [Cron jobs](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. - - Увімкніть HTTP webhook endpoints на Gateway: + + Увімкніть кінцеві точки HTTP webhook на Gateway: ```json5 { @@ -439,20 +439,20 @@ OpenClaw приймає лише конфігурації, які повніст ``` Примітка щодо безпеки: - - Вважайте весь вміст payload hook/webhook недовіреним введенням. + - Сприймайте весь вміст payload hook/webhook як недовірений ввід. - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - - Автентифікація hooks працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. - - `hooks.path` не може бути `/`; залишайте webhook ingress на окремому підшляху, наприклад `/hooks`. - - Тримайте прапори обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте строго обмежене налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які вибирає викликач. - - Для агентів, керованих hooks, надавайте перевагу потужним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). + - Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. + - `hooks.path` не може бути `/`; використовуйте для webhook ingress окремий підшлях, наприклад `/hooks`. + - Залишайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які можуть обирати викликачі. + - Для агентів, керованих hook, надавайте перевагу потужним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція там, де це можливо). Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mappings і інтеграції Gmail. - - Запускайте кількох ізольованих агентів з окремими workspace і сесіями: + + Запускайте кілька ізольованих агентів з окремими робочими просторами й сесіями: ```json5 { @@ -474,7 +474,7 @@ OpenClaw приймає лише конфігурації, які повніст - Використовуйте `$include`, щоб упорядкувати великі конфігурації: + Використовуйте `$include` для впорядкування великих конфігурацій: ```json5 // ~/.openclaw/openclaw.json @@ -487,28 +487,28 @@ OpenClaw приймає лише конфігурації, які повніст } ``` - - **Один файл**: замінює об’єкт, у якому міститься - - **Масив файлів**: deep-merge у вказаному порядку (пізніші мають пріоритет) - - **Сусідні ключі**: зливаються після include’ів (перевизначають включені значення) - - **Вкладені include’и**: підтримуються до 10 рівнів вкладеності - - **Відносні шляхи**: обчислюються відносно файла, який виконує включення - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу й циклічних include’ів + - **Окремий файл**: замінює об’єкт, у якому міститься + - **Масив файлів**: об’єднується глибоким злиттям у вказаному порядку (пізніші мають пріоритет) + - **Сусідні ключі**: зливаються після includes (перевизначають включені значення) + - **Вкладені includes**: підтримуються до 10 рівнів вкладеності + - **Відносні шляхи**: обчислюються відносно файла, що включає + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу й циклічних includes ## Гаряче перезавантаження конфігурації -Gateway стежить за `~/.openclaw/openclaw.json` і застосовує зміни автоматично — для більшості налаштувань ручний перезапуск не потрібен. +Gateway стежить за `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. ### Режими перезавантаження -| Режим | Поведінка | -| ---------------------- | -------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Безпечно застосовує зміни одразу. Автоматично перезапускається для критичних змін. | -| **`hot`** | Лише безпечно застосовує зміни. Записує попередження, коли потрібен перезапуск — ви обробляєте це самі. | +| Режим | Поведінка | +| ---------------------- | --------------------------------------------------------------------------------------- | +| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Для критичних змін автоматично перезапускається. | +| **`hot`** | Гаряче застосовує лише безпечні зміни. Коли потрібен перезапуск, записує попередження в журнал — ви обробляєте це самі. | | **`restart`** | Перезапускає Gateway після будь-якої зміни конфігурації, безпечної чи ні. | -| **`off`** | Вимикає стеження за файлом. Зміни набирають чинності після наступного ручного перезапуску. | +| **`off`** | Вимикає стеження за файлом. Зміни набудуть чинності під час наступного ручного перезапуску. | ```json5 { @@ -520,37 +520,37 @@ Gateway стежить за `~/.openclaw/openclaw.json` і застосовує ### Що застосовується гаряче, а що потребує перезапуску -Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, які потребують перезапуску, обробляються автоматично. +Більшість полів гаряче застосовуються без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. -| Категорія | Поля | Потрібен перезапуск? | -| ----------------- | -------------------------------------------------------------------- | -------------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані й extension канали | Ні | -| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | -| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сесії й повідомлення | `session`, `messages` | Ні | -| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | -| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | -| Сервер gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | -| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | +| Категорія | Поля | Потрібен перезапуск? | +| ------------------- | -------------------------------------------------------------------- | -------------------- | +| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані й розширювані канали | Ні | +| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | +| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | +| Сесії й повідомлення | `session`, `messages` | Ні | +| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | +| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | +| Сервер gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | +| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` — винятки: їх зміна **не** викликає перезапуск. +`gateway.reload` і `gateway.remote` — винятки: зміна цих полів **не** спричиняє перезапуск. -## Config RPC (програмні оновлення) +## RPC конфігурації (програмні оновлення) -RPC керуючої площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити на 60 секунд** для кожної пари `deviceId+clientIp`. У разі обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. +RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) мають обмеження частоти: **3 запити за 60 секунд** для кожної пари `deviceId+clientIp`. Після спрацювання обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. Безпечний/типовий потік: -- `config.schema.lookup`: переглянути одне піддерево конфігурації, обмежене шляхом, з неглибоким - вузлом схеми, відповідними метаданими підказок і короткими зведеннями безпосередніх дочірніх елементів +- `config.schema.lookup`: перевірити одне піддерево конфігурації, обмежене шляхом, із поверхневим + вузлом схеми, відповідними метаданими підказок і зведеннями для безпосередніх дочірніх елементів - `config.get`: отримати поточний знімок + hash -- `config.patch`: бажаний шлях часткового оновлення +- `config.patch`: рекомендований шлях часткового оновлення - `config.apply`: лише повна заміна конфігурації -- `update.run`: явне самооновлення + перезапуск +- `update.run`: явне самостійне оновлення + перезапуск Якщо ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`, а потім `config.patch`. @@ -566,15 +566,15 @@ RPC керуючої площини для запису (`config.apply`, `config Параметри: - `raw` (string) — payload JSON5 для всієї конфігурації - - `baseHash` (optional) — hash конфігурації з `config.get` (обов’язковий, якщо конфігурація вже існує) - - `sessionKey` (optional) — ключ сесії для ping пробудження після перезапуску - - `note` (optional) — примітка для restart sentinel - - `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000) + - `baseHash` (необов’язковий) — hash конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) + - `sessionKey` (необов’язковий) — ключ сесії для ping пробудження після перезапуску + - `note` (необов’язковий) — примітка для sentinel перезапуску + - `restartDelayMs` (необов’язковий) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундна пауза. + Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний cooldown. ```bash - openclaw gateway call config.get --params '{}' # отримати payload.hash + openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.apply --params '{ "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }", "baseHash": "", @@ -585,19 +585,19 @@ RPC керуючої площини для запису (`config.apply`, `config - Зливає часткове оновлення з наявною конфігурацією (семантика JSON merge patch): + Об’єднує часткове оновлення з наявною конфігурацією (семантика JSON merge patch): - - Об’єкти зливаються рекурсивно + - Об’єкти об’єднуються рекурсивно - `null` видаляє ключ - Масиви замінюються Параметри: - - `raw` (string) — JSON5 лише з ключами, які треба змінити - - `baseHash` (required) — hash конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — те саме, що й для `config.apply` + - `raw` (string) — JSON5 лише з ключами, які потрібно змінити + - `baseHash` (обов’язковий) — hash конфігурації з `config.get` + - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` - Поведінка перезапуску така сама, як у `config.apply`: об’єднання очікуваних перезапусків і 30-секундна пауза між циклами перезапуску. + Поведінка перезапуску відповідає `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундний cooldown між циклами перезапуску. ```bash openclaw gateway call config.patch --params '{ @@ -613,10 +613,10 @@ RPC керуючої площини для запису (`config.apply`, `config OpenClaw читає env vars із батьківського процесу, а також: -- `.env` із поточного робочого каталогу (якщо є) -- `~/.openclaw/.env` (глобальний резервний варіант) +- `.env` з поточного робочого каталогу (якщо є) +- `~/.openclaw/.env` (глобальний запасний варіант) -Жоден із цих файлів не перевизначає наявні env vars. Ви також можете задавати inline env vars у конфігурації: +Жоден із цих файлів не перевизначає наявні env vars. Ви також можете встановлювати inline env vars у конфігурації: ```json5 { @@ -627,8 +627,8 @@ OpenClaw читає env vars із батьківського процесу, а } ``` - - Якщо це ввімкнено й очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + + Якщо це ввімкнено і очікувані ключі не встановлені, OpenClaw запускає вашу shell входу й імпортує лише відсутні ключі: ```json5 { @@ -642,7 +642,7 @@ OpenClaw читає env vars із батьківського процесу, а - Посилайтеся на env vars у будь-якому рядковому значенні конфігурації через `${VAR_NAME}`: + Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -653,15 +653,15 @@ OpenClaw читає env vars із батьківського процесу, а Правила: -- Збігаються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` -- Відсутні/порожні env vars викликають помилку під час завантаження -- Екрануйте як `$${VAR}` для буквального виводу +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Відсутні/порожні змінні спричиняють помилку під час завантаження +- Екрануйте через `$${VAR}` для буквального виводу - Працює всередині файлів `$include` -- Inline substitution: `"${BASE}/v1"` → `"https://api.example.com/v1"` +- Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - + Для полів, які підтримують об’єкти SecretRef, можна використовувати: ```json5 @@ -694,15 +694,15 @@ OpenClaw читає env vars із батьківського процесу, а } ``` -Докладніше про SecretRef (зокрема `secrets.providers` для `env`/`file`/`exec`) див. у [Secrets Management](/uk/gateway/secrets). -Підтримувані шляхи облікових даних наведено в [SecretRef Credential Surface](/uk/reference/secretref-credential-surface). +Подробиці SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведено в [Керування секретами](/uk/gateway/secrets). +Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Див. [Environment](/uk/help/environment) для повного порядку пріоритетів і джерел. +Див. [Environment](/uk/help/environment) для повного пріоритету та джерел. ## Повний довідник -Для повного довідника за полями див. **[Configuration Reference](/uk/gateway/configuration-reference)**. +Повний довідник по кожному полю дивіться в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. --- diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index d09f2869d..790169fdd 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -4,10 +4,10 @@ read_when: summary: Міркування безпеки та модель загроз для запуску AI-шлюзу з доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-10T18:37:00Z" + generated_at: "2026-04-10T20:41:23Z" model: gpt-5.4 provider: openai - source_hash: fee87a3b1bbddf46326754305d78f51bd958de4d91325c55b856dbd09e3006d8 + source_hash: 770407f64b2ce27221ebd9756b2f8490a249c416064186e64edb663526f9d6b5 source_path: gateway/security/index.md workflow: 15 --- @@ -15,29 +15,29 @@ x-i18n: # Безпека -**Модель довіри персонального помічника:** ці рекомендації припускають одну межу довіри оператора на один шлюз (модель одного користувача/персонального помічника). -OpenClaw **не є** ворожою багатокористувацькою межею безпеки для кількох зловмисних користувачів, які спільно використовують одного агента/шлюз. -Якщо вам потрібна робота зі змішаною довірою або зловмисними користувачами, розділіть межі довіри (окремий шлюз + облікові дані, в ідеалі окремі користувачі ОС/хости). +**Модель довіри для персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри оператора на шлюз (модель одного користувача / персонального асистента). +OpenClaw **не** є безпечною межею для ворожого багатокористувацького середовища, де кілька недовірених користувачів ділять одного агента/шлюз. +Якщо вам потрібна робота зі змішаним рівнем довіри або ворожими користувачами, розділіть межі довіри (окремий шлюз + облікові дані, бажано також окремі користувачі ОС/хости). -**На цій сторінці:** [Модель довіри](#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 щодо безпеки припускають розгортання **персонального асистента**: одна межа довіри оператора, потенційно багато агентів. -- Підтримувана позиція безпеки: один користувач/межа довіри на один шлюз (бажано один користувач ОС/хост/VPS на одну межу). -- Непідтримувана межа безпеки: один спільний шлюз/агент, який використовується взаємно недовіреними або зловмисними користувачами. -- Якщо потрібна ізоляція зловмисних користувачів, розділяйте за межами довіри (окремий шлюз + облікові дані, і в ідеалі окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що всі вони спільно використовують один і той самий делегований рівень доступу до інструментів цього агента. +- Підтримувана модель безпеки: один користувач / одна межа довіри на шлюз (бажано один користувач ОС/хост/VPS на межу). +- Непідтримувана межа безпеки: один спільний шлюз/агент, яким користуються взаємно недовірені або ворожі користувачі. +- Якщо потрібна ізоляція від ворожих користувачів, розділяйте за межами довіри (окремий шлюз + облікові дані, а бажано також окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що всі вони спільно використовують ті самі делеговані повноваження цього агента. -На цій сторінці пояснюється посилення безпеки **в межах цієї моделі**. Вона не стверджує наявність ворожої багатокористувацької ізоляції на одному спільному шлюзі. +Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ізоляції для ворожого багатокористувацького середовища на одному спільному шлюзі. ## Швидка перевірка: `openclaw security audit` Див. також: [Формальна верифікація (моделі безпеки)](/uk/security/formal-verification) -Регулярно запускайте це (особливо після зміни конфігурації або відкриття мережевих поверхонь): +Запускайте це регулярно (особливо після зміни конфігурації або відкриття мережевих поверхонь): ```bash openclaw security audit @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно залишається вузькоспрямованим: перемикає типові відкриті групові політики на allowlists, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-файлів і використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. +`security audit --fix` навмисно має вузьку дію: він переводить типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-файлів і використовує скидання Windows ACL замість POSIX `chmod` під час роботи у Windows. -Він виявляє поширені небезпечні конфігурації (викриття Gateway auth, викриття керування браузером, підвищені allowlists, дозволи файлової системи, надто поблажливі схвалення exec і відкритий доступ до інструментів у каналах). +Він виявляє типові небезпечні конфігурації (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, підвищені allowlist, дозволи файлової системи, надто поблажливі схвалення exec і відкритий доступ інструментів у каналах). OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — свідомо контролювати: -- хто може звертатися до вашого бота -- де боту дозволено діяти -- до чого бот може отримати доступ +- хто може взаємодіяти з вашим ботом +- де бот має право діяти +- до чого бот може мати доступ -Починайте з мінімального доступу, який усе ще працює, а потім розширюйте його в міру зростання впевненості. +Починайте з мінімального доступу, якого достатньо для роботи, і розширюйте його лише тоді, коли зростає ваша впевненість. ### Розгортання та довіра до хоста -OpenClaw припускає, що хост і межа конфігурації є довіреними: +OpenClaw виходить із довіри до хоста та межі конфігурації: -- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте його довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/зловмисних операторів **не є рекомендованою конфігурацією**. -- Для команд зі змішаною довірою розділяйте межі довіри за допомогою окремих шлюзів (або принаймні окремих користувачів ОС/хостів). -- Рекомендований варіант за замовчуванням: один користувач на одну машину/хост (або VPS), один gateway для цього користувача й один або кілька агентів у цьому gateway. -- У межах одного екземпляра Gateway автентифікований доступ оператора — це довірена роль control-plane, а не роль окремого користувача-орендаря. -- Ідентифікатори сесій (`sessionKey`, ID сесій, мітки) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може спрямовувати той самий набір дозволів. Ізоляція сесій/пам’яті на рівні користувача допомагає з приватністю, але не перетворює спільного агента на авторизацію хоста для окремих користувачів. +- Якщо хтось може змінювати стан/конфігурацію Gateway на хості (`~/.openclaw`, включно з `openclaw.json`), вважайте цю людину довіреним оператором. +- Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованим сценарієм**. +- Для команд зі змішаним рівнем довіри розділяйте межі довіри окремими шлюзами (або щонайменше окремими користувачами ОС/хостами). +- Рекомендоване типове налаштування: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або кілька агентів у цьому gateway. +- У межах одного екземпляра Gateway автентифікований доступ оператора — це роль довіреної control plane, а не роль окремого користувача-орендаря. +- Ідентифікатори сесії (`sessionKey`, ID сесій, мітки) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні користувача допомагає конфіденційності, але не перетворює спільного агента на авторизацію хоста на рівні окремого користувача. ### Спільний робочий простір Slack: реальний ризик -Якщо «будь-хто в Slack може написати боту», основний ризик — це делегований доступ до інструментів: +Якщо «будь-хто у Slack може написати боту», основний ризик — це делеговані повноваження інструментів: -- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) у межах політики агента; -- ін’єкція промптів/вмісту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; -- якщо один спільний агент має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може керувати витоком даних через використання інструментів. +- будь-який дозволений відправник може спричинити виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) в межах політик агента; +- ін’єкція підказок/вмісту від одного відправника може викликати дії, що впливають на спільний стан, пристрої або результати; +- якщо один спільний агент має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може спричинити витік через використання інструментів. -Для командних робочих процесів використовуйте окремі агенти/шлюзи з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. +Для командних сценаріїв використовуйте окремих агентів/шлюзи з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. ### Спільний агент компанії: прийнятний шаблон -Це прийнятно, якщо всі, хто використовує цього агента, перебувають в одній межі довіри (наприклад, одна команда в компанії) і агент має суворо бізнесову сферу застосування. +Це прийнятно, якщо всі, хто користується цим агентом, перебувають у межах однієї довіри (наприклад, одна команда в компанії) і агент суворо обмежений робочими завданнями. -- запускайте його на окремій машині/VM/контейнері; -- використовуйте окремого користувача ОС + окремий браузер/профіль/облікові записи для цього середовища виконання; -- не входьте в цьому середовищі у персональні облікові записи Apple/Google або персональні профілі менеджера паролів/браузера. +- запускайте його на виділеній машині/VM/контейнері; +- використовуйте окремого користувача ОС + окремий браузер/профіль/акаунти для цього runtime; +- не входьте в цьому runtime у персональні облікові записи Apple/Google чи особисті профілі браузера/менеджера паролів. -Якщо ви змішуєте особисті та корпоративні ідентичності в одному середовищі виконання, ви руйнуєте розділення й підвищуєте ризик витоку персональних даних. +Якщо ви змішуєте особисті та корпоративні ідентичності в одному runtime, ви руйнуєте поділ і підвищуєте ризик витоку персональних даних. -## Концепція довіри до Gateway і node +## Концепція довіри між Gateway і node -Розглядайте Gateway і node як один домен довіри оператора з різними ролями: +Розглядайте Gateway і node як одну доменну область довіри оператора, але з різними ролями: - **Gateway** — це control plane і поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, спарена з цим Gateway (команди, дії на пристрої, локальні можливості хоста). -- Викликаючий клієнт, автентифікований у Gateway, є довіреним у межах Gateway. Після спарювання дії node — це дії довіреного оператора на цьому node. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація окремого користувача. -- Схвалення exec (allowlist + ask) — це запобіжники для намірів оператора, а не ворожа багатокористувацька ізоляція. -- Типовий варіант OpenClaw для довірених конфігурацій з одним оператором полягає в тому, що host exec на `gateway`/`node` дозволено без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви це не посилите). Ця поведінка за замовчуванням є навмисним UX-рішенням, а не вразливістю сама по собі. -- Схвалення exec прив’язуються до точного контексту запиту та найкращим зусиллям до прямих локальних файлових операндів; вони не моделюють семантично кожен шлях завантажувача під час виконання/інтерпретації. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії з пристроями, можливості хоста на цьому вузлі). +- Викликаючий, автентифікований у Gateway, є довіреним у межах Gateway. Після pairing дії node вважаються діями довіреного оператора на цьому node. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на рівні користувача. +- Схвалення exec (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. +- Типова поведінка продукту OpenClaw для довірених конфігурацій з одним оператором полягає в тому, що host exec на `gateway`/`node` дозволений без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви самі не посилите політику). Цей типовий режим — свідоме UX-рішення, а не вразливість сам по собі. +- Схвалення exec прив’язані до точного контексту запиту та, наскільки можливо, до прямих локальних файлових операндів; вони не моделюють семантично всі шляхи завантаження під час виконання/інтерпретації. Для сильних меж використовуйте sandboxing та ізоляцію хоста. -Якщо вам потрібна ізоляція від зловмисних користувачів, розділяйте межі довіри за користувачем ОС/хостом і запускайте окремі шлюзи. +Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами й запускайте окремі шлюзи. ## Матриця меж довіри Використовуйте це як швидку модель під час оцінювання ризику: -| Межа або контроль | Що це означає | Поширене хибне тлумачення | -| ------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликаючих клієнтів для API gateway | «Щоб бути безпечним, потрібні підписи для кожного повідомлення на кожному кадрі» | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії є межею автентифікації користувача» | -| Запобіжники промптів/вмісту | Зменшують ризик зловживання моделлю | «Лише ін’єкція промпта вже доводить обхід автентифікації» | -| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли її увімкнено | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | -| Локальна TUI-оболонка `!` | Явний локальний запуск, ініційований оператором | «Зручна локальна команда оболонки — це віддалена ін’єкція» | -| Pairing node і команди node | Віддалене виконання на рівні оператора на спарених пристроях | «Керування віддаленим пристроєм слід за замовчуванням вважати доступом недовіреного користувача» | +| Межа або контроль | Що це означає | Типове хибне тлумачення | +| -------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує виклики до API шлюзу | «Щоб було безпечно, потрібні підписи кожного повідомлення в кожному кадрі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії — це межа автентифікації користувача» | +| Запобіжники для prompt/content | Знижують ризик зловживання моделлю | «Одна лише prompt injection уже доводить обхід автентифікації» | +| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли увімкнено | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна TUI-команда `!` shell | Явний локальний запуск, ініційований оператором | «Зручна локальна shell-команда — це віддалена ін’єкція» | +| Pairing node і команди node | Віддалене виконання на рівні оператора на paired-пристроях | «Керування віддаленим пристроєм за замовчуванням слід вважати доступом недовіреного користувача» | ## За задумом не є вразливостями -Про ці шаблони часто повідомляють, але зазвичай їх закривають без дій, якщо не показано реального обходу меж: +Ці шаблони часто повідомляють як проблеми, але зазвичай їх закривають без дій, якщо не показано реальний обхід межі: -- Ланцюжки лише з ін’єкцією промпта без обходу політики/автентифікації/sandbox. -- Твердження, що припускають ворожу багатокористувацьку роботу на одному спільному хості/конфігурації. -- Заяви, які класифікують звичайний доступ оператора шляхом читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у спільній конфігурації gateway. -- Виявлення, що стосуються лише localhost-розгортання (наприклад, HSTS на gateway, доступному тільки через loopback). -- Висновки про підписи вхідних webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. -- Звіти, які трактують метадані pairing node як прихований другий рівень схвалення для кожної команди `system.run`, тоді як реальною межею виконання все ще є глобальна політика команд node у gateway плюс власні схвалення exec на node. -- Виявлення про «відсутню авторизацію на рівні користувача», які трактують `sessionKey` як токен автентифікації. +- Ланцюжки, що ґрунтуються лише на prompt injection без обходу політик/автентифікації/sandbox. +- Твердження, які припускають ворожий багатокористувацький сценарій на одному спільному хості/конфігурації. +- Твердження, які класифікують нормальний операторський доступ на читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації спільного gateway. +- Знахідки, релевантні лише для localhost-розгортання (наприклад, HSTS на шлюзі, доступному тільки через loopback). +- Знахідки щодо підпису вхідних webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. +- Звіти, які трактують метадані pairing node як прихований другий шар схвалення для кожної команди `system.run`, хоча реальна межа виконання — це глобальна політика команд node на шлюзі плюс власні схвалення exec на node. +- Знахідки про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. -## Контрольний список для дослідника перед поданням +## Контрольний список дослідника перед поданням -Перш ніж відкривати GHSA, перевірте все з наведеного нижче: +Перш ніж відкривати GHSA, перевірте все з цього списку: -1. Відтворення все ще працює на останньому `main` або останньому релізі. -2. Звіт містить точний шлях у коді (`file`, function, range рядків) і протестовану версію/коміт. -3. Вплив перетинає документовану межу довіри (а не лише ін’єкцію промпта). -4. Заяву не включено до [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). -5. Наявні advisory перевірено на дублікати (за потреби повторно використовуйте канонічний GHSA). -6. Припущення щодо розгортання явно вказані (loopback/local чи відкритий доступ, довірені чи недовірені оператори). +1. Відтворення досі працює на останньому `main` або останньому релізі. +2. Звіт містить точний шлях у коді (`file`, function, line range) і протестовану версію/коміт. +3. Вплив перетинає задокументовану межу довіри, а не лише prompt injection. +4. Твердження не входить до списку [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). +5. Наявні advisory вже перевірено на дублікати (за потреби використовуйте канонічний GHSA повторно). +6. Припущення щодо розгортання явно вказані (loopback/local чи exposed, довірені чи недовірені оператори). ## Посилена базова конфігурація за 60 секунд -Спочатку використайте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для кожного довіреного агента: +Спочатку використовуйте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для довірених агентів: ```json5 { @@ -171,201 +171,213 @@ OpenClaw припускає, що хост і межа конфігурації ## Швидке правило для спільної скриньки вхідних -Якщо більше ніж одна людина може надсилати вашому боту DM: +Якщо більше ніж одна людина може надсилати DM вашому боту: -- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів з кількома обліковими записами). -- Залишайте `dmPolicy: "pairing"` або суворі allowlists. +- Встановіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для багатoакаунтних каналів). +- Залишайте `dmPolicy: "pairing"` або використовуйте суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює кооперативні/спільні скриньки вхідних, але не призначене для ворожої коорендної ізоляції, коли користувачі мають спільний доступ на запис до хоста/конфігурації. +- Це посилює захист для кооперативних/спільних вхідних, але не призначене для ворожої ізоляції співкористувачів, якщо вони мають спільний доступ на запис до хоста/конфігурації. ## Модель видимості контексту -OpenClaw розділяє дві концепції: +OpenClaw розділяє два поняття: -- **Авторизація тригера**: хто може активувати агента (`dmPolicy`, `groupPolicy`, allowlists, вимоги до згадки). -- **Видимість контексту**: який додатковий контекст додається до вхідних даних моделі (текст відповіді, цитований текст, історія гілки, метадані пересилання). +- **Авторизація запуску**: хто може активувати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги щодо згадки). +- **Видимість контексту**: який додатковий контекст інжектується у вхід моделі (тіло відповіді, процитований текст, історія треду, метадані пересилання). -Allowlists контролюють тригери та авторизацію команд. Налаштування `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, корені гілок, отримана історія): +Allowlists керують запуском і авторизацією команд. Налаштування `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, кореневі повідомлення треду, витягнута історія): -- `contextVisibility: "all"` (типово) зберігає додатковий контекст у тому вигляді, в якому його отримано. +- `contextVisibility: "all"` (типово) залишає додатковий контекст у тому вигляді, як він був отриманий. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну цитовану відповідь. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явно процитовану відповідь. -Установлюйте `contextVisibility` для кожного каналу або для кожної кімнати/розмови. Докладніше див. у [Групові чати](/uk/channels/groups#context-visibility). +Встановлюйте `contextVisibility` на рівні каналу або кімнати/розмови. Докладніше див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). Рекомендації для triage advisory: -- Твердження, які лише показують, що «модель може бачити цитований або історичний текст від відправників поза allowlist», є висновками щодо посилення безпеки, які можна усунути за допомогою `contextVisibility`, але самі по собі не є обходом меж автентифікації чи sandbox. -- Щоб мати вплив на безпеку, звіти все одно мають демонструвати обхід межі довіри (автентифікація, політика, sandbox, схвалення або інша документована межа). +- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників поза allowlist», є hardening-знахідками, які можна усунути через `contextVisibility`, але самі по собі не є обходом меж автентифікації чи sandbox. +- Щоб вважатися суттєвими для безпеки, звіти все одно мають демонструвати обхід межі довіри (автентифікація, політика, sandbox, схвалення або інша задокументована межа). ## Що перевіряє аудит (на високому рівні) -- **Вхідний доступ** (політики DM, групові політики, allowlists): чи можуть сторонні люди активувати бота? -- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може ін’єкція промпта перетворитися на дії оболонки/файлової системи/мережі? -- **Дрейф схвалення exec** (`security=full`, `autoAllowSkills`, allowlists інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec усе ще працюють так, як ви очікуєте? - - `security="full"` — це широке попередження про позицію безпеки, а не доказ помилки. Це обраний варіант за замовчуванням для довірених конфігурацій персонального помічника; посилюйте його лише тоді, коли ваша модель загроз потребує схвалення або запобіжників allowlist. -- **Викриття мережі** (bind/auth шлюзу, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). -- **Викриття керування браузером** (віддалені node, relay-порти, віддалені кінцеві точки CDP). -- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «синхронізованих папок»). +- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні користувачі активувати бота? +- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії в оболонці/файловій системі/мережі? +- **Зсув схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи й далі запобіжники host-exec працюють так, як ви очікуєте? + - `security="full"` — це широке попередження про рівень ризику, а не доказ помилки. Це свідомо обраний типовий режим для довірених конфігурацій персонального асистента; посилюйте його лише тоді, коли ваша модель загроз вимагає схвалення або запобіжників allowlist. +- **Відкритість мережі** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). +- **Відкритість керування браузером** (віддалені nodes, relay-порти, віддалені CDP endpoints). +- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «synced folder»). - **Plugins** (розширення існують без явного allowlist). -- **Дрейф політик/неправильна конфігурація** (налаштування sandbox docker задані, але режим sandbox вимкнено; неефективні шаблони `gateway.nodes.denyCommands`, оскільки зіставлення відбувається лише за точною назвою команди (наприклад, `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями на рівні агента; інструменти extension plugin доступні за поблажливої політики інструментів). -- **Дрейф очікувань від runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, коли `tools.exec.host` тепер за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). -- **Гігієна моделей** (попередження, якщо налаштовані моделі виглядають застарілими; не є жорстким блокуванням). +- **Зсув політик/помилки конфігурації** (налаштовано sandbox docker settings, але режим sandbox вимкнений; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди (наприклад, `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями на рівні агента; інструменти extension plugin доступні через поблажливу політику інструментів). +- **Зсув очікувань runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, хоча `tools.exec.host` тепер типово має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). +- **Гігієна моделей** (попереджає, якщо налаштовані моделі виглядають застарілими; це не жорстке блокування). -Якщо ви запускаєте `--deep`, OpenClaw також виконує best-effort live-пробу Gateway. +Якщо ви запускаєте `--deep`, OpenClaw також виконує best-effort live probe Gateway. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або вирішення, що саме резервно копіювати: +Використовуйте це під час аудиту доступу або коли вирішуєте, що саме резервно копіювати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Токен Telegram bot**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) -- **Токен Discord bot**: config/env або SecretRef (провайдери env/file/exec) -- **Токени Slack**: config/env (`channels.slack.*`) -- **Allowlists для pairing**: - - `~/.openclaw/credentials/-allowFrom.json` (обліковий запис за замовчуванням) - - `~/.openclaw/credentials/--allowFrom.json` (облікові записи не за замовчуванням) +- **Telegram bot token**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) +- **Discord bot token**: config/env або SecretRef (провайдери env/file/exec) +- **Slack tokens**: config/env (`channels.slack.*`) +- **Pairing allowlist**: + - `~/.openclaw/credentials/-allowFrom.json` (типовий акаунт) + - `~/.openclaw/credentials/--allowFrom.json` (нетипові акаунти) - **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Payload секретів із файловим бекендом (необов’язково)**: `~/.openclaw/secrets.json` +- **Payload секретів на основі файлу (необов’язково)**: `~/.openclaw/secrets.json` - **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить результати, сприймайте це в такому порядку пріоритету: +Коли аудит виводить результати, сприймайте це як порядок пріоритетів: -1. **Усе, що є “open”, коли інструменти увімкнені**: спочатку обмежте DM/групи (pairing/allowlists), потім посильте політику інструментів/sandboxing. -2. **Відкриття у публічну мережу** (bind у LAN, Funnel, відсутня автентифікація): виправляйте негайно. -3. **Віддалене викриття керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, свідомо pairing node, уникайте публічного відкриття). -4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні для читання групі або всім. +1. **Будь-що “open” + увімкнені інструменти**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. +2. **Публічна мережева відкритість** (bind у LAN, Funnel, відсутня автентифікація): виправляйте негайно. +3. **Віддалена відкритість керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, pairing nodes навмисно, уникайте публічної відкритості). +4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні на читання групі або всім. 5. **Plugins/extensions**: завантажуйте лише те, чому явно довіряєте. -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/політику інструментів/конфігурацію | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | -| `fs.config.symlink` | warn | Ціль конфігураційного файла стає іншою межею довіри | схема файлової системи конфігураційного файла | ні | -| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/параметри конфігурації | дозволи файлової системи для конфігураційного файла | так | -| `fs.config.perms_world_readable` | critical | Конфігурація може розкрити токени/параметри | дозволи файлової системи для конфігураційного файла | так | -| `fs.config_include.perms_writable` | critical | Файл include конфігурації можуть змінювати інші | дозволи для 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 | Інші можуть читати журнали, де дані редаговано, але які все одно лишаються чутливими | дозволи для файла журналу gateway | так | -| `fs.synced_dir` | warn | Стан/конфігурація в iCloud/Dropbox/Drive розширює ризик викриття токенів/транскриптів | перемістіть конфігурацію/стан поза межі синхронізованих папок | ні | -| `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 присутні, але не позначені як довірені | `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` може дозволити підміну source IP через помилкову конфігурацію proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | -| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати brute force | `gateway.auth.token` | ні | -| `gateway.auth_no_rate_limit` | warn | Відкрита auth без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні | -| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | ні | -| `gateway.trusted_proxy_no_proxies` | critical | Автентифікація trusted-proxy без IP-адрес довірених proxy є небезпечною | `gateway.trustedProxies` | ні | -| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | -| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | -| `gateway.probe_auth_secretref_unavailable` | warn | Поглиблена проба не змогла розв’язати auth SecretRef у цьому шляху команди | джерело auth для deep-probe / доступність SecretRef | ні | -| `gateway.probe_failed` | warn/critical | Live-проба Gateway завершилася помилкою | досяжність/автентифікація gateway | ні | -| `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | -| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні/небезпечні debug-прапорці | кілька ключів (див. деталі результату) | ні | -| `config.secrets.gateway_password_in_config` | warn | Пароль gateway зберігається безпосередньо в конфігурації | `gateway.auth.password` | ні | -| `config.secrets.hooks_token_in_config` | warn | Bearer-токен hook зберігається безпосередньо в конфігурації | `hooks.token` | ні | -| `hooks.token_reuse_gateway_token` | critical | Токен входу hook також відкриває auth gateway | `hooks.token`, `gateway.auth.token` | ні | -| `hooks.token_too_short` | warn | Простіший brute force для входу hook | `hooks.token` | ні | -| `hooks.default_session_key_unset` | warn | Агент hook запускає fan out у згенеровані сесії для кожного запиту | `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 бракує метаданих integrity | метадані встановлення hook | ні | -| `hooks.installs_version_drift` | warn | Записи встановлення hook розходяться з установленими пакетами | метадані встановлення hook | ні | -| `logging.redact_off` | warn | Чутливі значення потрапляють у журнали/status | `logging.redactSensitive` | так | -| `browser.control_invalid_config` | warn | Конфігурація керування браузером недійсна до запуску runtime | `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 socket | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_network_mode` | critical | Мережа Sandbox Docker використовує режим `host` або `container:*` із приєднанням до namespace | `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 | Browser bridge у sandbox відкрито без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | -| `sandbox.browser_container.non_loopback_publish` | critical | Наявний контейнер браузера публікує CDP на інтерфейсах поза loopback | конфігурація публікації контейнера browser sandbox | ні | -| `sandbox.browser_container.hash_label_missing` | warn | Наявний контейнер браузера створено до поточних міток config-hash | `openclaw sandbox recreate --browser --all` | ні | -| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний контейнер браузера створено до поточної епохи конфігурації браузера | `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 неявно довіряють skill bins | `~/.openclaw/exec-approvals.json` | ні | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlists інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist схвалень exec | ні | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Біни інтерпретаторів/runtime у `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) | стан файлової системи `skills/**` у workspace | ні | -| `plugins.extensions_no_allowlist` | warn | Extensions встановлено без явного allowlist plugin | `plugins.allowlist` | ні | -| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення plugin не прив’язані до незмінних специфікацій npm | метадані встановлення plugin | ні | -| `plugins.installs_missing_integrity` | warn | У записах встановлення plugin бракує метаданих integrity | метадані встановлення 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 не вдалося завершити | шлях extension plugin / середовище сканування | ні | -| `skills.code_safety` | warn/critical | Метадані/код інсталятора Skills містять підозрілі або небезпечні шаблони | джерело встановлення skill | ні | -| `skills.code_safety.scan_failed` | warn | Сканування коду Skills не вдалося завершити | середовище сканування 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 | Відкриті групи + підвищені інструменти створюють шляхи ін’єкції промпта з високим впливом | `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 | Конфігурація виглядає багатокористувацькою, тоді як модель довіри gateway — персональний помічник | розділіть межі довіри або посильте спільне використання (`sandbox.mode`, deny для інструментів/scoping workspace) | ні | -| `tools.profile_minimal_overridden` | warn | Перевизначення агента обходять глобальний мінімальний профіль | `agents.list[].tools.profile` | ні | -| `plugins.tools_reachable_permissive_policy` | warn | Інструменти extension доступні в поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | -| `models.legacy` | warn | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | -| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточно рекомендовані рівні | вибір моделі | ні | -| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + політика sandbox/інструментів | ні | -| `summary.attack_surface` | info | Зведений підсумок стану auth, каналів, інструментів і відкритих поверхонь | кілька ключів (див. деталі результату) | ні | +| `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/tool/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | +| `fs.config.symlink` | warn | Ціль файлу конфігурації стає іншою межею довіри | схема файлової системи файлу конфігурації | ні | +| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування з конфігурації | дозволи файлової системи для файлу конфігурації | так | +| `fs.config.perms_world_readable` | critical | Конфігурація може розкривати токени/налаштування | дозволи файлової системи для файлу конфігурації | так | +| `fs.config_include.perms_writable` | critical | Include-файл конфігурації може бути змінений іншими | дозволи 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 | Інші можуть читати журнали, що хоч і редаговані, але все ще містять чутливі дані | дозволи для файла журналу gateway | так | +| `fs.synced_dir` | warn | Стан/конфігурація в iCloud/Dropbox/Drive розширюють доступ до токенів/транскриптів | перемістіть конфігурацію/стан поза межі синхронізованих папок | ні | +| `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-header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | +| `gateway.control_ui.insecure_auth` | warn | Увімкнено compatibility toggle для небезпечної автентифікації | `gateway.controlUi.allowInsecureAuth` | ні | +| `gateway.control_ui.device_auth_disabled` | critical | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | +| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підміну source IP через помилку proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | +| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | +| `gateway.auth_no_rate_limit` | warn | Відкрита автентифікація без rate limiting підвищує ризик brute force | `gateway.auth.rateLimit` | ні | +| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | ні | +| `gateway.trusted_proxy_no_proxies` | critical | Автентифікація trusted-proxy без IP довірених proxy є небезпечною | `gateway.trustedProxies` | ні | +| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | +| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача зверху | `gateway.auth.trustedProxy.allowUsers` | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------- | +| `gateway.probe_auth_secretref_unavailable` | warn | Deep probe не зміг визначити auth SecretRef у цьому шляху виконання команди | джерело auth для deep probe / доступність SecretRef | ні | +| `gateway.probe_failed` | warn/critical | Live probe Gateway завершився невдачею | доступність gateway / auth | ні | +| `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | +| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні/ризиковані debug-прапорці | кілька ключів (див. деталі у finding) | ні | +| `config.secrets.gateway_password_in_config` | warn | Пароль Gateway зберігається безпосередньо в конфігурації | `gateway.auth.password` | ні | +| `config.secrets.hooks_token_in_config` | warn | Bearer-токен hooks зберігається безпосередньо в конфігурації | `hooks.token` | ні | +| `hooks.token_reuse_gateway_token` | critical | Токен входу hooks також відкриває auth Gateway | `hooks.token`, `gateway.auth.token` | ні | +| `hooks.token_too_short` | warn | Полегшує brute force для входу hooks | `hooks.token` | ні | +| `hooks.default_session_key_unset` | warn | Агент hooks виконує fan out у згенеровані сесії для кожного запиту | `hooks.defaultSessionKey` | ні | +| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані виклики hooks можуть маршрутизуватися до будь-якого налаштованого агента | `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 | Шлях hooks дорівнює `/`, що спрощує колізії або помилкову маршрутизацію входу | `hooks.path` | ні | +| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлення hooks не закріплені за незмінними npm-специфікаціями | метадані встановлення hook | ні | +| `hooks.installs_missing_integrity` | warn | У записах встановлення hooks відсутні метадані integrity | метадані встановлення hook | ні | +| `hooks.installs_version_drift` | warn | Записи встановлення hooks розходяться з установленими пакетами | метадані встановлення hook | ні | +| `logging.redact_off` | warn | Чутливі значення потрапляють у журнали/статус | `logging.redactSensitive` | так | +| `browser.control_invalid_config` | warn | Конфігурація керування браузером некоректна ще до runtime | `browser.*` | ні | +| `browser.control_no_auth` | critical | Керування браузером відкрите без auth через токен/пароль | `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 | Конфігурація Docker sandbox присутня, але неактивна | `agents.*.sandbox.mode` | ні | +| `sandbox.bind_mount_non_absolute` | warn | Відносні bind mount можуть розв’язуватися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_bind_mount` | critical | Bind mount у sandbox спрямовано на заблоковані системні шляхи, шляхи облікових даних або Docker socket | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_network_mode` | critical | Мережа Docker sandbox використовує `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 | Міст CDP браузера в sandbox відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | +| `sandbox.browser_container.non_loopback_publish` | critical | Наявний контейнер браузера публікує CDP на інтерфейсах, відмінних від loopback | конфігурація публікації контейнера браузера sandbox | ні | +| `sandbox.browser_container.hash_label_missing` | warn | Наявний контейнер браузера створено до поточних міток хеша конфігурації | `openclaw sandbox recreate --browser --all` | ні | +| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний контейнер браузера створено до поточної епохи конфігурації браузера | `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 неявно довіряють skill bins | `~/.openclaw/exec-approvals.json` | ні | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlists інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist схвалень exec | ні | +| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Бінарники інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | +| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти широкої поведінки в `safeBins` послаблюють модель довіри з низьким ризиком для stdin-фільтра | `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) | стан файлової системи `skills/**` у workspace | ні | +| `plugins.extensions_no_allowlist` | warn | Extensions встановлені без явного allowlist plugins | `plugins.allowlist` | ні | +| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення plugins не закріплені за незмінними npm-специфікаціями | метадані встановлення plugin | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------- | +| `plugins.installs_missing_integrity` | warn | У записах встановлення plugin відсутні метадані integrity | метадані встановлення 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 не вдалося завершити | шлях extension plugin / середовище сканування | ні | +| `skills.code_safety` | warn/critical | Метадані інсталятора/code для 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 | Конфігурація виглядає багатокористувацькою, хоча модель довіри gateway — персональний асистент | розділіть межі довіри або посильте спільний доступ (`sandbox.mode`, deny інструментів / обмеження workspace) | ні | +| `tools.profile_minimal_overridden` | warn | Перевизначення на рівні агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | +| `plugins.tools_reachable_permissive_policy` | warn | Інструменти extension доступні в поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | +| `models.legacy` | warn | Досі налаштовані застарілі сімейства моделей | вибір моделі | ні | +| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточно рекомендовані рівні | вибір моделі | ні | +| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + sandbox/політика інструментів | ні | +| `summary.attack_surface` | info | Зведений підсумок про стан auth, каналів, інструментів і рівень відкритості | кілька ключів (див. деталі у finding) | ні | ## Control UI через HTTP -Control UI потребує **безпечного контексту** (HTTPS або localhost) для генерації ідентичності пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: +Для створення ідентичності пристрою Control UI потребує **безпечного контексту** (HTTPS або localhost). +`gateway.controlUi.allowInsecureAuth` — це локальний compatibility toggle: -- На localhost він дозволяє auth для Control UI без ідентичності пристрою, коли сторінку завантажено через незахищений HTTP. +- На localhost він дозволяє автентифікацію Control UI без ідентичності пристрою, якщо сторінку завантажено через небезпечний HTTP. - Він не обходить перевірки pairing. - Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень. Надавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. -Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; тримайте його вимкненим, якщо тільки ви не виконуєте активне налагодження й не можете швидко відкотити зміну. +Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` +повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; +тримайте цей параметр вимкненим, якщо тільки ви не займаєтеся активним налагодженням і не можете швидко все повернути назад. -Окремо від цих небезпечних прапорців, успішний `gateway.auth.mode: "trusted-proxy"` може допускати **операторські** сесії Control UI без ідентичності пристрою. Це навмисна поведінка режиму auth, а не обхід через `allowInsecureAuth`, і вона все одно не поширюється на сесії Control UI з роллю node. +Окремо від цих небезпечних прапорців, успішний режим `gateway.auth.mode: "trusted-proxy"` +може допускати **операторські** сесії Control UI без ідентичності пристрою. Це +свідома поведінка режиму auth, а не скорочений шлях через `allowInsecureAuth`, і вона +все одно не поширюється на сесії Control UI з роллю node. `openclaw security audit` попереджає, коли цей параметр увімкнено. -## Підсумок небезпечних або незахищених прапорців +## Підсумок небезпечних або ризикованих прапорців -`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли увімкнено відомі незахищені/небезпечні debug-перемикачі. Наразі ця перевірка агрегує: +`openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли +відомі небезпечні/ризиковані debug-перемикачі увімкнені. Наразі ця перевірка +агрегує: - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` @@ -375,7 +387,7 @@ Control UI потребує **безпечного контексту** (HTTPS - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` -Повний список ключів конфігурації `dangerous*` / `dangerously*`, визначених у схемі конфігурації OpenClaw: +Повний перелік ключів конфігурації `dangerous*` / `dangerously*`, визначених у schema конфігурації OpenClaw: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` @@ -408,21 +420,21 @@ Control UI потребує **безпечного контексту** (HTTPS ## Конфігурація reverse proxy Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для коректної обробки IP-адрес клієнтів через forwarded headers. +`gateway.trustedProxies` для коректної обробки пересланої IP-адреси клієнта. -Коли Gateway виявляє proxy-заголовки з адреси, якої **немає** в `trustedProxies`, він **не** вважатиме з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання буде відхилено. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше виглядали б як такі, що надходять із localhost, і автоматично отримували б довіру. +Коли Gateway виявляє заголовки proxy від адреси, якої **немає** у `trustedProxies`, він **не** вважатиме підключення локальними клієнтами. Якщо auth gateway вимкнено, такі підключення буде відхилено. Це запобігає обходу автентифікації, коли проксійовані підключення інакше могли б виглядати як такі, що походять із localhost, і отримували б автоматичну довіру. `gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: -- auth trusted-proxy **завершується безпечною відмовою для proxy із джерелом loopback** -- reverse proxy loopback на тому самому хості все ще можуть використовувати `gateway.trustedProxies` для визначення локального клієнта та обробки forwarded IP -- для reverse proxy loopback на тому самому хості використовуйте auth за token/password замість `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"` ```yaml gateway: trustedProxies: - "10.0.0.1" # IP reverse proxy - # Необов’язково. Типово false. + # Необов’язково. Типове значення false. # Вмикайте лише якщо ваш proxy не може надавати X-Forwarded-For. allowRealIpFallback: false auth: @@ -430,16 +442,16 @@ gateway: 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 headers): +Правильна поведінка reverse proxy (перезапис вхідних заголовків пересилання): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Некоректна поведінка reverse proxy (додавання/збереження недовірених forwarding headers): +Неправильна поведінка reverse proxy (додавання/збереження недовірених заголовків пересилання): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -447,54 +459,54 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ## Примітки щодо HSTS і origin -- Шлюз OpenClaw орієнтований насамперед на local/loopback. Якщо ви завершуєте TLS на reverse proxy, встановлюйте HSTS там, на HTTPS-домені, який бачить proxy. +- Шлюз OpenClaw спочатку орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштовуйте HSTS там, на HTTPS-домені, який бачить proxy. - Якщо HTTPS завершує сам gateway, ви можете встановити `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: ["*"]` — це явна політика browser-origin «дозволити все», а не посилене налаштування за замовчуванням. Уникайте цього поза межами жорстко контрольованого локального тестування. -- Збої auth за browser-origin на 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 «дозволити все», а не посилене типове налаштування. Уникайте її поза межами жорстко контрольованого локального тестування. +- Збої браузерної автентифікації за origin на loopback усе одно обмежуються rate limiting навіть тоді, коли ввімкнено загальний виняток для loopback, але ключ блокування прив’язується до кожного нормалізованого значення `Origin`, а не до одного спільного бакета localhost. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin через Host-header; розглядайте це як небезпечну політику, свідомо обрану оператором. +- Розглядайте DNS rebinding і поведінку proxy щодо Host-header як питання посилення безпеки розгортання; тримайте `trustedProxies` максимально вузьким і не відкривайте gateway напряму в публічний інтернет. ## Локальні журнали сесій зберігаються на диску OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сесій і (за бажанням) індексації пам’яті сесій, але це також означає, що -**будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска -межею довіри й обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +Це потрібно для безперервності сесій і (за бажанням) індексації пам’яті сесій, але це також означає, +що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска +межею довіри й жорстко обмежуйте дозволи на `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. ## Виконання на node (`system.run`) -Якщо node macOS спарено, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: +Якщо macOS node paired, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: -- Потребує pairing node (схвалення + токен). -- 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. -- Режим схвалення прив’язується до точного контексту запиту і, коли можливо, до одного конкретного локального операнда скрипта/файла. Якщо OpenClaw не може точно визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання з підтримкою схвалення буде відхилено, замість обіцянки повного семантичного покриття. -- Для `host=node` виконання з підтримкою схвалення також зберігає канонічний підготовлений `systemRunPlan`; пізніші схвалені пересилання повторно використовують цей збережений план, а валідація gateway відхиляє редагування команд/cwd/контексту сесії викликаючим клієнтом після створення запиту на схвалення. -- Якщо ви не хочете віддаленого виконання, установіть security у **deny** і видаліть pairing node для цього Mac. +- Керування на Mac виконується через **Settings → Exec approvals** (security + ask + allowlist). +- Політика `system.run` для кожного node — це власний файл схвалень exec цього node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ідентифікаторів команд gateway. +- Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не вимагає суворішого режиму схвалення або allowlist. +- Режим схвалення прив’язується до точного контексту запиту та, коли це можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання на основі схвалення буде відхилене, а не вдаватиме повне семантичне покриття. +- Для `host=node` виконання на основі схвалення також зберігає канонічний підготовлений `systemRunPlan`; подальші схвалені переспрямування повторно використовують цей збережений план, а валідація gateway відхиляє зміни викликача до command/cwd/session context після створення запиту на схвалення. +- Якщо вам не потрібне віддалене виконання, встановіть security у **deny** і видаліть pairing node для цього Mac. Це розрізнення важливе для triage: -- Повторне підключення спареного node, який рекламує інший список команд, саме по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec на node все ще забезпечують фактичну межу виконання. -- Звіти, які трактують метадані pairing node як другий прихований рівень схвалення для кожної команди, зазвичай є плутаниною щодо політики/UX, а не обходом межі безпеки. +- Якщо paired node після повторного підключення оголошує інший список команд, це саме по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec на node усе ще забезпечують фактичну межу виконання. +- Звіти, які трактують метадані pairing node як другий прихований шар схвалення кожної команди, зазвичай є плутаниною навколо політики/UX, а не обходом межі безпеки. -## Динамічні Skills (watcher / віддалені node) +## Динамічні Skills (watcher / віддалені nodes) -OpenClaw може оновлювати список Skills у середині сесії: +OpenClaw може оновлювати список Skills посеред сесії: -- **Skills watcher**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході агента. -- **Віддалені node**: підключення node macOS може зробити Skills лише для macOS придатними до використання (на основі перевірки bin). +- **Watcher Skills**: зміни у `SKILL.md` можуть оновити знімок Skills на наступному ході агента. +- **Віддалені nodes**: підключення macOS node може зробити доступними Skills лише для macOS (на основі перевірки bin). -Розглядайте каталоги skill як **довірений код** і обмежуйте, хто може їх змінювати. +Розглядайте папки skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. ## Модель загроз -Ваш AI-помічник може: +Ваш AI-асистент може: - Виконувати довільні команди оболонки - Читати/записувати файли @@ -503,42 +515,42 @@ OpenClaw може оновлювати список Skills у середині Люди, які надсилають вам повідомлення, можуть: -- Намагатися обдурити ваш AI, щоб він зробив щось шкідливе -- Соціально інженерити доступ до ваших даних -- Зондувати деталі інфраструктури +- Намагатися обдурити ваш AI, щоб він робив шкідливі речі +- Соціальною інженерією здобувати доступ до ваших даних +- Досліджувати вашу інфраструктуру на предмет деталей -## Основна ідея: контроль доступу перед інтелектом +## Основна концепція: контроль доступу перед інтелектом -Більшість збоїв тут — не витончені експлойти, а ситуації на кшталт «хтось написав боту, і бот зробив те, що його попросили». +Більшість збоїв тут — це не хитромудрі експлойти, а радше «хтось написав боту, і бот зробив те, що його попросили». Позиція OpenClaw: -- **Спочатку ідентичність:** визначте, хто може звертатися до бота (pairing DM / allowlists / явний режим “open”). -- **Потім межі:** визначте, де боту дозволено діяти (group allowlists + вимога згадки, інструменти, sandboxing, дозволи пристрою). -- **Модель в останню чергу:** припускайте, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляцій мали обмежений радіус ураження. +- **Спочатку ідентичність:** визначте, хто може взаємодіяти з ботом (pairing DM / allowlist / явний режим “open”). +- **Потім обсяг:** визначте, де бот має право діяти (allowlist груп + вимога згадки, інструменти, sandboxing, дозволи пристрою). +- **І лише потім модель:** виходьте з того, що моделлю можна маніпулювати; будуйте систему так, щоб маніпуляції мали обмежений радіус ураження. ## Модель авторизації команд -Слеш-команди та директиви обробляються лише для **авторизованих відправників**. Авторизація визначається через -allowlists/pairing каналів плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) +Slash commands і directives виконуються лише для **авторизованих відправників**. Авторизація визначається через +allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, команди фактично відкриті для цього каналу. -`/exec` — це зручний інструмент лише для сесії й лише для авторизованих операторів. Він **не** записує конфігурацію і +`/exec` — це зручна команда лише для сесії, призначена для авторизованих операторів. Вона **не** записує конфігурацію і не змінює інші сесії. -## Ризик інструментів control plane +## Ризики інструментів control plane -Два вбудовані інструменти можуть вносити стійкі зміни до control plane: +Два вбудовані інструменти можуть вносити постійні зміни в control plane: -- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get` і може вносити постійні зміни через `config.apply`, `config.patch` та `update.run`. +- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. - `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. -Інструмент runtime `gateway`, доступний лише власнику, все одно відмовляється переписувати +Інструмент runtime `gateway`, доступний лише власнику, усе одно відмовляється переписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого агента/поверхні, що обробляє недовірений вміст, за замовчуванням забороняйте це: +Для будь-якого агента/поверхні, що обробляє недовірений вміст, за замовчуванням забороняйте таке: ```json5 { @@ -548,33 +560,35 @@ allowlists/pairing каналів плюс `commands.useAccessGroups` (див. [ } ``` -`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії `gateway` з конфігурацією/оновленням. +`commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії конфігурації/оновлення `gateway`. ## Plugins/extensions -Plugins виконуються **у тому самому процесі**, що й Gateway. Розглядайте їх як довірений код: +Plugins працюють **у тому самому процесі**, що й Gateway. Розглядайте їх як довірений код: -- Установлюйте plugins лише з джерел, яким ви довіряєте. -- Надавайте перевагу явним allowlists `plugins.allow`. -- Переглядайте конфігурацію plugin перед увімкненням. -- Перезапускайте Gateway після змін plugin. +- Встановлюйте plugins лише з джерел, яким довіряєте. +- Надавайте перевагу явним allowlist `plugins.allow`. +- Перевіряйте конфігурацію plugin перед увімкненням. +- Перезапускайте Gateway після змін plugins. - Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: - - Шлях установлення — це каталог кожного plugin у межах активного кореня встановлення plugin. - - Перед установленням/оновленням OpenClaw запускає вбудоване сканування небезпечного коду. Знахідки рівня `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: вбудовані знахідки `critical` блокують операцію, якщо викликаючий клієнт явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі знахідки лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення skills через ClawHub. + - Шлях встановлення — це каталог конкретного plugin у межах активного кореня встановлення plugins. + - Перед встановленням/оновленням OpenClaw запускає вбудоване сканування на небезпечний код. Знахідки рівня `critical` типово блокують процес. + - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (npm lifecycle scripts можуть виконувати код під час встановлення). + - Надавайте перевагу закріпленим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` — лише аварійний варіант для хибнопозитивних спрацювань вбудованого сканування під час потоків встановлення/оновлення plugin. Він не обходить блокування політики hook `before_install` для plugin і не обходить збої сканування. + - Встановлення залежностей Skills через Gateway дотримується такого самого поділу між dangerous і suspicious: вбудовані знахідки `critical` блокують процес, якщо тільки викликаючий явно не встановить `dangerouslyForceUnsafeInstall`, тоді як suspicious-знахідки й надалі лише попереджають. `openclaw skills install` і надалі залишається окремим потоком завантаження/встановлення skill через ClawHub. Докладніше: [Plugins](/uk/tools/plugin) + + ## Модель доступу через DM (pairing / allowlist / open / disabled) -Усі поточні канали, що підтримують DM, мають політику DM (`dmPolicy` або `*.dm.policy`), яка контролює вхідні DM **до** обробки повідомлення: +Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка контролює вхідні DM **до** обробки повідомлення: -- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість очікуваних запитів за замовчуванням обмежена **3 на канал**. -- `allowlist`: невідомі відправники блокуються (без handshake pairing). -- `open`: дозволити будь-кому надсилати DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явне підтвердження). +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість очікувальних запитів типово обмежена до **3 на канал**. +- `allowlist`: невідомих відправників блокують (без handshake pairing). +- `open`: дозволити будь-кому надсилати DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явна згода). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -588,7 +602,7 @@ openclaw pairing approve ## Ізоляція DM-сесій (багатокористувацький режим) -За замовчуванням OpenClaw спрямовує **усі DM до основної сесії**, щоб ваш помічник зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist із кількома людьми), розгляньте ізоляцію DM-сесій: +Типово OpenClaw маршрутизує **всі DM до основної сесії**, щоб ваш асистент зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist із кількома людьми), розгляньте ізоляцію DM-сесій: ```json5 { @@ -596,63 +610,63 @@ openclaw pairing approve } ``` -Це запобігає витоку контексту між користувачами, зберігаючи ізоляцію групових чатів. +Це запобігає витоку контексту між користувачами, зберігаючи водночас ізоляцію групових чатів. -Це межа контексту повідомлень, а не межа адміністрування хоста. Якщо користувачі є взаємно зловмисними й мають спільний хост/конфігурацію Gateway, запускайте окремі шлюзи для кожної межі довіри. +Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі є взаємно ворожими й ділять той самий хост/config Gateway, запускайте окремі шлюзи для кожної межі довіри. ### Безпечний режим DM (рекомендовано) Розглядайте наведений вище фрагмент як **безпечний режим DM**: -- Типово: `session.dmScope: "main"` (усі DM використовують одну сесію для безперервності). -- Типове значення під час локального онбордингу CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (зберігає наявні явні значення). -- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований DM-контекст). -- Ізоляція контакту між каналами: `session.dmScope: "per-peer"` (кожен відправник має одну сесію в усіх каналах одного типу). +- Типове значення: `session.dmScope: "main"` (усі DM ділять одну сесію для безперервності). +- Типове значення для локального CLI-онбордингу: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (зберігає наявні явні значення). +- Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). +- Ізоляція відправника між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). -Якщо ви використовуєте кілька облікових записів в одному каналі, замість цього використовуйте `per-account-channel-peer`. Якщо та сама людина звертається до вас через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Керування сесіями](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). +Якщо ви запускаєте кілька акаунтів в одному каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина звертається до вас через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Керування сесіями](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). ## Allowlists (DM + групи) - термінологія OpenClaw має два окремі шари «хто може мене активувати?»: -- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право звертатися до бота в особистих повідомленнях. - - Коли `dmPolicy="pairing"`, схвалення записуються до сховища pairing allowlist з областю дії на обліковий запис у `~/.openclaw/credentials/` (`-allowFrom.json` для типового облікового запису, `--allowFrom.json` для нетипових облікових записів), а потім об’єднуються з allowlists у конфігурації. -- **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`: allowlists для кожної поверхні + типові значення для згадок. - - Групові перевірки виконуються в такому порядку: спочатку `groupPolicy`/group allowlists, потім активація через згадку/відповідь. - - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlists відправника, такі як `groupAllowFrom`. - - **Примітка щодо безпеки:** ставтеся до `dmPolicy="open"` і `groupPolicy="open"` як до налаштувань останньої надії. Їх слід використовувати вкрай рідко; надавайте перевагу pairing + allowlists, якщо ви не довіряєте повністю кожному учаснику кімнати. +- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право спілкуватися з ботом у direct messages. + - Коли `dmPolicy="pairing"`, схвалення записуються в сховище pairing allowlist, прив’язане до акаунта, у `~/.openclaw/credentials/` (`-allowFrom.json` для типового акаунта, `--allowFrom.json` для нетипових акаунтів), і об’єднуються з allowlist із конфігурації. +- **Group allowlist** (залежить від каналу): з яких саме груп/каналів/guilds бот взагалі прийматиме повідомлення. + - Типові шаблони: + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові налаштування на рівні групи, наприклад `requireMention`; якщо встановлено, це також працює як group allowlist (включіть `"*"`, щоб зберегти поведінку «дозволити все»). + - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може активувати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: allowlist на рівні поверхонь + типові налаштування згадок. + - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/group allowlist, потім активація через згадку/відповідь. + - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправника, наприклад `groupAllowFrom`. + - **Примітка з безпеки:** розглядайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування останньої інстанції. Їх слід використовувати вкрай рідко; надавайте перевагу pairing + allowlists, якщо тільки ви не довіряєте повністю кожному учаснику кімнати. Докладніше: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) -## Ін’єкція промптів (що це, чому це важливо) +## Prompt injection (що це таке і чому це важливо) -Ін’єкція промптів — це коли атакувальник створює повідомлення, яке маніпулює моделлю, змушуючи її зробити щось небезпечне («ігноруй свої інструкції», «вивантаж файлову систему», «перейди за цим посиланням і запусти команди» тощо). +Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «вивантаж свою файлову систему», «перейди за цим посиланням і виконай команди» тощо). -Навіть за сильних системних промптів **проблему ін’єкції промптів не вирішено**. Запобіжники в системному промпті — це лише м’які рекомендації; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlists каналів (і оператори можуть навмисно їх вимкнути). Що реально допомагає на практиці: +Навіть із сильними system prompt **проблема prompt injection не вирішена**. Запобіжники в system prompt — це лише м’які рекомендації; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlist каналів (і оператори можуть за задумом усе це вимкнути). Що реально допомагає на практиці: - Тримайте вхідні DM закритими (pairing/allowlists). -- У групах віддавайте перевагу активації через згадку; уникайте ботів, які «завжди слухають» у публічних кімнатах. -- За замовчуванням вважайте посилання, вкладення та вставлені інструкції ворожими. -- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза файловою системою, до якої агент може дістатися. -- Примітка: sandboxing є opt-in. Якщо режим sandbox вимкнено, неявне `host=auto` розв’язується до хоста gateway. Явне `host=sandbox` усе одно безпечно завершується відмовою, оскільки runtime sandbox недоступний. Установіть `host=gateway`, якщо хочете, щоб ця поведінка була явно відображена в конфігурації. -- Обмежуйте високоризикові інструменти (`exec`, `browser`, `web_fetch`, `web_search`) довіреними агентами або явними allowlists. -- Якщо ви створюєте allowlist для інтерпретаторів (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб форми inline eval усе одно вимагали явного схвалення. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до ін’єкції промптів і зловживання інструментами. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. +- У групах надавайте перевагу активації через згадки; уникайте «завжди активних» ботів у публічних кімнатах. +- Розглядайте посилання, вкладення та вставлені інструкції як потенційно ворожі за замовчуванням. +- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза досяжною для агента файловою системою. +- Примітка: sandboxing є opt-in. Якщо режим 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 і зроби точно те, що там написано». +- «Ігноруй свій system prompt або правила безпеки». +- «Розкрий свої приховані інструкції або результати інструментів». +- «Встав повний вміст `~/.openclaw` або свої журнали». ## Прапорці обходу небезпечного зовнішнього вмісту -OpenClaw містить явні прапорці обходу, які вимикають безпечне обгортання зовнішнього вмісту: +OpenClaw містить явні прапорці обходу, які вимикають обгортання безпеки для зовнішнього вмісту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` @@ -660,121 +674,120 @@ OpenClaw містить явні прапорці обходу, які вими Рекомендації: -- У production залишайте їх unset/false. -- Вмикайте лише тимчасово для вузькоспрямованого налагодження. -- Якщо увімкнено, ізолюйте цього агента (sandbox + мінімум інструментів + окремий простір імен сесій). +- У production тримайте ці параметри не встановленими/`false`. +- Вмикайте лише тимчасово для вузько обмеженого налагодження. +- Якщо ввімкнено, ізолюйте такого агента (sandbox + мінімум інструментів + окремий простір імен сесії). -Примітка щодо ризику hooks: +Примітка про ризики hooks: -- Payload hooks — це недовірений вміст, навіть якщо доставка надходить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити ін’єкцію промптів). -- Слабкі рівні моделей підвищують цей ризик. Для автоматизації на основі hooks надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing, де це можливо. +- Payload hooks — це недовірений вміст, навіть якщо доставка надходить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити prompt injection). +- Слабкі рівні моделей підвищують цей ризик. Для автоматизації, що запускається через hooks, надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing, де це можливо. -### Ін’єкція промптів не потребує публічних DM +### Prompt injection не потребує публічних DM -Навіть якщо **лише ви** можете писати боту, ін’єкція промптів усе одно може трапитися через -будь-який **недовірений вміст**, який читає бот (результати web search/fetch, сторінки браузера, -листи, документи, вкладення, вставлені журнали/код). Іншими словами: відправник — не єдина поверхня загрози; -**сам вміст** також може нести ворожі інструкції. +Навіть якщо **лише ви** можете надсилати повідомлення боту, prompt injection усе одно може виникнути через +будь-який **недовірений вміст**, який бот читає (результати web search/fetch, сторінки браузера, +листи, документи, вкладення, вставлені журнали/код). Іншими словами: джерелом загрози є не лише відправник; сам **вміст** також може містити ворожі інструкції. -Коли інструменти увімкнено, типовий ризик — це витік контексту або ініціювання -викликів інструментів. Зменшуйте радіус ураження так: +Коли інструменти увімкнено, типовий ризик — це витік контексту або запуск +викликів інструментів. Зменшити радіус ураження можна так: -- Використовуйте **агента-читача** лише для читання або без інструментів, щоб узагальнювати недовірений вміст, - а потім передавайте підсумок основному агенту. -- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з інструментами, якщо вони не потрібні. +- Використовуйте **агента-читача** у режимі лише для читання або без інструментів для узагальнення недовіреного вмісту, + а потім передавайте це узагальнення вашому основному агенту. +- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами, якщо вони не потрібні. - Для URL-входів OpenResponses (`input_file` / `input_image`) задавайте суворі `gateway.http.endpoints.responses.files.urlAllowlist` і - `gateway.http.endpoints.responses.images.urlAllowlist`, а `maxUrlParts` тримайте низьким. - Порожні allowlists трактуються як unset; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, - якщо хочете повністю вимкнути завантаження URL. -- Для файлових входів OpenResponses декодований текст `input_file` усе одно ін’єктується як - **недовірений зовнішній вміст**. Не вважайте текст файла довіреним лише тому, - що Gateway декодував його локально. Ін’єктований блок усе одно містить явні + `gateway.http.endpoints.responses.images.urlAllowlist`, а також тримайте `maxUrlParts` низьким. + Порожні allowlist трактуються як не встановлені; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + якщо хочете повністю вимкнути отримання URL. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно інжектується як + **недовірений зовнішній вміст**. Не вважайте текст файлу довіреним лише тому, + що Gateway декодував його локально. Інжектований блок усе одно містить явні маркери меж `<<>>` плюс метадані `Source: External`, хоча в цьому шляху відсутній довший банер `SECURITY NOTICE:`. - Те саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст - із прикріплених документів перед додаванням цього тексту до промпта media. -- Увімкнення sandboxing і суворих allowlists інструментів для будь-якого агента, який працює з недовіреним введенням. -- Тримайте секрети поза промптами; передавайте їх через env/config на хості gateway. + із вкладених документів перед додаванням цього тексту до media prompt. +- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, що працює з недовіреним вводом. +- Тримайте секрети поза prompt; передавайте їх через env/config на хості gateway. -### Сила моделі (примітка щодо безпеки) +### Сила моделі (примітка з безпеки) -Стійкість до ін’єкції промптів **не є однаковою** для всіх рівнів моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та захоплення інструкцій, особливо під впливом ворожих промптів. +Стійкість до prompt injection **не** є однаковою для всіх рівнів моделей. Менші/дешевші моделі зазвичай більш уразливі до неправильного використання інструментів і захоплення інструкцій, особливо під ворожими prompt. -Для агентів з увімкненими інструментами або агентів, які читають недовірений вміст, ризик ін’єкції промптів зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. +Для агентів з увімкненими інструментами або агентів, які читають недовірений вміст, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте модель найкращого рівня останнього покоління** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для агентів з увімкненими інструментами або недовірених вхідних; ризик ін’єкції промптів надто високий. -- Якщо вам усе ж потрібно використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlists). -- Під час роботи з малими моделями **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються жорстко. -- Для персональних помічників лише для чату з довіреним введенням і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з інструментами або недовіреними вхідними даними; ризик prompt injection занадто високий. +- Якщо вам усе ж потрібна менша модель, **зменшуйте радіус ураження** (інструменти лише для читання, сильний sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Під час запуску малих моделей **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не перебувають під суворим контролем. +- Для чат-асистентів особистого користування з довіреним вводом і без інструментів менші моделі зазвичай підходять. -## Reasoning і verbose output у групах +## Reasoning і докладний вивід у групах -`/reasoning` і `/verbose` можуть розкривати внутрішнє міркування або результати інструментів, -які не призначалися для публічного каналу. У групових сценаріях вважайте їх -**лише засобами налагодження** й тримайте вимкненими, якщо тільки вони вам явно не потрібні. +`/reasoning` і `/verbose` можуть розкривати внутрішнє reasoning або вивід інструментів, +який не призначався для публічного каналу. У групових налаштуваннях розглядайте їх як **лише для налагодження** +і тримайте вимкненими, якщо тільки вони вам явно не потрібні. Рекомендації: - Тримайте `/reasoning` і `/verbose` вимкненими в публічних кімнатах. -- Якщо вмикаєте їх, робіть це лише в довірених DM або жорстко контрольованих кімнатах. -- Пам’ятайте: verbose output може містити аргументи інструментів, URL і дані, які бачила модель. +- Якщо ви їх вмикаєте, робіть це лише в довірених DM або жорстко контрольованих кімнатах. +- Пам’ятайте: докладний вивід може містити аргументи інструментів, URL і дані, які бачила модель. ## Посилення конфігурації (приклади) ### 0) Дозволи файлів -Тримайте конфігурацію й стан приватними на хості gateway: +Тримайте config + state приватними на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) -- `~/.openclaw`: `700` (лише користувач) +- `~/.openclaw`: `700` (лише для користувача) `openclaw doctor` може попередити про це й запропонувати посилити ці дозволи. -### 0.4) Відкриття в мережу (bind + port + firewall) +### 0.4) Відкритість мережі (bind + port + firewall) -Gateway мультиплексує **WebSocket + HTTP** на одному порту: +Шлюз мультиплексує **WebSocket + HTTP** на одному порту: -- Типово: `18789` -- Конфігурація/прапорці/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` +- Типовий: `18789` +- Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` Ця HTTP-поверхня включає Control UI і canvas host: - Control UI (ресурси SPA) (типовий базовий шлях `/`) -- Canvas host: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; ставтеся до нього як до недовіреного вмісту) +- Canvas host: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; розглядайте як недовірений вміст) -Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: +Якщо ви завантажуєте canvas-вміст у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: - Не відкривайте canvas host для недовірених мереж/користувачів. -- Не змушуйте вміст canvas використовувати той самий origin, що й привілейовані вебповерхні, якщо ви не повністю розумієте наслідки. +- Не змушуйте canvas-вміст ділити той самий origin із привілейованими вебповерхнями, якщо ви повністю не розумієте наслідки. Режим bind визначає, де слухає Gateway: - `gateway.bind: "loopback"` (типово): підключатися можуть лише локальні клієнти. -- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише разом з auth gateway (спільний token/password або правильно налаштований trusted proxy не на loopback) і реальним firewall. +- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте його лише разом з auth gateway (спільний token/password або правильно налаштований trusted proxy не на loopback) і реальним firewall. Практичні правила: -- Надавайте перевагу Tailscale Serve замість bind у LAN (Serve залишає Gateway на loopback, а Tailscale керує доступом). -- Якщо вам все ж потрібно виконати bind у LAN, обмежте порт у firewall жорстким allowlist IP-адрес джерела; не робіть для нього широке port-forwarding. +- Надавайте перевагу 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` або `ports:` у Compose) маршрутизуються через ланцюжки -переспрямування Docker, а не лише через правила `INPUT` хоста. +Якщо ви запускаєте OpenClaw з Docker на VPS, пам’ятайте, що опубліковані порти контейнера +(`-p HOST:CONTAINER` або `ports:` у Compose) маршрутизуються через ланцюги пересилання Docker, +а не лише через правила `INPUT` хоста. -Щоб узгодити трафік Docker з політикою вашого firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюжок перевіряється до власних правил accept Docker). -У багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` +Щоб трафік Docker відповідав вашій політиці firewall, застосовуйте правила в +`DOCKER-USER` (цей ланцюг обробляється до власних правил accept Docker). +На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` і все одно застосовують ці правила до backend nftables. Мінімальний приклад allowlist (IPv4): @@ -796,10 +809,10 @@ Gateway мультиплексує **WebSocket + HTTP** на одному пор COMMIT ``` -Для IPv6 використовуються окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо -у Docker увімкнено IPv6. +Для IPv6 існують окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо +Docker IPv6 увімкнено. -Уникайте жорстко закодованих назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів +Уникайте жорсткого кодування назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково пропустити ваше правило deny. @@ -812,22 +825,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -Очікувані зовнішні порти мають бути лише тими, які ви свідомо відкрили (для більшості +Очікуваними зовнішніми портами мають бути лише ті, які ви навмисно відкрили (для більшості конфігурацій: SSH + порти вашого reverse proxy). -### 0.4.2) Виявлення через mDNS/Bonjour (розкриття інформації) +### 0.4.2) Виявлення mDNS/Bonjour (розкриття інформації) -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати деталі роботи: - `cliPath`: повний шлях файлової системи до бінарного файла CLI (розкриває ім’я користувача та місце встановлення) -- `sshPort`: рекламує доступність SSH на хості +- `sshPort`: повідомляє про доступність SSH на хості - `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування операційної безпеки:** трансляція деталей інфраструктури спрощує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та доступність SSH, допомагає атакувальникам картографувати ваше середовище. +**Міркування операційної безпеки:** трансляція деталей інфраструктури спрощує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та наявність SSH, допомагає зловмисникам картографувати ваше середовище. **Рекомендації:** -1. **Мінімальний режим** (типовий, рекомендований для відкритих шлюзів): опускає чутливі поля з трансляцій mDNS: +1. **Мінімальний режим** (типовий, рекомендований для відкритих gateway): виключає чутливі поля з mDNS-трансляцій: ```json5 { @@ -847,7 +860,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Повний режим** (лише за явним увімкненням): включає `cliPath` + `sshPort` у TXT-записи: +3. **Повний режим** (лише за явною згодою): включає `cliPath` + `sshPort` у TXT-записи: ```json5 { @@ -857,19 +870,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. +4. **Змінна середовища** (альтернатива): встановіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін у конфігурації. -У мінімальному режимі Gateway усе одно транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях CLI, можуть отримати її через автентифіковане підключення WebSocket. +У мінімальному режимі Gateway все одно транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане підключення WebSocket. -### 0.5) Заблокуйте WebSocket Gateway (локальна auth) +### 0.5) Захистіть WebSocket Gateway (локальна auth) -Auth gateway **обов’язкова за замовчуванням**. Якщо не налаштовано -дійсний шлях auth gateway, Gateway відмовляє у WebSocket-підключеннях (fail‑closed). +Auth gateway **є обов’язковою за замовчуванням**. Якщо не налаштовано +жодного коректного шляху auth gateway, Gateway відмовляє у підключеннях WebSocket (безпечна відмова за замовчуванням). -Онбординг за замовчуванням генерує токен (навіть для loopback), тому -локальні клієнти мають автентифікуватися. +Онбординг типово генерує token (навіть для loopback), тому +локальні клієнти повинні проходити автентифікацію. -Установіть токен, щоб **усі** WS-клієнти мусили проходити автентифікацію: +Встановіть token, щоб **усі** клієнти WS проходили автентифікацію: ```json5 { @@ -881,121 +894,123 @@ Auth gateway **обов’язкова за замовчуванням**. Якщ Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. -Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. Вони -самі по собі **не** захищають локальний WS-доступ. -Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback, лише коли `gateway.auth.*` -не задано. -Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, -розв’язання завершується за принципом fail closed (жоден fallback remote це не маскує). -Необов’язково: фіксуйте remote TLS через `gateway.remote.tlsFingerprint`, якщо використовуєте `wss://`. -Незашифрований `ws://` за замовчуванням дозволено лише для loopback. Для довірених шляхів у приватній мережі +Примітка: `gateway.remote.token` / `.password` — це джерела клієнтських облікових даних. Вони +самі по собі **не** захищають локальний доступ WS. +Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` +не встановлено. +Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається визначити значення, +визначення завершується безпечним блокуванням (без маскування через fallback на remote). +Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint`, якщо використовуєте `wss://`. +Нешифрований `ws://` типово дозволений лише для loopback. Для довірених шляхів у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. -Локальне pairing пристроїв: +Локальне pairing пристрою: - Pairing пристрою автоматично схвалюється для прямих локальних loopback-підключень, щоб - спростити роботу клієнтів на тому самому хості. -- OpenClaw також має вузький шлях самопідключення backend/container-local для - довірених допоміжних потоків зі спільним секретом. -- Підключення через tailnet і LAN, включно з bind tailnet на тому самому хості, вважаються - віддаленими для pairing і все одно потребують схвалення. + same-host клієнти працювали без зайвих перешкод. +- OpenClaw також має вузький backend/container-local шлях самопідключення для + довірених helper-потоків зі спільним секретом. +- Підключення через tailnet і LAN, включно з bind через tailnet на тому ж хості, вважаються + віддаленими з погляду pairing і все одно потребують схвалення. Режими auth: -- `gateway.auth.mode: "token"`: спільний bearer-токен (рекомендовано для більшості конфігурацій). -- `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 з підтримкою identity, який автентифікує користувачів і передає ідентичність через заголовки (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (token/password): -1. Згенеруйте/задайте новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). +1. Згенеруйте/встановіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). 2. Перезапустіть Gateway (або перезапустіть застосунок macOS, якщо він керує Gateway). -3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). -4. Переконайтеся, що зі старими обліковими даними більше не можна підключитися. +3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які викликають Gateway). +4. Перевірте, що зі старими обліковими даними підключитися вже не можна. ### 0.6) Заголовки ідентичності Tailscale Serve Коли `gateway.auth.allowTailscale` має значення `true` (типово для Serve), OpenClaw приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації -Control UI/WebSocket. OpenClaw перевіряє ідентичність, розв’язуючи адресу -`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і звіряючи її із заголовком. Це спрацьовує лише для запитів, які потрапляють на loopback +Control UI/WebSocket. OpenClaw перевіряє ідентичність, визначаючи адресу +`x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і зіставляючи її +із заголовком. Це спрацьовує лише для запитів, що потрапляють на loopback і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, як їх додає Tailscale. -Для цього асинхронного шляху перевірки ідентичності невдалі спроби для одного `{scope, ip}` -серіалізуються до того, як лімітер зафіксує збій. Тому паралельні хибні повторні спроби +Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` +серіалізуються до того, як лімітатор зафіксує помилку. Тому паралельні невдалі повторні спроби від одного клієнта Serve можуть одразу заблокувати другу спробу, замість того щоб -проскочити як дві звичайні невідповідності. -Кінцеві точки HTTP API (наприклад, `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують auth за заголовками ідентичності Tailscale. Вони, як і раніше, дотримуються +пройти як дві звичайні незалежні невідповідності. +Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) +**не** використовують auth через заголовки ідентичності Tailscale. Вони й далі дотримуються налаштованого режиму HTTP auth gateway. Важлива примітка про межі: -- HTTP bearer auth шлюзу фактично дає повний операторський доступ за принципом «усе або нічого». -- Облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, слід вважати повними операторськими секретами доступу до цього gateway. -- На HTTP-поверхні, сумісній з OpenAI, bearer auth зі спільним секретом відновлює повні типові операторські scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. -- Семантика scope для кожного запиту в HTTP застосовується лише тоді, коли запит надходить із режиму, що передає ідентичність, наприклад trusted proxy auth або `gateway.auth.mode="none"` на приватному ingress. -- У цих режимах, що передають ідентичність, пропуск `x-openclaw-scopes` призводить до повернення до звичайного типового набору операторських scope; надсилайте цей заголовок явно, коли хочете звузити набір scope. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там теж вважається повним операторським доступом, тоді як режими, що передають ідентичність, як і раніше, поважають оголошені scope. -- Не діліться цими обліковими даними з недовіреними викликаючими клієнтами; надавайте перевагу окремим шлюзам для кожної межі довіри. +- Bearer auth HTTP Gateway фактично дає повний або нульовий операторський доступ. +- Облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, слід вважати секретами оператора з повним доступом для цього gateway. +- На HTTP-поверхні, сумісній з OpenAI, bearer auth зі спільним секретом відновлює повний типовий набір операторських scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику owner для ходів агента; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. +- Семантика scope на HTTP на рівні окремого запиту застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як auth trusted proxy або `gateway.auth.mode="none"` на приватному ingress. +- У таких режимах, що несуть ідентичність, пропуск `x-openclaw-scopes` повертає типовий набір операторських scope; надсилайте цей заголовок явно, якщо хочете вужчий набір scope. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password і тут розглядається як повний операторський доступ, тоді як режими з ідентичністю все ще враховують оголошені scope. +- Не діліться цими обліковими даними з недовіреними викликаючими; для кожної межі довіри краще використовувати окремі gateway. -**Припущення довіри:** auth Serve без токена припускає, що хост gateway є довіреним. -Не вважайте це захистом від зловмисних процесів на тому самому хості. Якщо на хості gateway +**Припущення довіри:** auth Serve без token виходить із довіри до хоста gateway. +Не вважайте це захистом від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явну auth зі спільним секретом через `gateway.auth.mode: "token"` або +і вимагайте явної auth зі спільним секретом через `gateway.auth.mode: "token"` або `"password"`. **Правило безпеки:** не пересилайте ці заголовки зі свого reverse proxy. Якщо -ви завершуєте TLS або проксіюєте трафік перед gateway, вимкніть +ви завершуєте TLS або ставите proxy перед gateway, вимкніть `gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: -"token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth). +"token"` або `"password"`) чи [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) +замість цього. Довірені proxy: -- Якщо ви завершуєте TLS перед Gateway, установіть `gateway.trustedProxies` на IP-адреси вашого proxy. -- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP, щоб визначати IP клієнта для локальних перевірок pairing і HTTP auth/local. +- Якщо ви завершуєте TLS перед Gateway, вкажіть IP-адреси proxy у `gateway.trustedProxies`. +- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP для визначення IP-адреси клієнта під час локальних перевірок pairing і HTTP auth/local-перевірок. - Переконайтеся, що ваш proxy **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. -Див. [Tailscale](/uk/gateway/tailscale) і [Огляд вебінтерфейсу](/web). +Див. [Tailscale](/uk/gateway/tailscale) і [Огляд web](/web). -### 0.6.1) Керування браузером через host node (рекомендовано) +### 0.6.1) Керування браузером через хост node (рекомендовано) -Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **host node** +Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **хост node** на машині з браузером і дозвольте Gateway проксіювати дії браузера (див. [Інструмент browser](/uk/tools/browser)). -Ставтеся до pairing node як до адміністративного доступу. +Розглядайте pairing node як адміндоступ. Рекомендований шаблон: -- Тримайте Gateway і host node в одному tailnet (Tailscale). -- Виконуйте pairing node свідомо; вимикайте маршрутизацію проксі браузера, якщо вона вам не потрібна. +- Тримайте Gateway і хост node в одному tailnet (Tailscale). +- Pairing node виконуйте свідомо; вимикайте proxy routing браузера, якщо він вам не потрібен. Уникайте: - Відкриття relay/control-портів у LAN або публічному інтернеті. -- Tailscale Funnel для кінцевих точок керування браузером (публічне відкриття). +- Tailscale Funnel для кінцевих точок керування браузером (публічна відкритість). ### 0.7) Секрети на диску (чутливі дані) -Вважайте, що все під `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: +Виходьте з того, що будь-що в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: конфігурація може містити токени (gateway, remote gateway), налаштування провайдерів і allowlists. -- `credentials/**`: облікові дані каналів (наприклад, creds WhatsApp), pairing allowlists, імпорт застарілого 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`), які можуть містити приватні повідомлення та результати інструментів. -- пакети bundled plugin: установлені plugins (разом із їхніми `node_modules/`). -- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте в sandbox. +- `openclaw.json`: конфігурація може містити токени (gateway, remote gateway), налаштування провайдерів і allowlist. +- `credentials/**`: облікові дані каналів (наприклад, WhatsApp creds), pairing allowlist, імпорт застарілого OAuth. +- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени та необов’язкові `keyRef`/`tokenRef`. +- `secrets.json` (необов’язково): payload секретів на основі файлу, що використовується провайдерами `file` SecretRef (`secrets.providers`). +- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються після виявлення. +- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення і вивід інструментів. +- пакети bundled plugin: встановлені plugins (разом із їхніми `node_modules/`). +- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте всередині sandbox. -Поради щодо посилення безпеки: +Поради щодо посилення захисту: -- Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). +- Тримайте жорсткі дозволи (`700` для каталогів, `600` для файлів). - Використовуйте повнодискове шифрування на хості gateway. -- Якщо хост є спільним, використовуйте для Gateway окремий обліковий запис користувача ОС. +- Якщо хост спільний, надавайте перевагу окремому користувацькому акаунту ОС для Gateway. -### 0.8) Журнали + транскрипти (редагування + зберігання) +### 0.8) Журнали й транскрипти (редагування + зберігання) -Журнали та транскрипти можуть витікати чутливу інформацію, навіть якщо контроль доступу налаштовано правильно: +Журнали й транскрипти можуть призводити до витоку чутливої інформації, навіть якщо контроль доступу налаштовано правильно: - Журнали Gateway можуть містити зведення інструментів, помилки та URL. - Транскрипти сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. @@ -1003,9 +1018,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро Рекомендації: - Тримайте редагування зведень інструментів увімкненим (`logging.redactSensitive: "tools"`; типово). -- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). +- Додавайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). - Під час поширення діагностики надавайте перевагу `openclaw status --all` (зручно для вставлення, секрети відредаговано) замість сирих журналів. -- Видаляйте старі транскрипти сесій і файли журналів, якщо вам не потрібне тривале зберігання. +- Видаляйте старі транскрипти сесій і файли журналів, якщо вам не потрібне довготривале зберігання. Докладніше: [Logging](/uk/gateway/logging) @@ -1039,31 +1054,31 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -У групових чатах відповідайте лише за явної згадки. +У групових чатах відповідайте лише тоді, коли вас явно згадали. ### 3) Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі телефонних номерів розгляньте запуск вашого AI на окремому номері телефону, не на особистому: +Для каналів на основі номера телефону варто розглянути запуск вашого AI на окремому номері телефону, відмінному від особистого: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: AI обробляє їх із належними межами +- Номер бота: AI обробляє саме їх, у відповідних межах ### 4) Режим лише для читання (через sandbox + tools) -Ви можете створити профіль лише для читання, поєднавши: +Ви можете побудувати профіль лише для читання, поєднавши: - `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` без доступу до workspace) - списки allow/deny інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо -Додаткові варіанти посилення безпеки: +Додаткові варіанти посилення захисту: -- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти файли поза каталогом workspace, навіть коли sandboxing вимкнено. Установлюйте `false` лише якщо ви свідомо хочете, щоб `apply_patch` змінював файли поза workspace. -- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автоматичного завантаження зображень у native prompt каталогом workspace (корисно, якщо ви зараз дозволяєте абсолютні шляхи й хочете один спільний запобіжник). -- Тримайте корені файлової системи вузькими: уникайте широких коренів, таких як ваш домашній каталог, для workspace агента/sandbox workspace. Широкі корені можуть відкрити чутливі локальні файли (наприклад, state/config у `~/.openclaw`) для файлових інструментів. +- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти файли поза каталогом workspace, навіть якщо sandboxing вимкнено. Встановлюйте `false` лише якщо свідомо хочете, щоб `apply_patch` працював із файлами поза workspace. +- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автозавантаження зображень native prompt каталогом workspace (корисно, якщо зараз ви дозволяєте абсолютні шляхи й хочете один спільний запобіжник). +- Тримайте корені файлової системи вузькими: уникайте широких коренів на кшталт домашнього каталогу для workspace агента/sandbox workspace. Широкі корені можуть відкрити інструментам файлової системи доступ до чутливих локальних файлів (наприклад, state/config у `~/.openclaw`). -### 5) Безпечна базова конфігурація (скопіювати/вставити) +### 5) Безпечна базова конфігурація (копіювати/вставити) -Одна «безпечна типова» конфігурація, яка тримає Gateway приватним, вимагає DM pairing і уникає ботів у групах, які завжди активні: +Одна «безпечна за замовчуванням» конфігурація, яка тримає Gateway приватним, вимагає DM pairing і уникає завжди активних ботів у групах: ```json5 { @@ -1082,9 +1097,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -Якщо ви також хочете «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + deny небезпечних інструментів для будь-якого агента, який не є власником (приклад нижче в розділі «Профілі доступу для кожного агента»). +Якщо ви також хочете «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого агента, що не є owner (приклад нижче в розділі «Профілі доступу на рівні агента»). -Вбудована базова конфігурація для чат-керованих ходів агента: відправники, які не є власником, не можуть використовувати інструменти `cron` або `gateway`. +Вбудована базова політика для ходів агента, керованих через чат: відправники, які не є owner, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) @@ -1092,59 +1107,59 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро Два взаємодоповнювальні підходи: -- **Запуск усього Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) -- **Tool sandbox** (`agents.defaults.sandbox`, host gateway + інструменти, ізольовані Docker): [Sandboxing](/uk/gateway/sandboxing) +- **Запускати весь Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) +- **Інструментальний sandbox** (`agents.defaults.sandbox`, хостовий gateway + інструменти, ізольовані через 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 агента; інструменти працюють із sandbox workspace в `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) не дає доступу до workspace агента; інструменти працюють із sandbox workspace у `~/.openclaw/sandboxes` - `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace агента для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими та канонізованими шляхами джерела. Трюки з батьківськими symlink і канонічними псевдонімами домашнього каталогу все одно безпечно завершуються відмовою, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у домашньому каталозі ОС. +- Додаткові `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. Ефективним хостом типово є `gateway`, або `node`, якщо ціль exec налаштована як `node`. Тримайте `tools.elevated.allowFrom` суворо обмеженим і не вмикайте його для сторонніх користувачів. Ви можете додатково обмежити elevated на рівні агента через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). -### Запобіжник делегування sub-agent +### Запобіжник делегування субагентам -Якщо ви дозволяєте session tools, розглядайте делеговані запуски sub-agent як ще одне рішення щодо меж: +Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як окреме рішення щодо меж: - Забороняйте `sessions_spawn`, якщо агенту справді не потрібне делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агента обмеженими відомими безпечними цільовими агентами. -- Для будь-якого процесу, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). -- `sandbox: "require"` завершується швидкою відмовою, якщо цільовий дочірній runtime не працює в sandbox. +- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агента обмеженими відомо безпечними цільовими агентами. +- Для будь-якого workflow, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` негайно завершується помилкою, якщо дочірній runtime цільового агента не працює в sandbox. ## Ризики керування браузером Увімкнення керування браузером дає моделі можливість керувати реальним браузером. -Якщо профіль цього браузера вже містить активні сесії входу, модель може -отримати доступ до цих облікових записів і даних. Розглядайте профілі браузера як **чутливий стан**: +Якщо в цьому профілі браузера вже є активні сесії входу, модель може +отримати доступ до цих акаунтів і даних. Розглядайте профілі браузера як **чутливий стан**: - Надавайте перевагу окремому профілю для агента (типовий профіль `openclaw`). -- Не спрямовуйте агента на ваш особистий щоденний профіль. -- Тримайте host browser control вимкненим для агентів у sandbox, якщо ви їм не довіряєте. -- Окремий loopback API керування браузером приймає лише auth зі спільним секретом - (bearer auth за токеном gateway або пароль gateway). Він не використовує +- Уникайте спрямування агента на ваш особистий щоденний профіль. +- Тримайте керування браузером на хості вимкненим для sandboxed-агентів, якщо ви їм не довіряєте. +- Окремий loopback API керування браузером підтримує лише auth зі спільним секретом + (bearer auth через token gateway або пароль gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Розглядайте завантаження браузера як недовірений вхід; надавайте перевагу ізольованому каталогу завантажень. -- Якщо можливо, вимкніть синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). -- Для віддалених шлюзів припускайте, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. -- Тримайте Gateway і host node лише в межах tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. -- Вимикайте маршрутизацію проксі браузера, коли вона вам не потрібна (`gateway.nodes.browser.mode="off"`). -- Режим наявної сесії Chrome MCP **не є** «безпечнішим»; він може діяти від вашого імені скрізь, куди має доступ цей профіль Chrome на хості. +- Розглядайте завантаження браузером як недовірений вхід; надавайте перевагу ізольованому каталогу завантажень. +- Якщо можливо, вимикайте синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). +- Для віддалених gateway виходьте з того, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. +- Тримайте Gateway і хости node лише в tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. +- Вимикайте proxy routing браузера, якщо він вам не потрібен (`gateway.nodes.browser.mode="off"`). +- Режим наявної сесії Chrome MCP **не** є «безпечнішим»; він може діяти від вашого імені в усьому, до чого має доступ той профіль Chrome на хості. -### Політика SSRF для browser (сувора за замовчуванням) +### Політика SSRF браузера (сувора за замовчуванням) -Політика навігації browser в OpenClaw за замовчуванням сувора: приватні/внутрішні адресати залишаються заблокованими, якщо ви явно не дозволите їх. +Політика навігації браузера в OpenClaw за замовчуванням сувора: приватні/внутрішні адресати залишаються заблокованими, якщо ви явно не дозволите їх. -- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не задано, тому навігація browser продовжує блокувати приватні/внутрішні/спеціальні адресати. -- Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` усе ще приймається для сумісності. -- Режим opt-in: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/спеціальні адресати. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для хостів, включно із заблокованими іменами, як-от `localhost`) для явних винятків. -- Навігація перевіряється перед запитом і best-effort повторно перевіряється на фінальному URL `http(s)` після навігації, щоб зменшити можливість redirect-орієнтованих обходів. +- Типова поведінка: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера й далі блокує приватні/внутрішні/special-use адресати. +- Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` і далі приймається для сумісності. +- Режим з явною згодою: встановіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use адресати. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки хостів, включно із заблокованими іменами на кшталт `localhost`) для явних винятків. +- Навігація перевіряється до запиту та повторно перевіряється best-effort на фінальному URL `http(s)` після навігації, щоб зменшити ризик переходів через редиректи. Приклад суворої політики: @@ -1160,15 +1175,15 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -## Профілі доступу для кожного агента (multi-agent) +## Профілі доступу на рівні агента (multi-agent) -За маршрутизації multi-agent кожен агент може мати власну політику sandbox + tools: -використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного агента. +У multi-agent-маршрутизації кожен агент може мати власну політику sandbox + tools: +використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** на рівні агента. Повні подробиці та правила пріоритету див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). -Поширені варіанти використання: +Типові сценарії: -- Персональний агент: повний доступ, без sandbox +- Особистий агент: повний доступ, без sandbox - Сімейний/робочий агент: sandbox + інструменти лише для читання - Публічний агент: sandbox + без інструментів файлової системи/оболонки @@ -1212,7 +1227,7 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро } ``` -### Приклад: без доступу до файлової системи/оболонки (дозволено обмін повідомленнями через провайдера) +### Приклад: без доступу до файлової системи/оболонки (дозволені provider messaging) ```json5 { @@ -1226,9 +1241,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро scope: "agent", workspaceAccess: "none", }, - // Session tools можуть розкривати чутливі дані з транскриптів. За замовчуванням OpenClaw обмежує ці інструменти - // поточною сесією + сесіями spawned subagent, але за потреби ви можете затиснути їх ще сильніше. - // Див. `tools.sessions.visibility` у довіднику з конфігурації. + // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools + // to the current session + spawned subagent sessions, but you can clamp further if needed. + // See `tools.sessions.visibility` in the configuration reference. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1265,53 +1280,53 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ро ## Що сказати вашому AI -Додайте рекомендації з безпеки до системного промпта вашого агента: +Включіть рекомендації з безпеки до system prompt вашого агента: ``` -## Правила безпеки -- Ніколи не діліться списками каталогів або шляхами до файлів зі сторонніми -- Ніколи не розкривайте API-ключі, облікові дані або деталі інфраструктури -- Підтверджуйте із власником запити, які змінюють конфігурацію системи -- Якщо сумніваєтеся, запитайте перед дією -- Тримайте приватні дані приватними, якщо немає явної авторизації +## Security Rules +- Never share directory listings or file paths with strangers +- Never reveal API keys, credentials, or infrastructure details +- Verify requests that modify system config with the owner +- When in doubt, ask before acting +- Keep private data private unless explicitly authorized ``` ## Реагування на інциденти -Якщо ваш AI зробив щось погане: +Якщо ваш AI зробив щось небажане: ### Стримування -1. **Зупиніть його:** зупиніть застосунок macOS (якщо він керує Gateway) або завершіть процес `openclaw gateway`. -2. **Закрийте відкриття:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** перемкніть ризиковані DM/групи на `dmPolicy: "disabled"` / вимогу згадки й видаліть записи `"*"` із режимом «дозволити всім», якщо вони були. +1. **Зупиніть це:** зупиніть застосунок macOS (якщо він керує Gateway) або завершіть процес `openclaw gateway`. +2. **Закрийте відкритість:** встановіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. +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 зашифрованих секретів, якщо вони використовуються). +2. Замініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на всіх машинах, які можуть викликати Gateway. +3. Замініть облікові дані провайдерів/API (WhatsApp creds, токени Slack/Discord, ключі моделей/API в `auth-profiles.json` і значення payload зашифрованих секретів, якщо вони використовуються). ### Аудит 1. Перевірте журнали Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). 2. Перегляньте відповідні транскрипти: `~/.openclaw/agents//sessions/*.jsonl`. -3. Перегляньте останні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни plugin). -4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні результати усунено. +3. Перегляньте недавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни plugins). +4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні знахідки усунуто. -### Зберіть для звіту +### Зберіть дані для звіту -- Часова позначка, ОС хоста gateway + версія OpenClaw -- Транскрипт(и) сесії + короткий хвіст журналу (після редагування) -- Що надіслав атакувальник + що зробив агент +- Часова мітка, ОС хоста gateway + версія OpenClaw +- Транскрипти сесії(й) + короткий хвіст журналу (після редагування) +- Що надіслав зловмисник + що зробив агент - Чи був Gateway відкритий за межі loopback (LAN/Tailscale Funnel/Serve) ## Сканування секретів (detect-secrets) CI запускає pre-commit hook `detect-secrets` у job `secrets`. Push у `main` завжди запускають сканування всіх файлів. Pull request використовують -швидкий шлях лише для змінених файлів, коли доступний базовий коміт, і повертаються -до сканування всіх файлів в іншому разі. Якщо перевірка не проходить, це означає, що є нові кандидати, яких ще немає в baseline. +швидкий шлях для змінених файлів, коли доступний базовий коміт, і повертаються до +сканування всіх файлів в іншому випадку. Якщо перевірка не проходить, з’явилися нові кандидати, яких ще немає в baseline. ### Якщо CI не проходить @@ -1322,27 +1337,25 @@ Push у `main` завжди запускають сканування всіх ``` 2. Зрозумійте інструменти: - - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із baseline - і excludes репозиторію. - - `detect-secrets audit` відкриває інтерактивний перегляд, де можна позначити кожен елемент baseline - як реальний або хибнопозитивний. -3. Для реальних секретів: замініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. -4. Для хибнопозитивних результатів: запустіть інтерактивний аудит і позначте їх як хибні: + - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з baseline та exclude цього репозиторію. + - `detect-secrets audit` відкриває інтерактивний перегляд, де можна позначити кожен елемент baseline як справжній секрет або хибнопозитивне спрацювання. +3. Якщо це справжні секрети: замініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. +4. Якщо це хибнопозитивні спрацювання: запустіть інтерактивний аудит і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові excludes, додайте їх до `.detect-secrets.cfg` і заново згенеруйте - baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл - конфігурації є лише довідковим; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові exclude, додайте їх до `.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/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 288e61e54..970e86914 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,22 +1,22 @@ --- read_when: - - Центр усунення несправностей скерував вас сюди для глибшої діагностики - - Вам потрібні стабільні розділи посібника за симптомами з точними командами -summary: Детальний посібник з усунення несправностей для gateway, каналів, автоматизації, вузлів і браузера -title: Усунення несправностей + - Центр усунення неполадок направив вас сюди для глибшої діагностики + - Вам потрібні стабільні розділи посібника з діагностики за симптомами з точними командами +summary: Детальний посібник з усунення неполадок для gateway, каналів, автоматизації, вузлів і браузера +title: Усунення неполадок x-i18n: - generated_at: "2026-04-07T14:59:22Z" + generated_at: "2026-04-10T20:41:23Z" model: gpt-5.4 provider: openai - source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba + source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5 source_path: gateway/troubleshooting.md workflow: 15 --- -# Усунення несправностей gateway +# Усунення неполадок gateway -Ця сторінка — детальний посібник. -Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік тріажу. +Ця сторінка є детальним посібником. +Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік первинної діагностики. ## Послідовність команд @@ -33,13 +33,13 @@ openclaw channels status --probe Очікувані ознаки справного стану: - `openclaw gateway status` показує `Runtime: running` і `RPC probe: ok`. -- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісу. +- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/служб. - `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису та, - де це підтримується, результати probe/audit, наприклад `works` або `audit ok`. + де це підтримується, результати probe/audit, як-от `works` або `audit ok`. -## Для Anthropic 429 для довгого контексту потрібне додаткове використання +## Anthropic 429: для довгого контексту потрібне додаткове використання -Використовуйте це, коли журнали/помилки містять: +Використовуйте це, коли логи/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash @@ -52,13 +52,13 @@ openclaw config get agents.defaults.models - Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. - Поточні облікові дані Anthropic не мають права на використання довгого контексту. -- Запити збоять лише в довгих сесіях/запусках моделі, яким потрібен шлях 1M beta. +- Запити збійно завершуються лише для довгих сесій/запусків моделі, яким потрібен beta-шлях 1M. Варіанти виправлення: 1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. -2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на Anthropic API key. -3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли Anthropic відхиляє запити з довгим контекстом. +2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на ключ Anthropic API. +3. Налаштуйте резервні моделі, щоб виконання продовжувалося, коли запити Anthropic з довгим контекстом відхиляються. Пов’язане: @@ -66,13 +66,13 @@ openclaw config get agents.defaults.models - [/reference/token-use](/uk/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/uk/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-compatible backend проходить прямі probe, але збоять agent runs +## Локальний OpenAI-compatible backend проходить прямі probe, але збоять запуски агента Використовуйте це, коли: - `curl ... /v1/models` працює - малі прямі виклики `/v1/chat/completions` працюють -- запуски моделей OpenClaw збоять лише під час звичайних ходів агента +- запуски моделі OpenClaw збоять лише під час звичайних ходів агента ```bash curl http://127.0.0.1:1234/v1/models @@ -86,42 +86,43 @@ openclaw logs --follow Зверніть увагу на таке: - прямі малі виклики успішні, але запуски OpenClaw збоять лише на більших prompt -- backend повертає помилки про те, що `messages[].content` очікує рядок -- backend падає лише при більшій кількості токенів prompt або на повних prompt середовища агента +- помилки backend про те, що `messages[].content` очікує рядок +- збої backend, які з’являються лише при більшій кількості токенів у prompt або в повних + prompt середовища виконання агента -Типові ознаки: +Поширені ознаки: - `messages[...].content: invalid type: sequence, expected a string` → backend - відхиляє структуровані частини вмісту Chat Completions. Виправлення: задайте + відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть `models.providers..models[].compat.requiresStringContent: true`. -- прямі малі запити успішні, але ходи агента OpenClaw збоять із падіннями backend/моделі - (наприклад Gemma у деяких збірках `inferrs`) → транспорт OpenClaw, - імовірно, уже налаштований правильно; backend збоїть на більшій формі prompt - середовища агента. -- збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів - були частиною навантаження, але решта проблеми все ще в обмеженнях моделі/сервера - вищого рівня або в помилці backend. +- прямі малі запити успішні, але ходи агента OpenClaw збоять через збої backend/моделі + (наприклад, Gemma у деяких збірках `inferrs`) → транспорт OpenClaw + імовірно вже налаштований правильно; проблема в тому, що backend не справляється з більшою формою + prompt середовища виконання агента. +- після вимкнення tools збоїв стає менше, але вони не зникають → схеми tools були + частиною навантаження, але решта проблеми все ще пов’язана з upstream місткістю моделі/сервера + або помилкою backend. Варіанти виправлення: -1. Задайте `compat.requiresStringContent: true` для backend Chat Completions, які приймають лише рядки. -2. Задайте `compat.supportsTools: false` для моделей/backend, які не можуть надійно обробляти - поверхню схем інструментів OpenClaw. +1. Встановіть `compat.requiresStringContent: true` для backend Chat Completions, які підтримують лише рядковий вміст. +2. Встановіть `compat.supportsTools: false` для моделей/backend, які не можуть + надійно обробляти поверхню схем tools OpenClaw. 3. За можливості зменште навантаження prompt: менший bootstrap workspace, коротша історія сесії, легша локальна модель або backend із кращою підтримкою довгого контексту. -4. Якщо малі прямі запити й надалі проходять, а ходи OpenClaw усе ще падають - всередині backend, розглядайте це як обмеження upstream server/model і створіть - там repro з прийнятою формою payload. +4. Якщо прямі малі запити й далі проходять, а ходи агента OpenClaw усе ще збоять + всередині backend, розглядайте це як обмеження upstream сервера/моделі й створіть + там repro з формою payload, яка приймається. Пов’язане: - [/gateway/local-models](/uk/gateway/local-models) -- [/gateway/configuration#models](/uk/gateway/configuration#models) +- [/gateway/configuration](/uk/gateway/configuration) - [/gateway/configuration-reference#openai-compatible-endpoints](/uk/gateway/configuration-reference#openai-compatible-endpoints) ## Немає відповідей -Якщо канали працюють, але ніхто не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. +Якщо канали працюють, але ніхто не відповідає, перевірте маршрутизацію та політики перед тим, як щось перепідключати. ```bash openclaw status @@ -133,14 +134,14 @@ openclaw logs --follow Зверніть увагу на таке: -- Очікує pairing для відправників у DM. -- Фільтрація згадок у групах (`requireMention`, `mentionPatterns`). +- Pairing очікує на розгляд для відправників у DM. +- Обмеження згадок у групах (`requireMention`, `mentionPatterns`). - Невідповідності allowlist каналу/групи. -Типові ознаки: +Поширені ознаки: -- `drop guild message (mention required` → повідомлення в групі ігнорується, доки не буде згадки. -- `pairing request` → відправника потрібно схвалити. +- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадки. +- `pairing request` → відправнику потрібне схвалення. - `blocked` / `allowlist` → відправника/канал відфільтровано політикою. Пов’язане: @@ -149,9 +150,9 @@ openclaw logs --follow - [/channels/pairing](/uk/channels/pairing) - [/channels/groups](/uk/channels/groups) -## Підключення dashboard control UI +## Підключення dashboard/control UI -Коли dashboard/control UI не підключається, перевірте URL, режим auth і припущення щодо secure context. +Коли dashboard/control UI не може підключитися, перевірте URL, режим auth і припущення про безпечний контекст. ```bash openclaw gateway status @@ -164,48 +165,47 @@ openclaw gateway status --json Зверніть увагу на таке: - Правильний URL probe і URL dashboard. -- Невідповідність режиму auth/token між клієнтом і gateway. +- Невідповідність режиму auth/токена між клієнтом і gateway. - Використання HTTP там, де потрібна ідентичність пристрою. -Типові ознаки: +Поширені ознаки: - `device identity required` → небезпечний контекст або відсутня auth пристрою. - `origin not allowed` → `Origin` браузера відсутній у `gateway.controlUi.allowedOrigins` - (або ви підключаєтеся з не-loopback origin браузера без явного + (або ви підключаєтеся з browser origin не на loopback без явного allowlist). - `device nonce required` / `device nonce mismatch` → клієнт не завершує - flow challenge-based device auth (`connect.challenge` + `device.nonce`). + flow auth пристрою на основі challenge (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → клієнт підписав неправильний payload (або використав застарілу часову мітку) для поточного handshake. - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. -- Ця повторна спроба з кешованим токеном повторно використовує набір scope, збережений разом - зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають свій - запитаний набір scope. -- Поза цим шляхом повторної спроби пріоритет auth під час підключення такий: +- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із paired + токеном пристрою. Виклики з явними `deviceToken` / явними `scopes` зберігають + запитаний ними набір scope. +- Поза цим шляхом повторної спроби пріоритет auth для connect такий: спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, - а потім bootstrap token. + потім bootstrap token. - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого - `{scope, ip}` серіалізуються до того, як обмежувач зафіксує невдачу. Тому дві некоректні - одночасні повторні спроби від одного клієнта можуть показати `retry later` - на другій спробі замість двох звичайних невідповідностей. -- `too many failed authentication attempts (retry later)` від loopback-клієнта браузерного origin - → повторні невдачі від того самого нормалізованого `Origin` тимчасово - блокуються; інший localhost origin використовує окремий bucket. -- повторювані `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена й за потреби повторно схваліть/переверніть токен пристрою. + `{scope, ip}` серіалізуються до того, як limiter зафіксує збій. Тому дві хибні + одночасні повторні спроби від того самого клієнта можуть призвести до `retry later` + для другої спроби замість двох звичайних невідповідностей. +- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin + → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. +- повторюване `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та за потреби повторно схваліть/перегенеруйте токен пристрою. - `gateway connect failed:` → неправильний host/port/url призначення. -### Швидка карта кодів деталей auth +### Швидка таблиця кодів деталей auth -Використовуйте `error.details.code` із невдалого відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: -| Detail code | Значення | Рекомендована дія | -| ---------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий shared token. | Вставте/задайте токен у клієнті й повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, а потім вставте його в налаштуваннях Control UI. | -| `AUTH_TOKEN_MISMATCH` | Shared token не збігся з токеном auth gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явним `deviceToken` / `scopes` зберігають запитані scope. Якщо все одно не працює, виконайте [контрольний список відновлення після дрейфу токена](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для пристрою застарів або відкликаний. | Переверніть/повторно схваліть токен пристрою за допомогою [CLI devices](/cli/devices), а потім підключіться знову. | -| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve `. | +| Код деталей | Значення | Рекомендована дія | +| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий shared token. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, а потім вставте його в налаштуваннях Control UI. | +| `AUTH_TOKEN_MISMATCH` | Shared token не збігся з токеном auth gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явними `deviceToken` / `scopes` зберігають запитані scope. Якщо й далі не вдається, виконайте [контрольний список відновлення після розсинхронізації токена](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Перегенеруйте/повторно схваліть токен пристрою через [CLI devices](/cli/devices), а потім перепідключіться. | +| `PAIRING_REQUIRED` | Ідентичність пристрою відома, але не схвалена для цієї ролі. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve `. | -Перевірка міграції device auth v2: +Перевірка міграції auth пристрою v2: ```bash openclaw --version @@ -213,18 +213,18 @@ openclaw doctor openclaw gateway status ``` -Якщо журнали показують помилки nonce/signature, оновіть клієнт, що підключається, і переконайтеся, що він: +Якщо логи показують помилки nonce/signature, оновіть клієнт, що підключається, і перевірте, що він: 1. чекає на `connect.challenge` 2. підписує payload, прив’язаний до challenge 3. надсилає `connect.params.device.nonce` з тим самим nonce challenge -Якщо `openclaw devices rotate` / `revoke` / `remove` несподівано заборонено: +Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано заборонено: -- сесії paired-device token можуть керувати лише **власним** - пристроєм, якщо тільки виклик також не має `operator.admin` +- сесії з токеном paired-device можуть керувати лише **власним** пристроєм, якщо + виклик також не має `operator.admin` - `openclaw devices rotate --scope ...` може запитувати лише ті operator scope, - які сесія виклику вже має + які вже має сесія виклику Пов’язане: @@ -234,32 +234,32 @@ openclaw gateway status - [/gateway/remote](/uk/gateway/remote) - [/cli/devices](/cli/devices) -## Сервіс gateway не працює +## Служба gateway не працює -Використовуйте це, якщо сервіс встановлено, але процес не утримується в робочому стані. +Використовуйте це, коли службу встановлено, але процес не залишається активним. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # також сканує системні сервіси +openclaw gateway status --deep # також сканує служби на рівні системи ``` Зверніть увагу на таке: -- `Runtime: stopped` з підказками про завершення. -- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`). +- `Runtime: stopped` з підказками щодо виходу. +- Невідповідність конфігурації служби (`Config (cli)` vs `Config (service)`). - Конфлікти портів/слухачів. - Додаткові встановлення launchd/systemd/schtasks при використанні `--deep`. -- Підказки очищення `Other gateway-like services detected (best effort)`. +- Підказки для очищення `Other gateway-like services detected (best effort)`. -Типові ознаки: +Поширені ознаки: -- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим gateway не ввімкнено, або файл конфігурації було пошкоджено й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у своїй конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб відновити очікувану конфігурацію local-mode. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації — `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху auth gateway (token/password або trusted-proxy, якщо налаштовано). +- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим gateway не ввімкнено, або файл конфігурації було пошкоджено й у ньому втрачено `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у своїй конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, стандартний шлях до конфігурації — `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` → прив’язка не до loopback без коректного шляху auth gateway (token/password або trusted-proxy, якщо налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. -- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks units. У більшості конфігурацій слід тримати один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + config/state/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні модулі launchd/systemd/schtasks. У більшості конфігурацій має бути один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). Пов’язане: @@ -267,9 +267,9 @@ openclaw gateway status --deep # також сканує системні се - [/gateway/configuration](/uk/gateway/configuration) - [/gateway/doctor](/uk/gateway/doctor) -## Попередження probe gateway +## Попередження gateway probe -Використовуйте це, коли `openclaw gateway probe` до чогось дістається, але все одно виводить блок попередження. +Використовуйте це, коли `openclaw gateway probe` до чогось дістається, але все одно виводить блок попереджень. ```bash openclaw gateway probe @@ -279,15 +279,15 @@ openclaw gateway probe --ssh user@gateway-host Зверніть увагу на таке: -- `warnings[].code` і `primaryTargetId` у виводі JSON. -- Чи пов’язане попередження з резервним SSH, кількома gateway, відсутніми scope або нерозв’язаними auth refs. +- `warnings[].code` і `primaryTargetId` у JSON-виводі. +- Чи пов’язане попередження з резервним переходом через SSH, кількома gateway, відсутніми scope або нерозв’язаними auth refs. -Типові ознаки: +Поширені ознаки: -- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-призначення. -- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисне багатошлюзове налаштування або застарілі/дубльовані слухачі. -- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але RPC деталей обмежений scope; спарте ідентичність пристрою або використайте облікові дані з `operator.read`. -- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → auth-матеріал був недоступний у цьому шляху команди для цілі, що не пройшла перевірку. +- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-цілі. +- `multiple reachable gateways detected` → відповіла більше ніж одна ціль. Зазвичай це означає навмисну конфігурацію з кількома gateway або застарілі/дубльовані listeners. +- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але детальний RPC обмежений scope; виконайте pairing ідентичності пристрою або використайте облікові дані з `operator.read`. +- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth-матеріал був недоступний у цьому шляху команди для цілі, що не пройшла перевірку. Пов’язане: @@ -295,9 +295,9 @@ openclaw gateway probe --ssh user@gateway-host - [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host) - [/gateway/remote](/uk/gateway/remote) -## Канал підключений, але повідомлення не проходять +## Канал підключено, але повідомлення не проходять -Якщо стан каналу показує, що він підключений, але потік повідомлень мертвий, зосередьтеся на політиці, дозволах і специфічних для каналу правилах доставки. +Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиках, дозволах і правилах доставки, специфічних для каналу. ```bash openclaw channels status --probe @@ -311,9 +311,9 @@ openclaw config get channels - Політика DM (`pairing`, `allowlist`, `open`, `disabled`). - Allowlist групи та вимоги до згадок. -- Відсутні дозволи/scopes API каналу. +- Відсутні дозволи/scope API каналу. -Типові ознаки: +Поширені ознаки: - `mention required` → повідомлення ігнорується через політику згадок у групі. - `pairing` / сліди очікування схвалення → відправника не схвалено. @@ -328,7 +328,7 @@ openclaw config get channels ## Доставка cron і heartbeat -Якщо cron або heartbeat не запустилися чи не були доставлені, спочатку перевірте стан планувальника, а потім ціль доставки. +Якщо cron або heartbeat не запустився чи не доставився, спочатку перевірте стан scheduler, а вже потім ціль доставки. ```bash openclaw cron status @@ -340,19 +340,19 @@ openclaw logs --follow Зверніть увагу на таке: -- Cron увімкнено і є наступне пробудження. -- Стан історії запусків завдання (`ok`, `skipped`, `error`). +- Cron увімкнений і присутній час наступного пробудження. +- Стан історії запусків job (`ok`, `skipped`, `error`). - Причини пропуску heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). -Типові ознаки: +Поширені ознаки: - `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. -- `cron: timer tick failed` → збій тіку планувальника; перевірте помилки файлів/журналів/середовища виконання. -- `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. +- `cron: timer tick failed` → збій tick scheduler; перевірте помилки файлів/логів/runtime. +- `heartbeat skipped` з `reason=quiet-hours` → поза межами вікна активних годин. - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. -- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але на цьому тіку жодне із завдань не має бути виконане. -- `heartbeat: unknown accountId` → недійсний id облікового запису для цілі доставки heartbeat. -- `heartbeat skipped` з `reason=dm-blocked` → ціль heartbeat визначилася як призначення стилю DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`. +- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але на цьому tick жодне із завдань не підлягає виконанню. +- `heartbeat: unknown accountId` → недійсний account id для цілі доставки heartbeat. +- `heartbeat skipped` з `reason=dm-blocked` → ціль heartbeat була визначена як призначення у стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`. Пов’язане: @@ -360,9 +360,9 @@ openclaw logs --follow - [/automation/cron-jobs](/uk/automation/cron-jobs) - [/gateway/heartbeat](/uk/gateway/heartbeat) -## Не працює paired tool вузла +## Збій paired tool вузла -Якщо вузол спарено, але інструменти не працюють, окремо перевірте foreground, дозволи та стан схвалення. +Якщо вузол paired, але tools не працюють, ізолюйте стан foreground, дозволи та схвалення. ```bash openclaw nodes status @@ -374,16 +374,16 @@ openclaw status Зверніть увагу на таке: -- Вузол онлайн з очікуваними можливостями. +- Вузол online з очікуваними capability. - Надані дозволи ОС для camera/mic/location/screen. - Стан exec approvals і allowlist. -Типові ознаки: +Поширені ознаки: -- `NODE_BACKGROUND_UNAVAILABLE` → застосунок вузла має бути на передньому плані. +- `NODE_BACKGROUND_UNAVAILABLE` → застосунок вузла має бути у foreground. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС. -- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. -- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist. +- `SYSTEM_RUN_DENIED: approval required` → схвалення exec очікує. +- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано через allowlist. Пов’язане: @@ -391,9 +391,9 @@ openclaw status - [/nodes/index](/uk/nodes/index) - [/tools/exec-approvals](/uk/tools/exec-approvals) -## Не працює browser tool +## Збій browser tool -Використовуйте це, коли дії browser tool збоять, хоча сам gateway справний. +Використовуйте це, коли дії browser tool завершуються з помилкою, хоча сам gateway справний. ```bash openclaw browser status @@ -405,30 +405,30 @@ openclaw doctor Зверніть увагу на таке: -- Чи задано `plugins.allow` і чи містить він `browser`. +- Чи задано `plugins.allow` і чи включає воно `browser`. - Коректний шлях до виконуваного файла браузера. - Досяжність профілю CDP. -- Доступність локального Chrome для профілів `existing-session` / `user`. +- Наявність локального Chrome для профілів `existing-session` / `user`. -Типові ознаки: +Поширені ознаки: -- `unknown command "browser"` або `unknown command 'browser'` → bundled plugin браузера виключено через `plugins.allow`. -- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому plugin ніколи не завантажився. -- `Failed to start Chrome CDP on port` → процес браузера не зміг запуститися. +- `unknown command "browser"` або `unknown command 'browser'` → bundled browser plugin виключено через `plugins.allow`. +- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому plugin ніколи не завантажувався. +- `Failed to start Chrome CDP on port` → процес браузера не вдалося запустити. - `browser.executablePath not found` → налаштований шлях недійсний. - `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, наприклад `file:` або `ftp:`. -- `browser.cdpUrl has invalid port` → налаштований URL CDP має некоректний або позадіапазонний порт. -- `No Chrome tabs found for profile="user"` → профіль підключення Chrome MCP не має відкритих локальних вкладок Chrome. -- `Remote CDP for profile "" is not reachable` → налаштований віддалений endpoint CDP недосяжний з хоста gateway. -- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише з підключенням не має досяжної цілі, або HTTP endpoint відповів, але WebSocket CDP все одно не вдалося відкрити. -- `Playwright is not available in this gateway build; '' is unsupported.` → поточна інсталяція gateway не містить повного пакета Playwright; ARIA snapshots і базові знімки сторінки все ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-селекторами та експорт PDF залишаються недоступними. -- `fullPage is not supported for element screenshots` → запит знімка екрана поєднав `--full-page` з `--ref` або `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі snapshot, а не CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів Chrome MCP потребують snapshot refs, а не CSS-селекторів. -- `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP. -- `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення timeout. -- `response body is not supported for existing-session profiles yet.` → `responsebody` поки що потребує керованого браузера або профілю raw CDP. -- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування та звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. +- `browser.cdpUrl has invalid port` → налаштований URL CDP має некоректний або неприпустимий порт. +- `No Chrome tabs found for profile="user"` → у профілі приєднання Chrome MCP немає відкритих локальних вкладок Chrome. +- `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста gateway. +- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для приєднання не має досяжної цілі, або HTTP endpoint відповів, але CDP WebSocket усе одно не вдалося відкрити. +- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні gateway відсутній повний пакет Playwright; знімки ARIA і базові знімки сторінки все ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-селекторами та експорт PDF залишаються недоступними. +- `fullPage is not supported for element screenshots` → запит screenshot поєднав `--full-page` з `--ref` або `--element`. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики screenshot для Chrome MCP / `existing-session` мають використовувати захоплення сторінки або snapshot `--ref`, а не CSS `--element`. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooks завантаження файлів у Chrome MCP потребують snapshot refs, а не CSS-селекторів. +- `existing-session file uploads currently support one file at a time.` → для профілів Chrome MCP надсилайте одне завантаження за виклик. +- `existing-session dialog handling does not support timeoutMs.` → hooks діалогів у профілях Chrome MCP не підтримують перевизначення timeout. +- `response body is not supported for existing-session profiles yet.` → `responsebody` поки що потребує керованого браузера або сирого профілю CDP. +- застарілі перевизначення viewport / dark-mode / locale / offline для профілів лише для приєднання або віддалених CDP-профілів → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування та скинути стан емуляції Playwright/CDP без перезапуску всього gateway. Пов’язане: @@ -437,7 +437,7 @@ openclaw doctor ## Якщо ви оновилися і щось раптово зламалося -Більшість проблем після оновлення — це дрейф конфігурації або суворіші типові налаштування, які тепер примусово застосовуються. +Більшість проблем після оновлення — це дрейф конфігурації або суворіші стандартні значення, які тепер застосовуються. ### 1) Змінилася поведінка auth і перевизначення URL @@ -450,15 +450,15 @@ openclaw config get gateway.auth.mode Що перевірити: -- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на remote, тоді як локальний сервіс працює нормально. -- Явні виклики `--url` не використовують збережені облікові дані як резервний варіант. +- Якщо `gateway.mode=remote`, виклики CLI можуть спрямовуватися на remote, тоді як ваша локальна служба працює нормально. +- Явні виклики `--url` не переходять до збережених облікових даних. -Типові ознаки: +Поширені ознаки: -- `gateway connect failed:` → неправильна ціль URL. +- `gateway connect failed:` → неправильна URL-ціль. - `unauthorized` → endpoint досяжний, але auth неправильна. -### 2) Обмеження bind і auth стали суворішими +### 2) Guardrails для bind і auth стали суворішими ```bash openclaw config get gateway.bind @@ -470,13 +470,13 @@ openclaw logs --follow Що перевірити: -- Для bind не до loopback (`lan`, `tailnet`, `custom`) потрібен дійсний шлях auth gateway: auth через shared token/password або коректно налаштоване розгортання non-loopback `trusted-proxy`. +- Bind не до loopback (`lan`, `tailnet`, `custom`) потребують коректного шляху auth gateway: shared token/password auth або правильно налаштованого розгортання `trusted-proxy` не на loopback. - Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. -Типові ознаки: +Поширені ознаки: -- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху auth gateway. -- `RPC probe: failed` while runtime is running → gateway живий, але недоступний з поточною auth/url. +- `refusing to bind gateway ... without auth` → bind не до loopback без коректного шляху auth gateway. +- `RPC probe: failed` коли runtime працює → gateway живий, але недоступний із поточними auth/url. ### 3) Змінився стан pairing та ідентичності пристрою @@ -489,15 +489,15 @@ openclaw doctor Що перевірити: -- Очікують схвалення пристрої для dashboard/nodes. -- Очікують схвалення DM pairing після змін політики або ідентичності. +- Pending-схвалення пристроїв для dashboard/nodes. +- Pending-схвалення pairing для DM після змін політики або ідентичності. -Типові ознаки: +Поширені ознаки: -- `device identity required` → вимоги device auth не виконано. +- `device identity required` → auth пристрою не виконано. - `pairing required` → відправника/пристрій потрібно схвалити. -Якщо після перевірок конфігурація сервісу й runtime усе ще не збігаються, перевстановіть метадані сервісу з того самого каталогу profile/state: +Якщо після перевірок конфігурація служби й runtime усе ще не збігаються, перевстановіть метадані служби з того самого каталогу профілю/стану: ```bash openclaw gateway install --force diff --git a/docs/uk/help/troubleshooting.md b/docs/uk/help/troubleshooting.md index 7463ce96f..7526b5d7e 100644 --- a/docs/uk/help/troubleshooting.md +++ b/docs/uk/help/troubleshooting.md @@ -1,21 +1,21 @@ --- read_when: - OpenClaw не працює, і вам потрібен найшвидший шлях до виправлення - - Ви хочете пройти процес тріажу перед зануренням у докладні інструкції -summary: Центр усунення несправностей OpenClaw зі швидкою діагностикою за симптомами + - Вам потрібен процес первинної діагностики, перш ніж переходити до детальних інструкцій +summary: Центр усунення несправностей OpenClaw за симптомами title: Загальне усунення несправностей x-i18n: - generated_at: "2026-04-07T14:58:59Z" + generated_at: "2026-04-10T20:41:24Z" model: gpt-5.4 provider: openai - source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3 + source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a source_path: help/troubleshooting.md workflow: 15 --- # Усунення несправностей -Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку тріажу. +Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку діагностики. ## Перші 60 секунд @@ -33,45 +33,47 @@ openclaw logs --follow Хороший результат в одному рядку: -- `openclaw status` → показує налаштовані канали та відсутність явних помилок автентифікації. +- `openclaw status` → показує налаштовані канали та відсутність очевидних помилок автентифікації. - `openclaw status --all` → повний звіт наявний і ним можна поділитися. - `openclaw gateway probe` → очікувана ціль gateway доступна (`Reachable: yes`). `RPC: limited - missing scope: operator.read` означає погіршену діагностику, а не збій підключення. - `openclaw gateway status` → `Runtime: running` і `RPC probe: ok`. -- `openclaw doctor` → немає блокувальних помилок конфігурації/сервісу. -- `openclaw channels status --probe` → доступний gateway повертає живий стан транспорту для кожного облікового запису разом із результатами probe/audit, такими як `works` або `audit ok`; якщо gateway недоступний, команда повертається до зведень лише за конфігурацією. +- `openclaw doctor` → немає блокувальних помилок конфігурації або сервісу. +- `openclaw channels status --probe` → доступний gateway повертає поточний + стан транспорту для кожного облікового запису разом із результатами probe/audit, такими як `works` або `audit ok`; якщо + gateway недоступний, команда переходить до зведень лише за конфігурацією. - `openclaw logs --follow` → стабільна активність, без повторюваних фатальних помилок. -## 429 для довгого контексту Anthropic +## Anthropic long context 429 Якщо ви бачите: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`, перейдіть до [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). -## Локальний OpenAI-compatible backend працює напряму, але не працює в OpenClaw +## Локальний OpenAI-compatible бекенд працює напряму, але не працює в OpenClaw -Якщо ваш локальний або self-hosted backend `/v1` відповідає на малі прямі probe до -`/v1/chat/completions`, але завершується помилкою в `openclaw infer model run` або під час звичайних +Якщо ваш локальний або самостійно розміщений `/v1` бекенд відповідає на малі прямі +перевірки `/v1/chat/completions`, але завершується помилкою в `openclaw infer model run` або під час звичайних ходів агента: -1. Якщо помилка згадує, що `messages[].content` має бути рядком, установіть +1. Якщо помилка згадує, що `messages[].content` очікує рядок, встановіть `models.providers..models[].compat.requiresStringContent: true`. -2. Якщо backend усе ще завершується помилкою лише під час ходів агента OpenClaw, установіть +2. Якщо бекенд усе ще не працює лише під час ходів агента OpenClaw, встановіть `models.providers..models[].compat.supportsTools: false` і повторіть спробу. -3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw аварійно завершують роботу - backend, розглядайте решту проблеми як обмеження висхідної моделі/сервера та - продовжуйте в докладній інструкції: +3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw призводять до збою + бекенда, розглядайте решту проблеми як обмеження моделі/сервера на стороні джерела + і перейдіть до детальної інструкції: [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/uk/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -## Не вдається встановити plugin через відсутні openclaw extensions +## Не вдається встановити плагін через відсутні openclaw extensions -Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет plugin +Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет плагіна використовує стару структуру, яку OpenClaw більше не приймає. -Виправлення в пакеті plugin: +Виправлення в пакеті плагіна: 1. Додайте `openclaw.extensions` до `package.json`. 2. Спрямуйте записи на зібрані runtime-файли (зазвичай `./dist/index.js`). -3. Перевидайте plugin і знову виконайте `openclaw plugins install `. +3. Повторно опублікуйте плагін і знову виконайте `openclaw plugins install `. Приклад: @@ -85,28 +87,28 @@ openclaw logs --follow } ``` -Довідка: [Архітектура plugin](/uk/plugins/architecture) +Довідка: [Архітектура плагінів](/uk/plugins/architecture) ## Дерево рішень ```mermaid flowchart TD - A[OpenClaw is not working] --> B{What breaks first} - B --> C[No replies] - B --> D[Dashboard or Control UI will not connect] - B --> E[Gateway will not start or service not running] - B --> F[Channel connects but messages do not flow] - B --> G[Cron or heartbeat did not fire or did not deliver] - B --> H[Node is paired but camera canvas screen exec fails] - B --> I[Browser tool fails] + A[OpenClaw не працює] --> B{Що ламається першим} + B --> C[Немає відповідей] + B --> D[Dashboard або Control UI не підключається] + B --> E[Gateway не запускається або сервіс не запущено] + B --> F[Канал підключається, але повідомлення не проходять] + B --> G[Cron або heartbeat не спрацював чи не доставив] + B --> H[Node з'єднано, але інструмент camera canvas screen exec не працює] + B --> I[Не працює інструмент браузера] - C --> C1[/No replies section/] - D --> D1[/Control UI section/] - E --> E1[/Gateway section/] - F --> F1[/Channel flow section/] - G --> G1[/Automation section/] - H --> H1[/Node tools section/] - I --> I1[/Browser section/] + C --> C1[/Розділ Немає відповідей/] + D --> D1[/Розділ Control UI/] + E --> E1[/Розділ Gateway/] + F --> F1[/Розділ Потік каналу/] + G --> G1[/Розділ Автоматизація/] + H --> H1[/Розділ Інструменти node/] + I --> I1[/Розділ Браузер/] ``` @@ -123,16 +125,16 @@ flowchart TD - `Runtime: running` - `RPC probe: ok` - - Ваш канал показує підключений транспорт і, де підтримується, `works` або `audit ok` у `channels status --probe` - - Відправник позначений як схвалений (або для DM політика відкрита/allowlist) + - Ваш канал показує підключений транспорт і, де це підтримується, `works` або `audit ok` у `channels status --probe` + - Відправника показано як схваленого (або політика DM є відкритою/зі списком дозволених) Поширені сигнатури в логах: - - `drop guild message (mention required` → обмеження згадки заблокувало повідомлення в Discord. - - `pairing request` → відправника не схвалено, і він очікує схвалення pairing у DM. + - `drop guild message (mention required` → обмеження за згадкою заблокувало повідомлення в Discord. + - `pairing request` → відправник не схвалений і очікує схвалення DM pairing. - `blocked` / `allowlist` у логах каналу → відправник, кімната або група відфільтровані. - Докладні сторінки: + Детальні сторінки: - [/gateway/troubleshooting#no-replies](/uk/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/uk/channels/troubleshooting) @@ -140,7 +142,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -151,22 +153,27 @@ flowchart TD Хороший результат виглядає так: - - `Dashboard: http://...` показується в `openclaw gateway status` + - `Dashboard: http://...` показано в `openclaw gateway status` - `RPC probe: ok` - У логах немає циклу автентифікації Поширені сигнатури в логах: - `device identity required` → HTTP/незахищений контекст не може завершити автентифікацію пристрою. - - `origin not allowed` → `Origin` браузера не дозволений для цілі gateway Control UI. - - `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → одна повторна спроба з довіреним токеном пристрою може відбутися автоматично. - - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із paired токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний ними набір scope. - - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як limiter зафіксує помилку, тому друга одночасна невдала повторна спроба вже може показати `retry later`. - - `too many failed authentication attempts (retry later)` з браузерного джерела localhost → повторні невдалі спроби з того самого `Origin` тимчасово блокуються; інше джерело localhost використовує окремий bucket. - - повторюване `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий paired токен пристрою. - - `gateway connect failed:` → UI спрямовано на неправильний URL/порт або gateway недоступний. + - `origin not allowed` → `Origin` браузера не дозволений для цілі gateway у Control UI. + - `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → одна повторна спроба з довіреним токеном пристрою може виконуватися автоматично. + - Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом із прив’язаним + токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають + свій запитаний набір scope. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого + `{scope, ip}` серіалізуються до того, як limiter фіксує збій, тож + друга одночасна невдала повторна спроба вже може показати `retry later`. + - `too many failed authentication attempts (retry later)` з браузерного origin localhost → повторні + невдалі спроби з того самого `Origin` тимчасово блокуються; інший origin localhost використовує окремий bucket. + - повторювані `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий токен прив’язаного пристрою. + - `gateway connect failed:` → UI націлений на неправильний URL/порт або gateway недоступний. - Докладні сторінки: + Детальні сторінки: - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/uk/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/web/control-ui) @@ -174,7 +181,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -191,11 +198,11 @@ flowchart TD Поширені сигнатури в логах: - - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим gateway є remote, або у файлі конфігурації відсутня позначка локального режиму, і його слід виправити. + - `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим gateway є remote, або у файлі конфігурації відсутня позначка локального режиму, і його слід відновити. - `refusing to bind gateway ... without auth` → прив’язування не до loopback без дійсного шляху автентифікації gateway (токен/пароль або trusted-proxy, якщо налаштовано). - - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнятий. + - `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнято. - Докладні сторінки: + Детальні сторінки: - [/gateway/troubleshooting#gateway-service-not-running](/uk/gateway/troubleshooting#gateway-service-not-running) - [/gateway/background-process](/uk/gateway/background-process) @@ -214,24 +221,24 @@ flowchart TD Хороший результат виглядає так: - - Транспорт каналу підключено. + - Транспорт каналу підключений. - Перевірки pairing/allowlist проходять. - Згадки виявляються там, де це потрібно. Поширені сигнатури в логах: - - `mention required` → обмеження згадки в групі заблокувало обробку. - - `pairing` / `pending` → відправника DM ще не схвалено. + - `mention required` → обмеження за згадкою в групі заблокувало обробку. + - `pairing` / `pending` → відправник DM ще не схвалений. - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → проблема з токеном дозволів каналу. - Докладні сторінки: + Детальні сторінки: - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/uk/gateway/troubleshooting#channel-connected-messages-not-flowing) - [/channels/troubleshooting](/uk/channels/troubleshooting) - + ```bash openclaw status openclaw gateway status @@ -243,28 +250,29 @@ flowchart TD Хороший результат виглядає так: - - `cron.status` показує, що cron увімкнено і є наступне пробудження. + - `cron.status` показує, що його ввімкнено, і вказує наступне пробудження. - `cron runs` показує нещодавні записи `ok`. - - Heartbeat увімкнено і він не поза активними годинами. + - Heartbeat увімкнено, і він не поза активними годинами. Поширені сигнатури в логах: -- `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. -- `heartbeat skipped` з `reason=quiet-hours` → поза налаштованими активними годинами. -- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній каркас або каркас лише із заголовками. -- `heartbeat skipped` з `reason=no-tasks-due` → у `HEARTBEAT.md` активний режим завдань, але ще не настав час для жодного з інтервалів завдань. -- `heartbeat skipped` з `reason=alerts-disabled` → усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені). -- `requests-in-flight` → основна смуга зайнята; пробудження heartbeat було відкладено. - `unknown accountId` → цільовий account heartbeat для доставки не існує. + - `cron: scheduler disabled; jobs will not run automatically` → cron вимкнено. + - `heartbeat skipped` з `reason=quiet-hours` → поза налаштованими активними годинами. + - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній каркас або лише заголовки. + - `heartbeat skipped` з `reason=no-tasks-due` → режим завдань `HEARTBEAT.md` активний, але жоден із інтервалів завдань ще не настав. + - `heartbeat skipped` з `reason=alerts-disabled` → усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені). + - `requests-in-flight` → основна лінія зайнята; пробудження heartbeat було відкладено. + - `unknown accountId` → цільовий обліковий запис доставки heartbeat не існує. - Докладні сторінки: + Детальні сторінки: - - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/uk/gateway/troubleshooting#cron-and-heartbeat-delivery) - - [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting) - - [/gateway/heartbeat](/uk/gateway/heartbeat) + - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/uk/gateway/troubleshooting#cron-and-heartbeat-delivery) + - [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting) + - [/gateway/heartbeat](/uk/gateway/heartbeat) - + ```bash openclaw status openclaw gateway status @@ -275,18 +283,18 @@ flowchart TD Хороший результат виглядає так: - - Node вказано як підключений і paired для ролі `node`. - - Для команди, яку ви викликаєте, існує capability. - - Для інструмента надано стан дозволу. + - Node вказано як підключений і прив’язаний для ролі `node`. + - Для команди, яку ви викликаєте, наявна capability. + - Для інструмента надано потрібний стан дозволів. Поширені сигнатури в логах: - `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок node на передній план. - - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено або він відсутній. - - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. - - `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist exec. + - `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено або його бракує. + - `SYSTEM_RUN_DENIED: approval required` → схвалення exec очікує підтвердження. + - `SYSTEM_RUN_DENIED: allowlist miss` → команда відсутня у списку дозволених для exec. - Докладні сторінки: + Детальні сторінки: - [/gateway/troubleshooting#node-paired-tool-fails](/uk/gateway/troubleshooting#node-paired-tool-fails) - [/nodes/troubleshooting](/uk/nodes/troubleshooting) @@ -294,7 +302,7 @@ flowchart TD - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -304,14 +312,14 @@ flowchart TD Що змінилося: - - Якщо `tools.exec.host` не встановлено, значенням за замовчуванням є `auto`. - - `host=auto` визначається як `sandbox`, коли активний runtime sandbox, інакше як `gateway`. - - `host=auto` відповідає лише за маршрутизацію; поведінка "YOLO" без запиту визначається `security=full` разом із `ask=off` на gateway/node. - - Для `gateway` і `node` невстановлений `tools.exec.security` за замовчуванням має значення `full`. - - Невстановлений `tools.exec.ask` за замовчуванням має значення `off`. - - Результат: якщо ви бачите схвалення, якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням. + - Якщо `tools.exec.host` не задано, значенням за замовчуванням є `auto`. + - `host=auto` розв’язується в `sandbox`, коли активне sandbox runtime, і в `gateway` у протилежному разі. + - `host=auto` відповідає лише за маршрутизацію; поведінка "YOLO" без запиту зумовлюється `security=full` разом із `ask=off` на gateway/node. + - У `gateway` і `node` незадане `tools.exec.security` за замовчуванням має значення `full`. + - Незадане `tools.exec.ask` за замовчуванням має значення `off`. + - Результат: якщо ви бачите схвалення, якийсь локальний для хоста або для сеансу policy посилив exec порівняно з поточними значеннями за замовчуванням. - Відновлення поточної поведінки за замовчуванням без схвалень: + Відновити поточну типову поведінку без схвалення: ```bash openclaw config set tools.exec.host gateway @@ -322,21 +330,21 @@ flowchart TD Безпечніші альтернативи: - - Встановіть лише `tools.exec.host=gateway`, якщо вам просто потрібна стабільна маршрутизація на хості. - - Використовуйте `security=allowlist` з `ask=on-miss`, якщо хочете exec на хості, але також хочете перевірку у разі промахів по allowlist. - - Увімкніть режим sandbox, якщо хочете, щоб `host=auto` знову визначався як `sandbox`. + - Встановіть лише `tools.exec.host=gateway`, якщо вам потрібна просто стабільна маршрутизація хоста. + - Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо хочете виконання на хості, але все ще бажаєте перевірку у випадках промаху по allowlist. + - Увімкніть режим sandbox, якщо хочете, щоб `host=auto` знову розв’язувався в `sandbox`. Поширені сигнатури в логах: - `Approval required.` → команда очікує на `/approve ...`. - - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec на хості node. - - `exec host=sandbox requires a sandbox runtime for this session` → неявно/явно вибрано sandbox, але режим sandbox вимкнено. + - `SYSTEM_RUN_DENIED: approval required` → очікує схвалення для node-host exec. + - `exec host=sandbox requires a sandbox runtime for this session` → неявно або явно вибрано sandbox, але режим sandbox вимкнено. - Докладні сторінки: + Детальні сторінки: - [/tools/exec](/uk/tools/exec) - [/tools/exec-approvals](/uk/tools/exec-approvals) - - [/gateway/security#runtime-expectation-drift](/uk/gateway/security#runtime-expectation-drift) + - [/gateway/security#what-the-audit-checks-high-level](/uk/gateway/security#what-the-audit-checks-high-level) @@ -351,22 +359,22 @@ flowchart TD Хороший результат виглядає так: - - Стан браузера показує `running: true` і вибраний браузер/профіль. - - `openclaw` запускається, або `user` бачить локальні вкладки Chrome. + - Статус браузера показує `running: true` і вибраний браузер/профіль. + - `openclaw` запускається, або `user` може бачити локальні вкладки Chrome. Поширені сигнатури в логах: - - `unknown command "browser"` або `unknown command 'browser'` → `plugins.allow` установлено, але воно не містить `browser`. - - `Failed to start Chrome CDP on port` → не вдалося запустити локальний браузер Chrome CDP. - - `browser.executablePath not found` → налаштований шлях до бінарного файла неправильний. + - `unknown command "browser"` або `unknown command 'browser'` → задано `plugins.allow`, і воно не містить `browser`. + - `Failed to start Chrome CDP on port` → не вдалося запустити локальний Chrome CDP на порту. + - `browser.executablePath not found` → указаний шлях до виконуваного файла неправильний. - `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему. - - `browser.cdpUrl has invalid port` → налаштований URL CDP містить неправильний або позадіапазонний порт. - - `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. + - `browser.cdpUrl has invalid port` → налаштований URL CDP має неправильний або неприпустимий порт. + - `No Chrome tabs found for profile="user"` → у профілі приєднання Chrome MCP немає відкритих локальних вкладок Chrome. - `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з цього хоста. - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має живої цілі CDP. - - застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію та скинути стан емуляції без перезапуску gateway. + - застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активний сеанс керування й скинути стан емуляції без перезапуску gateway. - Докладні сторінки: + Детальні сторінки: - [/gateway/troubleshooting#browser-tool-fails](/uk/gateway/troubleshooting#browser-tool-fails) - [/tools/browser#missing-browser-command-or-tool](/uk/tools/browser#missing-browser-command-or-tool) @@ -374,12 +382,13 @@ flowchart TD - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting) + -## Пов’язані матеріали +## Пов’язане - [FAQ](/uk/help/faq) — поширені запитання -- [Усунення несправностей gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з gateway -- [Doctor](/uk/gateway/doctor) — автоматичні перевірки стану та виправлення +- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з gateway +- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану та виправлення - [Усунення несправностей каналів](/uk/channels/troubleshooting) — проблеми з підключенням каналів - [Усунення несправностей автоматизації](/uk/automation/cron-jobs#troubleshooting) — проблеми з cron і heartbeat diff --git a/docs/uk/plugins/sdk-channel-plugins.md b/docs/uk/plugins/sdk-channel-plugins.md index 1bba9615e..f1557f464 100644 --- a/docs/uk/plugins/sdk-channel-plugins.md +++ b/docs/uk/plugins/sdk-channel-plugins.md @@ -1,106 +1,104 @@ --- read_when: - - Ви створюєте новий плагін каналу повідомлень + - Ви створюєте новий плагін каналу обміну повідомленнями - Ви хочете підключити OpenClaw до платформи обміну повідомленнями - Вам потрібно зрозуміти поверхню адаптера ChannelPlugin sidebarTitle: Channel Plugins -summary: Покроковий посібник зі створення плагіна каналу повідомлень для OpenClaw +summary: Покроковий посібник зі створення плагіна каналу обміну повідомленнями для OpenClaw title: Створення плагінів каналів x-i18n: - generated_at: "2026-04-07T20:09:23Z" + generated_at: "2026-04-10T20:41:27Z" model: gpt-5.4 provider: openai - source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f + source_hash: 8a026e924f9ae8a3ddd46287674443bcfccb0247be504261522b078e1f440aef source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Створення плагінів каналів -Цей посібник допоможе вам створити плагін каналу, який підключає OpenClaw до -платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із -безпекою DM, сполученням, потоками відповідей і вихідними повідомленнями. +Цей посібник покроково пояснює створення плагіна каналу, який підключає OpenClaw до +платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із захистом DM, +сполученням, потоками відповідей та вихідними повідомленнями. Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Початок роботи](/uk/plugins/building-plugins) про базову структуру пакета - та налаштування маніфесту. + [Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою + структурою пакета та налаштуванням маніфесту. ## Як працюють плагіни каналів -Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw -зберігає один спільний інструмент `message` у ядрі. Вашому плагіну належать: +Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw зберігає +один спільний інструмент `message` у core. Ваш плагін відповідає за: -- **Конфігурація** — визначення облікового запису та майстер налаштування -- **Безпека** — політика DM і списки дозволених +- **Конфігурацію** — визначення облікового запису та майстер налаштування +- **Безпеку** — політику DM і allowlist-списки - **Сполучення** — потік підтвердження DM -- **Граматика сесії** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами потоків і резервними батьківськими елементами -- **Вихідні повідомлення** — надсилання тексту, медіа й опитувань на платформу -- **Потоки** — як групуються відповіді +- **Граматику сесій** — як ідентифікатори розмов, специфічні для провайдера, відображаються на базові чати, ідентифікатори потоків і резервні батьківські значення +- **Вихідні повідомлення** — надсилання тексту, медіа та опитувань на платформу +- **Потоковість** — як організовуються потоки відповідей -Ядру належать спільний інструмент message, зв’язування промптів, зовнішня форма -ключа сесії, загальний облік `:thread:` і диспетчеризація. +Core відповідає за спільний інструмент повідомлень, підключення prompt, зовнішню форму ключа сесії, +загальне ведення обліку `:thread:` та диспетчеризацію. -Якщо ваша платформа зберігає додаткову область дії в ідентифікаторах розмов, -залишайте цей розбір у плагіні за допомогою -`messaging.resolveSessionConversation(...)`. Це канонічний хук для -зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим -ідентифікатором потоку, явним `baseConversationId` і будь-якими -`parentConversationCandidates`. +Якщо ваша платформа зберігає додаткову область видимості всередині ідентифікаторів розмов, +залишайте цей парсинг у плагіні за допомогою `messaging.resolveSessionConversation(...)`. Це канонічний хук +для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим ідентифікатором потоку, +явним `baseConversationId` та будь-якими `parentConversationCandidates`. Коли ви повертаєте `parentConversationCandidates`, зберігайте їхній порядок від найвужчого батьківського елемента до найширшої/базової розмови. -Вбудовані плагіни, яким потрібен той самий розбір до запуску реєстру каналів, -також можуть експортувати файл верхнього рівня `session-key-api.ts` із -відповідним експортом `resolveSessionConversation(...)`. Ядро використовує цю -безпечну для завантаження поверхню лише тоді, коли реєстр плагінів під час -виконання ще недоступний. +Вбудовані плагіни, яким потрібен той самий парсинг до запуску реєстру каналів, +також можуть експортувати файл верхнього рівня `session-key-api.ts` з відповідним +експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для bootstrap поверхню +лише тоді, коли реєстр runtime-плагінів ще недоступний. -`messaging.resolveParentConversationCandidates(...)` залишається доступним як -застарілий резервний варіант сумісності, коли плагіну потрібні лише резервні -батьківські елементи поверх загального/raw id. Якщо наявні обидва хуки, ядро -спочатку використовує +`messaging.resolveParentConversationCandidates(...)` залишається доступним як застарілий +резервний механізм сумісності, коли плагіну потрібні лише резервні батьківські значення +поверх загального/raw id. Якщо існують обидва хуки, core спочатку використовує `resolveSessionConversation(...).parentConversationCandidates` і лише потім повертається до `resolveParentConversationCandidates(...)`, якщо канонічний хук -їх не містить. +їх не вказує. -## Підтвердження та можливості каналів +## Підтвердження та можливості каналу Більшості плагінів каналів не потрібен код, специфічний для підтверджень. -- Ядру належать `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальна резервна доставка. -- Надавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, коли каналу потрібна поведінка, специфічна для підтверджень. -- `ChannelPlugin.approvals` видалено. Розміщуйте факти доставки/нативного відтворення/автентифікації підтверджень у `approvalCapability`. -- `plugin.auth` — лише login/logout; ядро більше не читає з цього об’єкта хуки автентифікації підтверджень. -- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — канонічний шов автентифікації підтверджень. -- Використовуйте `approvalCapability.getActionAvailabilityState` для доступності автентифікації підтверджень у тому самому чаті. -- Якщо ваш канал надає нативні підтвердження exec, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану поверхні ініціювання/нативного клієнта, коли він відрізняється від автентифікації підтверджень у тому самому чаті. Ядро використовує цей хук, специфічний для exec, щоб розрізняти `enabled` і `disabled`, вирішувати, чи підтримує канал ініціювання нативні підтвердження exec, і включати канал до підказок щодо резервного варіанту для нативного клієнта. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку. -- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для специфічної для каналу поведінки життєвого циклу payload, наприклад приховування дубльованих локальних підказок підтвердження або надсилання індикаторів набору перед доставкою. -- Використовуйте `approvalCapability.delivery` лише для маршрутизації нативних підтверджень або придушення резервної доставки. -- Використовуйте `approvalCapability.nativeRuntime` для фактів нативних підтверджень, що належать каналу. Зберігайте його лінивим у гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру збирати життєвий цикл підтверджень. -- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтверджень замість спільного рендерера. -- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь для вимкненого шляху пояснювала точні параметри конфігурації, потрібні для ввімкнення нативних підтверджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами повинні відтворювати шляхи з областю облікового запису, як-от `channels..accounts..execApprovals.*`, а не значення верхнього рівня за замовчуванням. -- Якщо канал може виводити стабільні DM-ідентичності, схожі на власника, з наявної конфігурації, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання специфічної для підтверджень логіки ядра. -- Якщо каналу потрібна доставка нативних підтверджень, зосередьте код каналу на нормалізації цілі та фактах транспорту/подання. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте специфічні для каналу факти за `approvalCapability.nativeRuntime`, ідеально через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб ядро могло збирати обробник і володіти фільтрацією запитів, маршрутизацією, дедуплікацією, строком дії, підпискою gateway і сповіщеннями про маршрутизацію в інше місце. `nativeRuntime` поділено на кілька менших швів: -- `availability` — чи налаштований обліковий запис і чи слід обробляти запит -- `presentation` — зіставлення спільної view model підтвердження з нативними payload у станах pending/resolved/expired або фінальними діями -- `transport` — підготовка цілей і надсилання/оновлення/видалення нативних повідомлень підтвердження +- Core відповідає за `/approve` у тому самому чаті, спільні payload-кнопок підтвердження та загальну резервну доставку. +- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, якщо каналу потрібна поведінка, специфічна для підтверджень. +- `ChannelPlugin.approvals` видалено. Розміщуйте факти доставки/нативного режиму/рендерингу/автентифікації підтверджень у `approvalCapability`. +- `plugin.auth` призначений лише для login/logout; core більше не читає хуки автентифікації підтверджень із цього об’єкта. +- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічна поверхня для auth підтверджень. +- Використовуйте `approvalCapability.getActionAvailabilityState` для доступності auth підтверджень у тому самому чаті. +- Якщо ваш канал надає нативні exec-підтвердження, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану ініціювальної поверхні/нативного клієнта, коли він відрізняється від auth підтвердження в тому самому чаті. Core використовує цей exec-специфічний хук, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціювальний канал нативні exec-підтвердження, і включати канал до інструкцій резервного сценарію нативного клієнта. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку. +- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дубльованих локальних prompt-підтверджень або надсилання індикаторів набору тексту перед доставкою. +- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації підтверджень або придушення резервної доставки. +- Використовуйте `approvalCapability.nativeRuntime` для фактів нативних підтверджень, що належать каналу. Зберігайте його лінивим на гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи core зібрати життєвий цикл підтвердження. +- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтвердження замість спільного рендерера. +- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь на вимкнений шлях пояснювала точні параметри конфігурації, потрібні для ввімкнення нативних exec-підтверджень. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають рендерити шляхи з областю облікового запису, такі як `channels..accounts..execApprovals.*`, замість дефолтів верхнього рівня. +- Якщо канал може вивести стабільні DM-ідентичності на кшталт власника з наявної конфігурації, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки підтверджень у core. +- Якщо каналу потрібна нативна доставка підтверджень, зосередьте код каналу на нормалізації цілі та фактах транспорту/представлення. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте факти, специфічні для каналу, за `approvalCapability.nativeRuntime`, бажано через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб core міг зібрати обробник і відповідати за фільтрацію запитів, маршрутизацію, dedupe, строки дії, підписку gateway та сповіщення про маршрутизацію в інше місце. `nativeRuntime` поділено на кілька менших поверхонь: +- `availability` — чи налаштований обліковий запис і чи потрібно обробляти запит +- `presentation` — відображення спільної view model підтверджень у нативні payload у станах pending/resolved/expired або фінальні дії +- `transport` — підготовка цілей, а також надсилання/оновлення/видалення нативних повідомлень підтвердження - `interactions` — необов’язкові хуки bind/unbind/clear-action для нативних кнопок або реакцій - `observe` — необов’язкові хуки діагностики доставки -- Якщо каналу потрібні об’єкти, що належать runtime, наприклад клієнт, токен, застосунок Bolt або отримувач webhook, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-контексту дозволяє ядру завантажувати обробники, керовані можливостями, зі стану запуску каналу без додавання обгорткового glue-коду, специфічного для підтверджень. -- Звертайтеся до нижчорівневих `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли шов, керований можливостями, ще недостатньо виразний. -- Канали з нативними підтвердженнями повинні маршрутизувати через ці helper-и і `accountId`, і `approvalKind`. `accountId` зберігає політику підтверджень для кількох облікових записів у правильній області бот-облікового запису, а `approvalKind` зберігає для каналу доступну поведінку підтверджень exec або плагіна без жорстко закодованих гілок у ядрі. -- Тепер ядру також належать сповіщення про перемаршрутизацію підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт "підтвердження перейшло в DM / інший канал" із `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні helper-и можливостей підтверджень і дозвольте ядру агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад у чат ініціювання. -- Зберігайте наскрізно тип delivered approval id. Нативні клієнти не повинні вгадувати або переписувати маршрутизацію підтверджень exec чи plugin зі стану, локального для каналу. +- Якщо каналу потрібні об’єкти, що належать runtime, наприклад клієнт, токен, застосунок Bolt або отримувач webhook, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-контексту дає core змогу bootstrap-ити обробники на основі можливостей зі стану запуску каналу без додавання обгорток, специфічних для підтверджень. +- Звертайтеся до нижчорівневих `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли поверхня, заснована на можливостях, ще недостатньо виразна. +- Канали з нативними підтвердженнями мають передавати через ці helper-и і `accountId`, і `approvalKind`. `accountId` зберігає політику підтверджень для кількох облікових записів у межах правильного облікового запису бота, а `approvalKind` зберігає поведінку exec чи плагіна доступною для каналу без жорстко закодованих гілок у core. +- Тепер core також відповідає за сповіщення про повторну маршрутизацію підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт «підтвердження перейшло в DM / інший канал» із `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні helper-и можливостей підтверджень і дозвольте core агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад в ініціювальний чат. +- Зберігайте тип ідентифікатора доставленого підтвердження від початку до кінця. Нативні клієнти не повинні + вгадувати або переписувати маршрутизацію exec чи plugin підтвердження на основі локального стану каналу. - Різні типи підтверджень можуть навмисно відкривати різні нативні поверхні. - Поточні вбудовані приклади: - - Slack зберігає доступною нативну маршрутизацію підтверджень як для exec, так і для plugin id. - - Matrix зберігає ту саму нативну маршрутизацію DM/каналу та UX реакцій для підтверджень exec і plugin, водночас дозволяючи автентифікації відрізнятися за типом підтвердження. -- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має надавати перевагу побудовнику можливостей і експортувати `approvalCapability` у плагіні. + Поточні приклади вбудованих плагінів: + - Slack зберігає нативну маршрутизацію підтверджень доступною як для exec-, так і для plugin-id. + - Matrix зберігає ту саму нативну DM/канальну маршрутизацію та UX реакцій для exec + і plugin-підтверджень, водночас дозволяючи auth відрізнятися за типом підтвердження. +- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має віддавати перевагу builder-у можливостей і експонувати `approvalCapability` у плагіні. -Для гарячих точок входу каналу надавайте перевагу вужчим runtime-підшляхам, -коли вам потрібна лише одна частина цієї родини: +Для гарячих точок входу каналу віддавайте перевагу вужчим runtime-підшляхам, коли вам потрібна лише +одна частина цієї сім’ї: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -112,107 +110,98 @@ x-i18n: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -Так само надавайте перевагу `openclaw/plugin-sdk/setup-runtime`, +Так само віддавайте перевагу `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` і `openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша -узагальнена поверхня. +узагальнювальна поверхня. -Окремо для setup: +Зокрема для setup: -- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper-и setup: - безпечні для імпорту адаптери patch setup (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` охоплює runtime-безпечні helper-и setup: + безпечні для імпорту patched-адаптери setup (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), вивід нотаток пошуку, + `createSetupInputPresenceValidator`), вивід lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries` і делеговані - побудовники setup-proxy -- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шов - адаптера для `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` охоплює побудовники setup - з необов’язковим встановленням, а також кілька примітивів, безпечних для setup: + builder-и setup-proxy +- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузька env-aware поверхня адаптера + для `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` охоплює builder-и setup для необов’язкового встановлення + плюс кілька setup-безпечних примітивів: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Якщо ваш канал підтримує setup або auth на основі env і загальні потоки -startup/config повинні знати ці назви env ще до завантаження runtime, -оголошуйте їх у маніфесті плагіна через `channelEnvVars`. Зберігайте runtime -`envVars` каналу або локальні константи лише для текстів, орієнтованих на операторів. +Якщо ваш канал підтримує setup або auth на основі env, і загальні потоки startup/config +мають знати ці env-імена до завантаження runtime, оголосіть їх у маніфесті плагіна через +`channelEnvVars`. Зберігайте runtime `envVars` каналу або локальні константи лише для копірайту, видимого операторам. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і `splitSetupEntries` -- використовуйте ширший шов `openclaw/plugin-sdk/setup` лише тоді, коли вам - також потрібні важчі спільні helper-и setup/config, наприклад +- використовуйте ширшу поверхню `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні + важчі спільні helper-и setup/config, такі як `moveSingleAccountChannelSectionToDefaultAccount(...)` -Якщо ваш канал хоче лише оголошувати "спочатку встановіть цей плагін" на -поверхнях setup, надавайте перевагу `createOptionalChannelSetupSurface(...)`. -Згенеровані adapter/wizard працюють у безпечному зачиненому режимі щодо -записів конфігурації та фіналізації, а також повторно використовують те саме -повідомлення про необхідність встановлення у валідації, finalize і текстах -посилань на документацію. +Якщо ваш канал лише хоче показувати в поверхнях setup повідомлення «спочатку встановіть цей плагін», +віддавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані +adapter/wizard закриваються з відмовою для записів конфігурації та фіналізації, і повторно використовують +те саме повідомлення про необхідність встановлення для перевірки, finalize і тексту з посиланням на документацію. -Для інших гарячих шляхів каналів надавайте перевагу вузьким helper-ам замість -ширших застарілих поверхонь: +Для інших гарячих шляхів каналу віддавайте перевагу вузьким helper-ам замість ширших застарілих +поверхонь: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` і - `openclaw/plugin-sdk/account-helpers` для конфігурації кількох - облікових записів і резервного варіанта з обліковим записом за - замовчуванням + `openclaw/plugin-sdk/account-helpers` для конфігурації кількох облікових записів та + резервного переходу до облікового запису за замовчуванням - `openclaw/plugin-sdk/inbound-envelope` і - `openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта - вхідних повідомлень і зв’язування record-and-dispatch -- `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей + `openclaw/plugin-sdk/inbound-reply-dispatch` для route/envelope вхідних повідомлень та + зв’язування record-and-dispatch +- `openclaw/plugin-sdk/messaging-targets` для парсингу/зіставлення цілей - `openclaw/plugin-sdk/outbound-media` і - `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа та - делегатів identity/send для вихідних повідомлень -- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу - прив’язок потоків і реєстрації адаптерів -- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще - потрібне застаріле компонування полів payload агента/медіа -- `openclaw/plugin-sdk/telegram-command-config` для нормалізації - користувацьких команд Telegram, валідації дублікатів/конфліктів і стабільного - для fallback контракту конфігурації команд + `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс + делегатів ідентичності/надсилання вихідних повідомлень +- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок потоків + і реєстрації адаптерів +- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібне + застаріле компонування полів payload агента/медіа +- `openclaw/plugin-sdk/telegram-command-config` для нормалізації користувацьких команд Telegram, + перевірки дублікатів/конфліктів і стабільного резервного контракту конфігурації команд -Канали лише з auth зазвичай можуть зупинитися на шляху за замовчуванням: ядро -обробляє підтвердження, а плагін просто надає можливості outbound/auth. Канали -з нативними підтвердженнями, як-от Matrix, Slack, Telegram і користувацькі -chat-транспорти, мають використовувати спільні нативні helper-и замість -створення власного життєвого циклу підтверджень. +Канали лише з auth зазвичай можуть зупинитися на шляху за замовчуванням: core обробляє підтвердження, а плагін лише надає можливості outbound/auth. Канали з нативними підтвердженнями, такі як Matrix, Slack, Telegram і власні транспортні чати, мають використовувати спільні нативні helper-и замість створення власного життєвого циклу підтверджень. ## Політика вхідних згадок -Розділяйте обробку вхідних згадок на два шари: +Зберігайте обробку вхідних згадок розділеною на два рівні: - збирання доказів, що належить плагіну -- спільна оцінка політики +- спільне оцінювання політики -Для спільного шару використовуйте `openclaw/plugin-sdk/channel-inbound`. +Використовуйте `openclaw/plugin-sdk/channel-inbound` для спільного рівня. Добре підходить для локальної логіки плагіна: -- виявлення відповіді боту -- виявлення цитати бота +- виявлення reply-to-bot +- виявлення quoted-bot - перевірки участі в потоці - виключення службових/системних повідомлень -- специфічні для платформи нативні кеші, потрібні для підтвердження участі бота +- платформено-нативні кеші, потрібні для підтвердження участі бота Добре підходить для спільного helper-а: - `requireMention` - явний результат згадки -- список дозволених неявних згадок +- allowlist неявних згадок - обхід для команд - фінальне рішення про пропуск Рекомендований потік: -1. Обчисліть локальні факти згадок. +1. Обчисліть локальні факти згадки. 2. Передайте ці факти в `resolveInboundMentionDecision({ facts, policy })`. -3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у своїй вхідній перевірці. +3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у вашому вхідному шлюзі. ```typescript import { @@ -252,7 +241,7 @@ if (decision.shouldSkip) return; ``` `api.runtime.channel.mentions` надає ті самі спільні helper-и згадок для -вбудованих плагінів каналів, які вже залежать від runtime injection: +вбудованих плагінів каналів, які вже залежать від ін’єкції runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -261,17 +250,17 @@ if (decision.shouldSkip) return; - `resolveInboundMentionDecision` Старіші helper-и `resolveMentionGating*` залишаються в -`openclaw/plugin-sdk/channel-inbound` лише як експорти сумісності. Новий код -повинен використовувати `resolveInboundMentionDecision({ facts, policy })`. +`openclaw/plugin-sdk/channel-inbound` лише як експорт сумісності. Новий код +має використовувати `resolveInboundMentionDecision({ facts, policy })`. ## Покроковий розбір - Створіть стандартні файли плагіна. Поле `channel` у `package.json` - робить цей пакет плагіном каналу. Повну поверхню метаданих пакета див. у - [Налаштування плагіна та конфігурація](/uk/plugins/sdk-setup#openclawchannel): + Створіть стандартні файли плагіна. Поле `channel` у `package.json` — + це те, що робить цей плагін плагіном каналу. Повну поверхню метаданих пакета + див. у [Налаштування плагіна та конфігурація](/uk/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -285,7 +274,7 @@ if (decision.shouldSkip) return; "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Connect OpenClaw to Acme Chat." + "blurb": "Підключіть OpenClaw до Acme Chat." } } } @@ -297,7 +286,7 @@ if (decision.shouldSkip) return; "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Acme Chat channel plugin", + "description": "Плагін каналу Acme Chat", "configSchema": { "type": "object", "additionalProperties": false, @@ -320,9 +309,9 @@ if (decision.shouldSkip) return; - - Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. - Почніть із мінімуму — `id` і `setup` — і додавайте адаптери за потреби. + + Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптера. Почніть із + мінімуму — `id` і `setup` — і додавайте адаптери за потреби. Створіть `src/channel.ts`: @@ -332,7 +321,7 @@ if (decision.shouldSkip) return; createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // your platform API client + import { acmeChatApi } from "./client.js"; // ваш клієнт API платформи type ResolvedAccount = { accountId: string | null; @@ -373,7 +362,7 @@ if (decision.shouldSkip) return; }, }), - // DM security: who can message the bot + // Безпека DM: хто може писати боту security: { dm: { channelKey: "acme-chat", @@ -383,21 +372,21 @@ if (decision.shouldSkip) return; }, }, - // Pairing: approval flow for new DM contacts + // Сполучення: потік підтвердження для нових контактів у DM pairing: { text: { - idLabel: "Acme Chat username", - message: "Send this code to verify your identity:", + idLabel: "Ім’я користувача Acme Chat", + message: "Надішліть цей код, щоб підтвердити свою особу:", notify: async ({ target, code }) => { await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // Threading: how replies are delivered + // Потоковість: як доставляються відповіді threading: { topLevelReplyToMode: "reply" }, - // Outbound: send messages to the platform + // Outbound: надсилання повідомлень на платформу outbound: { attachedResults: { sendText: async (params) => { @@ -417,19 +406,19 @@ if (decision.shouldSkip) return; }); ``` - - Замість ручної реалізації низькорівневих інтерфейсів адаптерів ви - передаєте декларативні параметри, а побудовник їх компонуватиме: + + Замість того щоб вручну реалізовувати низькорівневі інтерфейси адаптера, ви передаєте + декларативні параметри, а builder компонує їх: | Параметр | Що він підключає | | --- | --- | - | `security.dm` | Визначення політики DM з областю дії за полями конфігурації | - | `pairing.text` | Потік текстового сполучення DM з обміном коду | - | `threading` | Визначення режиму reply-to (фіксований, з областю облікового запису або користувацький) | + | `security.dm` | Резолвер безпеки DM з областю дії на основі полів конфігурації | + | `pairing.text` | Потік сполучення через текстовий DM з обміном кодом | + | `threading` | Резолвер режиму відповіді (фіксований, з областю облікового запису або кастомний) | | `outbound.attachedResults` | Функції надсилання, що повертають метадані результату (ідентифікатори повідомлень) | - Ви також можете передавати сирі об’єкти адаптерів замість декларативних - параметрів, якщо вам потрібен повний контроль. + Ви також можете передавати сирі об’єкти адаптера замість декларативних параметрів, + якщо вам потрібен повний контроль. @@ -444,20 +433,20 @@ if (decision.shouldSkip) return; export default defineChannelPluginEntry({ id: "acme-chat", name: "Acme Chat", - description: "Acme Chat channel plugin", + description: "Плагін каналу Acme Chat", plugin: acmeChatPlugin, registerCliMetadata(api) { api.registerCli( ({ program }) => { program .command("acme-chat") - .description("Acme Chat management"); + .description("Керування Acme Chat"); }, { descriptors: [ { name: "acme-chat", - description: "Acme Chat management", + description: "Керування Acme Chat", hasSubcommands: false, }, ], @@ -470,23 +459,21 @@ if (decision.shouldSkip) return; }); ``` - Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, - щоб OpenClaw міг показувати їх у кореневій довідці без активації повного - runtime каналу, тоді як звичайні повні завантаження все одно підхоплюють - ті самі дескриптори для реєстрації реальних команд. Зберігайте - `registerFull(...)` для роботи лише під час runtime. - Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте - префікс, специфічний для плагіна. Простори імен адміністратора ядра - (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються - зарезервованими й завжди зіставляються з `operator.admin`. - `defineChannelPluginEntry` автоматично обробляє поділ за режимами реєстрації. Див. - [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry), щоб - переглянути всі параметри. + Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw + міг показувати їх у кореневій довідці без активації повного runtime каналу, + тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації + реальних команд. Залишайте `registerFull(...)` для роботи лише під час runtime. + Якщо `registerFull(...)` реєструє gateway RPC-методи, використовуйте + префікс, специфічний для плагіна. Простори імен адміністратора core (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди + резолвляться в `operator.admin`. + `defineChannelPluginEntry` автоматично обробляє поділ режимів реєстрації. Усі + параметри див. у [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry). - - Створіть `setup-entry.ts` для полегшеного завантаження під час onboarding: + + Створіть `setup-entry.ts` для легкого завантаження під час онбордингу: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -495,29 +482,28 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw завантажує це замість повної точки входу, коли канал вимкнений - або не налаштований. Це дозволяє не підтягувати важкий runtime-код під час - потоків setup. - Докладніше див. у [Setup і конфігурація](/uk/plugins/sdk-setup#setup-entry). + OpenClaw завантажує цей файл замість повної точки входу, коли канал вимкнений + або не налаштований. Це дозволяє уникнути підтягування важкого runtime-коду під час потоків setup. + Докладніше див. у [Налаштування та конфігурація](/uk/plugins/sdk-setup#setup-entry). - Ваш плагін має отримувати повідомлення з платформи та пересилати їх у + Ваш плагін має отримувати повідомлення з платформи та пересилати їх до OpenClaw. Типовий шаблон — це webhook, який перевіряє запит і - диспетчеризує його через обробник вхідних повідомлень вашого каналу: + диспетчеризує його через вхідний обробник вашого каналу: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // plugin-managed auth (verify signatures yourself) + auth: "plugin", // auth, керований плагіном (перевіряйте підписи самостійно) handler: async (req, res) => { const event = parseWebhookPayload(req); - // Your inbound handler dispatches the message to OpenClaw. - // The exact wiring depends on your platform SDK — - // see a real example in the bundled Microsoft Teams or Google Chat plugin package. + // Ваш вхідний обробник диспетчеризує повідомлення до OpenClaw. + // Точне підключення залежить від SDK вашої платформи — + // реальний приклад див. у вбудованому пакеті плагіна Microsoft Teams або Google Chat. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -529,8 +515,8 @@ if (decision.shouldSkip) return; ``` - Обробка вхідних повідомлень є специфічною для каналу. Кожен плагін каналу - володіє власним вхідним конвеєром. Дивіться на вбудовані плагіни каналів + Обробка вхідних повідомлень залежить від каналу. Кожен плагін каналу відповідає + за власний вхідний pipeline. Подивіться на вбудовані плагіни каналів (наприклад, пакет плагіна Microsoft Teams або Google Chat), щоб побачити реальні шаблони. @@ -538,7 +524,7 @@ if (decision.shouldSkip) return; -Пишіть колоковані тести в `src/channel.test.ts`: +Пишіть colocated тести в `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -583,49 +569,48 @@ if (decision.shouldSkip) return; ## Структура файлів -``` +```text /acme-chat/ ├── package.json # метадані openclaw.channel -├── openclaw.plugin.json # маніфест зі схемою конфігурації +├── openclaw.plugin.json # Маніфест зі схемою конфігурації ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # публічні експорти (необов’язково) -├── runtime-api.ts # внутрішні runtime-експорти (необов’язково) +├── api.ts # Публічні експорти (необов’язково) +├── runtime-api.ts # Внутрішні runtime-експорти (необов’язково) └── src/ ├── channel.ts # ChannelPlugin через createChatChannelPlugin - ├── channel.test.ts # тести - ├── client.ts # клієнт API платформи - └── runtime.ts # сховище runtime (за потреби) + ├── channel.test.ts # Тести + ├── client.ts # Клієнт API платформи + └── runtime.ts # Runtime-сховище (за потреби) ``` ## Розширені теми - - Фіксовані режими відповідей, режими з областю облікового запису або користувацькі + + Фіксовані режими відповіді, режими з областю облікового запису або кастомні режими - + describeMessageTool і виявлення дій - + inferTargetChatType, looksLikeId, resolveTarget - + TTS, STT, медіа, subagent через api.runtime -Деякі вбудовані helper seams усе ще існують для підтримки вбудованих плагінів і -сумісності. Вони не є рекомендованим шаблоном для нових плагінів каналів; -надавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної -поверхні SDK, якщо тільки ви безпосередньо не підтримуєте цю родину -вбудованих плагінів. +Деякі вбудовані поверхні helper-ів усе ще існують для супроводу вбудованих плагінів і +сумісності. Це не рекомендований шаблон для нових плагінів каналів; +віддавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної +поверхні SDK, якщо тільки ви не супроводжуєте безпосередньо цю сім’ю вбудованих плагінів. ## Наступні кроки - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — якщо ваш плагін також надає моделі -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з імпортів за підшляхами +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів за підшляхами - [Тестування SDK](/uk/plugins/sdk-testing) — утиліти тестування та контрактні тести - [Маніфест плагіна](/uk/plugins/manifest) — повна схема маніфесту diff --git a/docs/uk/tools/reactions.md b/docs/uk/tools/reactions.md index 7c55f2fd3..28cd1a911 100644 --- a/docs/uk/tools/reactions.md +++ b/docs/uk/tools/reactions.md @@ -1,21 +1,21 @@ --- read_when: - Робота з реакціями в будь-якому каналі - - Розуміння того, як emoji-реакції відрізняються на різних платформах + - Розуміння того, як реакції з емодзі відрізняються на різних платформах summary: Семантика інструмента реакцій у всіх підтримуваних каналах title: Реакції x-i18n: - generated_at: "2026-04-05T18:20:35Z" + generated_at: "2026-04-10T20:41:24Z" model: gpt-5.4 provider: openai - source_hash: 9af2951eee32e73adb982dbdf39b32e4065993454e9cce2ad23b27565cab4f84 + source_hash: cfac31b7f0effc89cc696e3cf34cd89503ccdbb28996723945025e4b6e159986 source_path: tools/reactions.md workflow: 15 --- # Реакції -Агент може додавати й видаляти emoji-реакції до повідомлень за допомогою інструмента `message` з дією `react`. Поведінка реакцій залежить від каналу. +Агент може додавати й видаляти реакції з емодзі на повідомленнях за допомогою інструмента `message` з дією `react`. Поведінка реакцій залежить від каналу. ## Як це працює @@ -28,20 +28,20 @@ x-i18n: ``` - `emoji` є обов’язковим під час додавання реакції. -- Встановіть `emoji` як порожній рядок (`""`), щоб видалити реакцію(ї) бота. -- Встановіть `remove: true`, щоб видалити конкретне emoji (потрібне непорожнє `emoji`). +- Установіть `emoji` як порожній рядок (`""`), щоб видалити реакцію(ї) бота. +- Установіть `remove: true`, щоб видалити певне емодзі (потрібне непорожнє `emoji`). ## Поведінка в каналах - - Порожнє `emoji` видаляє всі реакції бота на повідомлення. - - `remove: true` видаляє лише вказане emoji. + - Порожнє `emoji` видаляє всі реакції бота на повідомленні. + - `remove: true` видаляє лише вказане емодзі. - - Порожнє `emoji` видаляє реакції застосунку на повідомлення. - - `remove: true` видаляє лише вказане emoji. + - Порожнє `emoji` видаляє реакції застосунку на повідомленні. + - `remove: true` видаляє лише вказане емодзі. @@ -51,12 +51,12 @@ x-i18n: - Порожнє `emoji` видаляє реакцію бота. - - `remove: true` внутрішньо зіставляється з порожнім emoji (у виклику інструмента все одно потрібне `emoji`). + - `remove: true` внутрішньо перетворюється на порожнє emoji (у виклику інструмента `emoji` усе одно потрібне). - Потрібне непорожнє `emoji`. - - `remove: true` видаляє цю конкретну emoji-реакцію. + - `remove: true` видаляє реакцію з цим конкретним емодзі. @@ -71,14 +71,14 @@ x-i18n: ## Рівень реакцій -Конфігурація `reactionLevel` для кожного каналу визначає, наскільки широко агент використовує реакції. Типові значення: `off`, `ack`, `minimal` або `extensive`. +Параметр `reactionLevel` для кожного каналу визначає, наскільки широко агент використовує реакції. Зазвичай доступні значення `off`, `ack`, `minimal` або `extensive`. - [Telegram reactionLevel](/uk/channels/telegram#reaction-notifications) — `channels.telegram.reactionLevel` -- [WhatsApp reactionLevel](/uk/channels/whatsapp#reactions) — `channels.whatsapp.reactionLevel` +- [WhatsApp reactionLevel](/uk/channels/whatsapp#reaction-level) — `channels.whatsapp.reactionLevel` -Установіть `reactionLevel` для окремих каналів, щоб налаштувати, наскільки активно агент реагує на повідомлення на кожній платформі. +Налаштуйте `reactionLevel` для окремих каналів, щоб визначити, наскільки активно агент реагує на повідомлення на кожній платформі. ## Пов’язане -- [Agent Send](/tools/agent-send) — інструмент `message`, який містить `react` -- [Канали](/uk/channels) — конфігурація для конкретних каналів +- [Agent Send](/uk/tools/agent-send) — інструмент `message`, який містить `react` +- [Channels](/uk/channels) — конфігурація для конкретних каналів