diff --git a/docs/uk/gateway/index.md b/docs/uk/gateway/index.md index 843e8f01b..5ae0dc54b 100644 --- a/docs/uk/gateway/index.md +++ b/docs/uk/gateway/index.md @@ -1,31 +1,31 @@ --- read_when: - Запуск або налагодження процесу Gateway -summary: Посібник із Gateway service, його життєвого циклу та операцій -title: Посібник із Gateway +summary: Ранбук для сервісу Gateway, життєвого циклу та операцій +title: Ранбук Gateway x-i18n: - generated_at: "2026-04-24T20:11:16Z" + generated_at: "2026-04-26T00:40:09Z" model: gpt-5.4 provider: openai - source_hash: a1d82474bc6485cc14a0be74154e08ba54455031cdae37916de5bc615d3e01a4 + source_hash: 696ad47a7e2a85a27a6dbe0a220dc9d5b1320542854f162ae58ea4ede0195efa source_path: gateway/index.md workflow: 15 --- -Використовуйте цю сторінку для старту в перший день і операцій другого дня для служби Gateway. +Використовуйте цю сторінку для старту в перший день і операцій другого дня для сервісу Gateway. Діагностика від симптомів із точними послідовностями команд і сигнатурами логів. - Посібник із налаштування, орієнтований на задачі, + повний довідник із конфігурації. + Орієнтований на завдання посібник із налаштування + повний довідник із конфігурації. - Контракт SecretRef, поведінка знімка часу виконання та операції міграції/перезавантаження. + Контракт SecretRef, поведінка знімків під час виконання та операції міграції/перезавантаження. - Точні правила target/path для `secrets apply` і поведінка auth-profile лише з ref. + Точні правила цілі/шляху для `secrets apply` і поведінка auth-profile лише з посиланнями. @@ -36,15 +36,15 @@ x-i18n: ```bash openclaw gateway --port 18789 -# debug/trace дублюються у stdio +# debug/trace віддзеркалюються у stdio openclaw gateway --port 18789 --verbose -# примусово завершує listener на вибраному порту, потім запускає +# примусово завершує слухач на вибраному порту, потім запускає openclaw gateway --force ``` - + ```bash openclaw gateway status @@ -52,7 +52,7 @@ openclaw status openclaw logs --follow ``` -Справна базова конфігурація: `Runtime: running`, `Connectivity probe: ok` і `Capability: ...`, що відповідає вашим очікуванням. Використовуйте `openclaw gateway status --require-rpc`, коли вам потрібне підтвердження RPC із read-scope, а не лише досяжність. +Базовий здоровий стан: `Runtime: running`, `Connectivity probe: ok` і `Capability: ...`, що відповідає вашим очікуванням. Використовуйте `openclaw gateway status --require-rpc`, коли вам потрібне підтвердження RPC з областю читання, а не лише досяжність. @@ -62,35 +62,35 @@ openclaw logs --follow openclaw channels status --probe ``` -За наявності доступного Gateway це виконує живі перевірки каналів для кожного облікового запису та необов’язкові аудити. -Якщо Gateway недоступний, CLI повертається до зведень каналів лише на основі конфігурації -замість виводу живих перевірок. +За наявності доступного Gateway це виконує живі перевірки каналів для кожного акаунта та необов’язкові аудити. +Якщо Gateway недоступний, CLI повертається до зведень каналів лише за конфігурацією +замість виводу живої перевірки. -Перезавантаження конфігурації Gateway відстежує шлях до активного файлу конфігурації (визначений із типових значень профілю/стану або `OPENCLAW_CONFIG_PATH`, якщо задано). +Перезавантаження конфігурації Gateway відстежує шлях до активного файлу конфігурації (визначений із типових значень профілю/стану або `OPENCLAW_CONFIG_PATH`, якщо змінну задано). Типовий режим — `gateway.reload.mode="hybrid"`. -Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно замінює цей знімок. +Після першого успішного завантаження запущений процес обслуговує активний знімок конфігурації в пам’яті; успішне перезавантаження атомарно підміняє цей знімок. -## Модель часу виконання +## Модель виконання -- Один постійно активний процес для маршрутизації, control plane і підключень каналів. +- Один постійно запущений процес для маршрутизації, control plane і з’єднань каналів. - Один мультиплексований порт для: - WebSocket control/RPC - HTTP API, сумісних з OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`) - - Control UI і хуків + - UI керування і хуків - Типовий режим прив’язки: `loopback`. -- Автентифікація типово обов’язкова. Конфігурації зі спільним секретом використовують +- Автентифікація типово обов’язкова. Налаштування зі спільним секретом використовують `gateway.auth.token` / `gateway.auth.password` (або - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а для не-loopback - конфігурацій зі зворотним проксі можна використовувати `gateway.auth.mode: "trusted-proxy"`. + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), а для non-loopback + налаштувань зі зворотним проксі можна використовувати `gateway.auth.mode: "trusted-proxy"`. -## Сумісні з OpenAI endpoint-и +## Кінцеві точки, сумісні з OpenAI -Найцінніша поверхня сумісності OpenClaw зараз така: +Поверхня сумісності OpenClaw з найбільшою віддачею зараз така: - `GET /v1/models` - `GET /v1/models/{id}` @@ -101,38 +101,44 @@ openclaw channels status --probe Чому цей набір важливий: - Більшість інтеграцій Open WebUI, LobeChat і LibreChat спочатку перевіряють `/v1/models`. -- Багато RAG- і memory-конвеєрів очікують `/v1/embeddings`. -- Клієнти, орієнтовані на агентів, дедалі частіше надають перевагу `/v1/responses`. +- Багато конвеєрів RAG і пам’яті очікують `/v1/embeddings`. +- Клієнти, орієнтовані на агентів, дедалі частіше віддають перевагу `/v1/responses`. Примітка щодо планування: - `/v1/models` орієнтований насамперед на агентів: він повертає `openclaw`, `openclaw/default` і `openclaw/`. -- `openclaw/default` — це стабільний псевдонім, який завжди вказує на налаштованого типового агента. -- Використовуйте `x-openclaw-model`, коли вам потрібно перевизначити backend provider/model; інакше керування зберігають звичайна модель і налаштування embeddings вибраного агента. +- `openclaw/default` — це стабільний псевдонім, який завжди вказує на налаштованого агента за замовчуванням. +- Використовуйте `x-openclaw-model`, якщо хочете перевизначити backend provider/model; інакше керування залишається за звичайною моделлю та налаштуванням embedding вибраного агента. Усе це працює на основному порту Gateway і використовує ту саму межу автентифікації довіреного оператора, що й решта HTTP API Gateway. ### Пріоритет порту та прив’язки -| Налаштування | Порядок визначення | -| ------------ | -------------------------------------------------------------- | +| Налаштування | Порядок визначення | +| ------------ | ------------------------------------------------------------- | | Порт Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` | | Режим bind | CLI/override → `gateway.bind` → `loopback` | -### Режими hot reload +Під час запуску Gateway використовує ті самі ефективні порт і прив’язку, коли задає локальні +джерела Control UI для non-loopback прив’язок. Наприклад, `--bind lan --port 3000` +додає `http://localhost:3000` і `http://127.0.0.1:3000` до виконання +перевірки під час виконання. Будь-які віддалені джерела браузера, наприклад HTTPS URL проксі, додавайте в +`gateway.controlUi.allowedOrigins` явно. + +### Режими гарячого перезавантаження | `gateway.reload.mode` | Поведінка | | --------------------- | ------------------------------------------ | | `off` | Без перезавантаження конфігурації | -| `hot` | Застосовує лише hot-safe зміни | -| `restart` | Перезапускає за змін, що вимагають reload | -| `hybrid` (типово) | Hot-apply, коли безпечно, restart за потреби | +| `hot` | Застосовувати лише безпечні для hot зміни | +| `restart` | Перезапуск при змінах, що вимагають reload | +| `hybrid` (типово) | Гаряче застосування, коли безпечно, і перезапуск за потреби | ## Набір команд оператора ```bash openclaw gateway status -openclaw gateway status --deep # додає сканування служби на рівні системи +openclaw gateway status --deep # додає перевірку сервісу на рівні системи openclaw gateway status --json openclaw gateway install openclaw gateway restart @@ -142,15 +148,15 @@ openclaw logs --follow openclaw doctor ``` -`gateway status --deep` призначено для додаткового виявлення служб (системні +`gateway status --deep` призначено для додаткового виявлення сервісів (системні одиниці LaunchDaemons/systemd/schtasks), а не для глибшої перевірки стану RPC. ## Кілька Gateway (на одному хості) -У більшості інсталяцій слід запускати один Gateway на машину. Один Gateway може обслуговувати кілька -агентів і каналів. +У більшості інсталяцій слід запускати один Gateway на машину. Один Gateway може розміщувати кількох +агентів і канали. -Кілька Gateway потрібні лише тоді, коли вам навмисно потрібна ізоляція або rescue bot. +Кілька Gateway потрібні лише тоді, коли вам навмисно потрібна ізоляція або резервний бот. Корисні перевірки: @@ -163,9 +169,9 @@ openclaw gateway probe - `gateway status --deep` може повідомити `Other gateway-like services detected (best effort)` і вивести підказки з очищення, якщо ще залишилися застарілі інсталяції launchd/systemd/schtasks. -- `gateway probe` може попереджати про `multiple reachable gateways`, коли відповідає - більше ніж одна ціль. -- Якщо це навмисно, ізолюйте порти, config/state і корені workspace для кожного Gateway. +- `gateway probe` може попередити про `multiple reachable gateways`, коли відповідає + більше однієї цілі. +- Якщо це навмисно, ізолюйте порти, конфігурацію/стан і корені робочих просторів для кожного Gateway. Контрольний список для кожного екземпляра: @@ -181,25 +187,25 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002 ``` -Докладне налаштування: [/gateway/multiple-gateways](/uk/gateway/multiple-gateways). +Детальне налаштування: [/gateway/multiple-gateways](/uk/gateway/multiple-gateways). -## Endpoint мозку реального часу VoiceClaw +## Кінцева точка мозку реального часу VoiceClaw -OpenClaw надає сумісний із VoiceClaw endpoint WebSocket реального часу за адресою -`/voiceclaw/realtime`. Використовуйте його, коли клієнт VoiceClaw для настільних систем має напряму -підключатися до мозку OpenClaw реального часу замість проходження через окремий relay- -процес. +OpenClaw надає сумісну з VoiceClaw кінцеву точку WebSocket реального часу за адресою +`/voiceclaw/realtime`. Використовуйте її, коли настільний клієнт VoiceClaw має напряму +підключатися до мозку OpenClaw реального часу замість окремого процесу +ретрансляції. -Endpoint використовує Gemini Live для аудіо реального часу та викликає OpenClaw як -мозок, безпосередньо надаючи інструменти OpenClaw для Gemini Live. Виклики інструментів повертають -негайний результат `working`, щоб зберігати чутливість голосового ходу, після чого OpenClaw -виконує фактичний інструмент асинхронно й повертає результат назад у -живу сесію. Установіть `GEMINI_API_KEY` у середовищі процесу Gateway. Якщо -автентифікацію Gateway увімкнено, клієнт для настільних систем надсилає токен або пароль Gateway +Кінцева точка використовує Gemini Live для аудіо реального часу і викликає OpenClaw як +мозок, надаючи інструменти OpenClaw безпосередньо Gemini Live. Виклики інструментів повертають +негайний результат `working`, щоб голосовий хід залишався чутливим, а потім OpenClaw +виконує фактичний інструмент асинхронно й підставляє результат назад у +живу сесію. Задайте `GEMINI_API_KEY` у середовищі процесу Gateway. Якщо +автентифікацію Gateway увімкнено, настільний клієнт надсилає токен або пароль Gateway у своєму першому повідомленні `session.config`. -Доступ до мозку реального часу виконує команди агента OpenClaw, авторизовані власником. Залишайте -`gateway.auth.mode: "none"` лише для тестових екземплярів, доступних тільки через loopback. Для нелокальних +Доступ до мозку реального часу виконує команди агента OpenClaw, авторизовані власником. Обмежуйте +`gateway.auth.mode: "none"` лише тестовими екземплярами, доступними через loopback. Для нелокальних підключень до мозку реального часу потрібна автентифікація Gateway. Для ізольованого тестового Gateway запустіть окремий екземпляр із власними портом, конфігурацією @@ -228,19 +234,19 @@ ws://127.0.0.1:19789/voiceclaw/realtime ssh -N -L 18789:127.0.0.1:18789 user@host ``` -Потім підключайте клієнтів локально до `ws://127.0.0.1:18789`. +Потім підключайте клієнти локально до `ws://127.0.0.1:18789`. SSH-тунелі не обходять автентифікацію Gateway. Для автентифікації зі спільним секретом клієнти все одно -мають надсилати `token`/`password` навіть через тунель. Для режимів, що несуть ідентичність, -запит усе одно має задовольняти цей шлях автентифікації. +мають надсилати `token`/`password`, навіть через тунель. Для режимів з ідентифікацією +запит однаково має відповідати цьому шляху автентифікації. Див.: [Remote Gateway](/uk/gateway/remote), [Authentication](/uk/gateway/authentication), [Tailscale](/uk/gateway/tailscale). -## Нагляд і життєвий цикл служби +## Нагляд і життєвий цикл сервісу -Для надійності, подібної до production, використовуйте запуски під наглядом. +Для надійності, близької до production, використовуйте запуск під наглядом. @@ -252,7 +258,7 @@ openclaw gateway restart openclaw gateway stop ``` -Мітки LaunchAgent: `ai.openclaw.gateway` (типово) або `ai.openclaw.` (іменований профіль). `openclaw doctor` перевіряє та виправляє розходження конфігурації служби. +Мітки LaunchAgent: `ai.openclaw.gateway` (типово) або `ai.openclaw.` (іменований профіль). `openclaw doctor` перевіряє та виправляє дрейф конфігурації сервісу. @@ -264,13 +270,13 @@ systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` -Для збереження після виходу з системи ввімкніть lingering: +Для збереження після виходу із системи увімкніть lingering: ```bash sudo loginctl enable-linger ``` -Приклад ручної user-unit, коли потрібен власний шлях інсталяції: +Приклад ручного user-unit, коли потрібен власний шлях інсталяції: ```ini [Unit] @@ -302,9 +308,10 @@ openclaw gateway restart openclaw gateway stop ``` -Керований автозапуск у нативному Windows використовує Scheduled Task з назвою `OpenClaw Gateway` -(або `OpenClaw Gateway ()` для іменованих профілів). Якщо створення Scheduled Task -заборонено, OpenClaw перемикається на launcher у папці Startup для поточного користувача, який вказує на `gateway.cmd` у каталозі стану. +Керований нативний запуск у Windows використовує заплановане завдання з назвою `OpenClaw Gateway` +(або `OpenClaw Gateway ()` для іменованих профілів). Якщо створення запланованого завдання +заборонено, OpenClaw повертається до запуску через Startup-folder для поточного користувача, +який вказує на `gateway.cmd` усередині каталогу стану. @@ -317,7 +324,7 @@ sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -Використовуйте те саме тіло служби, що й для user unit, але інсталюйте його в +Використовуйте те саме тіло сервісу, що й для user unit, але встановлюйте його в `/etc/systemd/system/openclaw-gateway[-].service` і скоригуйте `ExecStart=`, якщо ваш бінарний файл `openclaw` розташований в іншому місці. @@ -332,23 +339,23 @@ openclaw --dev gateway --allow-unconfigured openclaw --dev status ``` -Типові значення включають ізольований state/config і базовий порт Gateway `19001`. +Типові значення включають ізольовані стан/конфігурацію та базовий порт Gateway `19001`. -## Короткий довідник з протоколу (погляд оператора) +## Короткий довідник протоколу (погляд оператора) - Першим кадром клієнта має бути `connect`. - Gateway повертає знімок `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy). - `hello-ok.features.methods` / `events` — це консервативний список виявлення, а не - згенерований дамп кожного доступного helper route. + згенерований дамп кожного викличного допоміжного маршруту. - Запити: `req(method, params)` → `res(ok/payload|error)`. -- Типові події включають `connect.challenge`, `agent`, `chat`, +- Поширені події включають `connect.challenge`, `agent`, `chat`, `session.message`, `session.tool`, `sessions.changed`, `presence`, `tick`, `health`, `heartbeat`, події життєвого циклу pairing/approval і `shutdown`. -Запуски агентів — двоетапні: +Запуски агентів є двоетапними: 1. Негайне підтвердження прийняття (`status:"accepted"`) -2. Остаточна відповідь про завершення (`status:"ok"|"error"`), зі streaming-подіями `agent` між ними. +2. Остаточна відповідь завершення (`status:"ok"|"error"`), із потоковими подіями `agent` між ними. Див. повну документацію протоколу: [Gateway Protocol](/uk/gateway/protocol). @@ -369,23 +376,23 @@ openclaw health ### Відновлення після пропусків -Події не відтворюються повторно. За пропусків у послідовності оновіть стан (`health`, `system-presence`), перш ніж продовжувати. +Події не відтворюються повторно. За пропусків у послідовності оновіть стан (`health`, `system-presence`) перед продовженням. -## Типові сигнатури збоїв +## Поширені сигнатури збоїв -| Сигнатура | Ймовірна проблема | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `refusing to bind gateway ... without auth` | Прив’язка не-loopback без дійсного шляху автентифікації Gateway | -| `another gateway instance is already listening` / `EADDRINUSE` | Конфлікт порту | +| Сигнатура | Імовірна проблема | +| -------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| `refusing to bind gateway ... without auth` | Non-loopback прив’язка без дійсного шляху автентифікації Gateway | +| `another gateway instance is already listening` / `EADDRINUSE` | Конфлікт портів | | `Gateway start blocked: set gateway.mode=local` | У конфігурації встановлено віддалений режим або в пошкодженій конфігурації відсутній штамп локального режиму | -| `unauthorized` during connect | Невідповідність автентифікації між клієнтом і Gateway | +| `unauthorized` during connect | Невідповідність автентифікації між клієнтом і Gateway | Для повних послідовностей діагностики використовуйте [Gateway Troubleshooting](/uk/gateway/troubleshooting). ## Гарантії безпеки -- Клієнти протоколу Gateway швидко завершуються з помилкою, коли Gateway недоступний (без неявного fallback напряму до каналу). -- Некоректні перші кадри або перші кадри не `connect` відхиляються, а з’єднання закривається. +- Клієнти протоколу Gateway швидко завершуються з помилкою, коли Gateway недоступний (без неявного прямого резервного переходу на канал). +- Неприпустимі/не-`connect` перші кадри відхиляються, а з’єднання закривається. - Коректне завершення роботи надсилає подію `shutdown` перед закриттям сокета. --- diff --git a/docs/uk/help/testing-live.md b/docs/uk/help/testing-live.md index 10a324f68..f8097cd03 100644 --- a/docs/uk/help/testing-live.md +++ b/docs/uk/help/testing-live.md @@ -1,35 +1,35 @@ --- read_when: - - Запуск перевірок live для матриці моделей / бекенду CLI / ACP / медіапровайдерів + - Запуск живих smoke-тестів для матриці моделей / бекенду CLI / ACP / медіапровайдерів - Налагодження визначення облікових даних для живих тестів - - Додавання нового живого тесту для конкретного провайдера + - Додавання нового живого тесту, специфічного для провайдера sidebarTitle: Live tests -summary: 'Живі (із мережевими зверненнями) тести: матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' +summary: 'Живі тести (що взаємодіють із мережею): матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' title: 'Тестування: живі набори тестів' x-i18n: - generated_at: "2026-04-25T20:48:52Z" + generated_at: "2026-04-26T00:40:10Z" model: gpt-5.4 provider: openai - source_hash: 70f3539054e1e19f8a8f312e9b571a1e5894f868c3bc963756db4de9b6aaf8b0 + source_hash: 669d68dc80d0bf86942635c792f64f1edc7a23684c880cb66799401dee3d127f source_path: help/testing-live.md workflow: 15 --- -Для швидкого старту, раннерів QA, unit/integration наборів і Docker-потоків див. -[Testing](/uk/help/testing). Ця сторінка охоплює **живі** (із мережевими зверненнями) набори тестів: -матрицю моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також +Для швидкого старту, QA-ранерів, unit/integration наборів тестів і Docker-потоків див. +[Тестування](/uk/help/testing). Ця сторінка охоплює **живі** (що взаємодіють із мережею) +набори тестів: матрицю моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також обробку облікових даних. -## Живі: команди локального smoke-тестування профілю +## Живі: локальні команди smoke-тестів для профілю -Підключайте `~/.profile` перед разовими живими перевірками, щоб ключі провайдерів і локальні шляхи до інструментів -відповідали вашій оболонці: +Виконайте `source ~/.profile` перед разовими живими перевірками, щоб ключі провайдерів і шляхи +до локальних інструментів відповідали вашій оболонці: ```bash source ~/.profile ``` -Безпечна медіаперевірка: +Безпечний smoke-тест для медіа: ```bash pnpm openclaw infer tts convert --local --json \ @@ -37,131 +37,131 @@ pnpm openclaw infer tts convert --local --json \ --output /tmp/openclaw-live-smoke.mp3 ``` -Безпечна перевірка готовності голосового виклику: +Безпечний smoke-тест готовності голосових викликів: ```bash pnpm openclaw voicecall setup --json pnpm openclaw voicecall smoke --to "+15555550123" ``` -`voicecall smoke` є dry run, якщо також не вказано `--yes`. Використовуйте `--yes` лише тоді, -коли ви свідомо хочете здійснити реальний сповіщувальний дзвінок. Для Twilio, Telnyx і -Plivo успішна перевірка готовності потребує публічного URL Webhook; fallback-варіанти лише для локального -loopback/приватного доступу навмисно відхиляються. +`voicecall smoke` — це пробний запуск, якщо також не вказано `--yes`. Використовуйте `--yes` лише +тоді, коли ви свідомо хочете здійснити справжній сповіщувальний виклик. Для Twilio, Telnyx і +Plivo успішна перевірка готовності вимагає публічної URL-адреси Webhook; лише локальні +резервні варіанти loopback/private за задумом відхиляються. -## Живі: перевірка можливостей Android Node +## Живі: повний прохід можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка наразі оголошена** підключеним Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, що наразі оголошена** підключеним Android Node, і перевірити поведінку контракту команд. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не виконує pair для застосунку). - - Покомандна перевірка gateway `node.invoke` для вибраного Android Node. -- Обов’язкове попереднє налаштування: - - Android-застосунок уже підключено й pair виконано з Gateway. + - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює/не запускає/не спаровує застосунок). + - Перевірка `node.invoke` шлюзу для кожної команди для вибраного Android Node. +- Необхідне попереднє налаштування: + - Android-застосунок уже підключено й спаровано зі Gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте як успішні. + - Дозволи/згода на захоплення надані для можливостей, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості щодо налаштування Android: [Android App](/uk/platforms/android) -## Живі: перевірка моделі (ключі профілю) +## Живі: smoke-тест моделей (ключі профілю) Живі тести поділено на два рівні, щоб можна було ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). +- «Пряма модель» показує, чи провайдер/модель взагалі можуть відповісти з указаним ключем. +- «Smoke-тест Gateway» показує, чи працює для цієї моделі весь конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: Безпосереднє завершення моделі (без gateway) +### Рівень 1: пряме завершення моделі (без Gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і цільові регресійні перевірки за потреби) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресійні перевірки там, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді виконувався; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір тестів; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на smoke-тестах Gateway - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all перевірок за замовчуванням використовується curated high-signal ліміт; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. - - Вичерпні перевірки використовують `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього direct-model тесту. Типове значення: 60 хвилин. - - Direct-model перевірки за замовчуванням виконуються з паралелізмом 20; щоб перевизначити, установіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. + - Для modern/all проходів за замовчуванням використовується підібране обмеження високосигнальних моделей; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-проходу або додатне число для меншого обмеження. + - Вичерпні проходи використовують `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут для всього тесту прямої моделі. Типове значення: 60 хвилин. + - Перевірки прямої моделі за замовчуванням запускаються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і fallback через env + - За замовчуванням: сховище профілів і резервні значення env - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки виклику інструментів) -### Рівень 2: Gateway + smoke dev agent (те, що фактично робить "@openclaw") +### Рівень 2: smoke-тест Gateway + dev agent (те, що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Запустити in-process Gateway - - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Перебрати моделі з ключами й перевірити: + - Підняти внутрішньопроцесний Gateway + - Створити/оновити сесію `agent:dev:*` (з перевизначенням моделі для кожного запуску) + - Ітеруватися по моделях із ключами та перевіряти: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (перевірка `read`) + - що працює справжній виклик інструмента (перевірка читання) - необов’язкові додаткові перевірки інструментів (перевірка exec+read) - - що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють -- Деталі перевірок (щоб ви могли швидко пояснити збої): - - перевірка `read`: тест записує nonce-файл у workspace і просить agent виконати `read` для нього та повернути nonce у відповіді. - - перевірка `exec+read`: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім прочитати його назад через `read`. - - перевірка зображення: тест додає згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat `. + - що регресійні шляхи OpenAI (лише виклик інструмента → продовження) не ламаються +- Подробиці перевірок (щоб можна було швидко пояснювати збої): + - перевірка `read`: тест записує nonce-файл у робочий простір і просить agent `read` його та повернути nonce. + - перевірка `exec+read`: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім прочитати його через `read`. + - перевірка зображення: тест додає згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для modern/all gateway-перевірок за замовчуванням використовується curated high-signal ліміт; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникати «OpenRouter everything»): + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому) для звуження + - Для modern/all проходів Gateway за замовчуванням використовується підібране обмеження високосигнальних моделей; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-проходу або додатне число для меншого обмеження. +- Як вибирати провайдерів (уникнути «усе через OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) - Перевірки інструментів і зображень у цьому живому тесті завжди ввімкнені: - - перевірка `read` + перевірка `exec+read` (навантаження на інструменти) - - перевірка зображення запускається, коли модель повідомляє про підтримку введення зображень + - перевірка `read` + перевірка `exec+read` (навантажувальна перевірка інструментів) + - перевірка зображення запускається, коли модель заявляє про підтримку вхідних зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволено) + - Вбудований agent передає моделі мультимодальне повідомлення користувача + - Перевірка: відповідь містить `cat` + код (допускається OCR-похибка: незначні помилки дозволені) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Живі: перевірка бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) +## Живі: smoke-тест бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent із локальним бекендом CLI, не змінюючи вашу типову конфігурацію. -- Типові параметри smoke для конкретного бекенду містяться у визначенні `cli-backend.ts` відповідного Plugin. +- Мета: перевірити конвеєр Gateway + agent за допомогою локального CLI-бекенду, не торкаючись вашої типової конфігурації. +- Типові значення smoke-тестів для конкретного бекенду зберігаються у визначенні `cli-backend.ts` розширення-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Команда/аргументи/поведінка зображень беруться з метаданих відповідного Plugin бекенду CLI. + - Типові провайдер/модель: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих Plugin бекенду CLI-власника. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи вбудовуються в prompt). У рецептах Docker це типово вимкнено, якщо явно не запитано. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість вбудовування в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, щоб увімкнути перевірку безперервності тієї самої сесії Claude Sonnet -> Opus, коли вибрана модель підтримує ціль перемикання. У рецептах Docker це типово вимкнено для загальної надійності. - - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, щоб увімкнути перевірку loopback MCP/tool. У рецептах Docker це типово вимкнено, якщо явно не запитано. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи впроваджуються в prompt). У Docker-рецептах це типово вимкнено, якщо явно не запитано. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість впровадження в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, щоб увімкнути перевірку безперервності тієї самої сесії Claude Sonnet -> Opus, коли вибрана модель підтримує ціль перемикання. У Docker-рецептах це типово вимкнено для загальної надійності. + - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, щоб увімкнути loopback-перевірку MCP/інструментів. У Docker-рецептах це типово вимкнено, якщо явно не запитано. Приклад: @@ -171,7 +171,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Недорога перевірка конфігурації Gemini MCP: +Дешева перевірка конфігурації Gemini MCP: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -179,17 +179,17 @@ OPENCLAW_LIVE_TEST=1 \ ``` Це не просить Gemini згенерувати відповідь. Воно записує ті самі системні -налаштування, які OpenClaw передає Gemini, а потім запускає `gemini --debug mcp list`, щоб довести, що -збережений сервер `transport: "streamable-http"` нормалізується до HTTP MCP-форми Gemini і -може підключатися до локального streamable-HTTP MCP-сервера. +налаштування, які OpenClaw передає Gemini, а потім запускає `gemini --debug mcp list`, щоб довести, +що збережений сервер `transport: "streamable-http"` нормалізується до HTTP MCP-форми Gemini і +може підключитися до локального streamable-HTTP MCP-сервера. -Рецепт Docker: +Docker-рецепт: ```bash pnpm test:docker:live-cli-backend ``` -Рецепти Docker для окремих провайдерів: +Docker-рецепти для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -200,32 +200,33 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає живу перевірку бекенду CLI всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані перевірки CLI з відповідного extension, а потім установлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища Anthropic API-key. Цей subscription lane типово вимикає перевірки Claude MCP/tool і image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію extra-usage, а не через звичайні ліміти плану підписки. -- Жива перевірка бекенду CLI тепер охоплює той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. -- Типова перевірка Claude також оновлює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає живий smoke-тест CLI-бекенду всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke-тесту CLI з розширення-власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносимого OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-бекенду без збереження змінних середовища ключа Anthropic API. За замовчуванням цей режим підписки вимикає перевірки Claude MCP/інструментів і зображень, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг додаткового використання, а не через звичайні ліміти тарифного плану підписки. +- Живий smoke-тест CLI-бекенду тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через шлюз CLI. +- Типовий smoke-тест Claude також оновлює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Живі: перевірка прив’язки ACP (`/acp spawn ... --bind here`) +## Живий: smoke-тест прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік ACP conversation-bind із живим ACP agent: +- Мета: перевірити справжній потік прив’язки розмови ACP із живим ACP-агентом: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову каналу повідомлень на місці - - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє до transcript прив’язаної ACP-сесії + - надіслати звичайне подальше повідомлення в тій самій розмові + - перевірити, що подальше повідомлення потрапляє в транскрипт прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agents у Docker: `claude,codex,gemini` - - ACP agent для прямого `pnpm test:live ...`: `claude` + - ACP-агенти в Docker: `claude,codex,gemini` + - ACP-агент для прямого `pnpm test:live ...`: `claude` - Синтетичний канал: контекст розмови в стилі Slack DM - - Бекенд ACP: `acpx` + - ACP-бекенд: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` + - `OPENCLAW_LIVE_ACP_BIND_AGENT=droid` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT=opencode` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` @@ -235,8 +236,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_TRANSCRIPT=1` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2` - Примітки: - - Ця lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли приєднувати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent із вбудованого Plugin `acpx` для вибраного ACP harness agent. + - Цей режим використовує поверхню gateway `chat.send` з полями синтетичного originating-route, доступними лише адміністратору, щоб тести могли приєднувати контекст каналу повідомлень без удавання зовнішньої доставки. + - Якщо `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів встроєного Plugin `acpx` для вибраного ACP harness-агента. Приклад: @@ -246,55 +247,57 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного agent: +Docker-рецепти для одного агента: ```bash pnpm test:docker:live-acp-bind:claude pnpm test:docker:live-acp-bind:codex +pnpm test:docker:live-acp-bind:droid pnpm test:docker:live-acp-bind:gemini pnpm test:docker:live-acp-bind:opencode ``` Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає ACP bind smoke для сукупних живих CLI agents послідовно: `claude`, `codex`, потім `gemini`. -- Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode`, щоб звузити матрицю. -- Він підключає `~/.profile`, підготовлює відповідні матеріали автентифікації CLI в контейнері, а потім установлює запитаний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex`, `@google/gemini-cli` або `opencode-ai`), якщо його бракує. Сам бекенд ACP — це вбудований пакет `acpx/runtime` із Plugin `acpx`. -- Варіант OpenCode для Docker — це сувора регресійна lane для одного agent. Він записує тимчасову типову модель `OPENCODE_CONFIG_CONTENT` з `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (типово `opencode/kimi-k2.6`) після підключення `~/.profile`, а `pnpm test:docker:live-acp-bind:opencode` вимагає transcript прив’язаного assistant замість прийняття загального post-bind skip. -- Прямі виклики CLI `acpx` — це лише ручний/обхідний шлях для порівняння поведінки поза Gateway. Docker ACP bind smoke перевіряє вбудований бекенд середовища виконання `acpx` в OpenClaw. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke-тест прив’язки ACP для сукупних живих CLI-агентів послідовно: `claude`, `codex`, потім `gemini`. +- Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode`, щоб звузити матрицю. +- Він виконує `source ~/.profile`, поміщає відповідні автентифікаційні матеріали CLI в контейнер, а потім встановлює запитуваний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid через `https://app.factory.ai/cli`, `@google/gemini-cli` або `opencode-ai`), якщо його бракує. Сам ACP-бекенд — це комплектний вбудований пакет `acpx/runtime` з Plugin `acpx`. +- Варіант Droid для Docker поміщає `~/.factory` для налаштувань, передає `FACTORY_API_KEY` і вимагає цей API-ключ, оскільки локальна Factory OAuth/keyring-автентифікація не є переносимою в контейнер. Він використовує вбудований запис реєстру ACPX `droid exec --output-format acp`. +- Варіант OpenCode для Docker — це суворий регресійний режим для одного агента. Він записує тимчасову типову модель `OPENCODE_CONFIG_CONTENT` із `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (типово `opencode/kimi-k2.6`) після виконання `source ~/.profile`, а `pnpm test:docker:live-acp-bind:opencode` вимагає транскрипт прив’язаного помічника замість прийняття загального пропуску після прив’язки. +- Прямі виклики CLI `acpx` — це лише ручний/обхідний шлях для порівняння поведінки поза Gateway. Docker smoke-тест прив’язки ACP перевіряє вбудований бекенд runtime `acpx` в OpenClaw. -## Живі: smoke Codex app-server harness +## Живий: smoke-тест harness app-server Codex -- Мета: перевірити Codex harness, що належить Plugin, через звичайний метод gateway - `agent`: - - завантажити вбудований Plugin `codex` +- Мета: перевірити harness Codex, яким володіє Plugin, через звичайний + метод gateway `agent`: + - завантажити комплектний Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `openai/gpt-5.2` із примусово вибраним Codex harness - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік - app-server може бути відновлений + - надіслати перший хід gateway agent до `openai/gpt-5.2` з примусово вибраним harness Codex + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік app-server + може відновитися - виконати `/codex status` і `/codex models` через той самий шлях - команд gateway - - за потреби виконати дві Guardian-reviewed перевірки shell з підвищенням прав: одну нешкідливу - команду, яку має бути схвалено, і одне фальшиве вивантаження секрету, яке має бути - відхилено, щоб agent перепитав + команди gateway + - за потреби виконати дві перевірки shell з підвищенням прав, переглянуті Guardian: одну нешкідливу + команду, яку слід схвалити, і одне фальшиве вивантаження секрету, яке слід + відхилити, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `openai/gpt-5.2` - Необов’язкова перевірка зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язкова перевірка MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язкова перевірка MCP/інструментів: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти непомітно через fallback до PI. -- Автентифікація: автентифікація Codex app-server із локального входу в підписку Codex. Docker - smoke-тести також можуть передавати `OPENAI_API_KEY` для не-Codex перевірок, де це доречно, - а також за потреби скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. +- У цьому smoke-тесті встановлюється `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти, непомітно переключившись на запасний варіант PI. +- Автентифікація: автентифікація app-server Codex із локального логіна підписки Codex. Docker- + smoke-тести також можуть надавати `OPENAI_API_KEY` для не-Codex перевірок, де це доречно, + а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -308,7 +311,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash source ~/.profile @@ -317,73 +320,73 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він підключає змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації Codex CLI за наявності, установлює `@openai/codex` у доступний для запису змонтований npm - префікс, готує дерево вихідного коду, а потім запускає лише живий тест Codex-harness. -- У Docker перевірки image, MCP/tool і Guardian увімкнені за замовчуванням. Установіть +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він виконує `source` для змонтованого `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у змонтований записуваний npm- + префікс, поміщає дерево вихідного коду, а потім запускає лише живий тест harness Codex. +- У Docker за замовчуванням увімкнені перевірки зображення, MCP/інструментів і Guardian. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий - налагоджувальний запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфігурації живого - тесту, щоб застарілі псевдоніми або fallback до PI не могли приховати регресію - Codex harness. + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий режим + налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, що відповідає конфігурації живого + тесту, тому застарілі псевдоніми або запасний варіант PI не можуть приховати регресію + harness Codex. ### Рекомендовані живі рецепти -Вузькі, явні allowlist є найшвидшими й найменш нестабільними: +Вузькі, явні allowlist — найшвидші й найменш схильні до збоїв: -- Одна модель, direct (без gateway): +- Одна модель, напряму (без Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, gateway smoke: +- Одна модель, smoke-тест Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклики інструментів для кількох провайдерів: +- Виклик інструментів для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (ключ API Gemini + Antigravity): - - Gemini (ключ API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API-ключ Gemini + Antigravity): + - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Smoke adaptive thinking для Google: - - Якщо локальні ключі зберігаються в профілі оболонки: `source ~/.profile` +- Живий smoke-тест adaptive thinking для Google: + - Якщо локальні ключі містяться в профілі оболонки: `source ~/.profile` - Gemini 3 dynamic default: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` - Gemini 2.5 dynamic budget: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` Примітки: -- `google/...` використовує API Gemini (ключ API). -- `google-antigravity/...` використовує OAuth-міст Antigravity (кінцева точка agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google/...` використовує Gemini API (API-ключ). +- `google-antigravity/...` використовує міст Antigravity OAuth (кінцева точка агента в стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (ключ API / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розходження версій). -## Живі: матриця моделей (що ми охоплюємо) +## Живі: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (живі тести вмикаються за бажанням), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Фіксованого «списку моделей CI» немає (живі тести вмикаються за бажанням), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. -### Сучасний набір smoke (виклик інструментів + зображення) +### Сучасний набір smoke-тестів (виклик інструментів + зображення) Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: -- OpenAI (не-Codex): `openai/gpt-5.2` +- OpenAI (не Codex): `openai/gpt-5.2` - OpenAI Codex OAuth: `openai-codex/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) +- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - DeepSeek: `deepseek/deepseek-v4-flash` і `deepseek/deepseek-v4-pro` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з інструментами + зображенням: +Запустити smoke-тест Gateway з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язково Exec) -Виберіть щонайменше одну модель на сімейство провайдерів: +Виберіть принаймні одну модель для кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -392,46 +395,46 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано): +Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою інструментів, яку у вас ввімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Включіть щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою Vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. ### Агрегатори / альтернативні gateway -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідні кандидати з підтримкою інструментів і зображень) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до живої матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, яких можна включити в живу матрицю (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` - Через `models.providers` (власні кінцеві точки): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко фіксувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко прописати в документації «всі моделі». Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, плюс ті ключі, які доступні. ## Облікові дані (ніколи не комітьте) Живі тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, живі тести мають знаходити ті самі ключі. -- Якщо живий тест повідомляє «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, живі тести мають знайти ті самі ключі. +- Якщо живий тест повідомляє «немає облікових даних», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» у живих тестах) +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в живих тестах означає «ключі профілю») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home за наявності, але не є основним сховищем ключів профілю) -- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` і `agentDir` видаляються, щоб перевірки не торкалися вашого реального host workspace. +- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в підготовлений живий home, якщо присутній, але це не основне сховище ключів профілю) +- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; підготовлені живі home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб перевірки не працювали з вашим справжнім робочим простором хоста. -Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Живий Deepgram (транскрипція аудіо) +## Живий Deepgram (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` @@ -447,9 +450,9 @@ pnpm test:docker:live-codex-harness - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео і `music_generate` + - Перевіряє комплектні шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо не налаштовано `plugins.entries.comfy.config.` - - Корисно після змін у надсиланні comfy workflow, polling, завантаженнях або реєстрації plugin + - Корисно після змін у надсиланні comfy workflow, опитуванні, завантаженнях або реєстрації Plugin ## Жива генерація зображень @@ -457,14 +460,14 @@ pnpm test:docker:live-codex-harness - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований provider plugin генерації зображень - - Завантажує відсутні змінні env провайдерів із вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує ключі live/env API раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Перелічує кожен зареєстрований Plugin провайдера генерації зображень + - Завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує живі/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували справжні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає кожного налаштованого провайдера через спільне середовище виконання генерації зображень: + - Запускає кожного налаштованого провайдера через спільний runtime генерації зображень: - `:generate` - - `:edit`, коли провайдер заявляє підтримку редагування -- Поточні вбудовані провайдери, які охоплено: + - `:edit`, коли провайдер заявляє про підтримку редагування +- Поточні комплектні провайдери, які покриваються: - `fal` - `google` - `minimax` @@ -477,10 +480,10 @@ pnpm test:docker:live-codex-harness - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env -Для shipped шляху CLI додайте smoke для `infer` після того, як живий -тест provider/runtime пройде успішно: +Для shipped-шляху CLI додайте smoke-тест `infer` після того, як живий +тест провайдера/runtime пройде успішно: ```bash OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts @@ -492,9 +495,9 @@ openclaw infer image generate \ --json ``` -Це охоплює розбір аргументів CLI, визначення config/default-agent, активацію вбудованого -plugin, repair залежностей середовища виконання вбудованого runtime на вимогу, спільне -середовище виконання генерації зображень і live-запит до провайдера. +Це покриває розбір аргументів CLI, визначення конфігурації/типового агента, +активацію комплектного Plugin, ремонт залежностей комплектного runtime на вимогу, спільний +runtime генерації зображень і живий запит до провайдера. ## Жива генерація музики @@ -502,23 +505,23 @@ plugin, repair залежностей середовища виконання в - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів генерації музики + - Перевіряє спільний комплектний шлях провайдерів генерації музики - Наразі охоплює Google і MiniMax - - Завантажує змінні env провайдерів із вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує ключі live/env API раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує живі/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували справжні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва заявлені режими runtime, коли вони доступні: - - `generate` з введенням лише prompt + - `generate` з input лише у вигляді prompt - `edit`, коли провайдер заявляє `capabilities.edit.enabled` - - Поточне покриття спільної lane: + - Поточне покриття спільного режиму: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий живий файл Comfy, а не ця спільна перевірка + - `comfy`: окремий живий файл Comfy, а не цей спільний прохід - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env ## Жива генерація відео @@ -526,43 +529,43 @@ plugin, repair залежностей середовища виконання в - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів генерації відео - - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt з лобстером і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) - - За замовчуванням пропускає FAL, оскільки затримка черги на стороні провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує змінні env провайдерів із вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує ключі live/env API раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Перевіряє спільний комплектний шлях провайдерів генерації відео + - За замовчуванням використовує безпечний для релізу шлях smoke-тесту: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster-prompt і обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка в черзі на стороні провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує живі/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували справжні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - За замовчуванням запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати заявлені режими трансформації, коли вони доступні: - - `imageToVideo`, коли провайдер заявляє `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення на основі буфера в межах спільної перевірки - - `videoToVideo`, коли провайдер заявляє `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео на основі буфера в межах спільної перевірки - - Поточні заявлені, але пропущені провайдери `imageToVideo` у спільній перевірці: - - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення - - Покриття Vydra, специфічне для провайдера: + - `imageToVideo`, коли провайдер заявляє `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний input зображення на основі буфера в межах спільного проходу + - `videoToVideo`, коли провайдер заявляє `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний input відео на основі буфера в межах спільного проходу + - Поточні заявлені, але пропущені провайдери `imageToVideo` у спільному проході: + - `vydra`, оскільки комплектний `veo3` підтримує лише текст, а комплектний `kling` вимагає віддалену URL-адресу зображення + - Специфічне покриття Vydra для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, яка за замовчуванням використовує fixture з віддаленим URL зображення + - цей файл запускає `veo3` text-to-video плюс режим `kling`, який за замовчуванням використовує фікстуру віддаленої URL-адреси зображення - Поточне живе покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні заявлені, але пропущені провайдери `videoToVideo` у спільній перевірці: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені URL-посилання `http(s)` / MP4 - - `google`, оскільки поточна спільна lane Gemini/Veo використовує локальне введення на основі буфера, а цей шлях не приймається у спільній перевірці - - `openai`, оскільки поточна спільна lane не гарантує доступ до inpaint/remix відео, специфічний для організації + - Поточні заявлені, але пропущені провайдери `videoToVideo` у спільному проході: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені еталонні URL-адреси `http(s)` / MP4 + - `google`, оскільки поточний спільний режим Gemini/Veo використовує локальний input на основі буфера, а цей шлях не приймається в спільному проході + - `openai`, оскільки поточний спільний режим не гарантує доступу до video inpaint/remix, специфічного для організації - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера під час агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера у типовий прохід, зокрема FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера для агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env ## Harness для живих медіатестів - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні живі набори для зображень, музики та відео через один вбудований у репозиторій entrypoint - - Автоматично завантажує відсутні змінні env провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму залишається узгодженою + - Запускає спільні живі набори тестів для зображень, музики й відео через один вбудований у репозиторій entrypoint + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір тестів до провайдерів, які наразі мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і тихого режиму залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -571,4 +574,4 @@ plugin, repair залежностей середовища виконання в ## Пов’язане -- [Testing](/uk/help/testing) — набори unit, integration, QA і Docker +- [Тестування](/uk/help/testing) — unit, integration, QA і Docker-набори тестів diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index e0f41cab4..f7455c9cd 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделей/провайдерів - - Налагодження поведінки Gateway + агента -summary: 'Набір тестування: набори unit/e2e/live, ранери Docker і що охоплює кожен тест' + - Додавання регресійних тестів для помилок моделей/провайдерів + - Налагодження поведінки Gateway + агентів +summary: 'Набір для тестування: набори unit/e2e/live, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-26T00:18:19Z" + generated_at: "2026-04-26T00:40:10Z" model: gpt-5.4 provider: openai - source_hash: 106fd042e6b065595df0b7c7667cb0e07aceff28d88bb2cd59752c0946ba2edd + source_hash: c235193ed82e20739522cc9571408de804382c38d1b97b22c5aa70153cc23054 source_path: help/testing.md workflow: 15 --- @@ -20,216 +20,214 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Що охоплює кожен набір (і що він навмисно _не_ охоплює). - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. +- Як додавати регресійні тести для реальних проблем моделей/провайдерів. ## Швидкий старт У більшості випадків: -- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Повний набір перевірок (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` -- Прямий таргетинг файлу тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією проблемою спочатку віддавайте перевагу цільовим запускам. -- QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на основі Docker: `pnpm qa:lab:up` +- QA lane на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете більше впевненості: -- Gate покриття: `pnpm test:coverage` +- Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): -- Набір live (моделі + зондування tool/image через Gateway): `pnpm test:live` -- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker sweep live-моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелике зондування у стилі читання файлу. - Моделі, чиї метадані вказують на вхід `image`, також виконують невеликий хід із зображенням. - Вимкніть додаткові зондування через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Набір live (моделі + probes інструментів/зображень Gateway): `pnpm test:live` +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker-прогін live-моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий turn і невеликий probe у стилі читання файлу. + Моделі, чиї метадані оголошують вхід `image`, також виконують невеликий turn із зображенням. + Вимкніть додаткові probes через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні + - Покриття в CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, який включає окремі matrix jobs Docker live-моделей, - розбиті за провайдерами. - - Для точкових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, що включає окремі matrix jobs Docker live-моделей, + розподілені за провайдером. + - Для цільових повторних запусків у CI виконайте dispatch `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + - Додайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - викликів зі schedule/release. -- Native Codex smoke для bound-chat: `pnpm test:docker:live-codex-bind` - - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний - Slack DM через `/codex bind`, виконує `/codex fast` і + scheduled/release викликачів. +- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane проти шляху app-server Codex, прив’язує синтетичне + Slack DM за допомогою `/codex bind`, виконує `/codex fast` і `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення - проходять через native Plugin binding, а не через ACP. -- Smoke команди rescue для Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Необов’язкова додаткова перевірка поверхні команди rescue для message-channel. - Вона виконує `/crestodian status`, ставить у чергу стійку - зміну моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. -- Docker smoke planner для Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` - і перевіряє, що нечіткий fallback planner перетворюється на audited typed - запис у конфігурацію. -- Docker smoke першого запуску для Crestodian: `pnpm test:docker:crestodian-first-run` - - Стартує з порожнього каталогу стану OpenClaw, маршрутизує голий `openclaw` до - Crestodian, застосовує записи setup/model/agent/Discord Plugin + SecretRef, - перевіряє конфігурацію та записи audit. Той самий шлях налаштування Ring 0 - також охоплюється в QA Lab через + проходять через native-прив’язку plugin, а не через ACP. +- Smoke-тест rescue-команди Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Необов’язкова додаткова перевірка поверхні rescue-команди message-channel. + Вона виконує `/crestodian status`, ставить у чергу стійку зміну моделі, + відповідає `/crestodian yes` і перевіряє шлях запису audit/config. +- Docker smoke-тест planner Crestodian: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без config із фальшивим Claude CLI в `PATH` + і перевіряє, що fallback нечіткого planner перетворюється на audited typed + запис config. +- Docker smoke-тест першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` + - Починає з порожнього каталогу стану OpenClaw, маршрутизує голий `openclaw` до + Crestodian, застосовує записи setup/model/agent/Discord plugin + SecretRef, + перевіряє config і перевіряє записи audit. Той самий шлях налаштування Ring 0 + також покривається в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Smoke перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте +- Smoke-тест вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте `openclaw models list --provider moonshot --json`, потім виконайте ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` проти `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6 і що - transcript асистента зберігає нормалізоване `usage.cost`. + транскрипт assistant зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## Спеціальні ранери для QA +## Ранери для QA -Ці команди стоять поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR -і через ручний dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний dispatch із mock parity gate, live Matrix lane і -керованим Convex live Telegram lane як паралельними jobs. `OpenClaw Release Checks` -запускає ті самі lane перед затвердженням релізу. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і +через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний dispatch із mock parity gate, live lane Matrix та +live lane Telegram під керуванням Convex як паралельні jobs. `OpenClaw Release Checks` +запускає ті самі lane перед схваленням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA на базі репозиторію безпосередньо на хості. + - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - worker-и Gateway. Для `qa-channel` типовим є concurrency 4 (обмежується + workers Gateway. `qa-channel` за замовчуванням використовує concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування - кількості worker-ів або `--concurrency 1` для старішого послідовного lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнав невдачі. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і protocol-mock без заміни lane `mock-openai`, - орієнтованого на сценарії. + кількості workers або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, + коли вам потрібні артефакти без аварійного коду завершення. + - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + `aimock` запускає локальний сервер провайдера на основі AIMock для експериментального + покриття fixtures і protocol-mock без заміни сценарно-орієнтованого + lane `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA suite всередині тимчасової Linux VM Multipass. + - Запускає той самий набір QA всередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для guest: - ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, - якщо він наявний. - - Каталоги виводу мають залишатися під коренем репозиторію, щоб guest міг записувати назад через - змонтований робочий простір. - - Записує звичайний звіт і підсумок QA, а також логи Multipass у + - Live-запуски передають підтримувані QA-входи автентифікації, які практично використовувати в гостьовій системі: + ключі провайдерів через env, шлях до config live-провайдера QA і `CODEX_HOME`, якщо присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + змонтований workspace. + - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської роботи в QA. + - Запускає QA-сайт на основі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивний onboarding з ключем OpenAI API, за замовчуванням налаштовує Telegram, - перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, - запускає doctor і один локальний хід агента проти mocked OpenAI endpoint. + Docker, запускає неінтерактивне onboarding з API-ключем OpenAI, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення plugin за потреби встановлює runtime-залежності, + запускає doctor і виконує один локальний turn агента проти замоканого endpoint OpenAI. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane - пакетного встановлення з Discord. + packaged-install з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає детермінований Docker smoke для зібраного застосунку для transcript-ів із - вбудованим runtime context. Перевіряє, що прихований runtime context OpenClaw - зберігається як недоступне для відображення кастомне повідомлення замість витоку у видимий хід користувача, - потім підставляє уражений зламаний JSONL сесії та перевіряє, що - `openclaw doctor --fix` переписує його в активну гілку з резервною копією. + - Запускає детермінований Docker smoke built-app для транскриптів вбудованого runtime context. + Він перевіряє, що прихований runtime context OpenClaw зберігається як + користувацьке повідомлення, що не відображається, замість витоку у видимий turn користувача, + потім засіває пошкоджений JSONL сесії та перевіряє, що + `openclaw doctor --fix` переписує його в active branch із резервною копією. - `pnpm test:docker:npm-telegram-live` - - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding + - Установлює опублікований пакет OpenClaw у Docker, запускає onboarding встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує - QA lane live Telegram із цим встановленим пакетом як SUT Gateway. + live lane Telegram QA з цим установленим пакетом як Gateway SUT. - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й + - Використовує ті самі облікові дані Telegram через env або джерело облікових даних Convex, що й `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`, а також - `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і secret ролі Convex присутні в CI, - обгортка Docker автоматично вибирає Convex. + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс + `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо + `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, + Docker-обгортка автоматично вибирає Convex. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - GitHub Actions надає цей lane як ручний workflow для мейнтейнерів - `NPM Telegram Beta E2E`. Він не запускається при merge. Workflow використовує + `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує середовище `qa-live-shared` і оренду облікових даних Convex CI. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - зі сконфігурованим OpenAI, а потім вмикає bundled channel/plugins через зміни конфігурації. + з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування config. - Перевіряє, що виявлення setup залишає runtime-залежності - не налаштованих Plugin відсутніми, що перший налаштований запуск Gateway або doctor - встановлює runtime-залежності кожного bundled Plugin на вимогу, і що другий restart + не налаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor + за потреби встановлює runtime-залежності кожного bundled plugin, і що другий restart не перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу npm-базову версію, вмикає Telegram перед запуском - `openclaw update --tag `, а потім перевіряє, що - post-update doctor у candidate відновлює runtime-залежності bundled channel без - postinstall-виправлення з боку harness. + - Також установлює відомий старіший npm baseline, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що post-update doctor кандидата + відновлює runtime-залежності bundled channel без відновлення postinstall + на боці harness. - `pnpm test:parallels:npm-update` - - Запускає native smoke оновлення пакетного встановлення в guest-системах Parallels. Для кожної - вибраної платформи спочатку встановлюється потрібний базовий пакет, а потім у тій самій guest-системі - запускається встановлена команда `openclaw update` і перевіряються встановлена версія, - статус оновлення, готовність Gateway і один локальний хід агента. - - Під час ітерацій над однією guest-системою використовуйте `--platform macos`, `--platform windows` або `--platform linux`. - Використовуйте `--json` для шляху до підсумкового артефакту і статусу кожного lane. - - Обгортайте довгі локальні запуски в host timeout, щоб зависання транспорту Parallels - не з’їли решту вікна тестування: + - Запускає native smoke-тест оновлення packaged-install у гостьових системах Parallels. Кожна + вибрана платформа спочатку встановлює запитаний baseline-пакет, потім виконує + встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє + встановлену версію, статус оновлення, готовність gateway і один локальний turn агента. + - Використовуйте `--platform macos`, `--platform windows` або `--platform linux`, коли + ітеруєте лише на одній гостьовій системі. Використовуйте `--json` для шляху до підсумкового артефакту + і статусу кожного lane. + - Обгортайте тривалі локальні запуски в timeout хоста, щоб зависання транспорту Parallels + не забирало решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені логи lane у `/tmp/openclaw-parallels-npm-update.*`. + - Скрипт записує вкладені журнали lane у `/tmp/openclaw-parallels-npm-update.*`. Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, перш ніж припускати, що зовнішня обгортка зависла. - Оновлення Windows може витрачати від 10 до 15 хвилин на post-update doctor/runtime - repair залежностей на холодній guest-системі; це все ще нормальний стан, якщо вкладений + dependency repair у холодній гостьовій системі; це все ще є нормальним, якщо вкладений npm debug log продовжує оновлюватися. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke lane Parallels для - macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час - відновлення snapshot, обслуговування пакетів або стану guest Gateway. - - Post-update proof запускає звичайну поверхню bundled Plugin, оскільки - capability facades, такі як speech, генерація зображень і - розуміння медіа, завантажуються через bundled runtime API, навіть коли сам хід агента - перевіряє лише просту текстову відповідь. + - Не запускайте цю агреговану обгортку паралельно з окремими lane smoke-тестів Parallels + для macOS, Windows або Linux. Вони використовують спільний стан VM і можуть конфліктувати під час + відновлення snapshot, обслуговування пакета або стану gateway гостьової системи. + - Доказ після оновлення запускає звичайну поверхню bundled plugin, оскільки + capability facades, як-от мовлення, генерація зображень і + розуміння медіа, завантажуються через bundled runtime APIs, навіть коли сам + turn агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування + протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA host наразі призначений лише для repo/dev. Пакетні встановлення OpenClaw не постачають - `qa-lab`, тому не відкривають `openclaw qa`. - - Checkout-и репозиторію завантажують bundled runner напряму; окремий крок встановлення Plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Plugin Matrix як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на основі Docker. + - Цей QA-хост наразі призначений лише для repo/dev. Упаковані встановлення OpenClaw не постачають + `qa-lab`, тому не надають `openclaw qa`. + - Checkout репозиторію завантажують bundled runner напряму; окремий крок встановлення plugin не потрібен. + - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним plugin Matrix як транспортом SUT. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює тимчасових користувачів. - - Записує звіт Matrix QA, підсумок, артефакт observed-events і об’єднаний лог виводу stdout/stderr у `.artifacts/qa-e2e/...`. - - За замовчуванням виводить прогрес і примусово застосовує жорсткий timeout виконання через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а у випадку збоїв включається команда відновлення `docker compose ... down --remove-orphans`. + - Записує звіт Matrix QA, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - За замовчуванням виводить прогрес і примусово застосовує жорсткий timeout запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а збої містять команду відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени бота driver і бота SUT із env. - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим chat id Telegram. - - Підтримує `--credential-source convex` для спільних пулованих облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на пуловані lease. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнав невдачі. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати username Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання від driver до спостережуваної відповіді SUT. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулінгові lease. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів у тій самій приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження бот-до-бота увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостереженої відповіді SUT. Live transport lane використовують один стандартний контракт, щоб нові транспорти не розходилися: `qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live transport. -| Lane | Canary | Фільтрація за згадуванням | Блокування allowlist | Відповідь верхнього рівня | Відновлення після restart | Подальша відповідь у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | -| -------- | ------ | ------------------------- | -------------------- | ------------------------- | ------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Контроль згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження реакцій | Команда help | +| -------- | ------ | --------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat -для цього lease, поки lane виконується, і звільняє lease під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивний lease із пулу на основі Convex, надсилає Heartbeat для цього lease, поки lane виконується, і звільняє lease під час завершення. Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env-змінні: +Обов’язкові змінні env: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: @@ -239,7 +237,7 @@ QA lab отримує ексклюзивний lease із пулу на базі - CLI: `--credential-role maintainer|ci` - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) -Необов’язкові env-змінні: +Необов’язкові змінні env: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -247,12 +245,12 @@ QA lab отримує ексклюзивний lease із пулу на базі - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex із `http://` лише для локальної розробки. У звичайному режимі роботи `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди мейнтейнера (додавання/видалення/список пулу) потребують -саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Адміністративні команди мейнтейнера (додавання/видалення/список пулу) потребують саме +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI-хелпери для мейнтейнерів: @@ -263,12 +261,11 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети брокера, +Перед live-запусками використовуйте `doctor`, щоб перевірити URL сайту Convex, секрети broker, префікс endpoint, HTTP timeout і доступність admin/list без виведення -значень секретів. Використовуйте `--json` для машиночитаного виводу в скриптах і CI -утилітах. +значень секретів. Для машиночитаного виводу в скриптах і утилітах CI використовуйте `--json`. -Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Контракт типового endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -299,55 +296,55 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання каналу до QA -Додавання каналу до markdown-системи QA потребує рівно двох речей: +Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Транспортний адаптер для каналу. +1. Transport adapter для каналу. 2. Пакет сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий top-level-командний простір QA, якщо спільний host `qa-lab` -може керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може +керувати цим потоком. -`qa-lab` керує спільною механікою host: +`qa-lab` відповідає за спільну механіку хоста: -- кореневою командою `openclaw qa` -- запуском і завершенням suite -- паралелізмом worker-ів -- записом артефактів -- генерацією звітів -- виконанням сценаріїв +- кореневу команду `openclaw qa` +- запуск і завершення suite +- паралелізм workers +- запис артефактів +- генерацію звітів +- виконання сценаріїв - alias сумісності для старіших сценаріїв `qa-channel` -Runner Plugin володіють транспортним контрактом: +Runner plugins відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway конфігурується для цього транспорту +- як налаштовується gateway для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються transcript-и й нормалізований транспортний стан -- як виконуються дії, прив’язані до транспорту -- як обробляються транспортно-специфічні reset або cleanup +- як надаються транскрипти й нормалізований стан транспорту +- як виконуються дії на основі транспорту +- як обробляється специфічне для транспорту скидання або очищення -Мінімальний поріг прийняття для нового каналу: +Мінімальний поріг впровадження для нового каналу: -1. Залишити `qa-lab` власником спільного кореня `qa`. -2. Реалізувати transport runner на спільному seam host `qa-lab`. -3. Залишити транспортно-специфічну механіку всередині runner Plugin або harness каналу. -4. Монтувати runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner Plugin мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Залишайте `runtime-api.ts` легким; ліниве виконання CLI і runner має бути винесене за окремі entrypoint. -5. Створювати або адаптувати markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Для нових сценаріїв використовувати загальні scenario helper-и. -7. Зберігати працездатність наявних alias сумісності, якщо тільки репозиторій не виконує навмисну міграцію. +1. Залишайте `qa-lab` власником спільного кореня `qa`. +2. Реалізуйте transport runner на спільному хостовому seam `qa-lab`. +3. Тримайте механіку, специфічну для транспорту, всередині runner plugin або channel harness. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. + Runner plugins повинні оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Тримайте `runtime-api.ts` легким; відкладений CLI і виконання runner мають залишатися за окремими entrypoint. +5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовуйте загальні хелпери сценаріїв для нових сценаріїв. +7. Зберігайте наявні alias сумісності працездатними, якщо лише репозиторій не виконує навмисну міграцію. Правило ухвалення рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспортного каналу, залишайте її в runner Plugin або harness цього Plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додавайте загальний helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій транспортно-специфічним і явно фіксуйте це в контракті сценарію. +- Якщо поведінка залежить від одного транспорту каналу, тримайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку можуть використовувати більш ніж один канал, додайте загальний хелпер замість гілки, специфічної для каналу, у `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, зберігайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. -Для нових сценаріїв бажані назви загальних helper-ів: +Бажані назви загальних хелперів для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -370,122 +367,122 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати загальні назви helper-ів. -Alias сумісності існують, щоб уникнути міграції «в один день», а не як модель для +Нова робота над каналами має використовувати загальні назви хелперів. +Alias сумісності існують, щоб уникнути міграції одним днем, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: нетаргетовані запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в конфігурації для окремих проєктів для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, які охоплюються `vitest.unit.config.ts` +- Config: запуски без націлювання використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації по проєктах для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, tooling, парсинг, конфігурація) - - Детерміновані регресії для відомих багів + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, config) + - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - + - - Нетаргетований `pnpm test` запускає дванадцять менших конфігурацій shard (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл watch із кількома shard не є практичним. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lane, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lane, коли diff зачіпає лише routable файли джерел/тестів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lane typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих контрактів core. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни пакета поза полем версії верхнього рівня. - - Unit-тести з легкими імпортами з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` і подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються в наявних lane. - - Вибрані helper-вихідники `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними сусідніми тестами в цих легких lane, тож редагування helper-ів уникають повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` має окремі кошики для top-level helper-ів core, top-level integration-тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на shard agent-runner, dispatch і commands/state-routing, щоб один кошик із важкими імпортами не контролював увесь tail Node. + - Запуски `pnpm test` без націлювання використовують дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, тому що цикл спостереження з багатьма shard непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає сплати повної вартості запуску root-проєкту. + - `pnpm test:changed` розгортає змінені шляхи git у ті самі scoped lanes, коли diff торкається лише маршрутизованих файлів source/test; редагування config/setup все ще повертаються до широкого повторного запуску root-проєкту. + - `pnpm check:changed` — це звичайний розумний локальний набір перевірок для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, metadata релізу та tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих контрактів core. Підвищення версій лише в metadata релізу запускають цільові перевірки version/config/root-dependency замість повного набору, із запобіжником, що відхиляє зміни пакета поза полем версії верхнього рівня. + - Легкі з погляду імпортів unit-тести з agents, commands, plugins, хелперів auto-reply, `plugin-sdk` та подібних чистих утилітних ділянок маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними сусідніми тестами в цих легких lanes, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` має виділені bucket для helper верхнього рівня core, інтеграційних тестів верхнього рівня `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково ділить піддерево reply на shards agent-runner, dispatch і commands/state-routing, щоб один bucket із важкими імпортами не контролював увесь хвіст Node. - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime - context Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані регресії helper-ів для чистих меж маршрутизації та + - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, + зберігайте обидва рівні покриття. + - Додавайте цільові helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте інтеграційні набори embedded runner у здоровому стані: + - Підтримуйте здоровими набори інтеграції embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка compaction все ще проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише helper-ів - не є достатньою заміною для цих інтеграційних шляхів. + - Ці набори перевіряють, що scoped ids і поведінка Compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є + достатньою заміною для цих шляхів інтеграції. - - Базова конфігурація Vitest типово використовує `threads`. - - Спільна конфігурація Vitest фіксує `isolate: false` і використовує + - Базовий config Vitest типово використовує `threads`. + - Спільний config Vitest фіксує `isolate: false` і використовує неізольований runner у root projects, e2e і live config. - - Root lane UI зберігає свій `jsdom` setup і optimizer, але теж запускається на + - Root lane UI зберігає свої `jsdom` setup та optimizer, але також працює на спільному неізольованому runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` - зі спільної конфігурації Vitest. + зі спільного config Vitest. - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні lane зачіпає diff. - - Pre-commit hook виконує лише форматування. Він знову додає відформатовані файли до stage і + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до staging і не запускає lint, typecheck або тести. - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли - вам потрібен розумний локальний gate. Зміни в публічному Plugin SDK і plugin-contract + вам потрібен розумний локальний набір перевірок. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension. - - `pnpm test:changed` маршрутизує через scoped lane, коли змінені шляхи - чітко зіставляються з меншим набором. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи + однозначно зіставляються з меншим набором. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом worker-ів. - - Автомасштабування локальних worker-ів навмисно є консервативним і зменшує навантаження, - коли середнє навантаження хоста вже високе, тож кілька одночасних + лише з вищою межею workers. + - Автомасштабування локальних workers навмисно консервативне й зменшує навантаження, + коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли - змінюється зв’язування тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - мати одну явну локацію кешу для прямого профілювання. + - Базовий config Vitest позначає файли projects/config як + `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, + коли змінюється підключення тестів. + - Config зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс - вивід детального розбору імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання - файлами, зміненими відносно `origin/main`. - - Дані часу shard записуються до `.artifacts/vitest-shard-timings.json`. - Запуски всієї конфігурації використовують шлях конфігурації як ключ; shard-и CI з include-pattern - додають назву shard, щоб відфільтровані shard можна було відстежувати - окремо. + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту та + вивід import-breakdown. + - `pnpm test:perf:imports:changed` звужує той самий профілювальний перегляд до + файлів, змінених відносно `origin/main`. + - Дані часу shard записуються в `.artifacts/vitest-shard-timings.json`. + Запуски цілого config використовують шлях config як ключ; shards CI з include-pattern + додають назву shard, щоб відфільтровані shards можна було + відстежувати окремо. - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - напряму mock-айте цей seam замість глибокого імпорту helper-ів runtime - лише для того, щоб передати їх у `vi.mock(...)`. + мокайте цей seam безпосередньо замість глибокого імпорту runtime-хелперів + лише для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з native шляхом root-project для цього зафіксованого + `test:changed` із native root-project шляхом для цього закоміченого diff і виводить wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, - маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для - накладних витрат старту та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для - unit-набору з вимкненим паралелізмом файлів. + - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного + брудного дерева, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і root config Vitest. + - `pnpm test:perf:profile:main` записує CPU profile головного потоку для + старту Vitest/Vite і накладних витрат transform. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для + набору unit із вимкненим файловим паралелізмом. @@ -493,247 +490,248 @@ Alias сумісності існують, щоб уникнути міграц ### Стабільність (Gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один worker +- Config: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з діагностикою, увімкненою за замовчуванням - - Проганяє синтетичне навантаження повідомленнями gateway, пам’яттю та великими payload через шлях діагностичних подій + - Запускає реальний loopback Gateway із діагностикою, увімкненою за замовчуванням + - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - Виконує запит до `diagnostics.stability` через WS RPC Gateway - - Охоплює helper-и збереження пакета діагностичної стабільності - - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються в межах бюджету тиску, а глибини черг на сесію знову зменшуються до нуля + - Покриває helper-функції збереження diagnostic stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються нижче бюджету тиску, а глибини черг на рівні сесій повертаються до нуля - Очікування: - - Безпечно для CI і не потребує ключів - - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Безпечно для CI і без ключів + - Вузький lane для подальшої роботи зі стабільнісними регресіями, а не заміна повного набору Gateway -### E2E (smoke для gateway) +### E2E (smoke Gateway) - Команда: `pnpm test:e2e` -- Конфігурація: `vitest.e2e.config.ts` +- Config: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` -- Типові параметри runtime: - - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість worker-ів (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на вивід у консоль. +- Типові значення runtime: + - Використовує `threads` Vitest з `isolate: false`, узгоджено з рештою репозиторію. + - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість worker-ів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути детальний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. - Обсяг: - - Наскрізна поведінка gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, спарювання Node і важчий мережевий стек + - End-to-end поведінка Gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, спарювання Node і важче мережеве навантаження - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: smoke для backend OpenShell +### E2E: smoke-тест backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge + - Перевіряє backend OpenShell OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Перевіряє remote-canonical поведінку файлової системи через fs bridge sandbox - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локальний CLI `openshell` і робочий Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox + - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` + - Потребує локальний CLI `openshell` і справний Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфігурація: `vitest.live.config.ts` +- Config: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявляє зміни формату провайдера, особливості виклику tool, проблеми автентифікації та поведінку rate limit + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (специфічна для провайдера): встановлюйте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для окремого live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Live-запуски підтягують `~/.profile`, щоб отримати відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає журнали bootstrap Gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. +- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення на рівні live через `OPENCLAW_LIVE_*_KEY`; тести виконують повторну спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера видно як активні навіть тоді, коли захоплення консолі Vitest є тихим. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway негайно транслювалися під час live-запусків. + - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно активність довгих викликів провайдерів навіть тоді, коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/Gateway транслюються негайно під час live-запусків. - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Користуйтеся цією таблицею рішень: +Використовуйте цю таблицю рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Зачіпаєте мережеву взаємодію Gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні збої провайдера / виклик tool: запускайте звужений `pnpm test:live` +- Торкаєтеся мережевої взаємодії Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Live-тести (із доступом до мережі) +## Live-тести (які торкаються мережі) -Для live-матриці моделей, smoke backend CLI, smoke ACP, harness +Для live-матриці моделей, smoke-тестів backend CLI, smoke-тестів ACP, harness app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також для обробки облікових даних для live-запусків — див. +music, video, media harness) — а також обробки облікових даних для live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). ## Ранери Docker (необов’язкові перевірки «працює в Linux») Ці ранери Docker поділяються на дві групи: -- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із profile-key всередині образу Docker репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочий простір (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runner-и типово мають менший smoke-ліміт, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і підтягують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менше обмеження smoke, щоб повний Docker-прогін залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібне більше, вичерпне сканування. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для live Docker lane. Також він збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E smoke-ранерів у контейнерах, які перевіряють зібраний застосунок. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як обмеження ресурсів не дають одночасно стартувати всім важким live-, npm-install- і multi-service lane. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker host має більший запас ресурсів. Runner типово виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, виводить статус кожні 30 секунд, зберігає таймінги успішних lane у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спочатку стартували довші lane. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збирання або запуску Docker. -- Smoke-ранери контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні env, коли + вам явно потрібне більше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для Docker live lane. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для контейнерних smoke-ранерів E2E, які перевіряють built app. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають одночасно запускатися всім важким live-, npm-install- і multi-service lane. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу ресурсів. За замовчуванням раннер виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, виводить статус кожні 30 секунд, зберігає таймінги успішних lane у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спочатку стартували довші lane. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збирання або запуску Docker. +- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker runner-и live-моделей також bind-mount-ять лише потрібні home-каталоги CLI auth (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home каталогу контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у host auth store: +Docker-ранери live-моделей також bind-монтують лише потрібні каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище автентифікації хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke bind для ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово охоплює Claude, Codex і Gemini, із суворим покриттям OpenCode через `pnpm test:docker:live-acp-bind:opencode`) -- Smoke для backend CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; за замовчуванням покриває Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke-тест harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює упакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref плюс типово Telegram, перевіряє, що doctor відновлює runtime deps активованого Plugin, і виконує один агентський хід проти mocked OpenAI. Використовуйте вже зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження transcript прихованого runtime context плюс виправлення doctor для уражених дубльованих гілок prompt-rewrite. -- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Використовуйте вже зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` використовує один npm cache для своїх контейнерів root, update і direct-npm. Smoke оновлення типово бере npm `latest` як стабільну базову версію перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи кешу з правами root не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними перезапусками. -- Install Smoke CI пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; локально запускайте скрипт без цього env, коли потрібне покриття прямого `npm install -g`. -- Smoke CLI для видалення спільного робочого простору agents: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає image з root Dockerfile, ініціалізує двох агентів з одним робочим простором в ізольованому home контейнера, виконує `agents delete --json` і перевіряє коректний JSON плюс поведінку зі збереженням робочого простору. Повторно використовуйте image install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Регресія мінімального reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mocked сервер OpenAI через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` із `minimal` до `low`, потім примушує схему провайдера відхилити запит і перевіряє, що сирі деталі з’являються в логах Gateway. -- Міст каналу MCP (seeded Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP у Pi bundle (реальний stdio MCP server + smoke allow/deny для вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Smoke-тест live Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke-тест onboarding/channel/agent з npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref плюс Telegram за замовчуванням, перевіряє, що doctor відновлює runtime-залежності активованих plugin, і виконує один замоканий turn агента OpenAI. Щоб повторно використати попередньо зібраний tarball, установіть `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, щоб пропустити host rebuild — `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, або щоб змінити канал — `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-тест runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження транскрипту прихованого runtime context плюс відновлення doctor для уражених дубльованих branch переписування prompt. +- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Щоб повторно використати попередньо зібраний tarball, установіть `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, щоб пропустити host build — `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, або щоб скопіювати `dist/` зі зібраного Docker-образу — `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує один спільний npm cache для своїх root-, update- і direct-npm-контейнерів. Smoke-тест оновлення за замовчуванням бере npm `latest` як стабільний baseline перед оновленням до tarball кандидата. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи кешу, створені root, не маскували поведінку користувацького локального встановлення. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm у локальних перезапусках. +- Install Smoke CI пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; локально запускайте скрипт без цієї змінної env, коли потрібне покриття прямого `npm install -g`. +- CLI smoke видалення спільного workspace агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає root Dockerfile-образ, створює два агенти з одним workspace в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON плюс поведінку збереженого workspace. Повторно використовуйте install-smoke-образ через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Мінімальна reasoning-регресія `web_search` для OpenAI Responses: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає замоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення schema провайдера і перевіряє, що необроблена деталь з’являється в журналах Gateway. +- Міст каналу MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP пакета Pi (реальний stdio MCP-сервер + smoke allow/deny для вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) - Очищення MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення + alias `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke оновлення Plugin без змін: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps bundled Plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker runner image, один раз збирає та пакує OpenClaw на host, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker aggregate один раз попередньо пакує цей tarball, а потім розбиває перевірки bundled channel на незалежні lane, зокрема окремі lane оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити channel matrix під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. -- Під час ітерацій звужуйте runtime deps bundled Plugin, вимикаючи не пов’язані сценарії, наприклад: +- Plugins (smoke встановлення + alias `/plugin` + семантика restart для пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke-тест незмінності оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke-тест metadata перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker-ранера, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте host rebuild після свіжого локального збирання через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегат один раз попередньо пакує цей tarball, а потім розбиває перевірки bundled channel на незалежні lane, включно з окремими lane оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення runtime-залежностей через doctor. +- Звужуйте runtime-залежності bundled plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати і повторно використовувати спільний image built-app: +Щоб вручну попередньо зібрати й повторно використати спільний built-app image: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакування/встановлення, а не спільний runtime зібраного застосунку. +Перевизначення образів на рівні набору, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Тести Docker для QR та installer зберігають власні Dockerfile, оскільки перевіряють поведінку package/install, а не runtime спільного built app. -Docker runner-и live-моделей також bind-mount-ять поточний checkout у режимі лише для читання і -розміщують його в тимчасовому workdir усередині контейнера. Це дозволяє зберегти runtime -image компактним, водночас запускаючи Vitest точно проти вашого локального source/config. -Крок staging пропускає великі локальні кеші та вихідні дані збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -вихідні каталоги Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. +Docker-ранери live-моделей також bind-монтують поточний checkout у режимі лише читання й +розміщують його в тимчасовому workdir усередині контейнера. Це дозволяє зберегти runtime-образ +компактним і водночас запускати Vitest точно на вашому локальному source/config. +Крок підготовки пропускає великі локальні кеші й результати збирання застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги +`.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали -реальні worker-и каналів Telegram/Discord тощо всередині контейнера. +реальні workers каналів Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити live-покриття Gateway з цього Docker lane. -`test:docker:openwebui` — це smoke перевірка сумісності вищого рівня: вона запускає -контейнер Gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, -запускає зафіксований контейнер Open WebUI проти цього Gateway, входить через +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити live-покриття Gateway +з цього Docker lane. +`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -image Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. +реальний запит чату через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження +образу Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded контейнер -Gateway, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутованих розмов, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію outbound send, а також сповіщення у стилі Claude про канал + +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає заповнений Gateway +у контейнері, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, metadata вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення в стилі Claude про канали + дозволи через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frame, тож smoke перевіряє те, що міст -справді виводить, а не лише те, що випадково показує конкретний клієнтський SDK. +безпосередньо аналізує сирі stdio MCP frames, тож smoke-тест перевіряє те, що міст +справді виводить, а не лише те, що випадково показує конкретний client SDK. `test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує -ключа live-моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей сервер через embedded Pi bundle -MCP runtime, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний probe-сервер stdio MCP +усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP пакета Pi, +виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. `test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. -Він запускає seeded Gateway з реальним stdio MCP probe server, виконує ізольований -хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +Він запускає заповнений Gateway із реальним probe-сервером stdio MCP, виконує +ізольований turn Cron і одноразовий дочірній turn `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke для ACP plain-language thread (не CI): +Ручний smoke-тест ACP plain-language thread (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для валідації маршрутизації ACP thread, тому не видаляйте його. -Корисні env-змінні: +Корисні змінні env: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і source-иться перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, source-нуті з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішнього CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker -- Зовнішні каталоги/файли CLI auth під `$HOME` монтуються в режимі лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підтягується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` для перевірки лише змінних env, підтягуваних із `OPENCLAW_PROFILE_FILE`, з використанням тимчасових каталогів config/workspace і без зовнішніх монтувань CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI всередині Docker +- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний image `openclaw:local-live` для перезапусків, яким не потрібна нова збірка -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища профілю (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt для перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег image Open WebUI +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1` для повторного використання наявного образу `openclaw:local-live` у перезапусках, яким не потрібне повторне збирання +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб переконатися, що облікові дані надходять зі сховища profile (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...` для вибору моделі, яку gateway показує для smoke-тесту Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` для перевизначення prompt перевірки nonce, який використовує smoke-тест Open WebUI +- `OPENWEBUI_IMAGE=...` для перевизначення закріпленого тега образу Open WebUI ## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну валідацію anchor Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Offline-регресія (безпечна для CI) +## Офлайн-регресія (безпечно для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик tool через Gateway (mock OpenAI, реальний Gateway + цикл агента): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Wizard Gateway (WS `wizard.start`/`wizard.next`, записує config + auth enforced): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (замоканий OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + примусово застосовану auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агентів (Skills) +## Оцінки надійності агентів (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінки надійності агентів»: -- Mock tool-calling через реальний Gateway + цикл агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки wizard, які перевіряють прив’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Замоканий виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end потоки wizard, які перевіряють прив’язку сесій і ефекти config (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Ухвалення рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval мають спочатку залишатися детермінованими: +Майбутні evals мають спочатку залишатися детермінованими: -- Runner сценаріїв із mock-провайдерами для перевірки викликів tool + порядку, читання файлів skill і прив’язки сесії. -- Невеликий набір сценаріїв, зосереджених на skill (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-eval (opt-in, керовані env) лише після того, як безпечний для CI набір уже буде на місці. +- Runner сценаріїв із mock-провайдерами для перевірки викликів інструментів + їх порядку, читання skill-файлів і прив’язки сесії. +- Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-eval (увімкнення за запитом, керовані env) — лише після того, як буде готовий безпечний для CI набір. -## Contract-тести (форма Plugin і каналу) +## Контрактні тести (форма Plugin і каналу) -Contract-тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму -контракту інтерфейсу. Вони ітеруються по всіх виявлених Plugin і запускають набір +Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму +контракту інтерфейсу. Вони проходять по всіх виявлених plugins і запускають набір перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці файли спільних seam і smoke; запускайте contract-команди явно, -коли зачіпаєте спільні поверхні каналу або провайдера. +пропускає ці спільні seam- і smoke-файли; запускайте команди контрактів явно, +коли змінюєте спільні поверхні каналу або провайдера. ### Команди @@ -745,56 +743,56 @@ Contract-тести перевіряють, що кожен зареєстров Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) -- **setup** - Контракт setup wizard +- **plugin** - Базова форма plugin (id, name, capabilities) +- **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій каналу -- **threading** - Обробка ID тредів -- **directory** - API каталогу/складу -- **group-policy** - Застосування групової політики +- **threading** - Обробка thread ID +- **directory** - API каталогу/списку учасників +- **group-policy** - Застосування політики групи ### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Зондування статусу каналу -- **registry** - Форма реєстру Plugin +- **status** - Probes статусу каналу +- **registry** - Форма registry Plugin ### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/selection автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/добір auth - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin - **runtime** - Runtime провайдера - **shape** - Форма/інтерфейс Plugin -- **wizard** - Setup wizard +- **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export-ів або subpath у plugin-sdk -- Після додавання або зміни каналу чи Plugin провайдера -- Після рефакторингу реєстрації або виявлення Plugin +- Після змін у `plugin-sdk` exports або subpaths +- Після додавання або зміни plugin каналу чи провайдера +- Після рефакторингу реєстрації або виявлення plugin -Contract-тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресійних тестів (настанови) +## Додавання регресій (настанови) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні -- Віддавайте перевагу найменшому рівню, який виявляє баг: - - баг перетворення/відтворення запиту провайдера → direct models test - - баг pipeline сесії/історії/tool у gateway → live smoke Gateway або безпечний для CI mock-тест Gateway -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нову цільову сім’ю SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не могли бути тихо пропущені. +- Додайте безпечну для CI регресію, якщо це можливо (замоканий/підмінений провайдер або захоплення точної трансформації форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limit, політики auth), залишайте live-тест вузьким і таким, що вмикається через змінні env +- Намагайтеся націлюватися на найменший шар, який виявляє помилку: + - помилка конвертації/повторення запиту провайдера → direct models test + - помилка pipeline сесії/історії/інструментів gateway → live smoke Gateway або безпечний для CI mock-тест Gateway +- Захисний механізм обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується з помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити. ## Пов’язане diff --git a/docs/uk/install/fly.md b/docs/uk/install/fly.md index 261e94052..5c0e3eccc 100644 --- a/docs/uk/install/fly.md +++ b/docs/uk/install/fly.md @@ -1,34 +1,34 @@ --- read_when: - Розгортання OpenClaw на Fly.io - - Налаштування томів Fly, секретів і початкової конфігурації -summary: Покрокове розгортання OpenClaw на Fly.io зі стійким сховищем і HTTPS + - Налаштування томів Fly, секретів і конфігурації першого запуску +summary: Покрокове розгортання OpenClaw на Fly.io зі сталим сховищем і HTTPS title: Fly.io x-i18n: - generated_at: "2026-04-24T03:18:38Z" + generated_at: "2026-04-26T00:40:11Z" model: gpt-5.4 provider: openai - source_hash: 8913b6917c23de69865c57ec6a455f3e615bc65b09334edec0a3fe8ff69cf503 + source_hash: 1fe13cb60aff6ee2159e1008d2af660b689d819d38893e9758c23e1edaf32e22 source_path: install/fly.md workflow: 15 --- # Розгортання на Fly.io -**Мета:** Gateway OpenClaw, що працює на машині [Fly.io](https://fly.io) зі стійким сховищем, автоматичним HTTPS і доступом до Discord/каналів. +**Мета:** Gateway OpenClaw, запущений на машині [Fly.io](https://fly.io) зі сталим сховищем, автоматичним HTTPS і доступом до Discord/каналів. -## Що вам потрібно +## Що вам знадобиться -- Встановлений [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/) -- Обліковий запис Fly.io (працює безкоштовний тариф) -- Автентифікація моделі: API-ключ для вибраного провайдера моделі -- Облікові дані каналів: токен бота Discord, токен Telegram тощо +- встановлений [CLI `flyctl`](https://fly.io/docs/hands-on/install-flyctl/) +- обліковий запис Fly.io (безкоштовний тариф підходить) +- автентифікація моделі: API-ключ для обраного вами провайдера моделі +- облікові дані каналу: токен бота Discord, токен Telegram тощо ## Швидкий шлях для початківців 1. Клонуйте репозиторій → налаштуйте `fly.toml` -2. Створіть застосунок + том → задайте секрети -3. Розгорніть через `fly deploy` +2. Створіть застосунок і том → задайте секрети +3. Розгорніть за допомогою `fly deploy` 4. Підключіться через SSH, щоб створити конфігурацію, або використайте Control UI @@ -45,14 +45,14 @@ x-i18n: fly volumes create openclaw_data --size 1 --region iad ``` - **Порада:** Виберіть регіон ближче до себе. Поширені варіанти: `lhr` (Лондон), `iad` (Вірджинія), `sjc` (Сан-Хосе). + **Порада:** Оберіть регіон, близький до вас. Поширені варіанти: `lhr` (Лондон), `iad` (Вірджинія), `sjc` (Сан-Хосе). - Відредагуйте `fly.toml` відповідно до назви вашого застосунку та вимог. + Відредагуйте `fly.toml`, щоб він відповідав назві вашого застосунку та вашим вимогам. - **Примітка щодо безпеки:** Типова конфігурація відкриває публічний URL. Для посиленого розгортання без публічної IP-адреси див. [Приватне розгортання](#private-deployment-hardened) або використайте `fly.private.toml`. + **Примітка щодо безпеки:** Конфігурація за замовчуванням відкриває публічну URL-адресу. Для посиленого розгортання без публічної IP-адреси див. [Приватне розгортання](#private-deployment-hardened) або використайте `fly.private.toml`. ```toml app = "my-openclaw" # Your app name @@ -89,13 +89,13 @@ x-i18n: **Ключові параметри:** - | Параметр | Навіщо | - | ------------------------------ | ----------------------------------------------------------------------------- | - | `--bind lan` | Прив’язує до `0.0.0.0`, щоб проксі Fly міг дістатися до gateway | - | `--allow-unconfigured` | Запускає без файла конфігурації (ви створите його пізніше) | - | `internal_port = 3000` | Має збігатися з `--port 3000` (або `OPENCLAW_GATEWAY_PORT`) для health checks Fly | - | `memory = "2048mb"` | 512MB замало; рекомендовано 2GB | - | `OPENCLAW_STATE_DIR = "/data"` | Зберігає стан на томі | + | Параметр | Чому | + | ----------------------------- | ---------------------------------------------------------------------------- | + | `--bind lan` | Прив’язує до `0.0.0.0`, щоб проксі Fly міг дістатися до gateway | + | `--allow-unconfigured` | Запускає без конфігураційного файлу (ви створите його пізніше) | + | `internal_port = 3000` | Має збігатися з `--port 3000` (або `OPENCLAW_GATEWAY_PORT`) для health checks Fly | + | `memory = "2048mb"` | 512 МБ замало; рекомендовано 2 ГБ | + | `OPENCLAW_STATE_DIR = "/data"`| Зберігає стан на томі | @@ -117,9 +117,9 @@ x-i18n: **Примітки:** - - Прив’язки не до loopback (`--bind lan`) вимагають коректного шляху автентифікації gateway. У цьому прикладі Fly.io використовується `OPENCLAW_GATEWAY_TOKEN`, але `gateway.auth.password` або правильно налаштоване розгортання `trusted-proxy` не до loopback також задовольняють цю вимогу. + - Прив’язки не до local loopback (`--bind lan`) вимагають коректного шляху автентифікації gateway. У цьому прикладі Fly.io використовується `OPENCLAW_GATEWAY_TOKEN`, але `gateway.auth.password` або правильно налаштоване розгортання `trusted-proxy` не на local loopback також задовольняють цю вимогу. - Ставтеся до цих токенів як до паролів. - - **Надавайте перевагу env vars замість файла конфігурації** для всіх API-ключів і токенів. Так секрети не потраплять до `openclaw.json`, де вони можуть бути випадково розкриті або залоговані. + - **Надавайте перевагу змінним середовища замість конфігураційного файлу** для всіх API-ключів і токенів. Це не дає секретам потрапити в `openclaw.json`, де вони можуть бути випадково розкриті або залоговані. @@ -128,7 +128,7 @@ x-i18n: fly deploy ``` - Перше розгортання збирає Docker-образ (~2–3 хвилини). Наступні розгортання відбуваються швидше. + Під час першого розгортання збирається Docker-образ (~2–3 хвилини). Наступні розгортання швидші. Після розгортання перевірте: @@ -146,14 +146,14 @@ x-i18n: - - Підключіться до машини через SSH, щоб створити належну конфігурацію: + + Підключіться через SSH до машини, щоб створити належну конфігурацію: ```bash fly ssh console ``` - Створіть каталог конфігурації та файл: + Створіть каталог і файл конфігурації: ```bash mkdir -p /data @@ -200,23 +200,34 @@ x-i18n: }, "gateway": { "mode": "local", - "bind": "auto" + "bind": "auto", + "controlUi": { + "allowedOrigins": [ + "https://my-openclaw.fly.dev", + "http://localhost:3000", + "http://127.0.0.1:3000" + ] + } }, "meta": {} } EOF ``` - **Примітка:** Із `OPENCLAW_STATE_DIR=/data` шлях до конфігурації — `/data/openclaw.json`. + **Примітка:** Якщо задано `OPENCLAW_STATE_DIR=/data`, шлях до конфігурації — `/data/openclaw.json`. - **Примітка:** Токен Discord може надходити з одного з джерел: + **Примітка:** Замініть `https://my-openclaw.fly.dev` на справжнє + джерело походження вашого застосунку Fly. Під час запуску gateway локальні джерела походження для Control UI ініціалізуються на основі значень `--bind` і `--port` у середовищі виконання, тож перший запуск може відбутися ще до появи конфігурації, але для доступу через браузер у Fly все одно потрібно точно вказати HTTPS-джерело походження в + `gateway.controlUi.allowedOrigins`. - - змінна середовища: `DISCORD_BOT_TOKEN` (рекомендовано для секретів) - - файл конфігурації: `channels.discord.token` + **Примітка:** Токен Discord може надходити з: - Якщо використовується env var, додавати токен у конфігурацію не потрібно. Gateway автоматично читає `DISCORD_BOT_TOKEN`. + - Змінної середовища: `DISCORD_BOT_TOKEN` (рекомендовано для секретів) + - Конфігураційного файлу: `channels.discord.token` - Перезапустіть для застосування змін: + Якщо ви використовуєте змінну середовища, додавати токен до конфігурації не потрібно. Gateway автоматично читає `DISCORD_BOT_TOKEN`. + + Перезапустіть, щоб застосувати зміни: ```bash exit @@ -236,9 +247,9 @@ x-i18n: Або перейдіть за адресою `https://my-openclaw.fly.dev/` - Автентифікуйтеся за допомогою налаштованого спільного секрету. У цьому посібнику використовується токен gateway з `OPENCLAW_GATEWAY_TOKEN`; якщо ви перейшли на автентифікацію паролем, використайте натомість цей пароль. + Автентифікуйтеся за допомогою налаштованого спільного секрету. У цьому посібнику використовується токен gateway з `OPENCLAW_GATEWAY_TOKEN`; якщо ви перейшли на автентифікацію паролем, використайте замість нього цей пароль. - ### Журнали + ### Логи ```bash fly logs # Live logs @@ -256,15 +267,15 @@ x-i18n: ## Усунення несправностей -### "App is not listening on expected address" +### «App is not listening on expected address» -Gateway прив’язується до `127.0.0.1`, а не до `0.0.0.0`. +Gateway прив’язується до `127.0.0.1` замість `0.0.0.0`. **Виправлення:** Додайте `--bind lan` до команди процесу у `fly.toml`. -### Health checks failing / connection refused +### Збої health checks / connection refused -Fly не може дістатися до gateway на налаштованому порті. +Fly не може дістатися до gateway на вказаному порту. **Виправлення:** Переконайтеся, що `internal_port` збігається з портом gateway (задайте `--port 3000` або `OPENCLAW_GATEWAY_PORT=3000`). @@ -285,13 +296,13 @@ Fly не може дістатися до gateway на налаштованом fly machine update --vm-memory 2048 -y ``` -**Примітка:** 512MB замало. 1GB може працювати, але здатен призводити до OOM під навантаженням або з докладним логуванням. **Рекомендовано 2GB.** +**Примітка:** 512 МБ замало. 1 ГБ може працювати, але під навантаженням або з детальним логуванням можливі OOM. **Рекомендовано 2 ГБ.** ### Проблеми з блокуванням Gateway -Gateway відмовляється запускатися з помилками на кшталт "already running". +Gateway відмовляється запускатися з помилками на кшталт «already running». -Таке трапляється, коли контейнер перезапускається, але файл PID-блокування залишається на томі. +Це трапляється, коли контейнер перезапускається, але файл блокування PID залишається на томі. **Виправлення:** Видаліть файл блокування: @@ -300,11 +311,11 @@ fly ssh console --command "rm -f /data/gateway.*.lock" fly machine restart ``` -Файл блокування розташований у `/data/gateway.*.lock` (не в підкаталозі). +Файл блокування знаходиться в `/data/gateway.*.lock` (не в підкаталозі). -### Конфігурація не читається +### Конфігурація не зчитується -`--allow-unconfigured` лише обходить перевірку під час запуску. Цей параметр не створює й не виправляє `/data/openclaw.json`, тож переконайтеся, що ваш реальний файл конфігурації існує й містить `gateway.mode="local"`, якщо вам потрібен звичайний локальний запуск gateway. +`--allow-unconfigured` лише обходить перевірку під час запуску. Він не створює і не відновлює `/data/openclaw.json`, тому переконайтеся, що реальна конфігурація існує та містить `gateway.mode="local"`, якщо вам потрібен звичайний локальний запуск gateway. Перевірте, що конфігурація існує: @@ -314,7 +325,7 @@ fly ssh console --command "cat /data/openclaw.json" ### Запис конфігурації через SSH -Команда `fly ssh console -C` не підтримує перенаправлення shell. Щоб записати файл конфігурації: +Команда `fly ssh console -C` не підтримує перенаправлення оболонки. Щоб записати конфігураційний файл: ```bash # Use echo + tee (pipe from local to remote) @@ -333,10 +344,10 @@ fly ssh console --command "rm /data/openclaw.json" ### Стан не зберігається -Якщо після перезапуску ви втрачаєте auth profiles, стан каналу/провайдера або сесії, -це означає, що каталог стану записується у файлову систему контейнера. +Якщо після перезапуску ви втрачаєте профілі автентифікації, стан каналу/провайдера або сесії, +каталог стану записується у файлову систему контейнера. -**Виправлення:** Переконайтеся, що в `fly.toml` задано `OPENCLAW_STATE_DIR=/data`, і розгорніть знову. +**Виправлення:** Переконайтеся, що в `fly.toml` задано `OPENCLAW_STATE_DIR=/data`, і виконайте повторне розгортання. ## Оновлення @@ -367,19 +378,19 @@ fly machine update --command "node dist/index.js gateway --port 300 fly machine update --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y ``` -**Примітка:** Після `fly deploy` команда машини може бути скинута до значення з `fly.toml`. Якщо ви робили ручні зміни, застосуйте їх повторно після розгортання. +**Примітка:** Після `fly deploy` команда машини може бути скинута до значення з `fly.toml`. Якщо ви вносили зміни вручну, застосуйте їх повторно після розгортання. ## Приватне розгортання (посилене) -Типово Fly виділяє публічні IP-адреси, через що ваш gateway стає доступним за адресою `https://your-app.fly.dev`. Це зручно, але означає, що ваше розгортання може бути виявлене інтернет-сканерами (Shodan, Censys тощо). +За замовчуванням Fly виділяє публічні IP-адреси, через що ваш gateway стає доступним за адресою `https://your-app.fly.dev`. Це зручно, але означає, що ваше розгортання можна виявити інтернет-сканерами (Shodan, Censys тощо). -Для посиленого розгортання **без публічної доступності** використовуйте приватний шаблон. +Для посиленого розгортання **без публічного доступу** використовуйте приватний шаблон. -### Коли використовувати приватне розгортання +### Коли варто використовувати приватне розгортання -- Ви виконуєте лише **вихідні** виклики/надсилання повідомлень (без вхідних Webhook) +- Ви робите лише **вихідні** виклики/надсилання повідомлень (без вхідних Webhook) - Ви використовуєте тунелі **ngrok або Tailscale** для будь-яких callback Webhook -- Ви отримуєте доступ до gateway через **SSH, proxy або WireGuard**, а не через браузер +- Ви отримуєте доступ до gateway через **SSH, проксі або WireGuard**, а не через браузер - Ви хочете, щоб розгортання було **приховане від інтернет-сканерів** ### Налаштування @@ -418,9 +429,9 @@ v6 fdaa:x:x:x:x::x private global ### Доступ до приватного розгортання -Оскільки публічного URL немає, використовуйте один із цих способів: +Оскільки публічної URL-адреси немає, скористайтеся одним із цих способів: -**Варіант 1: локальний proxy (найпростіший)** +**Варіант 1: Локальний проксі (найпростіше)** ```bash # Forward local port 3000 to the app @@ -439,7 +450,7 @@ fly wireguard create # Example: http://[fdaa:x:x:x:x::x]:3000 ``` -**Варіант 3: лише SSH** +**Варіант 3: Лише SSH** ```bash fly ssh console -a my-openclaw @@ -447,11 +458,11 @@ fly ssh console -a my-openclaw ### Webhook у приватному розгортанні -Якщо вам потрібні callback Webhook (Twilio, Telnyx тощо) без публічної доступності: +Якщо вам потрібні callback Webhook (Twilio, Telnyx тощо) без публічного доступу: 1. **Тунель ngrok** — запустіть ngrok усередині контейнера або як sidecar -2. **Tailscale Funnel** — відкрийте конкретні шляхи через Tailscale -3. **Лише вихідний режим** — деякі провайдери (Twilio) нормально працюють для вихідних викликів без Webhook +2. **Tailscale Funnel** — відкрийте певні шляхи через Tailscale +3. **Лише вихідний трафік** — деякі провайдери (Twilio) добре працюють для вихідних викликів і без Webhook Приклад конфігурації голосових викликів з ngrok: @@ -474,30 +485,30 @@ fly ssh console -a my-openclaw } ``` -Тунель ngrok працює всередині контейнера й надає публічний URL Webhook без відкриття самого застосунку Fly. Установіть `webhookSecurity.allowedHosts` на публічне ім’я хоста тунелю, щоб переслані заголовки host приймалися. +Тунель ngrok працює всередині контейнера і надає публічну URL-адресу Webhook, не відкриваючи сам застосунок Fly. Задайте `webhookSecurity.allowedHosts` як ім’я хоста публічного тунелю, щоб заголовки хоста, переслані далі, приймалися. -### Переваги безпеки +### Переваги для безпеки -| Аспект | Публічне | Приватне | -| ----------------- | ------------- | ----------- | -| Інтернет-сканери | Виявляється | Приховано | +| Аспект | Публічне | Приватне | +| ----------------- | ------------- | ---------- | +| Інтернет-сканери | Виявляється | Приховане | | Прямі атаки | Можливі | Заблоковані | -| Доступ до Control UI | Браузер | Proxy/VPN | +| Доступ до Control UI | Браузер | Проксі/VPN | | Доставка Webhook | Напряму | Через тунель | ## Примітки - Fly.io використовує **архітектуру x86** (не ARM) - Dockerfile сумісний з обома архітектурами -- Для початкового налаштування WhatsApp/Telegram використовуйте `fly ssh console` -- Стійкі дані зберігаються на томі в `/data` -- Для Signal потрібні Java + signal-cli; використовуйте власний образ і тримайте пам’ять на рівні 2GB+. +- Для онбордингу WhatsApp/Telegram використовуйте `fly ssh console` +- Сталі дані зберігаються на томі в `/data` +- Для Signal потрібні Java + `signal-cli`; використовуйте власний образ і тримайте пам’ять на рівні 2 ГБ+. ## Вартість -Із рекомендованою конфігурацією (`shared-cpu-2x`, 2GB RAM): +З рекомендованою конфігурацією (`shared-cpu-2x`, 2 ГБ RAM): -- приблизно ~$10-15/місяць залежно від використання +- приблизно ~$10–15/місяць залежно від використання - безкоштовний тариф включає певний ліміт Докладніше див. у [тарифах Fly.io](https://fly.io/docs/about/pricing/). @@ -508,9 +519,9 @@ fly ssh console -a my-openclaw - Налаштуйте Gateway: [Конфігурація Gateway](/uk/gateway/configuration) - Підтримуйте OpenClaw в актуальному стані: [Оновлення](/uk/install/updating) -## Пов’язано +## Пов’язане - [Огляд встановлення](/uk/install) - [Hetzner](/uk/install/hetzner) - [Docker](/uk/install/docker) -- [VPS-хостинг](/uk/vps) +- [Хостинг VPS](/uk/vps) diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index b7b26ae16..494758511 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,205 +1,205 @@ --- read_when: - - Запуск coding harnesses через ACP - - Налаштування прив’язаних до розмови сесій ACP на каналах обміну повідомленнями - - Прив’язка розмови в каналі повідомлень до постійної сесії ACP - - Усунення несправностей бекенду ACP і підключення Plugin - - Налагодження доставки завершення ACP або циклів між агентами - - Використання команд `/acp` у чаті -summary: Використовуйте сесії середовища виконання ACP для Claude Code, Cursor, Gemini CLI, явного резервного ACP Codex, ACP OpenClaw та інших агентів harness. + - Запуск обв’язок кодування через ACP + - Налаштування ACP-сеансів, прив’язаних до розмов, у каналах обміну повідомленнями + - Прив’язування розмови в каналі повідомлень до постійного ACP-сеансу + - Усунення неполадок внутрішнього сервера ACP і підключення Plugin + - Налагодження доставки завершень ACP або циклів між агентами + - Використання команд `/acp` із чату +summary: Використовуйте сеанси середовища виконання ACP для Claude Code, Cursor, Gemini CLI, явного резервного ACP Codex, OpenClaw ACP та інших агентів обв’язки title: агенти ACP x-i18n: - generated_at: "2026-04-26T00:29:14Z" + generated_at: "2026-04-26T00:40:15Z" model: gpt-5.4 provider: openai - source_hash: 6fbf36aa46bbd555881333368c858ec80271ce188d01fb0e71ef12a13d2d626e + source_hash: a83f8a9a90569fd5d6e7bff4edbf15831e01179964a2d758fd1b70578ca378a0 source_path: tools/acp-agents.md workflow: 15 --- -Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harnesses (наприклад Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через бекенд Plugin ACP. +Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні обв’язки кодування (наприклад Pi, Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані обв’язки ACPX) через внутрішній серверний Plugin ACP. -Якщо ви просите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові й увімкнено вбудований Plugin `codex`, OpenClaw має використовувати нативний Plugin app-server для Codex (`/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, `/codex stop`) замість ACP. Якщо ви явно просите `/acp`, ACP, acpx або тест адаптера ACP, OpenClaw усе одно може маршрутизувати Codex через ACP. Кожен запуск сесії ACP відстежується як [фонове завдання](/uk/automation/tasks). +Якщо ви попросите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові й увімкнено вбудований Plugin `codex`, OpenClaw має використовувати нативний Plugin app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, `/codex stop`) замість ACP. Якщо ви явно попросите `/acp`, ACP, acpx або тест адаптера ACP, OpenClaw усе одно може маршрутизувати Codex через ACP. Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). -Якщо ви просите OpenClaw звичайною мовою "запустити Claude Code у гілці" або використати інший зовнішній harness, OpenClaw має маршрутизувати цей запит до середовища виконання ACP (а не до нативного середовища виконання sub-agent). +Якщо ви попросите OpenClaw звичайною мовою «запустити Claude Code у потоці» або використати іншу зовнішню обв’язку, OpenClaw має маршрутизувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). -Якщо ви хочете, щоб Codex або Claude Code напряму підключалися як зовнішній MCP-клієнт -до наявних розмов каналів OpenClaw, використовуйте +Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній клієнт MCP безпосередньо +до наявних розмов OpenClaw у каналах, використовуйте [`openclaw mcp serve`](/uk/cli/mcp) замість ACP. -## Яка сторінка мені потрібна? +## Яку сторінку мені потрібно? -Поруч є три схожі поверхні, які легко сплутати: +Поруч є три поверхні, які легко сплутати: -| Ви хочете... | Використовуйте це | Примітки | -| ----------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex, коли увімкнено Plugin `codex`; включає прив’язані відповіді в чаті, пересилання зображень, керування model/fast/permissions, stop і steer. ACP — явний резервний варіант | -| Запускати Claude Code, Gemini CLI, явний Codex ACP або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Прив’язані до чату сесії, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування середовищем виконання | -| Відкрити сесію OpenClaw Gateway _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим мосту. IDE/клієнт говорить з OpenClaw через ACP по stdio/WebSocket | -| Повторно використовувати локальний AI CLI як резервну текстову модель | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без керування ACP, без середовища виконання harness | +| Ви хочете... | Використовуйте це | Примітки | +| ------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex, коли увімкнено Plugin `codex`; містить прив’язані відповіді в чаті, пересилання зображень, елементи керування model/fast/permissions, зупинку та steer. ACP є явним резервним варіантом | +| Запустити Claude Code, Gemini CLI, явний Codex ACP або іншу зовнішню обв’язку _через_ OpenClaw | Ця сторінка: агенти ACP | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування середовищем виконання | +| Відкрити сеанс OpenClaw Gateway _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим мосту. IDE/клієнт взаємодіє з ACP у OpenClaw через stdio/WebSocket | +| Повторно використовувати локальний AI CLI як текстову резервну модель | [Внутрішні сервери CLI](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без середовища виконання обв’язки | -## Чи працює це з коробки? +## Чи працює це відразу після встановлення? -Зазвичай так. Нові встановлення постачаються з увімкненим за замовчуванням вбудованим Runtime Plugin `acpx`, із закріпленим локально для Plugin бінарним файлом `acpx`, який OpenClaw перевіряє й самостійно відновлює під час запуску. Запустіть `/acp doctor`, щоб перевірити готовність. +Зазвичай так. У свіжих установках вбудований Plugin середовища виконання `acpx` увімкнено за замовчуванням разом із локально закріпленим у Plugin двійковим файлом `acpx`, який OpenClaw перевіряє та самостійно відновлює під час запуску. Запустіть `/acp doctor`, щоб перевірити готовність. -Поширені нюанси першого запуску: +Типові нюанси першого запуску: -- Якщо встановлено `plugins.allow`, це обмежувальний перелік Plugin-ів і він має включати `acpx`; інакше вбудований варіант за замовчуванням навмисно блокується, а `/acp doctor` повідомляє про відсутній запис у allowlist. -- Адаптери цільових harnesses (Codex, Claude тощо) можуть бути завантажені за потреби через `npx` під час першого використання. -- Автентифікація постачальника для цього harness усе одно має бути налаштована на хості. -- Якщо хост не має доступу до npm або мережі, початкове завантаження адаптерів завершиться помилкою, доки кеші не буде прогріто або адаптер не буде встановлено іншим способом. +- Якщо задано `plugins.allow`, це обмежувальний перелік Plugin, і він має містити `acpx`; інакше вбудоване значення за замовчуванням навмисно блокується, а `/acp doctor` повідомляє про відсутній запис у списку дозволених. +- Адаптери цільових обв’язок (Codex, Claude тощо) можуть завантажуватися за потреби через `npx` під час першого використання. +- На хості все одно має бути налаштована автентифікація постачальника для цієї обв’язки. +- Якщо на хості немає npm або доступу до мережі, перше завантаження адаптерів завершиться помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. -## Операційний runbook +## Операторський посібник -Швидкий процес `/acp` у чаті: +Швидкий процес `/acp` із чату: -1. **Запуск** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явний `/acp spawn codex --bind here` -2. **Працюйте** у прив’язаній розмові або гілці (або явно вказуйте ключ сесії). -3. **Перевіряйте стан** — `/acp status` -4. **Налаштовуйте** — `/acp model `, `/acp permissions `, `/acp timeout ` -5. **Спрямовуйте** без заміни контексту — `/acp steer tighten logging and continue` -6. **Зупинка** — `/acp cancel` (поточний хід) або `/acp close` (сесія + прив’язки) +1. **Створити** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явне `/acp spawn codex --bind here` +2. **Працювати** в прив’язаній розмові або потоці (або явно вказати ключ сеансу). +3. **Перевірити стан** — `/acp status` +4. **Налаштувати** — `/acp model `, `/acp permissions `, `/acp timeout ` +5. **Скерувати** без заміни контексту — `/acp steer tighten logging and continue` +6. **Зупинити** — `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки) -Тригери природною мовою, які мають маршрутизуватися до нативного Plugin Codex, коли його -увімкнено: +Тригери природною мовою, які мають маршрутизуватися до нативного Plugin Codex, коли +його увімкнено: -- "Прив’яжи цей канал Discord до Codex." -- "Приєднай цей чат до гілки Codex ``." -- "Покажи гілки Codex, а потім прив’яжи цю." +- «Прив’яжи цей канал Discord до Codex». +- «Прикріпи цей чат до потоку Codex ``». +- «Покажи потоки Codex, а потім прив’яжи цей». -Нативна прив’язка розмов Codex є типовим шляхом керування з чату. Динамічні +Нативне прив’язування розмов Codex — це стандартний шлях керування чатом. Динамічні інструменти OpenClaw, як і раніше, виконуються через OpenClaw, тоді як нативні інструменти Codex, такі як shell/apply-patch, виконуються всередині Codex. Для подій -нативних інструментів Codex OpenClaw впроваджує relay нативних hook-ів на кожен хід, -щоб hook-и Plugin-ів могли блокувати `before_tool_call`, спостерігати -`after_tool_call` і маршрутизувати події Codex -`PermissionRequest` через схвалення OpenClaw. Hook-и Codex `Stop` -передаються до OpenClaw `before_agent_finalize`, де Plugin-и можуть запросити ще один -прохід моделі перед тим, як Codex завершить свою відповідь. Relay навмисно залишається -обережним: він не змінює аргументи нативних інструментів Codex і не переписує записи -гілок Codex. Використовуйте явний ACP лише тоді, коли вам потрібна модель -середовища виконання/сесій ACP. Межа підтримки вбудованого Codex задокументована в -[контракті підтримки harness Codex v1](/uk/plugins/codex-harness#v1-support-contract). +нативних інструментів Codex OpenClaw впроваджує нативну ретрансляцію хуків для кожного ходу, щоб +хуки Plugin могли блокувати `before_tool_call`, спостерігати за `after_tool_call` і +маршрутизувати події Codex `PermissionRequest` через погодження OpenClaw. Хуки `Stop` +Codex ретранслюються до `before_agent_finalize` в OpenClaw, де Plugin можуть запросити +ще один прохід моделі перед тим, як Codex завершить свою відповідь. Ретрансляція +навмисно залишається консервативною: вона не змінює аргументи нативних інструментів Codex +і не переписує записи потоків Codex. Використовуйте явний ACP лише тоді, коли вам +потрібна модель середовища виконання/сеансу ACP. Межу вбудованої підтримки Codex +задокументовано в +[контракті підтримки обв’язки Codex v1](/uk/plugins/codex-harness#v1-support-contract). Тригери природною мовою, які мають маршрутизуватися до середовища виконання ACP: -- "Запусти це як одноразову сесію Claude Code ACP і підсумуй результат." -- "Використай Gemini CLI для цього завдання в гілці, а потім зберігай подальші повідомлення в цій самій гілці." -- "Запусти Codex через ACP у фоновій гілці." +- «Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат». +- «Використай Gemini CLI для цього завдання в потоці, а потім залишай подальші дії в цьому самому потоці». +- «Запусти Codex через ACP у фоновому потоці». -OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, прив’язує до поточної розмови або гілки, якщо це підтримується, і маршрутизує подальші повідомлення до цієї сесії, доки її не буде закрито або доки не сплине термін дії. Codex використовує цей шлях лише тоді, коли ACP/acpx вказано явно або нативний Plugin Codex недоступний для запитаної операції. +OpenClaw вибирає `runtime: "acp"`, визначає `agentId` обв’язки, прив’язує до поточної розмови або потоку, якщо це підтримується, і маршрутизує подальші дії до цього сеансу до закриття або завершення терміну дії. Codex використовує цей шлях лише тоді, коли ACP/acpx вказано явно або нативний Plugin Codex недоступний для запитаної операції. Для `sessions_spawn` параметр `runtime: "acp"` оголошується лише тоді, коли ACP увімкнено, -запитувач не перебуває в sandbox, і завантажено бекенд середовища виконання ACP. Він націлюється -на ідентифікатори harness ACP, такі як `codex`, `claude`, `gemini` або `opencode`. Не передавайте -звичайний ідентифікатор агента конфігурації OpenClaw з `agents_list`, якщо цей запис не -налаштований явно з `agents.list[].runtime.type="acp"`; інакше використовуйте -типове середовище виконання sub-agent. Коли агент OpenClaw налаштований із -`runtime.type="acp"`, OpenClaw використовує `runtime.acp.agent` як базовий -ідентифікатор harness. +запитувач не перебуває в ізольованому середовищі, а внутрішній сервер середовища виконання ACP завантажено. Він націлений +на ідентифікатори обв’язок ACP, такі як `codex`, `claude`, `droid`, `gemini` або `opencode`. Не передавайте +звичайний ідентифікатор агента конфігурації OpenClaw із `agents_list`, якщо цей запис +не налаштовано явно з `agents.list[].runtime.type="acp"`; інакше використовуйте +середовище виконання субагента за замовчуванням. Якщо агент OpenClaw налаштовано з +`runtime.type="acp"`, OpenClaw використовує `runtime.acp.agent` як базовий ідентифікатор +обв’язки. -## ACP проти sub-agents +## ACP проти субагентів -Використовуйте ACP, якщо вам потрібне зовнішнє середовище виконання harness. Використовуйте нативний app-server Codex для прив’язки/керування розмовами Codex, коли увімкнено Plugin `codex`. Використовуйте sub-agents, якщо вам потрібні делеговані запуски, нативні для OpenClaw. +Використовуйте ACP, якщо вам потрібне середовище виконання зовнішньої обв’язки. Використовуйте нативний app-server Codex для прив’язування/керування розмовами Codex, коли увімкнено Plugin `codex`. Використовуйте субагентів, якщо вам потрібні делеговані запуски, нативні для OpenClaw. -| Область | Сесія ACP | Запуск sub-agent | +| Область | Сеанс ACP | Запуск субагента | | ------------- | ------------------------------------- | ----------------------------------- | -| Runtime | Бекенд Plugin ACP (наприклад acpx) | Нативне середовище виконання sub-agent OpenClaw | -| Ключ сесії | `agent::acp:` | `agent::subagent:` | +| Середовище виконання | Внутрішній серверний Plugin ACP (наприклад acpx) | Нативне середовище виконання субагента OpenClaw | +| Ключ сеансу | `agent::acp:` | `agent::subagent:` | | Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типове середовище виконання) | +| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | -Див. також [Sub-agents](/uk/tools/subagents). +Див. також [Субагенти](/uk/tools/subagents). ## Як ACP запускає Claude Code -Для Claude Code через ACP стек такий: +Для Claude Code через ACP стек виглядає так: -1. Контрольна площина сесій ACP OpenClaw -2. вбудований Runtime Plugin `acpx` -3. адаптер Claude ACP -4. механіка середовища виконання/сесій на боці Claude +1. Площина керування сеансом ACP OpenClaw +2. вбудований Plugin середовища виконання `acpx` +3. Адаптер Claude ACP +4. Механізми середовища виконання/сеансу на боці Claude Важливе розрізнення: -- ACP Claude — це сесія harness із керуванням ACP, відновленням сесії, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/гілки. -- CLI backends — це окремі локальні резервні середовища виконання лише для тексту. Див. [CLI Backends](/uk/gateway/cli-backends). +- ACP Claude — це сеанс обв’язки з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковим прив’язуванням до розмови/потоку. +- Внутрішні сервери CLI — це окремі локальні резервні середовища виконання лише для тексту. Див. [Внутрішні сервери CLI](/uk/gateway/cli-backends). Для операторів практичне правило таке: -- потрібні `/acp spawn`, сесії з можливістю прив’язки, керування середовищем виконання або постійна робота harness: використовуйте ACP -- потрібен простий локальний резервний текстовий режим через сирий CLI: використовуйте CLI backends +- якщо потрібні `/acp spawn`, сеанси з можливістю прив’язування, елементи керування середовищем виконання або постійна робота обв’язки: використовуйте ACP +- якщо потрібен простий локальний текстовий резервний варіант через сирий CLI: використовуйте внутрішні сервери CLI -## Прив’язані сесії +## Прив’язані сеанси ### Прив’язки до поточної розмови -`/acp spawn --bind here` закріплює поточну розмову за запущеною сесією ACP — без дочірньої гілки, на тій самій поверхні чату. OpenClaw і далі керує транспортом, автентифікацією, безпекою та доставкою; подальші повідомлення в цій розмові маршрутизуються до тієї самої сесії; `/new` і `/reset` скидають сесію на місці; `/acp close` видаляє прив’язку. +`/acp spawn --bind here` закріплює поточну розмову за створеним сеансом ACP — без дочірнього потоку, на тій самій поверхні чату. OpenClaw продовжує володіти транспортом, автентифікацією, безпекою та доставкою; подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` видаляє прив’язку. Ментальна модель: - **поверхня чату** — місце, де люди продовжують спілкуватися (канал Discord, тема Telegram, чат iMessage). -- **сесія ACP** — стійкий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw. -- **дочірня гілка/тема** — необов’язкова додаткова поверхня обміну повідомленнями, яка створюється лише за допомогою `--thread ...`. -- **робочий простір середовища виконання** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір бекенду), де працює harness. Незалежне від поверхні чату. +- **сеанс ACP** — стійкий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw. +- **дочірній потік/тема** — необов’язкова додаткова поверхня повідомлень, яка створюється лише за `--thread ...`. +- **робочий простір середовища виконання** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір внутрішнього сервера), де запускається обв’язка. Незалежне від поверхні чату. Приклади: -- `/codex bind` — залишити цей чат, запустити або приєднати нативний app-server Codex, маршрутизувати сюди майбутні повідомлення. -- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштовувати прив’язану нативну гілку Codex із чату. -- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним ходом нативного Codex. -- `/acp spawn codex --bind here` — явний резервний ACP-варіант для Codex. -- `/acp spawn codex --thread auto` — OpenClaw може створити дочірню гілку/тему й прив’язати її там. -- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка чату, Codex працює в `/workspace/repo`. +- `/codex bind` — зберегти цей чат, створити або приєднати нативний app-server Codex, маршрутизувати сюди майбутні повідомлення. +- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштовувати прив’язаний нативний потік Codex із чату. +- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним нативним ходом Codex. +- `/acp spawn codex --bind here` — явний резервний ACP для Codex. +- `/acp spawn codex --thread auto` — OpenClaw може створити дочірній потік/тему та прив’язати там. +- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка до чату, Codex працює в `/workspace/repo`. Примітки: - `--bind here` і `--thread ...` взаємовиключні. -- `--bind here` працює лише на каналах, які оголошують підтримку прив’язки до поточної розмови; інакше OpenClaw повертає чітке повідомлення про відсутність підтримки. Прив’язки зберігаються після перезапуску Gateway. -- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірню гілку для `--thread auto|here` — не для `--bind here`. -- Якщо ви запускаєте до іншого агента ACP без `--cwd`, OpenClaw успадковує робочий простір **цільового агента** за замовчуванням. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до типового значення бекенду; інші помилки доступу (наприклад, `EACCES`) показуються як помилки запуску. +- `--bind here` працює лише в каналах, які оголошують підтримку прив’язування до поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив’язки зберігаються після перезапуску Gateway. +- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній потік для `--thread auto|here` — не для `--bind here`. +- Якщо ви створюєте сеанс для іншого агента ACP без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) призводять до повернення до значення внутрішнього сервера за замовчуванням; інші помилки доступу (наприклад `EACCES`) повертаються як помилки створення сеансу. -### Прив’язані до гілки сесії +### Сеанси, прив’язані до потоку -Коли для адаптера каналу ввімкнено прив’язки гілок, сесії ACP можна прив’язувати до гілок: +Коли для адаптера каналу увімкнено прив’язки до потоків, сеанси ACP можна прив’язувати до потоків: -- OpenClaw прив’язує гілку до цільової сесії ACP. -- Подальші повідомлення в цій гілці маршрутизуються до прив’язаної сесії ACP. -- Вивід ACP доставляється назад у ту саму гілку. -- Зняття фокуса/закриття/архівування/перевищення тайм-ауту бездіяльності або максимального віку знімає прив’язку. +- OpenClaw прив’язує потік до цільового сеансу ACP. +- Подальші повідомлення в цьому потоці маршрутизуються до прив’язаного сеансу ACP. +- Вивід ACP доставляється назад у той самий потік. +- Втрата фокуса/закриття/архівування/завершення часу бездіяльності або завершення максимального строку дії видаляє прив’язку. -Підтримка прив’язки гілок залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки гілок, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. +Підтримка прив’язування до потоку залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до потоку, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. -Обов’язкові feature flags для ACP, прив’язаного до гілки: +Обов’язкові feature flag для ACP, прив’язаного до потоку: - `acp.enabled=true` -- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) -- Увімкнено прапорець запуску ACP-гілок для адаптера каналу (залежить від адаптера) +- `acp.dispatch.enabled` увімкнено за замовчуванням (установіть `false`, щоб призупинити диспетчеризацію ACP) +- Увімкнений прапорець створення ACP-потоків для адаптера каналу (залежить від адаптера) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -### Канали з підтримкою гілок +### Канали з підтримкою потоків -- Будь-який адаптер каналу, який надає можливість прив’язки сесії/гілки. +- Будь-який адаптер каналу, який надає можливість прив’язування сеансу/потоку. - Поточна вбудована підтримка: - - гілки/канали Discord - - теми Telegram (теми форуму в групах/супергрупах і теми в DM) -- Канали Plugin-ів можуть додавати підтримку через той самий інтерфейс прив’язки. + - потоки/канали Discord + - теми Telegram (теми форуму в групах/супергрупах і теми DM) +- Канали Plugin можуть додавати підтримку через той самий інтерфейс прив’язування. ## Налаштування для конкретних каналів -Для неперехідних робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. +Для неефемерних робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. -### Модель прив’язки +### Модель прив’язування - `bindings[].type="acp"` позначає постійну прив’язку розмови ACP. - `bindings[].match` визначає цільову розмову: - - Канал або гілка Discord: `match.channel="discord"` + `match.peer.id=""` + - Канал або потік Discord: `match.channel="discord"` + `match.peer.id=""` - Тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - - DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`. - - DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*`. + - Чат DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` + Для стабільних прив’язок груп краще використовувати `chat_id:*` або `chat_identifier:*`. + - Чат DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id=""` + Для стабільних прив’язок груп краще використовувати `chat_id:*`. - `bindings[].agentId` — це ідентифікатор агента OpenClaw-власника. - Необов’язкові перевизначення ACP розміщуються в `bindings[].acp`: - `mode` (`persistent` або `oneshot`) @@ -207,21 +207,21 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п - `cwd` - `backend` -### Типові значення середовища виконання для кожного агента +### Значення середовища виконання за замовчуванням для кожного агента -Використовуйте `agents.list[].runtime`, щоб один раз визначити типові параметри ACP для кожного агента: +Використовуйте `agents.list[].runtime`, щоб один раз визначити значення ACP за замовчуванням для кожного агента: - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent` (ідентифікатор harness, наприклад `codex` або `claude`) +- `agents.list[].runtime.acp.agent` (ідентифікатор обв’язки, наприклад `codex` або `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -Пріоритет перевизначення для прив’язаних сесій ACP: +Пріоритет перевизначень для прив’язаних сеансів ACP: 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` -3. глобальні типові параметри ACP (наприклад `acp.backend`) +3. глобальні значення ACP за замовчуванням (наприклад `acp.backend`) Приклад: @@ -305,18 +305,18 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п Поведінка: -- OpenClaw забезпечує наявність налаштованої сесії ACP перед використанням. -- Повідомлення в цьому каналі або темі маршрутизуються до налаштованої сесії ACP. -- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сесії ACP на місці. -- Тимчасові прив’язки середовища виконання (наприклад, створені потоками фокусування гілок) усе одно застосовуються, якщо вони існують. +- OpenClaw гарантує, що налаштований сеанс ACP існує перед використанням. +- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого сеансу ACP. +- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. +- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування) усе одно застосовуються там, де вони є. - Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. -- Відсутні успадковані шляхи робочого простору повертаються до типового `cwd` бекенду; збої доступу для наявних шляхів відображаються як помилки запуску. +- Відсутні шляхи успадкованого робочого простору призводять до повернення до `cwd` внутрішнього сервера за замовчуванням; збої доступу для наявних шляхів повертаються як помилки створення сеансу. -## Запуск сесій ACP (інтерфейси) +## Запуск сеансів ACP (інтерфейси) ### Із `sessions_spawn` -Використовуйте `runtime: "acp"`, щоб запустити сесію ACP із ходу агента або виклику інструмента. +Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента. ```json { @@ -330,71 +330,71 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п Примітки: -- Типове значення `runtime` — `subagent`, тому для сесій ACP явно задавайте `runtime: "acp"`. +- Значення `runtime` за замовчуванням — `subagent`, тому для сеансів ACP явно вказуйте `runtime: "acp"`. - Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. -- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову. +- `mode: "session"` вимагає `thread: true`, щоб зберігати постійну прив’язану розмову. Деталі інтерфейсу: -- `task` (обов’язково): початковий prompt, що надсилається до сесії ACP. +- `task` (обов’язково): початковий запит, надісланий до сеансу ACP. - `runtime` (обов’язково для ACP): має бути `"acp"`. -- `agentId` (необов’язково): ідентифікатор цільового ACP harness. Якщо задано, використовується `acp.defaultAgent`. -- `thread` (необов’язково, типово `false`): запитати потік прив’язки до гілки, якщо підтримується. +- `agentId` (необов’язково): ідентифікатор цільової ACP-обв’язки. Якщо задано `acp.defaultAgent`, використовується він. +- `thread` (необов’язково, за замовчуванням `false`): запит на потік прив’язування там, де це підтримується. - `mode` (необов’язково): `run` (одноразовий) або `session` (постійний). - - типове значення — `run` - - якщо `thread: true` і `mode` не вказано, OpenClaw може типово перейти до постійної поведінки залежно від шляху середовища виконання + - значення за замовчуванням — `run` + - якщо `thread: true` і `mode` пропущено, OpenClaw може за замовчуванням перейти до постійної поведінки залежно від шляху середовища виконання - `mode: "session"` вимагає `thread: true` -- `cwd` (необов’язково): запитаний робочий каталог середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо його не вказано, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенду, а реальні помилки доступу повертаються користувачу. -- `label` (необов’язково): видима для оператора мітка, що використовується в тексті сесії/банера. -- `resumeSessionId` (необов’язково): відновити наявну сесію ACP замість створення нової. Агент відтворює свою історію розмови через `session/load`. Потрібно `runtime: "acp"`. -- `streamTo` (необов’язково): `"parent"` передає підсумки поступу початкового запуску ACP назад до сесії-запитувача як системні події. - - Якщо доступно, прийняті відповіді включають `streamLogPath`, що вказує на прив’язаний до сесії журнал JSONL (`.acp-stream.jsonl`), який можна читати для повної історії relay. -- `runTimeoutSeconds` (необов’язково): перериває дочірній хід ACP через N секунд. Значення `0` залишає хід на шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway і середовища виконання ACP, щоб harnesses, які зависли або вичерпали квоту, не займали смугу батьківського агента невизначено довго. -- `model` (необов’язково): явне перевизначення model для дочірньої сесії ACP. Запуски Codex ACP нормалізують посилання Codex OpenClaw, наприклад `openai-codex/gpt-5.4`, до стартової конфігурації Codex ACP перед `session/new`; форми зі слешами, такі як `openai-codex/gpt-5.4/high`, також задають зусилля міркування Codex ACP. Інші harnesses мають оголошувати ACP `models` і підтримувати `session/set_model`; інакше OpenClaw/acpx повертає чітку помилку замість тихого повернення до типової model цільового агента. -- `thinking` (необов’язково): явне зусилля thinking/reasoning для дочірньої сесії ACP. Для Codex ACP значення `minimal` відповідає низькому рівню зусилля, `low`/`medium`/`high`/`xhigh` відображаються напряму, а `off` не додає стартове перевизначення reasoning-effort. +- `cwd` (необов’язково): запитаний робочий каталог середовища виконання (перевіряється політикою внутрішнього сервера/середовища виконання). Якщо його пропущено, ACP-запуск успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи призводять до повернення до значень внутрішнього сервера за замовчуванням, а реальні помилки доступу повертаються. +- `label` (необов’язково): операторська мітка, яка використовується в тексті сеансу/банера. +- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює історію своєї розмови через `session/load`. Потрібно `runtime: "acp"`. +- `streamTo` (необов’язково): `"parent"` транслює підсумки перебігу початкового запуску ACP назад до сеансу-запитувача як системні події. + - Коли доступно, серед прийнятих відповідей є `streamLogPath`, який указує на JSONL-журнал у межах сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. +- `runTimeoutSeconds` (необов’язково): перериває дочірній хід ACP через N секунд. `0` залишає хід на шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway і середовища виконання ACP, щоб обв’язки, які зависли або вичерпали квоту, не займали смугу батьківського агента необмежено довго. +- `model` (необов’язково): явне перевизначення моделі для дочірнього сеансу ACP. ACP-запуски Codex нормалізують посилання Codex OpenClaw, як-от `openai-codex/gpt-5.4`, до стартової конфігурації Codex ACP перед `session/new`; форми зі слешами, як-от `openai-codex/gpt-5.4/high`, також задають зусилля міркування Codex ACP. Інші обв’язки мають оголошувати ACP `models` і підтримувати `session/set_model`; інакше OpenClaw/acpx повертає чітку помилку замість тихого повернення до цільового агента за замовчуванням. +- `thinking` (необов’язково): явне зусилля thinking/reasoning для дочірнього сеансу ACP. Для Codex ACP значення `minimal` відповідає низькому рівню зусиль, `low`/`medium`/`high`/`xhigh` напряму відображаються, а `off` пропускає стартове перевизначення зусилля міркування. ## Модель доставки -Сесії ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківській сесії. Шлях доставки залежить від цієї форми. +Сеанси ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківському агенту. Шлях доставки залежить від цієї форми. -### Інтерактивні сесії ACP +### Інтерактивні сеанси ACP -Інтерактивні сесії призначені для продовження розмови на видимій поверхні чату: +Інтерактивні сеанси призначені для продовження спілкування на видимій поверхні чату: -- `/acp spawn ... --bind here` прив’язує поточну розмову до сесії ACP. -- `/acp spawn ... --thread ...` прив’язує гілку/тему каналу до сесії ACP. -- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до тієї самої сесії ACP. +- `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP. +- `/acp spawn ... --thread ...` прив’язує потік/тему каналу до сеансу ACP. +- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до того самого сеансу ACP. -Подальші повідомлення в прив’язаній розмові напряму маршрутизуються до сесії ACP, а вивід ACP доставляється назад у той самий канал/гілку/тему. +Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад у той самий канал/потік/тему. -### Одноразові сесії ACP, що належать батьківській сесії +### Одноразові сеанси ACP, що належать батьківському агенту -Одноразові сесії ACP, запущені іншим агентом, є фоновими дочірніми сесіями, подібно до sub-agents: +Одноразові сеанси ACP, створені іншим запуском агента, — це фонові дочірні сеанси, подібні до субагентів: -- Батьківська сесія запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. -- Дочірня сесія виконується у власній сесії ACP harness. -- Дочірні ходи виконуються на тій самій фоновій смузі, що й нативні запуски sub-agent, тож повільний ACP harness не блокує іншу роботу основної сесії. +- Батьківський агент запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. +- Дочірній агент запускається у власному сеансі ACP-обв’язки. +- Дочірні ходи виконуються на тій самій фоновій смузі, що й нативні запускі субагентів, тому повільна ACP-обв’язка не блокує несуміжну роботу головного сеансу. - Завершення повертається через внутрішній шлях оголошення про завершення завдання. -- Якщо потрібна відповідь для користувача, батьківська сесія переписує результат дочірньої сесії звичайним голосом помічника. +- Коли потрібна відповідь для користувача, батьківський агент переписує результат дочірнього звичайним голосом помічника. -Не розглядайте цей шлях як одноранговий чат між батьківською й дочірньою сесіями. Дочірня сесія вже має канал завершення назад до батьківської. +Не сприймайте цей шлях як peer-to-peer чат між батьківським і дочірнім агентом. У дочірнього агента вже є канал завершення назад до батьківського. ### `sessions_send` і доставка A2A -`sessions_send` може націлюватися на іншу сесію після запуску. Для звичайних однорангових сесій OpenClaw використовує шлях подальших повідомлень agent-to-agent (A2A) після впровадження повідомлення: +`sessions_send` може націлюватися на інший сеанс після створення. Для звичайних peer-сеансів OpenClaw використовує шлях подальших дій agent-to-agent (A2A) після впровадження повідомлення: -- очікує на відповідь цільової сесії -- за потреби дає змогу запитувачу й цільовій сесії обмінятися обмеженою кількістю подальших ходів -- просить цільову сесію створити повідомлення-оголошення -- доставляє це оголошення до видимого каналу або гілки +- очікує на відповідь цільового сеансу +- за потреби дає змогу запитувачу й цільовому сеансу обмінятися обмеженою кількістю подальших ходів +- просить цільовий сеанс створити повідомлення-оголошення +- доставляє це оголошення у видимий канал або потік -Цей шлях A2A є резервним варіантом для однорангових надсилань, коли відправнику потрібне видиме подальше повідомлення. Він залишається ввімкненим, коли не пов’язана сесія може бачити й надсилати повідомлення до цілі ACP, наприклад за широких налаштувань `tools.sessions.visibility`. +Цей шлях A2A є резервним варіантом для peer-надсилань, коли відправнику потрібна видима подальша дія. Він залишається ввімкненим, коли непов’язаний сеанс може бачити й надсилати повідомлення до цільового ACP-сеансу, наприклад за широких налаштувань `tools.sessions.visibility`. -OpenClaw пропускає подальший шлях A2A лише тоді, коли запитувач є батьківською сесією для власної одноразової дочірньої ACP-сесії. У такому разі запуск A2A поверх завершення завдання може розбудити батьківську сесію результатом дочірньої, переслати відповідь батьківської назад у дочірню й створити цикл відлуння між батьківською та дочірньою сесіями. Для такого випадку власної дочірньої сесії результат `sessions_send` повідомляє `delivery.status="skipped"`, оскільки шлях завершення вже відповідає за результат. +OpenClaw пропускає подальшу дію A2A лише тоді, коли запитувач є батьківським агентом свого власного одноразового дочірнього ACP-сеансу. У такому разі запуск A2A поверх завершення завдання може розбудити батьківський агент результатом дочірнього, переслати відповідь батьківського назад у дочірній і створити цикл echo між батьківським і дочірнім. Для такого випадку дочірнього сеансу, що належить батьківському, результат `sessions_send` повідомляє `delivery.status="skipped"`, оскільки за результат уже відповідає шлях завершення. -### Відновлення наявної сесії +### Відновлення наявного сеансу -Використовуйте `resumeSessionId`, щоб продовжити попередню сесію ACP замість запуску нової. Агент відтворює свою історію розмови через `session/load`, тому продовжує роботу з повним контекстом попереднього. +Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску нового. Агент відтворює історію своєї розмови через `session/load`, тож продовжує з повним контекстом попередньої роботи. ```json { @@ -405,49 +405,49 @@ OpenClaw пропускає подальший шлях A2A лише тоді, } ``` -Типові випадки використання: +Типові сценарії використання: -- Передати сесію Codex із ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися -- Продовжити coding-сесію, яку ви почали інтерактивно в CLI, а тепер хочете вести безголово через агента -- Відновити роботу, перервану перезапуском Gateway або тайм-аутом бездіяльності +- Передати сеанс Codex зі свого ноутбука на телефон — скажіть агенту продовжити з того місця, де ви зупинилися +- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, тепер безголовим режимом через свого агента +- Повернутися до роботи, яку було перервано перезапуском Gateway або тайм-аутом бездіяльності Примітки: -- `resumeSessionId` вимагає `runtime: "acp"` — якщо використати його з середовищем виконання sub-agent, буде повернуто помилку. -- `resumeSessionId` відновлює історію розмови в ACP на верхньому рівні; `thread` і `mode` усе ще звичайно застосовуються до нової сесії OpenClaw, яку ви створюєте, тож `mode: "session"` як і раніше вимагає `thread: true`. +- `resumeSessionId` вимагає `runtime: "acp"` — якщо використати його із середовищем виконання субагента, буде повернуто помилку. +- `resumeSessionId` відновлює історію розмови ACP вище за течією; `thread` і `mode` як і раніше звичайно застосовуються до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`. - Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). -- Якщо ідентифікатор сесії не знайдено, запуск завершується з чіткою помилкою — без тихого переходу до нової сесії. +- Якщо ідентифікатор сеансу не знайдено, створення завершується з чіткою помилкою — без тихого повернення до нового сеансу. - + -Після розгортання Gateway виконайте живу наскрізну перевірку, а не покладайтеся лише на unit-тести: +Після розгортання Gateway виконайте живу наскрізну перевірку, а не покладайтеся лише на модульні тести: -1. Перевірте версію та commit розгорнутого Gateway на цільовому хості. -2. Відкрийте тимчасову bridge-сесію ACPX до живого агента. -3. Попросіть цього агента викликати `sessions_spawn` із `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`. -4. Переконайтеся, що є `accepted=yes`, справжній `childSessionKey` і немає помилки валідатора. -5. Очистьте тимчасову bridge-сесію. +1. Перевірте версію та коміт розгорнутого Gateway на цільовому хості. +2. Відкрийте тимчасовий сеанс мосту ACPX до живого агента. +3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`. +4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки валідатора. +5. Очистьте тимчасовий сеанс мосту. -Тримайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — шляхи з прив’язкою до гілки для `mode: "session"` і relay потоків є окремими, багатшими інтеграційними перевірками. +Зберігайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — шляхи `mode: "session"`, прив’язані до потоку, і ретрансляція стримів є окремими, багатшими інтеграційними перевірками. ## Сумісність із sandbox -Наразі сесії ACP працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw. +Наразі сеанси ACP виконуються в середовищі виконання хоста, а не всередині sandbox OpenClaw. Поточні обмеження: -- Якщо сесія-запитувач перебуває в sandbox, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`. +- Якщо сеанс-запитувач працює в sandbox, запуск ACP блокується як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`. - Помилка: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.` -- `sessions_spawn` із `runtime: "acp"` не підтримує `sandbox: "require"`. +- `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`. - Помилка: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".` Використовуйте `runtime: "subagent"`, коли вам потрібне виконання з примусовим sandbox. ### Із команди `/acp` -Використовуйте `/acp spawn` для явного керування оператором із чату, коли це потрібно. +Використовуйте `/acp spawn` для явного операторського керування з чату, коли це потрібно. ```text /acp spawn codex --mode persistent --thread auto @@ -456,7 +456,7 @@ OpenClaw пропускає подальший шлях A2A лише тоді, /acp spawn codex --thread here ``` -Ключові прапорці: +Основні прапорці: - `--mode persistent|oneshot` - `--bind here|off` @@ -464,11 +464,11 @@ OpenClaw пропускає подальший шлях A2A лише тоді, - `--cwd ` - `--label ` -Див. [Slash Commands](/uk/tools/slash-commands). +Див. [Косі команди](/uk/tools/slash-commands). -## Визначення цілі сесії +## Визначення цільового сеансу -Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, `session-id` або `session-label`). +Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`). Порядок визначення: @@ -476,114 +476,114 @@ OpenClaw пропускає подальший шлях A2A лише тоді, - спочатку пробує ключ - потім `session id` у форматі UUID - потім мітку -2. Прив’язка поточної гілки (якщо цю розмову/гілку прив’язано до сесії ACP) -3. Резервне використання поточної сесії-запитувача +2. Поточна прив’язка потоку (якщо ця розмова/потік прив’язана до сеансу ACP) +3. Резервний варіант поточного сеансу-запитувача -Прив’язки до поточної розмови й прив’язки до гілки беруть участь у кроці 2. +Прив’язки до поточної розмови й прив’язки до потоків обидві беруть участь у кроці 2. -Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`). +Якщо жодну ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`). -## Режими прив’язки під час запуску +## Режими прив’язування під час створення сеансу `/acp spawn` підтримує `--bind here|off`. | Режим | Поведінка | | ------ | ---------------------------------------------------------------------- | -| `here` | Прив’язати поточну активну розмову на місці; завершити з помилкою, якщо активної розмови немає. | +| `here` | Прив’язати поточну активну розмову на місці; завершити з помилкою, якщо активної немає. | | `off` | Не створювати прив’язку до поточної розмови. | Примітки: -- `--bind here` — це найпростіший операторський шлях для сценарію "зробити цей канал або чат підкріпленим Codex." -- `--bind here` не створює дочірню гілку. -- `--bind here` доступний лише на каналах, які підтримують прив’язку до поточної розмови. +- `--bind here` — найпростіший операторський шлях для сценарію «зробити цей канал або чат на основі Codex». +- `--bind here` не створює дочірній потік. +- `--bind here` доступний лише в каналах, які надають підтримку прив’язування до поточної розмови. - `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`. -## Режими запуску з гілкою +## Режими потоку під час створення сеансу `/acp spawn` підтримує `--thread auto|here|off`. | Режим | Поведінка | | ------ | --------------------------------------------------------------------------------------------------- | -| `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо це підтримується. | -| `here` | Вимагає поточну активну гілку; завершується з помилкою, якщо ви не в ній. | -| `off` | Без прив’язки. Сесія запускається без прив’язки. | +| `auto` | В активному потоці: прив’язати цей потік. Поза потоком: створити/прив’язати дочірній потік, якщо це підтримується. | +| `here` | Вимагати поточний активний потік; завершити з помилкою, якщо ви не в потоці. | +| `off` | Без прив’язування. Сеанс запускається без прив’язки. | Примітки: -- На поверхнях без підтримки прив’язки до гілок типова поведінка фактично є `off`. -- Запуск із прив’язкою до гілки вимагає підтримки політики каналу: +- На поверхнях без підтримки прив’язування до потоків поведінка за замовчуванням фактично дорівнює `off`. +- Створення сеансу з прив’язуванням до потоку вимагає підтримки політики каналу: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -- Використовуйте `--bind here`, коли хочете закріпити поточну розмову без створення дочірньої гілки. +- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього потоку. -## Керування ACP +## Елементи керування ACP -| Команда | Що вона робить | Приклад | -| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | Створює сесію ACP; необов’язково прив’язує до поточної розмови або до гілки. | `/acp spawn codex --bind here --cwd /repo` | -| `/acp cancel` | Скасовує хід, що виконується, для цільової сесії. | `/acp cancel agent:codex:acp:` | -| `/acp steer` | Надсилає інструкцію steer до сесії, що виконується. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Закриває сесію й відв’язує цілі гілок. | `/acp close` | -| `/acp status` | Показує backend, режим, стан, параметри середовища виконання й можливості. | `/acp status` | -| `/acp set-mode` | Встановлює режим середовища виконання для цільової сесії. | `/acp set-mode plan` | -| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Встановлює перевизначення робочого каталогу середовища виконання. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Встановлює профіль політики схвалення. | `/acp permissions strict` | -| `/acp timeout` | Встановлює тайм-аут середовища виконання (у секундах). | `/acp timeout 120` | -| `/acp model` | Встановлює перевизначення model середовища виконання. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Видаляє перевизначення параметрів середовища виконання для сесії. | `/acp reset-options` | -| `/acp sessions` | Перелічує нещодавні сесії ACP зі сховища. | `/acp sessions` | -| `/acp doctor` | Перевірка стану backend, можливостей і доступних виправлень. | `/acp doctor` | -| `/acp install` | Виводить детерміновані кроки встановлення й увімкнення. | `/acp install` | +| Команда | Що робить | Приклад | +| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------ | +| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка потоку. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Скасовує активний хід для цільового сеансу. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | Надсилає інструкцію steer до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Закриває сеанс і відв’язує цілі потоку. | `/acp close` | +| `/acp status` | Показує внутрішній сервер, режим, стан, параметри середовища виконання, можливості. | `/acp status` | +| `/acp set-mode` | Установлює режим середовища виконання для цільового сеансу. | `/acp set-mode plan` | +| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Установлює перевизначення робочого каталогу середовища виконання. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Установлює профіль політики погодження. | `/acp permissions strict` | +| `/acp timeout` | Установлює тайм-аут середовища виконання (у секундах). | `/acp timeout 120` | +| `/acp model` | Установлює перевизначення моделі середовища виконання. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | Видаляє перевизначення параметрів середовища виконання для сеансу. | `/acp reset-options` | +| `/acp sessions` | Перелічує нещодавні сеанси ACP зі сховища. | `/acp sessions` | +| `/acp doctor` | Стан внутрішнього сервера, можливості, виправлення, які можна виконати. | `/acp doctor` | +| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` | -`/acp status` показує ефективні параметри середовища виконання, а також ідентифікатори сесії на рівні середовища виконання й backend. Помилки непідтримуваного керування відображаються явно, якщо backend не має відповідної можливості. `/acp sessions` читає сховище для поточної прив’язаної сесії або сесії-запитувача; токени цілі (`session-key`, `session-id` або `session-label`) визначаються через виявлення сесій Gateway, включно з користувацькими коренями `session.store` для окремих агентів. +`/acp status` показує фактичні параметри середовища виконання, а також ідентифікатори сеансу на рівні середовища виконання й внутрішнього сервера. Помилки про непідтримувані елементи керування повертаються чітко, коли внутрішньому серверу бракує потрібної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу-запитувача; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через виявлення сеансів Gateway, зокрема для спеціальних кореневих шляхів `session.store` для окремих агентів. ## Відображення параметрів середовища виконання -`/acp` має зручні команди й загальний setter. +`/acp` має зручні команди й універсальний setter. Еквівалентні операції: -- `/acp model ` відображається на ключ конфігурації середовища виконання `model`. Для Codex ACP OpenClaw нормалізує `openai-codex/` до ідентифікатора model адаптера й відображає суфікси міркування через слеш, такі як `openai-codex/gpt-5.4/high`, у Codex ACP `reasoning_effort`. Для інших harnesses керування model залежить від підтримки адаптером ACP `models` і `session/set_model`. -- `/acp set thinking ` відображається на ключ конфігурації середовища виконання `thinking`. Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер його підтримує. +- `/acp model ` відображається на ключ конфігурації середовища виконання `model`. Для Codex ACP OpenClaw нормалізує `openai-codex/` до ідентифікатора моделі адаптера й відображає суфікси міркування через слеш, як-от `openai-codex/gpt-5.4/high`, до Codex ACP `reasoning_effort`. Для інших обв’язок керування моделлю залежить від підтримки адаптером ACP `models` і `session/set_model`. +- `/acp set thinking ` відображається на ключ конфігурації середовища виконання `thinking`. Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер це підтримує. - `/acp permissions ` відображається на ключ конфігурації середовища виконання `approval_policy`. - `/acp timeout ` відображається на ключ конфігурації середовища виконання `timeout`. - `/acp cwd ` напряму оновлює перевизначення `cwd` середовища виконання. -- `/acp set ` — це загальний шлях. +- `/acp set ` — це універсальний шлях. - Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`. -- `/acp reset-options` очищує всі перевизначення середовища виконання для цільової сесії. +- `/acp reset-options` очищає всі перевизначення середовища виконання для цільового сеансу. -## acpx harness, налаштування Plugin, і permissions +## Обв’язка acpx, налаштування Plugin і дозволи -Щоб дізнатися про конфігурацію acpx harness (аліаси Claude Code / Codex / Gemini CLI), -мости MCP plugin-tools і OpenClaw-tools, а також режими permissions ACP, див. -[ACP agents — налаштування](/uk/tools/acp-agents-setup). +Докладніше про конфігурацію обв’язки acpx (псевдоніми Claude Code / Codex / Gemini CLI), +мости MCP plugin-tools і OpenClaw-tools, а також режими дозволів ACP див. у +[ACP agents — setup](/uk/tools/acp-agents-setup). -## Усунення несправностей +## Усунення неполадок -| Симптом | Імовірна причина | Виправлення | -| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | Backend Plugin відсутній, вимкнений або заблокований через `plugins.allow`. | Установіть і ввімкніть backend Plugin, додайте `acpx` до `plugins.allow`, якщо цей allowlist увімкнено, а потім запустіть `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Вимкнено диспетчеризацію зі звичайних повідомлень у гілках. | Установіть `acp.dispatch.enabled=true`. | -| `ACP agent "" is not allowed by policy` | Агент відсутній у allowlist. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. | -| `Unable to resolve session target: ...` | Неправильний токен ключа/ідентифікатора/мітки. | Запустіть `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу. | -| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. | -| `Conversation bindings are unavailable for .` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом гілки. | Перейдіть до цільової гілки або використайте `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачу. | Переприв’яжіть як власник або використайте іншу розмову чи гілку. | -| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки до гілок. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на хості; сесія-запитувач перебуває в sandbox. | Використовуйте `runtime="subagent"` із sandbox-сесій або запускайте ACP із сесії поза sandbox. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandbox або ACP із `sandbox="inherit"` із сесії поза sandbox. | -| `Cannot apply --model ... did not advertise model support` | Цільовий harness не підтримує загальне перемикання model через ACP. | Використовуйте harness, який оголошує ACP `models`/`session/set_model`, використовуйте посилання model для Codex ACP або налаштуйте model безпосередньо в harness, якщо він має власний прапорець запуску. | -| Missing ACP metadata for bound session | Застарілі або видалені метадані сесії ACP. | Створіть сесію заново через `/acp spawn`, а потім повторно прив’яжіть або сфокусуйте гілку. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує записи/виконання в неінтерактивній сесії ACP. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування permissions](/uk/tools/acp-agents-setup#permission-configuration). | -| ACP session fails early with little output | Запити permissions блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних permissions установіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | -| ACP session stalls indefinitely after completing work | Процес harness завершився, але сесія ACP не повідомила про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть завислі процеси. | +| Симптом | Ймовірна причина | Виправлення | +| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ACP runtime backend is not configured` | Внутрішній серверний Plugin відсутній, вимкнений або заблокований через `plugins.allow`. | Установіть і ввімкніть внутрішній серверний Plugin, додайте `acpx` до `plugins.allow`, якщо задано цей список дозволених, а потім запустіть `/acp doctor`. | +| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень потоку вимкнено. | Установіть `acp.dispatch.enabled=true`. | +| `ACP agent "" is not allowed by policy` | Агента немає в списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. | +| `Unable to resolve session target: ...` | Неправильний токен ключа/ідентифікатора/мітки. | Запустіть `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть до цільового чату/каналу й повторіть спробу або використайте запуск без прив’язки. | +| `Conversation bindings are unavailable for .` | Адаптер не має можливості ACP-прив’язування до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть до підтримуваного каналу. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом потоку. | Перейдіть до цільового потоку або використовуйте `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язування. | Повторно прив’яжіть як власник або використайте іншу розмову чи потік. | +| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язування до потоку. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на боці хоста; сеанс-запитувач працює в sandbox. | Використовуйте `runtime="subagent"` із sandbox-сеансів або запускайте ACP із сеансу поза sandbox. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Для обов’язкового sandbox використовуйте `runtime="subagent"` або використовуйте ACP із `sandbox="inherit"` із сеансу поза sandbox. | +| `Cannot apply --model ... did not advertise model support` | Цільова обв’язка не надає загального перемикання моделей ACP. | Використовуйте обв’язку, яка оголошує ACP `models`/`session/set_model`, використовуйте посилання моделі Codex ACP або налаштуйте модель безпосередньо в обв’язці, якщо вона має власний стартовий прапорець. | +| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново через `/acp spawn`, а потім знову прив’яжіть/сфокусуйте потік. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/виконання в неінтерактивному сеансі ACP. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть Gateway. Див. [Конфігурація дозволів](/uk/tools/acp-agents-setup#permission-configuration). | +| ACP session fails early with little output | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали Gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | Процес обв’язки завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. | ## Пов’язане -- [Sub-agents](/uk/tools/subagents) -- [Інструменти sandbox для кількох агентів](/uk/tools/multi-agent-sandbox-tools) +- [Субагенти](/uk/tools/subagents) +- [Інструменти sandbox для багатьох агентів](/uk/tools/multi-agent-sandbox-tools) - [Надсилання агенту](/uk/tools/agent-send) diff --git a/docs/uk/tools/subagents.md b/docs/uk/tools/subagents.md index 14545ea51..ca076bf94 100644 --- a/docs/uk/tools/subagents.md +++ b/docs/uk/tools/subagents.md @@ -1,24 +1,24 @@ --- read_when: - - Ви хочете фонову/паралельну роботу через agent - - Ви змінюєте політику інструмента sessions_spawn або sub-agent - - Ви реалізуєте або усуваєте несправності прив’язаних до потоку сесій subagent -summary: 'Sub-agents: запуск ізольованих виконань agent, які повідомляють результати назад у чат запитувача' -title: Sub-agents + - Ви хочете фонову/паралельну роботу через агент + - Ви змінюєте `sessions_spawn` або політику інструмента підагентів + - Ви реалізуєте або усуваєте несправності сеансів підагентів, прив’язаних до потоку +summary: 'Підагенти: запуск ізольованих запусків агентів, які повідомляють про результати назад у чат запитувача' +title: Підагенти x-i18n: - generated_at: "2026-04-26T00:20:14Z" + generated_at: "2026-04-26T00:40:11Z" model: gpt-5.4 provider: openai - source_hash: 190f2dd3b5465fc2f9026769a60d03862fc2dbadb1cb66bf1fe846a7148e1f3f + source_hash: ae5c51e89541e3dd48646afb86a49eea21b778d816f8edb7c4b35e93b62bb64f source_path: tools/subagents.md workflow: 15 --- -Sub-agents — це фонові виконання agent, породжені з наявного виконання agent. Вони працюють у власній сесії (`agent::subagent:`) і після завершення **повідомляють** про свій результат назад у канал чату запитувача. Кожне виконання sub-agent відстежується як [фонове завдання](/uk/automation/tasks). +Підагенти — це фонові запуски агентів, створені з наявного запуску агента. Вони працюють у власному сеансі (`agent::subagent:`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен запуск підагента відстежується як [фонове завдання](/uk/automation/tasks). -## Slash-команда +## Команда зі скісною рискою -Використовуйте `/subagents`, щоб переглядати або керувати виконаннями sub-agent для **поточної сесії**: +Використовуйте `/subagents`, щоб переглядати або керувати запусками підагентів для **поточного сеансу**: - `/subagents list` - `/subagents kill ` @@ -28,9 +28,9 @@ Sub-agents — це фонові виконання agent, породжені з - `/subagents steer ` - `/subagents spawn [--model ] [--thinking ]` -Елементи керування прив’язкою до потоку: +Керування прив’язкою до потоку: -Ці команди працюють у каналах, які підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче. +Ці команди працюють у каналах, які підтримують постійні прив’язки до потоків. Див. **Канали з підтримкою потоків** нижче. - `/focus ` - `/unfocus` @@ -38,149 +38,149 @@ Sub-agents — це фонові виконання agent, породжені з - `/session idle ` - `/session max-age ` -`/subagents info` показує метадані виконання (стан, часові мітки, ID сесії, шлях до транскрипту, очищення). +`/subagents info` показує метадані запуску (статус, часові позначки, ідентифікатор сеансу, шлях до транскрипту, очищення). Використовуйте `sessions_history` для обмеженого, відфільтрованого з погляду безпеки перегляду історії; перевіряйте -шлях до транскрипту на диску, коли вам потрібен повний сирий транскрипт. +шлях до транскрипту на диску, коли вам потрібен необроблений повний транскрипт. ### Поведінка spawn -`/subagents spawn` запускає фоновий sub-agent як команду користувача, а не як внутрішню relay-операцію, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли виконання завершується. +`/subagents spawn` запускає фоновий підагент як команду користувача, а не внутрішнє переспрямування, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли запуск завершується. -- Команда spawn є неблокувальною; вона одразу повертає ID виконання. -- Після завершення sub-agent повідомляє зведення/результат назад у канал чату запитувача. -- Доставка завершення ґрунтується на push-механізмі. Після запуску не опитуйте `/subagents list`, +- Команда spawn не блокує виконання; вона відразу повертає ідентифікатор запуску. +- Після завершення підагент повідомляє стислий підсумок/результат назад у чат-канал запитувача. +- Доставка завершення є push-орієнтованою. Після запуску не опитуйте `/subagents list`, `sessions_list` або `sessions_history` у циклі лише для того, щоб дочекатися - завершення; перевіряйте стан лише за потреби для налагодження або втручання. -- Після завершення OpenClaw у режимі best-effort закриває відстежувані вкладки/процеси браузера, відкриті цією сесією sub-agent, перш ніж продовжиться потік очищення після повідомлення. -- Для ручних spawn доставка є стійкою: + завершення; перевіряйте статус лише за потреби для налагодження або втручання. +- Після завершення OpenClaw за можливості закриває відстежувані вкладки браузера/процеси, відкриті цим сеансом підагента, перш ніж продовжиться потік очищення повідомлення. +- Для ручних запусків доставка є стійкою: - OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем ідемпотентності. - - Якщо пряма доставка не вдається, він переходить до резервної маршрутизації через чергу. - - Якщо маршрутизація через чергу все ще недоступна, повідомлення про завершення повторюється з короткою експоненційною затримкою перед остаточною відмовою. -- Доставка завершення зберігає розв’язаний маршрут запитувача: - - маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні - - якщо джерело завершення надає лише канал, OpenClaw заповнює відсутню ціль/акаунт із розв’язаного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала -- Передача завершення до сесії запитувача — це внутрішній контекст середовища виконання, згенерований під час виконання (а не текст, створений користувачем), і він включає: - - `Result` (останній видимий текст відповіді `assistant`, або, інакше, санітизований останній текст tool/toolResult; невдалі завершені виконання не використовують повторно захоплений текст відповіді) + - Якщо пряма доставка не вдається, він переходить до маршрутизації через чергу. + - Якщо маршрутизація через чергу також недоступна, сповіщення повторюється з короткою експоненційною затримкою перед остаточною відмовою. +- Доставка завершення зберігає визначений маршрут запитувача: + - маршрути завершення, прив’язані до потоку або до розмови, мають пріоритет, коли доступні + - якщо джерело завершення надає лише канал, OpenClaw заповнює відсутню ціль/обліковий запис із визначеного маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала +- Передача завершення до сеансу запитувача — це внутрішній контекст, згенерований середовищем виконання (а не текст, написаний користувачем), і він містить: + - `Result` (останній видимий текст відповіді `assistant`, інакше санітизований останній текст tool/toolResult; невдалі термінальні запуски не використовують повторно захоплений текст відповіді) - `Status` (`completed successfully` / `failed` / `timed out` / `unknown`) - - стиснуту статистику runtime/token - - інструкцію доставки, яка наказує agent запитувача переписати це у звичайному голосі assistant (а не пересилати сирі внутрішні метадані) -- `--model` і `--thinking` перевизначають типові значення для цього конкретного виконання. -- Використовуйте `info`/`log`, щоб переглянути деталі та вивід після завершення. -- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сесій, прив’язаних до потоку, використовуйте `sessions_spawn` з `thread: true` і `mode: "session"`. -- Для ACP harness sessions (Claude Code, Gemini CLI, OpenCode або явно Codex ACP/acpx) використовуйте `sessions_spawn` з `runtime: "acp"`, коли інструмент рекламує це runtime, і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model) під час налагодження завершень або циклів agent-to-agent. Коли Plugin `codex` увімкнено, для керування чатом/потоком Codex слід віддавати перевагу `/codex ...` замість ACP, якщо користувач явно не просить ACP/acpx. OpenClaw приховує `runtime: "acp"`, доки ACP не ввімкнено, запитувач не працює в sandbox і не завантажено backend Plugin, як-от `acpx`. `runtime: "acp"` очікує зовнішній ACP harness id або запис `agents.list[]` з `runtime.type="acp"`; використовуйте типове runtime sub-agent для звичайних agent конфігурації OpenClaw з `agents_list`. + - компактну статистику середовища виконання/токенів + - інструкцію з доставки, яка повідомляє агенту запитувача переписати текст звичайним голосом асистента (а не пересилати необроблені внутрішні метадані) +- `--model` і `--thinking` перевизначають параметри за замовчуванням для цього конкретного запуску. +- Використовуйте `info`/`log`, щоб перевіряти деталі та вивід після завершення. +- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сеансів, прив’язаних до потоку, використовуйте `sessions_spawn` із `thread: true` і `mode: "session"`. +- Для сеансів обв’язки ACP (Claude Code, Gemini CLI, OpenCode або явно Codex ACP/acpx) використовуйте `sessions_spawn` із `runtime: "acp"`, коли інструмент оголошує це середовище виконання, і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model) під час налагодження завершень або циклів агент-до-агента. Коли увімкнено Plugin `codex`, для керування чатом/потоком Codex слід віддавати перевагу `/codex ...` замість ACP, якщо лише користувач явно не просить ACP/acpx. OpenClaw приховує `runtime: "acp"`, доки ACP не увімкнено, запитувач не перебуває в sandbox, і не завантажено backend Plugin, такий як `acpx`. `runtime: "acp"` очікує зовнішній ідентифікатор обв’язки ACP або запис `agents.list[]` із `runtime.type="acp"`; використовуйте стандартне середовище виконання підагента для звичайних агентів конфігурації OpenClaw з `agents_list`. Основні цілі: -- Розпаралелювати роботу типу "дослідження / довге завдання / повільний інструмент", не блокуючи основне виконання. -- За замовчуванням зберігати ізоляцію sub-agent (розділення сесій + необов’язковий sandboxing). -- Зробити поверхню інструмента стійкою до неправильного використання: sub-agents **не** отримують інструменти сесій за замовчуванням. +- Розпаралелювати роботу типу «дослідження / довге завдання / повільний інструмент» без блокування основного запуску. +- За замовчуванням зберігати ізоляцію підагентів (розділення сеансів + необов’язковий sandboxing). +- Зробити поверхню інструментів стійкою до неправильного використання: підагенти **не** отримують інструменти сеансу за замовчуванням. - Підтримувати налаштовувану глибину вкладеності для шаблонів оркестрації. -Примітка про вартість: кожен sub-agent за замовчуванням має **власний** контекст і використання токенів. Для важких або -повторюваних завдань встановіть для sub-agents дешевшу модель, а основний agent залиште на +Примітка щодо вартості: кожен підагент за замовчуванням має **власний** контекст і власне використання токенів. Для важких або +повторюваних завдань установіть для підагентів дешевшу модель, а основного агента залиште на якіснішій моделі. Це можна налаштувати через `agents.defaults.subagents.model` або через -перевизначення для окремого agent. Коли дочірньому процесу справді потрібен поточний транскрипт запитувача, agent може запросити -`context: "fork"` для цього одного spawn. +перевизначення для окремого агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запросити +`context: "fork"` для саме цього запуску. ## Режими контексту -Нативні sub-agents запускаються ізольовано, якщо тільки викликач явно не просить зробити fork -поточного транскрипту. +Власні підагенти запускаються ізольовано, якщо викликач явно не попросить відгалузити +поточний транскрипт. -| Режим | Коли його використовувати | Поведінка | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `isolated` | Нове дослідження, незалежна реалізація, повільна робота інструментів або будь-що, що можна коротко описати в тексті завдання | Створює чистий дочірній транскрипт. Це типове значення і воно знижує використання токенів. | -| `fork` | Робота, яка залежить від поточної розмови, попередніх результатів інструментів або тонких інструкцій, уже наявних у транскрипті запитувача | Відгалужує транскрипт запитувача в дочірню сесію перед запуском дочірнього процесу. | +| Режим | Коли його використовувати | Поведінка | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| `isolated` | Нове дослідження, незалежна реалізація, робота з повільним інструментом або будь-що, що можна стисло описати в тексті завдання | Створює чистий дочірній транскрипт. Це типово і зменшує використання токенів. | +| `fork` | Робота, що залежить від поточної розмови, попередніх результатів інструментів або нюансованих інструкцій, уже присутніх у транскрипті запитувача | Відгалужує транскрипт запитувача в дочірній сеанс до початку роботи дочірнього сеансу. | -Використовуйте `fork` ощадливо. Це для делегування, чутливого до контексту, а не заміна -чіткого формулювання завдання. +Використовуйте `fork` економно. Він призначений для делегування, чутливого до контексту, а не як заміна +написанню чіткого запиту завдання. ## Інструмент Використовуйте `sessions_spawn`: -- Запускає виконання sub-agent (`deliver: false`, глобальна смуга: `subagent`) -- Потім виконує крок повідомлення і публікує відповідь-повідомлення назад у канал чату запитувача -- Типова модель: успадковується від викликача, якщо ви не встановили `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для окремого agent); явне значення `sessions_spawn.model` усе одно має пріоритет. -- Типовий рівень thinking: успадковується від викликача, якщо ви не встановили `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для окремого agent); явне значення `sessions_spawn.thinking` усе одно має пріоритет. -- Типовий тайм-аут виконання: якщо `sessions_spawn.runTimeoutSeconds` не вказано, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його задано; інакше використовується `0` (без тайм-ауту). +- Запускає підагент (`deliver: false`, глобальна смуга: `subagent`) +- Потім виконує крок сповіщення та публікує відповідь-сповіщення в чат-канал запитувача +- Модель за замовчуванням: успадковується від викликача, якщо ви не задасте `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для окремого агента); явне `sessions_spawn.model` усе одно має пріоритет. +- Рівень thinking за замовчуванням: успадковується від викликача, якщо ви не задасте `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для окремого агента); явне `sessions_spawn.thinking` усе одно має пріоритет. +- Типовий час очікування запуску: якщо `sessions_spawn.runTimeoutSeconds` пропущено, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його задано; інакше використовується `0` (без тайм-ауту). Параметри інструмента: - `task` (обов’язково) - `label?` (необов’язково) -- `agentId?` (необов’язково; запуск під іншим ID agent, якщо дозволено) -- `runtime?` (`subagent|acp`, типово `subagent`; `acp` призначено лише для зовнішніх ACP harness, таких як `claude`, `gemini`, `opencode`, або явно запитаного Codex ACP/acpx, або для записів `agents.list[]`, у яких `runtime.type` має значення `acp`) -- `model?` (необов’язково; перевизначає модель sub-agent; некоректні значення пропускаються, і sub-agent запускається на типовій моделі з попередженням у результаті інструмента) -- `thinking?` (необов’язково; перевизначає рівень thinking для виконання sub-agent) -- `runTimeoutSeconds?` (типово — `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`; якщо встановлено, виконання sub-agent примусово переривається через N секунд) -- `thread?` (типово `false`; коли `true`, запитує прив’язку до потоку каналу для цієї сесії sub-agent) +- `agentId?` (необов’язково; запуск під іншим ідентифікатором агента, якщо це дозволено) +- `runtime?` (`subagent|acp`, типово `subagent`; `acp` призначений лише для зовнішніх ACP-обв’язок, таких як `claude`, `droid`, `gemini`, `opencode` або явно запитаний Codex ACP/acpx, або для записів `agents.list[]`, у яких `runtime.type` дорівнює `acp`) +- `model?` (необов’язково; перевизначає модель підагента; недійсні значення пропускаються, і підагент запускається на типовій моделі з попередженням у результаті інструмента) +- `thinking?` (необов’язково; перевизначає рівень thinking для запуску підагента) +- `runTimeoutSeconds?` (типово `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`; якщо задано, запуск підагента переривається через N секунд) +- `thread?` (типово `false`; якщо `true`, запитує прив’язку потоку каналу для цього сеансу підагента) - `mode?` (`run|session`) - - типове значення — `run` - - якщо `thread: true` і `mode` не вказано, типовим стає `session` - - `mode: "session"` вимагає `thread: true` + - типово `run` + - якщо `thread: true` і `mode` не задано, типовим стає `session` + - `mode: "session"` потребує `thread: true` - `cleanup?` (`delete|keep`, типово `keep`) -- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє spawn, якщо цільове дочірнє runtime не працює в sandbox) -- `context?` (`isolated|fork`, типово `isolated`; лише для нативних sub-agent) - - `isolated` створює чистий дочірній транскрипт і є типовим значенням. - - `fork` відгалужує поточний транскрипт запитувача в дочірню сесію, щоб дочірній процес почав із тим самим контекстом розмови. - - Використовуйте `fork`, лише коли дочірньому процесу потрібен поточний транскрипт. Для локалізованої роботи не вказуйте `context`. -- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із породженого виконання. +- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє запуск, якщо цільове дочірнє середовище виконання не працює в sandbox) +- `context?` (`isolated|fork`, типово `isolated`; лише для власних підагентів) + - `isolated` створює чистий дочірній транскрипт і є типовим режимом. + - `fork` відгалужує поточний транскрипт запитувача в дочірній сеанс, тож дочірній сеанс починає з того самого контексту розмови. + - Використовуйте `fork` лише тоді, коли дочірньому агенту потрібен поточний транскрипт. Для обмеженої за обсягом роботи не задавайте `context`. +- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного сеансу. -## Сесії, прив’язані до потоку +## Сеанси, прив’язані до потоку -Коли прив’язки до потоків увімкнено для каналу, sub-agent може залишатися прив’язаним до потоку, щоб наступні повідомлення користувача в цьому потоці й далі маршрутизувалися до тієї самої сесії sub-agent. +Коли для каналу ввімкнено прив’язки до потоків, підагент може залишатися прив’язаним до потоку, щоб подальші повідомлення користувача в цьому потоці й надалі маршрутизувалися до того самого сеансу підагента. ### Канали з підтримкою потоків -- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії subagent, прив’язані до потоку (`sessions_spawn` з `thread: true`), ручне керування потоками (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` та `channels.discord.threadBindings.spawnSubagentSessions`. +- Discord (наразі єдиний підтримуваний канал): підтримує постійні сеанси підагентів, прив’язані до потоку (`sessions_spawn` із `thread: true`), ручне керування потоками (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`), а також ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` і `channels.discord.threadBindings.spawnSubagentSessions`. -Короткий сценарій: +Швидкий процес: -1. Запустіть через `sessions_spawn` з `thread: true` (і, за бажанням, `mode: "session"`). -2. OpenClaw створює потік або прив’язує його до цільової сесії в активному каналі. -3. Відповіді та наступні повідомлення в цьому потоці маршрутизуються до прив’язаної сесії. -4. Використовуйте `/session idle`, щоб переглядати/оновлювати автоматичне відв’язування за неактивністю, і `/session max-age`, щоб керувати жорстким лімітом. -5. Використовуйте `/unfocus`, щоб вручну від’єднати. +1. Запустіть через `sessions_spawn`, використовуючи `thread: true` (і за бажанням `mode: "session"`). +2. OpenClaw створює потік або прив’язує його до цілі цього сеансу в активному каналі. +3. Відповіді та подальші повідомлення в цьому потоці маршрутизуються до прив’язаного сеансу. +4. Використовуйте `/session idle`, щоб переглянути/оновити автоматичне зняття фокуса через неактивність, і `/session max-age`, щоб керувати жорстким лімітом. +5. Використовуйте `/unfocus`, щоб від’єднати вручну. Ручні елементи керування: -- `/focus ` прив’язує поточний потік (або створює його) до цільової сесії/sub-agent. +- `/focus ` прив’язує поточний потік (або створює його) до цілі підагента/сеансу. - `/unfocus` видаляє прив’язку для поточного прив’язаного потоку. -- `/agents` перелічує активні виконання та стан прив’язки (`thread:` або `unbound`). -- `/session idle` і `/session max-age` працюють лише для сфокусованих прив’язаних потоків. +- `/agents` показує активні запуски та стан прив’язки (`thread:` або `unbound`). +- `/session idle` і `/session max-age` працюють лише для прив’язаних потоків у фокусі. Перемикачі конфігурації: -- Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` -- Перевизначення для каналу та ключі автоматичної прив’язки під час spawn залежать від адаптера. Див. **Канали з підтримкою потоків** вище. +- Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` +- Перевизначення каналу та ключі автоматичної прив’язки під час запуску залежать від адаптера. Див. **Канали з підтримкою потоків** вище. -Див. [Configuration Reference](/uk/gateway/configuration-reference) і [Slash commands](/uk/tools/slash-commands), щоб отримати актуальні відомості про адаптери. +Поточні відомості про адаптери див. у [довіднику з конфігурації](/uk/gateway/configuration-reference) та [командах зі скісною рискою](/uk/tools/slash-commands). -Список дозволених значень: +Список дозволених: -- `agents.list[].subagents.allowAgents`: список ID agent, на які можна націлюватися через `agentId` (`["*"]` дозволяє будь-який). Типово: лише agent запитувача. -- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових agent, який використовується, коли agent запитувача не задає власний `subagents.allowAgents`. -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: коли значення true, блокують виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю). Типово: false. +- `agents.list[].subagents.allowAgents`: список ідентифікаторів агентів, на які можна націлюватися через `agentId` (`["*"]` — дозволити будь-який). Типово: лише агент запитувача. +- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових агентів, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`. +- Захист успадкування sandbox: якщо сеанс запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: якщо true, блокують виклики `sessions_spawn`, у яких не задано `agentId` (примушує до явного вибору профілю). Типово: false. Виявлення: -- Використовуйте `agents_list`, щоб побачити, які ID agent наразі дозволені для `sessions_spawn`. Відповідь містить ефективну модель кожного переліченого agent і вбудовані метадані runtime, щоб викликачі могли розрізняти PI, сервер застосунку Codex та інші налаштовані нативні runtime. +- Використовуйте `agents_list`, щоб побачити, які ідентифікатори агентів зараз дозволені для `sessions_spawn`. Відповідь містить ефективну модель кожного переліченого агента та вбудовані метадані середовища виконання, щоб викликачі могли розрізняти PI, сервер застосунку Codex та інші налаштовані власні середовища виконання. -Автоархівація: +Автоархівування: -- Сесії Sub-agent автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60). -- Архівація використовує `sessions.delete` і перейменовує транскрипт у `*.deleted.` (та сама папка). -- `cleanup: "delete"` архівує одразу після повідомлення про завершення (транскрипт усе одно зберігається через перейменування). -- Автоархівація працює в режимі best-effort; очікувані таймери губляться, якщо gateway перезапускається. -- `runTimeoutSeconds` **не** виконує автоархівацію; він лише зупиняє виконання. Сесія залишається до автоархівації. -- Автоархівація однаково застосовується до сесій глибини 1 і глибини 2. -- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються в режимі best-effort після завершення виконання, навіть якщо запис транскрипту/сесії зберігається. +- Сеанси підагентів автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60). +- Архівація використовує `sessions.delete` і перейменовує транскрипт на `*.deleted.` (у тій самій папці). +- `cleanup: "delete"` архівує одразу після сповіщення (транскрипт усе одно зберігається через перейменування). +- Автоархівація виконується за можливості; відкладені таймери втрачаються, якщо Gateway перезапускається. +- `runTimeoutSeconds` **не** виконує автоархівацію; він лише зупиняє запуск. Сеанс залишається до автоархівації. +- Автоархівація однаково застосовується до сеансів глибини 1 і глибини 2. +- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються за можливості, коли запуск завершується, навіть якщо запис транскрипту/сеансу збережено. -## Вкладені sub-agents +## Вкладені підагенти -Типово sub-agents не можуть породжувати власні sub-agents (`maxSpawnDepth: 1`). Ви можете увімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: main → sub-agent-оркестратор → sub-sub-agents-воркери. +За замовчуванням підагенти не можуть створювати власних підагентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, установивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: main → підагент-оркестратор → дочірні підагенти-воркери. ### Як увімкнути @@ -189,10 +189,10 @@ Sub-agents — це фонові виконання agent, породжені з agents: { defaults: { subagents: { - maxSpawnDepth: 2, // дозволити sub-agents породжувати дочірні процеси (типово: 1) - maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх процесів на сесію agent (типово: 5) - maxConcurrent: 8, // глобальне обмеження паралельності для lane (типово: 8) - runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, якщо не вказано (0 = без тайм-ауту) + maxSpawnDepth: 2, // дозволити підагентам створювати дочірні агенти (типово: 1) + maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх агентів на сеанс агента (типово: 5) + maxConcurrent: 8, // глобальне обмеження паралельності для смуги (типово: 8) + runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, якщо параметр пропущено (0 = без тайм-ауту) }, }, }, @@ -201,132 +201,133 @@ Sub-agents — це фонові виконання agent, породжені з ### Рівні глибини -| Глибина | Форма ключа сесії | Роль | Може породжувати? | -| ------- | ------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | Основний agent | Завжди | -| 1 | `agent::subagent:` | Sub-agent (оркестратор, якщо дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | Sub-sub-agent (кінцевий воркер) | Ніколи | +| Глибина | Форма ключа сеансу | Роль | Може створювати дочірні? | +| ------- | -------------------------------------------- | --------------------------------------------- | ----------------------------- | +| 0 | `agent::main` | Основний агент | Завжди | +| 1 | `agent::subagent:` | Підагент (оркестратор, якщо дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | Дочірній підагент-воркер (leaf worker) | Ніколи | -### Ланцюжок повідомлень про завершення +### Ланцюг сповіщення -Результати повертаються вгору по ланцюжку: +Результати підіймаються вгору по ланцюгу: -1. Воркер depth-2 завершується → повідомляє свого батька (оркестратор depth-1) -2. Оркестратор depth-1 отримує повідомлення, синтезує результати, завершується → повідомляє main -3. Основний agent отримує повідомлення й доставляє його користувачу +1. Воркер глибини 2 завершується → сповіщає свого батьківського агента (оркестратор глибини 1) +2. Оркестратор глибини 1 отримує сповіщення, синтезує результати, завершується → сповіщає main +3. Основний агент отримує сповіщення і доставляє його користувачу -Кожен рівень бачить лише повідомлення від своїх прямих дочірніх процесів. +Кожен рівень бачить сповіщення лише від своїх безпосередніх дочірніх агентів. Операційні рекомендації: -- Запускайте дочірню роботу один раз і чекайте на події завершення, а не будуйте цикли +- Запускайте дочірню роботу один раз і чекайте на події завершення замість побудови циклів опитування навколо `sessions_list`, `sessions_history`, `/subagents list` або - команд `exec` зі `sleep`. -- `sessions_list` і `/subagents list` зберігають зв’язки дочірніх сесій - сфокусованими на активній роботі: активні дочірні процеси залишаються прив’язаними, завершені залишаються видимими - протягом короткого недавнього вікна, а застарілі посилання на дочірні процеси лише зі сховища ігноруються після завершення їхнього - вікна свіжості. Це запобігає відродженню примарних дочірніх процесів після перезапуску через старі метадані `spawnedBy` / `parentSessionKey`. -- Якщо подія завершення дочірнього процесу надходить після того, як ви вже надіслали фінальну відповідь, - правильною подальшою дією є точний тихий токен `NO_REPLY` / `no_reply`. + команд сну `exec`. +- `sessions_list` і `/subagents list` зберігають зв’язки дочірніх сеансів + сфокусованими на активній роботі: активні дочірні сеанси залишаються прив’язаними, завершені сеанси лишаються видимими протягом + короткого недавнього вікна, а застарілі посилання на дочірні сеанси, що є лише в сховищі, ігноруються після + завершення їхнього вікна свіжості. Це запобігає тому, щоб старі метадані `spawnedBy` / `parentSessionKey` + відроджували примарні дочірні сеанси після перезапуску. +- Якщо подія завершення дочірнього агента надходить після того, як ви вже надіслали фінальну відповідь, + правильним наступним кроком є точний беззвучний токен `NO_REPLY` / `no_reply`. ### Політика інструментів за глибиною -- Роль і область керування записуються в метадані сесії під час spawn. Це не дає плоским або відновленим ключам сесій випадково повернути привілеї оркестратора. -- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми процесами. Інші інструменти сесій/системи залишаються забороненими. -- **Глибина 1 (листок, коли `maxSpawnDepth == 1`)**: без інструментів сесій (поточна типова поведінка). -- **Глибина 2 (кінцевий воркер)**: без інструментів сесій — `sessions_spawn` завжди заборонено на глибині 2. Не може породжувати наступних дочірніх процесів. +- Роль і область керування записуються в метадані сеансу під час spawn. Це запобігає тому, щоб пласкі або відновлені ключі сеансів випадково знову отримали привілеї оркестратора. +- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми агентами. Інші інструменти сеансу/системи лишаються забороненими. +- **Глибина 1 (leaf, коли `maxSpawnDepth == 1`)**: без інструментів сеансу (поточна типова поведінка). +- **Глибина 2 (leaf worker)**: без інструментів сеансу — `sessions_spawn` на глибині 2 завжди заборонений. Не може створювати подальших дочірніх агентів. -### Ліміт spawn для кожного agent +### Ліміт spawn для кожного агента -Кожна сесія agent (на будь-якій глибині) може мати щонайбільше `maxChildrenPerAgent` (типово: 5) активних дочірніх процесів одночасно. Це запобігає неконтрольованому розгалуженню від одного оркестратора. +Кожен сеанс агента (на будь-якій глибині) може мати не більше `maxChildrenPerAgent` (типово: 5) активних дочірніх агентів одночасно. Це запобігає неконтрольованому розгалуженню від одного оркестратора. ### Каскадна зупинка -Зупинка оркестратора depth-1 автоматично зупиняє всіх його дочірніх процесів depth-2: +Зупинка оркестратора глибини 1 автоматично зупиняє всіх його дочірніх агентів глибини 2: -- `/stop` в основному чаті зупиняє всіх agent depth-1 і каскадно зупиняє їхніх дочірніх процесів depth-2. -- `/subagents kill ` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх процесів. -- `/subagents kill all` зупиняє всіх sub-agents для запитувача і виконує каскадну зупинку. +- `/stop` в основному чаті зупиняє всіх агентів глибини 1 і каскадно зупиняє їхніх дочірніх агентів глибини 2. +- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів. +- `/subagents kill all` зупиняє всіх підагентів для запитувача і виконує каскадну зупинку. ## Автентифікація -Автентифікація sub-agent розв’язується за **ID agent**, а не за типом сесії: +Автентифікація підагента визначається за **ідентифікатором агента**, а не за типом сеансу: -- Ключ сесії sub-agent — `agent::subagent:`. -- Сховище автентифікації завантажується з `agentDir` цього agent. -- Профілі автентифікації основного agent додаються як **резервний варіант**; профілі agent мають пріоритет над профілями main у разі конфліктів. +- Ключ сеансу підагента: `agent::subagent:`. +- Сховище автентифікації завантажується з `agentDir` цього агента. +- Профілі автентифікації основного агента об’єднуються як **резервний варіант**; у разі конфліктів профілі агента мають пріоритет над профілями main. -Примітка: об’єднання є адитивним, тому профілі main завжди доступні як резервні. Повністю ізольована автентифікація для кожного agent поки не підтримується. +Примітка: об’єднання є додатковим, тому профілі main завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки що не підтримується. -## Повідомлення про завершення +## Сповіщення -Sub-agents звітують назад через крок повідомлення про завершення: +Підагенти звітують назад через крок сповіщення: -- Крок повідомлення про завершення виконується всередині сесії sub-agent (а не сесії запитувача). -- Якщо sub-agent відповідає рівно `ANNOUNCE_SKIP`, нічого не публікується. -- Якщо останній текст assistant є точним тихим токеном `NO_REPLY` / `no_reply`, - вивід повідомлення про завершення пригнічується, навіть якщо раніше був видимий прогрес. +- Крок сповіщення виконується всередині сеансу підагента (а не сеансу запитувача). +- Якщо підагент відповідає рівно `ANNOUNCE_SKIP`, нічого не публікується. +- Якщо останній текст assistant є точним беззвучним токеном `NO_REPLY` / `no_reply`, + вивід сповіщення пригнічується, навіть якщо раніше був видимий прогрес. - Інакше доставка залежить від глибини запитувача: - - сесії запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`) - - вкладені сесії subagent запитувача отримують внутрішнє подальше вливання (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх процесів усередині сесії - - якщо вкладеної сесії subagent запитувача більше немає, OpenClaw переходить до резервного варіанта з використанням запитувача цієї сесії, коли це можливо -- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку розв’язує будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля channel-target зі збереженого маршруту сесії запитувача. Це утримує завершення в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал. -- Агрегація завершень дочірніх процесів обмежується поточним виконанням запитувача під час побудови вкладених результатів завершення, що запобігає витіканню застарілих виводів дочірніх процесів із попередніх запусків у поточне повідомлення. -- Відповіді-повідомлення про завершення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів. -- Контекст повідомлення про завершення нормалізується до стабільного внутрішнього блоку подій: + - сеанси запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`) + - вкладені сеанси запитувача-підагента отримують внутрішню ін’єкцію подальшого виклику (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сеансу + - якщо вкладений сеанс запитувача-підагента більше не існує, OpenClaw за можливості виконує fallback до запитувача цього сеансу +- Для сеансів запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля channel-target із збереженого маршруту сеансу запитувача. Це дозволяє завершенням лишатися в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал. +- Агрегація завершень дочірніх агентів обмежується поточним запуском запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх агентів із попередніх запусків у поточне сповіщення. +- Відповіді сповіщень зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів. +- Контекст сповіщення нормалізується до стабільного внутрішнього блоку подій: - джерело (`subagent` або `cron`) - - ключ/ID дочірньої сесії - - тип повідомлення + мітка завдання - - рядок стану, похідний від результату runtime (`success`, `error`, `timeout` або `unknown`) - - вміст результату, вибраний з останнього видимого тексту assistant, інакше — санітизований останній текст tool/toolResult; завершені невдалі виконання повідомляють про стан невдачі без відтворення захопленого тексту відповіді - - подальша інструкція, яка описує, коли відповідати, а коли зберігати мовчання -- `Status` не виводиться з виводу моделі; він походить із сигналів результату runtime. -- У разі тайм-ауту, якщо дочірній процес встиг лише виконати виклики інструментів, повідомлення про завершення може згорнути цю історію в коротке зведення часткового прогресу замість відтворення сирого виводу інструментів. + - ключ/ідентифікатор дочірнього сеансу + - тип сповіщення + мітка завдання + - рядок статусу, виведений із результату середовища виконання (`success`, `error`, `timeout` або `unknown`) + - вміст результату, вибраний з останнього видимого тексту assistant, інакше санітизований останній текст tool/toolResult; невдалі термінальні запуски повідомляють про статус невдачі без повторного відтворення захопленого тексту відповіді + - інструкцію подальшої дії, яка описує, коли відповідати, а коли залишатися безмовним +- `Status` не виводиться з результату моделі; він походить із сигналів результату середовища виконання. +- У разі тайм-ауту, якщо дочірній агент встиг дійти лише до викликів інструментів, сповіщення може згорнути цю історію в короткий підсумок часткового прогресу замість відтворення необробленого виводу інструментів. -Payload повідомлень про завершення включають рядок статистики в кінці (навіть якщо вони загорнуті): +Навантаження сповіщення містять рядок статистики в кінці (навіть якщо обгорнуті): -- Runtime (наприклад, `runtime 5m12s`) -- Використання токенів (input/output/total) -- Оцінена вартість, коли налаштовано ціни моделі (`models.providers.*.models[].cost`) -- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний agent міг отримати history через `sessions_history` або перевірити файл на диску) -- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача мають бути переписані звичайним голосом assistant. +- Час виконання середовища (наприклад, `runtime 5m12s`) +- Використання токенів (вхідні/вихідні/загалом) +- Орієнтовну вартість, коли налаштовано ціни моделей (`models.providers.*.models[].cost`) +- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний агент міг отримати історію через `sessions_history` або перевірити файл на диску) +- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайним голосом асистента. `sessions_history` — безпечніший шлях оркестрації: -- спочатку нормалізується пригадування assistant: +- історія assistant спочатку нормалізується: - теги thinking видаляються - блоки каркаса `` / `` видаляються - - блоки plain-text XML payload викликів інструментів, такі як `...`, + - блоки XML-навантаження викликів інструментів у звичайному тексті, такі як `...`, `...`, `...` і - `...`, видаляються, включно з обрізаними - payload, які так і не закриваються коректно - - понижені каркаси викликів інструментів/результатів та маркери історичного контексту видаляються - - витоки токенів керування моделі, як-от `<|assistant|>`, інші ASCII - токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються + `...`, видаляються, включно з усіченими + навантаженнями, які так і не закрилися коректно + - деградований каркас викликів/результатів інструментів та маркери історичного контексту видаляються + - витеклі токени керування моделлю, такі як `<|assistant|>`, інші ASCII- + токени `<|...|>`, а також повноширинні варіанти `<｜...｜>`, видаляються - некоректний XML викликів інструментів MiniMax видаляється - текст, схожий на облікові дані/токени, редагується -- довгі блоки можуть обрізатися -- дуже великі історії можуть втрачати старіші рядки або замінювати надмірно великий рядок на +- довгі блоки можуть усікатися +- у дуже великих історіях старіші рядки можуть відкидатися або надто великий рядок може бути замінений на `[sessions_history omitted: message too large]` -- перевірка сирого транскрипту на диску є резервним варіантом, коли вам потрібен повний побайтовий транскрипт +- перевірка необробленого транскрипту на диску — це fallback, коли вам потрібен повний побайтовий транскрипт -## Політика інструментів (інструменти sub-agent) +## Політика інструментів (інструменти підагентів) -Sub-agents спочатку використовують той самий профіль і pipeline політики інструментів, що й батьківський або цільовий -agent. Після цього OpenClaw застосовує шар обмежень sub-agent. +Підагенти спочатку використовують той самий профіль і конвеєр політики інструментів, що й батьківський або цільовий +агент. Після цього OpenClaw застосовує шар обмежень для підагентів. -Без обмежувального `tools.profile` sub-agents отримують **усі інструменти, крім інструментів сесій** -та системних інструментів: +Без обмежувального `tools.profile` підагенти отримують **усі інструменти, крім інструментів +сеансу** та системних інструментів: - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -`sessions_history` і тут залишається обмеженим, санітизованим поданням history; це не -сирий дамп транскрипту. +Тут `sessions_history` також лишається обмеженим, санітизованим поданням історії; це не +дамп необробленого транскрипту. -Коли `maxSpawnDepth >= 2`, sub-agents-оркестратори depth-1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми процесами. +Коли `maxSpawnDepth >= 2`, підагенти-оркестратори глибини 1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми агентами. Перевизначення через конфігурацію: @@ -344,7 +345,7 @@ agent. Після цього OpenClaw застосовує шар обмежен tools: { // заборона має пріоритет deny: ["gateway", "cron"], - // якщо задано allow, він стає списком лише дозволених (deny усе одно має пріоритет) + // якщо задано allow, він стає фільтром "дозволено лише це" (deny усе одно має пріоритет) // allow: ["read", "exec", "process"] }, }, @@ -352,10 +353,10 @@ agent. Після цього OpenClaw застосовує шар обмежен } ``` -`tools.subagents.tools.allow` — це фінальний фільтр лише дозволених значень. Він може звузити -вже розв’язаний набір інструментів, але не може повернути інструмент, -видалений `tools.profile`. Наприклад, `tools.profile: "coding"` включає -`web_search`/`web_fetch`, але не інструмент `browser`. Щоб дозволити sub-agents +`tools.subagents.tools.allow` — це фінальний фільтр "дозволено лише це". Він може звузити +вже визначений набір інструментів, але не може повернути інструмент, +вилучений `tools.profile`. Наприклад, `tools.profile: "coding"` включає +`web_search`/`web_fetch`, але не інструмент `browser`. Щоб дозволити підагентам із профілем coding використовувати автоматизацію браузера, додайте browser на етапі профілю: ```json5 @@ -367,51 +368,52 @@ agent. Після цього OpenClaw застосовує шар обмежен } ``` -Використовуйте `agents.list[].tools.alsoAllow: ["browser"]`, коли автоматизацію браузера -має отримати лише один agent. +Використовуйте `agents.list[].tools.alsoAllow: ["browser"]`, коли лише один агент +має отримати автоматизацію браузера. ## Паралельність -Sub-agents використовують окрему in-process queue lane: +Підагенти використовують окрему внутрішньопроцесну смугу черги: -- Назва lane: `subagent` +- Назва смуги: `subagent` - Паралельність: `agents.defaults.subagents.maxConcurrent` (типово `8`) ## Живучість і відновлення -OpenClaw не розглядає відсутність `endedAt` як постійний доказ того, що sub-agent -усе ще активний. Незавершені виконання, старіші за вікно застарілого виконання, перестають рахуватися як -активні/очікувані в `/subagents list`, підсумках стану, блокуванні завершення -нащадків і перевірках паралельності для кожної сесії. +OpenClaw не вважає відсутність `endedAt` постійним доказом того, що підагент +досі активний. Незавершені запуски, старші за вікно застарілого запуску, перестають враховуватися як +активні/очікувані в `/subagents list`, зведеннях статусу, контролі завершення нащадків +і перевірках паралельності для кожного сеансу. -Після перезапуску gateway застарілі відновлені незавершені виконання відсікаються, якщо їхня -дочірня сесія не позначена як `abortedLastRun: true`. Ці дочірні сесії, перервані під час перезапуску, -залишаються відновлюваними через потік відновлення осиротілих sub-agent, який -надсилає синтетичне повідомлення про відновлення перед очищенням маркера переривання. +Після перезапуску Gateway застарілі відновлені незавершені запуски відкидаються, якщо їхній +дочірній сеанс не позначено `abortedLastRun: true`. Такі дочірні сеанси, перервані через перезапуск, +можна відновити через потік відновлення осиротілих підагентів, який +надсилає синтетичне повідомлення відновлення перед очищенням маркера переривання. -Якщо spawn sub-agent завершується помилкою Gateway `PAIRING_REQUIRED` / `scope-upgrade`, -перевірте викликач RPC перед редагуванням стану pairing. Внутрішня координація `sessions_spawn` +Якщо spawn підагента завершується помилкою Gateway `PAIRING_REQUIRED` / `scope-upgrade`, +перевірте RPC-викликач, перш ніж редагувати стан pairing. Внутрішня координація `sessions_spawn` має підключатися як `client.id: "gateway-client"` з -`client.mode: "backend"` через пряму local loopback shared-token/password автентифікацію; цей -шлях не залежить від базового рівня scope спареного пристрою CLI. Віддалені викликачі, -явний `deviceIdentity`, явні шляхи токенів пристроїв і клієнти browser/node, як і раніше, потребують звичайного схвалення пристрою для підвищення scope. +`client.mode: "backend"` через пряму автентифікацію local loopback shared-token/password; цей +шлях не залежить від базового рівня області дії парного пристрою CLI. Віддалені викликачі, +явний `deviceIdentity`, явні шляхи device-token, а також клієнти browser/node і далі потребують +звичайного схвалення пристрою для розширення області дії. ## Зупинка -- Надсилання `/stop` у чаті запитувача перериває сесію запитувача і зупиняє всі активні виконання sub-agent, породжені з неї, з каскадним поширенням на вкладених дочірніх процесів. -- `/subagents kill ` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх процесів. +- Надсилання `/stop` у чаті запитувача перериває сеанс запитувача і зупиняє всі активні запуски підагентів, створені з нього, з каскадною зупинкою вкладених дочірніх агентів. +- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів. ## Обмеження -- Повідомлення sub-agent про завершення працює в режимі **best-effort**. Якщо gateway перезапускається, очікувана робота з "повідомлення назад" втрачається. -- Sub-agents усе ще спільно використовують ресурси того самого процесу gateway; розглядайте `maxConcurrent` як запобіжний клапан. -- `sessions_spawn` завжди є неблокувальним: він одразу повертає `{ status: "accepted", runId, childSessionKey }`. -- Контекст sub-agent інжектує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`). -- Максимальна глибина вкладеності — 5 (`maxSpawnDepth` у діапазоні 1–5). Для більшості сценаріїв рекомендовано depth 2. -- `maxChildrenPerAgent` обмежує кількість активних дочірніх процесів на сесію (типово: 5, діапазон: 1–20). +- Сповіщення підагента виконується **за можливості**. Якщо Gateway перезапускається, незавершена робота з «повідомлення назад» втрачається. +- Підагенти все ще спільно використовують ресурси того самого процесу Gateway; розглядайте `maxConcurrent` як запобіжний клапан. +- `sessions_spawn` завжди не блокує виконання: він одразу повертає `{ status: "accepted", runId, childSessionKey }`. +- Контекст підагента ін’єктує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`). +- Максимальна глибина вкладеності — 5 (`maxSpawnDepth` у діапазоні: 1–5). Для більшості сценаріїв використання рекомендовано глибину 2. +- `maxChildrenPerAgent` обмежує кількість активних дочірніх агентів на сеанс (типово: 5, діапазон: 1–20). ## Пов’язане - [ACP agents](/uk/tools/acp-agents) -- [Інструменти sandbox для багатьох agent](/uk/tools/multi-agent-sandbox-tools) -- [Надсилання agent](/uk/tools/agent-send) +- [Інструменти sandbox для мультиагентів](/uk/tools/multi-agent-sandbox-tools) +- [Надсилання агента](/uk/tools/agent-send) diff --git a/docs/uk/web/control-ui.md b/docs/uk/web/control-ui.md index 957b550e7..cb74e38b7 100644 --- a/docs/uk/web/control-ui.md +++ b/docs/uk/web/control-ui.md @@ -1,55 +1,56 @@ --- read_when: - - Вам потрібно керувати Gateway з браузера - - Вам потрібен доступ через Tailnet без SSH-тунелів -summary: Control UI на основі браузера для Gateway (чат, вузли, конфігурація) -title: Control UI + - Ви хочете керувати Gateway з браузера + - Вам потрібен доступ Tailnet без SSH-тунелів +summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація) +title: Інтерфейс керування x-i18n: - generated_at: "2026-04-25T17:34:48Z" + generated_at: "2026-04-26T00:40:12Z" model: gpt-5.4 provider: openai - source_hash: 29d77ae57e32abe5ad25b2c22986d9d8e67f7ac183af06e8ffc4907ae4e6c0bc + source_hash: 6b8b92415bedb9102a42cf5a01ec3872318d713a8de1d95d3931a9d199d237ee source_path: web/control-ui.md workflow: 15 --- -Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway: +Інтерфейс керування — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway: -- типово: `http://:18789/` -- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад `/openclaw`) +- за замовчуванням: `http://:18789/` +- необов’язковий префікс: установіть `gateway.controlUi.basePath` (наприклад, `/openclaw`) -Він працює **безпосередньо з WebSocket Gateway** на тому самому порту. +Він звертається **безпосередньо до WebSocket Gateway** на тому самому порту. ## Швидке відкриття (локально) -Якщо Gateway працює на тому самому комп’ютері, відкрийте: +Якщо Gateway запущено на тому самому комп’ютері, відкрийте: - [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (або [http://localhost:18789/](http://localhost:18789/)) Якщо сторінка не завантажується, спочатку запустіть Gateway: `openclaw gateway`. -Auth передається під час handshake WebSocket через: +Автентифікація передається під час handshake WebSocket через: - `connect.params.auth.token` - `connect.params.auth.password` -- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true` -- заголовки ідентичності trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"` +- заголовки ідентифікації Tailscale Serve, коли `gateway.auth.allowTailscale: true` +- заголовки ідентифікації trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"` -Панель налаштувань dashboard зберігає токен для поточної сесії вкладки браузера -та вибраної URL-адреси gateway; паролі не зберігаються. Під час онбордингу зазвичай -генерується токен gateway для auth зі спільним секретом при першому підключенні, але -auth паролем також працює, коли `gateway.auth.mode` має значення `"password"`. +Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера +та вибрану URL-адресу gateway; паролі не зберігаються. Onboarding зазвичай +генерує токен gateway для автентифікації зі спільним секретом під час першого +підключення, але автентифікація паролем також працює, коли +`gateway.auth.mode` має значення `"password"`. -## Парування пристрою (перше підключення) +## Сполучення пристрою (перше підключення) Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway -вимагає **одноразового підтвердження парування** — навіть якщо ви перебуваєте в тому самому Tailnet -з `gateway.auth.allowTailscale: true`. Це захід безпеки для запобігання -несанкціонованому доступу. +вимагає **одноразове схвалення сполучення** — навіть якщо ви перебуваєте в тій +самій Tailnet із `gateway.auth.allowTailscale: true`. Це захід безпеки для +запобігання несанкціонованому доступу. **Що ви побачите:** "disconnected (1008): pairing required" -**Щоб підтвердити пристрій:** +**Щоб схвалити пристрій:** ```bash # List pending requests @@ -59,175 +60,191 @@ openclaw devices list openclaw devices approve ``` -Якщо браузер повторює спробу парування зі зміненими даними auth (role/scopes/public -key), попередній очікуваний запит замінюється, і створюється новий `requestId`. -Перед підтвердженням повторно виконайте `openclaw devices list`. +Якщо браузер повторно намагається виконати сполучення зі зміненими даними +автентифікації (роль/області доступу/публічний ключ), попередній запит у +стані очікування замінюється, і створюється новий `requestId`. Перед +схваленням знову виконайте `openclaw devices list`. -Якщо браузер уже спаровано і ви змінюєте його з доступу лише для читання на -доступ для запису/admin, це розглядається як підвищення підтвердження, а не як тихе -повторне підключення. OpenClaw зберігає старе підтвердження активним, блокує ширше повторне підключення -і просить вас явно підтвердити новий набір scope. +Якщо браузер уже сполучено, а ви змінюєте його доступ із читання на +запис/адміністрування, це вважається підвищенням рівня схвалення, а не тихим +повторним підключенням. OpenClaw залишає попереднє схвалення активним, +блокує повторне підключення з ширшими правами та просить вас явно схвалити +новий набір областей доступу. -Після підтвердження пристрій запам’ятовується й не потребуватиме повторного підтвердження, -доки ви не відкличете його через `openclaw devices revoke --device --role `. Див. -[Devices CLI](/uk/cli/devices) щодо ротації токенів і відкликання. +Після схвалення пристрій запам’ятовується й не потребуватиме повторного +схвалення, доки ви не відкличете його за допомогою +`openclaw devices revoke --device --role `. Див. +[CLI Devices](/uk/cli/devices) щодо ротації токенів і відкликання. **Примітки:** -- Прямі локальні з’єднання браузера через loopback (`127.0.0.1` / `localhost`) - підтверджуються автоматично. -- Підключення браузера через Tailnet і LAN усе одно потребують явного підтвердження, навіть якщо - вони походять з тієї самої машини. -- Кожен профіль браузера генерує унікальний id пристрою, тому перехід на інший браузер або - очищення даних браузера потребуватиме повторного парування. +- Прямі локальні loopback-підключення браузера (`127.0.0.1` / `localhost`) + схвалюються автоматично. +- Підключення браузера через Tailnet і LAN однаково вимагають явного + схвалення, навіть якщо вони виконуються з тієї самої машини. +- Кожен профіль браузера генерує унікальний ідентифікатор пристрою, тому + перемикання браузерів або очищення даних браузера вимагатиме повторного + сполучення. ## Особиста ідентичність (локально в браузері) -Control UI підтримує особисту ідентичність для кожного браузера (відображуване ім’я та -аватар), яка додається до вихідних повідомлень для атрибуції в спільних сесіях. Вона -зберігається в сховищі браузера, обмежена поточним профілем браузера і не -синхронізується з іншими пристроями та не зберігається на сервері понад звичайні метадані -авторства transcript у повідомленнях, які ви фактично надсилаєте. Очищення даних сайту або -перехід на інший браузер скидає її до порожнього значення. +Control UI підтримує індивідуальну для кожного браузера особисту ідентичність +(відображуване ім’я та аватар), яка додається до вихідних повідомлень для +атрибуції в спільних сесіях. Вона зберігається в сховищі браузера, +обмежується поточним профілем браузера й не синхронізується з іншими +пристроями та не зберігається на сервері поза звичайними метаданими авторства +в стенограмі для повідомлень, які ви фактично надсилаєте. Очищення даних +сайту або перемикання браузерів скидає її до порожнього стану. -Той самий браузерно-локальний підхід застосовується до перевизначення аватара помічника. -Завантажені аватари помічника накладаються на ідентичність, визначену gateway, лише в локальному -браузері і ніколи не проходять назад через `config.patch`. Спільне -поле конфігурації `ui.assistant.avatar` усе ще доступне для не-UI клієнтів, які записують це поле напряму -(наприклад, scripted gateway або custom dashboards). +Той самий локальний для браузера підхід застосовується до перевизначення +аватара помічника. Завантажені аватари помічника накладаються на ідентичність, +визначену gateway, лише в локальному браузері й ніколи не передаються назад +через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` +залишається доступним для клієнтів поза UI, які записують це поле напряму +(наприклад, для gateway-скриптів або власних дашбордів). -## Endpoint конфігурації runtime +## Кінцева точка конфігурації середовища виконання -Control UI отримує свої налаштування runtime з -`/__openclaw/control-ui-config.json`. Доступ до цього endpoint захищено тим самим -auth gateway, що й до решти HTTP-поверхні: неавтентифіковані браузери не можуть -його отримати, а успішне отримання потребує або вже валідного токена/пароля gateway, -ідентичності Tailscale Serve, або ідентичності trusted-proxy. +Control UI отримує свої налаштування середовища виконання з +`/__openclaw/control-ui-config.json`. Доступ до цієї кінцевої точки +захищається тією самою автентифікацією gateway, що й решта HTTP-поверхні: +неавтентифіковані браузери не можуть її отримати, а успішне отримання +вимагає або вже дійсного токена/пароля gateway, або ідентифікації Tailscale +Serve, або ідентичності trusted-proxy. ## Підтримка мов -Control UI може локалізувати себе при першому завантаженні на основі локалі вашого браузера. -Щоб перевизначити це пізніше, відкрийте **Overview -> Gateway Access -> Language**. Засіб вибору -локалі знаходиться в картці Gateway Access, а не в розділі Appearance. +Control UI може локалізуватися під час першого завантаження відповідно до +локалі вашого браузера. Щоб перевизначити її пізніше, відкрийте +**Overview -> Gateway Access -> Language**. Вибір локалі розміщено в картці +Gateway Access, а не в розділі Appearance. - Підтримувані локалі: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th` -- Переклади, відмінні від англійської, ліниво завантажуються в браузері. -- Вибрана локаль зберігається в сховищі браузера і повторно використовується при наступних відвідуваннях. +- Неанглійські переклади ліниво завантажуються в браузері. +- Вибрана локаль зберігається в сховищі браузера та повторно використовується + під час майбутніх відвідувань. - Відсутні ключі перекладу повертаються до англійської. -## Що він уміє (на сьогодні) +## Що він уміє (зараз) -- Чат із моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`) -- Спілкування з OpenAI Realtime безпосередньо з браузера через WebRTC. Gateway - випускає короткоживучий клієнтський секрет Realtime через `talk.realtime.session`; браузер - надсилає аудіо з мікрофона безпосередньо до OpenAI і передає виклики інструмента - `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої - моделі OpenClaw. -- Потокові виклики інструментів + картки live-виводу інструментів у Chat (події агента) -- Канали: статус, вхід через QR і конфігурація для кожного каналу для вбудованих, bundled та зовнішніх plugin-каналів (`channels.status`, `web.login.*`, `config.patch`) -- Інстанси: список присутності + оновлення (`system-presence`) -- Сесії: список + перевизначення model/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`) -- Dreams: статус dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`) +- Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`) +- Напряму взаємодіяти з OpenAI Realtime з браузера через WebRTC. Gateway + випускає короткоживучий клієнтський секрет Realtime за допомогою + `talk.realtime.session`; браузер надсилає аудіо з мікрофона безпосередньо до + OpenAI і ретранслює виклики інструмента `openclaw_agent_consult` назад через + `chat.send` для більшої налаштованої моделі OpenClaw. +- Потоково передавати виклики інструментів + картки живого виводу інструментів у Chat (події агента) +- Канали: статус вбудованих, bundled і зовнішніх каналів Plugin, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`) +- Екземпляри: список присутності + оновлення (`system-presence`) +- Сесії: список + перевизначення моделі/мислення/швидкого режиму/докладного режиму/трасування/міркування для кожної сесії (`sessions.list`, `sessions.patch`) +- Dreams: статус Dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`) - Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`) -- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`) -- Node: список + caps (`node.list`) -- Підтвердження exec: редагування allowlist gateway або node + політика запиту для `exec host=gateway/node` (`exec.approvals.*`) +- Skills: статус, увімкнення/вимкнення, установлення, оновлення API-ключів (`skills.*`) +- Вузли: список + можливості (`node.list`) +- Схвалення exec: редагування allowlist gateway або Node + політика запиту для `exec host=gateway/node` (`exec.approvals.*`) - Конфігурація: перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`) -- Конфігурація: застосування + перезапуск з валідацією (`config.apply`) і пробудження останньої активної сесії -- Записи конфігурації містять захист base-hash, щоб запобігти перезапису одночасних змін -- Записи конфігурації (`config.set`/`config.apply`/`config.patch`) також попередньо перевіряють активне розв’язання SecretRef для ref у надісланому payload конфігурації; нерозв’язані активні надіслані ref відхиляються до запису +- Конфігурація: застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії +- Записи конфігурації включають захист base-hash, щоб запобігти перезапису конкурентних змін +- Записи конфігурації (`config.set`/`config.apply`/`config.patch`) також попередньо перевіряють активне розв’язання SecretRef для посилань у надісланому корисному навантаженні конфігурації; нерозв’язані активні надіслані посилання відхиляються до запису - Схема конфігурації + рендеринг форми (`config.schema` / `config.schema.lookup`, - включно з полями `title` / `description`, відповідними підказками UI, короткими - зведеннями безпосередніх дочірніх елементів, метаданими docs у вузлах nested object/wildcard/array/composition, - а також схемами plugin + channel, коли вони доступні); редактор Raw JSON - доступний лише тоді, коли snapshot має безпечний raw round-trip -- Якщо snapshot не може безпечно пройти raw round-trip, Control UI примусово вмикає режим Form і вимикає режим Raw для цього snapshot -- У редакторі Raw JSON команда "Reset to saved" зберігає форму, створену в raw-режимі (форматування, коментарі, макет `$include`), замість повторного рендерингу сплощеного snapshot, тож зовнішні зміни зберігаються після скидання, коли snapshot може безпечно пройти round-trip -- Структуровані значення об’єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок -- Налагодження: snapshot status/health/models + журнал подій + ручні виклики RPC (`status`, `health`, `models.list`) -- Журнали: live-tail журнальних файлів gateway із фільтрацією/експортом (`logs.tail`) + включно з полями `title` / `description`, відповідними підказками UI, + короткими зведеннями безпосередніх дочірніх елементів, метаданими + документації на вкладених вузлах object/wildcard/array/composition, + а також схемами Plugin і каналів, коли доступні); редактор Raw JSON + доступний лише тоді, коли знімок має безпечне пряме round-trip-перетворення +- Якщо знімок не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає режим Form і вимикає режим Raw для цього знімка +- У редакторі Raw JSON пункт "Reset to saved" зберігає форму, створену в raw-режимі (форматування, коментарі, розташування `$include`), замість повторного рендерингу сплощеного знімка, тож зовнішні редагування зберігаються після скидання, коли знімок може безпечно виконати round-trip +- Значення об’єктів Structured SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок +- Налагодження: знімки status/health/models + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`) +- Логи: live tail лог-файлів gateway із фільтрацією/експортом (`logs.tail`) - Оновлення: запуск оновлення пакета/git + перезапуск (`update.run`) зі звітом про перезапуск Примітки до панелі завдань Cron: -- Для ізольованих завдань типове доставлення — announce summary. Ви можете переключити на none, якщо хочете запускати лише внутрішні виконання. -- Поля channel/target з’являються, коли вибрано announce. -- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, заданим як валідна URL-адреса webhook HTTP(S). -- Для завдань main-session доступні режими доставлення webhook і none. -- Розширені елементи редагування включають delete-after-run, clear agent override, варіанти cron exact/stagger, - перевизначення model/thinking для агента та перемикачі best-effort delivery. -- Валідація форми вбудована, з помилками на рівні полів; невалідні значення вимикають кнопку збереження, доки їх не буде виправлено. -- Задайте `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його не задано, webhook надсилається без заголовка auth. -- Застарілий fallback: збережені застарілі завдання з `notify: true` усе ще можуть використовувати `cron.webhook`, доки не буде виконано міграцію. +- Для ізольованих завдань доставка за замовчуванням — оголошення підсумку. Ви + можете перемкнути на none, якщо хочете запускати лише внутрішні виконання. +- Поля каналу/цілі з’являються, коли вибрано announce. +- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, + встановленим на дійсну URL-адресу Webhook HTTP(S). +- Для завдань main-session доступні режими доставки webhook і none. +- Розширені елементи редагування включають видалення після запуску, очищення + перевизначення агента, параметри точної/зі зміщенням Cron, + перевизначення моделі/мислення агента та перемикачі доставки best-effort. +- Валідація форми виконується вбудовано з помилками на рівні полів; некоректні + значення вимикають кнопку збереження, доки їх не буде виправлено. +- Установіть `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його + не вказано, Webhook надсилається без заголовка автентифікації. +- Застарілий резервний варіант: збережені застарілі завдання з `notify: true` + усе ще можуть використовувати `cron.webhook`, доки їх не буде мігровано. -## Поведінка чату +## Поведінка Chat -- `chat.send` є **неблокувальним**: він одразу підтверджує запит через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`. +- `chat.send` є **неблокувальним**: він негайно підтверджує запит через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`. - Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення. -- Відповіді `chat.history` обмежуються за розміром для безпеки UI. Коли записи transcript надто великі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надто великі повідомлення заповнювачем (`[chat.history omitted: message too large]`). -- Зображення помічника/згенеровані зображення зберігаються як керовані посилання на медіа й віддаються назад через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від збереження сирих base64-payload зображень у відповіді історії чату. -- `chat.history` також прибирає візуальні inline-теги директив із видимого тексту помічника (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), XML-payload звичайного тексту для викликів інструментів (зокрема `...`, `...`, `...`, `...` і обрізані блоки викликів інструментів), а також витіклі ASCII/повноширинні токени керування моделлю, і пропускає записи помічника, у яких увесь видимий текст — це лише точний тихий токен `NO_REPLY` / `no_reply`. -- Під час активного надсилання та фінального оновлення історії вигляд чату зберігає локальні оптимістичні повідомлення користувача/помічника видимими, якщо `chat.history` тимчасово повертає старіший snapshot; канонічний transcript замінює ці локальні повідомлення, щойно історія Gateway наздоганяє стан. -- `chat.inject` додає примітку помічника до transcript сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставлення каналом). -- Засоби вибору моделі та thinking у заголовку чату одразу змінюють активну сесію через `sessions.patch`; це стійкі перевизначення сесії, а не параметри надсилання лише на один хід. -- Коли свіжі звіти Gateway про використання сесії показують високий тиск контексту, в області композитора чату з’являється повідомлення про контекст, а на рекомендованих рівнях Compaction — кнопка compact, яка запускає звичайний шлях Compaction сесії. Застарілі snapshot токенів приховуються, доки Gateway знову не повідомить про свіже використання. -- Режим Talk використовує зареєстрованого постачальника голосу realtime, який підтримує браузерні сесії WebRTC. Налаштуйте OpenAI через `talk.provider: "openai"` разом із `talk.providers.openai.apiKey`, або повторно використайте конфігурацію постачальника realtime для Voice Call. Браузер ніколи не отримує стандартний API-ключ OpenAI; він отримує лише ефемерний клієнтський секрет Realtime. Голос Google Live realtime підтримується для Voice Call на бекенді та мостів Google Meet, але ще не для цього браузерного шляху WebRTC. Prompt сесії Realtime збирається Gateway; `talk.realtime.session` не приймає перевизначення інструкцій від викликача. -- У композиторі Chat елемент керування Talk — це кнопка хвиль поруч із кнопкою диктування мікрофоном. Коли Talk запускається, у рядку стану композитора відображається `Connecting Talk...`, потім `Talk live`, поки підключено аудіо, або `Asking OpenClaw...`, поки виклик інструмента realtime консультується з налаштованою більшою моделлю через `chat.send`. +- Відповіді `chat.history` мають обмеження за розміром для безпеки UI. Коли записи стенограми надто великі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`). +- Зображення помічника/згенеровані зображення зберігаються як керовані посилання на медіа й повертаються через автентифіковані URL-адреси медіа Gateway, тому повторні завантаження не залежать від того, чи зберігаються сирі корисні навантаження зображень base64 у відповіді історії чату. +- `chat.history` також прибирає з видимого тексту помічника вбудовані теги директив, призначені лише для відображення (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), XML-корисні навантаження викликів інструментів у форматі простого тексту (зокрема `...`, `...`, `...`, `...` і обрізані блоки викликів інструментів), а також витеклі ASCII/повноширинні токени керування моделлю, і пропускає записи помічника, увесь видимий текст яких складається лише з точного тихого токена `NO_REPLY` / `no_reply`. +- Під час активного надсилання та остаточного оновлення історії у вікні чату залишаються видимими локальні оптимістичні повідомлення користувача/помічника, якщо `chat.history` тимчасово повертає старіший знімок; канонічна стенограма замінює ці локальні повідомлення, щойно історія Gateway наздожене. +- `chat.inject` додає примітку помічника до стенограми сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставки в канал). +- Перемикачі моделі та мислення в заголовку чату негайно змінюють активну сесію через `sessions.patch`; це постійні перевизначення сесії, а не параметри надсилання лише для одного ходу. +- Коли свіжі звіти Gateway про використання сесії показують високий тиск контексту, область редактора чату показує сповіщення про контекст і, на рекомендованих рівнях Compaction, кнопку compact, яка запускає звичайний шлях Compaction сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить про свіже використання. +- Режим Talk використовує зареєстрованого постачальника голосу realtime, який підтримує браузерні сеанси WebRTC. Налаштуйте OpenAI за допомогою `talk.provider: "openai"` плюс `talk.providers.openai.apiKey`, або повторно використайте конфігурацію realtime-постачальника Voice Call. Браузер ніколи не отримує стандартний API-ключ OpenAI; він отримує лише ефемерний клієнтський секрет Realtime. Голос realtime Google Live підтримується для серверного Voice Call і мостів Google Meet, але ще не для цього браузерного шляху WebRTC. Промпт сесії Realtime збирається Gateway; `talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем. +- У редакторі Chat елемент керування Talk — це кнопка з хвилями поруч із кнопкою диктування з мікрофона. Коли Talk запускається, у рядку стану редактора відображається `Connecting Talk...`, потім `Talk live`, поки аудіо підключене, або `Asking OpenClaw...`, поки виклик realtime-інструмента звертається до налаштованої більшої моделі OpenClaw через `chat.send`. - Зупинка: - Натисніть **Stop** (викликає `chat.abort`) - - Поки виконання активне, звичайні подальші повідомлення ставляться в чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це продовження в поточний хід. + - Поки запуск активний, звичайні наступні повідомлення ставляться в чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це наступне повідомлення в поточний хід. - Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза смугою - - `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних виконань цієї сесії -- Часткове збереження після переривання: - - Коли виконання переривається, частковий текст помічника все одно може відображатися в UI - - Gateway зберігає частковий текст помічника в історії transcript, якщо існує буферизований вивід - - Збережені записи містять метадані переривання, щоб споживачі transcript могли відрізняти часткові результати переривання від звичайного завершеного виводу + - `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків цієї сесії +- Збереження часткових даних після переривання: + - Коли запуск перервано, частковий текст помічника все одно може відображатися в UI + - Gateway зберігає частковий текст помічника від перерваних запусків в історію стенограми, якщо є буферизований вивід + - Збережені записи містять метадані переривання, щоб споживачі стенограми могли відрізнити часткові дані після переривання від звичайного завершеного виводу ## Установлення PWA і web push Control UI постачається з `manifest.webmanifest` і service worker, тому -сучасні браузери можуть установлювати його як окремий PWA. Web Push дає змогу +сучасні браузери можуть встановлювати його як окремий PWA. Web Push дає змогу Gateway пробуджувати встановлений PWA сповіщеннями, навіть коли вкладка або вікно браузера не відкриті. -| Поверхня | Що вона робить | -| ---------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він стає доступним. | -| `ui/public/sw.js` | Service worker, який обробляє події `push` і натискання сповіщень. | -| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID для підписування payload Web Push. | -| `push/web-push-subscriptions.json` | Збережені endpoint підписок браузера. | +| Поверхня | Що вона робить | +| ----------------------------------------------------- | ------------------------------------------------------------------ | +| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він стає доступним. | +| `ui/public/sw.js` | Service worker, який обробляє події `push` і натискання на сповіщення. | +| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID, яка використовується для підпису корисних навантажень Web Push. | +| `push/web-push-subscriptions.json` | Збережені кінцеві точки підписок браузера. | -Перевизначайте пару ключів VAPID через env vars у процесі Gateway, коли -потрібно зафіксувати ключі (для розгортань із кількома хостами, ротації секретів або -тестів): +Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, якщо +ви хочете зафіксувати ключі (для розгортань на кількох хостах, ротації +секретів або тестів): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT` (типово `mailto:openclaw@localhost`) -Control UI використовує ці методи Gateway з обмеженням за scope, щоб реєструвати і -тестувати підписки браузера: +Control UI використовує ці методи Gateway з обмеженням за областями доступу для +реєстрації та тестування підписок браузера: - `push.web.vapidPublicKey` — отримує активний публічний ключ VAPID. - `push.web.subscribe` — реєструє `endpoint` плюс `keys.p256dh`/`keys.auth`. -- `push.web.unsubscribe` — видаляє зареєстрований endpoint. -- `push.web.test` — надсилає тестове сповіщення до підписки викликача. +- `push.web.unsubscribe` — видаляє зареєстровану кінцеву точку. +- `push.web.test` — надсилає тестове сповіщення на підписку викликача. -Web Push не залежить від шляху iOS APNS relay -(див. [Configuration](/uk/gateway/configuration) щодо push через relay) -і від наявного методу `push.test`, які призначені для нативного парування мобільних пристроїв. +Web Push не залежить від шляху ретрансляції iOS APNS +(див. [Configuration](/uk/gateway/configuration) щодо push із підтримкою relay) і +наявного методу `push.test`, які націлені на сполучення з рідними мобільними застосунками. -## Розміщувані embed +## Вбудовування хостованого вмісту -Повідомлення помічника можуть відображати вбудований розміщений вебвміст через shortcode `[embed ...]`. -Політика sandbox для iframe керується через +Повідомлення помічника можуть вбудовувати хостований вебвміст безпосередньо за +допомогою shortcode `[embed ...]`. Політика sandbox iframe контролюється через `gateway.controlUi.embedSandbox`: -- `strict`: вимикає виконання скриптів у розміщуваних embed -- `scripts`: дозволяє інтерактивні embed зі збереженням ізоляції origin; це +- `strict`: вимикає виконання скриптів усередині хостованих вбудовувань +- `scripts`: дозволяє інтерактивні вбудовування, зберігаючи ізоляцію origin; це типове значення, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів - `trusted`: додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту, - яким навмисно потрібні сильніші привілеї + яким навмисно потрібні розширені привілеї Приклад: @@ -242,18 +259,19 @@ Web Push не залежить від шляху iOS APNS relay ``` Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна -поведінка same-origin. Для більшості ігор та інтерактивних canvas, згенерованих агентом, `scripts` — -безпечніший вибір. +поведінка same-origin. Для більшості ігор і інтерактивних полотен, +згенерованих агентом, `scripts` є безпечнішим вибором. -Абсолютні зовнішні URL embed `http(s)` типово залишаються заблокованими. Якщо ви -навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, задайте +Абсолютні зовнішні URL-адреси вбудовування `http(s)` типово залишаються +заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` +завантажував сторонні сторінки, установіть `gateway.controlUi.allowExternalEmbedUrls: true`. -## Доступ через Tailnet (рекомендовано) +## Доступ Tailnet (рекомендовано) ### Інтегрований Tailscale Serve (бажано) -Тримайте Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS: +Залиште Gateway на loopback і дозвольте Tailscale Serve проксіювати його через HTTPS: ```bash openclaw gateway --tailscale serve @@ -263,22 +281,19 @@ openclaw gateway --tailscale serve - `https:///` (або ваш налаштований `gateway.controlUi.basePath`) -Типово запити Serve до Control UI/WebSocket можуть проходити auth через заголовки ідентичності Tailscale +Типово запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв’язуючи адресу `x-forwarded-for` через -`tailscale whois` і звіряючи її із заголовком, і приймає це лише тоді, коли -запит потрапляє на loopback із заголовками `x-forwarded-*` від Tailscale. Установіть -`gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані зі спільним секретом -навіть для трафіку Serve. Тоді використовуйте `gateway.auth.mode: "token"` або +`tailscale whois` і звіряючи її із заголовком, і приймає їх лише тоді, коли +запит потрапляє на loopback із заголовками Tailscale `x-forwarded-*`. Установіть +`gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані +зі спільним секретом навіть для трафіку Serve. Тоді використовуйте `gateway.auth.mode: "token"` або `"password"`. -Для цього асинхронного шляху ідентичності Serve невдалі спроби auth для тієї самої IP-адреси клієнта -й scope auth серіалізуються перед записами про обмеження частоти. Тому паралельні невдалі повторні спроби -з того самого браузера можуть показувати `retry later` у другому запиті -замість двох звичайних невідповідностей, що змагаються паралельно. -Auth Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості може -виконуватися недовірений локальний код, вимагайте auth токеном/паролем. +Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта +й тієї самої області автентифікації серіалізуються перед записами обмеження частоти. Тому паралельні хибні повторні спроби з того самого браузера можуть показувати `retry later` у другому запиті замість двох звичайних невідповідностей, що змагаються паралельно. +Автентифікація Serve без токена передбачає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем. -### Bind до tailnet + токен +### Прив’язування до tailnet + токен ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" @@ -293,14 +308,14 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ## Небезпечний HTTP -Якщо ви відкриваєте dashboard через звичайний HTTP (`http://` або `http://`), +Якщо ви відкриваєте дашборд через звичайний HTTP (`http://` або `http://`), браузер працює в **незахищеному контексті** й блокує WebCrypto. Типово OpenClaw **блокує** підключення Control UI без ідентичності пристрою. Задокументовані винятки: -- сумісність з незахищеним HTTP лише для localhost через `gateway.controlUi.allowInsecureAuth=true` -- успішний auth оператора в Control UI через `gateway.auth.mode: "trusted-proxy"` +- сумісність localhost-only для незахищеного HTTP з `gateway.controlUi.allowInsecureAuth=true` +- успішна автентифікація оператора Control UI через `gateway.auth.mode: "trusted-proxy"` - аварійний варіант `gateway.controlUi.dangerouslyDisableDeviceAuth=true` **Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкривайте UI локально: @@ -308,7 +323,7 @@ OpenClaw **блокує** підключення Control UI без іденти - `https:///` (Serve) - `http://127.0.0.1:18789/` (на хості gateway) -**Поведінка перемикача insecure-auth:** +**Поведінка перемикача allowInsecureAuth:** ```json5 { @@ -322,10 +337,10 @@ OpenClaw **блокує** підключення Control UI без іденти `allowInsecureAuth` — це лише локальний перемикач сумісності: -- Він дозволяє сесіям localhost у Control UI продовжуватися без ідентичності пристрою в +- Він дозволяє localhost-сеансам Control UI продовжуватися без ідентичності пристрою в незахищених контекстах HTTP. -- Він не обходить перевірки pairing. -- Він не послаблює вимоги до ідентичності пристрою для віддалених (не-localhost) підключень. +- Він не обходить перевірки сполучення. +- Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень. **Лише для аварійних випадків:** @@ -340,50 +355,50 @@ OpenClaw **блокує** підключення Control UI без іденти ``` `dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою в Control UI і є -серйозним погіршенням безпеки. Після аварійного використання швидко поверніть попереднє значення. +серйозним зниженням рівня безпеки. Швидко скасуйте цю зміну після аварійного використання. Примітка щодо trusted-proxy: -- успішний auth через trusted-proxy може допускати сесії **оператора** в Control UI без +- успішна автентифікація trusted-proxy може допускати **операторські** сеанси Control UI без ідентичності пристрою -- це **не** поширюється на сесії Control UI з роллю node -- reverse proxy на loopback того самого хоста все одно не задовольняють auth trusted-proxy; див. +- це **не** поширюється на сеанси Control UI з роллю Node +- reverse proxy loopback на тому самому хості все одно не задовольняють вимоги автентифікації trusted-proxy; див. [Trusted proxy auth](/uk/gateway/trusted-proxy-auth) -Рекомендації щодо налаштування HTTPS див. у [Tailscale](/uk/gateway/tailscale). +Див. [Tailscale](/uk/gateway/tailscale) щодо налаштування HTTPS. -## Content Security Policy +## Політика безпеки вмісту -Control UI постачається з жорсткою політикою `img-src`: дозволені лише ресурси **того самого origin**, URL `data:` і локально згенеровані URL `blob:`. Віддалені URL `http(s)` і відносні до протоколу URL зображень відхиляються браузером і не ініціюють мережеві запити. +Control UI постачається з жорсткою політикою `img-src`: дозволено лише ресурси **того самого походження**, URL-адреси `data:` і локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси з `http(s)` і відносні до протоколу URL-адреси зображень відхиляються браузером і не спричиняють мережевих запитів. Що це означає на практиці: -- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад `/avatars/`), як і раніше відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує і перетворює на локальні URL `blob:`. -- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для внутрішньопротокольних payload). -- Локальні URL `blob:`, створені Control UI, як і раніше відображаються. -- Віддалені URL аватарів, що надходять із метаданих каналів, прибираються в допоміжних засобах аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може примусити браузер оператора виконувати довільні віддалені запити зображень. +- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/`), усе одно відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує й перетворює на локальні URL-адреси `blob:`. +- Вбудовані URL-адреси `data:image/...` усе одно відображаються (це корисно для внутрішньопротокольних корисних навантажень). +- Локальні URL-адреси `blob:`, створені Control UI, усе одно відображаються. +- Віддалені URL-адреси аватарів, які надходять із метаданих каналів, відсікаються допоміжними функціями аватарів Control UI і замінюються вбудованим логотипом/значком, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити за зображеннями. -Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена і не налаштовується. +Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується. -## Auth маршруту аватарів +## Автентифікація маршруту аватара -Коли налаштовано auth gateway, endpoint аватарів у Control UI потребує того самого токена gateway, що й решта API: +Коли налаштовано автентифікацію gateway, кінцева точка аватара Control UI вимагає той самий токен gateway, що й решта API: - `GET /avatar/` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/?meta=1` повертає метадані аватара за тим самим правилом. -- Неавтентифіковані запити до обох маршрутів відхиляються (узгоджено з сусіднім маршрутом assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які в іншому захищені. -- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL `blob:`, тож зображення все одно відображається в dashboard. +- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (узгоджено з сусіднім маршрутом медіа помічника). Це не дає маршруту аватара розкривати ідентичність агента на хостах, які загалом захищені. +- Сам Control UI передає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, тому зображення все одно відображається в дашбордах. -Якщо ви вимкнете auth gateway (не рекомендовано на спільних хостах), маршрут аватарів також стане неавтентифікованим, узгоджено з рештою gateway. +Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, відповідно до решти gateway. ## Збирання UI -Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх командою: +Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх за допомогою: ```bash pnpm ui:build ``` -Необов’язковий абсолютний base (коли потрібні фіксовані URL ресурсів): +Необов’язкова абсолютна база (коли вам потрібні фіксовані URL-адреси ресурсів): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build @@ -395,22 +410,22 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build pnpm ui:dev ``` -Потім спрямуйте UI на URL WS вашого Gateway (наприклад `ws://127.0.0.1:18789`). +Потім укажіть для UI URL-адресу вашого Gateway WS (наприклад, `ws://127.0.0.1:18789`). ## Налагодження/тестування: dev server + віддалений Gateway -Control UI — це статичні файли; ціль WebSocket налаштовується і може -відрізнятися від HTTP origin. Це зручно, коли ви хочете локальний dev server Vite, -але Gateway працює деінде. +Control UI — це статичні файли; ціль WebSocket налаштовується й може +відрізнятися від HTTP-origin. Це зручно, коли ви хочете використовувати Vite +dev server локально, але Gateway працює деінде. 1. Запустіть dev server UI: `pnpm ui:dev` -2. Відкрийте URL на кшталт: +2. Відкрийте URL-адресу на кшталт: ```text http://localhost:5173/?gatewayUrl=ws://:18789 ``` -Необов’язковий одноразовий auth (за потреби): +Необов’язкова одноразова автентифікація (за потреби): ```text http://localhost:5173/?gatewayUrl=wss://:18789#token= @@ -418,20 +433,23 @@ http://localhost:5173/?gatewayUrl=wss://:18789#token=` і + `http://127.0.0.1:`, на основі фактичного runtime bind і порту, але для віддалених + browser-origin усе одно потрібні явні записи. +- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім суворо контрольованого + локального тестування. Це означає дозволити будь-який browser-origin, а не “збігатися з будь-яким хостом, який я + використовую.” - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає - режим fallback origin через заголовок Host, але це небезпечний режим безпеки. + режим резервного origin через заголовок Host, але це небезпечний режим безпеки. Приклад: @@ -445,11 +463,11 @@ http://localhost:5173/?gatewayUrl=wss://:18789#token=