chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
00c356a0bc
commit
460d532823
@ -1,19 +1,19 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете підключити OpenClaw до IRC-каналів або приватних повідомлень
|
||||
- Ви налаштовуєте IRC allowlist-и, політику груп або шлюзування за згадками
|
||||
- Ви хочете підключити OpenClaw до каналів IRC або приватних повідомлень
|
||||
- Ви налаштовуєте списки дозволених для IRC, політику груп або контроль згадок
|
||||
summary: Налаштування IRC Plugin, керування доступом і усунення несправностей
|
||||
title: IRC
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:44:04Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T00:58:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69
|
||||
source_hash: 43c3098fe49a5e7405443df73e1bf752a579460dc0b2070c3d07f43b512bb555
|
||||
source_path: channels/irc.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Використовуйте IRC, коли хочете підключити OpenClaw до класичних каналів (`#room`) і приватних повідомлень.
|
||||
Використовуйте IRC, коли вам потрібен OpenClaw у класичних каналах (`#room`) і прямих повідомленнях.
|
||||
IRC постачається як вбудований Plugin, але налаштовується в основній конфігурації в `channels.irc`.
|
||||
|
||||
## Швидкий старт
|
||||
@ -36,50 +36,51 @@ IRC постачається як вбудований Plugin, але налаш
|
||||
}
|
||||
```
|
||||
|
||||
Для координації ботів бажано використовувати приватний IRC-сервер. Якщо ви свідомо використовуєте публічну IRC-мережу, поширені варіанти включають Libera.Chat, OFTC і Snoonet. Уникайте передбачуваних публічних каналів для бекканального трафіку бота або swarm.
|
||||
Для координації ботів віддавайте перевагу приватному IRC-серверу. Якщо ви навмисно використовуєте публічну IRC-мережу, поширені варіанти включають Libera.Chat, OFTC і Snoonet. Уникайте передбачуваних публічних каналів для трафіку бота або зворотного каналу рою.
|
||||
|
||||
3. Запустіть/перезапустіть Gateway:
|
||||
3. Запустіть або перезапустіть Gateway:
|
||||
|
||||
```bash
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
## Типові налаштування безпеки
|
||||
## Стандартні налаштування безпеки
|
||||
|
||||
- `channels.irc.dmPolicy` типово має значення `"pairing"`.
|
||||
- `channels.irc.groupPolicy` типово має значення `"allowlist"`.
|
||||
- Якщо `groupPolicy="allowlist"`, задайте `channels.irc.groups`, щоб визначити дозволені канали.
|
||||
- Використовуйте TLS (`channels.irc.tls=true`), якщо тільки ви свідомо не погоджуєтеся на незашифрований транспорт.
|
||||
- IRC використовує сирі TCP/TLS-сокети поза маршрутизацією через керований оператором OpenClaw прямий проксі. У розгортаннях, які вимагають, щоб увесь вихідний трафік проходив через цей прямий проксі, задайте `channels.irc.enabled=false`, якщо прямий вихідний IRC-трафік не схвалено явно.
|
||||
- `channels.irc.dmPolicy` за замовчуванням має значення `"pairing"`.
|
||||
- `channels.irc.groupPolicy` за замовчуванням має значення `"allowlist"`.
|
||||
- З `groupPolicy="allowlist"` задайте `channels.irc.groups`, щоб визначити дозволені канали.
|
||||
- Використовуйте TLS (`channels.irc.tls=true`), якщо ви навмисно не приймаєте передавання відкритим текстом.
|
||||
|
||||
## Керування доступом
|
||||
|
||||
Для IRC-каналів є два окремі «бар’єри»:
|
||||
Для IRC-каналів є два окремі «шлюзи»:
|
||||
|
||||
1. **Доступ до каналу** (`groupPolicy` + `groups`): чи приймає бот повідомлення з каналу взагалі.
|
||||
2. **Доступ відправника** (`groupAllowFrom` / `groups["#channel"].allowFrom` для конкретного каналу): хто має право запускати бота в цьому каналі.
|
||||
2. **Доступ відправника** (`groupAllowFrom` / `groups["#channel"].allowFrom` для окремого каналу): хто має право запускати бота всередині цього каналу.
|
||||
|
||||
Ключі конфігурації:
|
||||
|
||||
- Allowlist DM (доступ відправників у DM): `channels.irc.allowFrom`
|
||||
- Allowlist відправників у групах (доступ відправників у каналах): `channels.irc.groupAllowFrom`
|
||||
- Елементи керування для окремого каналу (канал + відправник + правила згадок): `channels.irc.groups["#channel"]`
|
||||
- `channels.irc.groupPolicy="open"` дозволяє не налаштовані канали (**типово вони все одно проходять шлюзування за згадками**)
|
||||
- Список дозволених для DM (доступ відправника DM): `channels.irc.allowFrom`
|
||||
- Список дозволених відправників групи (доступ відправника каналу): `channels.irc.groupAllowFrom`
|
||||
- Елементи керування для окремого каналу (правила каналу, відправника й згадок): `channels.irc.groups["#channel"]`
|
||||
- `channels.irc.groupPolicy="open"` дозволяє неналаштовані канали (**однак за замовчуванням усе ще вимагає згадки**)
|
||||
|
||||
Записи allowlist слід задавати через стабільні ідентичності відправників (`nick!user@host`).
|
||||
Зіставлення лише за nick є змінним і вмикається тільки коли `channels.irc.dangerouslyAllowNameMatching: true`.
|
||||
Записи списку дозволених мають використовувати стабільні ідентичності відправників (`nick!user@host`).
|
||||
Зіставлення лише за псевдонімом є змінним і вмикається тільки коли `channels.irc.dangerouslyAllowNameMatching: true`.
|
||||
|
||||
### Поширена пастка: `allowFrom` призначений для DM, а не для каналів
|
||||
### Поширена пастка: `allowFrom` призначено для DM, а не каналів
|
||||
|
||||
Якщо ви бачите такі логи:
|
||||
Якщо ви бачите журнали на кшталт:
|
||||
|
||||
- `irc: drop group sender alice!ident@host (policy=allowlist)`
|
||||
|
||||
…це означає, що відправник не був дозволений для повідомлень **групи/каналу**. Виправити це можна так:
|
||||
…це означає, що відправника не було дозволено для **групових/канальних** повідомлень. Виправте це одним зі способів:
|
||||
|
||||
- задати `channels.irc.groupAllowFrom` (глобально для всіх каналів), або
|
||||
- задати allowlist-и відправників для конкретного каналу: `channels.irc.groups["#channel"].allowFrom`
|
||||
- задайте `channels.irc.groupAllowFrom` (глобально для всіх каналів), або
|
||||
- задайте списки дозволених відправників для окремих каналів: `channels.irc.groups["#channel"].allowFrom`
|
||||
|
||||
Приклад (дозволити будь-кому в `#tuirc-dev` звертатися до бота):
|
||||
Приклад (дозволити будь-кому в `#tuirc-dev` спілкуватися з ботом):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -96,11 +97,11 @@ openclaw gateway run
|
||||
|
||||
## Запуск відповіді (згадки)
|
||||
|
||||
Навіть якщо канал дозволено (через `groupPolicy` + `groups`) і відправник дозволений, у групових контекстах OpenClaw типово використовує **шлюзування за згадками**.
|
||||
Навіть якщо канал дозволено (через `groupPolicy` + `groups`) і відправника дозволено, OpenClaw за замовчуванням застосовує **вимогу згадки** в групових контекстах.
|
||||
|
||||
Це означає, що ви можете бачити логи на кшталт `drop channel … (missing-mention)`, якщо повідомлення не містить шаблон згадки, який збігається з ботом.
|
||||
Це означає, що ви можете бачити журнали на кшталт `drop channel … (missing-mention)`, якщо повідомлення не містить шаблону згадки, що відповідає боту.
|
||||
|
||||
Щоб бот відповідав в IRC-каналі **без потреби в згадці**, вимкніть шлюзування за згадками для цього каналу:
|
||||
Щоб бот відповідав в IRC-каналі **без потреби в згадці**, вимкніть вимогу згадки для цього каналу:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -118,7 +119,7 @@ openclaw gateway run
|
||||
}
|
||||
```
|
||||
|
||||
Або, щоб дозволити **всі** IRC-канали (без allowlist для окремих каналів) і при цьому відповідати без згадок:
|
||||
Або, щоб дозволити **всі** IRC-канали (без списку дозволених для окремих каналів) і все одно відповідати без згадок:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -157,9 +158,9 @@ openclaw gateway run
|
||||
}
|
||||
```
|
||||
|
||||
### Різні інструменти для різних відправників (власник отримує більше можливостей)
|
||||
### Різні інструменти для кожного відправника (власник отримує більше повноважень)
|
||||
|
||||
Використовуйте `toolsBySender`, щоб застосувати суворішу політику до `"*"` і м’якшу — до вашого nick:
|
||||
Використовуйте `toolsBySender`, щоб застосувати суворішу політику до `"*"` і м’якшу до вашого псевдоніма:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -185,12 +186,12 @@ openclaw gateway run
|
||||
|
||||
Примітки:
|
||||
|
||||
- Ключі `toolsBySender` слід задавати з `id:` для значень ідентичності IRC-відправника:
|
||||
- Ключі `toolsBySender` мають використовувати `id:` для значень ідентичності IRC-відправника:
|
||||
`id:eigen` або `id:eigen!~eigen@174.127.248.171` для надійнішого зіставлення.
|
||||
- Застарілі ключі без префікса все ще приймаються й зіставляються лише як `id:`.
|
||||
- Перемагає перша політика відправника, що збіглася; `"*"` є запасним wildcard-варіантом.
|
||||
- Перемагає перша відповідна політика відправника; `"*"` є резервним шаблоном-джокером.
|
||||
|
||||
Докладніше про доступ до груп і шлюзування за згадками (та про їхню взаємодію) див.: [/channels/groups](/uk/channels/groups).
|
||||
Докладніше про доступ до груп і вимогу згадки (та як вони взаємодіють) дивіться: [/channels/groups](/uk/channels/groups).
|
||||
|
||||
## NickServ
|
||||
|
||||
@ -225,11 +226,11 @@ openclaw gateway run
|
||||
}
|
||||
```
|
||||
|
||||
Після реєстрації nick вимкніть `register`, щоб уникнути повторних спроб REGISTER.
|
||||
Вимкніть `register` після реєстрації псевдоніма, щоб уникнути повторних спроб REGISTER.
|
||||
|
||||
## Змінні середовища
|
||||
|
||||
Типовий акаунт підтримує:
|
||||
Обліковий запис за замовчуванням підтримує:
|
||||
|
||||
- `IRC_HOST`
|
||||
- `IRC_PORT`
|
||||
@ -238,22 +239,22 @@ openclaw gateway run
|
||||
- `IRC_USERNAME`
|
||||
- `IRC_REALNAME`
|
||||
- `IRC_PASSWORD`
|
||||
- `IRC_CHANNELS` (через кому)
|
||||
- `IRC_CHANNELS` (розділені комами)
|
||||
- `IRC_NICKSERV_PASSWORD`
|
||||
- `IRC_NICKSERV_REGISTER_EMAIL`
|
||||
|
||||
`IRC_HOST` не можна задавати з workspace `.env`; див. [Файли workspace `.env`](/uk/gateway/security).
|
||||
`IRC_HOST` не можна задавати з робочого `.env`; дивіться [Файли `.env` робочої області](/uk/gateway/security).
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
- Якщо бот підключається, але ніколи не відповідає в каналах, перевірте `channels.irc.groups` **і** чи не відкидає повідомлення шлюзування за згадками (`missing-mention`). Якщо ви хочете, щоб він відповідав без пінгів, задайте `requireMention:false` для каналу.
|
||||
- Якщо вхід не вдається, перевірте доступність nick і пароль сервера.
|
||||
- Якщо TLS не працює в кастомній мережі, перевірте host/port і налаштування сертифікатів.
|
||||
- Якщо бот підключається, але ніколи не відповідає в каналах, перевірте `channels.irc.groups` **і** чи вимога згадки не відкидає повідомлення (`missing-mention`). Якщо ви хочете, щоб він відповідав без згадок, задайте `requireMention:false` для каналу.
|
||||
- Якщо вхід не вдається, перевірте доступність псевдоніма й пароль сервера.
|
||||
- Якщо TLS не працює в користувацькій мережі, перевірте хост/порт і налаштування сертифіката.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд каналів](/uk/channels) — усі підтримувані канали
|
||||
- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing
|
||||
- [Групи](/uk/channels/groups) — поведінка групового чату та шлюзування за згадками
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
|
||||
- [Безпека](/uk/gateway/security) — модель доступу та зміцнення безпеки
|
||||
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
|
||||
- [Групи](/uk/channels/groups) — поведінка групового чату й вимога згадки
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень
|
||||
- [Безпека](/uk/gateway/security) — модель доступу й посилення захисту
|
||||
|
||||
@ -1,77 +1,77 @@
|
||||
---
|
||||
read_when:
|
||||
- Створення або запуск візуального QA у реальному часі для помилок OpenClaw
|
||||
- Додавання перевірки «до» та «після» для запиту на злиття
|
||||
- Додавання сценаріїв Discord, Slack, WhatsApp або інших живих транспортів
|
||||
- Створення або запуск візуального контролю якості в реальному часі для помилок OpenClaw
|
||||
- Додавання перевірки до і після для запиту на злиття
|
||||
- Додавання сценаріїв Discord, Slack, WhatsApp або інших реальних транспортів
|
||||
- Налагодження запусків QA, яким потрібні знімки екрана, автоматизація браузера або доступ VNC
|
||||
summary: Mantis — це система візуальної наскрізної перевірки для відтворення помилок OpenClaw на реальних транспортах, фіксації доказів до й після та прикріплення артефактів до запитів на злиття.
|
||||
summary: Mantis — це система візуальної наскрізної перевірки для відтворення помилок OpenClaw на реальних транспортах, фіксації доказів до й після та прикріплення артефактів до PR.
|
||||
title: Богомол
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T00:35:16Z"
|
||||
generated_at: "2026-05-04T00:59:13Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 7d1fe1e6cb57406fab351892b43c7057a0d08e26455d76a50157f958474e363e
|
||||
source_hash: 42161d802c8601e58af1abef69277b5b3eac37750480326e1f56b2898a6af3fb
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis — це система наскрізної перевірки OpenClaw для помилок, яким потрібні справжнє
|
||||
середовище виконання, справжній транспорт і видимий доказ. Вона запускає сценарій на відомому
|
||||
поганому ref, збирає докази, запускає той самий сценарій на кандидатному ref і
|
||||
публікує порівняння як артефакти, які мейнтейнер може переглянути з PR або
|
||||
Mantis — це система наскрізної перевірки OpenClaw для помилок, яким потрібні реальний
|
||||
runtime, реальний транспорт і видимий доказ. Вона запускає сценарій проти відомого
|
||||
поганого ref, збирає докази, запускає той самий сценарій проти candidate ref і
|
||||
публікує порівняння як артефакти, які maintainer може перевірити з PR або
|
||||
з локальної команди.
|
||||
|
||||
Mantis починає з Discord, тому що Discord дає нам цінну першу смугу:
|
||||
справжню автентифікацію бота, справжні канали guild, реакції, треди, нативні команди та
|
||||
інтерфейс браузера, де люди можуть візуально підтвердити, що показав транспорт.
|
||||
Mantis починає з Discord, тому що Discord дає нам першу lane з високою цінністю:
|
||||
реальна автентифікація бота, реальні канали guild, реакції, threads, нативні команди та
|
||||
браузерний UI, де люди можуть візуально підтвердити те, що показав транспорт.
|
||||
|
||||
## Цілі
|
||||
|
||||
- Відтворити помилку з GitHub issue або PR з тією самою формою транспорту, яку бачать
|
||||
користувачі.
|
||||
- Зібрати артефакт **до** на baseline ref перед застосуванням виправлення.
|
||||
- Зібрати артефакт **після** на кандидатному ref після застосування виправлення.
|
||||
- Використовувати детермінований оракул, коли це можливо, наприклад читання реакції через Discord REST
|
||||
або перевірку транскрипту каналу.
|
||||
- Знімати скриншоти, коли помилка має видиму поверхню UI.
|
||||
- Запускатися локально з CLI, керованого агентом, і віддалено з GitHub.
|
||||
- Зберігати достатньо стану машини для VNC-порятунку, коли вхід, автоматизація браузера або
|
||||
автентифікація провайдера застрягають.
|
||||
- Захопити артефакт **before** на baseline ref до застосування виправлення.
|
||||
- Захопити артефакт **after** на candidate ref після застосування виправлення.
|
||||
- Використовувати детермінований oracle, коли це можливо, наприклад читання реакції
|
||||
через Discord REST або перевірку transcript каналу.
|
||||
- Захоплювати скриншоти, коли помилка має видиму UI-поверхню.
|
||||
- Запускати локально з CLI, керованого агентом, і віддалено з GitHub.
|
||||
- Зберігати достатньо стану машини для VNC-рятування, коли login, браузерна автоматизація або
|
||||
автентифікація provider зависають.
|
||||
- Публікувати стислий статус в операторський канал Discord, коли запуск заблокований,
|
||||
потребує ручної допомоги через VNC або завершується.
|
||||
потребує ручної VNC-допомоги або завершується.
|
||||
|
||||
## Нецілі
|
||||
|
||||
- Mantis не є заміною юніт-тестів. Запуск Mantis зазвичай має стати
|
||||
меншим регресійним тестом після того, як виправлення стане зрозумілим.
|
||||
- Mantis не є звичайним швидким CI-гейтом. Він повільніший, використовує живі облікові дані та
|
||||
призначений для помилок, де живе середовище має значення.
|
||||
- Mantis не має вимагати людини для звичайної роботи. Ручний VNC — це шлях порятунку,
|
||||
а не основний шлях.
|
||||
- Mantis не зберігає необроблені секрети в артефактах, логах, скриншотах, Markdown
|
||||
звітах або коментарях PR.
|
||||
- Mantis не є заміною unit tests. Запуск Mantis зазвичай має перетворитися
|
||||
на менший regression test після того, як виправлення зрозуміле.
|
||||
- Mantis не є звичайним швидким CI gate. Він повільніший, використовує live credentials і
|
||||
призначений для помилок, де live environment має значення.
|
||||
- Mantis не має вимагати участі людини для нормальної роботи. Ручний VNC — це шлях
|
||||
рятування, а не happy path.
|
||||
- Mantis не зберігає сирі secrets в артефактах, логах, скриншотах, Markdown
|
||||
звітах або PR-коментарях.
|
||||
|
||||
## Власність
|
||||
## Відповідальність
|
||||
|
||||
Mantis належить до QA-стека OpenClaw.
|
||||
Mantis належить до QA-стеку OpenClaw.
|
||||
|
||||
- OpenClaw володіє середовищем виконання сценаріїв, транспортними адаптерами, схемою доказів і
|
||||
локальним CLI під `pnpm openclaw qa mantis`.
|
||||
- QA Lab володіє частинами живого транспортного harness, допоміжними засобами захоплення браузера та
|
||||
записувачами артефактів.
|
||||
- Crabbox володіє прогрітими Linux-машинами, коли потрібна віддалена VM.
|
||||
- GitHub Actions володіє віддаленою точкою входу workflow і збереженням артефактів.
|
||||
- ClawSweeper володіє маршрутизацією коментарів GitHub: розбором команд мейнтейнерів,
|
||||
запуском workflow і публікацією фінального коментаря PR.
|
||||
- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні агентне налаштування,
|
||||
налагодження або звітування про застряглий стан.
|
||||
- OpenClaw відповідає за runtime сценаріїв, transport adapters, схему доказів і
|
||||
локальний CLI під `pnpm openclaw qa mantis`.
|
||||
- QA Lab відповідає за компоненти live transport harness, helper-и для browser capture і
|
||||
artifact writers.
|
||||
- Crabbox відповідає за прогріті Linux-машини, коли потрібна віддалена VM.
|
||||
- GitHub Actions відповідає за entrypoint віддаленого workflow і зберігання артефактів.
|
||||
- ClawSweeper відповідає за маршрутизацію GitHub-коментарів: parsing maintainer commands,
|
||||
dispatching the workflow і публікацію фінального PR-коментаря.
|
||||
- Агенти OpenClaw керують Mantis через Codex, коли сценарію потрібні agentic setup,
|
||||
debugging або stuck-state reporting.
|
||||
|
||||
Ця межа утримує знання про транспорт в OpenClaw, планування машин у
|
||||
Crabbox, а клей мейнтейнерського workflow — у ClawSweeper.
|
||||
Ця межа зберігає знання про транспорт в OpenClaw, планування машин у
|
||||
Crabbox, а maintainer workflow glue у ClawSweeper.
|
||||
|
||||
## Форма команди
|
||||
## Форма команд
|
||||
|
||||
Перша локальна команда перевіряє бота Discord, guild, канал, надсилання повідомлення,
|
||||
Перша локальна команда перевіряє Discord-бота, guild, канал, надсилання повідомлення,
|
||||
надсилання реакції та шлях артефактів:
|
||||
|
||||
```bash
|
||||
@ -79,7 +79,7 @@ pnpm openclaw qa mantis discord-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-smoke
|
||||
```
|
||||
|
||||
Локальний runner до і після приймає таку форму:
|
||||
Локальний runner before і after приймає таку форму:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis run \
|
||||
@ -90,55 +90,58 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
Runner створює від’єднані worktree baseline і candidate під вихідним
|
||||
каталогом, встановлює залежності, збирає кожен ref, запускає сценарій з
|
||||
Runner створює від'єднані baseline і candidate worktrees під output
|
||||
directory, встановлює залежності, збирає кожен ref, запускає сценарій з
|
||||
`--allow-failures`, потім записує `baseline/`, `candidate/`, `comparison.json`
|
||||
і `mantis-report.md`. Для першого сценарію Discord успішна перевірка
|
||||
означає, що статус baseline — `fail`, а статус candidate — `pass`.
|
||||
означає, що baseline status — `fail`, а candidate status — `pass`.
|
||||
|
||||
Перший примітив VM/браузера — desktop smoke:
|
||||
Перший примітив VM/browser — це desktop smoke:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis desktop-browser-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
|
||||
```
|
||||
|
||||
Він орендує або повторно використовує desktop-машину Crabbox, запускає видимий браузер усередині
|
||||
VNC-сесії, захоплює desktop, витягує артефакти назад у локальний вихідний
|
||||
каталог і записує команду повторного підключення у звіт. Команда за замовчуванням
|
||||
використовує провайдера Hetzner, тому що це перший провайдер із робочим покриттям desktop/VNC
|
||||
у смузі Mantis. Перевизначте його через `--provider`, `--crabbox-bin` або
|
||||
`OPENCLAW_MANTIS_CRABBOX_PROVIDER`, коли запускаєте проти іншого флоту Crabbox.
|
||||
Він орендує або повторно використовує desktop-машину Crabbox, запускає видимий браузер всередині
|
||||
VNC-сесії, захоплює desktop, витягує артефакти назад у локальний output
|
||||
directory і записує команду перепідключення у звіт. Команда за замовчуванням
|
||||
використовує Hetzner provider, тому що це перший provider з робочим desktop/VNC
|
||||
coverage у Mantis lane. Перевизначте це через `--provider`, `--crabbox-bin` або
|
||||
`OPENCLAW_MANTIS_CRABBOX_PROVIDER`, коли запускаєте проти іншого Crabbox fleet.
|
||||
|
||||
Корисні прапорці desktop smoke:
|
||||
|
||||
- `--lease-id <cbx_...>` або `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` повторно використовує прогрітий desktop.
|
||||
- `--browser-url <url>` змінює сторінку, відкриту у видимому браузері.
|
||||
- `--keep-lease` або `OPENCLAW_MANTIS_KEEP_VM=1` залишає новостворену успішну оренду відкритою для VNC-інспекції. Невдалі запуски за замовчуванням залишають оренду, якщо її було створено, щоб оператор міг перепідключитися.
|
||||
- `--class`, `--idle-timeout` і `--ttl` налаштовують розмір машини та час життя оренди.
|
||||
- `--html-file <path>` рендерить локальний для repo HTML-артефакт у видимому браузері. Mantis використовує це, щоб захопити згенерований Discord status-reaction timeline через реальний Crabbox desktop.
|
||||
- `--keep-lease` або `OPENCLAW_MANTIS_KEEP_VM=1` зберігає новостворений успішний lease відкритим для VNC-перевірки. Невдалі запуски за замовчуванням зберігають lease, якщо його було створено, щоб оператор міг перепідключитися.
|
||||
- `--class`, `--idle-timeout` і `--ttl` налаштовують розмір машини та lifetime lease.
|
||||
|
||||
GitHub smoke workflow — це `Mantis Discord Smoke`. GitHub workflow до і після
|
||||
для першого реального сценарію — `Mantis Discord Status Reactions`. Він
|
||||
GitHub smoke workflow — це `Mantis Discord Smoke`. GitHub workflow before і after
|
||||
для першого реального сценарію — це `Mantis Discord Status Reactions`. Він
|
||||
приймає:
|
||||
|
||||
- `baseline_ref`: ref, який, як очікується, відтворює поведінку лише queued.
|
||||
- `candidate_ref`: ref, який, як очікується, показує `queued -> thinking -> done`.
|
||||
- `baseline_ref`: ref, який має відтворювати queued-only behavior.
|
||||
- `candidate_ref`: ref, який має показати `queued -> thinking -> done`.
|
||||
|
||||
Він checkout-ить ref workflow harness, збирає окремі worktree baseline і candidate,
|
||||
запускає `discord-status-reactions-tool-only` проти кожного worktree і
|
||||
Він checkout-ить workflow harness ref, збирає окремі baseline і candidate
|
||||
worktrees, запускає `discord-status-reactions-tool-only` проти кожного worktree і
|
||||
завантажує `baseline/`, `candidate/`, `comparison.json` і `mantis-report.md` як
|
||||
артефакти Actions.
|
||||
Actions artifacts. Він також рендерить timeline HTML кожної lane у desktop-браузері
|
||||
Crabbox і публікує ці VNC-скриншоти поруч із детермінованими
|
||||
timeline PNG у PR-коментарі.
|
||||
|
||||
Ви також можете запустити status-reactions run напряму з коментаря PR:
|
||||
Також можна запустити status-reactions run напряму з PR-коментаря:
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions
|
||||
```
|
||||
|
||||
Тригер коментаря навмисно вузький. Він запускається лише на коментарях pull request
|
||||
від користувачів із доступом write, maintain або admin, і розпізнає лише
|
||||
запити status-reaction Discord. За замовчуванням він використовує відомий поганий baseline ref
|
||||
і поточний SHA head PR як candidate. Мейнтейнери можуть перевизначити будь-який
|
||||
Comment trigger навмисно вузький. Він запускається лише на pull request
|
||||
comments від користувачів із write, maintain або admin access і розпізнає лише
|
||||
Discord status-reaction requests. За замовчуванням він використовує відомий поганий baseline ref
|
||||
і поточний PR head SHA як candidate. Maintainers можуть перевизначити будь-який
|
||||
ref:
|
||||
|
||||
```text
|
||||
@ -152,48 +155,48 @@ ref:
|
||||
@clawsweeper verify e2e discord
|
||||
```
|
||||
|
||||
Перша команда явна й зосереджена на сценарії. Друга згодом може зіставляти PR
|
||||
або issue з рекомендованими сценаріями Mantis на основі міток, змінених файлів і
|
||||
знахідок рев’ю ClawSweeper.
|
||||
Перша команда явна та зосереджена на сценарії. Друга згодом може зіставляти PR
|
||||
або issue з рекомендованими сценаріями Mantis на основі labels, changed files і
|
||||
ClawSweeper review findings.
|
||||
|
||||
## Життєвий цикл запуску
|
||||
|
||||
1. Отримати облікові дані.
|
||||
1. Отримати credentials.
|
||||
2. Виділити або повторно використати VM.
|
||||
3. Підготувати desktop/профіль браузера, коли сценарію потрібні докази UI.
|
||||
4. Підготувати чистий checkout для baseline ref.
|
||||
3. Підготувати desktop/browser profile, коли сценарію потрібні UI-докази.
|
||||
4. Підготувати clean checkout для baseline ref.
|
||||
5. Встановити залежності та зібрати лише те, що потрібно сценарію.
|
||||
6. Запустити дочірній OpenClaw Gateway з ізольованим каталогом стану.
|
||||
7. Налаштувати живий транспорт, провайдера, модель і профіль браузера.
|
||||
8. Запустити сценарій і зібрати докази baseline.
|
||||
9. Зупинити gateway і зберегти логи.
|
||||
6. Запустити дочірній OpenClaw Gateway з ізольованим state directory.
|
||||
7. Налаштувати live transport, provider, model і browser profile.
|
||||
8. Запустити сценарій і захопити baseline evidence.
|
||||
9. Зупинити gateway і зберегти logs.
|
||||
10. Підготувати candidate ref у тій самій VM.
|
||||
11. Запустити той самий сценарій і зібрати докази candidate.
|
||||
12. Порівняти результати оракула та візуальні докази.
|
||||
13. Записати Markdown, JSON, логи, скриншоти та необов’язкові trace-артефакти.
|
||||
14. Завантажити артефакти GitHub Actions.
|
||||
15. Опублікувати стислий статусний допис у PR або Discord.
|
||||
11. Запустити той самий сценарій і захопити candidate evidence.
|
||||
12. Порівняти oracle results і visual evidence.
|
||||
13. Записати Markdown, JSON, logs, screenshots і optional trace artifacts.
|
||||
14. Завантажити GitHub Actions artifacts.
|
||||
15. Опублікувати стислий PR або Discord status message.
|
||||
|
||||
Сценарій має бути здатний завершуватися невдачею двома різними способами:
|
||||
Сценарій має мати змогу завершитися невдало двома різними способами:
|
||||
|
||||
- **Помилку відтворено**: baseline завершився невдачею очікуваним способом.
|
||||
- **Збій harness**: налаштування середовища, облікові дані, Discord API, браузер або
|
||||
провайдер зазнали збою до того, як оракул помилки став meaningful.
|
||||
- **Помилку відтворено**: baseline завершився невдало очікуваним способом.
|
||||
- **Збій harness**: environment setup, credentials, Discord API, browser або
|
||||
provider завершилися невдало до того, як bug oracle став meaningful.
|
||||
|
||||
Фінальний звіт має розділяти ці випадки, щоб мейнтейнери не плутали нестабільне
|
||||
середовище з поведінкою продукту.
|
||||
Фінальний звіт має розділяти ці випадки, щоб maintainers не плутали flaky
|
||||
environment із product behavior.
|
||||
|
||||
## Discord MVP
|
||||
|
||||
Перший сценарій має націлюватися на status reactions Discord у guild-каналах, де
|
||||
режим доставки вихідної відповіді — `message_tool_only`.
|
||||
Перший сценарій має націлюватися на Discord status reactions у guild channels, де
|
||||
source reply delivery mode — `message_tool_only`.
|
||||
|
||||
Чому це хороший початковий сценарій Mantis:
|
||||
Чому це хороший seed для Mantis:
|
||||
|
||||
- Він видимий у Discord як реакції на повідомлення, що запускає сценарій.
|
||||
- Він має сильний REST-оракул через стан реакцій повідомлення Discord.
|
||||
- Він перевіряє справжній OpenClaw Gateway, автентифікацію бота Discord, диспетчеризацію повідомлень,
|
||||
режим доставки вихідної відповіді, стан status reaction і життєвий цикл модельного turn.
|
||||
- Це видно в Discord як reactions на triggering message.
|
||||
- Він має сильний REST oracle через Discord message reaction state.
|
||||
- Він перевіряє реальний OpenClaw Gateway, автентифікацію Discord-бота, message dispatch,
|
||||
source reply delivery mode, status reaction state і model turn lifecycle.
|
||||
- Він достатньо вузький, щоб перша реалізація залишалася чесною.
|
||||
|
||||
Очікувана форма сценарію:
|
||||
@ -227,12 +230,12 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
Докази baseline мають показувати queued acknowledgement reaction, але без
|
||||
lifecycle transition у режимі tool-only. Докази candidate мають показувати, що lifecycle
|
||||
Baseline evidence має показувати queued acknowledgement reaction, але без
|
||||
lifecycle transition у tool-only mode. Candidate evidence має показувати, що lifecycle
|
||||
status reactions працюють, коли `messages.statusReactions.enabled` явно
|
||||
дорівнює true.
|
||||
true.
|
||||
|
||||
Виконуваний перший зріз — це opt-in живий QA-сценарій Discord:
|
||||
Перший executable slice — це opt-in Discord live QA scenario:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa discord \
|
||||
@ -244,34 +247,34 @@ pnpm openclaw qa discord \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
|
||||
```
|
||||
|
||||
Він налаштовує SUT із завжди ввімкненою обробкою guild, `visibleReplies:
|
||||
"message_tool"`, `ackReaction: "👀"` і явними status reactions. Оракул
|
||||
опитує справжнє повідомлення Discord, що запустило сценарій, і очікує спостережувану послідовність
|
||||
`👀 -> 🤔 -> 👍`. Артефакти містять `discord-qa-reaction-timelines.json`,
|
||||
Він налаштовує SUT з always-on guild handling, `visibleReplies:
|
||||
"message_tool"`, `ackReaction: "👀"` і explicit status reactions. Oracle
|
||||
опитує реальне Discord triggering message і очікує observed sequence
|
||||
`👀 -> 🤔 -> 👍`. Артефакти включають `discord-qa-reaction-timelines.json`,
|
||||
`discord-status-reactions-tool-only-timeline.html` і
|
||||
`discord-status-reactions-tool-only-timeline.png`.
|
||||
|
||||
## Наявні компоненти QA
|
||||
|
||||
Mantis має будуватися на наявному приватному QA-стеку, а не починати з
|
||||
Mantis має спиратися на наявний private QA stack замість того, щоб починати з
|
||||
нуля:
|
||||
|
||||
- `pnpm openclaw qa discord` уже запускає живу смугу Discord з ботами driver і
|
||||
SUT.
|
||||
- Живий transport runner уже записує звіти та артефакти observed-message
|
||||
під `.artifacts/qa-e2e/`.
|
||||
- Оренди облікових даних Convex уже надають ексклюзивний доступ до спільних живих
|
||||
транспортних облікових даних.
|
||||
- Сервіс керування браузером уже підтримує скриншоти, snapshots,
|
||||
headless керовані профілі та віддалені CDP-профілі.
|
||||
- QA Lab уже має UI налагоджувача й шину для тестування у формі транспорту.
|
||||
- `pnpm openclaw qa discord` уже запускає live Discord lane з driver і
|
||||
SUT bots.
|
||||
- Live transport runner уже записує reports і observed-message
|
||||
artifacts під `.artifacts/qa-e2e/`.
|
||||
- Convex credential leases уже надають exclusive access до shared live
|
||||
transport credentials.
|
||||
- Browser control service уже підтримує screenshots, snapshots,
|
||||
headless managed profiles і remote CDP profiles.
|
||||
- QA Lab уже має debugger UI і bus для transport-shaped testing.
|
||||
|
||||
Перша реалізація Mantis може бути тонким runner до/після над цими
|
||||
компонентами плюс один шар візуальних доказів.
|
||||
Перша реалізація Mantis може бути тонким before/after runner поверх цих
|
||||
компонентів плюс один шар visual evidence.
|
||||
|
||||
## Модель доказів
|
||||
|
||||
Кожен запуск записує стабільний каталог артефактів:
|
||||
Кожен запуск записує стабільний artifact directory:
|
||||
|
||||
```text
|
||||
.artifacts/qa-e2e/mantis/<run-id>/
|
||||
@ -291,76 +294,76 @@ Mantis має будуватися на наявному приватному QA
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` має бути машинозчитуваним джерелом істини. Markdown
|
||||
звіт призначений для коментарів PR і людського рев’ю.
|
||||
`mantis-summary.json` має бути machine-readable source of truth. Markdown
|
||||
report призначений для PR comments і human review.
|
||||
|
||||
Підсумок має містити:
|
||||
Summary має включати:
|
||||
|
||||
- протестовані refs і SHA
|
||||
- refs і SHAs, які тестувалися
|
||||
- transport і scenario id
|
||||
- провайдера машини та machine id або lease id
|
||||
- джерело облікових даних без значень секретів
|
||||
- результат baseline
|
||||
- результат candidate
|
||||
- чи помилку відтворено на baseline
|
||||
- чи candidate виправив її
|
||||
- шляхи артефактів
|
||||
- санітизовані проблеми налаштування або очищення
|
||||
- machine provider і machine id або lease id
|
||||
- credential source без secret values
|
||||
- baseline result
|
||||
- candidate result
|
||||
- чи помилка відтворилася на baseline
|
||||
- чи candidate її виправив
|
||||
- artifact paths
|
||||
- sanitized setup або cleanup issues
|
||||
|
||||
Скриншоти — це докази, а не секрети. Вони все одно потребують дисципліни редагування:
|
||||
можуть з’являтися назви приватних каналів, імена користувачів або вміст повідомлень. Для публічних PR
|
||||
надавайте перевагу посиланням на артефакти GitHub Actions замість inline-зображень, доки історія
|
||||
редагування не стане сильнішою.
|
||||
Screenshots — це докази, а не secrets. Вони все одно потребують redaction discipline:
|
||||
private channel names, user names або message content можуть з'явитися. Для public PRs
|
||||
віддавайте перевагу GitHub Actions artifact links над inline images, доки redaction story
|
||||
не стане сильнішою.
|
||||
|
||||
## Браузер і VNC
|
||||
|
||||
Смуга браузера має два режими:
|
||||
Browser lane має два режими:
|
||||
|
||||
- **Headless automation**: стандартно для CI. Chrome запускається з увімкненим CDP, а
|
||||
Playwright або керування браузером OpenClaw захоплює скриншоти.
|
||||
- **VNC rescue**: увімкнено на тій самій VM, коли вхід, MFA, антиавтоматизація Discord
|
||||
або візуальне налагодження потребують людини.
|
||||
- **Headless automation**: за замовчуванням для CI. Chrome запускається з увімкненим CDP, а
|
||||
Playwright або OpenClaw browser control захоплює screenshots.
|
||||
- **VNC rescue**: увімкнено на тій самій VM, коли login, MFA, Discord anti-automation
|
||||
або visual debugging потребують людини.
|
||||
|
||||
Профіль браузера спостерігача Discord має бути достатньо persistent, щоб не доводилося
|
||||
входити під час кожного запуску, але ізольованим від особистого стану браузера. Профіль
|
||||
Профіль браузера спостерігача Discord має бути достатньо постійним, щоб уникати
|
||||
входу під час кожного запуску, але ізольованим від особистого стану браузера. Профіль
|
||||
належить пулу машин Mantis, а не ноутбуку розробника.
|
||||
|
||||
Коли Mantis застрягає, він публікує статусне повідомлення Discord з:
|
||||
Коли Mantis застрягає, він публікує статусне повідомлення Discord із:
|
||||
|
||||
- run id
|
||||
- scenario id
|
||||
- провайдером машини
|
||||
- id запуску
|
||||
- id сценарію
|
||||
- постачальником машини
|
||||
- каталогом артефактів
|
||||
- інструкціями підключення VNC або noVNC, якщо доступні
|
||||
- інструкціями з підключення через VNC або noVNC, якщо доступно
|
||||
- коротким текстом блокера
|
||||
|
||||
Перше приватне розгортання може публікувати ці повідомлення в наявний канал
|
||||
операторів і пізніше перейти до окремого каналу Mantis.
|
||||
операторів, а пізніше перейти до окремого каналу Mantis.
|
||||
|
||||
## Машини
|
||||
|
||||
Mantis має надавати перевагу AWS через Crabbox для першої віддаленої реалізації.
|
||||
Crabbox дає нам розігріті машини, відстеження оренди, гідратацію, журнали, результати та
|
||||
очищення. Якщо потужності AWS надто повільні або недоступні, додайте провайдера Hetzner
|
||||
Crabbox надає нам попередньо прогріті машини, відстеження оренди, гідратацію, журнали, результати та
|
||||
очищення. Якщо місткість AWS надто повільна або недоступна, додайте постачальника Hetzner
|
||||
за тим самим інтерфейсом машин.
|
||||
|
||||
Мінімальні вимоги до VM:
|
||||
|
||||
- Linux із встановленим Chrome або Chromium, здатним працювати з робочим столом
|
||||
- Linux з інсталяцією Chrome або Chromium, здатною працювати з робочим столом
|
||||
- доступ CDP для автоматизації браузера
|
||||
- VNC або noVNC для відновлення
|
||||
- VNC або noVNC для аварійного доступу
|
||||
- Node 22 і pnpm
|
||||
- клон OpenClaw і кеш залежностей
|
||||
- checkout OpenClaw і кеш залежностей
|
||||
- кеш браузера Playwright Chromium, коли використовується Playwright
|
||||
- достатньо CPU та пам’яті для одного OpenClaw Gateway, одного браузера й одного запуску моделі
|
||||
- вихідний доступ до Discord, GitHub, провайдерів моделей і брокера облікових даних
|
||||
- вихідний доступ до Discord, GitHub, постачальників моделей і брокера облікових даних
|
||||
|
||||
VM не має зберігати довготривалі сирі секрети поза очікуваними сховищами облікових даних або
|
||||
VM не має зберігати довготривалі необроблені секрети поза очікуваними сховищами облікових даних або
|
||||
профілів браузера.
|
||||
|
||||
## Секрети
|
||||
|
||||
Секрети зберігаються в секретах організації або репозиторію GitHub для віддалених запусків і в
|
||||
Секрети зберігаються в секретах організації або репозиторію GitHub для віддалених запусків, а також у
|
||||
локальному файлі секретів під контролем оператора для локальних запусків.
|
||||
|
||||
Рекомендовані назви секретів:
|
||||
@ -371,43 +374,43 @@ VM не має зберігати довготривалі сирі секрет
|
||||
- `OPENCLAW_QA_DISCORD_GUILD_ID`
|
||||
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` для завантаження публічних артефактів GitHub
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` для публічних завантажень артефактів GitHub
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
|
||||
У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом живих
|
||||
У довгостроковій перспективі пул облікових даних Convex має залишатися звичайним джерелом для живих
|
||||
облікових даних транспорту. Секрети GitHub початково завантажують брокер і резервні лінії.
|
||||
|
||||
Запускач Mantis ніколи не повинен друкувати:
|
||||
Runner Mantis ніколи не має друкувати:
|
||||
|
||||
- токени ботів Discord
|
||||
- API-ключі провайдерів
|
||||
- API-ключі постачальників
|
||||
- cookies браузера
|
||||
- вміст профілів автентифікації
|
||||
- вміст профілю автентифікації
|
||||
- паролі VNC
|
||||
- сирі корисні навантаження облікових даних
|
||||
- необроблені payloads облікових даних
|
||||
|
||||
Публічні завантаження артефактів також мають редагувати цільові метадані Discord, як-от ідентифікатори ботів,
|
||||
серверів, каналів і повідомлень. Робочий процес smoke GitHub вмикає
|
||||
Публічні завантаження артефактів також мають редагувати цільові метадані Discord, як-от id бота,
|
||||
guild, каналу й повідомлення. Smoke workflow GitHub вмикає
|
||||
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` саме з цієї причини.
|
||||
|
||||
Якщо токен випадково вставлено в issue, PR, чат або журнал, оберніть його
|
||||
Якщо токен випадково вставлено в issue, PR, чат або журнал, поверніть його
|
||||
після збереження нового секрету.
|
||||
|
||||
## Артефакти GitHub і коментарі PR
|
||||
|
||||
Робочі процеси Mantis мають завантажувати повний пакет доказів як короткоживучий артефакт Actions.
|
||||
Коли робочий процес запускається для звіту про помилку або PR із виправленням, він також має
|
||||
опублікувати відредаговані PNG-знімки екрана в гілку `qa-artifacts` і оновити або створити
|
||||
коментар до цієї помилки чи PR із виправленням із вбудованими знімками до/після. Не публікуйте
|
||||
основний доказ лише в загальному PR автоматизації QA. Сирі журнали, спостережені
|
||||
Workflow Mantis мають завантажувати повний пакет доказів як короткоживучий артефакт Actions.
|
||||
Коли workflow запускається для звіту про bug або PR з виправленням, він також має
|
||||
публікувати відредаговані PNG-знімки екрана в гілку `qa-artifacts` і upsert-коментар
|
||||
до цього bug або PR з виправленням із вбудованими знімками до/після. Не публікуйте
|
||||
основний доказ лише в загальному PR автоматизації QA. Необроблені журнали, спостережені
|
||||
повідомлення та інші об’ємні докази залишаються в артефакті Actions.
|
||||
|
||||
Виробничі робочі процеси мають публікувати ці коментарі через GitHub App Mantis, а не
|
||||
Production workflows мають публікувати ці коментарі через Mantis GitHub App, а не
|
||||
через `github-actions[bot]`. Зберігайте app id і приватний ключ як секрети GitHub Actions
|
||||
`MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. Робочий процес використовує прихований маркер
|
||||
як ключ upsert, оновлює цей коментар, коли токен може його редагувати, і створює новий
|
||||
коментар від імені Mantis, коли старіший маркер від бота не можна відредагувати.
|
||||
`MANTIS_GITHUB_APP_ID` і `MANTIS_GITHUB_APP_PRIVATE_KEY`. Workflow використовує прихований маркер як ключ upsert,
|
||||
оновлює цей коментар, коли токен може його редагувати, і створює новий коментар від імені Mantis,
|
||||
коли старіший маркер, що належить боту, не можна редагувати.
|
||||
|
||||
Коментар PR має бути коротким і візуальним:
|
||||
|
||||
@ -429,70 +432,72 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
Коли запуск завершується невдало через збій harness, коментар має повідомляти саме це,
|
||||
а не натякати, що кандидат не пройшов.
|
||||
Коли запуск завершується невдало через збій harness, у коментарі має бути сказано саме це,
|
||||
а не створюватися враження, що candidate не пройшов.
|
||||
|
||||
## Примітки щодо приватного розгортання
|
||||
## Нотатки щодо приватного розгортання
|
||||
|
||||
Приватне розгортання вже може мати застосунок Discord Mantis. Використовуйте цей
|
||||
застосунок повторно замість створення іншого app, якщо він має потрібні дозволи бота
|
||||
і його можна безпечно обернути.
|
||||
Приватне розгортання вже може мати застосунок Discord Mantis. Повторно використовуйте цей
|
||||
застосунок замість створення іншого app, якщо він має правильні дозволи бота
|
||||
і його можна безпечно ротувати.
|
||||
|
||||
Задайте початковий канал сповіщень оператора через секрети або конфігурацію розгортання.
|
||||
Спочатку він може вказувати на наявний канал мейнтейнерів або операцій, а потім перейти
|
||||
до окремого каналу Mantis, щойно такий з’явиться.
|
||||
Задайте початковий канал сповіщень операторів через секрети або конфігурацію розгортання.
|
||||
Спершу він може вказувати на наявний канал maintainer або operations,
|
||||
а потім перейти до окремого каналу Mantis, коли він з’явиться.
|
||||
|
||||
Не додавайте в цей документ ідентифікатори серверів, ідентифікатори каналів, токени ботів, cookies браузера або паролі VNC.
|
||||
Зберігайте їх у секретах GitHub, брокері облікових даних або локальному сховищі секретів оператора.
|
||||
Не додавайте guild ids, channel ids, токени ботів, cookies браузера або паролі VNC
|
||||
до цього документа. Зберігайте їх у секретах GitHub, брокері облікових даних або
|
||||
локальному сховищі секретів оператора.
|
||||
|
||||
## Додавання сценарію
|
||||
|
||||
Сценарій Mantis має оголошувати:
|
||||
|
||||
- id і title
|
||||
- id і назву
|
||||
- транспорт
|
||||
- необхідні облікові дані
|
||||
- політику базового ref
|
||||
- політику кандидатного ref
|
||||
- патч конфігурації OpenClaw
|
||||
- політику baseline ref
|
||||
- політику candidate ref
|
||||
- patch конфігурації OpenClaw
|
||||
- кроки налаштування
|
||||
- стимул
|
||||
- очікуваний oracle базової версії
|
||||
- очікуваний oracle кандидата
|
||||
- очікуваний oracle baseline
|
||||
- очікуваний oracle candidate
|
||||
- цілі візуального захоплення
|
||||
- бюджет тайм-ауту
|
||||
- бюджет часу очікування
|
||||
- кроки очищення
|
||||
|
||||
Сценарії мають надавати перевагу невеликим типізованим oracle:
|
||||
Сценарії мають надавати перевагу невеликим типізованим oracles:
|
||||
|
||||
- стан реакцій Discord для помилок реакцій
|
||||
- посилання на повідомлення Discord для помилок потоків
|
||||
- thread ts Slack і стан API реакцій для помилок Slack
|
||||
- ідентифікатори повідомлень і заголовки email для помилок email
|
||||
- стан реакцій Discord для bugs реакцій
|
||||
- посилання на повідомлення Discord для bugs тредингу
|
||||
- thread ts Slack і стан API реакцій для bugs Slack
|
||||
- ids повідомлень електронної пошти та заголовки для bugs електронної пошти
|
||||
- знімки екрана браузера, коли UI є єдиним надійним спостережуваним сигналом
|
||||
|
||||
Перевірки зором мають бути додатковими. Якщо API платформи може довести помилку, використовуйте
|
||||
API як oracle проходження/збою, а знімки екрана залишайте для впевненості людини.
|
||||
Перевірки зору мають бути додатковими. Якщо API платформи може довести bug, використовуйте
|
||||
API як oracle pass/fail і залишайте знімки екрана для впевненості людини.
|
||||
|
||||
## Розширення провайдерів
|
||||
## Розширення постачальників
|
||||
|
||||
Після Discord той самий запускач може додати:
|
||||
Після Discord той самий runner може додати:
|
||||
|
||||
- Slack: реакції, потоки, згадки app, модальні вікна, завантаження файлів.
|
||||
- Email: автентифікація Gmail і потоки повідомлень із використанням `gog`, коли connectors недостатньо.
|
||||
- Slack: реакції, треди, згадки app, модальні вікна, завантаження файлів.
|
||||
- Email: автентифікація Gmail і трединг повідомлень із використанням `gog`, коли connectors недостатньо.
|
||||
- WhatsApp: QR-вхід, повторна ідентифікація, доставка повідомлень, медіа, реакції.
|
||||
- Telegram: gate для згадок у групах, команди, реакції там, де доступні.
|
||||
- Matrix: зашифровані кімнати, зв’язки потоків або відповідей, відновлення після перезапуску.
|
||||
- Telegram: gating групових згадок, команди, реакції, де доступно.
|
||||
- Matrix: зашифровані кімнати, зв’язки тредів або відповідей, resume після рестарту.
|
||||
|
||||
Кожен транспорт має мати один дешевий smoke-сценарій і один або кілька сценаріїв класів помилок.
|
||||
Кожен транспорт має мати один дешевий smoke-сценарій і один або більше сценаріїв класу bug.
|
||||
Дорогі візуальні сценарії мають залишатися opt-in.
|
||||
|
||||
## Відкриті питання
|
||||
|
||||
- Який бот Discord має бути driver, а який SUT, коли наявний бот Mantis використовується повторно?
|
||||
- Чи має вхід браузера observer використовувати людський обліковий запис Discord, тестовий обліковий запис
|
||||
або лише доступні боту REST-докази для першої фази?
|
||||
- Як довго GitHub має зберігати артефакти Mantis для PR?
|
||||
- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування команди
|
||||
мейнтейнера?
|
||||
- Чи потрібно редагувати або обрізати знімки екрана перед завантаженням для публічних PR?
|
||||
- Який бот Discord має бути driver, а який SUT, коли
|
||||
наявний бот Mantis використовується повторно?
|
||||
- Чи має вхід браузера спостерігача використовувати людський обліковий запис Discord, тестовий обліковий запис
|
||||
або лише bot-readable REST-докази для першої фази?
|
||||
- Як довго GitHub має зберігати артефакти Mantis для PRs?
|
||||
- Коли ClawSweeper має автоматично рекомендувати Mantis замість очікування
|
||||
команди maintainer?
|
||||
- Чи слід редагувати або обрізати знімки екрана перед завантаженням для публічних PRs?
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен багаторівневий захист від атак SSRF і повторного прив’язування DNS
|
||||
- Вам потрібен багаторівневий захист від атак SSRF і переприв’язування DNS.
|
||||
- Налаштування зовнішнього прямого проксі для трафіку середовища виконання OpenClaw
|
||||
summary: Як маршрутизувати HTTP- і WebSocket-трафік середовища виконання OpenClaw через керований оператором фільтрувальний проксі
|
||||
summary: Як маршрутизувати HTTP- та WebSocket-трафік середовища виконання OpenClaw через фільтрувальний проксі, керований оператором
|
||||
title: Мережевий проксі
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T05:23:47Z"
|
||||
generated_at: "2026-05-04T00:58:55Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3
|
||||
source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,53 +17,53 @@ x-i18n:
|
||||
|
||||
OpenClaw може спрямовувати runtime HTTP- і WebSocket-трафік через керований оператором прямий проксі. Це необов’язковий додатковий рівень захисту для розгортань, яким потрібні централізований контроль вихідного трафіку, сильніший захист від SSRF і краща можливість аудиту мережі.
|
||||
|
||||
OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі. Ви запускаєте проксі-технологію, яка відповідає вашому середовищу, а OpenClaw спрямовує через неї звичайні process-local HTTP- і WebSocket-клієнти.
|
||||
OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі. Ви запускаєте проксі-технологію, яка підходить вашому середовищу, а OpenClaw спрямовує звичайні локальні для процесу HTTP- і WebSocket-клієнти через неї.
|
||||
|
||||
## Навіщо використовувати проксі?
|
||||
|
||||
Проксі дає операторам одну точку мережевого контролю для вихідного HTTP- і WebSocket-трафіку. Це може бути корисно навіть поза посиленням захисту від SSRF:
|
||||
|
||||
- Централізована політика: підтримуйте одну політику вихідного трафіку замість того, щоб покладатися на те, що кожне місце HTTP-виклику в застосунку правильно застосує мережеві правила.
|
||||
- Перевірки під час підключення: оцінюйте призначення після DNS-розв’язання й безпосередньо перед тим, як проксі відкриє upstream-з’єднання.
|
||||
- Захист від DNS rebinding: зменшуйте розрив між DNS-перевіркою на рівні застосунку й фактичним вихідним з’єднанням.
|
||||
- Ширше покриття JavaScript: спрямовуйте звичайні `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch і подібні клієнти одним і тим самим шляхом.
|
||||
- Можливість аудиту: журналюйте дозволені й заборонені призначення на межі вихідного трафіку.
|
||||
- Операційний контроль: застосовуйте правила призначень, сегментацію мережі, обмеження швидкості або allowlist-и вихідного трафіку без перебудови OpenClaw.
|
||||
- Централізована політика: підтримуйте одну політику вихідного трафіку замість покладатися на те, що кожне місце HTTP-виклику в застосунку правильно застосує мережеві правила.
|
||||
- Перевірки під час підключення: оцінюйте призначення після DNS-резолюції та безпосередньо перед тим, як проксі відкриє вихідне з’єднання.
|
||||
- Захист від DNS rebinding: зменшуйте проміжок між DNS-перевіркою на рівні застосунку та фактичним вихідним з’єднанням.
|
||||
- Ширше покриття JavaScript: спрямовуйте звичайні `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch і подібні клієнти одним шляхом.
|
||||
- Можливість аудиту: журналюйте дозволені та заборонені призначення на межі вихідного трафіку.
|
||||
- Операційний контроль: застосовуйте правила призначення, сегментацію мережі, ліміти швидкості або allowlist вихідних призначень без перебудови OpenClaw.
|
||||
|
||||
Маршрутизація через проксі — це запобіжник рівня процесу для звичайного вихідного HTTP- і WebSocket-трафіку. Вона дає операторам fail-closed шлях для спрямування підтримуваних JavaScript HTTP-клієнтів через власний фільтрувальний проксі, але не є мережевою пісочницею рівня ОС і не змушує OpenClaw сертифікувати політику призначень проксі.
|
||||
Маршрутизація через проксі є захисною межею на рівні процесу для звичайного вихідного HTTP- і WebSocket-трафіку. Вона дає операторам fail-closed шлях для маршрутизації підтримуваних JavaScript HTTP-клієнтів через їхній власний фільтрувальний проксі, але не є мережевою пісочницею на рівні ОС і не змушує OpenClaw сертифікувати політику призначень проксі.
|
||||
|
||||
## Як OpenClaw спрямовує трафік
|
||||
## Як OpenClaw маршрутизує трафік
|
||||
|
||||
Коли `proxy.enabled=true` і налаштовано URL проксі, захищені runtime-процеси, як-от `openclaw gateway run`, `openclaw node run` і `openclaw agent --local`, спрямовують звичайний вихідний HTTP- і WebSocket-трафік через налаштований проксі:
|
||||
|
||||
```text
|
||||
Процес OpenClaw
|
||||
fetch -> керований оператором фільтрувальний проксі -> публічний інтернет
|
||||
node:http and https -> керований оператором фільтрувальний проксі -> публічний інтернет
|
||||
WebSocket clients -> керований оператором фільтрувальний проксі -> публічний інтернет
|
||||
OpenClaw process
|
||||
fetch -> operator-managed filtering proxy -> public internet
|
||||
node:http and https -> operator-managed filtering proxy -> public internet
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
Публічний контракт — це поведінка маршрутизації, а не внутрішні Node-хуки, використані для її реалізації. WebSocket-клієнти control-plane OpenClaw Gateway використовують вузький прямий шлях для local loopback Gateway RPC-трафіку, коли URL Gateway використовує `localhost` або буквальну loopback IP-адресу, як-от `127.0.0.1` чи `[::1]`. Цей control-plane шлях має мати змогу досягати loopback Gateway, навіть коли операторський проксі блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити все одно використовують налаштований проксі.
|
||||
Публічний контракт — це поведінка маршрутизації, а не внутрішні Node-хуки, використані для її реалізації. Клієнти WebSocket площини керування OpenClaw Gateway використовують вузький прямий шлях для local loopback Gateway RPC-трафіку, коли URL Gateway використовує `localhost` або буквальну loopback IP-адресу, як-от `127.0.0.1` чи `[::1]`. Цей шлях площини керування має бути здатний досягати loopback Gateway навіть тоді, коли операторський проксі блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити й надалі використовують налаштований проксі.
|
||||
|
||||
Внутрішньо OpenClaw використовує два хуки маршрутизації рівня процесу для цієї функції:
|
||||
Внутрішньо OpenClaw використовує два хуки маршрутизації на рівні процесу для цієї функції:
|
||||
|
||||
- Маршрутизація диспетчера Undici покриває `fetch`, клієнти на основі undici та транспорти, які надають власний диспетчер undici.
|
||||
- Маршрутизація `global-agent` покриває виклики Node core `node:http` і `node:https`, включно з багатьма бібліотеками, побудованими поверх `http.request`, `https.request`, `http.get` і `https.get`. Керований режим проксі примусово застосовує цей глобальний агент, щоб явні Node HTTP-агенти випадково не обходили операторський проксі.
|
||||
- Маршрутизація dispatcher Undici покриває `fetch`, клієнти на базі undici та транспорти, що надають власний dispatcher undici.
|
||||
- Маршрутизація `global-agent` покриває виклики ядра Node `node:http` і `node:https`, зокрема багато бібліотек, побудованих поверх `http.request`, `https.request`, `http.get` і `https.get`. Керований режим проксі примусово використовує цей глобальний агент, щоб явні Node HTTP-агенти випадково не обходили операторський проксі.
|
||||
|
||||
Деякі plugins мають власні транспорти, яким потрібне явне проксі-підключення навіть за наявності маршрутизації рівня процесу. Наприклад, транспорт Bot API для Telegram використовує власний HTTP/1-диспетчер undici, тому враховує env проксі процесу, а також керований fallback `OPENCLAW_PROXY_URL` у цьому owner-specific транспортному шляху.
|
||||
Деякі плагіни володіють власними транспортами, яким потрібне явне підключення проксі навіть за наявності маршрутизації на рівні процесу. Наприклад, транспорт Bot API Telegram використовує власний HTTP/1 undici dispatcher і тому враховує env проксі процесу плюс керований fallback `OPENCLAW_PROXY_URL` у цьому owner-specific транспортному шляху.
|
||||
|
||||
Сам URL проксі має використовувати `http://`. HTTPS-призначення все одно підтримуються через проксі за допомогою HTTP `CONNECT`; це лише означає, що OpenClaw очікує простий HTTP forward-proxy listener, як-от `http://127.0.0.1:3128`.
|
||||
Сам URL проксі має використовувати `http://`. HTTPS-призначення все одно підтримуються через проксі за допомогою HTTP `CONNECT`; це лише означає, що OpenClaw очікує звичайний HTTP forward-proxy listener, наприклад `http://127.0.0.1:3128`.
|
||||
|
||||
Поки проксі активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу базуються на призначеннях, тому залишення там `localhost` або `127.0.0.1` дозволило б високоризиковим SSRF-цілям пропускати фільтрувальний проксі.
|
||||
Поки проксі активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу базуються на призначенні, тож якби там залишилися `localhost` або `127.0.0.1`, це дозволило б високоризиковим SSRF-цілям оминути фільтрувальний проксі.
|
||||
|
||||
Під час завершення роботи OpenClaw відновлює попереднє проксі-середовище й скидає кешований стан маршрутизації процесу.
|
||||
Під час завершення роботи OpenClaw відновлює попереднє proxy environment і скидає кешований стан маршрутизації процесу.
|
||||
|
||||
## Пов’язані терміни проксі
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl`: маршрутизація вихідного forward-proxy для runtime вихідного трафіку OpenClaw. Ця сторінка документує цю функцію.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: inbound identity-aware reverse-proxy authentication для доступу до Gateway. Див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy`: локальний debug proxy і capture inspector для розробки й підтримки. Див. [openclaw proxy](/uk/cli/proxy).
|
||||
- Налаштування проксі, специфічні для каналу або провайдера: owner-specific перевизначення для конкретного транспорту. Віддавайте перевагу керованому мережевому проксі, коли метою є централізований контроль вихідного трафіку в усьому runtime.
|
||||
- `proxy.enabled` / `proxy.proxyUrl`: маршрутизація вихідного forward-proxy для runtime-вихідного трафіку OpenClaw. Ця сторінка документує цю функцію.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: вхідна автентифікація через identity-aware reverse-proxy для доступу до Gateway. Див. [Автентифікація trusted proxy](/uk/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy`: локальний debug proxy та capture inspector для розробки й підтримки. Див. [openclaw proxy](/uk/cli/proxy).
|
||||
- Налаштування проксі, специфічні для каналу або провайдера: owner-specific перевизначення для конкретного транспорту. Надавайте перевагу керованому мережевому проксі, коли мета — централізований контроль вихідного трафіку в усьому runtime.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -81,9 +81,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
|
||||
`proxy.proxyUrl` має пріоритет над `OPENCLAW_PROXY_URL`.
|
||||
|
||||
Якщо `enabled=true`, але не налаштовано чинний URL проксі, захищені команди завершують запуск з помилкою замість fallback до прямого доступу до мережі.
|
||||
Якщо `enabled=true`, але не налаштовано дійсний URL проксі, захищені команди завершують запуск з помилкою замість відкату до прямого мережевого доступу.
|
||||
|
||||
Для керованих сервісів Gateway, запущених через `openclaw gateway start`, краще зберігати URL у конфігурації:
|
||||
Для керованих gateway-сервісів, запущених через `openclaw gateway start`, краще зберігати URL у конфігурації:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -92,9 +92,9 @@ openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
Fallback через середовище найкраще підходить для запусків у передньому плані. Якщо ви використовуєте його з установленим сервісом, помістіть `OPENCLAW_PROXY_URL` у durable environment сервісу, наприклад `$OPENCLAW_STATE_DIR/.env` або `~/.openclaw/.env`, а потім перевстановіть сервіс, щоб launchd, systemd або Scheduled Tasks запускали Gateway із цим значенням.
|
||||
Fallback через середовище найкраще підходить для запусків у передньому плані. Якщо ви використовуєте його з інстальованим сервісом, помістіть `OPENCLAW_PROXY_URL` у довговічне середовище сервісу, наприклад `$OPENCLAW_STATE_DIR/.env` або `~/.openclaw/.env`, а потім перевстановіть сервіс, щоб launchd, systemd або Scheduled Tasks запускали gateway з цим значенням.
|
||||
|
||||
Для команд `openclaw --container ...` OpenClaw передає `OPENCLAW_PROXY_URL` у child CLI, націлений на контейнер, коли його задано. URL має бути доступним зсередини контейнера; `127.0.0.1` вказує на сам контейнер, а не на хост. OpenClaw відхиляє loopback URL проксі для команд, націлених на контейнер, якщо ви явно не перевизначите цю перевірку безпеки.
|
||||
Для команд `openclaw --container ...` OpenClaw передає `OPENCLAW_PROXY_URL` до дочірнього CLI, націленого на контейнер, коли його задано. URL має бути доступним зсередини контейнера; `127.0.0.1` означає сам контейнер, а не хост. OpenClaw відхиляє loopback URL проксі для команд, націлених на контейнер, якщо ви явно не перевизначите цю перевірку безпеки.
|
||||
|
||||
## Вимоги до проксі
|
||||
|
||||
@ -103,50 +103,50 @@ Fallback через середовище найкраще підходить д
|
||||
Налаштуйте проксі так, щоб він:
|
||||
|
||||
- Прив’язувався лише до loopback або приватного довіреного інтерфейсу.
|
||||
- Обмежував доступ так, щоб ним могли користуватися лише процес OpenClaw, хост, контейнер або сервісний обліковий запис.
|
||||
- Самостійно розв’язував призначення й блокував IP-адреси призначення після DNS-розв’язання.
|
||||
- Застосовував політику під час підключення як для простих HTTP-запитів, так і для HTTPS-тунелів `CONNECT`.
|
||||
- Відхиляв destination-based обходи для loopback, приватних, link-local, metadata, multicast, reserved або documentation діапазонів.
|
||||
- Уникав allowlist-ів імен хостів, якщо ви повністю не довіряєте шляху DNS-розв’язання.
|
||||
- Журналював призначення, рішення, статус і причину без журналювання тіл запитів, заголовків авторизації, cookies або інших секретів.
|
||||
- Обмежував доступ так, щоб ним могли користуватися лише процес OpenClaw, хост, контейнер або обліковий запис сервісу.
|
||||
- Самостійно резолвив призначення та блокував IP-адреси призначення після DNS-резолюції.
|
||||
- Застосовував політику під час підключення як для звичайних HTTP-запитів, так і для HTTPS-тунелів `CONNECT`.
|
||||
- Відхиляв обходи на основі призначення для loopback, приватних, link-local, metadata, multicast, reserved або documentation діапазонів.
|
||||
- Уникав allowlist імен хостів, якщо ви повністю не довіряєте шляху DNS-резолюції.
|
||||
- Журналював призначення, рішення, статус і причину без журналювання тіл запитів, заголовків авторизації, cookie або інших секретів.
|
||||
- Тримав політику проксі під контролем версій і переглядав зміни як security-sensitive конфігурацію.
|
||||
|
||||
## Рекомендовані заблоковані призначення
|
||||
|
||||
Використовуйте цей denylist як початкову точку для будь-якого forward proxy, firewall або політики вихідного трафіку.
|
||||
|
||||
Логіка класифікатора на рівні застосунку OpenClaw розташована в `src/infra/net/ssrf.ts` і `src/shared/net/ip.ts`. Відповідні parity hooks — це `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` і вбудована обробка sentinel IPv4 для NAT64, 6to4, Teredo, ISATAP і IPv4-mapped форм. Ці файли корисні як довідка під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила автоматично у вашому проксі.
|
||||
Логіка класифікатора OpenClaw на рівні застосунку міститься в `src/infra/net/ssrf.ts` і `src/shared/net/ip.ts`. Відповідні parity hooks — це `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` і вбудована обробка IPv4 sentinel для NAT64, 6to4, Teredo, ISATAP і IPv4-mapped форм. Ці файли є корисними довідковими матеріалами під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила автоматично у вашому проксі.
|
||||
|
||||
| Діапазон або хост | Чому блокувати |
|
||||
| Діапазон або хост | Навіщо блокувати |
|
||||
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback |
|
||||
| `::1/128` | IPv6 loopback |
|
||||
| `0.0.0.0/8`, `::/128` | Невизначені адреси та адреси цієї мережі |
|
||||
| `0.0.0.0/8`, `::/128` | Невказані адреси та адреси цієї мережі |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Приватні мережі RFC1918 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Link-local адреси й поширені шляхи cloud metadata |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Link-local адреси та поширені шляхи cloud metadata |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Сервіси cloud metadata |
|
||||
| `100.64.0.0/10` | Спільний адресний простір carrier-grade NAT |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Діапазони для benchmarking |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Діапазони special-use і documentation |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Діапазони для benchmark |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-use і documentation діапазони |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | Reserved IPv4 |
|
||||
| `240.0.0.0/4` | Зарезервований IPv4 |
|
||||
| `fc00::/7`, `fec0::/10` | Локальні/приватні діапазони IPv6 |
|
||||
| `100::/64`, `2001:20::/28` | Діапазони IPv6 discard і ORCHIDv2 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | NAT64 prefixes із вбудованим IPv4 |
|
||||
| `2002::/16`, `2001::/32` | 6to4 і Teredo із вбудованим IPv4 |
|
||||
| `100::/64`, `2001:20::/28` | IPv6 discard і ORCHIDv2 діапазони |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | Префікси NAT64 з вбудованим IPv4 |
|
||||
| `2002::/16`, `2001::/32` | 6to4 і Teredo з вбудованим IPv4 |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv4-compatible і IPv4-mapped IPv6 |
|
||||
|
||||
Якщо ваш cloud provider або мережева платформа документує додаткові metadata hosts чи reserved ranges, додайте їх також.
|
||||
Якщо ваш хмарний провайдер або мережева платформа документує додаткові metadata hosts чи reserved ranges, додайте також їх.
|
||||
|
||||
## Валідація
|
||||
|
||||
Перевіряйте проксі з того самого хоста, контейнера або сервісного облікового запису, на якому працює OpenClaw:
|
||||
Валідуйте проксі з того самого хоста, контейнера або облікового запису сервісу, який запускає OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
За замовчуванням, коли не надано власних призначень, команда перевіряє, що `https://example.com/` успішно відкривається, і запускає тимчасовий loopback canary, до якого проксі не повинен дістатися. Перевірка default denied проходить, коли проксі повертає не-2xx denial response або блокує canary з transport failure; вона провалюється, якщо успішна відповідь доходить до canary. Якщо проксі не ввімкнено й не налаштовано, валідація повідомляє про проблему конфігурації; використовуйте `--proxy-url` для одноразового preflight перед зміною конфігурації. Використовуйте `--allowed-url` і `--denied-url`, щоб перевірити deployment-specific очікування. Власні заборонені призначення є fail-closed: будь-яка HTTP-відповідь означає, що призначення було доступне через проксі, а будь-яка transport error повідомляється як inconclusive, бо OpenClaw не може довести, що проксі заблокував reachable origin. У разі помилки валідації команда завершується з кодом 1.
|
||||
За замовчуванням, коли власні призначення не надано, команда перевіряє, що `https://example.com/` успішний, і запускає тимчасовий loopback canary, до якого проксі не має дістатися. Типова заборонена перевірка проходить, коли проксі повертає non-2xx denial response або блокує canary через транспортний збій; вона провалюється, якщо успішна відповідь досягає canary. Якщо проксі не ввімкнено й не налаштовано, валідація повідомляє про проблему конфігурації; використовуйте `--proxy-url` для одноразового preflight перед зміною конфігурації. Використовуйте `--allowed-url` і `--denied-url`, щоб перевірити очікування, специфічні для розгортання. Власні заборонені призначення є fail-closed: будь-яка HTTP-відповідь означає, що призначення було доступне через проксі, а будь-яка транспортна помилка повідомляється як непереконлива, оскільки OpenClaw не може довести, що проксі заблокував доступне джерело. У разі помилки валідації команда завершується з кодом 1.
|
||||
|
||||
Використовуйте `--json` для автоматизації. JSON-вивід містить загальний результат, ефективне джерело конфігурації проксі, будь-які помилки конфігурації та кожну перевірку призначення. Облікові дані URL проксі редагуються в текстовому та JSON-виводі:
|
||||
|
||||
@ -170,7 +170,7 @@ openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
}
|
||||
```
|
||||
|
||||
Ви також можете перевірити вручну за допомогою `curl`:
|
||||
Також можна перевірити вручну за допомогою `curl`:
|
||||
|
||||
```bash
|
||||
curl -x http://127.0.0.1:3128 https://example.com/
|
||||
@ -178,9 +178,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
Публічний запит має виконатися успішно. Запити до loopback і метаданих має заблокувати проксі. Для `openclaw proxy validate` вбудований loopback canary може відрізнити відмову проксі від доступного джерела. Користувацькі перевірки `--denied-url` не мають цього canary, тому вважайте як HTTP-відповіді, так і неоднозначні транспортні збої помилками валідації, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо.
|
||||
Публічний запит має бути успішним. Запити до loopback і метаданих мають блокуватися проксі. Для `openclaw proxy validate` вбудована canary-перевірка loopback може відрізнити відмову проксі від доступного джерела. Користувацькі перевірки `--denied-url` не мають такої canary-перевірки, тому вважайте як HTTP-відповіді, так і неоднозначні транспортні збої помилками перевірки, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо.
|
||||
|
||||
Потім увімкніть маршрутизацію через проксі OpenClaw:
|
||||
Потім увімкніть маршрутизацію OpenClaw через проксі:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -198,9 +198,10 @@ proxy:
|
||||
|
||||
## Обмеження
|
||||
|
||||
- Проксі покращує покриття для процес-локальних HTTP- і WebSocket-клієнтів JavaScript, але це не мережевий sandbox рівня ОС.
|
||||
- Необроблені сокети `net`, `tls` і `http2`, нативні addons і дочірні процеси можуть обходити маршрутизацію через проксі на рівні Node, якщо вони не успадковують і не дотримуються змінних середовища проксі.
|
||||
- Локальні WebUI користувача та локальні сервери моделей за потреби слід додати до списку дозволених у політиці проксі оператора; OpenClaw не надає для них загального обходу локальної мережі.
|
||||
- Обхід проксі для площини керування Gateway навмисно обмежено `localhost` і буквальними URL-адресами loopback IP. Використовуйте `ws://127.0.0.1:18789`, `ws://[::1]:18789` або `ws://localhost:18789` для локальних прямих підключень до площини керування Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імен хостів.
|
||||
- Проксі покращує покриття для процесно-локальних JavaScript HTTP- і WebSocket-клієнтів, але не є мережевою пісочницею рівня ОС.
|
||||
- Необроблені сокети `net`, `tls` і `http2`, нативні аддони та дочірні процеси можуть обходити маршрутизацію проксі рівня Node, якщо вони не успадковують і не дотримуються змінних середовища проксі.
|
||||
- IRC — це необроблений TCP/TLS-канал поза маршрутизацією через прямий проксі, керований оператором. У розгортаннях, де весь вихідний трафік має проходити через цей прямий проксі, задайте `channels.irc.enabled=false`, якщо прямий вихідний IRC-трафік не схвалено явно.
|
||||
- Локальні WebUI користувачів і локальні сервери моделей за потреби слід додати до списку дозволених у політиці проксі оператора; OpenClaw не надає для них загального обходу локальної мережі.
|
||||
- Обхід проксі для контрольної площини Gateway навмисно обмежено `localhost` і URL-адресами з буквальними loopback IP. Використовуйте `ws://127.0.0.1:18789`, `ws://[::1]:18789` або `ws://localhost:18789` для локальних прямих підключень до контрольної площини Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імен хостів.
|
||||
- OpenClaw не перевіряє, не тестує й не сертифікує вашу політику проксі.
|
||||
- Розглядайте зміни політики проксі як безпеково чутливі операційні зміни.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user