openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 07:19:51 +00:00
parent 7e0cdec050
commit 2b5e291d90
26 changed files with 4180 additions and 4106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

223
docs/uk/automation/cron-jobs.md
View File

@ -6,22 +6,22 @@ read_when:
summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway
title: Заплановані завдання
x-i18n:
generated_at: "2026-04-21T06:32:46Z"
generated_at: "2026-04-23T07:10:49Z"
model: gpt-5.4
provider: openai
source_hash: ac08f67af43bc85a1713558899a220c935479620f1ef74aa76336259daac2828
source_hash: c9565b73efc151c991ee6a1029c887c35d8673736913ddc5cdcfae09a4652f86
source_path: automation/cron-jobs.md
workflow: 15
---
# Заплановані завдання (Cron)
Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у канал чату або до endpoint Webhook.
Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у чат-канал або на кінцеву точку Webhook.
## Швидкий старт
```bash
# Add a one-shot reminder
# Додати одноразове нагадування
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
@ -30,128 +30,109 @@ openclaw cron add \
--wake now \
--delete-after-run
# Check your jobs
# Перевірити свої завдання
openclaw cron list
openclaw cron show <job-id>
# See run history
# Переглянути історію запусків
openclaw cron runs --id <job-id>
```
## Як працює cron
- Cron працює **всередині** процесу Gateway (а не всередині моделі).
- Cron працює **всередині** процесу Gateway (не всередині моделі).
- Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не призводять до втрати розкладів.
- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте до gitignore.
- Після цього розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть вважати завдання новими, оскільки поля стану виконання тепер зберігаються в `jobs-state.json`.
- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте в gitignore.
- Після поділу старіші версії OpenClaw можуть читати `jobs.json`, але можуть вважати завдання новими, оскільки поля часу виконання тепер зберігаються в `jobs-state.json`.
- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks).
- Одноразові завдання (`--at`) типово автоматично видаляються після успішного виконання.
- Ізольовані запуски cron після завершення намагаються закрити відстежувані вкладки браузера/процеси для своєї сесії `cron:<jobId>`, щоб відокремлена автоматизація браузера не залишала осиротілі процеси.
- Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо
перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything
together` та подібні підказки) і жоден дочірній запуск субагента більше не
відповідає за фінальну відповідь, OpenClaw повторно надсилає запит один раз, щоб отримати фактичний
результат перед доставленням.
- Ізольовані запуски cron після завершення намагаються в режимі best-effort закрити відстежувані вкладки браузера/процеси для своєї сесії `cron:<jobId>`, щоб від’єднана автоматизація браузера не залишала сирітські процеси.
- Ізольовані запуски cron також захищають від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення стану (`on it`, `pulling everything together` та подібні підказки) і жоден дочірній запуск subagent більше не відповідає за фінальну відповідь, OpenClaw повторно формує запит один раз, щоб отримати фактичний результат перед доставкою.
<a id="maintenance"></a>
Узгодження завдань для cron належить до середовища виконання: активне завдання cron залишається активним, поки
середовище cron і далі відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує.
Щойно середовище виконання перестає володіти цим завданням і спливає 5-хвилинне вікно відстрочки, обслуговування може
позначити завдання як `lost`.
Узгодження завдань для cron належить до часу виконання: активне завдання cron залишається активним, доки середовище виконання cron усе ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує.
Щойно середовище виконання перестає володіти завданням і минає 5-хвилинне вікно очікування, обслуговування може позначити завдання як `lost`.
## Типи розкладу
## Типи розкладів
| Вид | Прапорець CLI | Опис |
| ------- | ------------- | --------------------------------------------------------- |
| `at` | `--at` | Одноразова позначка часу (ISO 8601 або відносна, наприклад `20m`) |
| `every` | `--every` | Фіксований інтервал |
| `cron` | `--cron` | Вираз cron із 5 або 6 полів з необов’язковим `--tz` |
| Вид | Прапорець CLI | Опис |
| ------- | ------------- | -------------------------------------------------------- |
| `at` | `--at` | Одноразова часова позначка (ISO 8601 або відносно, як `20m`) |
| `every` | `--every` | Фіксований інтервал |
| `cron` | `--cron` | 5-польовий або 6-польовий cron-вираз з необов’язковим `--tz` |
Позначки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним часом.
Часові позначки без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом.
Періодичні вирази на початок години автоматично розносяться в межах до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна.
Повторювані вирази на початок години автоматично зсуваються до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово встановити точний час, або `--stagger 30s` для явного вікна.
### День місяця і день тижня використовують логіку OR
### День місяця та день тижня використовують логіку OR
Вирази cron парсяться через [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner виконує збіг, якщо **будь-яке** з полів збігається, а не обидва. Це стандартна поведінка Vixie cron.
Cron-вирази парсяться за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner виконує збіг, коли **збігається будь-яке** з полів, а не обидва. Це стандартна поведінка Vixie cron.
```
# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual: "9 AM on every 15th, AND 9 AM on every Monday"
# Очікування: "9:00 15-го числа, лише якщо це понеділок"
# Фактично: "9:00 кожного 15-го числа І 9:00 кожного понеділка"
0 9 15 * 1
```
Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує типову OR-поведінку Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` у Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання.
Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує стандартну OR-поведінку Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` від Croner (`0 9 15 * +1`) або плануйте за одним полем, а інше перевіряйте в prompt чи команді вашого завдання.
## Стилі виконання
| Стиль | Значення `--session` | Виконується в | Найкраще підходить для |
| --------------- | -------------------- | ------------------------- | ----------------------------------- |
| Основна сесія | `main` | Наступний такт heartbeat | Нагадувань, системних подій |
| Ізольований | `isolated` | Виділена `cron:<jobId>` | Звітів, фонових завдань |
| Поточна сесія | `current` | Прив’язується під час створення | Періодичної роботи з урахуванням контексту |
| Користувацька сесія | `session:custom-id` | Постійна іменована сесія | Робочих процесів, що спираються на історію |
| Стиль | Значення `--session` | Запускається в | Найкраще підходить для |
| --------------- | -------------------- | ------------------------- | ------------------------------- |
| Основна сесія | `main` | Наступний хід heartbeat | Нагадування, системні події |
| Ізольований | `isolated` | Виділений `cron:<jobId>` | Звіти, фонові рутинні завдання |
| Поточна сесія | `current` | Прив’язується під час створення | Повторювана робота з урахуванням контексту |
| Користувацька сесія | `session:custom-id` | Постійна іменована сесія | Робочі процеси, що спираються на історію |
Завдання **основної сесії** ставлять системну подію в чергу та за потреби пробуджують heartbeat (`--wake now` або `--wake next-heartbeat`). **Ізольовані** завдання виконують окремий хід агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу реалізовувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки.
Завдання **основної сесії** ставлять у чергу системну подію й за потреби пробуджують heartbeat (`--wake now` або `--wake next-heartbeat`). **Ізольовані** завдання запускають окремий хід агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу реалізувати робочі процеси на кшталт щоденних стендапів, які спираються на попередні підсумки.
Для ізольованих завдань завершення виконання тепер включає найкращу спробу очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет.
Для ізольованих завдань завершення часу виконання тепер включає best-effort очищення браузера для цієї cron-сесії. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет.
Коли ізольовані запуски cron оркеструють субагентів, під час доставлення також
перевага надається фінальному результату дочірнього запуску, а не застарілому проміжному тексту батьківського.
Якщо дочірні запуски все ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського процесу, замість того щоб оголошувати його.
Ізольовані запуски cron також звільняють усі вбудовані екземпляри середовища виконання MCP, створені для цього завдання, через спільний шлях очищення часу виконання. Це відповідає тому, як клієнти MCP для основної сесії та користувацької сесії завершуються, тому ізольовані cron-завдання не залишають дочірні stdio-процеси або довготривалі з’єднання MCP між запусками.
Коли ізольовані запуски cron оркеструють subagent-и, доставка також надає перевагу фінальному результату нащадка перед застарілим проміжним текстом батьківського процесу. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його.
### Параметри payload для ізольованих завдань
- `--message`: текст prompt (обов’язковий для ізольованих)
- `--message`: текст prompt (обов’язковий для isolated)
- `--model` / `--thinking`: перевизначення моделі та рівня thinking
- `--light-context`: пропустити ін’єкцію bootstrap-файлів робочого простору
- `--light-context`: пропустити ін’єкцію файла bootstrap робочого простору
- `--tools exec,read`: обмежити, які інструменти може використовувати завдання
`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель
не дозволена, cron записує попередження в журнал і повертається до вибору моделі агента/типової моделі для цього завдання.
Налаштовані ланцюжки fallback, як і раніше, застосовуються, але звичайне перевизначення
моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби.
`--model` використовує вибрану дозволену модель для цього завдання. Якщо запитана модель не дозволена, cron записує попередження в журнал і натомість повертається до вибору моделі агента/типової моделі для завдання. Налаштовані ланцюжки fallback усе ще застосовуються, але просте перевизначення моделі без явного списку fallback для конкретного завдання більше не додає основну модель агента як приховану додаткову ціль повторної спроби.
Пріоритет вибору моделі для ізольованих завдань такий:
Пріоритет вибору моделі для ізольованих завдань:
1. Перевизначення моделі hook Gmail (коли запуск походить із Gmail і це перевизначення дозволене)
1. Перевизначення моделі з Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене)
2. `model` у payload конкретного завдання
3. Збережене перевизначення моделі сесії cron
4. Вибір моделі агента/типової моделі
Швидкий режим також дотримується визначеного активного вибору. Якщо вибрана конфігурація моделі
має `params.fastMode`, ізольований cron використовує його типово. Збережене перевизначення
`fastMode` сесії все одно має пріоритет над конфігурацією в будь-якому напрямку.
Режим fast mode також слідує за визначеним активним вибором. Якщо в конфігурації вибраної моделі є `params.fastMode`, ізольований cron використовує це типово. Збережене перевизначення сесії `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках.
Якщо ізольований запуск потрапляє на живе передавання керування під час перемикання моделі, cron повторює спробу з
перемкненим провайдером/моделлю та зберігає цей активний вибір перед повторною спробою. Коли
перемикання також несе новий профіль автентифікації, cron також зберігає це перевизначення профілю автентифікації.
Кількість повторних спроб обмежена: після початкової спроби та ще 2 повторних спроб через перемикання
cron переривається, а не зациклюється назавжди.
Якщо ізольований запуск натрапляє на передачу керування через live-перемикання моделі, cron повторює спробу з перемкненим provider/model і зберігає цей live-вибір перед повторною спробою. Якщо перемикання також містить новий профіль автентифікації, cron зберігає і це перевизначення профілю автентифікації. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб через перемикання cron перериває виконання замість нескінченного циклу.
## Доставлення і результат
## Доставка та вивід
| Режим | Що відбувається |
| ---------- | ------------------------------------------------------------------ |
| `announce` | Запасне доставлення фінального тексту до цілі, якщо агент не надіслав |
| `webhook` | POST payload завершеної події на URL |
| `none` | Немає запасного доставлення з боку runner |
| Режим | Що відбувається |
| --------- | ----------------------------------------------------------------- |
| `announce` | Резервно доставляє фінальний текст у ціль, якщо агент не надіслав |
| `webhook` | Надсилає payload події завершення на URL через POST |
| `none` | Без резервної доставки з боку виконавця |
Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставлення в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:<id>`, `user:<id>`).
Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:<id>`, `user:<id>`).
Для ізольованих завдань доставлення в чат є спільним. Якщо маршрут чату доступний,
агент може використовувати інструмент `message` навіть коли завдання використовує `--no-deliver`. Якщо
агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає запасне
оголошення. Інакше `announce`, `webhook` і `none` лише керують тим, що
runner робить із фінальною відповіддю після ходу агента.
Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. В іншому разі `announce`, `webhook` і `none` керують лише тим, що виконавець робить із фінальною відповіддю після ходу агента.
Сповіщення про помилки йдуть окремим маршрутом призначення:
Сповіщення про помилки використовують окремий шлях призначення:
- `cron.failureDestination` задає глобальне типове значення для сповіщень про помилки.
- `job.delivery.failureDestination` перевизначає це для конкретного завдання.
- Якщо не задано жодного з них і завдання вже доставляє результат через `announce`, сповіщення про помилки тепер запасно надсилаються до цієї ж основної цілі announce.
- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставлення не є `webhook`.
- `job.delivery.failureDestination` перевизначає це для окремого завдання.
- Якщо не задано жодного з них і завдання вже доставляє через `announce`, сповіщення про помилки тепер резервно надсилаються до цієї основної цілі announce.
- `delivery.failureDestination` підтримується лише для завдань з `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`.
## Приклади CLI
@ -166,7 +147,7 @@ openclaw cron add \
--wake now
```
Періодичне ізольоване завдання з доставленням:
Повторюване ізольоване завдання з доставкою:
```bash
openclaw cron add \
@ -196,7 +177,7 @@ openclaw cron add \
## Webhook-и
Gateway може відкривати HTTP endpoint-и Webhook для зовнішніх тригерів. Увімкніть це в конфігурації:
Gateway може відкривати HTTP-кінцеві точки Webhook для зовнішніх тригерів. Увімкніть у конфігурації:
```json5
{
@ -210,16 +191,16 @@ Gateway може відкривати HTTP endpoint-и Webhook для зовні
### Автентифікація
Кожен запит має містити токен hook через заголовок:
Кожен запит має включати токен hook через заголовок:
- `Authorization: Bearer <token>` (рекомендовано)
- `x-openclaw-token: <token>`
Токени в query string відхиляються.
Токени в рядку запиту відхиляються.
### POST /hooks/wake
Поставити системну подію в чергу для основної сесії:
Поставити в чергу системну подію для основної сесії:
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
@ -246,23 +227,23 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \
### Зіставлені hook-и (POST /hooks/\<name\>)
Користувацькі назви hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільний payload на дії `wake` або `agent` за допомогою шаблонів або кодових трансформацій.
Користувацькі імена hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільний payload на дії `wake` або `agent` за допомогою шаблонів або перетворень коду.
### Безпека
- Тримайте endpoint-и hook-ів за loopback, tailnet або довіреним reverse proxy.
- Використовуйте окремий токен hook-ів; не використовуйте повторно токени автентифікації gateway.
- Тримайте кінцеві точки hook за loopback, tailnet або довіреним reverse proxy.
- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway.
- Тримайте `hooks.path` на окремому підшляху; `/` відхиляється.
- Встановіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`.
- Тримайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, які вибирає викликач.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесії.
- Payload-и hook-ів типово обгортаються межами безпеки.
- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесії.
- Payload hook-ів типово обгортаються захисними межами.
## Інтеграція Gmail PubSub
Підключіть тригери вхідної пошти Gmail до OpenClaw через Google PubSub.
**Передумови**: CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS endpoint.
**Передумови**: CLI `gcloud`, `gog` (gogcli), увімкнені hook-и OpenClaw, Tailscale для публічної кінцевої точки HTTPS.
### Налаштування через майстер (рекомендовано)
@ -270,11 +251,11 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \
openclaw webhooks gmail setup --account openclaw@gmail.com
```
Це записує конфігурацію `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push endpoint.
Це записує конфігурацію `hooks.gmail`, вмикає пресет Gmail і використовує Tailscale Funnel для push-кінцевої точки.
### Автозапуск Gateway
Коли `hooks.enabled=true` і `hooks.gmail.account` задано, Gateway під час запуску запускає `gog gmail watch serve` і автоматично поновлює watch. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися від цього.
Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway під час запуску запускає `gog gmail watch serve` і автоматично поновлює watch. Щоб відмовитися від цього, установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`.
### Ручне одноразове налаштування
@ -320,28 +301,28 @@ gog gmail watch start \
## Керування завданнями
```bash
# List all jobs
# Показати всі завдання
openclaw cron list
# Show one job, including resolved delivery route
# Показати одне завдання, включно з визначеним маршрутом доставки
openclaw cron show <jobId>
# Edit a job
# Редагувати завдання
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
# Force run a job now
# Примусово запустити завдання зараз
openclaw cron run <jobId>
# Run only if due
# Запустити лише якщо час уже настав
openclaw cron run <jobId> --due
# View run history
# Переглянути історію запусків
openclaw cron runs --id <jobId> --limit 50
# Delete a job
# Видалити завдання
openclaw cron remove <jobId>
# Agent selection (multi-agent setups)
# Вибір агента (у конфігураціях із кількома агентами)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
@ -349,13 +330,9 @@ openclaw cron edit <jobId> --clear-agent
Примітка щодо перевизначення моделі:
- `openclaw cron add|edit --model ...` змінює вибрану модель завдання.
- Якщо модель дозволена, саме цей провайдер/модель використовується в ізольованому
запуску агента.
- Якщо її не дозволено, cron попереджає й повертається до вибору моделі
агента/типової моделі завдання.
- Налаштовані ланцюжки fallback, як і раніше, застосовуються, але звичайне перевизначення `--model`
без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента
як до тихої додаткової цілі повторної спроби.
- Якщо модель дозволена, саме ця точна provider/model потрапляє до ізольованого запуску агента.
- Якщо вона не дозволена, cron видає попередження та повертається до вибору моделі агента/типової моделі завдання.
- Налаштовані ланцюжки fallback усе ще застосовуються, але звичайне перевизначення `--model` без явного списку fallback для конкретного завдання більше не переходить до основної моделі агента як до неявної додаткової цілі повторної спроби.
## Конфігурація
@ -377,21 +354,19 @@ openclaw cron edit <jobId> --clear-agent
}
```
Sidecar стану виконання виводиться з `cron.store`: сховище `.json`, таке як
`~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а до шляху сховища
без суфікса `.json` додається `-state.json`.
Sidecar стану часу виконання виводиться з `cron.store`: сховище `.json`, таке як `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а до шляху сховища без суфікса `.json` додається `-state.json`.
Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`.
Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`.
**Повтор одноразового завдання**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційною затримкою. Постійні помилки одразу вимикають завдання.
**Повтор для одноразового завдання**: тимчасові помилки (rate limit, overload, network, server error) повторюються до 3 разів з експоненційним backoff. Постійні помилки призводять до негайного вимкнення.
**Повтор періодичного завдання**: експоненційна затримка (від 30 с до 60 хв) між повторними спробами. Після наступного успішного запуску затримка скидається.
**Повтор для повторюваного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску.
**Обслуговування**: `cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналу запусків.
## Усунення неполадок
## Усунення несправностей
### Набір команд
### Послідовність команд
```bash
openclaw status
@ -409,29 +384,25 @@ openclaw doctor
- Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`.
- Переконайтеся, що Gateway працює безперервно.
- Для розкладів `cron` перевірте часовий пояс (`--tz`) відносно часового поясу хоста.
- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run <jobId> --due`, і час виконання завдання ще не настав.
- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено командою `openclaw cron run <jobId> --due`, і час завдання ще не настав.
### Cron спрацював, але доставлення немає
### Cron спрацював, але доставки немає
- Режим доставлення `none` означає, що запасне надсилання з боку runner не очікується. Агент
усе ще може надіслати повідомлення безпосередньо через інструмент `message`, якщо маршрут чату доступний.
- Відсутня/невалідна ціль доставлення (`channel`/`to`) означає, що вихідне надсилання було пропущено.
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставлення було заблоковано обліковими даними.
- Якщо ізольований запуск повертає лише silent token (`NO_REPLY` / `no_reply`),
OpenClaw пригнічує пряме вихідне доставлення, а також пригнічує запасний
шлях зведення через чергу, тому назад у чат нічого не публікується.
- Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний
маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль).
- Режим доставки `none` означає, що резервне надсилання з боку виконавця не очікується. Агент усе ще може надсилати напряму за допомогою інструмента `message`, коли маршрут чату доступний.
- Відсутня/некоректна ціль доставки (`channel`/`to`) означає, що вихідну доставку було пропущено.
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку було заблоковано обліковими даними.
- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також резервний шлях постановки підсумку в чергу, тому назад у чат нічого не публікується.
- Якщо агент має сам надіслати повідомлення користувачеві, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль).
### Поширені проблеми з часовими поясами
### Особливості часових поясів
- Cron без `--tz` використовує часовий пояс хоста gateway.
- Розклади `at` без часового поясу трактуються як UTC.
- `activeHours` Heartbeat використовує налаштоване визначення часового поясу.
- `activeHours` у Heartbeat використовує визначення часового поясу з конфігурації.
## Пов’язане
- [Автоматизація й завдання](/uk/automation) — огляд усіх механізмів автоматизації
- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації з першого погляду
- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron
- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії
- [Часовий пояс](/uk/concepts/timezone) — конфігурація часового поясу

95
docs/uk/channels/irc.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Ви хочете підключити OpenClaw до каналів IRC або приватних повідомлень
- Ви налаштовуєте списки дозволів IRC, групову політику або обмеження за згадуванням
summary: Налаштування плагіна IRC, контроль доступу та усунення несправностей
- Ви налаштовуєте списки дозволених IRC, групову політику або обмеження згадок
summary: Налаштування Plugin IRC, керування доступом і усунення неполадок
title: IRC
x-i18n:
generated_at: "2026-04-23T06:42:20Z"
generated_at: "2026-04-23T07:10:48Z"
model: gpt-5.4
provider: openai
source_hash: 89c788a2be95b43420a5324ed30cada32626b72b2feb77df62aeb928fc0a386c
source_hash: 28d0929e1e3f882eca1ba46eeb5e3fa537baaebfedbe2cf4079946cd9b432c87
source_path: channels/irc.md
workflow: 15
---
@ -16,12 +16,12 @@ x-i18n:
# IRC
Використовуйте IRC, коли хочете мати OpenClaw у класичних каналах (`#room`) і приватних повідомленнях.
IRC постачається як вбудований Plugin, але налаштовується в основному конфігу в `channels.irc`.
IRC постачається як вбудований Plugin, але налаштовується в основній конфігурації в `channels.irc`.
## Швидкий старт
1. Увімкніть конфігурацію IRC у `~/.openclaw/openclaw.json`.
2. Установіть щонайменше:
2. Встановіть щонайменше:
```json5
{
@ -38,48 +38,48 @@ IRC постачається як вбудований Plugin, але налаш
}
```
Для координації бота віддавайте перевагу приватному IRC-серверу. Якщо ви свідомо використовуєте публічну IRC-мережу, поширені варіанти включають Libera.Chat, OFTC і Snoonet. Уникайте передбачуваних публічних каналів для службового трафіку бота або swarm.
Надавайте перевагу приватному IRC-серверу для координації ботів. Якщо ви навмисно використовуєте публічну IRC-мережу, поширені варіанти включають Libera.Chat, OFTC і Snoonet. Уникайте передбачуваних публічних каналів для службового трафіку бота або swarm.
3. Запустіть або перезапустіть Gateway:
3. Запустіть/перезапустіть Gateway:
```bash
openclaw gateway run
```
## Безпечні значення за замовчуванням
## Типові налаштування безпеки
- `channels.irc.dmPolicy` за замовчуванням має значення `"pairing"`.
- `channels.irc.groupPolicy` за замовчуванням має значення `"allowlist"`.
- Якщо `groupPolicy="allowlist"`, установіть `channels.irc.groups`, щоб визначити дозволені канали.
- Використовуйте TLS (`channels.irc.tls=true`), якщо тільки ви свідомо не погоджуєтеся на незашифрований транспорт.
- `channels.irc.dmPolicy` типово має значення `"pairing"`.
- `channels.irc.groupPolicy` типово має значення `"allowlist"`.
- Якщо `groupPolicy="allowlist"`, задайте `channels.irc.groups`, щоб визначити дозволені канали.
- Використовуйте TLS (`channels.irc.tls=true`), якщо тільки ви навмисно не погоджуєтесь на незашифрований транспорт.
## Контроль доступу
## Керування доступом
Для IRC-каналів є дві окремі «перепони»:
Для IRC-каналів є двоє окремих «воріт»:
1. **Доступ до каналу** (`groupPolicy` + `groups`): чи приймає бот повідомлення з каналу взагалі.
2. **Доступ відправника** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): кому дозволено запускати бота всередині цього каналу.
1. **Доступ до каналу** (`groupPolicy` + `groups`): чи бот взагалі приймає повідомлення з каналу.
2. **Доступ відправника** (`groupAllowFrom` / `groups["#channel"].allowFrom` для окремого каналу): хто має право викликати бота всередині цього каналу.
Ключі конфігурації:
- Список дозволів для DM (доступ відправника DM): `channels.irc.allowFrom`
- Список дозволів для відправників у групах (доступ відправника в каналі): `channels.irc.groupAllowFrom`
- Поканальні елементи керування (канал + відправник + правила згадування): `channels.irc.groups["#channel"]`
- `channels.irc.groupPolicy="open"` дозволяє не налаштовані канали (**але за замовчуванням усе одно вимагає згадування**)
- Список дозволених для приватних повідомлень (доступ відправника в DM): `channels.irc.allowFrom`
- Список дозволених відправників у групах (доступ відправника в каналі): `channels.irc.groupAllowFrom`
- Керування для окремого каналу (канал + відправник + правила згадок): `channels.irc.groups["#channel"]`
- `channels.irc.groupPolicy="open"` дозволяє неналаштовані канали (**але за замовчуванням усе одно вимагає згадку**)
Елементи списку дозволів мають використовувати стабільні ідентифікатори відправника (`nick!user@host`).
Записи в allowlist мають використовувати стабільні ідентичності відправника (`nick!user@host`).
Зіставлення лише за nick є змінним і вмикається лише коли `channels.irc.dangerouslyAllowNameMatching: true`.
### Поширена пастка: `allowFrom` призначено для DM, а не для каналів
### Поширена пастка: `allowFrom` призначений для DM, а не для каналів
Якщо ви бачите в логах щось на кшталт:
Якщо ви бачите журнали на кшталт:
- `irc: drop group sender alice!ident@host (policy=allowlist)`
…це означає, що відправник не був дозволений для повідомлень **групи/каналу**. Виправте це одним із способів:
…це означає, що відправник не був дозволений для **групових/канальних** повідомлень. Виправте це одним із способів:
- установіть `channels.irc.groupAllowFrom` (глобально для всіх каналів), або
- установіть поканальні списки дозволів для відправників: `channels.irc.groups["#channel"].allowFrom`
- задайте `channels.irc.groupAllowFrom` (глобально для всіх каналів), або
- задайте списки дозволених відправників для окремих каналів: `channels.irc.groups["#channel"].allowFrom`
Приклад (дозволити будь-кому в `#tuirc-dev` звертатися до бота):
@ -96,13 +96,13 @@ openclaw gateway run
}
```
## Запуск відповіді (згадування)
## Запуск відповіді (згадки)
Навіть якщо канал дозволений (через `groupPolicy` + `groups`) і відправник дозволений, OpenClaw за замовчуванням застосовує **обмеження за згадуванням** у групових контекстах.
Навіть якщо канал дозволений (через `groupPolicy` + `groups`) і відправник дозволений, у групових контекстах OpenClaw за замовчуванням застосовує **обмеження згадкою**.
Це означає, що ви можете бачити в логах щось на кшталт `drop channel … (missing-mention)`, якщо повідомлення не містить шаблон згадування, який відповідає боту.
Це означає, що ви можете бачити журнали на кшталт `drop channel … (missing-mention)`, якщо повідомлення не містить шаблон згадки, який відповідає боту.
Щоб бот відповідав в IRC-каналі **без потреби у згадуванні**, вимкніть обмеження за згадуванням для цього каналу:
Щоб бот відповідав в IRC-каналі **без потреби в згадці**, вимкніть обмеження згадкою для цього каналу:
```json5
{
@ -120,7 +120,7 @@ openclaw gateway run
}
```
Або, щоб дозволити **всі** IRC-канали (без поканального списку дозволів) і водночас відповідати без згадувань:
Або щоб дозволити **усі** IRC-канали (без allowlist для окремих каналів) і водночас відповідати без згадок:
```json5
{
@ -187,12 +187,12 @@ openclaw gateway run
Примітки:
- Ключі `toolsBySender` мають використовувати `id:` для значень ідентифікації відправника IRC:
- Ключі `toolsBySender` мають використовувати `id:` для значень ідентичності відправника IRC:
`id:eigen` або `id:eigen!~eigen@174.127.248.171` для надійнішого зіставлення.
- Старі ключі без префікса все ще приймаються та зіставляються лише як `id:`.
- Перемагає перша відповідна політика відправника; `"*"` — це резервний шаблон для будь-кого.
- Застарілі ключі без префікса все ще підтримуються і зіставляються лише як `id:`.
- Перша відповідна політика відправника має пріоритет; `"*"` є резервним шаблоном.
Докладніше про доступ до групи порівняно з обмеженням за згадуванням (і про те, як вони взаємодіють), див.: [/channels/groups](/uk/channels/groups).
Докладніше про доступ у групах і обмеження згадкою (та їхню взаємодію) див.: [/channels/groups](/uk/channels/groups).
## NickServ
@ -231,7 +231,7 @@ openclaw gateway run
## Змінні середовища
Обліковий запис за замовчуванням підтримує:
Типовий обліковий запис підтримує:
- `IRC_HOST`
- `IRC_PORT`
@ -240,20 +240,27 @@ openclaw gateway run
- `IRC_USERNAME`
- `IRC_REALNAME`
- `IRC_PASSWORD`
- `IRC_CHANNELS` (через кому)
- `IRC_CHANNELS` (розділені комами)
- `IRC_NICKSERV_PASSWORD`
- `IRC_NICKSERV_REGISTER_EMAIL`
## Усунення несправностей
<Note>
`IRC_HOST` входить до списку блокування endpoint і не може задаватися з файлу
`.env` робочого простору. Він має надходити з середовища shell або середовища
процесу Gateway, щоб недовірені робочі простори не могли перенаправити IRC-трафік на
інший сервер. Повний список див. у [Файли `.env` робочого простору](/uk/gateway/security).
</Note>
- Якщо бот підключається, але ніколи не відповідає в каналах, перевірте `channels.irc.groups` **і** чи не відкидаються повідомлення через обмеження за згадуванням (`missing-mention`). Якщо ви хочете, щоб він відповідав без ping, установіть `requireMention:false` для каналу.
## Усунення неполадок
- Якщо бот підключається, але ніколи не відповідає в каналах, перевірте `channels.irc.groups` **і** чи не відкидає повідомлення обмеження згадкою (`missing-mention`). Якщо ви хочете, щоб він відповідав без згадок, встановіть `requireMention:false` для каналу.
- Якщо вхід не вдається, перевірте доступність nick і пароль сервера.
- Якщо TLS не працює в користувацькій мережі, перевірте host/port і налаштування сертифіката.
- Якщо TLS не працює в нестандартній мережі, перевірте host/port і налаштування сертифіката.
## Пов’язане
- [Огляд каналів](/uk/channels) — усі підтримувані канали
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження за згадуванням
- [Pairing](/uk/channels/pairing) — автентифікація в DM і процес pairing
- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження згадкою
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та зміцнення захисту
- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту

681
docs/uk/channels/matrix.md
View File

File diff suppressed because it is too large Load Diff

274
docs/uk/channels/mattermost.md
View File

@ -2,13 +2,13 @@
read_when:
- Налаштування Mattermost
- Налагодження маршрутизації Mattermost
summary: Налаштування бота Mattermost і конфігурація OpenClaw
summary: Налаштування бота Mattermost та конфігурація OpenClaw
title: Mattermost
x-i18n:
generated_at: "2026-04-23T06:42:23Z"
generated_at: "2026-04-23T07:10:47Z"
model: gpt-5.4
provider: openai
source_hash: 7a87465c47c432ad5c6693ca3d2f992f211380a3fc5b602054b2a50d803b72c8
source_hash: 04913fe38ddce73eba2a7f3953ec3241b6871ce4a06e0393d09331e37a39cc2f
source_path: channels/mattermost.md
workflow: 15
---
@ -16,15 +16,15 @@ x-i18n:
# Mattermost
Статус: вбудований plugin (токен бота + події WebSocket). Підтримуються канали, групи та приватні повідомлення.
Mattermost — це платформа командного обміну повідомленнями, яку можна розгорнути самостійно; відомості про продукт і завантаження див. на офіційному сайті
Mattermost — це платформа командного обміну повідомленнями з можливістю самостійного розгортання; докладніше про продукт і завантаження дивіться на офіційному сайті
[mattermost.com](https://mattermost.com).
## Вбудований plugin
Mattermost постачається як вбудований plugin у поточних релізах OpenClaw, тому звичайним
Mattermost постачається як вбудований plugin у поточних випусках OpenClaw, тому звичайним
пакетним збіркам не потрібне окреме встановлення.
Якщо у вас старіша збірка або власне встановлення без Mattermost,
Якщо ви використовуєте старішу збірку або власне встановлення без Mattermost,
встановіть його вручну:
Встановлення через CLI (реєстр npm):
@ -33,7 +33,7 @@ Mattermost постачається як вбудований plugin у пото
openclaw plugins install @openclaw/mattermost
```
Локальний checkout (під час запуску з git-репозиторію):
Локальна checkout-копія (під час запуску з git-репозиторію):
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
@ -44,10 +44,10 @@ openclaw plugins install ./path/to/local/mattermost-plugin
## Швидке налаштування
1. Переконайтеся, що plugin Mattermost доступний.
- Поточні пакетні релізи OpenClaw уже містять його в комплекті.
- У старіших/кастомних встановленнях його можна додати вручну командами вище.
- У поточних пакетних випусках OpenClaw він уже вбудований.
- У старіших/власних встановленнях його можна додати вручну командами вище.
2. Створіть обліковий запис бота Mattermost і скопіюйте **токен бота**.
3. Скопіюйте **базову URL-адресу** Mattermost (наприклад, `https://chat.example.com`).
3. Скопіюйте **базовий URL** Mattermost (наприклад, `https://chat.example.com`).
4. Налаштуйте OpenClaw і запустіть Gateway.
Мінімальна конфігурація:
@ -65,10 +65,10 @@ openclaw plugins install ./path/to/local/mattermost-plugin
}
```
## Власні slash-команди
## Вбудовані slash-команди
Власні slash-команди вмикаються за бажанням. Якщо їх увімкнено, OpenClaw реєструє slash-команди `oc_*` через
Mattermost API і отримує callback POST-запити на HTTP-сервер Gateway.
Вбудовані slash-команди є необов’язковими. Якщо їх увімкнено, OpenClaw реєструє slash-команди `oc_*` через
API Mattermost і отримує callback POST-запити на HTTP-сервері Gateway.
```json5
{
@ -78,7 +78,7 @@ Mattermost API і отримує callback POST-запити на HTTP-серве
native: true,
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
// Використовуйте, якщо Mattermost не може напряму дістатися до Gateway (зворотний проксі/публічна URL-адреса).
// Використовуйте, якщо Mattermost не може напряму звернутися до Gateway (reverse proxy/публічний URL).
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
},
@ -88,41 +88,49 @@ Mattermost API і отримує callback POST-запити на HTTP-серве
Примітки:
- `native: "auto"` типово вимкнено для Mattermost. Установіть `native: true`, щоб увімкнути.
- Якщо `callbackUrl` пропущено, OpenClaw формує її з хоста/порту Gateway + `callbackPath`.
- Для багатокористувацьких конфігурацій `commands` можна задавати на верхньому рівні або в
- `native: "auto"` за замовчуванням вимкнено для Mattermost. Щоб увімкнути, установіть `native: true`.
- Якщо `callbackUrl` пропущено, OpenClaw формує його з хоста/порту Gateway + `callbackPath`.
- Для конфігурацій із кількома обліковими записами `commands` можна задавати на верхньому рівні або в
`channels.mattermost.accounts.<id>.commands` (значення облікового запису мають пріоритет над полями верхнього рівня).
- Callback-и команд перевіряються за допомогою токенів для кожної команди, які повертає
Mattermost, коли OpenClaw реєструє команди `oc_*`.
- Callback-и slash-команд працюють у режимі fail closed, якщо реєстрація не вдалася, запуск був частковим або
токен callback-а не збігається з жодною із зареєстрованих команд.
- Вимога до доступності: endpoint callback-а має бути доступним із сервера Mattermost.
- Не задавайте `callbackUrl` як `localhost`, якщо Mattermost не працює на тому самому хості/в тій самій мережевій області, що й OpenClaw.
- Не задавайте `callbackUrl` як базову URL-адресу Mattermost, якщо ця URL-адреса не проксуює `/api/channels/mattermost/command` до OpenClaw у режимі reverse proxy.
- Швидка перевірка: `curl https://<gateway-host>/api/channels/mattermost/command`; GET-запит має повернути від OpenClaw `405 Method Not Allowed`, а не `404`.
- Callback-и slash-команд блокуються в разі помилки реєстрації, часткового запуску або
якщо токен callback-у не збігається з жодною із зареєстрованих команд.
- Вимога доступності: endpoint callback-у має бути доступний із сервера Mattermost.
- Не задавайте `callbackUrl` як `localhost`, якщо Mattermost не працює на тому самому хості/в тому самому мережевому просторі імен, що й OpenClaw.
- Не задавайте `callbackUrl` як ваш базовий URL Mattermost, якщо цей URL не проксіює `/api/channels/mattermost/command` до OpenClaw через reverse proxy.
- Швидка перевірка: `curl https://<gateway-host>/api/channels/mattermost/command`; GET-запит має повертати `405 Method Not Allowed` від OpenClaw, а не `404`.
- Вимога до allowlist вихідних з’єднань Mattermost:
- Якщо ваш callback спрямовано на приватні/tailnet/internal адреси, задайте в Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections`, щоб включити хост/домен callback-а.
- Використовуйте записи хоста/домену, а не повні URL-адреси.
- Добре: `gateway.tailnet-name.ts.net`
- Погано: `https://gateway.tailnet-name.ts.net`
- Якщо ваш callback спрямовано на приватні/tailnet/internal адреси, додайте хост/домен callback-у до
`ServiceSettings.AllowedUntrustedInternalConnections` у Mattermost.
- Використовуйте записи хоста/домену, а не повні URL.
- Правильно: `gateway.tailnet-name.ts.net`
- Неправильно: `https://gateway.tailnet-name.ts.net`
## Змінні середовища (обліковий запис за замовчуванням)
Задайте їх на хості Gateway, якщо віддаєте перевагу змінним середовища:
Задайте їх на хості Gateway, якщо вам зручніше використовувати змінні середовища:
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
Змінні середовища застосовуються лише до **облікового запису за замовчуванням** (`default`). Для інших облікових записів слід використовувати значення конфігурації.
Змінні середовища застосовуються лише до **облікового запису за замовчуванням** (`default`). Для інших облікових записів потрібно використовувати значення з конфігурації.
<Note>
`MATTERMOST_URL` входить до списку заблокованих endpoint-блоком змінних і не може задаватися з
файлу `.env` робочого простору. Його потрібно передавати через shell environment або
середовище процесу Gateway, щоб ненадійні робочі простори не могли перенаправити трафік Mattermost
на інший сервер. Повний список див. у
[Workspace `.env` files](/uk/gateway/security).
</Note>
## Режими чату
Mattermost автоматично відповідає на приватні повідомлення. Поведінка в каналах керується через `chatmode`:
- `oncall` (типово): відповідати в каналах лише за @згадки.
- `oncall` (за замовчуванням): відповідати в каналах лише при @згадці.
- `onmessage`: відповідати на кожне повідомлення в каналі.
- `onchar`: відповідати, коли повідомлення починається з префікса тригера.
- `onchar`: відповідати, коли повідомлення починається з префікса-тригера.
Приклад конфігурації:
@ -140,18 +148,18 @@ Mattermost автоматично відповідає на приватні п
Примітки:
- `onchar` усе одно відповідає на явні @згадки.
- `channels.mattermost.requireMention` враховується для застарілих конфігурацій, але перевага надається `chatmode`.
- `channels.mattermost.requireMention` враховується для застарілих конфігурацій, але рекомендовано використовувати `chatmode`.
## Потоки та сесії
## Гілки та сесії
Використовуйте `channels.mattermost.replyToMode`, щоб керувати, чи відповіді в каналах і групах залишаються в
основному каналі, чи запускають потік під дописом, що ініціював взаємодію.
Використовуйте `channels.mattermost.replyToMode`, щоб керувати тим, чи відповіді в каналах і групах залишаються в
основному каналі, чи починають гілку під постом, який їх спричинив.
- `off` (типово): відповідати в потоці лише тоді, коли вхідний допис уже перебуває в ньому.
- `first`: для дописів верхнього рівня в каналі/групі запускати потік під цим дописом і маршрутизувати
розмову до сесії в межах потоку.
- `all`: на сьогодні для Mattermost має ту саму поведінку, що й `first`.
- Приватні повідомлення ігнорують це налаштування та лишаються без потоків.
- `off` (за замовчуванням): відповідати в гілці лише тоді, коли вхідний пост уже в ній.
- `first`: для повідомлень верхнього рівня в каналі/групі почати гілку під цим постом і спрямувати
розмову в сесію, прив’язану до гілки.
- `all`: наразі для Mattermost поводиться так само, як `first`.
- Приватні повідомлення ігнорують цей параметр і залишаються без гілок.
Приклад конфігурації:
@ -167,27 +175,27 @@ Mattermost автоматично відповідає на приватні п
Примітки:
- Сесії в межах потоку використовують id допису, що ініціював взаємодію, як корінь потоку.
- `first` і `all` зараз еквівалентні, оскільки щойно Mattermost має корінь потоку,
подальші фрагменти та медіа продовжують іти в тому самому потоці.
- Сесії, прив’язані до гілки, використовують id поста-тригера як корінь гілки.
- `first` і `all` зараз еквівалентні, оскільки щойно в Mattermost з’являється корінь гілки,
подальші частини відповіді та медіа продовжуються в тій самій гілці.
## Керування доступом (приватні повідомлення)
- Типово: `channels.mattermost.dmPolicy = "pairing"` (невідомі відправники отримують код pairing).
- Підтвердження через:
- За замовчуванням: `channels.mattermost.dmPolicy = "pairing"` (невідомі відправники отримують код pairing).
- Схвалення через:
- `openclaw pairing list mattermost`
- `openclaw pairing approve mattermost <CODE>`
- Публічні приватні повідомлення: `channels.mattermost.dmPolicy="open"` плюс `channels.mattermost.allowFrom=["*"]`.
## Канали (групи)
- Типово: `channels.mattermost.groupPolicy = "allowlist"` (із вимогою згадки).
- Додавайте відправників до allowlist через `channels.mattermost.groupAllowFrom` (рекомендуються ID користувачів).
- Перевизначення згадок для окремих каналів розміщуються в `channels.mattermost.groups.<channelId>.requireMention`
- За замовчуванням: `channels.mattermost.groupPolicy = "allowlist"` (із вимогою згадки).
- Додавайте відправників до allowlist через `channels.mattermost.groupAllowFrom` (рекомендовано використовувати ID користувачів).
- Перевизначення згадки для окремих каналів задаються в `channels.mattermost.groups.<channelId>.requireMention`
або в `channels.mattermost.groups["*"].requireMention` як типове значення.
- Відповідність `@username` є змінною і вмикається лише тоді, коли `channels.mattermost.dangerouslyAllowNameMatching: true`.
- Відповідність `@username` є змінною і вмикається лише за `channels.mattermost.dangerouslyAllowNameMatching: true`.
- Відкриті канали: `channels.mattermost.groupPolicy="open"` (із вимогою згадки).
- Примітка щодо runtime: якщо `channels.mattermost` повністю відсутній, runtime використовує `groupPolicy="allowlist"` для перевірок груп (навіть якщо задано `channels.defaults.groupPolicy`).
- Примітка щодо runtime: якщо `channels.mattermost` повністю відсутній, runtime повертається до `groupPolicy="allowlist"` для перевірок груп (навіть якщо задано `channels.defaults.groupPolicy`).
Приклад:
@ -207,25 +215,25 @@ Mattermost автоматично відповідає на приватні п
## Цілі для вихідної доставки
Використовуйте ці формати цілей з `openclaw message send` або Cron/Webhook:
Використовуйте ці формати цілей з `openclaw message send` або cron/webhooks:
- `channel:<id>` для каналу
- `user:<id>` для приватного повідомлення
- `@username` для приватного повідомлення (визначається через Mattermost API)
- `@username` для приватного повідомлення (визначається через API Mattermost)
Прості непрозорі ID (наприклад, `64ifufp...`) у Mattermost **неоднозначні** (ID користувача чи ID каналу).
OpenClaw визначає їх у порядку **спочатку користувач**:
OpenClaw визначає їх **спочатку як користувача**:
- Якщо ID існує як користувач (`GET /api/v4/users/<id>` виконується успішно), OpenClaw надсилає **приватне повідомлення**, визначаючи прямий канал через `/api/v4/channels/direct`.
- Інакше ID обробляється як **ID каналу**.
- Інакше ID трактується як **ID каналу**.
Якщо вам потрібна детермінована поведінка, завжди використовуйте явні префікси (`user:<id>` / `channel:<id>`).
## Повторні спроби DM-каналу
## Повторні спроби для DM-каналу
Коли OpenClaw надсилає повідомлення до цілі DM у Mattermost і спочатку має визначити прямий канал,
типово він повторює спроби при тимчасових збоях створення прямого каналу.
Коли OpenClaw надсилає в ціль приватного повідомлення Mattermost і спочатку має визначити прямий канал,
за замовчуванням він повторює спроби у випадку тимчасових збоїв створення прямого каналу.
Використовуйте `channels.mattermost.dmChannelRetry`, щоб налаштувати цю поведінку глобально для plugin Mattermost,
або `channels.mattermost.accounts.<id>.dmChannelRetry` для окремого облікового запису.
@ -247,13 +255,13 @@ OpenClaw визначає їх у порядку **спочатку корист
Примітки:
- Це застосовується лише до створення DM-каналу (`/api/v4/channels/direct`), а не до кожного виклику Mattermost API.
- Повторні спроби застосовуються до тимчасових збоїв, таких як обмеження швидкості, відповіді 5xx, а також мережеві помилки чи помилки тайм-ауту.
- Клієнтські помилки 4xx, крім `429`, вважаються постійними та не повторюються.
- Це стосується лише створення DM-каналу (`/api/v4/channels/direct`), а не кожного виклику API Mattermost.
- Повторні спроби застосовуються до тимчасових збоїв, таких як обмеження швидкості, відповіді 5xx та помилки мережі або тайм-ауту.
- Помилки клієнта 4xx, окрім `429`, вважаються постійними й не повторюються.
## Потокове попереднє відображення
## Попередній перегляд streaming
Mattermost транслює хід міркувань, активність інструментів і частковий текст відповіді в один **чернетковий допис попереднього перегляду**, який завершується на місці, коли фінальну відповідь безпечно надсилати. Попередній перегляд оновлюється в межах того самого id допису, а не засмічує канал повідомленнями для кожного фрагмента. Фінальні медіа/помилки скасовують очікувані редагування попереднього перегляду й використовують звичайну доставку замість публікації тимчасового допису попереднього перегляду.
Mattermost передає thinking, активність інструментів і частковий текст відповіді в один **чернетковий пост попереднього перегляду**, який фіналізується на місці, коли фінальну відповідь безпечно надсилати. Попередній перегляд оновлюється в тому самому id поста замість того, щоб засмічувати канал повідомленнями на кожен фрагмент. Фінальні медіа/помилки скасовують незавершені редагування попереднього перегляду й використовують звичайну доставку замість публікації тимчасового поста попереднього перегляду.
Увімкнення через `channels.mattermost.streaming`:
@ -269,21 +277,21 @@ Mattermost транслює хід міркувань, активність ін
Примітки:
- `partial` — звичайний вибір: один допис попереднього перегляду, який редагується в міру зростання відповіді, а потім завершується повною відповіддю.
- `block` використовує фрагменти чернетки у стилі додавання всередині допису попереднього перегляду.
- `progress` показує попередній перегляд статусу під час генерації й публікує фінальну відповідь лише після завершення.
- `off` вимикає потокове попереднє відображення.
- Якщо потік неможливо завершити на місці (наприклад, якщо допис було видалено посеред потоку), OpenClaw повертається до надсилання нового фінального допису, щоб відповідь ніколи не була втрачена.
- Дані, що містять лише міркування, не потрапляють у дописи каналу, зокрема текст, який надходить як blockquote `> Reasoning:`. Установіть `/reasoning on`, щоб бачити міркування на інших поверхнях; у фінальному дописі Mattermost лишається тільки відповідь.
- Див. [Streaming](/uk/concepts/streaming#preview-streaming-modes) для матриці відображення каналів.
- `partial` — звичайний вибір: один пост попереднього перегляду, який редагується в міру зростання відповіді, а потім фіналізується повною відповіддю.
- `block` використовує фрагменти чернетки у стилі додавання всередині поста попереднього перегляду.
- `progress` показує статусний попередній перегляд під час генерації та публікує фінальну відповідь лише після завершення.
- `off` вимикає preview streaming.
- Якщо потік не можна фіналізувати на місці (наприклад, якщо пост було видалено під час потоку), OpenClaw повертається до надсилання нового фінального поста, щоб відповідь ніколи не загубилася.
- Дані лише з reasoning приховуються з постів каналу, зокрема текст, що надходить як blockquote `> Reasoning:`. Установіть `/reasoning on`, щоб бачити thinking в інших поверхнях; фінальний пост Mattermost міститиме лише відповідь.
- Матрицю відповідності каналів див. у [Streaming](/uk/concepts/streaming#preview-streaming-modes).
## Реакції (інструмент message)
- Використовуйте `message action=react` з `channel=mattermost`.
- `messageId` — це id допису Mattermost.
- `messageId` — це id поста Mattermost.
- `emoji` приймає назви на кшталт `thumbsup` або `:+1:` (двокрапки необов’язкові).
- Установіть `remove=true` (boolean), щоб видалити реакцію.
- Події додавання/видалення реакцій пересилаються як системні події до сесії агента за маршрутом.
- Події додавання/видалення реакцій пересилаються як системні події в сесію агента, до якої виконується маршрутизація.
Приклади:
@ -294,7 +302,7 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
Конфігурація:
- `channels.mattermost.actions.reactions`: увімкнення/вимкнення дій із реакціями (типово true).
- `channels.mattermost.actions.reactions`: увімкнення/вимкнення дій із реакціями (за замовчуванням true).
- Перевизначення для облікового запису: `channels.mattermost.accounts.<id>.actions.reactions`.
## Інтерактивні кнопки (інструмент message)
@ -314,16 +322,16 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
}
```
Використовуйте `message action=send` з параметром `buttons`. Кнопки — це двовимірний масив (рядки кнопок):
Використовуйте `message action=send` з параметром `buttons`. Кнопки — це двовимірний масив (ряди кнопок):
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
```
Поля кнопки:
Поля кнопок:
- `text` (обов’язково): мітка для відображення.
- `callback_data` (обов’язково): значення, яке повертається при натисканні (використовується як ID дії).
- `text` (обов’язково): підпис, що відображається.
- `callback_data` (обов’язково): значення, що надсилається назад при натисканні (використовується як ID дії).
- `style` (необов’язково): `"default"`, `"primary"` або `"danger"`.
Коли користувач натискає кнопку:
@ -334,8 +342,8 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
Примітки:
- Callback-и кнопок використовують перевірку HMAC-SHA256 (автоматично, без додаткової конфігурації).
- Mattermost прибирає callback data зі своїх API-відповідей (функція безпеки), тому після натискання
прибираються всі кнопки — часткове видалення неможливе.
- Mattermost видаляє callback data зі своїх відповідей API (функція безпеки), тому після натискання
видаляються всі кнопки — часткове видалення неможливе.
- ID дій, що містять дефіси або підкреслення, автоматично санітизуються
(обмеження маршрутизації Mattermost).
@ -343,23 +351,23 @@ message action=send channel=mattermost target=channel:<channelId> buttons=[[{"te
- `channels.mattermost.capabilities`: масив рядків можливостей. Додайте `"inlineButtons"`, щоб
увімкнути опис інструмента кнопок у системному prompt агента.
- `channels.mattermost.interactions.callbackBaseUrl`: необов’язкова зовнішня базова URL-адреса для
- `channels.mattermost.interactions.callbackBaseUrl`: необов’язковий зовнішній базовий URL для
callback-ів кнопок (наприклад, `https://gateway.example.com`). Використовуйте це, якщо Mattermost не може
напряму дістатися до Gateway за його bind host.
- У багатокористувацьких конфігураціях це саме поле також можна задати в
напряму звернутися до Gateway за його bind host.
- У конфігураціях із кількома обліковими записами це саме поле також можна задати в
`channels.mattermost.accounts.<id>.interactions.callbackBaseUrl`.
- Якщо `interactions.callbackBaseUrl` пропущено, OpenClaw формує URL-адресу callback-а з
`gateway.customBindHost` + `gateway.port`, а потім використовує резервний варіант `http://localhost:<port>`.
- Правило доступності: URL-адреса callback-а кнопок має бути доступною із сервера Mattermost.
`localhost` працює лише тоді, коли Mattermost і OpenClaw працюють на тому самому хості/в тій самій мережевій області.
- Якщо ваша ціль callback-а є private/tailnet/internal, додайте її хост/домен до Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections`.
- Якщо `interactions.callbackBaseUrl` пропущено, OpenClaw формує URL callback-у з
`gateway.customBindHost` + `gateway.port`, а потім повертається до `http://localhost:<port>`.
- Правило доступності: URL callback-у кнопки має бути доступний із сервера Mattermost.
`localhost` працює лише тоді, коли Mattermost і OpenClaw запущені на тому самому хості/в тому самому мережевому просторі імен.
- Якщо ваша ціль callback-у є приватною/tailnet/internal, додайте її хост/домен до
`ServiceSettings.AllowedUntrustedInternalConnections` у Mattermost.
### Пряма інтеграція API (зовнішні скрипти)
Зовнішні скрипти та Webhook можуть напряму публікувати кнопки через Mattermost REST API
Зовнішні скрипти та Webhook можуть публікувати кнопки напряму через REST API Mattermost
замість використання інструмента `message` агента. За можливості використовуйте `buildButtonAttachments()` із
plugin; якщо публікуєте сирий JSON, дотримуйтеся цих правил:
plugin; якщо надсилаєте необроблений JSON, дотримуйтеся цих правил:
**Структура payload:**
@ -373,13 +381,13 @@ plugin; якщо публікуєте сирий JSON, дотримуйтеся
actions: [
{
id: "mybutton01", // лише буквено-цифрові символи — див. нижче
type: "button", // обов’язково, інакше натискання буде тихо проігноровано
name: "Approve", // мітка для відображення
type: "button", // обов’язково, інакше натискання тихо ігноруються
name: "Approve", // підпис, що відображається
style: "primary", // необов’язково: "default", "primary", "danger"
integration: {
url: "https://gateway.example.com/mattermost/interactions/default",
context: {
action_id: "mybutton01", // має збігатися з id кнопки (для визначення назви)
action_id: "mybutton01", // має збігатися з id кнопки (для пошуку назви)
action: "approve",
// ... будь-які власні поля ...
_token: "<hmac>", // див. розділ HMAC нижче
@ -395,27 +403,27 @@ plugin; якщо публікуєте сирий JSON, дотримуйтеся
**Критично важливі правила:**
1. Attachments мають розміщуватися в `props.attachments`, а не у верхньорівневому `attachments` (інакше будуть тихо проігноровані).
2. Кожна дія потребує `type: "button"` — без цього натискання будуть тихо поглинуті.
3. Кожна дія потребує поля `id` — Mattermost ігнорує дії без ID.
1. Attachments мають бути в `props.attachments`, а не у верхньорівневому `attachments` (інакше тихо ігноруються).
2. Кожна дія потребує `type: "button"` — без цього натискання тихо поглинаються.
3. Кожна дія потребує поле `id` — Mattermost ігнорує дії без ID.
4. `id` дії має бути **лише буквено-цифровим** (`[a-zA-Z0-9]`). Дефіси та підкреслення ламають
серверну маршрутизацію дій Mattermost (повертає 404). Видаляйте їх перед використанням.
5. `context.action_id` має збігатися з `id` кнопки, щоб у повідомленні підтвердження відображалася
серверну маршрутизацію дій Mattermost (повертається 404). Видаляйте їх перед використанням.
5. `context.action_id` має збігатися з `id` кнопки, щоб у повідомленні підтвердження показувалася
назва кнопки (наприклад, "Approve"), а не сирий ID.
6. `context.action_id` є обов’язковим — без нього обробник інтеракції повертає 400.
6. `context.action_id` є обов’язковим — без нього обробник взаємодій повертає 400.
**Генерація HMAC-токена:**
Gateway перевіряє натискання кнопок за допомогою HMAC-SHA256. Зовнішні скрипти мають генерувати токени,
які збігаються з логікою перевірки Gateway:
Gateway перевіряє натискання кнопок за допомогою HMAC-SHA256. Зовнішні скрипти повинні генерувати токени,
які відповідають логіці перевірки Gateway:
1. Виведіть секрет із токена бота:
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
2. Зберіть об’єкт context з усіма полями **крім** `_token`.
2. Побудуйте об’єкт context з усіма полями **крім** `_token`.
3. Серіалізуйте з **відсортованими ключами** і **без пробілів** (Gateway використовує `JSON.stringify`
з відсортованими ключами, що дає компактний вивід).
4. Підпишіть: `HMAC-SHA256(key=secret, data=serializedContext)`
5. Додайте отриманий hex-digest як `_token` до context.
5. Додайте отриманий hex digest як `_token` у context.
Приклад на Python:
@ -436,22 +444,22 @@ context = {**ctx, "_token": token}
Поширені помилки з HMAC:
- `json.dumps` у Python типово додає пробіли (`{"key": "val"}`). Використовуйте
- `json.dumps` у Python за замовчуванням додає пробіли (`{"key": "val"}`). Використовуйте
`separators=(",", ":")`, щоб відповідати компактному виводу JavaScript (`{"key":"val"}`).
- Завжди підписуйте **всі** поля context (крім `_token`). Gateway видаляє `_token`, а потім
- Завжди підписуйте **всі** поля context (крім `_token`). Gateway прибирає `_token`, а потім
підписує все, що залишилося. Підписування лише частини полів призводить до тихої помилки перевірки.
- Використовуйте `sort_keys=True` — Gateway сортує ключі перед підписуванням, а Mattermost може
змінювати порядок полів context під час збереження payload.
- Виводьте секрет із токена бота (детерміновано), а не з випадкових байтів. Секрет
має бути однаковим у процесі, який створює кнопки, і в Gateway, який їх перевіряє.
має бути однаковим у процесі, що створює кнопки, і в Gateway, який їх перевіряє.
## Адаптер каталогу
## Адаптер directory
Plugin Mattermost містить адаптер каталогу, який визначає назви каналів і користувачів
через Mattermost API. Це дає змогу використовувати цілі `#channel-name` і `@username` у
`openclaw message send` та доставках Cron/Webhook.
Plugin Mattermost містить адаптер directory, який визначає імена каналів і користувачів
через API Mattermost. Це дає змогу використовувати цілі `#channel-name` і `@username` в
`openclaw message send` і доставках cron/Webhook.
Додаткова конфігурація не потрібна — адаптер використовує токен бота з конфігурації облікового запису.
Жодної конфігурації не потрібно — адаптер використовує токен бота з конфігурації облікового запису.
## Кілька облікових записів
@ -472,34 +480,34 @@ Mattermost підтримує кілька облікових записів у
## Усунення несправностей
- Немає відповідей у каналах: переконайтеся, що бот є в каналі й його згадують (oncall), використовуйте префікс тригера (onchar) або задайте `chatmode: "onmessage"`.
- Помилки автентифікації: перевірте токен бота, базову URL-адресу та чи обліковий запис увімкнено.
- Немає відповідей у каналах: переконайтеся, що бот є в каналі та його згадують (oncall), використовуйте префікс-тригер (onchar) або задайте `chatmode: "onmessage"`.
- Помилки автентифікації: перевірте токен бота, базовий URL і чи ввімкнено обліковий запис.
- Проблеми з кількома обліковими записами: змінні середовища застосовуються лише до облікового запису `default`.
- Власні slash-команди повертають `Unauthorized: invalid command token.`: OpenClaw
не прийняв токен callback-а. Типові причини:
- реєстрація slash-команд не вдалася або була виконана лише частково під час запуску
- callback надходить не до того Gateway/облікового запису
- у Mattermost усе ще є старі команди, що вказують на попередню ціль callback-а
- Вбудовані slash-команди повертають `Unauthorized: invalid command token.`: OpenClaw
не прийняв токен callback-у. Типові причини:
- реєстрація slash-команд не вдалася або лише частково завершилася під час запуску
- callback потрапляє не в той Gateway/обліковий запис
- у Mattermost усе ще є старі команди, що вказують на попередню ціль callback-у
- Gateway перезапустився без повторної активації slash-команд
- Якщо власні slash-команди перестали працювати, перевірте логи на наявність
- Якщо вбудовані slash-команди перестали працювати, перевірте журнали на наявність
`mattermost: failed to register slash commands` або
`mattermost: native slash commands enabled but no commands could be registered`.
- Якщо `callbackUrl` пропущено і логи попереджають, що callback визначився як
`http://127.0.0.1:18789/...`, ця URL-адреса, ймовірно, доступна лише тоді,
коли Mattermost працює на тому самому хості/в тій самій мережевій області, що й OpenClaw. Задайте
натомість явний зовнішньо доступний `commands.callbackUrl`.
- Кнопки відображаються як білі прямокутники: агент може надсилати некоректні дані кнопок. Перевірте, що кожна кнопка має поля `text` і `callback_data`.
- Кнопки відображаються, але натискання нічого не робить: перевірте, що `AllowedUntrustedInternalConnections` у конфігурації сервера Mattermost містить `127.0.0.1 localhost`, і що `EnablePostActionIntegration` має значення `true` у ServiceSettings.
- Якщо `callbackUrl` пропущено й журнали попереджають, що callback визначився як
`http://127.0.0.1:18789/...`, цей URL, імовірно, доступний лише тоді,
коли Mattermost працює на тому самому хості/в тому самому мережевому просторі імен, що й OpenClaw. Задайте
явний зовнішньо доступний `commands.callbackUrl`.
- Кнопки відображаються як білі прямокутники: агент може надсилати некоректні дані кнопок. Переконайтеся, що кожна кнопка має поля `text` і `callback_data`.
- Кнопки відображаються, але натискання нічого не роблять: перевірте, що `AllowedUntrustedInternalConnections` у конфігурації сервера Mattermost містить `127.0.0.1 localhost`, а `EnablePostActionIntegration` у ServiceSettings має значення `true`.
- Кнопки повертають 404 при натисканні: `id` кнопки, імовірно, містить дефіси або підкреслення. Маршрутизатор дій Mattermost ламається на небуквено-цифрових ID. Використовуйте лише `[a-zA-Z0-9]`.
- У логах Gateway `invalid _token`: невідповідність HMAC. Перевірте, що ви підписуєте всі поля context (а не лише частину), використовуєте відсортовані ключі та компактний JSON (без пробілів). Див. розділ HMAC вище.
- У логах Gateway `missing _token in context`: поле `_token` відсутнє в context кнопки. Переконайтеся, що його включено під час побудови payload інтеграції.
- У підтвердженні відображається сирий ID замість назви кнопки: `context.action_id` не збігається з `id` кнопки. Задайте для обох те саме санітизоване значення.
- У журналах Gateway є `invalid _token`: невідповідність HMAC. Переконайтеся, що ви підписуєте всі поля context (а не лише частину), використовуєте відсортовані ключі та компактний JSON (без пробілів). Див. розділ HMAC вище.
- У журналах Gateway є `missing _token in context`: поле `_token` відсутнє в context кнопки. Переконайтеся, що його включено під час побудови payload integration.
- Підтвердження показує сирий ID замість назви кнопки: `context.action_id` не збігається з `id` кнопки. Задайте обом однакове санітизоване значення.
- Агент не знає про кнопки: додайте `capabilities: ["inlineButtons"]` до конфігурації каналу Mattermost.
## Пов’язане
## Пов’язані матеріали
- [Огляд каналів](/uk/channels) — усі підтримувані канали
- [Channels Overview](/uk/channels) — усі підтримувані канали
- [Pairing](/uk/channels/pairing) — автентифікація приватних повідомлень і процес pairing
- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження за згадками
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту
- [Groups](/uk/channels/groups) — поведінка групових чатів і обмеження за згадками
- [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
- [Security](/uk/gateway/security) — модель доступу та посилення безпеки

92
docs/uk/channels/synology-chat.md
View File

@ -5,26 +5,26 @@ read_when:
summary: Налаштування Webhook Synology Chat і конфігурація OpenClaw
title: Synology Chat
x-i18n:
generated_at: "2026-04-21T18:02:09Z"
generated_at: "2026-04-23T07:10:47Z"
model: gpt-5.4
provider: openai
source_hash: 7288e2aa873ee1a1f57861d839cfb44ff324e3d40a7f36da07c6ba43cbe1e6e6
source_hash: dda0d5d11e2526f4813b69ca914a63231003eb60d8bc2e1f030bcb3d77c8eda0
source_path: channels/synology-chat.md
workflow: 15
---
# Synology Chat
Статус: вбудований plugin каналу прямих повідомлень, що використовує Webhook Synology Chat.
Статус: bundled plugin каналу прямих повідомлень, що використовує Webhook Synology Chat.
Plugin приймає вхідні повідомлення з вихідних Webhook Synology Chat і надсилає відповіді
через вхідний Webhook Synology Chat.
## Вбудований plugin
## Bundled plugin
Synology Chat постачається як вбудований plugin у поточних релізах OpenClaw, тому звичайні
Synology Chat постачається як bundled plugin у поточних релізах OpenClaw, тому звичайні
пакетні збірки не потребують окремого встановлення.
Якщо ви використовуєте старішу збірку або власне встановлення без Synology Chat,
Якщо у вас старіша збірка або користувацьке встановлення без Synology Chat,
встановіть його вручну:
Встановлення з локального checkout:
@ -37,14 +37,14 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
## Швидке налаштування
1. Переконайтеся, що plugin Synology Chat доступний.
- Поточні пакетні релізи OpenClaw вже містять його вбудованим.
- У старіших/власних встановленнях його можна додати вручну з checkout вихідного коду командою вище.
1. Переконайтеся, що Plugin Synology Chat доступний.
- Поточні пакетні релізи OpenClaw уже містять його.
- Старіші/користувацькі встановлення можуть додати його вручну з checkout вихідного коду командою вище.
- `openclaw onboard` тепер показує Synology Chat у тому самому списку налаштування каналів, що й `openclaw channels add`.
- Неінтерактивне налаштування: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. В інтеграціях Synology Chat:
- Створіть вхідний Webhook і скопіюйте його URL.
- Створіть вихідний Webhook зі своїм секретним token.
- Створіть вихідний Webhook зі своїм секретним токеном.
3. Спрямуйте URL вихідного Webhook на ваш Gateway OpenClaw:
- `https://gateway-host/webhook/synology` за замовчуванням.
- Або ваш власний `channels.synology-chat.webhookPath`.
@ -55,14 +55,14 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
Деталі автентифікації Webhook:
- OpenClaw приймає token вихідного Webhook з `body.token`, потім
`?token=...`, потім із заголовків.
- OpenClaw приймає токен вихідного Webhook з `body.token`, потім
`?token=...`, а потім із заголовків.
- Підтримувані форми заголовків:
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- Порожні або відсутні token блокуються за замовчуванням.
- Порожні або відсутні токени відхиляються за принципом fail-closed.
Мінімальна конфігурація:
@ -90,20 +90,28 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
- `SYNOLOGY_NAS_HOST`
- `SYNOLOGY_ALLOWED_USER_IDS` (через кому)
- `SYNOLOGY_ALLOWED_USER_IDS` (розділені комами)
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
Значення конфігурації мають пріоритет над змінними середовища.
<Note>
`SYNOLOGY_CHAT_INCOMING_URL` входить до списку заблокованих endpoint-ів і не може бути встановлений
з файлу `.env` робочого простору. Він має надходити з shell-середовища або
середовища процесу Gateway, щоб ненадійні робочі простори не могли перенаправити
трафік Synology Chat на інший Webhook. Повний список див. у
[Workspace `.env` files](/uk/gateway/security).
</Note>
## Політика DM і контроль доступу
- `dmPolicy: "allowlist"` — рекомендоване значення за замовчуванням.
- `allowedUserIds` приймає список (або рядок із розділенням комами) ID користувачів Synology.
- У режимі `allowlist` порожній список `allowedUserIds` вважається помилкою конфігурації, і маршрут Webhook не буде запущено (використовуйте `dmPolicy: "open"` для дозволу всім).
- `allowedUserIds` приймає список (або рядок, розділений комами) ID користувачів Synology.
- У режимі `allowlist` порожній список `allowedUserIds` вважається неправильною конфігурацією, і маршрут Webhook не буде запущено (для дозволу всім використовуйте `dmPolicy: "open"`).
- `dmPolicy: "open"` дозволяє будь-якого відправника.
- `dmPolicy: "disabled"` блокує DM.
- Прив’язка отримувача відповіді за замовчуванням зберігається до стабільного числового `user_id`. `channels.synology-chat.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який знову вмикає пошук за змінюваними username/nickname для доставки відповідей.
- Прив’язка одержувача відповіді за замовчуванням ґрунтується на стабільному числовому `user_id`. `channels.synology-chat.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який знову вмикає пошук за змінним username/nickname для доставки відповідей.
- Підтвердження pairing працює з:
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
@ -120,19 +128,19 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te
```
Надсилання медіа підтримується через доставку файлів за URL.
Вихідні URL файлів мають використовувати `http` або `https`, а приватні чи іншим чином заблоковані мережеві цілі відхиляються ще до того, як OpenClaw передасть URL до Webhook NAS.
URL вихідних файлів мають використовувати `http` або `https`, а приватні чи іншим чином заблоковані мережеві цілі відхиляються до того, як OpenClaw передасть URL до Webhook NAS.
## Кілька облікових записів
Кілька облікових записів Synology Chat підтримуються в `channels.synology-chat.accounts`.
Кожен обліковий запис може перевизначати token, вхідний URL, шлях Webhook, політику DM та ліміти.
Сеанси прямих повідомлень ізольовані для кожного облікового запису й користувача, тому той самий числовий `user_id`
у двох різних облікових записах Synology не використовує спільний стан транскрипту.
Для кожного ввімкненого облікового запису задайте окремий `webhookPath`. OpenClaw тепер відхиляє дубльовані точні шляхи
і відмовляється запускати іменовані облікові записи, які лише успадковують спільний шлях Webhook у конфігураціях з кількома обліковими записами.
Якщо вам навмисно потрібне застаріле успадкування для іменованого облікового запису, задайте
Підтримується кілька облікових записів Synology Chat у `channels.synology-chat.accounts`.
Кожен обліковий запис може перевизначати token, incoming URL, webhook path, політику DM та ліміти.
Сесії прямих повідомлень ізольовані для кожного облікового запису та користувача, тож однаковий числовий `user_id`
у двох різних облікових записах Synology не ділить стан транскрипту.
Надайте кожному ввімкненому обліковому запису окремий `webhookPath`. OpenClaw тепер відхиляє дублікати точних шляхів
і відмовляється запускати іменовані облікові записи, які лише успадковують спільний webhook path у багатoоблікових конфігураціях.
Якщо вам навмисно потрібне застаріле успадкування для іменованого облікового запису, установіть
`dangerouslyAllowInheritedWebhookPath: true` для цього облікового запису або в `channels.synology-chat`,
але дубльовані точні шляхи все одно відхиляються з блокуванням за замовчуванням. Надавайте перевагу явним шляхам для кожного облікового запису.
але дублікати точних шляхів усе одно відхиляються за принципом fail-closed. Надавайте перевагу явним шляхам для кожного облікового запису.
```json5
{
@ -159,35 +167,35 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te
## Примітки щодо безпеки
- Тримайте `token` у таємниці та змініть його, якщо він витік.
- Залишайте `allowInsecureSsl: false`, якщо тільки ви явно не довіряєте локальному самопідписаному сертифікату NAS.
- Вхідні запити Webhook перевіряються за token і обмежуються за частотою для кожного відправника.
- Перевірки недійсних token використовують порівняння секретів із постійним часом виконання та блокуються за замовчуванням.
- Тримайте `token` у секреті та змініть його, якщо він був розкритий.
- Залишайте `allowInsecureSsl: false`, якщо тільки ви явно не довіряєте локальному сертифікату NAS із самопідписом.
- Вхідні запити Webhook перевіряються за токеном і мають rate limit для кожного відправника.
- Перевірки недійсного токена використовують порівняння секретів у сталий час і працюють за принципом fail-closed.
- Для production надавайте перевагу `dmPolicy: "allowlist"`.
- Не вмикайте `dangerouslyAllowNameMatching`, якщо вам явно не потрібна застаріла доставка відповідей на основі username.
- Не вмикайте `dangerouslyAllowInheritedWebhookPath`, якщо тільки ви явно не приймаєте ризик маршрутизації спільного шляху в конфігурації з кількома обліковими записами.
- Не вмикайте `dangerouslyAllowNameMatching`, якщо тільки вам явно не потрібна застаріла доставка відповідей на основі username.
- Не вмикайте `dangerouslyAllowInheritedWebhookPath`, якщо тільки ви явно не приймаєте ризик маршрутизації через спільний path у багатoобліковій конфігурації.
## Усунення несправностей
- `Missing required fields (token, user_id, text)`:
- у payload вихідного Webhook відсутнє одне з обов’язкових полів
- якщо Synology надсилає token у заголовках, переконайтеся, що Gateway/proxy зберігає ці заголовки
- якщо Synology надсилає токен у заголовках, переконайтеся, що Gateway/proxy зберігає ці заголовки
- `Invalid token`:
- секрет вихідного Webhook не збігається з `channels.synology-chat.token`
- запит надходить не до того облікового запису/шляху Webhook
- reverse proxy видалив заголовок token до того, як запит досяг OpenClaw
- запит потрапляє не до того облікового запису/шляху webhook
- reverse proxy видалив заголовок токена до того, як запит досяг OpenClaw
- `Rate limit exceeded`:
- занадто багато спроб із недійсним token з одного джерела можуть тимчасово заблокувати це джерело
- для автентифікованих відправників також діє окреме обмеження частоти повідомлень для кожного користувача
- забагато спроб із недійсним токеном з одного джерела можуть тимчасово заблокувати це джерело
- для автентифікованих відправників також діє окремий rate limit повідомлень на користувача
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`:
- увімкнено `dmPolicy="allowlist"`, але не налаштовано жодного користувача
- увімкнено `dmPolicy="allowlist"`, але користувачів не налаштовано
- `User not authorized`:
- числовий `user_id` відправника відсутній у `allowedUserIds`
## Пов’язане
- [Огляд каналів](/uk/channels) — усі підтримувані канали
- [Channels Overview](/uk/channels) — усі підтримувані канали
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
- [Групи](/uk/channels/groups) — поведінка групового чату та фільтрація згадок
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту
- [Groups](/uk/channels/groups) — поведінка групових чатів і обмеження за згадками
- [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
- [Security](/uk/gateway/security) — модель доступу та зміцнення безпеки

45
docs/uk/cli/doctor.md
View File

@ -1,14 +1,14 @@
---
read_when:
- У вас є проблеми з підключенням або автентифікацією, і ви хочете отримати керовані виправлення
- Ви оновилися й хочете виконати базову перевірку працездатності
summary: Довідник CLI для `openclaw doctor` (перевірки стану + кероване виправлення)
title: лікар
- У вас є проблеми з підключенням/автентифікацією, і ви хочете керовані виправлення.
- Ви оновилися й хочете перевірку справності.
summary: Довідник CLI для `openclaw doctor` (перевірки стану + керовані виправлення)
title: doctor
x-i18n:
generated_at: "2026-04-23T06:17:54Z"
generated_at: "2026-04-23T07:10:47Z"
model: gpt-5.4
provider: openai
source_hash: ad44619b427b938b2f6d4f904fcdc2d9862ff33c569008590f25e17d12e03530
source_hash: c4b858e8726094c950edcde1e3bdff05d03ae2bd216c3519bbee4805955cf851
source_path: cli/doctor.md
workflow: 15
---
@ -17,10 +17,10 @@ x-i18n:
Перевірки стану + швидкі виправлення для Gateway і каналів.
Пов’язане:
Пов’язано:
- Усунення несправностей: [Troubleshooting](/uk/gateway/troubleshooting)
- Аудит безпеки: [Security](/uk/gateway/security)
- Усунення несправностей: [Усунення несправностей](/uk/gateway/troubleshooting)
- Аудит безпеки: [Безпека](/uk/gateway/security)
## Приклади
@ -38,29 +38,30 @@ openclaw doctor --generate-gateway-token
- `--yes`: приймати типові значення без запитів
- `--repair`: застосувати рекомендовані виправлення без запитів
- `--fix`: псевдонім для `--repair`
- `--force`: застосувати агресивні виправлення, включно з перезаписом користувацької конфігурації сервісу за потреби
- `--force`: застосувати агресивні виправлення, зокрема перезаписати користувацьку конфігурацію сервісу, якщо потрібно
- `--non-interactive`: запуск без запитів; лише безпечні міграції
- `--generate-gateway-token`: згенерувати й налаштувати токен Gateway
- `--deep`: просканувати системні сервіси на наявність додаткових встановлень Gateway
- `--deep`: просканувати системні сервіси на наявність додаткових інсталяцій Gateway
Примітки:
- Інтерактивні запити (як-от виправлення keychain/OAuth) запускаються лише тоді, коли stdin є TTY і **не** встановлено `--non-interactive`. Безголові запуски (cron, Telegram, без термінала) пропускають запити.
- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і `--non-interactive` **не** встановлено. Безголові запуски (Cron, Telegram, без термінала) пропускають запити.
- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження Plugin, щоб безголові перевірки стану залишалися швидкими. Інтерактивні сеанси, як і раніше, повністю завантажують plugins, коли перевірці потрібен їхній внесок.
- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і видаляє невідомі ключі конфігурації, перелічуючи кожне видалення.
- Перевірки цілісності стану тепер виявляють осиротілі файли transcript у каталозі сесій і можуть архівувати їх як `.deleted.<timestamp>`, щоб безпечно звільнити місце.
- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм cron jobs і може переписати їх на місці до того, як scheduler муситиме автоматично нормалізувати їх під час виконання.
- Doctor відновлює відсутні runtime-залежності вбудованих plugin без потреби в правах на запис до встановленого пакета OpenClaw. Для npm-встановлень, що належать root, або захищених systemd units установіть `OPENCLAW_PLUGIN_STAGE_DIR` у каталог із правом запису, наприклад `/var/lib/openclaw/plugin-runtime-deps`.
- Перевірки цілісності стану тепер виявляють осиротілі файли transcript у каталозі сеансів і можуть архівувати їх як `.deleted.<timestamp>`, щоб безпечно звільнити місце.
- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих структур завдань Cron і може переписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання.
- Doctor відновлює відсутні залежності середовища виконання вбудованих Plugin без потреби в доступі на запис до встановленого пакета OpenClaw. Для npm-інсталяцій, що належать root, або захищених systemd-юнитів задайте `OPENCLAW_PLUGIN_STAGE_DIR` у каталозі з правом запису, наприклад `/var/lib/openclaw/plugin-runtime-deps`.
- Doctor автоматично мігрує застарілу пласку конфігурацію Talk (`talk.voiceId`, `talk.modelId` та подібні) у `talk.provider` + `talk.providers.<provider>`.
- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, якщо єдина відмінність — це порядок ключів об’єкта.
- Doctor містить перевірку готовності memory-search і може рекомендувати `openclaw configure --section model`, якщо відсутні embedding-облікові дані.
- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє виразне попередження з варіантами виправлення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`).
- Якщо `gateway.auth.token`/`gateway.auth.password` керуються через SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання і не записує резервні відкриті облікові дані.
- Якщо перевірка channel SecretRef завершується помилкою в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість передчасного завершення.
- Автоматичне визначення username у Telegram `allowFrom` (`doctor --fix`) потребує токена Telegram, який можна визначити в поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає автовизначення в цьому проході.
- Повторні запуски `doctor --fix` більше не повідомляють/не застосовують нормалізацію Talk, якщо єдина відмінність — це порядок ключів об’єкта.
- Doctor містить перевірку готовності пошуку в пам’яті й може рекомендувати `openclaw configure --section model`, якщо відсутні облікові дані для вбудовувань.
- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє чітке попередження з рекомендацією щодо виправлення (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`).
- Якщо `gateway.auth.token`/`gateway.auth.password` керуються через SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує відкриті резервні облікові дані.
- Якщо перевірка SecretRef каналу завершується помилкою під час шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового завершення.
- Автоматичне розпізнавання імен користувачів Telegram `allowFrom` (`doctor --fix`) вимагає Telegram-токен, який можна розпізнати в поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає авторозпізнавання під час цього проходу.
## macOS: перевизначення змінних середовища `launchctl`
Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти стійкі помилки “unauthorized”.
Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти постійні помилки «неавторизовано».
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN

244
docs/uk/cli/gateway.md
View File

@ -2,14 +2,14 @@
read_when:
- Запуск Gateway з CLI (розробка або сервери)
- Налагодження автентифікації Gateway, режимів прив’язки та підключення
- Виявлення Gateway через Bonjour (локально + широкозонний DNS-SD)
summary: CLI Gateway OpenClaw (`openclaw gateway`) — запуск, запити й виявлення Gateway
- Виявлення шлюзів через Bonjour (локальний + широкозонний DNS-SD)
summary: CLI шлюзу OpenClaw (`openclaw gateway`) — запуск, запити й виявлення шлюзів
title: Gateway
x-i18n:
generated_at: "2026-04-23T06:17:52Z"
generated_at: "2026-04-23T07:10:47Z"
model: gpt-5.4
provider: openai
source_hash: 60706df4d3c49271c4b53029eaae16672dde534c7f6f4ce68e04b58fb0cfa467
source_hash: 30d261a33e54bed10c17c14d09d0dd2b8e227bbf9f0ed415e332e7bda4803f1e
source_path: cli/gateway.md
workflow: 15
---
@ -18,7 +18,7 @@ x-i18n:
Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки).
Підкоманди на цій сторінці доступні через `openclaw gateway …`.
Підкоманди на цій сторінці доступні в межах `openclaw gateway …`.
Пов’язана документація:
@ -34,7 +34,7 @@ Gateway — це WebSocket-сервер OpenClaw (канали, вузли, се
openclaw gateway
```
Псевдонім для запуску у foreground:
Псевдонім для запуску у передньому плані:
```bash
openclaw gateway run
@ -43,37 +43,37 @@ openclaw gateway run
Примітки:
- За замовчуванням Gateway відмовляється запускатися, якщо в `~/.openclaw/openclaw.json` не встановлено `gateway.mode=local`. Для разових запусків або запусків у режимі розробки використовуйте `--allow-unconfigured`.
- Очікується, що `openclaw onboard --mode local` і `openclaw setup` записують `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією та виправте її, а не припускайте локальний режим неявно.
- Якщо файл існує, а `gateway.mode` відсутній, Gateway вважає це підозрілим пошкодженням конфігурації та відмовляється «вгадувати local» за вас.
- Прив’язка поза межами loopback без автентифікації блокується (захисне обмеження).
- `SIGUSR1` запускає перезапуск у межах процесу за наявності дозволу (`commands.restart` увімкнено за замовчуванням; установіть `commands.restart: false`, щоб заборонити ручний перезапуск, при цьому інструменти gateway tool/config apply/update залишатимуться дозволеними).
- Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жоден користувацький стан термінала. Якщо ви обгортаєте CLI в TUI або raw-mode input, відновіть термінал перед виходом.
- Очікується, що `openclaw onboard --mode local` і `openclaw setup` записують `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією й виправте її, а не припускайте локальний режим неявно.
- Якщо файл існує, а `gateway.mode` відсутній, Gateway трактує це як підозріле пошкодження конфігурації й відмовляється «вгадувати local» за вас.
- Прив’язка за межами loopback без автентифікації блокується (захисне обмеження).
- `SIGUSR1` запускає перезапуск у межах процесу, якщо це дозволено (`commands.restart` увімкнено за замовчуванням; установіть `commands.restart: false`, щоб заблокувати ручний перезапуск, тоді як gateway tool/config apply/update залишаються дозволеними).
- Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жодний спеціальний стан термінала. Якщо ви обгортаєте CLI у TUI або ввід у raw-mode, відновіть термінал перед виходом.
### Параметри
- `--port <port>`: порт WebSocket (типове значення надходить із config/env; зазвичай `18789`).
- `--port <port>`: порт WebSocket (значення за замовчуванням береться з config/env; зазвичай `18789`).
- `--bind <loopback|lan|tailnet|auto|custom>`: режим прив’язки слухача.
- `--auth <token|password>`: перевизначення режиму автентифікації.
- `--token <token>`: перевизначення токена (також установлює `OPENCLAW_GATEWAY_TOKEN` для процесу).
- `--password <password>`: перевизначення пароля. Попередження: паролі, передані inline, можуть бути видимі в локальних списках процесів.
- `--password-file <path>`: прочитати пароль gateway з файлу.
- `--tailscale <off|serve|funnel>`: оприлюднити Gateway через Tailscale.
- `--tailscale-reset-on-exit`: скинути конфігурацію Tailscale serve/funnel під час завершення роботи.
- `--allow-unconfigured`: дозволити запуск gateway без `gateway.mode=local` у конфігурації. Це обходить стартовий захист лише для разового/dev bootstrap; воно не записує й не виправляє файл конфігурації.
- `--dev`: створити dev config + workspace, якщо їх немає (пропускає BOOTSTRAP.md).
- `--reset`: скинути dev config + credentials + sessions + workspace (потребує `--dev`).
- `--force`: перед запуском завершити будь-який наявний listener на вибраному порту.
- `--password <password>`: перевизначення пароля. Попередження: паролі, передані безпосередньо в команді, можуть бути видимі в локальних списках процесів.
- `--password-file <path>`: читати пароль gateway з файлу.
- `--tailscale <off|serve|funnel>`: опублікувати Gateway через Tailscale.
- `--tailscale-reset-on-exit`: скинути конфігурацію Tailscale serve/funnel під час завершення.
- `--allow-unconfigured`: дозволити запуск gateway без `gateway.mode=local` у config. Це обходить захист запуску лише для разового запуску або bootstrap у режимі розробки; параметр не записує та не виправляє файл конфігурації.
- `--dev`: створити конфігурацію та workspace для розробки, якщо їх немає (пропускає BOOTSTRAP.md).
- `--reset`: скинути конфігурацію для розробки, облікові дані, сесії та workspace (потребує `--dev`).
- `--force`: завершити будь-який наявний listener на вибраному порту перед запуском.
- `--verbose`: докладні журнали.
- `--cli-backend-logs`: показувати в консолі лише журнали backend CLI (і вмикати stdout/stderr).
- `--ws-log <auto|full|compact>`: стиль журналу websocket (типово `auto`).
- `--cli-backend-logs`: показувати в консолі лише журнали бекенда CLI (і ввімкнути stdout/stderr).
- `--ws-log <auto|full|compact>`: стиль журналів websocket (типово `auto`).
- `--compact`: псевдонім для `--ws-log compact`.
- `--raw-stream`: журналювати сирі події потоку моделі у jsonl.
- `--raw-stream-path <path>`: шлях до raw stream jsonl.
- `--raw-stream`: журналювати необроблені події потоку моделі у jsonl.
- `--raw-stream-path <path>`: шлях до jsonl необробленого потоку.
Профілювання запуску:
- Установіть `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб журналювати тривалість фаз під час запуску Gateway.
- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виміряти продуктивність запуску Gateway. Бенчмарк фіксує перший вивід процесу, `/healthz`, `/readyz` і часові показники startup trace.
- Установіть `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб журналювати часові показники фаз під час запуску Gateway.
- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виконати бенчмарк запуску Gateway. Бенчмарк фіксує перший вивід процесу, `/healthz`, `/readyz` і часові показники трасування запуску.
## Запит до запущеного Gateway
@ -81,20 +81,20 @@ openclaw gateway run
Режими виводу:
- Типово: зручний для читання людиною формат (із кольорами в TTY).
- `--json`: JSON для машинного читання (без стилізації/spinner).
- `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігши придатний для читання людиною макет.
- Типово: зручний для читання людиною формат (кольоровий у TTY).
- `--json`: JSON для машинного читання (без стилізації/спінера).
- `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігши формат для читання людиною.
Спільні параметри (де підтримуються):
- `--url <url>`: URL WebSocket Gateway.
- `--token <token>`: токен Gateway.
- `--password <password>`: пароль Gateway.
- `--timeout <ms>`: тайм-аут/бюджет часу (залежить від команди).
- `--expect-final`: чекати на відповідь “final” (виклики агентів).
- `--timeout <ms>`: timeout/бюджет часу (залежить від команди).
- `--expect-final`: чекати на «final» відповідь (виклики агента).
Примітка: коли ви встановлюєте `--url`, CLI не використовує резервний перехід до облікових даних із конфігурації або змінних середовища.
Передайте `--token` або `--password` явно. Відсутність явних облікових даних є помилкою.
Примітка: коли ви вказуєте `--url`, CLI не використовує як запасний варіант облікові дані з config або середовища.
Передайте `--token` або `--password` явно. Відсутність явно вказаних облікових даних є помилкою.
### `gateway health`
@ -102,7 +102,7 @@ openclaw gateway run
openclaw gateway health --url ws://127.0.0.1:18789
```
HTTP-ендпойнт `/healthz` — це перевірка живучості: він повертає відповідь, щойно сервер може відповідати по HTTP. HTTP-ендпойнт `/readyz` суворіший і залишається червоним, доки стартові sidecar-процеси, канали або налаштовані хуки ще завершують ініціалізацію.
HTTP-ендпойнт `/healthz` — це перевірка живості: він відповідає, щойно сервер може обслуговувати HTTP. HTTP-ендпойнт `/readyz` суворіший і залишається в стані red, поки побічні компоненти запуску, канали або налаштовані хуки ще стабілізуються.
### `gateway usage-cost`
@ -120,7 +120,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
Отримати нещодавні дані записувача діагностичної стабільності із запущеного Gateway.
Отримати нещодавній засіб запису діагностичної стабільності з запущеного Gateway.
```bash
openclaw gateway stability
@ -135,19 +135,19 @@ openclaw gateway stability --json
- `--limit <limit>`: максимальна кількість нещодавніх подій для включення (типово `25`, максимум `1000`).
- `--type <type>`: фільтр за типом діагностичної події, наприклад `payload.large` або `diagnostic.memory.pressure`.
- `--since-seq <seq>`: включати лише події після номера діагностичної послідовності.
- `--bundle [path]`: читати збережений stability bundle замість звернення до запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого bundle у каталозі стану або передайте шлях безпосередньо до bundle JSON.
- `--export`: записати shareable support diagnostics zip замість виведення подробиць stability.
- `--bundle [path]`: читати збережений пакет стабільності замість звернення до запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого пакета в каталозі стану або передайте шлях до JSON-файлу пакета безпосередньо.
- `--export`: записати zip-файл із діагностикою для підтримки, яким можна ділитися, замість виведення подробиць стабільності.
- `--output <path>`: шлях виводу для `--export`.
Примітки:
- Записувач активний за замовчуванням. Установлюйте `diagnostics.enabled: false` лише тоді, коли потрібно вимкнути збір діагностичного Heartbeat Gateway.
- Записи зберігають операційні метадані: назви подій, кількості, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналу/plugin і відредаговані зведення сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies, секретні значення, імена хостів або сирі ідентифікатори сесій.
- У разі фатального завершення Gateway, тайм-аутів під час завершення роботи та збоїв запуску після перезапуску OpenClaw записує той самий діагностичний знімок у `~/.openclaw/logs/stability/openclaw-stability-*.json`, якщо в записувача є події. Перегляньте найновіший bundle за допомогою `openclaw gateway stability --bundle latest`; параметри `--limit`, `--type` і `--since-seq` також застосовуються до виводу bundle.
- Засіб запису активний за замовчуванням і не містить payload: він фіксує лише операційні метадані, а не текст чату, результати інструментів чи необроблені тіла запитів або відповідей. Установлюйте `diagnostics.enabled: false` лише коли потрібно повністю вимкнути збір діагностичного Heartbeat Gateway.
- Записи зберігають операційні метадані: назви подій, кількості, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/Plugin і зредаговані підсумки сесій. Вони не зберігають текст чату, тіла webhook, результати інструментів, необроблені тіла запитів або відповідей, токени, cookies, секретні значення, імена хостів або необроблені id сесій.
- У разі фатального завершення Gateway, timeout під час завершення роботи та збоїв запуску під час перезапуску OpenClaw записує той самий діагностичний знімок до `~/.openclaw/logs/stability/openclaw-stability-*.json`, якщо засіб запису має події. Перегляньте найновіший пакет за допомогою `openclaw gateway stability --bundle latest`; параметри `--limit`, `--type` і `--since-seq` також застосовуються до виводу пакета.
### `gateway diagnostics export`
Записати локальний diagnostics zip, призначений для додавання до звітів про помилки.
Записати локальний zip-файл діагностики, призначений для додавання до звітів про помилки.
```bash
openclaw gateway diagnostics export
@ -157,23 +157,23 @@ openclaw gateway diagnostics export --json
Параметри:
- `--output <path>`: шлях до вихідного zip-файлу. Типово — support export у каталозі стану.
- `--output <path>`: шлях до вихідного zip-файлу. За замовчуванням — support export у каталозі стану.
- `--log-lines <count>`: максимальна кількість санітизованих рядків журналу для включення (типово `5000`).
- `--log-bytes <bytes>`: максимальна кількість байтів журналу для аналізу (типово `1000000`).
- `--url <url>`: URL WebSocket Gateway для знімка health.
- `--token <token>`: токен Gateway для знімка health.
- `--password <password>`: пароль Gateway для знімка health.
- `--timeout <ms>`: тайм-аут знімка status/health (типово `3000`).
- `--no-stability-bundle`: пропустити пошук збереженого stability bundle.
- `--json`: вивести записаний шлях, розмір і manifest у форматі JSON.
- `--timeout <ms>`: timeout знімка status/health (типово `3000`).
- `--no-stability-bundle`: пропустити пошук збереженого пакета стабільності.
- `--json`: вивести записаний шлях, розмір і маніфест як JSON.
Експорт містить manifest, зведення в Markdown, форму конфігурації, санітизовані деталі конфігурації, санітизовані зведення журналів, санітизовані знімки стану/health Gateway і найновіший stability bundle, якщо він існує.
Експорт містить маніфест, підсумок у Markdown, форму конфігурації, санітизовані деталі конфігурації, санітизовані підсумки журналів, санітизовані знімки status/health Gateway і найновіший пакет стабільності, якщо він існує.
Він призначений для поширення. Він зберігає операційні деталі, які допомагають у налагодженні, наприклад безпечні поля журналів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, ідентифікатори plugin, ідентифікатори провайдерів, несекретні налаштування функцій і відредаговані операційні повідомлення журналу. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookies, ідентифікатори облікових записів/повідомлень, текст prompt/instruction, імена хостів і секретні значення. Якщо повідомлення у стилі LogTape схоже на текст навантаження користувача/чату/інструмента, експорт зберігає лише факт пропуску повідомлення та його розмір у байтах.
Він призначений для поширення. Він зберігає операційні деталі, що допомагають налагодженню, наприклад безпечні поля журналів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, id Plugin, id провайдерів, несекретні налаштування функцій і зредаговані повідомлення операційних журналів. Він пропускає або редагує текст чату, тіла webhook, результати інструментів, облікові дані, cookies, ідентифікатори акаунтів/повідомлень, текст prompt/інструкцій, імена хостів і секретні значення. Коли повідомлення у стилі LogTape виглядає як текст payload користувача/чату/інструмента, експорт зберігає лише факт пропуску повідомлення та кількість його байтів.
### `gateway status`
`gateway status` показує сервіс Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливостей підключення/автентифікації.
`gateway status` показує службу Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливостей підключення/автентифікації.
```bash
openclaw gateway status
@ -183,86 +183,86 @@ openclaw gateway status --require-rpc
Параметри:
- `--url <url>`: додати явну ціль перевірки. Налаштовані remote + localhost також перевіряються.
- `--token <token>`: автентифікація токеном для перевірки.
- `--password <password>`: автентифікація паролем для перевірки.
- `--timeout <ms>`: тайм-аут перевірки (типово `10000`).
- `--no-probe`: пропустити перевірку підключення (лише перегляд сервісу).
- `--deep`: також сканувати системні сервіси.
- `--require-rpc`: підвищити типову перевірку підключення до перевірки читання та завершуватися з ненульовим кодом, якщо ця перевірка читання не вдалася. Не можна поєднувати з `--no-probe`.
- `--url <url>`: додати явну ціль для probe. Налаштовані remote + localhost усе одно перевіряються.
- `--token <token>`: автентифікація токеном для probe.
- `--password <password>`: автентифікація паролем для probe.
- `--timeout <ms>`: timeout probe (типово `10000`).
- `--no-probe`: пропустити перевірку підключення (лише перегляд служби).
- `--deep`: також сканувати системні служби.
- `--require-rpc`: підвищити типову перевірку підключення до перевірки читання й завершуватися з ненульовим кодом, якщо ця перевірка читання не вдалася. Не можна поєднувати з `--no-probe`.
Примітки:
- `gateway status` залишається доступною для діагностики, навіть коли локальна конфігурація CLI відсутня або недійсна.
- Типова `gateway status` підтверджує стан сервісу, WebSocket-підключення та можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування.
- `gateway status` визначає налаштовані auth SecretRef для автентифікації перевірки, коли це можливо.
- Якщо потрібний auth SecretRef не визначається в цьому шляху виконання команди, `gateway status --json` повідомляє `rpc.authWarning`, коли перевірка підключення/автентифікації не вдається; передайте `--token`/`--password` явно або спочатку визначте джерело секрету.
- Якщо перевірка успішна, попередження про невизначені auth-ref приховуються, щоб уникнути хибнопозитивних результатів.
- Використовуйте `--require-rpc` у скриптах і автоматизації, коли недостатньо просто сервісу, що слухає, і потрібно, щоб RPC-виклики зі scope читання теж були справними.
- `--deep` додає спробу знайти додаткові встановлення launchd/systemd/schtasks. Коли виявлено кілька сервісів, схожих на gateway, придатний для читання людиною вивід показує підказки з очищення та попереджає, що більшість установок повинні запускати один gateway на машину.
- Вивід для людини містить визначений шлях до журналу файлу, а також знімок шляхів/чинності конфігурації CLI порівняно із сервісом, щоб допомогти діагностувати розходження профілю або state-dir.
- В установках Linux systemd перевірки розходження автентифікації читають значення `Environment=` і `EnvironmentFile=` з unit-файлу (включно з `%h`, лапкованими шляхами, кількома файлами й необов’язковими файлами з `-`).
- Перевірки розходження визначають SecretRef для `gateway.auth.token`, використовуючи об’єднане runtime env (спочатку env команди сервісу, потім резервно env процесу).
- Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy` або режим не встановлено, де пароль може мати пріоритет і жоден кандидат токена не може мати пріоритет), перевірки розходження токена пропускають визначення токена конфігурації.
- Типова `gateway status` підтверджує стан служби, WebSocket-підключення та можливість автентифікації, видиму на етапі handshake. Вона не підтверджує операції читання/запису/адміністрування.
- `gateway status` за можливості розв’язує налаштовані auth SecretRef для автентифікації probe.
- Якщо необхідний auth SecretRef неможливо розв’язати в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли перевірка підключення/автентифікації probe не вдається; передайте `--token`/`--password` явно або спочатку розв’яжіть джерело секрету.
- Якщо probe виконується успішно, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибнопозитивних результатів.
- Використовуйте `--require-rpc` у скриптах та автоматизації, коли недостатньо лише служби, що слухає, і потрібно, щоб виклики RPC з областю читання також були працездатні.
- `--deep` додає спробу виявити додаткові інсталяції launchd/systemd/schtasks. Коли виявлено кілька gateway-подібних служб, вивід для людини містить підказки з очищення й попереджає, що в більшості конфігурацій має працювати один gateway на машину.
- Вивід для людини містить розв’язаний шлях до файлового журналу, а також знімок шляхів/валідності конфігурації CLI-в-порівнянні-зі-службою, щоб допомогти діагностувати дрейф профілю або каталогу стану.
- У Linux-інсталяціях systemd перевірки дрейфу автентифікації служби читають значення `Environment=` і `EnvironmentFile=` з unit-файлу (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами з `-`).
- Перевірки дрейфу розв’язують SecretRef у `gateway.auth.token`, використовуючи об’єднане runtime env (спочатку env команди служби, потім запасний варіант — env процесу).
- Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy`, або режим не задано, де може перемогти пароль і жоден кандидат токена не може перемогти), перевірки дрейфу токена пропускають розв’язання токена конфігурації.
### `gateway probe`
`gateway probe` — це команда «налагодити все». Вона завжди перевіряє:
- ваш налаштований remote gateway (якщо задано), і
- localhost (loopback) **навіть якщо remote налаштовано**.
- ваш налаштований віддалений gateway (якщо задано), і
- localhost (loopback) **навіть якщо віддалений gateway налаштовано**.
Якщо ви передасте `--url`, ця явна ціль буде додана перед обома. У виводі для людини
Якщо ви передасте `--url`, цю явну ціль буде додано перед обома. У виводі для людини
цілі позначаються так:
- `URL (explicit)`
- `Remote (configured)` або `Remote (configured, inactive)`
- `Local loopback`
Якщо доступно кілька gateway, команда виведе їх усі. Підтримка кількох gateway можлива, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість установок усе ж запускають один gateway.
Якщо доступно кілька gateway, буде показано їх усі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість інсталяцій усе ще запускає один gateway.
```bash
openclaw gateway probe
openclaw gateway probe --json
```
Інтерпретація:
Тлумачення:
- `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-підключення.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що саме перевірка змогла довести щодо автентифікації. Це окремо від доступності.
- `Read probe: ok` означає, що RPC-виклики деталей зі scope читання (`health`/`status`/`system-presence`/`config.get`) також були успішними.
- `Read probe: limited - missing scope: operator.read` означає, що підключення успішне, але RPC зі scope читання обмежені. Це повідомляється як **знижена** доступність, а не як повна відмова.
- Код виходу є ненульовим лише тоді, коли жодна з перевірених цілей не є доступною.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що probe змогла підтвердити щодо автентифікації. Це окремо від досяжності.
- `Read probe: ok` означає, що також успішно виконалися детальні RPC-виклики з областю читання (`health`/`status`/`system-presence`/`config.get`).
- `Read probe: limited - missing scope: operator.read` означає, що підключення встановлено успішно, але RPC з областю читання обмежені. Це повідомляється як **погіршена** досяжність, а не повна помилка.
- Код виходу ненульовий лише тоді, коли жодна з перевірених цілей недоступна.
Примітки щодо JSON (`--json`):
- Верхній рівень:
- `ok`: принаймні одна ціль є доступною.
- `degraded`: принаймні одна ціль мала RPC деталей з обмеженим scope.
- `capability`: найкраща можливість, виявлена серед доступних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`).
- `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем у такому порядку: явний URL, SSH-тунель, налаштований remote, потім local loopback.
- `warnings[]`: записи попереджень best-effort з `code`, `message` і необов’язковими `targetIds`.
- `network`: підказки URL для local loopback/tailnet, похідні від поточної конфігурації та мережі хоста.
- `discovery.timeoutMs` і `discovery.count`: фактичний бюджет/кількість результатів виявлення, використані для цього проходу перевірки.
- `ok`: принаймні одна ціль доступна.
- `degraded`: принаймні одна ціль мала RPC подробиць, обмежений областю доступу.
- `capability`: найвища можливість, виявлена серед доступних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`).
- `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем, у такому порядку: явний URL, SSH-тунель, налаштований remote, потім локальний loopback.
- `warnings[]`: записи попереджень у режимі best-effort з полями `code`, `message` та необов’язковим `targetIds`.
- `network`: підказки URL для локального loopback/tailnet, отримані з поточної конфігурації та мережі хоста.
- `discovery.timeoutMs` і `discovery.count`: фактичний бюджет виявлення/кількість результатів, використані в цьому проході probe.
- Для кожної цілі (`targets[].connect`):
- `ok`: доступність після підключення + класифікація degraded.
- `rpcOk`: повний успіх RPC деталей.
- `scopeLimited`: RPC деталей не вдалося через відсутній operator scope.
- `rpcOk`: повний успіх RPC подробиць.
- `scopeLimited`: RPC подробиць не вдалося виконати через відсутню область доступу оператора.
- Для кожної цілі (`targets[].auth`):
- `role`: роль автентифікації, повідомлена в `hello-ok`, якщо доступна.
- `scopes`: надані scope, повідомлені в `hello-ok`, якщо доступні.
- `capability`: класифікація можливості автентифікації, показана для цієї цілі.
- `scopes`: надані області доступу, повідомлені в `hello-ok`, якщо доступні.
- `capability`: класифікація можливості автентифікації, відображена для цієї цілі.
Поширені коди попереджень:
- `ssh_tunnel_failed`: не вдалося налаштувати SSH-тунель; команда повернулася до прямих перевірок.
- `multiple_gateways`: доступною була більш ніж одна ціль; це нетипово, якщо тільки ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot.
- `auth_secretref_unresolved`: налаштований auth SecretRef не вдалося визначити для цілі, що завершилася помилкою.
- `probe_scope_limited`: WebSocket-підключення успішне, але перевірка читання була обмежена через відсутність `operator.read`.
- `ssh_tunnel_failed`: не вдалося налаштувати SSH-тунель; команда переключилася на прямі probe.
- `multiple_gateways`: було доступно більше ніж одну ціль; це нетипово, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot.
- `auth_secretref_unresolved`: не вдалося розв’язати налаштований auth SecretRef для цілі, що завершилася помилкою.
- `probe_scope_limited`: WebSocket-підключення було успішним, але probe читання була обмежена через відсутність `operator.read`.
#### Remote через SSH (паритет із застосунком Mac)
Режим macOS-застосунку “Remote over SSH” використовує локальне перенаправлення порту, щоб remote gateway (який може бути прив’язаний лише до loopback) став доступним за адресою `ws://127.0.0.1:<port>`.
Режим «Remote over SSH» у застосунку macOS використовує локальне перенаправлення порту, тому віддалений gateway (який може бути прив’язаний лише до loopback) стає доступним за адресою `ws://127.0.0.1:<port>`.
Еквівалент у CLI:
@ -272,20 +272,20 @@ openclaw gateway probe --ssh user@gateway-host
Параметри:
- `--ssh <target>`: `user@host` або `user@host:port` (порт типово `22`).
- `--ssh-identity <path>`: файл identity.
- `--ssh-auto`: вибрати перший виявлений хост gateway як SSH-ціль із визначеної
кінцевої точки виявлення (`local.` плюс налаштований домен широкозонного виявлення, якщо є). Підказки лише з TXT
ігноруються.
- `--ssh <target>`: `user@host` або `user@host:port` (порт за замовчуванням `22`).
- `--ssh-identity <path>`: файл ідентичності.
- `--ssh-auto`: вибрати перший виявлений хост gateway як SSH-ціль із розв’язаного
ендпойнта виявлення (`local.` плюс налаштований wide-area домен, якщо він є). Підказки
лише з TXT ігноруються.
Конфігурація (необов’язкова, використовується як типові значення):
Конфігурація (необов’язкова, використовується як значення за замовчуванням):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
### `gateway call <method>`
Низькорівневий допоміжний засіб RPC.
Низькорівневий помічник RPC.
```bash
openclaw gateway call status
@ -294,7 +294,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Параметри:
- `--params <json>`: рядок JSON-об’єкта для параметрів (типово `{}`)
- `--params <json>`: рядок JSON-об’єкта для params (типово `{}`)
- `--url <url>`
- `--token <token>`
- `--password <password>`
@ -305,9 +305,9 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Примітки:
- `--params` має бути коректним JSON.
- `--expect-final` головним чином призначений для RPC у стилі агентів, які транслюють проміжні події перед фінальним навантаженням.
- `--expect-final` призначено переважно для RPC у стилі агента, які передають проміжні події потоком перед фінальним payload.
## Керування сервісом Gateway
## Керування службою Gateway
```bash
openclaw gateway install
@ -326,31 +326,31 @@ openclaw gateway uninstall
Примітки:
- `gateway install` підтримує `--port`, `--runtime`, `--token`, `--force`, `--json`.
- Коли автентифікація токеном потребує токен і `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можливо визначити, але не зберігає визначений токен у метаданих середовища сервісу.
- Якщо автентифікація токеном потребує токен, а налаштований token SecretRef не визначається, встановлення завершується із закриттям доступу замість збереження резервного відкритого тексту.
- Для автентифікації паролем у `gateway run` віддавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password`, підкріпленому SecretRef, замість inline `--password`.
- У режимі виведеної автентифікації shell-only `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час встановлення; використовуйте стійку конфігурацію (`gateway.auth.password` або config `env`) під час встановлення керованого сервісу.
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, встановлення блокується, доки режим не буде задано явно.
- Команди життєвого циклу приймають `--json` для скриптів.
- Коли автентифікація токеном потребує токена, а `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у метаданих середовища служби.
- Якщо автентифікація токеном потребує токена, а налаштований SecretRef токена не розв’язується, інсталяція завершується в закритому режимі замість збереження резервного відкритого тексту.
- Для автентифікації паролем у `gateway run` надавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password` на основі SecretRef замість вбудованого `--password`.
- У режимі inferred auth значення `OPENCLAW_GATEWAY_PASSWORD`, задане лише в оболонці, не послаблює вимоги до токена під час інсталяції; під час інсталяції керованої служби використовуйте стійку конфігурацію (`gateway.auth.password` або `env` конфігурації).
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, інсталяція блокується, доки режим не буде явно встановлено.
- Команди життєвого циклу приймають `--json` для сценаріїв автоматизації.
## Виявлення gateway (Bonjour)
`gateway discover` сканує маяки Gateway (`_openclaw-gw._tcp`).
`gateway discover` сканує beacon Gateway (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (наприклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [/gateway/bonjour](/uk/gateway/bonjour)
- Багатоадресний DNS-SD: `local.`
- Одноадресний DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [/gateway/bonjour](/uk/gateway/bonjour)
Лише gateway з увімкненим виявленням Bonjour (типово ввімкнено) рекламують маяк.
Лише gateway з увімкненим виявленням Bonjour (типово увімкнено) рекламують beacon.
Записи Wide-Area discovery містять (TXT):
- `role` (підказка ролі gateway)
- `transport` (підказка транспорту, наприклад `gateway`)
- `role` (підказка про роль gateway)
- `transport` (підказка про транспорт, наприклад `gateway`)
- `gatewayPort` (порт WebSocket, зазвичай `18789`)
- `sshPort` (необов’язково; клієнти типово використовують `22` для SSH-цілей, якщо це значення відсутнє)
- `tailnetDns` (ім’я хоста MagicDNS, коли доступне)
- `sshPort` (необов’язково; клієнти використовують `22` як SSH-ціль за замовчуванням, якщо значення відсутнє)
- `tailnetDns` (ім’я хоста MagicDNS, якщо доступне)
- `gatewayTls` / `gatewayTlsSha256` (TLS увімкнено + відбиток сертифіката)
- `cliPath` (підказка remote-install, записана до wide-area zone)
- `cliPath` (підказка віддаленої інсталяції, записана до wide-area зони)
### `gateway discover`
@ -360,8 +360,8 @@ openclaw gateway discover
Параметри:
- `--timeout <ms>`: тайм-аут на команду (browse/resolve); типово `2000`.
- `--json`: машинозчитуваний вивід (також вимикає стилізацію/spinner).
- `--timeout <ms>`: timeout для кожної команди (browse/resolve); типово `2000`.
- `--json`: вивід для машинного читання (також вимикає стилізацію/спінер).
Приклади:
@ -372,9 +372,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
Примітки:
- CLI сканує `local.` плюс налаштований домен широкозонного виявлення, якщо його ввімкнено.
- `wsUrl` у JSON-виводі виводиться з визначеної кінцевої точки сервісу, а не з підказок
лише з TXT, таких як `lanHost` або `tailnetDns`.
- У `local.` mDNS `sshPort` і `cliPath` транслюються лише тоді, коли
- CLI сканує `local.` плюс налаштований wide-area домен, якщо такий увімкнено.
- `wsUrl` у JSON-виводі виводиться з розв’язаного ендпойнта служби, а не з підказок
лише TXT, таких як `lanHost` або `tailnetDns`.
- У `local.` mDNS `sshPort` і `cliPath` транслюються лише коли
`discovery.mdns.mode` має значення `full`. Wide-area DNS-SD усе одно записує `cliPath`; `sshPort`
і там також залишається необов’язковим.
там теж залишається необов’язковим.

348
docs/uk/cli/mcp.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Підключення Codex, Claude Code або іншого MCP-клієнта до каналів на базі OpenClaw
- Підключення Codex, Claude Code або іншого клієнта MCP до каналів на базі OpenClaw
- Запуск `openclaw mcp serve`
- Керування збереженими OpenClaw визначеннями MCP-серверів
summary: Надавайте доступ до розмов каналів OpenClaw через MCP і керуйте збереженими визначеннями MCP-серверів
- Керування визначеннями серверів MCP, збереженими в OpenClaw
summary: Відкрийте доступ до розмов каналів OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP
title: mcp
x-i18n:
generated_at: "2026-04-23T06:18:09Z"
generated_at: "2026-04-23T07:10:49Z"
model: gpt-5.4
provider: openai
source_hash: bbc528a7490132f4b505f62bdc4556602243a5e27557c4965c2e1d4f80ad00bd
source_hash: e9783d6270d5ab5526e0f52c72939a6a895d4a92da6193703337ef394655d27c
source_path: cli/mcp.md
workflow: 15
---
@ -18,20 +18,20 @@ x-i18n:
`openclaw mcp` має дві задачі:
- запускати OpenClaw як MCP-сервер за допомогою `openclaw mcp serve`
- керувати визначеннями вихідних MCP-серверів, що належать OpenClaw, за допомогою `list`, `show`,
- запускати OpenClaw як сервер MCP за допомогою `openclaw mcp serve`
- керувати визначеннями вихідних серверів MCP, що належать OpenClaw, за допомогою `list`, `show`,
`set` і `unset`
Інакше кажучи:
Іншими словами:
- `serve` — це OpenClaw, що працює як MCP-сервер
- `list` / `show` / `set` / `unset` — це OpenClaw, що працює як реєстр на
стороні MCP-клієнта для інших MCP-серверів, які його runtime-компоненти можуть використати пізніше
- `serve` — це OpenClaw, що діє як сервер MCP
- `list` / `show` / `set` / `unset` — це OpenClaw, що діє як реєстр на боці клієнта MCP
для інших серверів MCP, які його середовища виконання можуть використовувати пізніше
Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати
сеанс coding harness і маршрутизувати це runtime-середовище через ACP.
Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має самостійно розміщувати
сесію coding harness і спрямовувати це середовище виконання через ACP.
## OpenClaw як MCP-сервер
## OpenClaw як сервер MCP
Це шлях `openclaw mcp serve`.
@ -39,91 +39,98 @@ x-i18n:
Використовуйте `openclaw mcp serve`, коли:
- Codex, Claude Code або інший MCP-клієнт має напряму взаємодіяти з
- Codex, Claude Code або інший клієнт MCP має напряму взаємодіяти з
розмовами каналів на базі OpenClaw
- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сеансами
- вам потрібен один MCP-сервер, який працює з різними каналами OpenClaw,
- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сесіями
- вам потрібен один сервер MCP, що працює через бекенди каналів OpenClaw,
замість запуску окремих мостів для кожного каналу
Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам
розміщувати runtime-середовище coding і зберігати сеанс агента всередині OpenClaw.
Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати
середовище виконання coding і зберігати сесію агента всередині OpenClaw.
## Як це працює
`openclaw mcp serve` запускає stdio MCP-сервер. Цим процесом керує MCP-клієнт.
Поки клієнт тримає stdio-сеанс відкритим, міст підключається до
локального або віддаленого Gateway OpenClaw через WebSocket і надає доступ до
маршрутизованих розмов каналів через MCP.
`openclaw mcp serve` запускає stdio-сервер MCP. Процесом володіє клієнт MCP.
Поки клієнт тримає stdio-сесію відкритою, міст підключається до локального або
віддаленого Gateway OpenClaw через WebSocket і відкриває маршрутизовані розмови
каналів через MCP.
Життєвий цикл:
1. MCP-клієнт запускає `openclaw mcp serve`
1. клієнт MCP запускає `openclaw mcp serve`
2. міст підключається до Gateway
3. маршрутизовані сеанси стають розмовами MCP та інструментами transcript/history
4. живі події ставляться в чергу в пам’яті, поки міст підключений
5. якщо ввімкнено режим каналу Claude, той самий сеанс також може отримувати
3. маршрутизовані сесії стають розмовами MCP та інструментами transcript/history
4. події в реальному часі ставляться в чергу в пам’яті, поки міст підключений
5. якщо увімкнено режим каналу Claude, та сама сесія також може отримувати
push-сповіщення, специфічні для Claude
Важлива поведінка:
- стан live-черги починається з моменту підключення моста
- старіша історія transcript зчитується через `messages_read`
- push-сповіщення Claude існують лише поки MCP-сеанс активний
- стан live-черги починається, коли міст підключається
- старіша історія transcript читається через `messages_read`
- push-сповіщення Claude існують лише поки жива сесія MCP
- коли клієнт відключається, міст завершує роботу, а live-черга зникає
- stdio-сервери MCP, запущені OpenClaw (вбудовані або налаштовані користувачем), під час завершення роботи
зупиняються як дерево процесів, тому дочірні підпроцеси, запущені сервером, не виживають після завершення
батьківського stdio-клієнта
- видалення або скидання сесії звільняє клієнтів MCP цієї сесії через
спільний шлях очищення середовища виконання, тому не залишається завислих stdio-з’єднань,
прив’язаних до видаленої сесії
## Вибір режиму клієнта
Той самий міст можна використовувати двома різними способами:
Використовуйте той самий міст двома різними способами:
- Загальні MCP-клієнти: лише стандартні MCP-інструменти. Використовуйте `conversations_list`,
- Загальні клієнти MCP: лише стандартні інструменти MCP. Використовуйте `conversations_list`,
`messages_read`, `events_poll`, `events_wait`, `messages_send` та
інструменти погодження.
- Claude Code: стандартні MCP-інструменти плюс адаптер каналу, специфічний для Claude.
Увімкніть `--claude-channel-mode on` або залиште типове значення `auto`.
- Claude Code: стандартні інструменти MCP плюс адаптер каналу, специфічний для Claude.
Увімкніть `--claude-channel-mode on` або залиште значення за замовчуванням `auto`.
Наразі `auto` поводиться так само, як `on`. Визначення можливостей клієнта поки що немає.
Сьогодні `auto` поводиться так само, як `on`. Виявлення можливостей клієнта
ще не реалізовано.
## Що надає `serve`
## Що відкриває `serve`
Міст використовує наявні метадані маршруту сеансу Gateway, щоб надавати
доступ до розмов на основі каналів. Розмова з’являється, коли OpenClaw уже має
стан сеансу з відомим маршрутом, наприклад:
Міст використовує наявні метадані маршруту сесії Gateway, щоб відкривати
розмови на базі каналів. Розмова з’являється, коли OpenClaw уже має стан сесії
з відомим маршрутом, таким як:
- `channel`
- метадані одержувача або призначення
- необов’язковий `accountId`
- необов’язковий `threadId`
Це дає MCP-клієнтам єдину точку для:
Це дає клієнтам MCP одне місце, де можна:
- перегляду списку нещодавніх маршрутизованих розмов
- читання нещодавньої історії transcript
- очікування нових вхідних подій
- надсилання відповіді назад тим самим маршрутом
- перегляду запитів на погодження, що надходять, поки міст підключений
- перелічувати нещодавні маршрутизовані розмови
- читати нещодавню історію transcript
- очікувати нові вхідні події
- надсилати відповідь назад тим самим маршрутом
- бачити запити на погодження, що надходять, поки міст підключений
## Використання
```bash
# Локальний Gateway
# Local Gateway
openclaw mcp serve
# Віддалений Gateway
# Remote Gateway
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Віддалений Gateway з автентифікацією паролем
# Remote Gateway with password auth
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
# Увімкнути докладні журнали моста
# Enable verbose bridge logs
openclaw mcp serve --verbose
# Вимкнути push-сповіщення, специфічні для Claude
# Disable Claude-specific push notifications
openclaw mcp serve --claude-channel-mode off
```
## Інструменти моста
## Інструменти мосту
Поточний міст надає такі MCP-інструменти:
Поточний міст відкриває такі інструменти MCP:
- `conversations_list`
- `conversation_get`
@ -137,8 +144,8 @@ openclaw mcp serve --claude-channel-mode off
### `conversations_list`
Показує список нещодавніх розмов на основі сеансів, які вже мають метадані маршруту в
стані сеансу Gateway.
Перелічує нещодавні розмови на базі сесій, які вже мають метадані маршруту
в стані сесії Gateway.
Корисні фільтри:
@ -154,42 +161,44 @@ openclaw mcp serve --claude-channel-mode off
### `messages_read`
Зчитує нещодавні повідомлення transcript для однієї розмови на основі сеансу.
Читає нещодавні повідомлення transcript для однієї розмови на базі сесії.
### `attachments_fetch`
Витягує нетекстові блоки вмісту повідомлення з одного повідомлення transcript. Це
подання метаданих поверх вмісту transcript, а не окреме стале сховище attachment blob.
подання метаданих поверх вмісту transcript, а не окреме довговічне blob-сховище
вкладень.
### `events_poll`
Зчитує поставлені в чергу живі події, починаючи з числового курсора.
Читає поставлені в чергу live-події, починаючи з числового курсора.
### `events_wait`
Виконує довге опитування, доки не надійде наступна відповідна поставлена в чергу подія або не спливе тайм-аут.
Виконує long-polling, доки не надійде наступна відповідна поставлена в чергу подія
або не сплине час очікування.
Використовуйте це, коли загальному MCP-клієнту потрібна майже реальна доставка в реальному часі без
push-протоколу, специфічного для Claude.
Використовуйте це, коли загальному клієнту MCP потрібна майже реальна доставка
в реальному часі без push-протоколу, специфічного для Claude.
### `messages_send`
Надсилає текст назад тим самим маршрутом, уже записаним у сеансі.
Надсилає текст назад тим самим маршрутом, уже збереженим у сесії.
Поточна поведінка:
- потрібен наявний маршрут розмови
- використовує канал сеансу, одержувача, id облікового запису та id треду
- вимагає наявного маршруту розмови
- використовує канал сесії, одержувача, id облікового запису та id гілки
- надсилає лише текст
### `permissions_list_open`
Показує список очікуваних запитів на погодження exec/plugin, які міст спостерігав з моменту
підключення до Gateway.
Перелічує незавершені запити на погодження exec/Plugin, які міст спостерігав
від моменту підключення до Gateway.
### `permissions_respond`
Обробляє один очікуваний запит на погодження exec/plugin одним із варіантів:
Завершує один незавершений запит на погодження exec/Plugin за допомогою:
- `allow-once`
- `allow-always`
@ -197,7 +206,7 @@ push-протоколу, специфічного для Claude.
## Модель подій
Поки міст підключений, він підтримує чергу подій у пам’яті.
Міст зберігає чергу подій у пам’яті, поки він підключений.
Поточні типи подій:
@ -210,24 +219,24 @@ push-протоколу, специфічного для Claude.
Важливі обмеження:
- черга є лише live; вона починається в момент запуску MCP-моста
- черга є лише live; вона починається, коли запускається міст MCP
- `events_poll` і `events_wait` самі по собі не відтворюють старішу історію Gateway
- стале відставання слід зчитувати через `messages_read`
- довговічний беклог слід читати через `messages_read`
## Сповіщення каналу Claude
Міст також може надавати сповіщення каналу, специфічні для Claude. Це
еквівалент адаптера каналу Claude Code в OpenClaw: стандартні MCP-інструменти залишаються
доступними, але живі вхідні повідомлення також можуть надходити як MCP-сповіщення,
специфічні для Claude.
Міст також може відкривати сповіщення каналу, специфічні для Claude. Це
еквівалент OpenClaw для адаптера каналу Claude Code: стандартні інструменти MCP
залишаються доступними, але live-вхідні повідомлення також можуть надходити як
MCP-сповіщення, специфічні для Claude.
Прапорці:
- `--claude-channel-mode off`: лише стандартні MCP-інструменти
- `--claude-channel-mode off`: лише стандартні інструменти MCP
- `--claude-channel-mode on`: увімкнути сповіщення каналу Claude
- `--claude-channel-mode auto`: поточне типове значення; така сама поведінка моста, як у `on`
- `--claude-channel-mode auto`: поточне значення за замовчуванням; така сама поведінка моста, як і в `on`
Коли ввімкнено режим каналу Claude, сервер оголошує експериментальні
Коли режим каналу Claude увімкнено, сервер оголошує експериментальні
можливості Claude і може надсилати:
- `notifications/claude/channel`
@ -235,18 +244,18 @@ push-протоколу, специфічного для Claude.
Поточна поведінка моста:
- вхідні повідомлення transcript типу `user` пересилаються як
- вхідні повідомлення transcript від `user` пересилаються як
`notifications/claude/channel`
- запити дозволів Claude, отримані через MCP, відстежуються в пам’яті
- якщо пов’язана розмова пізніше надсилає `yes abcde` або `no abcde`, міст
перетворює це на `notifications/claude/channel/permission`
- ці сповіщення доступні лише для live-сеансу; якщо MCP-клієнт відключається,
ціль для push зникає
- ці сповіщення існують лише для live-сесії; якщо клієнт MCP відключається,
цілі для push більше немає
Це навмисно специфічно для клієнта. Загальні MCP-клієнти мають покладатися на
стандартні інструменти опитування.
Це навмисно залежить від конкретного клієнта. Загальні клієнти MCP мають
покладатися на стандартні інструменти опитування.
## Конфігурація MCP-клієнта
## Конфігурація клієнта MCP
Приклад конфігурації stdio-клієнта:
@ -268,9 +277,9 @@ push-протоколу, специфічного для Claude.
}
```
Для більшості загальних MCP-клієнтів починайте зі стандартної поверхні інструментів і
ігноруйте режим Claude. Вмикайте режим Claude лише для клієнтів, які справді
розуміють методи сповіщень, специфічні для Claude.
Для більшості загальних клієнтів MCP починайте зі стандартної поверхні
інструментів і ігноруйте режим Claude. Увімкніть режим Claude лише для клієнтів,
які справді розуміють методи сповіщень, специфічні для Claude.
## Параметри
@ -278,105 +287,108 @@ push-протоколу, специфічного для Claude.
- `--url <url>`: URL WebSocket Gateway
- `--token <token>`: токен Gateway
- `--token-file <path>`: зчитати токен із файлу
- `--token-file <path>`: прочитати токен із файла
- `--password <password>`: пароль Gateway
- `--password-file <path>`: зчитати пароль із файлу
- `--password-file <path>`: прочитати пароль із файла
- `--claude-channel-mode <auto|on|off>`: режим сповіщень Claude
- `-v`, `--verbose`: докладні журнали у stderr
- `-v`, `--verbose`: докладні журнали в stderr
За можливості віддавайте перевагу `--token-file` або `--password-file` замість секретів у командному рядку.
За можливості віддавайте перевагу `--token-file` або `--password-file` замість
inline-секретів.
## Безпека та межа довіри
## Межа безпеки та довіри
Міст не вигадує маршрутизацію. Він лише надає доступ до розмов, які Gateway
вже знає, як маршрутизувати.
Міст не вигадує маршрутизацію. Він лише відкриває розмови, які Gateway
вже вміє маршрутизувати.
Це означає:
- allowlist відправників, pairing і довіра на рівні каналу як і раніше належать
до базової конфігурації каналу OpenClaw
базовій конфігурації каналу OpenClaw
- `messages_send` може відповідати лише через наявний збережений маршрут
- стан погоджень є лише live/в пам’яті для поточного сеансу моста
- автентифікація моста має використовувати ті самі механізми токена або пароля Gateway, яким ви
довіряли б для будь-якого іншого віддаленого клієнта Gateway
- стан погоджень існує лише в live/пам’яті для поточної сесії моста
- автентифікація моста має використовувати ті самі механізми токена або пароля Gateway,
яким ви довіряли б для будь-якого іншого віддаленого клієнта Gateway
Якщо розмова відсутня в `conversations_list`, зазвичай причина не в
конфігурації MCP. Причина — відсутні або неповні метадані маршруту в базовому
сеансі Gateway.
Якщо розмова відсутня в `conversations_list`, звичайна причина — не конфігурація
MCP. Це відсутні або неповні метадані маршруту в базовій сесії Gateway.
## Тестування
OpenClaw постачається з детермінованою Docker smoke-перевіркою для цього моста:
OpenClaw постачається з детермінованим Docker smoke-тестом для цього моста:
```bash
pnpm test:docker:mcp-channels
```
Ця smoke-перевірка:
Цей smoke-тест:
- запускає контейнер Gateway із підготовленими даними
- запускає другий контейнер, який запускає `openclaw mcp serve`
- перевіряє виявлення розмов, читання transcript, читання метаданих attachment,
поведінку live-черги подій і маршрутизацію вихідних надсилань
- перевіряє сповіщення стилю Claude для каналу та дозволів через справжній
stdio MCP-міст
- запускає заповнений контейнер Gateway
- запускає другий контейнер, який стартує `openclaw mcp serve`
- перевіряє виявлення розмов, читання transcript, читання метаданих вкладень,
поведінку черги live-подій і маршрутизацію вихідного надсилання
- перевіряє сповіщення каналу та дозволів у стилі Claude через реальний
stdio-міст MCP
Це найшвидший спосіб довести, що міст працює, без підключення реального
облікового запису Telegram, Discord або iMessage до тестового запуску.
Це найшвидший спосіб довести, що міст працює, без підключення реального облікового
запису Telegram, Discord або iMessage до тестового запуску.
Для ширшого контексту тестування див. [Тестування](/uk/help/testing).
Для ширшого контексту тестування див. [Testing](/uk/help/testing).
## Усунення несправностей
### Не повертаються розмови
Зазвичай це означає, що сеанс Gateway ще не можна маршрутизувати. Підтвердьте, що
базовий сеанс має збережені метадані маршруту channel/provider, recipient і
необов’язкові `account/thread`.
Зазвичай це означає, що сесію Gateway ще не можна маршрутизувати. Переконайтеся, що
базова сесія має збережені метадані маршруту каналу/провайдера, одержувача та
необов’язково облікового запису/гілки.
### `events_poll` або `events_wait` пропускає старіші повідомлення
Це очікувано. Live-черга починається з моменту підключення моста. Читайте старішу історію transcript через `messages_read`.
Це очікувано. Live-черга починається, коли міст підключається. Читайте старішу
історію transcript через `messages_read`.
### Не з’являються сповіщення Claude
### Сповіщення Claude не з’являються
Перевірте все з наведеного:
- клієнт тримає stdio MCP-сеанс відкритим
- клієнт тримав stdio-сесію MCP відкритою
- `--claude-channel-mode` має значення `on` або `auto`
- клієнт справді розуміє методи сповіщень, специфічні для Claude
- вхідне повідомлення надійшло після підключення моста
- вхідне повідомлення сталося після підключення моста
### Відсутні погодження
`permissions_list_open` показує лише запити на погодження, які були помічені, поки міст
був підключений. Це не API сталої історії погоджень.
`permissions_list_open` показує лише запити на погодження, які спостерігалися, поки
міст був підключений. Це не API довговічної історії погоджень.
## OpenClaw як реєстр MCP-клієнтів
## OpenClaw як реєстр клієнта MCP
Це шлях `openclaw mcp list`, `show`, `set` і `unset`.
Ці команди не надають доступ до OpenClaw через MCP. Вони керують визначеннями MCP-серверів, що належать OpenClaw,
у `mcp.servers` в конфігурації OpenClaw.
Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями серверів
MCP, що належать OpenClaw, у `mcp.servers` в конфігурації OpenClaw.
Ці збережені визначення призначені для runtime-середовищ, які OpenClaw запускає або налаштовує
пізніше, наприклад вбудованого Pi та інших runtime-адаптерів. OpenClaw зберігає
визначення централізовано, щоб цим runtime-компонентам не потрібно було підтримувати власні дублікати
списків MCP-серверів.
Ці збережені визначення призначені для середовищ виконання, які OpenClaw
запускає або налаштовує пізніше, наприклад вбудований Pi та інші адаптери
середовища виконання. OpenClaw зберігає визначення централізовано, щоб цим
середовищам виконання не доводилося тримати власні дубльовані списки серверів MCP.
Важлива поведінка:
- ці команди лише читають або записують конфігурацію OpenClaw
- вони не підключаються до цільового MCP-сервера
- вони не підключаються до цільового сервера MCP
- вони не перевіряють, чи команда, URL або віддалений транспорт
доступні прямо зараз
- runtime-адаптери самі вирішують, які форми транспорту вони реально підтримують під час виконання
- вбудований Pi надає налаштовані MCP-інструменти у звичайних профілях інструментів `coding` і `messaging`;
`minimal` усе ще приховує їх, а `tools.deny: ["bundle-mcp"]` явно їх вимикає
досяжні прямо зараз
- адаптери середовища виконання вирішують, які форми транспорту вони фактично підтримують
під час виконання
- вбудований Pi відкриває налаштовані інструменти MCP у звичайних профілях інструментів `coding` і `messaging`;
`minimal` як і раніше приховує їх, а `tools.deny: ["bundle-mcp"]`
вимикає їх явно
## Збережені визначення MCP-серверів
## Збережені визначення серверів MCP
OpenClaw також зберігає в конфігурації легковаговий реєстр MCP-серверів для поверхонь,
OpenClaw також зберігає в конфігурації спрощений реєстр серверів MCP для поверхонь,
яким потрібні визначення MCP, керовані OpenClaw.
Команди:
@ -388,10 +400,10 @@ OpenClaw також зберігає в конфігурації легкова
Примітки:
- `list` сортує імена серверів.
- `show` без імені виводить повний об’єкт налаштованих MCP-серверів.
- `set` очікує одне значення JSON-об’єкта в командному рядку.
- `unset` завершується з помилкою, якщо вказаний сервер не існує.
- `list` сортує назви серверів.
- `show` без назви виводить повний налаштований об’єкт серверів MCP.
- `set` очікує одне значення-об’єкт JSON у командному рядку.
- `unset` завершується помилкою, якщо сервера з вказаною назвою не існує.
Приклади:
@ -403,7 +415,7 @@ openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7
```
Приклад структури конфігурації:
Приклад форми конфігурації:
```json
{
@ -421,32 +433,32 @@ openclaw mcp unset context7
}
```
### Транспорт stdio
### Транспорт Stdio
Запускає локальний дочірній процес і взаємодіє через stdin/stdout.
Запускає локальний дочірній процес і обмінюється даними через stdin/stdout.
| Поле | Опис |
| -------------------------- | ------------------------------------- |
| Поле | Опис |
| -------------------------- | ----------------------------------- |
| `command` | Виконуваний файл для запуску (обов’язково) |
| `args` | Масив аргументів командного рядка |
| `env` | Додаткові змінні середовища |
| `cwd` / `workingDirectory` | Робочий каталог для процесу |
| `args` | Масив аргументів командного рядка |
| `env` | Додаткові змінні середовища |
| `cwd` / `workingDirectory` | Робочий каталог для процесу |
#### Фільтр безпеки env для stdio
OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску stdio MCP-сервера до першого RPC, навіть якщо вони вказані в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування runtime. Під час запуску такі значення відхиляються з помилкою конфігурації, щоб вони не могли підставити неявний prelude, замінити інтерпретатор або ввімкнути debugger для stdio-процесу. Звичайні облікові дані, proxy і змінні env, специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, власні `*_API_KEY` тощо), це не зачіпає.
OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску stdio-сервера MCP до першого RPC, навіть якщо вони з’являються в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування середовищем виконання. Такі параметри запуску відхиляються з помилкою конфігурації, щоб вони не могли впровадити неявний пролог, підмінити інтерпретатор або ввімкнути налагоджувач для stdio-процесу. Звичайні змінні середовища для облікових даних, проксі та специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, користувацькі `*_API_KEY` тощо) не зачіпаються.
Якщо вашому MCP-серверу справді потрібна одна із заблокованих змінних, задайте її для хост-процесу Gateway, а не в `env` stdio-сервера.
Якщо вашому серверу MCP справді потрібна одна із заблокованих змінних, задайте її в процесі хоста Gateway, а не в `env` stdio-сервера.
### Транспорт SSE / HTTP
Підключається до віддаленого MCP-сервера через HTTP Server-Sent Events.
Підключається до віддаленого сервера MCP через HTTP Server-Sent Events.
| Поле | Опис |
| --------------------- | ---------------------------------------------------------------- |
| `url` | URL `http` або `https` віддаленого сервера (обов’язково) |
| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени автентифікації) |
| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) |
| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) |
| `headers` | Необов’язкова мапа HTTP-заголовків ключ-значення (наприклад, токени автентифікації) |
| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) |
Приклад:
@ -465,19 +477,19 @@ OpenClaw відхиляє ключі env запуску інтерпретато
}
```
Чутливі значення в `url` (userinfo) і `headers` маскуються в журналах і
виводі стану.
Чутливі значення в `url` (userinfo) і `headers` редагуються в журналах і
виводі статусу.
### Транспорт Streamable HTTP
`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує HTTP streaming для двобічного зв’язку з віддаленими MCP-серверами.
`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує HTTP-streaming для двостороннього зв’язку з віддаленими серверами MCP.
| Поле | Опис |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `url` | URL `http` або `https` віддаленого сервера (обов’язково) |
| `transport` | Установіть `"streamable-http"` для вибору цього транспорту; якщо поле не вказано, OpenClaw використовує `sse` |
| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени автентифікації) |
| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) |
| Поле | Опис |
| --------------------- | ------------------------------------------------------------------------------------ |
| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) |
| `transport` | Встановіть `"streamable-http"`, щоб вибрати цей транспорт; якщо параметр не вказано, OpenClaw використовує `sse` |
| `headers` | Необов’язкова мапа HTTP-заголовків ключ-значення (наприклад, токени автентифікації) |
| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) |
Приклад:
@ -498,18 +510,18 @@ OpenClaw відхиляє ключі env запуску інтерпретато
}
```
Ці команди керують лише збереженою конфігурацією. Вони не запускають міст каналу,
не відкривають live-сеанс MCP-клієнта і не доводять, що цільовий сервер доступний.
Ці команди керують лише збереженою конфігурацією. Вони не запускають міст каналів,
не відкривають live-сесію клієнта MCP і не доводять, що цільовий сервер досяжний.
## Поточні обмеження
Ця сторінка описує міст у тому вигляді, у якому він постачається зараз.
Ця сторінка документує міст у тому вигляді, у якому він постачається сьогодні.
Поточні обмеження:
- виявлення розмов залежить від наявних метаданих маршруту сеансу Gateway
- виявлення розмов залежить від наявних метаданих маршруту сесії Gateway
- немає загального push-протоколу, окрім адаптера, специфічного для Claude
- поки що немає інструментів редагування повідомлень або реакцій
- транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки що немає
- `permissions_list_open` включає лише погодження, які спостерігалися, поки міст
був підключений
- інструментів редагування повідомлень або реакцій поки немає
- транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки немає
- `permissions_list_open` містить лише погодження, які спостерігалися, поки міст
підключений

78
docs/uk/cli/memory.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Ви хочете індексувати або шукати семантичну пам’ять
- Ви налагоджуєте доступність пам’яті або індексування
- Ви хочете перенести викликану короткострокову пам’ять до `MEMORY.md`
- Ви хочете індексувати або шукати семантичну пам’ять.
- Ви налагоджуєте доступність пам’яті або індексування.
- Ви хочете перенести відновлену короткочасну пам’ять до `MEMORY.md`.
summary: Довідник CLI для `openclaw memory` (status/index/search/promote/promote-explain/rem-harness)
title: пам’ять
x-i18n:
generated_at: "2026-04-23T06:18:14Z"
generated_at: "2026-04-23T07:11:16Z"
model: gpt-5.4
provider: openai
source_hash: c9ea7aa2858b18cc6daa6531c45c9e838015b84de1c7a1b88716f2b1323e419c
source_hash: 4a6207037e1097aa793ccb8fbdb8cbf8708ceb7910e31bc286ebb7a5bccb30a2
source_path: cli/memory.md
workflow: 15
---
@ -19,11 +19,11 @@ x-i18n:
Керуйте індексуванням і пошуком семантичної пам’яті.
Надається активним plugin пам’яті (типово: `memory-core`; установіть `plugins.slots.memory = "none"`, щоб вимкнути).
Пов’язане:
Пов’язано:
- Концепція пам’яті: [Memory](/uk/concepts/memory)
- Концепція пам’яті: [Пам’ять](/uk/concepts/memory)
- Вікі пам’яті: [Memory Wiki](/uk/plugins/memory-wiki)
- Wiki CLI: [wiki](/uk/cli/wiki)
- CLI вікі: [wiki](/uk/cli/wiki)
- Plugins: [Plugins](/uk/tools/plugin)
## Приклади
@ -58,11 +58,13 @@ openclaw memory index --agent main --verbose
`memory status`:
- `--deep`: перевірити доступність vector + embedding.
- `--index`: виконати повторне індексування, якщо сховище забруднене (має на увазі `--deep`).
- `--fix`: виправити застарілі блокування recall і нормалізувати метадані перенесення.
- `--deep`: перевірити доступність векторів і вбудовувань.
- `--index`: виконати повторне індексування, якщо сховище брудне (має на увазі `--deep`).
- `--fix`: відновити застарілі блокування recall і нормалізувати метадані перенесення.
- `--json`: вивести JSON.
Якщо `memory status` показує `Dreaming status: blocked`, це означає, що керований Cron для dreaming увімкнено, але Heartbeat, який його запускає, не спрацьовує для типового агента. Див. [Dreaming never runs](/uk/concepts/dreaming#dreaming-never-runs-status-shows-blocked) для двох поширених причин.
`memory index`:
- `--force`: примусово виконати повне повторне індексування.
@ -70,16 +72,16 @@ openclaw memory index --agent main --verbose
`memory search`:
- Вхід запиту: передайте або позиційний `[query]`, або `--query <text>`.
- Якщо передано обидва, перемагає `--query`.
- Якщо передано обидва, пріоритет має `--query`.
- Якщо не передано жодного, команда завершується з помилкою.
- `--agent <id>`: обмежити одним агентом (типово: типовий агент).
- `--max-results <n>`: обмежити кількість повернених результатів.
- `--min-score <n>`: відфільтрувати збіги з низькою оцінкою.
- `--json`: вивести результати JSON.
- `--json`: вивести результати у форматі JSON.
`memory promote`:
Попередній перегляд і застосування перенесення короткострокової пам’яті.
Попередній перегляд і застосування перенесення короткочасної пам’яті.
```bash
openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
@ -91,21 +93,21 @@ openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
Повні параметри:
- Ранжує короткострокових кандидатів із `memory/YYYY-MM-DD.md` за допомогою зважених сигналів перенесення (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`).
- Використовує короткострокові сигнали як із recall пам’яті, так і з щоденних проходів ingestion, а також легкі сигнали підсилення фаз light/REM.
- Коли Dreaming увімкнено, `memory-core` автоматично керує одним завданням Cron, яке виконує повний цикл (`light -> REM -> deep`) у фоновому режимі (ручний `openclaw cron add` не потрібен).
- Ранжує короткочасних кандидатів із `memory/YYYY-MM-DD.md` з використанням зважених сигналів перенесення (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`).
- Використовує короткочасні сигнали як із відновлень пам’яті, так і з щоденних проходів поглинання, а також сигнали підсилення фаз light/REM.
- Коли dreaming увімкнено, `memory-core` автоматично керує одним завданням Cron, яке запускає повний прохід (`light -> REM -> deep`) у фоновому режимі (ручний `openclaw cron add` не потрібен).
- `--agent <id>`: обмежити одним агентом (типово: типовий агент).
- `--limit <n>`: максимальна кількість кандидатів для повернення/застосування.
- `--min-score <n>`: мінімальна зважена оцінка перенесення.
- `--min-recall-count <n>`: мінімальна кількість recall, потрібна для кандидата.
- `--min-unique-queries <n>`: мінімальна кількість різних запитів, потрібна для кандидата.
- `--apply`: додати вибраних кандидатів до `MEMORY.md` і позначити їх як перенесені.
- `--include-promoted`: включити у вивід уже перенесених кандидатів.
- `--include-promoted`: включити вивід для вже перенесених кандидатів.
- `--json`: вивести JSON.
`memory promote-explain`:
Пояснити конкретного кандидата на перенесення та розклад його оцінки.
Пояснити конкретного кандидата на перенесення та розбивку його оцінки.
```bash
openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]
@ -118,7 +120,7 @@ openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [
`memory rem-harness`:
Попередній перегляд REM reflections, candidate truths і результату deep-перенесення без будь-якого запису.
Попередньо переглянути REM-reflections, кандидатів на істини та вивід deep-перенесення без запису будь-чого.
```bash
openclaw memory rem-harness [--agent <id>] [--include-promoted] [--json]
@ -130,23 +132,23 @@ openclaw memory rem-harness [--agent <id>] [--include-promoted] [--json]
## Dreaming
Dreaming — це фонова система консолідації пам’яті з трьома взаємодоповнювальними
фазами: **light** (сортування/підготовка короткострокового матеріалу), **deep** (перенесення
сталих фактів до `MEMORY.md`) і **REM** (рефлексія та виявлення тем).
Dreaming — це фонова система консолідації пам’яті з трьома кооперативними
фазами: **light** (сортування/підготовка короткочасного матеріалу), **deep** (перенесення стійких
фактів до `MEMORY.md`) і **REM** (осмислення та виявлення тем).
- Увімкнення через `plugins.entries.memory-core.config.dreaming.enabled: true`.
- Перемикання з чату через `/dreaming on|off` (або перевірка через `/dreaming status`).
- Dreaming працює за одним керованим розкладом циклу (`dreaming.frequency`) і виконує фази в порядку: light, REM, deep.
- Лише фаза deep записує сталу пам’ять до `MEMORY.md`.
- Увімкніть через `plugins.entries.memory-core.config.dreaming.enabled: true`.
- Перемикайте з чату за допомогою `/dreaming on|off` (або перевіряйте через `/dreaming status`).
- Dreaming працює за одним керованим розкладом проходів (`dreaming.frequency`) і виконує фази в порядку: light, REM, deep.
- Лише фаза deep записує стійку пам’ять до `MEMORY.md`.
- Людинозрозумілий вивід фаз і записи щоденника записуються до `DREAMS.md` (або наявного `dreams.md`), з необов’язковими звітами по фазах у `memory/dreaming/<phase>/YYYY-MM-DD.md`.
- Ранжування використовує зважені сигнали: частота recall, релевантність отримання, різноманітність запитів, часова свіжість, міжденна консолідація та похідне концептуальне багатство.
- Перенесення повторно читає live-щоденну нотатку перед записом до `MEMORY.md`, тож відредаговані або видалені короткострокові уривки не будуть перенесені зі застарілих знімків сховища recall.
- Заплановані й ручні запуски `memory promote` використовують однакові типові параметри фази deep, якщо ви не передасте перевизначення порогів через CLI.
- Ранжування використовує зважені сигнали: частота recall, релевантність відновлення, різноманітність запитів, часова недавність, міжденна консолідація та похідна концептуальна насиченість.
- Під час перенесення щоденна нотатка перечитується в живому стані перед записом до `MEMORY.md`, тому відредаговані або видалені короткочасні уривки не переносяться зі застарілих знімків сховища recall.
- Заплановані та ручні запуски `memory promote` використовують однакові типові параметри фази deep, якщо ви не передасте через CLI перевизначення порогів.
- Автоматичні запуски розподіляються між налаштованими робочими просторами пам’яті.
Типовий розклад:
- **Частота циклу**: `dreaming.frequency = 0 3 * * *`
- **Частота проходів**: `dreaming.frequency = 0 3 * * *`
- **Пороги deep**: `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`, `maxAgeDays=30`
Приклад:
@ -169,13 +171,13 @@ Dreaming — це фонова система консолідації пам’
Примітки:
- `memory index --verbose` виводить подробиці по фазах (provider, model, sources, активність пакетів).
- `memory index --verbose` виводить подробиці по фазах (provider, model, джерела, активність пакетів).
- `memory status` включає будь-які додаткові шляхи, налаштовані через `memorySearch.extraPaths`.
- Якщо фактично активні поля remote API key для пам’яті налаштовано як SecretRef, команда визначає ці значення з активного знімка Gateway. Якщо Gateway недоступний, команда одразу завершується з помилкою.
- Примітка про розбіжність версій Gateway: цей шлях команди потребує Gateway, який підтримує `secrets.resolve`; старіші Gateway повертають помилку unknown-method.
- Налаштовуйте частоту запланованих циклів через `dreaming.frequency`. Політика deep-перенесення в іншому разі є внутрішньою; використовуйте прапорці CLI в `memory promote`, коли вам потрібні разові ручні перевизначення.
- `memory rem-harness --path <file-or-dir> --grounded` показує попередній перегляд grounded `What Happened`, `Reflections` і `Possible Lasting Updates` з історичних щоденних нотаток без будь-якого запису.
- Якщо фактично активні поля ключів віддаленого API пам’яті налаштовані як SecretRef, команда отримує ці значення з активного знімка Gateway. Якщо Gateway недоступний, команда швидко завершується з помилкою.
- Примітка щодо розбіжності версій Gateway: цей шлях команди вимагає Gateway, який підтримує `secrets.resolve`; старіші Gateway повертають помилку unknown-method.
- Налаштовуйте частоту запланованих проходів через `dreaming.frequency`. В іншому політика deep-перенесення є внутрішньою; використовуйте прапорці CLI у `memory promote`, коли потрібні разові ручні перевизначення.
- `memory rem-harness --path <file-or-dir> --grounded` попередньо переглядає grounded `What Happened`, `Reflections` і `Possible Lasting Updates` з історичних щоденних нотаток без жодного запису.
- `memory rem-backfill --path <file-or-dir>` записує оборотні grounded-записи щоденника до `DREAMS.md` для перегляду в UI.
- `memory rem-backfill --path <file-or-dir> --stage-short-term` також додає grounded-сталі кандидати до live-сховища короткострокового перенесення, щоб звичайна фаза deep могла їх ранжувати.
- `memory rem-backfill --rollback` видаляє раніше записані grounded-записи щоденника, а `memory rem-backfill --rollback-short-term` видаляє раніше підготовлених grounded-кандидатів короткострокової пам’яті.
- `memory rem-backfill --path <file-or-dir> --stage-short-term` також засіває grounded-стійких кандидатів до живого сховища перенесення короткочасної пам’яті, щоб звичайна фаза deep могла їх ранжувати.
- `memory rem-backfill --rollback` видаляє раніше записані grounded-записи щоденника, а `memory rem-backfill --rollback-short-term` видаляє раніше підготовлених grounded-кандидатів короткочасної пам’яті.
- Див. [Dreaming](/uk/concepts/dreaming) для повного опису фаз і довідника з конфігурації.

89
docs/uk/cli/models.md
View File

@ -2,13 +2,13 @@
read_when:
- Ви хочете змінити моделі за замовчуванням або переглянути статус автентифікації провайдера
- Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі автентифікації
summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація)
summary: Довідка CLI для `openclaw models` (`status`/`list`/`set`/`scan`, псевдоніми, резервні варіанти, автентифікація)
title: моделі
x-i18n:
generated_at: "2026-04-23T06:24:09Z"
generated_at: "2026-04-23T07:11:26Z"
model: gpt-5.4
provider: openai
source_hash: 3bf7b864ff57af0649bc31443ce77b193d6b3dbb200c53b69ea584fa2e12cbf7
source_hash: d4ba72ca8acb7cc31796c119fce3816e6a919eb28a4ed4b03664d3b222498f5a
source_path: cli/models.md
workflow: 15
---
@ -19,8 +19,9 @@ x-i18n:
Пов’язане:
- Провайдери + моделі: [Моделі](/uk/providers/models)
- Налаштування автентифікації провайдера: [Початок роботи](/uk/start/getting-started)
- Провайдери + моделі: [Models](/uk/providers/models)
- Концепції вибору моделей + slash-команда `/models`: [Models concept](/uk/concepts/models)
- Налаштування автентифікації провайдера: [Getting started](/uk/start/getting-started)
## Поширені команди
@ -31,39 +32,39 @@ openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації.
Коли доступні знімки використання провайдера, розділ статусу OAuth/API-ключів містить
`openclaw models status` показує визначені модель/резервні варіанти за замовчуванням, а також огляд автентифікації.
Коли доступні знімки використання провайдера, розділ статусу OAuth/API key містить
вікна використання провайдера та знімки квот.
Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації використання надходять із
специфічних для провайдера хуків, коли вони доступні; інакше OpenClaw використовує резервний варіант і зіставляє облікові дані OAuth/API-ключів
із профілів автентифікації, env або config.
Codex, MiniMax, Xiaomi і z.ai. Автентифікація використання надходить із хуків,
специфічних для провайдера, коли вони доступні; інакше OpenClaw використовує резервний варіант і зіставляє OAuth/API key
облікові дані з профілів автентифікації, env або конфігурації.
У виводі `--json` `auth.providers` — це огляд провайдерів
з урахуванням env/config/store, а `auth.oauth` — лише стан профілів зі сховища автентифікації.
з урахуванням env/config/store, а `auth.oauth` — лише стан профілів сховища автентифікації.
Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю провайдера.
Перевірки — це реальні запити (можуть споживати токени та спричиняти обмеження швидкості).
Використовуйте `--agent <id>`, щоб переглянути стан моделі/автентифікації налаштованого агента. Якщо не вказано,
команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо їх задано, інакше —
Перевірки — це реальні запити (можуть витрачати токени та спричиняти rate limit).
Використовуйте `--agent <id>`, щоб переглянути стан моделі/автентифікації налаштованого агента. Якщо параметр не вказано,
команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо вони задані, інакше —
налаштованого агента за замовчуванням.
Рядки перевірок можуть походити з профілів автентифікації, облікових даних env або `models.json`.
Рядки перевірок можуть надходити з профілів автентифікації, env-облікових даних або `models.json`.
Примітки:
- `models set <model-or-alias>` приймає `provider/model` або псевдонім.
- `models list --all` включає статичні рядки каталогу вбудованих провайдерів навіть
якщо ви ще не пройшли автентифікацію в цього провайдера. Такі рядки все одно
відображаються як недоступні, доки не буде налаштовано відповідну автентифікацію.
- `models list --all` включає рядки статичного каталогу bundled provider-owned навіть
тоді, коли ви ще не автентифікувалися в цього провайдера. Такі рядки все одно показуються
як недоступні, доки не буде налаштовано відповідну автентифікацію.
- `models list --provider <id>` фільтрує за id провайдера, наприклад `moonshot` або
`openai-codex`. Він не приймає відображувані мітки з інтерактивних
засобів вибору провайдера, наприклад `Moonshot AI`.
- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
- Якщо ви не вкажете провайдера, OpenClaw спочатку визначить введення як псевдонім, потім —
засобів вибору провайдера, як-от `Moonshot AI`.
- Посилання на модель розбираються розділенням за **першим** `/`. Якщо ID моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
- Якщо ви не вказали провайдера, OpenClaw спочатку визначає введення як псевдонім, потім —
як унікальний збіг серед налаштованих провайдерів для цього точного id моделі, і лише після цього
використає резервний варіант із налаштованим провайдером за замовчуванням із попередженням про застарілість.
використовує резервний варіант — налаштованого провайдера за замовчуванням — із попередженням про застарілість.
Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw
використовує резервний варіант і переходить до першої налаштованої пари провайдер/модель, замість того щоб показувати
застаріле значення за замовчуванням для видаленого провайдера.
- `models status` може показувати `marker(<value>)` у виводі автентифікації для незасекречених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
використовує резервний варіант — першу налаштовану пару провайдер/модель — замість показу
застарілого значення за замовчуванням для видаленого провайдера.
- `models status` може показувати `marker(<value>)` у виводі автентифікації для несекретних заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
### `models status`
@ -71,16 +72,16 @@ Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації викор
- `--json`
- `--plain`
- `--check` (код виходу 1=прострочено/відсутнє, 2=скоро спливає)
- `--check` (коди виходу: 1=прострочено/відсутнє, 2=скоро спливає)
- `--probe` (жива перевірка налаштованих профілів автентифікації)
- `--probe-provider <name>` (перевірити один провайдер)
- `--probe-profile <id>` (повторювані або id профілів, розділені комами)
- `--probe-provider <name>` (перевірити одного провайдера)
- `--probe-profile <id>` (повторювані або розділені комами id профілів)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>` (id налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
- `--agent <id>` (id налаштованого агента; має пріоритет над `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
Категорії статусу перевірок:
Категорії статусу перевірки:
- `ok`
- `auth`
@ -91,13 +92,13 @@ Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації викор
- `unknown`
- `no_model`
Варіанти detail/reason-code перевірок, яких варто очікувати:
Випадки detail/reason-code перевірки, яких слід очікувати:
- `excluded_by_auth_order`: збережений профіль існує, але явне
`auth.order.<provider>` його пропустило, тому перевірка повідомляє про виключення, а не
намагається його використати.
- `excluded_by_auth_order`: існує збережений профіль, але явне
`auth.order.<provider>` його не включило, тож перевірка повідомляє про виключення замість
спроби його використати.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
профіль наявний, але не придатний/не може бути визначений.
профіль присутній, але не є придатним/таким, що може бути визначений.
- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити
придатний для перевірки кандидат моделі для цього провайдера.
@ -118,8 +119,8 @@ openclaw models auth paste-token
```
`models auth add` — це інтерактивний помічник автентифікації. Він може запускати потік автентифікації провайдера
(OAuth/API key) або провести вас через ручне вставлення токена, залежно від
обраного провайдера.
(OAuth/API key) або провести вас через ручне вставлення токена — залежно від
вибраного провайдера.
`models auth login` запускає потік автентифікації Plugin провайдера (OAuth/API key). Використовуйте
`openclaw plugins list`, щоб побачити, які провайдери встановлено.
@ -134,13 +135,13 @@ openclaw models auth login --provider openai-codex --set-default
- `setup-token` і `paste-token` залишаються універсальними командами для роботи з токенами для провайдерів,
які надають методи автентифікації токеном.
- `setup-token` вимагає інтерактивний TTY і запускає метод токен-автентифікації провайдера
(типово використовуючи метод `setup-token` цього провайдера, якщо він його надає).
- `paste-token` приймає рядок токена, згенерований деінде або автоматизацією.
- `setup-token` потребує інтерактивного TTY і запускає метод token-auth провайдера
(за замовчуванням використовується метод `setup-token` цього провайдера, якщо він його надає).
- `paste-token` приймає рядок токена, створений деінде або засобами автоматизації.
- `paste-token` вимагає `--provider`, запитує значення токена та записує
його в id профілю за замовчуванням `<provider>:manual`, якщо ви не передасте
`--profile-id`.
- `paste-token --expires-in <duration>` зберігає абсолютний час спливу токена на основі
відносної тривалості, наприклад `365d` або `12h`.
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токенів OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли вони доступні.
- `paste-token --expires-in <duration>` зберігає абсолютний строк дії токена на основі
відносної тривалості, такої як `365d` або `12h`.
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях роботи з токенами OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно.

200
docs/uk/cli/plugins.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Ви хочете встановити або керувати Plugin для Gateway чи сумісними пакетами
- Ви хочете встановити або керувати Plugin Gateway або сумісними пакетами
- Ви хочете налагодити збої завантаження Plugin
summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: plugins
x-i18n:
generated_at: "2026-04-23T06:43:20Z"
generated_at: "2026-04-23T07:11:35Z"
model: gpt-5.4
provider: openai
source_hash: 80e324995fa2dbb5babb9631714eb2449a1c8c00411bf6bf44c4c74bc9a3e2b8
source_hash: 7dd521db1de47ceb183d98a538005d3d816f52ffeee12593bcbaa8014d6e507b
source_path: cli/plugins.md
workflow: 15
---
# `openclaw plugins`
Керуйте Plugin для Gateway, пакетами хуків і сумісними пакетами.
Керуйте Plugin Gateway, наборами hook і сумісними пакетами.
Пов’язане:
@ -46,17 +46,11 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Вбудовані Plugin постачаються разом з OpenClaw. Деякі з них увімкнені за замовчуванням (наприклад,
вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний
Plugin); для інших потрібна команда `plugins enable`.
Вбудовані plugins постачаються разом з OpenClaw. Деякі з них увімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований plugin browser); інші потребують `plugins enable`.
Нативні Plugin OpenClaw мають постачатися з `openclaw.plugin.json` із вбудованою JSON
Schema (`configSchema`, навіть якщо вона порожня). Натомість сумісні пакети використовують
власні маніфести пакетів.
Нативні plugins OpenClaw мають постачатися з `openclaw.plugin.json` із вбудованою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні пакети натомість використовують власні маніфести пакетів.
`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info
також показує підтип пакета (`codex`, `claude` або `cursor`), а також виявлені
можливості пакета.
`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info також показує підтип пакета (`codex`, `claude` або `cursor`) разом із виявленими можливостями пакета.
### Встановлення
@ -64,7 +58,7 @@ Schema (`configSchema`, навіть якщо вона порожня). Нато
openclaw plugins install <package> # спочатку ClawHub, потім npm
openclaw plugins install clawhub:<package> # лише ClawHub
openclaw plugins install <package> --force # перезаписати наявне встановлення
openclaw plugins install <package> --pin # закріпити версію
openclaw plugins install <package> --pin # зафіксувати версію
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # локальний шлях
openclaw plugins install <plugin>@<marketplace> # marketplace
@ -72,77 +66,50 @@ openclaw plugins install <plugin> --marketplace <name> # marketplace (явно)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
Прості назви пакетів спочатку перевіряються в ClawHub, а потім у npm. Примітка щодо безпеки:
ставтеся до встановлення Plugin так, ніби ви запускаєте код. Віддавайте перевагу закріпленим версіям.
Прості назви пакетів спочатку перевіряються в ClawHub, а потім у npm. Примітка щодо безпеки: ставтеся до встановлення plugin так само, як до запуску коду. Віддавайте перевагу зафіксованим версіям.
Якщо конфігурація некоректна, `plugins install` зазвичай безпечно завершується з помилкою і пропонує
спочатку виконати `openclaw doctor --fix`. Єдиний задокументований виняток — вузький
шлях відновлення для вбудованих Plugin, які явно вмикають
`openclaw.install.allowInvalidConfigRecovery`.
Якщо ваш розділ `plugins` підтримується однофайловим `$include`, то `plugins install`, `plugins update`, `plugins enable`, `plugins disable` і `plugins uninstall` записують зміни до цього включеного файлу та не змінюють `openclaw.json`. Кореневі include, масиви include та include із сусідніми перевизначеннями натомість безпечно блокуються, а не розгортаються. Підтримувані форми див. у [Config includes](/uk/gateway/configuration).
`--force` повторно використовує наявну ціль встановлення і перезаписує вже встановлений
Plugin або пакет хуків на місці. Використовуйте його, коли ви свідомо перевстановлюєте
той самий id з нового локального шляху, архіву, пакета ClawHub або npm-артефакту.
Для звичайного оновлення вже відстежуваного npm Plugin краще використовувати
`openclaw plugins update <id-or-npm-spec>`.
Якщо конфігурація невалідна, `plugins install` зазвичай безпечно завершується помилкою і радить спочатку виконати `openclaw doctor --fix`. Єдиний документований виняток — вузький шлях відновлення для вбудованого plugin, доступний для plugins, які явно вмикають `openclaw.install.allowInvalidConfigRecovery`.
`--pin` застосовується лише до встановлень із npm. Він не підтримується з `--marketplace`,
оскільки встановлення з marketplace зберігають метадані джерела marketplace, а не
специфікацію npm.
`--force` повторно використовує наявну ціль встановлення та перезаписує вже встановлений plugin або набір hook на місці. Використовуйте це, коли ви свідомо перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакту npm. Для звичайних оновлень уже відстежуваного npm plugin віддавайте перевагу `openclaw plugins update <id-or-npm-spec>`.
`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацьовувань
вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення навіть
коли вбудований сканер повідомляє про знахідки рівня `critical`, але **не**
обходить блокування політики хуків Plugin `before_install` і **не** обходить збої
сканування.
Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється та пропонує `plugins update <id-or-npm-spec>` для звичайного оновлення або `plugins install <package> --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела.
Цей прапорець CLI застосовується до сценаріїв встановлення/оновлення Plugin. Встановлення
залежностей Skills через Gateway використовують відповідне перевизначення запиту
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим
сценарієм завантаження/встановлення Skills із ClawHub.
`--pin` застосовується лише до встановлень npm. Він не підтримується з `--marketplace`, оскільки встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
`plugins install` також є поверхнею встановлення для пакетів хуків, які експонують
`openclaw.hooks` у `package.json`. Для фільтрованої видимості хуків і вмикання окремих
хуків використовуйте `openclaw hooks`, а не встановлення пакета.
`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацювань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про findings рівня `critical`, але **не** обходить блокування політик hook `before_install` plugin і **не** обходить помилки сканування.
Специфікації npm — **лише для registry** (назва пакета + необов’язкова **точна версія** або
**dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Встановлення
залежностей виконуються з `--ignore-scripts` задля безпеки.
Цей прапорець CLI застосовується до потоків встановлення/оновлення plugin. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub.
Прості специфікації та `@latest` залишаються на стабільній гілці. Якщо npm розв’язує
будь-яку з них у prerelease, OpenClaw зупиняється і просить вас явно погодитися
на це через prerelease-тег, наприклад `@beta`/`@rc`, або точну prerelease-версію,
наприклад `@1.2.3-beta.4`.
`plugins install` також є поверхнею встановлення для наборів hook, які експонують `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої видимості hook і вмикання окремих hook, а не для встановлення пакетів.
Якщо проста специфікація встановлення збігається з id вбудованого Plugin (наприклад `diffs`), OpenClaw
встановлює вбудований Plugin безпосередньо. Щоб установити npm-пакет із такою самою
назвою, використовуйте явну scoped-специфікацію (наприклад `@scope/diffs`).
Специфікації npm є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Для безпеки встановлення залежностей виконуються з `--ignore-scripts`.
Прості специфікації та `@latest` залишаються на стабільній гілці. Якщо npm розв’язує будь-яку з них у prerelease, OpenClaw зупиняється та просить вас явно погодитися за допомогою тега prerelease, такого як `@beta`/`@rc`, або точної версії prerelease, такої як `@1.2.3-beta.4`.
Якщо проста специфікація встановлення збігається з id вбудованого plugin (наприклад, `diffs`), OpenClaw встановлює вбудований plugin напряму. Щоб установити npm-пакет із такою самою назвою, використовуйте явну scoped-специфікацію (наприклад, `@scope/diffs`).
Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
Також підтримуються встановлення з marketplace Claude.
Встановлення з ClawHub використовують явний локатор `clawhub:<package>`:
Встановлення ClawHub використовують явний локатор `clawhub:<package>`:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Тепер OpenClaw також надає перевагу ClawHub для простих npm-безпечних специфікацій Plugin. Він переходить
до npm лише якщо в ClawHub немає цього пакета або версії:
Тепер OpenClaw також надає перевагу ClawHub для простих безпечних для npm специфікацій plugin. До npm він звертається лише тоді, коли в ClawHub немає цього пакета або версії:
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClaw завантажує архів пакета з ClawHub, перевіряє заявлену
сумісність API Plugin / мінімальну сумісність із gateway, а потім установлює його
через звичайний шлях роботи з архівами. Записані встановлення зберігають метадані
джерела ClawHub для подальших оновлень.
OpenClaw завантажує архів пакета з ClawHub, перевіряє заявлену сумісність API plugin / мінімальну сумісність gateway, а потім установлює його через звичайний шлях архіву. Записані встановлення зберігають метадані свого джерела ClawHub для подальших оновлень.
Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному
кеші реєстру Claude за адресою `~/.claude/plugins/known_marketplaces.json`:
Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному кеші реєстру Claude за шляхом `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
@ -162,31 +129,22 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
- назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json`
- локальний корінь marketplace або шлях до `marketplace.json`
- скорочений запис GitHub-репозиторію, наприклад `owner/repo`
- URL GitHub-репозиторію, наприклад `https://github.com/owner/repo`
- скорочений запис GitHub-репозиторію, такий як `owner/repo`
- URL GitHub-репозиторію, такий як `https://github.com/owner/repo`
- git URL
Для віддалених marketplace, завантажених із GitHub або git, записи Plugin мають залишатися
всередині клонованого репозиторію marketplace. OpenClaw приймає джерела з відносними
шляхами з цього репозиторію і відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші
джерела Plugin, що не є шляхами, з віддалених маніфестів.
Для віддалених marketplace, завантажених з GitHub або git, записи plugin мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає відносні джерела шляхів із цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела plugin з віддалених маніфестів.
Для локальних шляхів і архівів OpenClaw автоматично визначає:
Для локальних шляхів і архівів OpenClaw автоматично виявляє:
- нативні Plugin OpenClaw (`openclaw.plugin.json`)
- нативні plugins OpenClaw (`openclaw.plugin.json`)
- сумісні пакети Codex (`.codex-plugin/plugin.json`)
- сумісні пакети Claude (`.claude-plugin/plugin.json` або стандартне компонування
компонентів Claude)
- сумісні пакети Claude (`.claude-plugin/plugin.json` або стандартне компонування компонентів Claude)
- сумісні пакети Cursor (`.cursor-plugin/plugin.json`)
Сумісні пакети встановлюються до звичайного кореня Plugin і беруть участь
у тому самому сценарії list/info/enable/disable. Наразі підтримуються bundle Skills,
command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` /
`lspServers`, оголошені в маніфесті, command-skills Cursor і сумісні
каталоги хуків Codex; інші виявлені можливості пакета показуються в diagnostics/info,
але ще не підключені до виконання під час runtime.
Сумісні пакети встановлюються до звичайного кореня plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються bundle Skills, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / `lspServers`, оголошені в маніфесті, command-skills Cursor і сумісні каталоги hook Codex; інші виявлені можливості пакета показуються в diagnostics/info, але ще не підключені до виконання в runtime.
### List
### Список
```bash
openclaw plugins list
@ -195,22 +153,17 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
Використовуйте `--enabled`, щоб показати лише завантажені Plugin. Використовуйте `--verbose`, щоб перейти
від табличного подання до докладних рядків для кожного Plugin із метаданими
джерела/походження/версії/активації. Використовуйте `--json` для машиночитаного переліку
разом із diagnostics реєстру.
Використовуйте `--enabled`, щоб показати лише завантажені plugins. Використовуйте `--verbose`, щоб перейти від табличного подання до докладних рядків по кожному plugin із метаданими source/origin/version/activation. Використовуйте `--json` для машиночитаного інвентарю та diagnostics реєстру.
Використовуйте `--link`, щоб уникнути копіювання локального каталогу (додає до `plugins.load.paths`):
Використовуйте `--link`, щоб не копіювати локальний каталог (додає до `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
`--force` не підтримується з `--link`, оскільки linked-встановлення повторно використовують
вихідний шлях замість копіювання в керовану ціль встановлення.
`--force` не підтримується з `--link`, оскільки встановлення через посилання повторно використовують вихідний шлях замість копіювання в керовану ціль встановлення.
Використовуйте `--pin` під час встановлень із npm, щоб зберегти точну розв’язану специфікацію (`name@version`) у
`plugins.installs`, зберігаючи типову поведінку без закріплення за замовчуванням.
Використовуйте `--pin` для встановлень npm, щоб зберегти розв’язану точну специфікацію (`name@version`) у `plugins.installs`, зберігаючи типову поведінку без фіксації.
### Видалення
@ -220,13 +173,9 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` видаляє записи Plugin із `plugins.entries`, `plugins.installs`,
списку дозволених Plugin і записів linked `plugins.load.paths`, якщо це застосовно.
Для Plugin Active Memory слот пам’яті скидається до `memory-core`.
`uninstall` видаляє записи plugin з `plugins.entries`, `plugins.installs`, allowlist plugin і пов’язані записи `plugins.load.paths` для встановлень через посилання, якщо це застосовно. Для plugins активної пам’яті слот пам’яті скидається до `memory-core`.
За замовчуванням `uninstall` також видаляє каталог встановлення Plugin у межах активного
кореня plugin у state-dir. Використовуйте
`--keep-files`, щоб зберегти файли на диску.
За замовчуванням uninstall також видаляє каталог встановлення plugin у корені plugin активного state-dir. Використовуйте `--keep-files`, щоб зберегти файли на диску.
`--keep-config` підтримується як застарілий псевдонім для `--keep-files`.
@ -240,38 +189,19 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Оновлення застосовуються до відстежуваних встановлень у `plugins.installs` і відстежуваних
встановлень пакетів хуків у `hooks.internal.installs`.
Оновлення застосовуються до відстежуваних встановлень у `plugins.installs` і відстежуваних встановлень наборів hook у `hooks.internal.installs`.
Коли ви передаєте id Plugin, OpenClaw повторно використовує записану специфікацію встановлення для цього
Plugin. Це означає, що раніше збережені dist-tag, такі як `@beta`, і точні
закріплені версії продовжують використовуватися під час наступних запусків `update <id>`.
Коли ви передаєте id plugin, OpenClaw повторно використовує записану специфікацію встановлення для цього plugin. Це означає, що раніше збережені dist-tag, такі як `@beta`, і точно зафіксовані версії продовжують використовуватися в наступних запусках `update <id>`.
Для встановлень із npm ви також можете передати явну npm-специфікацію пакета з dist-tag
або точною версією. OpenClaw зіставляє цю назву пакета назад із відстежуваним записом Plugin,
оновлює цей установлений Plugin і записує нову npm-специфікацію для майбутніх
оновлень за id.
Для встановлень npm ви також можете передати явну специфікацію npm-пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета назад із відстежуваним записом plugin, оновлює встановлений plugin і записує нову специфікацію npm для майбутніх оновлень за id.
Передавання назви npm-пакета без версії або тега також зіставляє її назад
із відстежуваним записом Plugin. Використовуйте це, коли Plugin було закріплено на точній версії, а
ви хочете повернути його до стандартної гілки релізів реєстру.
Передавання назви npm-пакета без версії чи тега також зіставляється назад із відстежуваним записом plugin. Використовуйте це, коли plugin було зафіксовано на точній версії й ви хочете повернути його на типову лінію релізів реєстру.
Перед живим оновленням із npm OpenClaw перевіряє встановлену версію пакета за метаданими
реєстру npm. Якщо встановлена версія і записана ідентичність артефакту
вже відповідають розв’язаній цілі, оновлення пропускається без
завантаження, перевстановлення або переписування `openclaw.json`.
Перед живим оновленням npm OpenClaw перевіряє встановлену версію пакета за метаданими реєстру npm. Якщо встановлена версія та ідентичність записаного артефакту вже відповідають розв’язаній цілі, оновлення пропускається без завантаження, перевстановлення чи перезапису `openclaw.json`.
Коли існує збережений хеш цілісності й хеш отриманого артефакту змінюється,
OpenClaw трактує це як drift npm-артефакту. Інтерактивна команда
`openclaw plugins update` виводить очікуваний і фактичний хеші та просить
підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення безпечно завершуються з помилкою,
якщо викликач не надає явну політику продовження.
Коли існує збережений хеш цілісності й хеш завантаженого артефакту змінюється, OpenClaw трактує це як дрейф артефакту npm. Інтерактивна команда `openclaw plugins update` виводить очікуваний і фактичний хеші та запитує підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення безпечно завершуються помилкою, якщо виклик не надає явну політику продовження.
`--dangerously-force-unsafe-install` також доступний у `plugins update` як
аварійне перевизначення для хибнопозитивних спрацьовувань вбудованого сканування небезпечного коду під час
оновлень Plugin. Він однаково не обходить блокування політики `before_install`
Plugin або блокування через збої сканування і застосовується лише до оновлень Plugin,
а не до оновлень пакетів хуків.
`--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійне перевизначення для хибнопозитивних спрацювань сканування небезпечного коду під час оновлення plugin. Він усе ще не обходить блокування політик `before_install` plugin або блокування через помилки сканування і застосовується лише до оновлень plugin, а не до оновлень наборів hook.
### Inspect
@ -280,25 +210,20 @@ openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
Глибока інтроспекція для одного Plugin. Показує ідентичність, статус завантаження, джерело,
зареєстровані можливості, хуки, інструменти, команди, сервіси, методи gateway,
HTTP-маршрути, прапорці політик, diagnostics, метадані встановлення, можливості пакета,
а також будь-яку виявлену підтримку MCP або LSP-сервера.
Глибока інтроспекція для одного plugin. Показує ідентичність, стан завантаження, джерело, зареєстровані можливості, hooks, tools, commands, services, methods Gateway, HTTP routes, policy flags, diagnostics, метадані встановлення, можливості пакета та будь-яку виявлену підтримку MCP або LSP server.
Кожен Plugin класифікується за тим, що саме він реєструє під час runtime:
Кожен plugin класифікується за тим, що саме він реєструє в runtime:
- **plain-capability** — один тип можливостей (наприклад, Plugin лише з провайдером)
- **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення)
- **hook-only** — лише хуки, без можливостей або поверхонь
- **non-capability** — інструменти/команди/сервіси, але без можливостей
- **plain-capability** — один тип можливостей (наприклад, plugin лише з provider)
- **hybrid-capability** — кілька типів можливостей (наприклад, text + speech + images)
- **hook-only** — лише hooks, без можливостей або поверхонь
- **non-capability** — tools/commands/services, але без можливостей
Див. [Форми Plugin](/uk/plugins/architecture#plugin-shapes), щоб дізнатися більше про модель можливостей.
Докладніше про модель можливостей див. у [Форми Plugin](/uk/plugins/architecture#plugin-shapes).
Прапорець `--json` виводить машиночитаний звіт, придатний для скриптів і
аудиту.
Прапорець `--json` виводить машиночитаний звіт, придатний для сценаріїв і аудиту.
`inspect --all` відображає загальносистемну таблицю з колонками для shape, видів
можливостей, приміток про сумісність, можливостей пакета і підсумку хуків.
`inspect --all` відображає зведену таблицю для всього набору з колонками shape, capability kinds, compatibility notices, bundle capabilities і hook summary.
`info` — це псевдонім для `inspect`.
@ -308,13 +233,9 @@ HTTP-маршрути, прапорці політик, diagnostics, метад
openclaw plugins doctor
```
`doctor` повідомляє про помилки завантаження Plugin, diagnostics маніфесту/виявлення та
повідомлення про сумісність. Коли все в порядку, він виводить `No plugin issues
detected.`
`doctor` повідомляє про помилки завантаження plugin, diagnostics виявлення/маніфесту та compatibility notices. Коли все в порядку, він виводить `Проблем із plugin не виявлено.`
Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`, повторно виконайте
команду з `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб додати стислий підсумок форми експорту
до diagnostics-виводу.
Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`, перезапустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити компактне зведення форми експорту в diagnostics.
### Marketplace
@ -323,7 +244,4 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Список marketplace приймає локальний шлях до marketplace, шлях до `marketplace.json`,
скорочений запис GitHub на кшталт `owner/repo`, URL GitHub-репозиторію або git URL. `--json`
виводить розв’язану мітку джерела, а також розібраний маніфест marketplace і
записи Plugin.
Список marketplace приймає локальний шлях до marketplace, шлях до `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL GitHub-репозиторію або git URL. `--json` виводить мітку розв’язаного джерела разом із розібраним маніфестом marketplace і записами plugin.

37
docs/uk/cli/tui.md
View File

@ -1,37 +1,38 @@
---
read_when:
- Ви хочете TUI для Gateway (зручно для віддаленої роботи)
- Вам потрібен terminal UI для Gateway (зручний для віддаленої роботи)
- Ви хочете передавати url/token/session зі скриптів
- Ви хочете запускати TUI у локальному вбудованому режимі без Gateway
- Ви хочете запустити TUI у локальному вбудованому режимі без Gateway
- Ви хочете використовувати openclaw chat або openclaw tui --local
summary: Довідка CLI для `openclaw tui` (TUI на основі Gateway або локально вбудований)
title: TUI
summary: Довідка CLI для `openclaw tui` (terminal UI на базі Gateway або локально вбудований)
title: tui
x-i18n:
generated_at: "2026-04-23T06:19:44Z"
generated_at: "2026-04-23T07:12:04Z"
model: gpt-5.4
provider: openai
source_hash: 5f4b7cf2468779e0711f38a2cc304d783bb115fd5c5e573c9d1bc982da6e2905
source_hash: 4fca025a15f5e985ca6f2eaf39fcbe784bd716f24841f43450b71936db26d141
source_path: cli/tui.md
workflow: 15
---
# `openclaw tui`
Відкрийте TUI термінала, підключений до Gateway, або запустіть його в локальному вбудованому
Відкрийте terminal UI, підключений до Gateway, або запустіть його в локальному вбудованому
режимі.
Пов’язано:
- Посібник з TUI: [TUI](/uk/web/tui)
- Посібник TUI: [TUI](/uk/web/tui)
Примітки:
- `chat` і `terminal` — це псевдоніми для `openclaw tui --local`.
- `--local` не можна поєднувати з `--url`, `--token` або `--password`.
- `tui` визначає налаштовані auth SecretRef Gateway для автентифікації токеном/паролем, коли це можливо (`env`/`file`/`exec` providers).
- Якщо запуск відбувається зсередини каталогу налаштованого робочого простору агента, TUI автоматично вибирає цього агента як типове значення ключа сесії (якщо тільки `--session` не задано явно як `agent:<id>:...`).
- Локальний режим використовує вбудоване середовище виконання агента безпосередньо. Більшість локальних інструментів працює, але функції лише Gateway недоступні.
- У локальному режимі до поверхні команд TUI додається `/auth [provider]`.
- `tui` за можливості розв’язує налаштовані SecretRef автентифікації gateway для автентифікації токеном/паролем (`env`/`file`/`exec` providers).
- Якщо запуск відбувається зсередини каталогу налаштованого робочого простору агента, TUI автоматично вибирає цього агента як значення за замовчуванням для ключа сесії (якщо тільки `--session` явно не має вигляду `agent:<id>:...`).
- Локальний режим напряму використовує вбудоване середовище виконання агента. Більшість локальних інструментів працюють, але функції лише для Gateway недоступні.
- Локальний режим додає `/auth [provider]` усередині поверхні команд TUI.
- Обмеження погодження Plugin діють і в локальному режимі. Інструменти, які потребують погодження, запитують рішення в terminal; нічого не погоджується автоматично, оскільки Gateway не бере участі.
## Приклади
@ -48,11 +49,11 @@ openclaw tui --session bugfix
## Цикл виправлення конфігурації
Використовуйте локальний режим, коли поточна конфігурація вже проходить
перевірку і ви хочете, щоб вбудований агент проаналізував її, порівняв із документацією та допоміг виправити
з того самого термінала:
Використовуйте локальний режим, коли поточна конфігурація вже проходить валідацію і ви хочете, щоб
вбудований агент перевірив її, порівняв із документацією та допоміг виправити
з того самого terminal:
Якщо `openclaw config validate` уже завершується помилкою, спочатку використайте `openclaw configure` або
Якщо `openclaw config validate` вже завершується помилкою, спочатку скористайтеся `openclaw configure` або
`openclaw doctor --fix`. `openclaw chat` не обходить захист від недійсної
конфігурації.
@ -69,5 +70,5 @@ openclaw chat
!openclaw doctor
```
Застосовуйте точкові виправлення за допомогою `openclaw config set` або `openclaw configure`, а потім
повторно запускайте `openclaw config validate`. Див. [TUI](/uk/web/tui) і [Config](/uk/cli/config).
Застосуйте цільові виправлення за допомогою `openclaw config set` або `openclaw configure`, а потім
повторно запустіть `openclaw config validate`. Див. [TUI](/uk/web/tui) і [Config](/uk/cli/config).

153
docs/uk/concepts/session-tool.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Ви хочете зрозуміти, які інструменти сеансу має агент
- Ви хочете налаштувати міжсесійний доступ або запуск субагентів
- Ви хочете перевірити статус або керувати запущеними субагентами
summary: Інструменти агентів для міжсесійного статусу, відновлення контексту, обміну повідомленнями та оркестрації субагентів
- Ви хочете зрозуміти, які інструменти сеансу має агент.
- Ви хочете налаштувати міжсеансовий доступ або запуск підлеглих агентів.
- Ви хочете перевірити статус або керувати запущеними підлеглими агентами.
summary: Інструменти агента для міжсеансового статусу, recall, обміну повідомленнями та оркестрації підлеглих агентів
title: Інструменти сеансу
x-i18n:
generated_at: "2026-04-23T01:35:32Z"
generated_at: "2026-04-23T07:11:57Z"
model: gpt-5.4
provider: openai
source_hash: d99408f3052f4fa461bc26bf79456e7f852069ec101b9d593442cef6dd20a3ac
source_hash: cd8b545429726d0880e6086ba7190497861bf3f3e1e88d53cb38ef9e5e4468c6
source_path: concepts/session-tool.md
workflow: 15
---
@ -17,135 +17,136 @@ x-i18n:
# Інструменти сеансу
OpenClaw надає агентам інструменти для роботи між сеансами, перевірки статусу та
оркестрації субагентів.
оркестрації підлеглих агентів.
## Доступні інструменти
| Інструмент | Що він робить |
| ----------------- | -------------------------------------------------------------------------- |
| `sessions_list` | Показує список сеансів з необов’язковими фільтрами (kind, label, agent, recency, preview) |
| `sessions_history` | Читає стенограму конкретного сеансу |
| `sessions_send` | Надсилає повідомлення до іншого сеансу та за потреби очікує |
| `sessions_spawn` | Запускає ізольований сеанс субагента для фонової роботи |
| `sessions_yield` | Завершує поточний хід і очікує на подальші результати субагента |
| `subagents` | Показує список, керує або зупиняє запущені субагенти для цього сеансу |
| `sessions_list` | Перелічує сеанси з необов’язковими фільтрами (тип, мітка, агент, давність, попередній перегляд) |
| `sessions_history`| Читає transcript конкретного сеансу |
| `sessions_send` | Надсилає повідомлення до іншого сеансу й за потреби очікує |
| `sessions_spawn` | Запускає ізольований сеанс підлеглого агента для фонової роботи |
| `sessions_yield` | Завершує поточний хід і очікує подальші результати підлеглого агента |
| `subagents` | Перелічує, спрямовує або зупиняє запущених підлеглих агентів для цього сеансу |
| `session_status` | Показує картку в стилі `/status` і за потреби встановлює перевизначення моделі для сеансу |
## Перелік і читання сеансів
`sessions_list` повертає сеанси з їхнім ключем, agentId, kind, channel, model,
кількістю токенів і часовими мітками. Доступна фільтрація за kind (`main`, `group`, `cron`, `hook`,
`node`), точним `label`, точним `agentId`, текстом пошуку або нещодавністю
(`activeMinutes`). Якщо потрібне сортування в стилі поштової скриньки, можна
також запитати похідні заголовки, прев’ю останніх повідомлень або обмежені
останні повідомлення. Читання прев’ю стенограми обмежене сеансами, видимими
відповідно до налаштованої політики видимості інструментів сеансу.
`sessions_list` повертає сеанси з їхнім ключем, agentId, типом, каналом, моделлю,
кількістю токенів і часовими мітками. Можна фільтрувати за типом (`main`, `group`, `cron`, `hook`,
`node`), точною `label`, точним `agentId`, текстом пошуку або давністю
(`activeMinutes`). Якщо вам потрібне сортування в стилі поштової скриньки, інструмент також може запитувати
похідний заголовок з обмеженням за видимістю, уривок попереднього перегляду останнього повідомлення або
обмежену кількість недавніх повідомлень у кожному рядку. Похідні заголовки та попередні перегляди створюються лише для
сеансів, які викликач уже може бачити відповідно до налаштованої політики
видимості інструментів сеансів, тож не пов’язані сеанси залишаються прихованими.
`sessions_history` отримує стенограму розмови для конкретного сеансу.
За замовчуванням результати інструментів виключено — передайте `includeTools: true`, щоб бачити їх.
Повернутий вигляд навмисно обмежений і відфільтрований з міркувань безпеки:
`sessions_history` отримує transcript розмови для конкретного сеансу.
Типово результати інструментів виключені — передайте `includeTools: true`, щоб їх побачити.
Повернуте представлення навмисно обмежене та відфільтроване з міркувань безпеки:
- текст помічника нормалізується перед відновленням:
- текст assistant нормалізується перед відновленням:
- теги thinking видаляються
- блоки каркаса `<relevant-memories>` / `<relevant_memories>` видаляються
- блоки XML із plain-text викликами інструментів, такі як `<tool_call>...</tool_call>`,
- блоки XML plain-text з даними виклику інструментів, як-от `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` і
`<function_calls>...</function_calls>`, видаляються, включно з усіченими
payload, які так і не закриваються коректно
- знижений до тексту каркас викликів/результатів інструментів, такий як `[Tool Call: ...]`,
`<function_calls>...</function_calls>`, видаляються, зокрема
усічені дані, що так і не закриваються коректно
- спрощений каркас виклику/результату інструмента, як-от `[Tool Call: ...]`,
`[Tool Result ...]` і `[Historical context ...]`, видаляється
- витоки службових токенів керування моделі, такі як `<|assistant|>`, інші ASCII
- витоки службових токенів керування моделлю, як-от `<|assistant|>`, інші ASCII
токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються
- некоректний XML викликів інструментів MiniMax, такий як `<invoke ...>` /
- некоректний XML виклику інструмента MiniMax, як-от `<invoke ...>` /
`</minimax:tool_call>`, видаляється
- текст, схожий на облікові дані/токени, редагується перед поверненням
- довгі текстові блоки усікаються
- у дуже великих історіях старіші рядки можуть відкидатися, або надто великий рядок може бути замінений на
- у дуже великих історіях старіші рядки можуть відкидатися або надто великий рядок може бути замінений на
`[sessions_history omitted: message too large]`
- інструмент повідомляє прапорці зведення, такі як `truncated`, `droppedMessages`,
- інструмент повідомляє зведені прапорці, як-от `truncated`, `droppedMessages`,
`contentTruncated`, `contentRedacted` і `bytes`
Обидва інструменти приймають або **ключ сеансу** (наприклад, `"main"`), або **ID сеансу**
з попереднього виклику списку.
Якщо вам потрібна точна стенограма байт у байт, перегляньте файл стенограми на
диску замість того, щоб вважати `sessions_history` сирим дампом.
Якщо вам потрібен точний transcript побайтно, перевіряйте файл transcript на
диску замість того, щоб вважати `sessions_history` необробленим дампом.
## Надсилання повідомлень між сеансами
`sessions_send` доставляє повідомлення до іншого сеансу та за потреби очікує
на відповідь:
`sessions_send` доставляє повідомлення до іншого сеансу й за потреби очікує
відповідь:
- **Надіслати без очікування:** установіть `timeoutSeconds: 0`, щоб поставити в чергу й
одразу повернутись.
- **Очікування відповіді:** установіть тайм-аут і отримайте відповідь прямо у результаті.
- **Надіслати й не чекати:** установіть `timeoutSeconds: 0`, щоб поставити в чергу та
одразу повернутися.
- **Очікувати відповідь:** установіть тайм-аут і отримайте відповідь вбудовано.
Після того як цільовий сеанс відповість, OpenClaw може запустити **цикл reply-back**,
у якому агенти по черзі обмінюються повідомленнями (до 5 ходів). Цільовий агент може відповісти
`REPLY_SKIP`, щоб зупинити цикл раніше.
Після відповіді цільового сеансу OpenClaw може запустити **цикл відповіді у відповідь**,
де агенти чергують повідомлення (до 5 ходів). Цільовий агент може відповісти
`REPLY_SKIP`, щоб зупинитися раніше.
## Допоміжні інструменти статусу та оркестрації
`session_status` — це полегшений еквівалент `/status` для поточного
`session_status` — це легкий еквівалент `/status` для поточного
або іншого видимого сеансу. Він повідомляє про використання, час, стан моделі/середовища виконання та
пов’язаний контекст фонових задач, якщо він є. Як і `/status`, він може дозаповнювати
розріджені лічильники токенів/кешу з останнього запису використання у стенограмі, а
пов’язаний контекст фонового завдання, якщо він є. Як і `/status`, він може дозаповнювати
розріджені лічильники токенів/кешу з останнього запису про використання в transcript, а
`model=default` очищає перевизначення для конкретного сеансу.
`sessions_yield` навмисно завершує поточний хід, щоб наступним повідомленням могла
стати подія продовження, на яку ви очікуєте. Використовуйте його після запуску субагентів, коли
хочете, щоб результати завершення прийшли як наступне повідомлення, а не через побудову циклів опитування.
`sessions_yield` навмисно завершує поточний хід, щоб наступне повідомлення могло бути
подією продовження, на яку ви чекаєте. Використовуйте його після запуску підлеглих агентів, коли
хочете, щоб результати завершення надійшли наступним повідомленням, а не через побудову циклів опитування.
`subagents` — це допоміжний інструмент площини керування для вже запущених субагентів
OpenClaw. Він підтримує:
`subagents` — це допоміжний інструмент площини керування для вже запущених підлеглих агентів OpenClaw.
Він підтримує:
- `action: "list"` для перегляду активних/нещодавніх запусків
- `action: "list"` для перевірки активних/нещодавніх запусків
- `action: "steer"` для надсилання подальших вказівок запущеному дочірньому агенту
- `action: "kill"` для зупинки одного дочірнього агента або `all`
## Запуск субагентів
## Запуск підлеглих агентів
`sessions_spawn` створює ізольований сеанс для фонової задачі. Він завжди
`sessions_spawn` створює ізольований сеанс для фонового завдання. Він завжди
неблокувальний — одразу повертає `runId` і `childSessionKey`.
Основні параметри:
Ключові параметри:
- `runtime: "subagent"` (типово) або `"acp"` для агентів зовнішнього harness.
- перевизначення `model` і `thinking` для дочірнього сеансу.
- `thread: true`, щоб прив’язати запуск до потоку чату (Discord, Slack тощо).
- `sandbox: "require"`, щоб примусово застосувати sandboxing до дочірнього агента.
- `runtime: "subagent"` (типово) або `"acp"` для зовнішніх harness-агентів.
- Перевизначення `model` і `thinking` для дочірнього сеансу.
- `thread: true`, щоб прив’язати запуск до гілки чату (Discord, Slack тощо).
- `sandbox: "require"`, щоб примусово застосувати sandbox до дочірнього агента.
Типові кінцеві субагенти не отримують інструменти сеансу. Коли
`maxSpawnDepth >= 2`, субагенти-оркестратори глибини 1 додатково отримують
Типові листові підлеглі агенти не отримують інструменти сеансів. Коли
`maxSpawnDepth >= 2`, підлеглі агенти-оркестратори рівня 1 додатково отримують
`sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб вони
могли керувати власними дочірніми агентами. Кінцеві запуски все одно не отримують рекурсивні
інструменти оркестрації.
могли керувати власними дочірніми агентами. Листові запуски все одно не отримують рекурсивних
інструментів оркестрації.
Після завершення крок анонсу публікує результат у канал запитувача.
Доставка завершення зберігає прив’язану маршрутизацію thread/topic, якщо вона доступна, а якщо
джерело завершення визначає лише канал, OpenClaw усе одно може повторно використати
збережений маршрут сеансу запитувача (`lastChannel` / `lastTo`) для прямої
Після завершення крок оголошення публікує результат у канал запитувача.
Доставка завершення зберігає прив’язану маршрутизацію гілки/теми, коли вона доступна, а якщо
джерело завершення ідентифікує лише канал, OpenClaw усе одно може повторно використати збережений маршрут
сеансу запитувача (`lastChannel` / `lastTo`) для прямої
доставки.
Для поведінки, специфічної для ACP, див. [ACP Agents](/uk/tools/acp-agents).
Про поведінку, специфічну для ACP, див. [ACP Agents](/uk/tools/acp-agents).
## Видимість
Інструменти сеансу мають обмежену область видимості, щоб обмежити, що агент може бачити:
Інструменти сеансів мають область видимості, щоб обмежити те, що агент може бачити:
| Рівень | Область видимості |
| Рівень | Область |
| ------- | ---------------------------------------- |
| `self` | Лише поточний сеанс |
| `tree` | Поточний сеанс + запущені субагенти |
| `tree` | Поточний сеанс + запущені підлеглі агенти |
| `agent` | Усі сеанси для цього агента |
| `all` | Усі сеанси (між агентами, якщо налаштовано) |
Типове значення — `tree`. Сеанси в sandbox примусово обмежуються до `tree`
незалежно від конфігурації.
Типове значення — `tree`. Сеанси в sandbox примусово обмежуються до `tree` незалежно від
конфігурації.
## Додаткові матеріали
## Додатково
- [Керування сеансами](/uk/concepts/session) -- маршрутизація, життєвий цикл, обслуговування
- [ACP Agents](/uk/tools/acp-agents) -- запуск через зовнішній harness
- [Багатоагентність](/uk/concepts/multi-agent) -- багатоагентна архітектура
- [Налаштування Gateway](/uk/gateway/configuration) -- параметри конфігурації інструментів сеансу
- [ACP Agents](/uk/tools/acp-agents) -- запуск зовнішнього harness
- [Multi-agent](/uk/concepts/multi-agent) -- багатoагентна архітектура
- [Конфігурація Gateway](/uk/gateway/configuration) -- параметри конфігурації інструментів сеансу

227
docs/uk/gateway/cli-backends.md
View File

@ -1,47 +1,47 @@
---
read_when:
- Вам потрібен надійний резервний варіант, коли API-провайдери зазнають збою
- Ви запускаєте Codex CLI або інші локальні AI CLI й хочете повторно використовувати їх
- Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно їх використовувати
- Ви хочете зрозуміти міст local loopback MCP для доступу CLI-бекенду до інструментів
summary: 'CLI бекенди: локальний резервний AI CLI з необов’язковим мостом інструментів MCP'
summary: 'CLI-бекенди: резервний варіант локального AI CLI з необов’язковим мостом інструментів MCP'
title: CLI-бекенди
x-i18n:
generated_at: "2026-04-23T03:39:15Z"
generated_at: "2026-04-23T07:12:01Z"
model: gpt-5.4
provider: openai
source_hash: d36aea09a97b980e6938e12ea3bb5c01aa5f6c4275879d51879e48d5a2225fb2
source_hash: 475923b36e4580d3e4e57014ff2e6b89e9eb52c11b0a0ab1fc8241655b07836e
source_path: gateway/cli-backends.md
workflow: 15
---
# CLI-бекенди (резервне середовище виконання)
# CLI-бекенди (резервне runtime)
OpenClaw може запускати **локальні AI CLI** як **резервний варіант лише для тексту**, коли API-провайдери недоступні,
обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід:
OpenClaw може запускати **локальні AI CLI** як **текстовий резервний варіант**, коли API-провайдери недоступні,
мають rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід:
- **Інструменти OpenClaw не вбудовуються напряму**, але бекенди з `bundleMcp: true`
можуть отримувати інструменти Gateway через loopback-міст MCP.
- **Інструменти OpenClaw не інжектуються напряму**, але бекенди з `bundleMcp: true`
можуть отримувати інструменти Gateway через міст MCP local loopback.
- **JSONL-стримінг** для CLI, які це підтримують.
- **Сеанси підтримуються** (тому наступні ходи залишаються узгодженими).
- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень.
- **Сесії підтримуються** (тому наступні ходи залишаються узгодженими).
- **Зображення можна передавати наскрізь**, якщо CLI приймає шляхи до зображень.
Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли
вам потрібні текстові відповіді за принципом «завжди працює» без залежності від зовнішніх API.
Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли вам
потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API.
Якщо вам потрібне повне середовище виконання harness із керуванням сеансами ACP, фоновими завданнями,
прив’язкою до потоку/розмови та постійними зовнішніми сеансами кодування, використовуйте
Якщо вам потрібне повноцінне runtime harness із керуванням сесіями ACP, фоновими завданнями,
прив’язкою до thread/conversation і постійними зовнішніми coding sessions, використовуйте
[ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP.
## Швидкий старт для початківців
Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований Plugin OpenAI
Ви можете використовувати Codex CLI **без жодної конфігурації** (bundled plugin OpenAI
реєструє бекенд за замовчуванням):
```bash
openclaw agent --message "hi" --model codex-cli/gpt-5.4
```
Якщо ваш Gateway працює через launchd/systemd і PATH мінімальний, додайте лише
Якщо ваш Gateway працює під launchd/systemd і PATH мінімальний, додайте лише
шлях до команди:
```json5
@ -58,16 +58,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
}
```
І це все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI, не потрібно.
Ось і все. Жодні ключі чи додаткова конфігурація автентифікації не потрібні, окрім самої CLI.
Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на
хості Gateway, OpenClaw тепер автоматично завантажує пов’язаний вбудований Plugin, коли у вашій конфігурації
явно згадано цей бекенд у посиланні на модель або в
Якщо ви використовуєте bundled CLI-бекенд як **основного провайдера повідомлень** на
хості Gateway, OpenClaw тепер автоматично завантажує пов’язаний bundled plugin, коли ваша конфігурація
явно посилається на цей бекенд у model ref або в
`agents.defaults.cliBackends`.
## Використання як резервного варіанта
## Використання як резервного варіанту
Додайте CLI-бекенд до списку резервних, щоб він запускався лише тоді, коли основні моделі не працюють:
Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі зазнають збою:
```json5
{
@ -88,20 +88,20 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
Примітки:
- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі CLI-бекенду.
- Якщо основний провайдер не спрацьовує (автентифікація, обмеження rate limit, тайм-аути), OpenClaw
- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого CLI-бекенду.
- Якщо основний провайдер зазнає збою (автентифікація, rate limit, тайм-аути), OpenClaw
спробує CLI-бекенд наступним.
## Огляд конфігурації
Усі CLI-бекенди розміщуються в:
Усі CLI-бекенди розташовані в:
```
agents.defaults.cliBackends
```
Кожен запис має ключ у вигляді **id провайдера** (наприклад, `codex-cli`, `my-cli`).
Id провайдера стає лівою частиною посилання на модель:
Id провайдера стає лівою частиною вашого посилання на модель:
```
<provider>/<model>
@ -131,7 +131,7 @@ Id провайдера стає лівою частиною посилання
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
// CLI у стилі Codex натомість можуть вказувати на файл prompt:
// CLI у стилі Codex можуть натомість вказувати на файл prompt:
// systemPromptFileConfigArg: "-c",
// systemPromptFileConfigKey: "model_instructions_file",
systemPromptWhen: "first",
@ -148,61 +148,65 @@ Id провайдера стає лівою частиною посилання
## Як це працює
1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`).
2. **Формує системний prompt** із використанням того самого prompt OpenClaw і контексту робочого простору.
3. **Запускає CLI** з id сеансу (якщо підтримується), щоб історія залишалася узгодженою.
Вбудований бекенд `claude-cli` підтримує живий процес Claude stdio для кожного
сеансу OpenClaw і надсилає наступні ходи через stdin stream-json.
2. **Створює system prompt**, використовуючи той самий prompt OpenClaw і контекст робочого простору.
3. **Виконує CLI** з id сесії (якщо підтримується), щоб історія залишалася узгодженою.
Bundled бекенд `claude-cli` підтримує живий процес Claude stdio для кожної
сесії OpenClaw і надсилає наступні ходи через stream-json stdin.
4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст.
5. **Зберігає id сеансів** для кожного бекенду, щоб наступні ходи повторно використовували той самий сеанс CLI.
5. **Зберігає id сесій** для кожного бекенду, щоб наступні ходи повторно використовували ту саму CLI-сесію.
<Note>
Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає
використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує
Bundled бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає
використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує
нову політику.
</Note>
Вбудований бекенд OpenAI `codex-cli` передає системний prompt OpenClaw через
Bundled бекенд OpenAI `codex-cli` передає system prompt OpenClaw через
перевизначення конфігурації Codex `model_instructions_file` (`-c
model_instructions_file="..."`). Codex не надає прапорець на кшталт Claude
model_instructions_file="..."`). Codex не надає прапорець у стилі Claude
`--append-system-prompt`, тому OpenClaw записує зібраний prompt у
тимчасовий файл для кожного нового сеансу Codex CLI.
тимчасовий файл для кожної нової сесії Codex CLI.
Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw
двома способами: компактний каталог Skills OpenClaw у доданому системному prompt і
Bundled бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw
двома способами: компактний каталог Skills OpenClaw у доданому system prompt і
тимчасовий Plugin Claude Code, переданий через `--plugin-dir`. Plugin містить
лише ті Skills, які дозволені для цього агента/сеансу, тому нативний механізм розв’язання Skills у Claude Code
бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в prompt.
Перевизначення env/API key для Skills, як і раніше, застосовуються OpenClaw до середовища дочірнього процесу під час запуску.
лише Skills, допустимі для цього агента/сесії, тож нативний засіб визначення Skills у Claude Code бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в prompt. Перевизначення env/API key для Skills, як і раніше, застосовуються OpenClaw до середовища дочірнього процесу під час виконання.
## Сеанси
## Сесії
- Якщо CLI підтримує сеанси, задайте `sessionArg` (наприклад, `--session-id`) або
`sessionArgs` (з плейсхолдером `{sessionId}`), коли id потрібно вставити
у кілька прапорців.
- Якщо CLI використовує **resume subcommand** з іншими прапорцями, задайте
- Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або
`sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити
в кілька прапорців.
- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте
`resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput`
(для відновлення без JSON).
(для відновлення не у форматі JSON).
- `sessionMode`:
- `always`: завжди передавати id сеансу (новий UUID, якщо нічого не збережено).
- `existing`: передавати id сеансу лише якщо його вже було збережено.
- `none`: ніколи не передавати id сеансу.
- Для `claude-cli` за замовчуванням встановлено `liveSession: "claude-stdio"`, `output: "jsonl"`,
і `input: "stdin"`, тому наступні ходи повторно використовують живий процес Claude, поки
він активний. Якщо Gateway перезапускається або неактивний процес завершується, OpenClaw
відновлюється зі збереженого id сеансу Claude.
- Збережені CLI-сеанси забезпечують безперервність, що належить провайдеру. Неявне щоденне
скидання не обриває їх; `/reset` і явні політики `session.reset` — обривають.
- `always`: завжди передавати id сесії (новий UUID, якщо нічого не збережено).
- `existing`: передавати id сесії лише якщо його вже було збережено.
- `none`: ніколи не передавати id сесії.
- Для `claude-cli` типовими є `liveSession: "claude-stdio"`, `output: "jsonl"`
і `input: "stdin"`, тож наступні ходи повторно використовують живий процес Claude, поки
він активний. Теплий stdio тепер використовується за замовчуванням, зокрема для користувацьких конфігурацій,
які не вказують transport-поля. Якщо Gateway перезапускається або неактивний процес
завершується, OpenClaw відновлює роботу зі збереженого id сесії Claude. Збережені id сесій
перевіряються на наявність доступного для читання наявного project transcript перед
відновленням, тому фантомні прив’язки очищаються з `reason=transcript-missing`
замість тихого запуску нової сесії Claude CLI під `--resume`.
- Збережені CLI-сесії — це безперервність, що належить провайдеру. Неявне щоденне
скидання їх не перериває; `/reset` і явні політики `session.reset` — переривають.
Примітки щодо серіалізації:
- `serialize: true` зберігає впорядкованість запусків в одній доріжці.
- Більшість CLI серіалізують виконання в одній доріжці провайдера.
- OpenClaw скидає повторне використання збереженого CLI-сеансу, коли змінюється вибрана ідентичність автентифікації,
зокрема при зміні id профілю автентифікації, статичного API key, статичного токена або OAuth-ідентичності облікового запису, якщо CLI її надає. Ротація токенів доступу й оновлення OAuth не обриває збережений CLI-сеанс. Якщо CLI не надає
стабільний id OAuth-акаунта, OpenClaw дозволяє цій CLI самій забезпечувати дозволи на відновлення.
- `serialize: true` зберігає впорядкованість запусків у тій самій lane.
- Більшість CLI серіалізують виконання в одній lane провайдера.
- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється вибрана автентифікаційна ідентичність,
зокрема змінюється id профілю автентифікації, статичний API key, статичний токен або OAuth-ідентичність
облікового запису, якщо CLI її надає. Ротація access і refresh токенів OAuth не
перериває збережену CLI-сесію. Якщо CLI не надає стабільний id OAuth-облікового запису,
OpenClaw дозволяє цій CLI самій контролювати права на відновлення.
## Зображення (пряма передача)
## Зображення (наскрізна передача)
Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`:
@ -211,28 +215,29 @@ imageArg: "--image",
imageMode: "repeat"
```
OpenClaw записуватиме зображення base64 у тимчасові файли. Якщо задано `imageArg`, ці
OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці
шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає
шляхи до файлів у prompt (path injection), чого достатньо для CLI, які автоматично
шляхи до файлів у prompt (інжекція шляху), чого достатньо для CLI, які автоматично
завантажують локальні файли зі звичайних шляхів.
## Входи / виходи
- `output: "json"` (типово) намагається розібрати JSON і витягти текст + id сеансу.
- `output: "json"` (типово) намагається розібрати JSON і витягти текст + id сесії.
- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а
usage — зі `stats`, якщо `usage` відсутній або порожній.
- `output: "jsonl"` розбирає JSONL-потоки (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента, а також ідентифікатори сеансу, якщо вони є.
- `output: "text"` обробляє stdout як фінальну відповідь.
використання — зі `stats`, коли `usage` відсутнє або порожнє.
- `output: "jsonl"` розбирає потоки JSONL (наприклад Codex CLI `--json`) і витягує фінальне повідомлення агента разом з ідентифікаторами сесії,
коли вони присутні.
- `output: "text"` трактує stdout як фінальну відповідь.
Режими вводу:
Режими введення:
- `input: "arg"` (типово) передає prompt як останній аргумент CLI.
- `input: "stdin"` надсилає prompt через stdin.
- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin.
## Значення за замовчуванням (належать Plugin)
## Типові значення (належать plugin)
Вбудований Plugin OpenAI також реєструє значення за замовчуванням для `codex-cli`:
Bundled plugin OpenAI також реєструє типові значення для `codex-cli`:
- `command: "codex"`
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@ -243,7 +248,7 @@ OpenClaw записуватиме зображення base64 у тимчасо
- `imageArg: "--image"`
- `sessionMode: "existing"`
Вбудований Plugin Google також реєструє значення за замовчуванням для `google-gemini-cli`:
Bundled plugin Google також реєструє типові значення для `google-gemini-cli`:
- `command: "gemini"`
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@ -258,28 +263,28 @@ OpenClaw записуватиме зображення base64 у тимчасо
`gemini` у `PATH` (`brew install gemini-cli` або
`npm install -g @google/gemini-cli`).
Примітки щодо Gemini CLI JSON:
Примітки щодо JSON Gemini CLI:
- Текст відповіді читається з поля JSON `response`.
- Usage береться зі `stats`, якщо `usage` відсутній або порожній.
- `stats.cached` нормалізується до OpenClaw `cacheRead`.
- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із
- Використання бере резервний варіант зі `stats`, коли `usage` відсутнє або порожнє.
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
- Якщо `stats.input` відсутнє, OpenClaw обчислює вхідні токени з
`stats.input_tokens - stats.cached`.
Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`).
Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`).
## Значення за замовчуванням, що належать Plugin
## Типові значення, що належать Plugin
Значення за замовчуванням CLI-бекендів тепер є частиною поверхні Plugin:
Типові значення CLI-бекенду тепер є частиною поверхні Plugin:
- Plugins реєструють їх через `api.registerCliBackend(...)`.
- `id` бекенду стає префіксом провайдера в посиланнях на моделі.
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` як і раніше перевизначає значення Plugin за замовчуванням.
- Очищення конфігурації, специфічне для бекенду, залишається у власності Plugin через необов’язковий
hook `normalizeConfig`.
- `id` бекенду стає префіксом провайдера в посиланнях на модель.
- Користувацька конфігурація в `agents.defaults.cliBackends.<id>` як і раніше перевизначає типові значення Plugin.
- Очищення конфігурації, специфічне для бекенду, залишається відповідальністю plugin через необов’язковий
хук `normalizeConfig`.
Plugins, яким потрібні малі шими сумісності prompt/повідомлень, можуть оголошувати
двоспрямовані текстові трансформації без заміни провайдера чи CLI-бекенду:
Plugins, яким потрібні невеликі сумісні shim-перетворення prompt/повідомлень, можуть оголошувати
двонапрямні текстові перетворення без заміни провайдера або CLI-бекенду:
```typescript
api.registerTextTransforms({
@ -296,52 +301,52 @@ api.registerTextTransforms({
});
```
`input` переписує системний prompt і користувацький prompt, які передаються CLI. `output`
переписує стримінгові delta помічника і розібраний фінальний текст до того, як OpenClaw обробить
власні control markers і доставку в канал.
`input` переписує system prompt і user prompt, передані до CLI. `output`
переписує стримінгові deltas помічника та розібраний фінальний текст до того, як OpenClaw обробить
власні control markers і доставку через канали.
Для CLI, які виводять JSONL, сумісний із Claude Code stream-json, задайте
Для CLI, які видають JSONL, сумісний із Claude Code stream-json, задайте
`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенду.
## Bundle MCP overlays
CLI-бекенди **не** отримують виклики інструментів OpenClaw напряму, але бекенд може
увімкнути згенерований MCP config overlay через `bundleMcp: true`.
увімкнути згенерований накладений MCP-конфіг через `bundleMcp: true`.
Поточна вбудована поведінка:
Поточна bundled-поведінка:
- `claude-cli`: згенерований строгий MCP config file
- `claude-cli`: згенерований strict MCP config file
- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`
- `google-gemini-cli`: згенерований файл системних налаштувань Gemini
Коли bundle MCP увімкнено, OpenClaw:
- запускає loopback HTTP MCP-сервер, який відкриває інструменти Gateway для процесу CLI
- автентифікує міст за допомогою токена на рівні сеансу (`OPENCLAW_MCP_TOKEN`)
- обмежує доступ до інструментів поточним сеансом, акаунтом і контекстом каналу
- завантажує увімкнені bundle-MCP-сервери для поточного робочого простору
- об’єднує їх із наявною формою MCP-конфігурації/налаштувань бекенду
- переписує конфігурацію запуску з використанням режиму інтеграції, що належить бекенду з розширення-власника
- запускає loopback HTTP MCP-сервер, який надає інструменти Gateway процесу CLI
- автентифікує міст за допомогою токена на рівні сесії (`OPENCLAW_MCP_TOKEN`)
- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу
- завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору
- об’єднує їх із будь-якою наявною формою MCP-конфігурації/налаштувань бекенду
- переписує конфігурацію запуску з використанням режиму інтеграції, що належить бекенду, від розширення-власника
Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно вбудовує строгий config, коли
Якщо жоден MCP-сервер не ввімкнено, OpenClaw все одно інжектує strict config, коли
бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими.
## Обмеження
- **Жодних прямих викликів інструментів OpenClaw.** OpenClaw не вбудовує виклики інструментів у
протокол CLI-бекенду. Бекенди бачать інструменти Gateway лише тоді, коли вмикають
- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у
протокол CLI-бекенду. Бекенди бачать інструменти Gateway лише тоді, коли вони вмикають
`bundleMcp: true`.
- **Стримінг залежить від бекенду.** Деякі бекенди передають JSONL потоком; інші буферизують
- **Стримінг залежить від бекенду.** Деякі бекенди стримлять JSONL; інші буферизують
до завершення.
- **Структуровані виходи** залежать від JSON-формату CLI.
- **Сеанси Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш
структуровано, ніж початковий запуск `--json`. Сеанси OpenClaw при цьому, як і раніше, працюють
- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш
структуровано, ніж початковий запуск `--json`. Сесії OpenClaw при цьому все одно працюють
нормально.
## Усунення проблем
## Усунення несправностей
- **CLI не знайдено**: задайте `command` як повний шлях.
- **CLI не знайдено**: установіть `command` на повний шлях.
- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
- **Немає безперервності сеансу**: переконайтеся, що задано `sessionArg` і `sessionMode` не дорівнює
- **Немає безперервності сесії**: переконайтеся, що `sessionArg` задано, а `sessionMode` не дорівнює
`none` (Codex CLI наразі не може відновлюватися з JSON-виводом).
- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів).
- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).

416
docs/uk/gateway/configuration.md
View File

@ -1,37 +1,38 @@
---
read_when:
- Налаштування OpenClaw уперше
- Перше налаштування OpenClaw
- Пошук поширених шаблонів конфігурації
- Перехід до певних розділів конфігурації
- Перехід до конкретних розділів конфігурації
summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник'
title: Конфігурація
x-i18n:
generated_at: "2026-04-22T23:11:30Z"
generated_at: "2026-04-23T07:12:02Z"
model: gpt-5.4
provider: openai
source_hash: 39a9f521b124026a32064464b6d0ce1f93597c523df6839fde37d61e597bcce7
source_hash: 8130d29e9fbf5104d0a76f26b26186b6aab2b211030b8c8ba0d1131daf890993
source_path: gateway/configuration.md
workflow: 15
---
# Конфігурація
OpenClaw зчитує необов’язкову конфігурацію <Tooltip tip="JSON5 підтримує коментарі та кінцеві коми">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
OpenClaw читає необов’язкову конфігурацію <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> з `~/.openclaw/openclaw.json`.
Активний шлях до конфігурації має бути звичайним файлом. Макети
`openclaw.json` із символьними посиланнями не підтримуються для записів, якими керує OpenClaw; атомарний запис може замінити
шлях замість збереження символьного посилання. Якщо ви зберігаєте конфігурацію поза
типовим каталогом стану, вкажіть `OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл.
`openclaw.json` із symlink не підтримуються для записів, якими керує OpenClaw;
атомарний запис може замінити шлях замість збереження symlink. Якщо ви
зберігаєте конфігурацію поза типовим каталогом стану, вкажіть
`OPENCLAW_CONFIG_PATH` безпосередньо на реальний файл.
Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Поширені причини додати конфігурацію:
Якщо файл відсутній, OpenClaw використовує безпечні типові значення. Поширені причини додати конфігурацію:
- Підключити канали та керувати тим, хто може писати боту
- Підключити канали та контролювати, хто може надсилати повідомлення боту
- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks)
- Налаштувати сесії, медіа, мережу або UI
Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля.
Дивіться [повний довідник](/uk/gateway/configuration-reference) для всіх доступних полів.
<Tip>
**Ви вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) для готових конфігурацій, які можна повністю скопіювати й вставити.
**Вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) для готових конфігурацій, які можна скопіювати й вставити.
</Tip>
## Мінімальна конфігурація
@ -49,8 +50,8 @@ OpenClaw зчитує необов’язкову конфігурацію <Tool
<Tabs>
<Tab title="Інтерактивний майстер">
```bash
openclaw onboard # full onboarding flow
openclaw configure # config wizard
openclaw onboard # повний процес початкового налаштування
openclaw configure # майстер конфігурації
```
</Tab>
<Tab title="CLI (однорядкові команди)">
@ -62,73 +63,74 @@ OpenClaw зчитує необов’язкову конфігурацію <Tool
</Tab>
<Tab title="Control UI">
Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**.
Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів
`title` / `description`, а також схемами plugin і каналів, коли вони
доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих
UI та інших інструментів gateway також надає `config.schema.lookup`, щоб
отримати один вузол схеми для конкретного шляху разом із підсумками безпосередніх дочірніх елементів.
Control UI рендерить форму з живої схеми конфігурації, включно з
метаданими документації полів `title` / `description`, а також схемами Plugin і каналів,
коли вони доступні, з редактором **Raw JSON** як запасним варіантом. Для
інтерфейсів із поглибленим переглядом та інших інструментів gateway також
надає `config.schema.lookup`, щоб отримати один вузол схеми для заданого шляху
разом із підсумками безпосередніх дочірніх елементів.
</Tab>
<Tab title="Пряме редагування">
Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway стежить за файлом і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)).
</Tab>
</Tabs>
## Сувора валідація
## Строга валідація
<Warning>
OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema.
OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, неправильні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema.
</Warning>
Примітки щодо інструментів схеми:
- `openclaw config schema` виводить ту саму родину JSON Schema, яку використовують Control UI
- `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI
і валідація конфігурації.
- Сприймайте вивід цієї схеми як канонічний машиночитний контракт для
`openclaw.json`; цей огляд і довідник із конфігурації лише узагальнюють його.
- Значення полів `title` і `description` переносяться до виводу схеми для
- Розглядайте цей вивід схеми як канонічний машинозчитуваний контракт для
`openclaw.json`; цей огляд і довідник конфігурації його узагальнюють.
- Значення полів `title` і `description` переносяться у вивід схеми для
редакторів і інструментів форм.
- Вкладені об’єкти, шаблони (`*`) і елементи масивів (`[]`) успадковують ті самі
- Вкладені об’єкти, записи wildcard (`*`) і записи елементів масиву (`[]`) успадковують ті самі
метадані документації там, де існує відповідна документація поля.
- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі
метадані документації, тож варіанти union/intersection зберігають однакові підказки для полів.
метадані документації, тому варіанти union/intersection зберігають ті самі підказки для полів.
- `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким
вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі
та подібні поля валідації), відповідними метаданими підказок UI та підсумками безпосередніх дочірніх елементів
для інструментів детального перегляду.
- Схеми plugin/каналів середовища виконання об’єднуються, коли gateway може завантажити
та подібні поля валідації), відповідними метаданими UI-підказок і підсумками
безпосередніх дочірніх елементів для інструментів із поглибленим переглядом.
- Схеми Plugin/каналів часу виконання об’єднуються, коли gateway може завантажити
поточний реєстр маніфестів.
- `pnpm config:docs:check` виявляє розходження між артефактами базового рівня конфігурації для документації
і поточною поверхнею схеми.
- `pnpm config:docs:check` виявляє розходження між артефактами базової конфігурації
для документації та поточною поверхнею схеми.
Коли валідація не проходить:
- Gateway не запускається
- Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
- Запустіть `openclaw doctor`, щоб побачити точні проблеми
- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення
- Виконайте `openclaw doctor`, щоб побачити точні проблеми
- Виконайте `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення
Gateway також зберігає довірену останню відому справну копію після успішного запуску. Якщо
`openclaw.json` пізніше буде змінено поза OpenClaw і він більше не проходитиме валідацію, під час запуску
та гарячого перезавантаження пошкоджений файл буде збережено як позначений часовою міткою знімок `.clobbered.*`,
відновлено останню відому справну копію та записано помітне попередження з причиною відновлення.
Відновлення читання під час запуску також розглядає різкі зменшення розміру, відсутні метадані конфігурації та
відсутній `gateway.mode` як критичні ознаки пошкодження, якщо остання відома справна
Gateway також зберігає довірену останню відому коректну копію після успішного запуску. Якщо
`openclaw.json` пізніше змінено поза OpenClaw і він більше не проходить валідацію, запуск
і гаряче перезавантаження зберігають пошкоджений файл як знімок `.clobbered.*` з часовою міткою,
відновлюють останню відому коректну копію та записують помітне попередження з причиною відновлення.
Відновлення під час читання на запуску також трактує різке зменшення розміру, відсутність метаданих конфігурації та
відсутній `gateway.mode` як критичні ознаки пошкодження, коли остання відома коректна
копія містила ці поля.
Якщо перед інакше коректною JSON-конфігурацією випадково додається рядок статусу/журналу,
під час запуску gateway і `openclaw doctor --fix` можна видалити цей префікс,
запуск gateway і `openclaw doctor --fix` можуть видалити цей префікс,
зберегти забруднений файл як `.clobbered.*` і продовжити роботу з відновленим
JSON.
Наступний хід головного агента також отримує попередження події системи, яке повідомляє, що
конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої відомої справної копії
відбувається після перевіреного запуску та після прийнятих гарячих перезавантажень, включно із
записами конфігурації, якими керує OpenClaw, коли хеш збереженого файла все ще збігається з прийнятим
записом. Оновлення пропускається, якщо кандидат містить замасковані заповнювачі
секретів, такі як `***` або скорочені значення токенів.
Наступний хід основного агента також отримує попередження через системну подію про те, що
конфігурацію було відновлено і її не можна бездумно перезаписувати. Просування останньої відомої коректної копії
оновлюється після валідованого запуску та після прийнятих гарячих перезавантажень, включно з
записами конфігурації, якими керує OpenClaw, якщо хеш збереженого файла все ще збігається з прийнятим
записом. Просування пропускається, коли кандидат містить відредаговані
placeholder-и секретів, такі як `***` або скорочені значення токенів.
## Поширені завдання
<AccordionGroup>
<Accordion title="Налаштувати канал (WhatsApp, Telegram, Discord тощо)">
<Accordion title="Налаштування каналу (WhatsApp, Telegram, Discord тощо)">
Кожен канал має власний розділ конфігурації в `channels.<provider>`. Дивіться окрему сторінку каналу для кроків налаштування:
- [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp`
@ -142,7 +144,7 @@ JSON.
- [iMessage](/uk/channels/imessage) — `channels.imessage`
- [Mattermost](/uk/channels/mattermost) — `channels.mattermost`
Усі канали використовують однаковий шаблон політики приватних повідомлень:
Усі канали використовують однаковий шаблон політики DM:
```json5
{
@ -151,7 +153,7 @@ JSON.
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["tg:123"], // only for allowlist/open
allowFrom: ["tg:123"], // лише для allowlist/open
},
},
}
@ -159,8 +161,8 @@ JSON.
</Accordion>
<Accordion title="Вибрати й налаштувати моделі">
Установіть основну модель і необов’язкові резервні варіанти:
<Accordion title="Вибір і налаштування моделей">
Установіть основну модель і необов’язкові fallback:
```json5
{
@ -179,31 +181,31 @@ JSON.
}
```
- `agents.defaults.models` визначає каталог моделей і працює як список дозволених значень для `/model`.
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додавати записи до списку дозволених значень без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`.
- Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`).
- `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у запусках із великою кількістю знімків екрана.
- Дивіться [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover) для ротації автентифікації та поведінки резервування.
- Для користувацьких/self-hosted провайдерів дивіться [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику.
- `agents.defaults.models` визначає каталог моделей і працює як allowlist для `/model`.
- Використовуйте `openclaw config set agents.defaults.models '<json>' --strict-json --merge`, щоб додавати записи до allowlist без видалення наявних моделей. Звичайні заміни, які видалили б записи, відхиляються, якщо ви не передасте `--replace`.
- Посилання на модель використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`).
- `agents.defaults.imageMaxDimensionPx` керує зменшенням масштабу зображень транскрипту/інструментів (типово `1200`); менші значення зазвичай зменшують використання vision-токенів під час запусків із великою кількістю знімків екрана.
- Дивіться [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації та поведінки fallback.
- Для користувацьких/self-hosted provider дивіться [Користувацькі providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику.
</Accordion>
<Accordion title="Керувати тим, хто може писати боту">
Доступ до приватних повідомлень контролюється окремо для кожного каналу через `dmPolicy`:
<Accordion title="Контроль того, хто може надсилати повідомлення боту">
Доступ до DM контролюється для кожного каналу через `dmPolicy`:
- `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження
- `"allowlist"`: лише відправники в `allowFrom` (або в парному сховищі дозволених)
- `"open"`: дозволити всі вхідні приватні повідомлення (потрібно `allowFrom: ["*"]`)
- `"disabled"`: ігнорувати всі приватні повідомлення
- `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для підтвердження
- `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow)
- `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`)
- `"disabled"`: ігнорувати всі DM
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або специфічні для каналу списки дозволених значень.
Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist-и, специфічні для каналу.
Дивіться [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу.
Дивіться [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для деталей по каналах.
</Accordion>
<Accordion title="Налаштувати фільтрацію згадок у групових чатах">
Групові повідомлення типово **вимагають згадки**. Налаштуйте шаблони для кожного агента:
<Accordion title="Налаштування gating згадок у груповому чаті">
Повідомлення в групах типово **вимагають згадки**. Налаштовуйте шаблони для кожного агента:
```json5
{
@ -225,15 +227,15 @@ JSON.
}
```
- **Метадані згадок**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо)
- **Текстові шаблони**: безпечні шаблони regex у `mentionPatterns`
- **Згадки в метаданих**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо)
- **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns`
- Дивіться [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень по каналах і режиму self-chat.
</Accordion>
<Accordion title="Обмежити Skills для кожного агента">
Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретних
агентів через `agents.list[].skills`:
<Accordion title="Обмеження Skills для кожного агента">
Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретні
агенти через `agents.list[].skills`:
```json5
{
@ -242,24 +244,24 @@ JSON.
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
{ id: "locked-down", skills: [] }, // no skills
{ id: "writer" }, // успадковує github, weather
{ id: "docs", skills: ["docs-search"] }, // замінює типові значення
{ id: "locked-down", skills: [] }, // без Skills
],
},
}
```
- Опустіть `agents.defaults.skills`, щоб типово Skills не були обмежені.
- Опустіть `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
- Не вказуйте `agents.defaults.skills`, щоб типово Skills не були обмежені.
- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення.
- Установіть `agents.list[].skills: []`, щоб не було Skills.
- Дивіться [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і
[довідник із конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills).
- Дивіться [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і
[Довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills).
</Accordion>
<Accordion title="Налаштувати моніторинг стану каналів gateway">
Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають неактивними:
<Accordion title="Налаштування моніторингу стану каналів gateway">
Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають застарілими:
```json5
{
@ -281,20 +283,20 @@ JSON.
}
```
- Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану.
- Установіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски за моніторингом стану.
- `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки.
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора.
- Дивіться [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
- Використовуйте `channels.<provider>.healthMonitor.enabled` або `channels.<provider>.accounts.<id>.healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального монітора.
- Дивіться [Перевірки стану](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів.
</Accordion>
<Accordion title="Налаштувати сесії та скидання">
Сесії керують безперервністю та ізоляцією розмов:
<Accordion title="Налаштування сесій і скидань">
Сесії керують безперервністю розмови та ізоляцією:
```json5
{
session: {
dmScope: "per-channel-peer", // recommended for multi-user
dmScope: "per-channel-peer", // рекомендовано для багатокористувацького режиму
threadBindings: {
enabled: true,
idleHours: 24,
@ -309,15 +311,15 @@ JSON.
}
```
- `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
- Дивіться [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання.
- `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: глобальні типові значення для маршрутизації сесій, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`).
- Дивіться [Керування сесіями](/uk/concepts/session) для області видимості, зв’язків ідентичності та політики надсилання.
- Дивіться [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів.
</Accordion>
<Accordion title="Увімкнути ізоляцію">
Запускайте сесії агентів в ізольованих середовищах ізоляції:
<Accordion title="Увімкнення ізоляції">
Запускайте сесії агента в ізольованих середовищах sandbox:
```json5
{
@ -338,10 +340,10 @@ JSON.
</Accordion>
<Accordion title="Увімкнути push через relay для офіційних збірок iOS">
Push через relay налаштовується в `openclaw.json`.
<Accordion title="Увімкнення relay-backed push для офіційних збірок iOS">
Relay-backed push налаштовується в `openclaw.json`.
Установіть це в конфігурації gateway:
Установіть у конфігурації gateway таке:
```json5
{
@ -350,7 +352,7 @@ JSON.
apns: {
relay: {
baseUrl: "https://relay.example.com",
// Необов’язково. Типово: 10000
// Необов’язково. Типове значення: 10000
timeoutMs: 10000,
},
},
@ -365,37 +367,37 @@ JSON.
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```
Що це робить:
Що це дає:
- Дозволяє gateway надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній relay.
- Використовує grant надсилання з областю дії реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен relay-токен для всього розгортання.
- Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою спарився застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію.
- Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційно розповсюджених збірок, які зареєструвалися через relay.
- Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay.
- Дає змогу gateway надсилати `push.test`, сигнали пробудження та сигнали пробудження для перепідключення через зовнішній relay.
- Використовує прив’язаний до реєстрації дозвіл на надсилання, який пересилає спарений застосунок iOS. Gateway не потребує relay-токена для всього розгортання.
- Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою застосунок iOS було спарено, тож інший gateway не зможе повторно використати збережену реєстрацію.
- Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційних поширюваних збірок, які зареєструвалися через relay.
- Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання досягав того самого розгортання relay.
Повний потік роботи:
Наскрізний процес:
1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay.
2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway.
3. Спаріть застосунок iOS з gateway і дозвольте підключитися як сесіям node, так і сесіям оператора.
4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` із relay у спарений gateway.
5. Gateway зберігає relay handle і grant надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для повторного підключення.
1. Установіть офіційну/TestFlight збірку iOS, зібрану з тим самим базовим URL relay.
2. Налаштуйте `gateway.push.apns.relay.baseUrl` у gateway.
3. Спарте застосунок iOS із gateway і дозвольте підключитися як сесії node, так і сесії оператора.
4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` у спарений gateway.
5. Gateway зберігає relay handle і дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та сигналів пробудження для перепідключення.
Операційні примітки:
- Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway.
- Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює свій кешований relay-реєстраційний запис замість повторного використання старого relay-джерела.
- Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює свій кешований relay-запис замість повторного використання старого relay-origin.
Примітка щодо сумісності:
- `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається аварійним варіантом для розробки лише в loopback; не зберігайте URL relay з HTTP у конфігурації.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається засобом для розробки лише через loopback; не зберігайте HTTP URL relay у конфігурації.
Дивіться [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного потоку роботи та [Потік автентифікації та довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay.
Дивіться [Застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Автентифікація і модель довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay.
</Accordion>
<Accordion title="Налаштувати Heartbeat (періодичні перевірки)">
<Accordion title="Налаштування Heartbeat (періодичні перевірки)">
```json5
{
agents: {
@ -411,12 +413,12 @@ JSON.
- `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути.
- `target`: `last` | `none` | `<channel-id>` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`)
- `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі приватних повідомлень
- `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM
- Дивіться [Heartbeat](/uk/gateway/heartbeat) для повного посібника.
</Accordion>
<Accordion title="Налаштувати завдання Cron">
<Accordion title="Налаштування cron-завдань">
```json5
{
cron: {
@ -431,14 +433,14 @@ JSON.
}
```
- `sessionRetention`: видаляти завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю рядків, які потрібно зберегти.
- Дивіться [Завдання Cron](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI.
- `sessionRetention`: очищати завершені сесії ізольованих запусків із `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути).
- `runLog`: очищати `cron/runs/<jobId>.jsonl` за розміром і кількістю збережених рядків.
- Дивіться [Cron jobs](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI.
</Accordion>
<Accordion title="Налаштувати Webhook (hooks)">
Увімкніть HTTP-ендпоїнти Webhook на Gateway:
<Accordion title="Налаштування Webhook-ів (hooks)">
Увімкніть HTTP-кінцеві точки Webhook на Gateway:
```json5
{
@ -462,20 +464,20 @@ JSON.
```
Примітка щодо безпеки:
- Сприймайте весь вміст payload hook/webhook як недовірене введення.
- Уважайте весь вміст payload hook/Webhook ненадійним вхідним даними.
- Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway.
- Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються.
- `hooks.path` не може бути `/`; тримайте вхідний трафік webhook на окремому підшляху, наприклад `/hooks`.
- Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузько спрямоване налагодження.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які вибирає викликач.
- Для агентів, що запускаються через hook, надавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо).
- Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються.
- `hooks.path` не може бути `/`; тримайте вхідний Webhook-трафік на окремому підшляху, наприклад `/hooks`.
- Залишайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сесій, які обирає викликач.
- Для агентів, що запускаються через hook, надавайте перевагу потужним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише повідомлення плюс sandboxing, де це можливо).
Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mapping і інтеграції Gmail.
Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mappings та інтеграції Gmail.
</Accordion>
<Accordion title="Налаштувати маршрутизацію з кількома агентами">
Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями:
<Accordion title="Налаштування маршрутизації між кількома агентами">
Запускайте кілька ізольованих агентів з окремими робочими просторами та сесіями:
```json5
{
@ -492,12 +494,12 @@ JSON.
}
```
Дивіться [Кілька агентів](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил binding і профілів доступу для кожного агента.
Дивіться [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил bindings і профілів доступу для кожного агента.
</Accordion>
<Accordion title="Розділити конфігурацію на кілька файлів ($include)">
Використовуйте `$include`, щоб упорядкувати великі конфігурації:
<Accordion title="Розділення конфігурації на кілька файлів ($include)">
Використовуйте `$include` для організації великих конфігурацій:
```json5
// ~/.openclaw/openclaw.json
@ -510,48 +512,47 @@ JSON.
}
```
- **Один файл**: замінює об’єкт, що його містить
- **Масив файлів**: глибоко об’єднується за порядком (пізніші мають пріоритет)
- **Сусідні ключі**: об’єднуються після include (перевизначають включені значення)
- **Вкладені include**: підтримуються до 10 рівнів вкладеності
- **Відносні шляхи**: обчислюються відносно файла, що включає
- **Один файл**: замінює об’єкт, у якому міститься
- **Масив файлів**: глибоко об’єднується в указаному порядку (пізніші значення мають пріоритет)
- **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення)
- **Вкладені includes**: підтримуються до 10 рівнів глибини
- **Відносні шляхи**: обчислюються відносно файла, який виконує включення
- **Записи, якими керує OpenClaw**: коли запис змінює лише один розділ верхнього рівня,
який підтримується include одного файла, наприклад `plugins: { $include: "./plugins.json5" }`,
підкріплений include одного файла, наприклад `plugins: { $include: "./plugins.json5" }`,
OpenClaw оновлює цей включений файл і залишає `openclaw.json` без змін
- **Непідтримуваний наскрізний запис**: кореневі include, масиви include та include
із сусідніми перевизначеннями завершуються безпечною відмовою для записів, якими керує OpenClaw, замість
- **Непідтримуваний наскрізний запис**: кореневі includes, масиви include і includes
із сусідніми перевизначеннями аварійно завершуються для записів, якими керує OpenClaw, замість
сплощення конфігурації
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору та циклічних include
- **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних includes
</Accordion>
</AccordionGroup>
## Гаряче перезавантаження конфігурації
Gateway стежить за `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості параметрів ручний перезапуск не потрібен.
Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості параметрів ручний перезапуск не потрібен.
Прямі редагування файла вважаються недовіреними, доки не пройдуть валідацію. Спостерігач
чекає, поки тимчасові записи/перейменування редактора стабілізуються, читає
остаточний файл і відхиляє недійсні зовнішні редагування, відновлюючи
останню відому справну конфігурацію. Записи конфігурації, якими керує OpenClaw,
використовують ту саму перевірку схемою перед записом; руйнівні пошкодження, такі
як видалення `gateway.mode` або зменшення файла більш ніж удвічі, відхиляються
Прямі редагування файла вважаються ненадійними, доки не пройдуть валідацію. Спостерігач
чекає, доки тимчасові записи/перейменування редактора стабілізуються, читає
підсумковий файл і відхиляє недійсні зовнішні зміни, відновлюючи останню відому коректну конфігурацію. Записи конфігурації,
якими керує OpenClaw, використовують той самий контроль через схему перед записом; руйнівні пошкодження, такі
як видалення `gateway.mode` або зменшення файла більш ніж наполовину, відхиляються
і зберігаються як `.rejected.*` для перевірки.
Якщо ви бачите `Config auto-restored from last-known-good` або
`config reload restored last-known-good config` у журналах, перевірте відповідний
Якщо ви бачите в журналах `Config auto-restored from last-known-good` або
`config reload restored last-known-good config`, перевірте відповідний
файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте
`openclaw config validate`. Дивіться [усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config)
`openclaw config validate`. Дивіться [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config)
для контрольного списку відновлення.
### Режими перезавантаження
| Режим | Поведінка |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. |
| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви обробляєте це самі. |
| **`restart`** | Перезапускає Gateway при будь-якій зміні конфігурації, безпечній чи ні. |
| **`off`** | Вимикає спостереження за файлом. Зміни набувають чинності під час наступного ручного перезапуску. |
| Режим | Поведінка |
| ---------------------- | -------------------------------------------------------------------------------------- |
| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. |
| **`hot`** | Лише гаряче застосовує безпечні зміни. Записує попередження, коли потрібен перезапуск — ви обробляєте це самі. |
| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. |
| **`off`** | Вимикає відстеження файла. Зміни набудуть чинності під час наступного ручного перезапуску. |
```json5
{
@ -565,42 +566,55 @@ Gateway стежить за `~/.openclaw/openclaw.json` і автоматичн
Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, які потребують перезапуску, обробляються автоматично.
| Категорія | Поля | Потрібен перезапуск? |
| ------------------- | ----------------------------------------------------------------- | -------------------- |
| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали plugin | Ні |
| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні |
| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні |
| Сесії та повідомлення | `session`, `messages` | Ні |
| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні |
| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні |
| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** |
| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** |
| Категорія | Поля | Потрібен перезапуск? |
| ----------------- | ---------------------------------------------------------------- | -------------------- |
| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали Plugin | Ні |
| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні |
| Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні |
| Сесії й повідомлення | `session`, `messages` | Ні |
| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні |
| UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні |
| Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** |
| Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** |
<Note>
`gateway.reload` і `gateway.remote` — винятки: їх зміна **не** спричиняє перезапуск.
</Note>
### Планування перезавантаження
Коли ви редагуєте вихідний файл, на який є посилання через `$include`, OpenClaw планує
перезавантаження на основі макета, створеного у вихідному файлі, а не сплощеного представлення в пам’яті.
Це робить рішення гарячого перезавантаження (гаряче застосування чи перезапуск) передбачуваними навіть тоді, коли
один розділ верхнього рівня міститься у власному включеному файлі, наприклад
`plugins: { $include: "./plugins.json5" }`.
Якщо перезавантаження не можна безпечно спланувати — наприклад, через те, що вихідний макет
поєднує кореневі includes із сусідніми перевизначеннями — OpenClaw аварійно завершує таку спробу, записує
причину в журнал і залишає поточну запущену конфігурацію без змін, щоб ви могли виправити
форму джерела замість мовчазного переходу до сплощеного перезавантаження.
## RPC конфігурації (програмні оновлення)
<Note>
RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити за 60 секунд** на `deviceId+clientIp`. Коли ліміт досягнуто, RPC повертає `UNAVAILABLE` з `retryAfterMs`.
RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) мають обмеження частоти: **3 запити на 60 секунд** для кожної пари `deviceId+clientIp`. Якщо ліміт перевищено, RPC повертає `UNAVAILABLE` з `retryAfterMs`.
</Note>
Безпечний/типовий потік:
Безпечний/типовий процес:
- `config.schema.lookup`: перевірити одне дерево конфігурації з областю дії шляху з неглибоким
- `config.schema.lookup`: переглянути одне піддерево конфігурації для заданого шляху з неглибоким
вузлом схеми, відповідними метаданими підказок і підсумками безпосередніх дочірніх елементів
- `config.get`: отримати поточний знімок + хеш
- `config.patch`: рекомендований шлях часткового оновлення
- `config.get`: отримати поточний знімок + hash
- `config.patch`: бажаний шлях часткового оновлення
- `config.apply`: лише повна заміна конфігурації
- `update.run`: явне самооновлення + перезапуск
- `update.run`: явне самостійне оновлення + перезапуск
Якщо ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`,
Коли ви не замінюєте всю конфігурацію повністю, надавайте перевагу `config.schema.lookup`,
а потім `config.patch`.
<AccordionGroup>
<Accordion title="config.apply (повна заміна)">
Перевіряє + записує повну конфігурацію та перезапускає Gateway за один крок.
Валідовує + записує повну конфігурацію та перезапускає Gateway одним кроком.
<Warning>
`config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів.
@ -608,16 +622,16 @@ RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) м
Параметри:
- `raw` (рядок) — payload JSON5 для всієї конфігурації
- `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує)
- `sessionKey` (необов’язково) — ключ сесії для пінгу пробудження після перезапуску
- `raw` (string) — payload JSON5 для всієї конфігурації
- `baseHash` (необов’язково) — hash конфігурації з `config.get` (обов’язковий, якщо конфігурація існує)
- `sessionKey` (необов’язково) — ключ сесії для ping пробудження після перезапуску
- `note` (необов’язково) — примітка для sentinel перезапуску
- `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000)
Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, а між циклами перезапуску діє 30-секундний cooldown.
Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний cooldown.
```bash
openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.get --params '{}' # зафіксувати payload.hash
openclaw gateway call config.apply --params '{
"raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
"baseHash": "<hash>",
@ -636,11 +650,11 @@ RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) м
Параметри:
- `raw` (рядок) — JSON5 лише з ключами, які потрібно змінити
- `baseHash` (обов’язково) — хеш конфігурації з `config.get`
- `sessionKey`, `note`, `restartDelayMs` — так само, як у `config.apply`
- `raw` (string) — JSON5 лише з ключами, які треба змінити
- `baseHash` (обов’язково) — hash конфігурації з `config.get`
- `sessionKey`, `note`, `restartDelayMs` — те саме, що і для `config.apply`
Поведінка перезапуску відповідає `config.apply`: об’єднання відкладених перезапусків плюс 30-секундний cooldown між циклами перезапуску.
Поведінка перезапуску відповідає `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундний cooldown між циклами перезапуску.
```bash
openclaw gateway call config.patch --params '{
@ -654,12 +668,12 @@ RPC запису control-plane (`config.apply`, `config.patch`, `update.run`) м
## Змінні середовища
OpenClaw зчитує env vars із батьківського процесу, а також із:
OpenClaw читає env vars із батьківського процесу, а також із:
- `.env` у поточному робочому каталозі (якщо є)
- `~/.openclaw/.env` (глобальний запасний варіант)
- `.env` з поточного робочого каталогу (якщо є)
- `~/.openclaw/.env` (глобальний fallback)
Жоден із цих файлів не перевизначає наявні env vars. Ви також можете встановлювати вбудовані env vars у конфігурації:
Жоден із цих файлів не перевизначає наявні env vars. Ви також можете задавати вбудовані env vars у конфігурації:
```json5
{
@ -670,8 +684,8 @@ OpenClaw зчитує env vars із батьківського процесу,
}
```
<Accordion title="Імпорт env оболонки (необов’язково)">
Якщо ввімкнено і очікувані ключі не встановлено, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
<Accordion title="Імпорт shell env (необов’язково)">
Якщо цю можливість увімкнено і очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі:
```json5
{
@ -684,8 +698,8 @@ OpenClaw зчитує env vars із батьківського процесу,
Еквівалент env var: `OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="Підстановка env var у значення конфігурації">
Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`:
<Accordion title="Підстановка env var у значеннях конфігурації">
Посилайтеся на env vars у будь-якому рядковому значенні конфігурації через `${VAR_NAME}`:
```json5
{
@ -696,9 +710,9 @@ OpenClaw зчитує env vars із батьківського процесу,
Правила:
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
- Відсутні/порожні змінні спричиняють помилку під час завантаження
- Екрануйте як `$${VAR}` для буквального виводу
- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`
- Відсутні/порожні vars спричиняють помилку під час завантаження
- Екрануйте через `$${VAR}` для буквального виводу
- Працює всередині файлів `$include`
- Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"`
@ -737,16 +751,16 @@ OpenClaw зчитує env vars із батьківського процесу,
}
```
Подробиці про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведено в [Керування секретами](/uk/gateway/secrets).
Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
Деталі SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведено в [Керування секретами](/uk/gateway/secrets).
Підтримувані шляхи облікових даних перелічено в [SecretRef Credential Surface](/uk/reference/secretref-credential-surface).
</Accordion>
Дивіться [Середовище](/uk/help/environment) для повного порядку пріоритету та джерел.
Дивіться [Environment](/uk/help/environment) для повного порядку пріоритетів і джерел.
## Повний довідник
Повний довідник для всіх полів дивіться в **[Довіднику з конфігурації](/uk/gateway/configuration-reference)**.
Повний довідник по полях дивіться в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**.
---
_Пов’язане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник з конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_
_Пов’язане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_

167
docs/uk/gateway/openshell.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Ви хочете керовані хмарні sandbox замість локального Docker
- Ви налаштовуєте плагін OpenShell
- Вам потрібні керовані в хмарі sandbox замість локального Docker
- Ви налаштовуєте Plugin OpenShell
- Вам потрібно вибрати між режимами workspace mirror і remote
summary: Використання OpenShell як керованого бекенда sandbox для агентів OpenClaw
summary: Використовуйте OpenShell як керований бекенд sandbox для агентів OpenClaw
title: OpenShell
x-i18n:
generated_at: "2026-04-05T18:04:06Z"
generated_at: "2026-04-23T07:12:10Z"
model: gpt-5.4
provider: openai
source_hash: aaf9027d0632a70fb86455f8bc46dc908ff766db0eb0cdf2f7df39c715241ead
source_hash: f93a8350fd48602bc535ec0480d0ed1665e558b37cc23c820ac90097862abd23
source_path: gateway/openshell.md
workflow: 15
---
@ -17,24 +17,24 @@ x-i18n:
# OpenShell
OpenShell — це керований бекенд sandbox для OpenClaw. Замість локального запуску
контейнерів Docker OpenClaw делегує життєвий цикл sandbox до CLI `openshell`,
який надає віддалені середовища з виконанням команд через SSH.
контейнерів Docker OpenClaw делегує життєвий цикл sandbox CLI `openshell`,
який створює віддалені середовища з виконанням команд через SSH.
Плагін OpenShell повторно використовує той самий базовий транспорт SSH і
міст віддаленої файлової системи, що й загальний [бекенд SSH](/gateway/sandboxing#ssh-backend). Він додає
життєвий цикл, специфічний для OpenShell (`sandbox create/get/delete`, `sandbox ssh-config`),
та необов’язковий режим workspace `mirror`.
Plugin OpenShell повторно використовує той самий базовий транспорт SSH і міст
до віддаленої файлової системи, що й загальний [бекенд SSH](/uk/gateway/sandboxing#ssh-backend). Він додає
специфічний для OpenShell життєвий цикл (`sandbox create/get/delete`, `sandbox ssh-config`)
і необов’язковий режим workspace `mirror`.
## Передумови
- CLI `openshell` встановлено й доступний у `PATH` (або задайте власний шлях через
- Встановлений CLI `openshell`, доступний у `PATH` (або вкажіть власний шлях через
`plugins.entries.openshell.config.command`)
- Обліковий запис OpenShell із доступом до sandbox
- OpenClaw Gateway запущено на хості
- Gateway OpenClaw, запущений на хості
## Швидкий старт
1. Увімкніть плагін і задайте бекенд sandbox:
1. Увімкніть plugin і задайте бекенд sandbox:
```json5
{
@ -62,10 +62,10 @@ OpenShell — це керований бекенд sandbox для OpenClaw. За
}
```
2. Перезапустіть Gateway. На наступному ході агента OpenClaw створить sandbox OpenShell
і маршрутизуватиме виконання інструментів через нього.
2. Перезапустіть Gateway. Під час наступного ходу агента OpenClaw створить sandbox OpenShell
і спрямовуватиме виконання інструментів через нього.
3. Перевірка:
3. Перевірте:
```bash
openclaw sandbox list
@ -78,81 +78,82 @@ openclaw sandbox explain
### `mirror`
Використовуйте `plugins.entries.openshell.config.mode: "mirror"`, якщо ви хочете, щоб **локальний
Використовуйте `plugins.entries.openshell.config.mode: "mirror"`, якщо хочете, щоб **локальний
workspace залишався канонічним**.
Поведінка:
- Перед `exec` OpenClaw синхронізує локальний workspace в sandbox OpenShell.
- Після `exec` OpenClaw синхронізує віддалений workspace назад у локальний workspace.
- Файлові інструменти, як і раніше, працюють через міст sandbox, але локальний workspace
- Перед `exec` OpenClaw синхронізує локальний workspace до sandbox OpenShell.
- Після `exec` OpenClaw синхронізує віддалений workspace назад до локального workspace.
- Файлові інструменти й надалі працюють через міст sandbox, але локальний workspace
залишається джерелом істини між ходами.
Найкраще підходить для:
Найкраще підходить для випадків, коли:
- Ви редагуєте файли локально поза OpenClaw і хочете, щоб ці зміни автоматично були видимі в
sandbox.
- Ви хочете, щоб sandbox OpenShell поводився максимально схоже на бекенд Docker.
- Ви хочете, щоб sandbox OpenShell поводився максимально подібно до бекенда Docker.
- Ви хочете, щоб workspace хоста відображав записи sandbox після кожного ходу exec.
Компроміс: додаткова вартість синхронізації до і після кожного exec.
Компроміс: додаткові витрати на синхронізацію до і після кожного exec.
### `remote`
Використовуйте `plugins.entries.openshell.config.mode: "remote"`, якщо ви хочете, щоб
Використовуйте `plugins.entries.openshell.config.mode: "remote"`, якщо хочете, щоб
**workspace OpenShell став канонічним**.
Поведінка:
- Коли sandbox створюється вперше, OpenClaw один раз засіває віддалений workspace
- Коли sandbox створюється вперше, OpenClaw один раз ініціалізує віддалений workspace
з локального workspace.
- Після цього `exec`, `read`, `write`, `edit` і `apply_patch` працюють
безпосередньо з віддаленим workspace OpenShell.
- OpenClaw **не** синхронізує віддалені зміни назад у локальний workspace.
- Читання медіа під час побудови prompt усе одно працює, тому що файлові та медіаінструменти читають через міст sandbox.
- OpenClaw **не** синхронізує віддалені зміни назад до локального workspace.
- Читання медіа під час формування prompt і далі працює, оскільки інструменти файлів і медіа читають через
міст sandbox.
Найкраще підходить для:
Найкраще підходить для випадків, коли:
- Sandbox має жити переважно на віддаленому боці.
- Sandbox має існувати переважно на віддаленому боці.
- Ви хочете менші накладні витрати на синхронізацію на кожному ході.
- Ви не хочете, щоб локальні редагування на хості непомітно перезаписували стан віддаленого sandbox.
Важливо: якщо ви редагуєте файли на хості поза OpenClaw після початкового засівання,
Важливо: якщо ви редагуєте файли на хості поза OpenClaw після початкової ініціалізації,
віддалений sandbox **не** побачить цих змін. Використовуйте
`openclaw sandbox recreate`, щоб виконати повторне засівання.
`openclaw sandbox recreate`, щоб виконати повторну ініціалізацію.
### Вибір режиму
| | `mirror` | `remote` |
| ------------------------ | ------------------------- | -------------------------- |
| **Канонічний workspace** | Локальний хост | Віддалений OpenShell |
| **Напрям синхронізації** | Двостороння (кожен exec) | Одноразове засівання |
| | `mirror` | `remote` |
| ------------------------ | -------------------------- | ------------------------- |
| **Канонічний workspace** | Локальний хост | Віддалений OpenShell |
| **Напрям синхронізації** | Двосторонній (кожен exec) | Одноразова ініціалізація |
| **Накладні витрати на хід** | Вищі (вивантаження + завантаження) | Нижчі (прямі віддалені операції) |
| **Локальні редагування видимі?** | Так, на наступному exec | Ні, до recreate |
| **Найкраще для** | Робочих процесів розробки | Довготривалих агентів, CI |
| **Локальні редагування видимі?** | Так, під час наступного exec | Ні, до recreate |
| **Найкраще для** | Робочих процесів розробки | Довготривалих агентів, CI |
## Довідник конфігурації
## Довідка з конфігурації
Уся конфігурація OpenShell розташована в `plugins.entries.openshell.config`:
Уся конфігурація OpenShell розміщена в `plugins.entries.openshell.config`:
| Ключ | Тип | Типово | Опис |
| ------------------------- | ------------------------ | ------------- | ------------------------------------------------------- |
| `mode` | `"mirror"` або `"remote"` | `"mirror"` | Режим синхронізації workspace |
| `command` | `string` | `"openshell"` | Шлях або назва CLI `openshell` |
| `from` | `string` | `"openclaw"` | Джерело sandbox для першого створення |
| `gateway` | `string` | — | Назва шлюзу OpenShell (`--gateway`) |
| `gatewayEndpoint` | `string` | — | URL endpoint шлюзу OpenShell (`--gateway-endpoint`) |
| `policy` | `string` | — | ID політики OpenShell для створення sandbox |
| `providers` | `string[]` | `[]` | Назви провайдерів, які слід приєднати під час створення sandbox |
| `gpu` | `boolean` | `false` | Запросити ресурси GPU |
| `autoProviders` | `boolean` | `true` | Передавати `--auto-providers` під час створення sandbox |
| `remoteWorkspaceDir` | `string` | `"/sandbox"` | Основний доступний для запису workspace усередині sandbox |
| `remoteAgentWorkspaceDir` | `string` | `"/agent"` | Шлях монтування workspace агента (для доступу лише на читання) |
| `timeoutSeconds` | `number` | `120` | Тайм-аут для операцій CLI `openshell` |
| Ключ | Тип | За замовчуванням | Опис |
| ------------------------- | ------------------------ | ---------------- | ----------------------------------------------------- |
| `mode` | `"mirror"` або `"remote"` | `"mirror"` | Режим синхронізації workspace |
| `command` | `string` | `"openshell"` | Шлях або назва CLI `openshell` |
| `from` | `string` | `"openclaw"` | Джерело sandbox для першого створення |
| `gateway` | `string` | — | Назва шлюзу OpenShell (`--gateway`) |
| `gatewayEndpoint` | `string` | — | URL ендпойнта шлюзу OpenShell (`--gateway-endpoint`) |
| `policy` | `string` | — | ID policy OpenShell для створення sandbox |
| `providers` | `string[]` | `[]` | Назви провайдерів, які потрібно під’єднати під час створення sandbox |
| `gpu` | `boolean` | `false` | Запитати ресурси GPU |
| `autoProviders` | `boolean` | `true` | Передавати `--auto-providers` під час `sandbox create` |
| `remoteWorkspaceDir` | `string` | `"/sandbox"` | Основний workspace із правами запису всередині sandbox |
| `remoteAgentWorkspaceDir` | `string` | `"/agent"` | Шлях монтування workspace агента (для доступу лише на читання) |
| `timeoutSeconds` | `number` | `120` | Timeout для операцій CLI `openshell` |
Налаштування на рівні sandbox (`mode`, `scope`, `workspaceAccess`) задаються в
`agents.defaults.sandbox`, як і для будь-якого іншого бекенда. Повну матрицю див. у
[Sandboxing](/gateway/sandboxing).
Налаштування рівня sandbox (`mode`, `scope`, `workspaceAccess`) налаштовуються в
`agents.defaults.sandbox`, як і для будь-якого бекенда. Повну матрицю див. у
[Sandboxing](/uk/gateway/sandboxing).
## Приклади
@ -182,7 +183,7 @@ workspace залишався канонічним**.
}
```
### Режим mirror з GPU
### Режим mirror із GPU
```json5
{
@ -213,7 +214,7 @@ workspace залишався канонічним**.
}
```
### OpenShell для окремого агента з власним шлюзом
### OpenShell для окремого агента з власним gateway
```json5
{
@ -266,15 +267,15 @@ openclaw sandbox recreate --all
```
Для режиму `remote` **recreate особливо важливий**: він видаляє канонічний
віддалений workspace для цієї області дії. Під час наступного використання виконується нове засівання віддаленого workspace з
локального workspace.
віддалений workspace для цієї області. Під час наступного використання буде ініціалізовано новий віддалений workspace
з локального workspace.
Для режиму `mirror` recreate переважно скидає віддалене середовище виконання, оскільки
локальний workspace залишається канонічним.
### Коли виконувати recreate
Виконуйте recreate після зміни будь-якого з цих параметрів:
Виконуйте recreate після зміни будь-чого з наведеного:
- `agents.defaults.sandbox.backend`
- `plugins.entries.openshell.config.from`
@ -285,28 +286,42 @@ openclaw sandbox recreate --all
openclaw sandbox recreate --all
```
## Посилення безпеки
Допоміжні засоби sandbox OpenShell, які читають файли віддаленого workspace, використовують закріплений файловий
дескриптор для кореня workspace і проходять батьківськими каталогами від цього закріпленого fd,
замість повторного розв’язання шляху для кожного читання. У поєднанні з повторною
перевіркою ідентичності під час кожної операції це запобігає тому, щоб заміна symlink посеред ходу або
гаряча заміна монтування workspace перенаправила читання за межі призначеного
віддаленого workspace.
- Корінь workspace відкривається один раз і закріплюється; наступні читання повторно використовують цей fd.
- Проходи батьківськими каталогами обходять відносні записи від закріпленого fd, тому їх не можна
перенаправити заміненим каталогом вище в шляху.
- Ідентичність sandbox повторно перевіряється перед кожним читанням, тож повторно створений або
перепризначений sandbox не зможе непомітно віддавати файли з іншого workspace.
## Поточні обмеження
- Browser sandbox не підтримується бекендом OpenShell.
- Браузер sandbox не підтримується в бекенді OpenShell.
- `sandbox.docker.binds` не застосовується до OpenShell.
- Специфічні для Docker параметри runtime у `sandbox.docker.*` застосовуються лише до
бекенда Docker.
- Специфічні для Docker параметри runtime в `sandbox.docker.*` застосовуються лише до бекенда Docker.
## Як це працює
1. OpenClaw викликає `openshell sandbox create` (з прапорцями `--from`, `--gateway`,
`--policy`, `--providers`, `--gpu` згідно з конфігурацією).
2. OpenClaw викликає `openshell sandbox ssh-config <name>`, щоб отримати деталі
SSH-підключення для sandbox.
3. Core записує конфігурацію SSH у тимчасовий файл і відкриває SSH-сесію, використовуючи
той самий міст віддаленої файлової системи, що й загальний бекенд SSH.
4. У режимі `mirror`: синхронізує локальний стан у віддалений перед exec, виконує запуск, синхронізує назад після exec.
5. У режимі `remote`: один раз засіває під час створення, а потім працює безпосередньо з віддаленим
`--policy`, `--providers`, `--gpu` відповідно до конфігурації).
2. OpenClaw викликає `openshell sandbox ssh-config <name>`, щоб отримати SSH-дані
підключення для sandbox.
3. Ядро записує конфігурацію SSH до тимчасового файлу й відкриває SSH-сеанс, використовуючи
той самий міст до віддаленої файлової системи, що й загальний бекенд SSH.
4. У режимі `mirror`: синхронізувати локальне з віддаленим перед exec, виконати, синхронізувати назад після exec.
5. У режимі `remote`: одноразово ініціалізувати під час створення, а потім працювати безпосередньо з віддаленим
workspace.
## Див. також
- [Sandboxing](/gateway/sandboxing) -- режими, області дії та порівняння бекендів
- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження заблокованих інструментів
- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів
- [Sandbox CLI](/cli/sandbox) -- команди `openclaw sandbox`
- [Sandboxing](/uk/gateway/sandboxing) -- режими, області та порівняння бекендів
- [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження заблокованих інструментів
- [Multi-Agent Sandbox and Tools](/uk/tools/multi-agent-sandbox-tools) -- перевизначення для окремих агентів
- [Sandbox CLI](/uk/cli/sandbox) -- команди `openclaw sandbox`

165
docs/uk/gateway/pairing.md
View File

@ -1,47 +1,47 @@
---
read_when:
- Реалізація підтвердження прив’язки вузлів без UI macOS
- Додавання сценаріїв CLI для підтвердження віддалених вузлів
- Розширення протоколу gateway керуванням вузлами
summary: Прив’язка вузлів, якою володіє Gateway (варіант B), для iOS та інших віддалених вузлів
title: Прив’язка, якою володіє Gateway
- Реалізація погоджень спарювання Node без інтерфейсу macOS UI
- Додавання потоків CLI для погодження віддалених Node
- Розширення протоколу gateway керуванням Node
summary: Спарювання Node, що належить Gateway (варіант B), для iOS та інших віддалених Node
title: Спарювання, що належить Gateway
x-i18n:
generated_at: "2026-04-05T18:04:13Z"
generated_at: "2026-04-23T07:12:22Z"
model: gpt-5.4
provider: openai
source_hash: 8f90818c84daeb190f27df7413e23362372806f2c4250e4954295fbf6df70233
source_hash: adba3c833b57b1df117c57d3451598e3c84cd78dcc6e9811547cdbb101afda0b
source_path: gateway/pairing.md
workflow: 15
---
# Прив’язка, якою володіє Gateway (варіант B)
# Спарювання, що належить Gateway (варіант B)
У моделі прив’язки, якою володіє Gateway, саме **Gateway** є джерелом істини щодо того, яким вузлам
У спарюванні, що належить Gateway, **Gateway** є джерелом істини щодо того, яким Node
дозволено приєднуватися. UI (застосунок macOS, майбутні клієнти) — це лише фронтенди,
які підтверджують або відхиляють очікувальні запити.
які погоджують або відхиляють запити, що очікують розгляду.
**Важливо:** WS-вузли використовують **прив’язку пристрою** (роль `node`) під час `connect`.
`node.pair.*` — це окреме сховище прив’язки, і воно **не** керує WS-handshake.
Цей сценарій використовують лише клієнти, які явно викликають `node.pair.*`.
**Важливо:** WS Node використовують **спарювання пристрою** (роль `node`) під час `connect`.
`node.pair.*` — це окреме сховище спарювання, і воно **не** керує WS handshake.
Цей потік використовують лише клієнти, які явно викликають `node.pair.*`.
## Поняття
- **Очікувальний запит**: вузол попросився приєднатися; потребує підтвердження.
- **Прив’язаний вузол**: підтверджений вузол із виданим токеном автентифікації.
- **Транспорт**: endpoint Gateway WS пересилає запити, але не вирішує,
членство. (Підтримку застарілого TCP bridge видалено.)
- **Запит, що очікує розгляду**: Node попросив приєднатися; потрібне погодження.
- **Спарений Node**: погоджений Node із виданим токеном автентифікації.
- **Транспорт**: кінцева точка WS Gateway пересилає запити, але не вирішує
питання членства. (Підтримку застарілого TCP bridge було видалено.)
## Як працює прив’язка
## Як працює спарювання
1. Вузол підключається до Gateway WS і запитує прив’язку.
2. Gateway зберігає **очікувальний запит** і надсилає подію `node.pair.requested`.
3. Ви підтверджуєте або відхиляєте запит (через CLI або UI).
4. Після підтвердження Gateway видає **новий токен** (при повторній прив’язці токени ротуються).
5. Вузол повторно підключається, використовуючи токен, і тепер вважається “прив’язаним”.
1. Node підключається до WS Gateway і запитує спарювання.
2. Gateway зберігає **запит, що очікує розгляду**, і надсилає `node.pair.requested`.
3. Ви погоджуєте або відхиляєте запит (CLI або UI).
4. Після погодження Gateway видає **новий токен** (токени обертаються під час повторного спарювання).
5. Node повторно підключається з використанням токена і тепер є «спареним».
Очікувальні запити автоматично спливають через **5 хвилин**.
Запити, що очікують розгляду, автоматично спливають через **5 хвилин**.
## Сценарій CLI (дружній до headless)
## Потік CLI (зручно для headless-режиму)
```bash
openclaw nodes pending
@ -51,95 +51,124 @@ openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```
`nodes status` показує прив’язані/підключені вузли та їхні можливості.
`nodes status` показує спарені/підключені Node та їхні можливості.
## Поверхня API (протокол gateway)
Події:
- `node.pair.requested` — надсилається під час створення нового очікувального запиту.
- `node.pair.resolved` — надсилається, коли запит підтверджено/відхилено/термін дії минув.
- `node.pair.requested` — надсилається, коли створюється новий запит, що очікує розгляду.
- `node.pair.resolved` — надсилається, коли запит погоджено/відхилено/прострочено.
Методи:
- `node.pair.request` — створити або повторно використати очікувальний запит.
- `node.pair.list` — перелічити очікувальні + прив’язані вузли (`operator.pairing`).
- `node.pair.approve` — підтвердити очікувальний запит (видає токен).
- `node.pair.reject` — відхилити очікувальний запит.
- `node.pair.request` — створити або повторно використати запит, що очікує розгляду.
- `node.pair.list` — перелічити Node, що очікують розгляду, і спарені Node (`operator.pairing`).
- `node.pair.approve` — погодити запит, що очікує розгляду (видає токен).
- `node.pair.reject` — відхилити запит, що очікує розгляду.
- `node.pair.verify` — перевірити `{ nodeId, token }`.
Примітки:
- `node.pair.request` є ідемпотентним для кожного вузла: повторні виклики повертають той самий
очікувальний запит.
- Повторні запити для того самого очікувального вузла також оновлюють збережені метадані вузла
і найновіший allowlist-знімок оголошених команд для видимості оператора.
- Підтвердження **завжди** генерує новий токен; `node.pair.request` ніколи
не повертає токен.
- Запити можуть містити `silent: true` як підказку для сценаріїв автоматичного підтвердження.
- `node.pair.approve` використовує оголошені команди очікувального запиту для забезпечення
додаткових областей підтвердження:
- `node.pair.request` є ідемпотентним для кожного Node: повторні виклики повертають той самий
запит, що очікує розгляду.
- Повторні запити для того самого Node, що очікує розгляду, також оновлюють збережені
метадані Node та найновіший allowlist-знімок оголошених команд для видимості оператору.
- Погодження **завжди** генерує новий токен; токен ніколи не повертається з
`node.pair.request`.
- Запити можуть включати `silent: true` як підказку для потоків автоматичного погодження.
- `node.pair.approve` використовує оголошені команди із запиту, що очікує розгляду, щоб застосовувати
додаткові області погодження:
- запит без команд: `operator.pairing`
- запит команд без exec: `operator.pairing` + `operator.write`
- запит команди без exec: `operator.pairing` + `operator.write`
- запит `system.run` / `system.run.prepare` / `system.which`:
`operator.pairing` + `operator.admin`
Важливо:
- Прив’язка вузла — це сценарій довіри/ідентичності плюс видача токена.
- Вона **не** закріплює живу поверхню команд вузла для кожного вузла окремо.
- Живі команди вузла надходять із того, що вузол оголошує під час connect після
застосування глобальної політики команд вузлів gateway (`gateway.nodes.allowCommands` /
- Спарювання Node — це потік довіри/ідентичності плюс видача токена.
- Воно **не** фіксує живу поверхню команд Node для кожного Node.
- Живі команди Node походять із того, що Node оголошує під час connect після застосування
глобальної політики команд Node gateway (`gateway.nodes.allowCommands` /
`denyCommands`).
- Політика allow/ask для `system.run` для кожного вузла живе на самому вузлі в
`exec.approvals.node.*`, а не в записі прив’язки.
- Політика allow/ask для `system.run` на рівні окремого Node живе на самому Node у
`exec.approvals.node.*`, а не в записі спарювання.
## Керування командами вузла (2026.3.31+)
## Керування командами Node (2026.3.31+)
<Warning>
**Несумісна зміна:** починаючи з `2026.3.31`, команди вузлів вимкнено, доки не підтверджено прив’язку вузла. Самої лише прив’язки пристрою більше недостатньо для відкриття оголошених команд вузла.
**Breaking change:** Починаючи з `2026.3.31`, команди Node вимкнені, доки не буде погоджено спарювання Node. Самого лише спарювання пристрою більше недостатньо, щоб відкрити оголошені команди Node.
</Warning>
Коли вузол підключається вперше, запит на прив’язку створюється автоматично. Доки цей запит не буде підтверджено, усі очікувальні команди вузла від цього вузла фільтруються й не виконуються. Щойно довіру встановлено через підтвердження прив’язки, оголошені команди вузла стають доступними згідно зі звичайною політикою команд.
Коли Node підключається вперше, запит на спарювання створюється автоматично. Поки запит на спарювання не погоджено, усі очікувані команди Node від цього Node фільтруються і не виконуються. Щойно довіру встановлено через погодження спарювання, оголошені команди Node стають доступними з урахуванням звичайної політики команд.
Це означає:
- Вузли, які раніше покладалися лише на прив’язку пристрою для відкриття команд, тепер мають завершити прив’язку вузла.
- Команди, поставлені в чергу до підтвердження прив’язки, відкидаються, а не відкладаються.
- Node, які раніше покладалися лише на спарювання пристрою для відкриття команд, тепер мають завершити спарювання Node.
- Команди, поставлені в чергу до погодження спарювання, відкидаються, а не відкладаються.
## Межі довіри подій вузла (2026.3.31+)
## Межі довіри для подій Node (2026.3.31+)
<Warning>
**Несумісна зміна:** запуски, що походять від вузла, тепер залишаються на скороченій довіреній поверхні.
**Breaking change:** Запуски, ініційовані Node, тепер залишаються в межах скороченої довіреної поверхні.
</Warning>
Підсумки, що походять від вузла, і пов’язані події сесії обмежуються лише призначеною довіреною поверхнею. Сценарії на основі сповіщень або запусків вузла, які раніше покладалися на ширший доступ до інструментів хоста чи сесії, можуть потребувати коригування. Це посилення захисту гарантує, що події вузла не можуть підвищити привілеї до рівня інструментів хоста поза межами того, що дозволяє межа довіри вузла.
Підсумки, ініційовані Node, і пов’язані події сесії обмежуються призначеною довіреною поверхнею. Потоки, керовані сповіщеннями або ініційовані Node, які раніше покладалися на ширший доступ до інструментів хоста чи сесії, можуть потребувати коригування. Це посилення захисту гарантує, що події Node не можуть підвищити привілеї до доступу до інструментів рівня хоста понад те, що дозволяє межа довіри Node.
## Автоматичне підтвердження (застосунок macOS)
## Автоматичне погодження (застосунок macOS)
Застосунок macOS може за бажанням спробувати **тихе підтвердження**, коли:
Застосунок macOS може за бажанням спробувати **тихе погодження**, коли:
- запит позначено як `silent`, і
- застосунок може перевірити SSH-з’єднання з хостом gateway від того самого користувача.
- застосунок може перевірити SSH-підключення до хоста gateway від імені того самого користувача.
Якщо тихе підтвердження не вдається, використовується звичайне запрошення “Підтвердити/Відхилити”.
Якщо тихе погодження не вдається, виконується повернення до звичайного запиту «Погодити/Відхилити».
## Автоматичне погодження оновлення метаданих
Коли вже спарений пристрій повторно підключається лише зі змінами нечутливих
метаданих (наприклад, відображуваного імені або підказок щодо платформи клієнта), OpenClaw розглядає
це як `metadata-upgrade`. Тихе автоматичне погодження має вузьку область застосування: воно
стосується лише довірених повторних підключень локального CLI/допоміжних інструментів, які вже довели володіння
спільним токеном або паролем через loopback. Клієнти Browser/Control UI та віддалені
клієнти як і раніше використовують явний потік повторного погодження. Підвищення області
(read до write/admin) і зміни відкритого ключа **не** підпадають під автоматичне погодження
`metadata-upgrade` — вони залишаються явними запитами на повторне погодження.
## Допоміжні засоби спарювання QR
`/pair qr` відображає payload спарювання як структурований медіавміст, щоб мобільні й
браузерні клієнти могли сканувати його безпосередньо. Видалення пристрою тепер також очищає
застарілі запити на спарювання, що очікують розгляду, для того самого id пристрою, тому `nodes pending` більше
не показує осиротілих рядків після відкликання.
## Локальність і forwarded headers
Gateway-парування вважає з’єднання loopback лише тоді, коли і сирий сокет,
і будь-які свідчення від upstream proxy узгоджуються. Якщо запит надходить через loopback,
але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, які
вказують на нелокальне походження, ці свідчення через forwarded headers спростовують
твердження про loopback-локальність. Тоді шлях спарювання вимагає явного погодження
замість того, щоб мовчки трактувати запит як з’єднання з того самого хоста. Див.
[Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) для еквівалентного правила щодо
автентифікації оператора.
## Зберігання (локальне, приватне)
Стан прив’язки зберігається в каталозі state Gateway (типово `~/.openclaw`):
Стан спарювання зберігається в каталозі стану Gateway (типово `~/.openclaw`):
- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`
Якщо ви перевизначаєте `OPENCLAW_STATE_DIR`, каталог `nodes/` переміщується разом із ним.
Якщо ви перевизначаєте `OPENCLAW_STATE_DIR`, тека `nodes/` переміщується разом із ним.
Примітки щодо безпеки:
Примітки з безпеки:
- Токени — це секрети; ставтеся до `paired.json` як до чутливого файла.
- Ротація токена потребує повторного підтвердження (або видалення запису вузла).
- Токени є секретами; вважайте `paired.json` чутливим файлом.
- Обертання токена вимагає повторного погодження (або видалення запису Node).
## Поведінка транспорту
- Транспорт є **безстанним**; він не зберігає членство.
- Якщо Gateway офлайн або прив’язку вимкнено, вузли не можуть прив’язуватися.
- Якщо Gateway працює в remote mode, прив’язка все одно відбувається відносно сховища віддаленого Gateway.
- Транспорт є **безстановим**; він не зберігає членство.
- Якщо Gateway не в мережі або спарювання вимкнене, Node не можуть спаровуватися.
- Якщо Gateway працює у віддаленому режимі, спарювання все одно відбувається зі сховищем віддаленого Gateway.

1210
docs/uk/gateway/security/index.md
View File

File diff suppressed because it is too large Load Diff

229
docs/uk/gateway/trusted-proxy-auth.md
View File

@ -1,69 +1,69 @@
---
read_when:
- Запуск OpenClaw за проксі з урахуванням ідентичності
- Запуск OpenClaw за identity-aware проксі
- Налаштування Pomerium, Caddy або nginx з OAuth перед OpenClaw
- Виправлення помилок WebSocket 1008 unauthorized у конфігураціях із reverse proxy
- Визначення, де задавати HSTS та інші HTTP-заголовки посилення захисту
summary: Делегування автентифікації gateway довіреному reverse proxy (Pomerium, Caddy, nginx + OAuth)
- Усунення помилок WebSocket 1008 unauthorized у конфігураціях зі зворотним проксі
- Визначення, де встановлювати HSTS та інші заголовки посилення захисту HTTP
summary: Делегуйте автентифікацію Gateway довіреному зворотному проксі (Pomerium, Caddy, nginx + OAuth)
title: Автентифікація через довірений проксі
x-i18n:
generated_at: "2026-04-05T18:05:46Z"
generated_at: "2026-04-23T07:12:37Z"
model: gpt-5.4
provider: openai
source_hash: ccd39736b43e8744de31566d5597b3fbf40ecb6ba9c8ba9d2343e1ab9bb8cd45
source_hash: 649529e9a350d7df3a9ecbbae8871d61e1dff2069dfabf2f86a77a0d96c52778
source_path: gateway/trusted-proxy-auth.md
workflow: 15
---
# Автентифікація через довірений проксі
> ⚠️ **Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому reverse proxy. Помилка в налаштуванні може відкрити ваш Gateway для неавторизованого доступу. Уважно прочитайте цю сторінку перед увімкненням.
> ⚠️ **Функція, чутлива до безпеки.** У цьому режимі автентифікація повністю делегується вашому зворотному проксі. Неправильне налаштування може відкрити ваш Gateway для несанкціонованого доступу. Уважно прочитайте цю сторінку перед увімкненням.
## Коли використовувати
Використовуйте режим автентифікації `trusted-proxy`, коли:
- Ви запускаєте OpenClaw за **проксі з урахуванням ідентичності** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
- Ваш проксі обробляє всю автентифікацію й передає ідентичність користувача через заголовки
- Ви працюєте в середовищі Kubernetes або контейнерів, де проксі є єдиним шляхом до Gateway
- Ви отримуєте помилки WebSocket `1008 unauthorized`, тому що браузери не можуть передавати токени в payload WS
- ви запускаєте OpenClaw за **identity-aware проксі** (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth)
- ваш проксі виконує всю автентифікацію і передає ідентичність користувача через заголовки
- ви працюєте в Kubernetes або контейнерному середовищі, де проксі є єдиним шляхом до Gateway
- ви стикаєтеся з помилками WebSocket `1008 unauthorized`, оскільки браузери не можуть передавати токени в payload WS
## Коли НЕ використовувати
- Якщо ваш проксі не автентифікує користувачів (а лише завершує TLS або працює як load balancer)
- Якщо існує будь-який шлях до Gateway в обхід проксі (дірки у firewall, доступ із внутрішньої мережі)
- Якщо ви не впевнені, що ваш проксі правильно прибирає/перезаписує forwarded-заголовки
- Якщо вам потрібен лише особистий доступ одного користувача (розгляньте Tailscale Serve + loopback для простішого налаштування)
- якщо ваш проксі не автентифікує користувачів (лише завершує TLS або є балансувальником навантаження)
- якщо існує будь-який шлях до Gateway в обхід проксі (дірки у фаєрволі, доступ із внутрішньої мережі)
- якщо ви не впевнені, що ваш проксі правильно видаляє/перезаписує forwarded-заголовки
- якщо вам потрібен лише персональний доступ для одного користувача (для простішого налаштування розгляньте Tailscale Serve + loopback)
## Як це працює
1. Ваш reverse proxy автентифікує користувачів (OAuth, OIDC, SAML тощо)
1. Ваш зворотний проксі автентифікує користувачів (OAuth, OIDC, SAML тощо)
2. Проксі додає заголовок з ідентичністю автентифікованого користувача (наприклад, `x-forwarded-user: nick@example.com`)
3. OpenClaw перевіряє, що запит надійшов від **довіреної IP-адреси проксі** (налаштовується в `gateway.trustedProxies`)
3. OpenClaw перевіряє, що запит надійшов від **IP-адреси довіреного проксі** (налаштовано в `gateway.trustedProxies`)
4. OpenClaw витягує ідентичність користувача з налаштованого заголовка
5. Якщо все перевірено, запит авторизується
5. Якщо все збігається, запит авторизується
## Поведінка прив’язки для Control UI
## Керування поведінкою pairing у Control UI
Коли активний `gateway.auth.mode = "trusted-proxy"` і запит проходить перевірки
довіреного проксі, сеанси WebSocket Control UI можуть підключатися без
ідентичності прив’язки пристрою.
Коли активний `gateway.auth.mode = "trusted-proxy"` і запит проходить
перевірки trusted-proxy, сеанси WebSocket Control UI можуть підключатися без
ідентичності pairing пристрою.
Наслідки:
- Прив’язка більше не є основним механізмом доступу до Control UI в цьому режимі.
- Ефективним механізмом керування доступом стають ваша політика автентифікації reverse proxy і `allowUsers`.
- Тримайте ingress gateway заблокованим лише до IP довіреного проксі (`gateway.trustedProxies` + firewall).
- Pairing більше не є основним бар’єром доступу для Control UI в цьому режимі.
- Політика автентифікації вашого зворотного проксі та `allowUsers` стають фактичним контролем доступу.
- Залишайте вхідний трафік gateway заблокованим лише для IP-адрес довіреного проксі (`gateway.trustedProxies` + фаєрвол).
## Конфігурація
```json5
{
gateway: {
// Автентифікація trusted-proxy очікує запити з не-loopback джерела довіреного проксі
// Автентифікація trusted-proxy очікує запити від довіреного джерела проксі не на loopback
bind: "lan",
// КРИТИЧНО: додавайте сюди лише IP-адреси вашого проксі
// КРИТИЧНО: Додавайте сюди лише IP-адреси вашого проксі
trustedProxies: ["10.0.0.1", "172.17.0.1"],
auth: {
@ -75,7 +75,7 @@ x-i18n:
// Необов’язково: заголовки, які ОБОВ’ЯЗКОВО мають бути присутні (перевірка проксі)
requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],
// Необов’язково: обмежити конкретними користувачами (порожньо = дозволити всіх)
// Необов’язково: обмеження конкретними користувачами (порожньо = дозволити всіх)
allowUsers: ["nick@example.com", "admin@company.org"],
},
},
@ -83,34 +83,35 @@ x-i18n:
}
```
Важливе runtime-правило:
Важливе правило runtime:
- Автентифікація trusted-proxy відхиляє запити з loopback-джерела (`127.0.0.1`, `::1`, loopback CIDR).
- Reverse proxy на тому самому хості через loopback **не** задовольняють вимоги trusted-proxy auth.
- Для reverse proxy на тому самому хості через loopback натомість використовуйте автентифікацію token/password або маршрутизуйте через не-loopback адресу довіреного проксі, яку OpenClaw може перевірити.
- Не-loopback розгортання Control UI і далі потребують явного `gateway.controlUi.allowedOrigins`.
- Автентифікація trusted-proxy відхиляє запити з джерел loopback (`127.0.0.1`, `::1`, CIDR loopback).
- Зворотні проксі на loopback на тому ж хості **не** задовольняють вимоги автентифікації trusted-proxy.
- Для таких конфігурацій з loopback-проксі на тому ж хості використовуйте натомість автентифікацію за токеном/паролем або маршрутизуйте через довірену адресу проксі не на loopback, яку OpenClaw може перевірити.
- Для розгортань Control UI не на loopback усе ще потрібен явний `gateway.controlUi.allowedOrigins`.
- **Докази через forwarded-заголовки мають пріоритет над локальністю loopback.** Якщо запит надходить через loopback, але містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`, що вказують на нелокальне джерело, ці докази скасовують твердження про локальність loopback. Такий запит розглядається як віддалений для pairing, автентифікації trusted-proxy та контролю ідентичності пристрою в Control UI. Це не дозволяє зворотному проксі на loopback на тому ж хості «відмивати» ідентичність з forwarded-заголовків у trusted-proxy auth.
### Довідник із конфігурації
### Довідник з конфігурації
| Поле | Обов’язково | Опис |
| ------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
| `gateway.trustedProxies` | Так | Масив IP-адрес проксі, яким можна довіряти. Запити з інших IP відхиляються. |
| `gateway.trustedProxies` | Так | Масив IP-адрес проксі, яким довіряють. Запити з інших IP відхиляються. |
| `gateway.auth.mode` | Так | Має бути `"trusted-proxy"` |
| `gateway.auth.trustedProxy.userHeader` | Так | Назва заголовка, що містить ідентичність автентифікованого користувача |
| `gateway.auth.trustedProxy.requiredHeaders` | Ні | Додаткові заголовки, які мають бути присутні, щоб запит вважався довіреним |
| `gateway.auth.trustedProxy.allowUsers` | Ні | Allowlist ідентичностей користувачів. Порожньо означає всіх автентифікованих користувачів. |
| `gateway.auth.trustedProxy.allowUsers` | Ні | Список дозволених ідентичностей користувачів. Порожній означає дозволити всіх автентифікованих користувачів. |
## TLS termination і HSTS
## Завершення TLS і HSTS
Використовуйте одну точку TLS termination і задавайте HSTS саме там.
Використовуйте одну точку завершення TLS і застосовуйте HSTS саме там.
### Рекомендований шаблон: TLS termination на проксі
### Рекомендований шаблон: завершення TLS на проксі
Коли ваш reverse proxy обробляє HTTPS для `https://control.example.com`, задавайте
Коли ваш зворотний проксі обробляє HTTPS для `https://control.example.com`, установіть
`Strict-Transport-Security` на проксі для цього домену.
- Добре підходить для розгортань, відкритих в інтернет.
- Зберігає сертифікати й політику посилення HTTP в одному місці.
- Добре підходить для розгортань, доступних з інтернету.
- Дає змогу тримати сертифікати та політику посилення захисту HTTP в одному місці.
- OpenClaw може залишатися на loopback HTTP за проксі.
Приклад значення заголовка:
@ -119,9 +120,9 @@ x-i18n:
Strict-Transport-Security: max-age=31536000; includeSubDomains
```
### TLS termination на Gateway
### Завершення TLS на Gateway
Якщо OpenClaw сам напряму обслуговує HTTPS (без проксі, що завершує TLS), задайте:
Якщо сам OpenClaw напряму обслуговує HTTPS (без проксі, що завершує TLS), задайте:
```json5
{
@ -138,19 +139,19 @@ Strict-Transport-Security: max-age=31536000; includeSubDomains
`strictTransportSecurity` приймає рядкове значення заголовка або `false` для явного вимкнення.
### Рекомендації щодо розгортання
### Рекомендації щодо поетапного ввімкнення
- Спочатку використовуйте короткий max age (наприклад, `max-age=300`) під час перевірки трафіку.
- Переходьте до довготривалих значень (наприклад, `max-age=31536000`) лише після достатньої впевненості.
- Збільшуйте до довготривалих значень (наприклад, `max-age=31536000`) лише після появи високої впевненості.
- Додавайте `includeSubDomains` лише якщо кожен піддомен готовий до HTTPS.
- Використовуйте preload лише якщо ви свідомо відповідаєте вимогам preload для всього набору своїх доменів.
- Використовуйте preload лише якщо ви свідомо відповідаєте вимогам preload для всього набору ваших доменів.
- Локальна розробка лише на loopback не отримує користі від HSTS.
## Приклади налаштування проксі
### Pomerium
Pomerium передає ідентичність у `x-pomerium-claim-email` (або інших заголовках claims) і JWT у `x-pomerium-jwt-assertion`.
Pomerium передає ідентичність у `x-pomerium-claim-email` (або інші claim-заголовки) і JWT у `x-pomerium-jwt-assertion`.
```json5
{
@ -184,13 +185,13 @@ routes:
### Caddy з OAuth
Caddy з плагіном `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності.
Caddy з Plugin `caddy-security` може автентифікувати користувачів і передавати заголовки ідентичності.
```json5
{
gateway: {
bind: "lan",
trustedProxies: ["10.0.0.1"], // IP Caddy/sidecar проксі
trustedProxies: ["10.0.0.1"], // IP Caddy/sidecar-проксі
auth: {
mode: "trusted-proxy",
trustedProxy: {
@ -267,19 +268,19 @@ location / {
## Змішана конфігурація токенів
OpenClaw відхиляє неоднозначні конфігурації, у яких одночасно активні і `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`), і режим `trusted-proxy`. Змішані конфігурації токенів можуть призвести до того, що loopback-запити тихо автентифікуватимуться через неправильний шлях автентифікації.
OpenClaw відхиляє неоднозначні конфігурації, де одночасно активні `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`) і режим `trusted-proxy`. Змішані конфігурації токенів можуть призвести до того, що запити через loopback тихо автентифікуватимуться неправильним шляхом автентифікації.
Якщо під час запуску ви бачите помилку `mixed_trusted_proxy_token`:
- Приберіть спільний токен під час використання режиму trusted-proxy, або
- Змініть `gateway.auth.mode` на `"token"`, якщо ви справді хочете автентифікацію на основі токена.
- приберіть спільний токен, якщо використовуєте режим trusted-proxy, або
- перемкніть `gateway.auth.mode` на `"token"`, якщо ви маєте на увазі автентифікацію на основі токена.
Автентифікація trusted-proxy для loopback також блокується за принципом fail-closed: виклики з того самого хоста мають передавати налаштовані заголовки ідентичності через довірений проксі, а не проходити тиху автентифікацію.
Автентифікація trusted-proxy через loopback також безпечно блокується: виклики з того ж хоста мають передавати налаштовані заголовки ідентичності через довірений проксі, а не тихо автентифікуватися.
## Заголовок областей оператора
Автентифікація trusted-proxy — це HTTP-режим **з передаванням ідентичності**, тому виклики
можуть за бажанням оголошувати області оператора через `x-openclaw-scopes`.
Автентифікація trusted-proxy — це HTTP-режим, **що несе ідентичність**, тому виклики
можуть необов’язково оголошувати області оператора через `x-openclaw-scopes`.
Приклади:
@ -289,118 +290,118 @@ OpenClaw відхиляє неоднозначні конфігурації, у
Поведінка:
- Коли заголовок присутній, OpenClaw враховує оголошений набір областей.
- Коли заголовок присутній, але порожній, запит оголошує **жодної** операторської області.
- Коли заголовок відсутній, звичайні HTTP API з передаванням ідентичності повертаються до стандартного типового набору операторських областей.
- **Plugin HTTP routes** з автентифікацією gateway за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня runtime-область повертається до `operator.write`.
- HTTP-запити з браузера все одно мають проходити `gateway.controlUi.allowedOrigins` (або навмисний fallback-режим через Host-header) навіть після успішної trusted-proxy auth.
- Коли заголовок присутній, OpenClaw використовує оголошений набір областей.
- Коли заголовок присутній, але порожній, запит оголошує **жодної** області оператора.
- Коли заголовок відсутній, звичайні HTTP API, що несуть ідентичність, повертаються до стандартного типового набору областей оператора.
- **HTTP routes Plugin** з автентифікацією gateway за замовчуванням вужчі: коли `x-openclaw-scopes` відсутній, їхня область runtime повертається до `operator.write`.
- HTTP-запити з походження браузера все одно мають пройти `gateway.controlUi.allowedOrigins` (або навмисний fallback-режим заголовка Host) навіть після успішної автентифікації trusted-proxy.
Практичне правило:
- Явно надсилайте `x-openclaw-scopes`, коли хочете, щоб trusted-proxy-запит
був вужчим за типові значення, або коли gateway-auth plugin route потребує
чогось сильнішого за область write.
- Надсилайте `x-openclaw-scopes` явно, коли хочете, щоб запит trusted-proxy
був вужчим за типові значення, або коли маршруту plugin з автентифікацією gateway
потрібне щось сильніше за область write.
## Контрольний список безпеки
Перш ніж увімкнути trusted-proxy auth, перевірте:
Перш ніж увімкнути автентифікацію trusted-proxy, перевірте:
- [ ] **Проксі — єдиний шлях**: порт Gateway закритий firewall для всіх, крім вашого проксі
- [ ] **trustedProxies мінімальний**: лише фактичні IP-адреси вашого проксі, а не цілі підмережі
- [ ] **Немає loopback-джерела проксі**: trusted-proxy auth блокується для запитів із loopback-джерела
- [ ] **Проксі прибирає заголовки**: ваш проксі перезаписує (а не додає) `x-forwarded-*` заголовки від клієнтів
- [ ] **TLS termination**: ваш проксі обробляє TLS; користувачі підключаються через HTTPS
- [ ] **allowedOrigins задано явно**: не-loopback Control UI використовує явний `gateway.controlUi.allowedOrigins`
- [ ] **allowUsers задано** (рекомендовано): обмеження відомими користувачами замість дозволу будь-кому з автентифікацією
- [ ] **Немає змішаної конфігурації токенів**: не задавайте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`
- [ ] **Проксі є єдиним шляхом**: Порт Gateway закрито фаєрволом від усього, крім вашого проксі
- [ ] **trustedProxies мінімальний**: Лише фактичні IP-адреси ваших проксі, а не цілі підмережі
- [ ] **Немає джерела проксі на loopback**: автентифікація trusted-proxy безпечно блокується для запитів із джерел loopback
- [ ] **Проксі видаляє заголовки**: Ваш проксі перезаписує (а не дописує) заголовки `x-forwarded-*` від клієнтів
- [ ] **Завершення TLS**: Ваш проксі обробляє TLS; користувачі підключаються через HTTPS
- [ ] **allowedOrigins задано явно**: Для Control UI не на loopback використовується явний `gateway.controlUi.allowedOrigins`
- [ ] **allowUsers задано** (рекомендовано): Обмежте доступ відомими користувачами, а не дозволяйте будь-кому, хто пройшов автентифікацію
- [ ] **Немає змішаної конфігурації токенів**: Не задавайте одночасно `gateway.auth.token` і `gateway.auth.mode: "trusted-proxy"`
## Аудит безпеки
`openclaw security audit` позначить trusted-proxy auth як знахідку рівня **critical**. Це навмисно — нагадування, що ви делегуєте безпеку вашій конфігурації проксі.
`openclaw security audit` позначить автентифікацію trusted-proxy як finding рівня **critical**. Це навмисно — нагадування про те, що ви делегуєте безпеку вашій конфігурації проксі.
Аудит перевіряє:
- Базове попередження/нагадування `gateway.trusted_proxy_auth` рівня warning/critical
- Відсутню конфігурацію `trustedProxies`
- Відсутню конфігурацію `userHeader`
- Порожній `allowUsers` (дозволяє будь-якому автентифікованому користувачу)
- Wildcard або відсутню політику browser-origin на відкритих поверхнях Control UI
- базове попередження/нагадування `gateway.trusted_proxy_auth` рівня warning/critical
- відсутню конфігурацію `trustedProxies`
- відсутню конфігурацію `userHeader`
- порожній `allowUsers` (дозволяє будь-якого автентифікованого користувача)
- wildcard або відсутню політику походження браузера на відкритих поверхнях Control UI
## Усунення несправностей
## Усунення неполадок
### `trusted_proxy_untrusted_source`
Запит надійшов не з IP у `gateway.trustedProxies`. Перевірте:
- Чи правильний IP проксі? (IP контейнерів Docker можуть змінюватися)
- Чи є перед проксі ще один load balancer?
- Використайте `docker inspect` або `kubectl get pods -o wide`, щоб знайти фактичні IP
- чи правильний IP проксі? (IP контейнерів Docker можуть змінюватися)
- чи є балансувальник навантаження перед вашим проксі?
- використайте `docker inspect` або `kubectl get pods -o wide`, щоб знайти фактичні IP-адреси
### `trusted_proxy_loopback_source`
OpenClaw відхилив trusted-proxy-запит із loopback-джерела.
OpenClaw відхилив запит trusted-proxy із джерела loopback.
Перевірте:
- Чи проксі підключається з `127.0.0.1` / `::1`?
- Чи намагаєтеся ви використовувати trusted-proxy auth із reverse proxy на тому самому хості через loopback?
- чи підключається проксі з `127.0.0.1` / `::1`?
- чи не намагаєтеся ви використовувати автентифікацію trusted-proxy зі зворотним проксі на loopback на тому ж хості?
Виправлення:
- Використовуйте автентифікацію token/password для reverse proxy на тому самому хості через loopback, або
- Маршрутизуйте через не-loopback адресу довіреного проксі й тримайте цю IP-адресу в `gateway.trustedProxies`.
- Використовуйте автентифікацію за токеном/паролем для конфігурацій із проксі на loopback на тому ж хості, або
- Маршрутизуйте через довірену адресу проксі не на loopback і тримайте цю IP-адресу в `gateway.trustedProxies`.
### `trusted_proxy_user_missing`
Заголовок користувача був порожній або відсутній. Перевірте:
- Чи налаштований проксі на передавання заголовків ідентичності?
- Чи правильна назва заголовка? (без урахування регістру, але написання має значення)
- Чи користувач справді автентифікований на проксі?
- чи налаштований ваш проксі на передавання заголовків ідентичності?
- чи правильна назва заголовка? (регістр не має значення, але написання має)
- чи користувач справді автентифікований на проксі?
### `trusted*proxy_missing_header*\*`
### `trusted_proxy_missing_header_*`
Один з обов’язкових заголовків був відсутній. Перевірте:
Обов’язковий заголовок був відсутній. Перевірте:
- Конфігурацію проксі для цих конкретних заголовків
- Чи не прибираються заголовки десь у ланцюжку
- конфігурацію вашого проксі для цих конкретних заголовків
- чи не видаляються заголовки десь у ланцюжку
### `trusted_proxy_user_not_allowed`
Користувач автентифікований, але відсутній у `allowUsers`. Додайте його або приберіть allowlist.
Користувач автентифікований, але не входить до `allowUsers`. Або додайте його, або приберіть allowlist.
### `trusted_proxy_origin_not_allowed`
Автентифікація trusted-proxy пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки origin для Control UI.
Автентифікація trusted-proxy пройшла успішно, але заголовок браузера `Origin` не пройшов перевірки походження Control UI.
Перевірте:
- `gateway.controlUi.allowedOrigins` містить точний browser origin
- Ви не покладаєтеся на wildcard origin, якщо тільки свідомо не хочете дозволити всіх
- Якщо ви свідомо використовуєте fallback-режим через Host-header, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` задано навмисно
- `gateway.controlUi.allowedOrigins` містить точне походження браузера
- ви не покладаєтеся на wildcard-походження, якщо тільки свідомо не хочете поведінку «дозволити все»
- якщо ви навмисно використовуєте fallback-режим заголовка Host, `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` задано свідомо
### WebSocket усе ще не працює
Переконайтеся, що ваш проксі:
- Підтримує оновлення WebSocket (`Upgrade: websocket`, `Connection: upgrade`)
- Передає заголовки ідентичності під час запитів на оновлення WebSocket (а не лише для HTTP)
- Не має окремого шляху автентифікації для WebSocket-з’єднань
- підтримує оновлення WebSocket (`Upgrade: websocket`, `Connection: upgrade`)
- передає заголовки ідентичності в запитах на оновлення WebSocket (а не лише для HTTP)
- не має окремого шляху автентифікації для з’єднань WebSocket
## Міграція з автентифікації через токен
## Міграція з автентифікації за токеном
Якщо ви переходите з автентифікації через токен на trusted-proxy:
Якщо ви переходите з автентифікації за токеном на trusted-proxy:
1. Налаштуйте проксі на автентифікацію користувачів і передавання заголовків
2. Окремо протестуйте налаштування проксі (curl із заголовками)
3. Оновіть конфігурацію OpenClaw для trusted-proxy auth
1. Налаштуйте ваш проксі на автентифікацію користувачів і передавання заголовків
2. Окремо перевірте налаштування проксі (curl із заголовками)
3. Оновіть конфігурацію OpenClaw для автентифікації trusted-proxy
4. Перезапустіть Gateway
5. Перевірте WebSocket-з’єднання з Control UI
6. Запустіть `openclaw security audit` і перегляньте знахідки
5. Перевірте з’єднання WebSocket із Control UI
6. Запустіть `openclaw security audit` і перегляньте findings
## Пов’язане
- [Безпека](/gateway/security) — повний посібник із безпеки
- [Конфігурація](/gateway/configuration) — довідник із конфігурації
- [Віддалений доступ](/gateway/remote) — інші шаблони віддаленого доступу
- [Tailscale](/gateway/tailscale) — простіша альтернатива для доступу лише через tailnet
- [Безпека](/uk/gateway/security) — повний посібник із безпеки
- [Конфігурація](/uk/gateway/configuration) — довідник із конфігурації
- [Віддалений доступ](/uk/gateway/remote) — інші схеми віддаленого доступу
- [Tailscale](/uk/gateway/tailscale) — простіша альтернатива для доступу лише в tailnet

1408
docs/uk/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

241
docs/uk/plugins/bundles.md
View File

@ -1,48 +1,48 @@
---
read_when:
- Ви хочете встановити пакет, сумісний із Codex, Claude або Cursor
- Вам потрібно зрозуміти, як OpenClaw зіставляє вміст пакета з нативними можливостями
- Ви налагоджуєте виявлення пакета або відсутні можливості
summary: Встановлюйте та використовуйте пакети Codex, Claude і Cursor як плагіни OpenClaw
title: Набори плагінів
- Ви хочете встановити набір, сумісний із Codex, Claude або Cursor
- Вам потрібно зрозуміти, як OpenClaw зіставляє вміст набору з нативними функціями
- Ви налагоджуєте виявлення набору або відсутні можливості
summary: Установлення та використання наборів Codex, Claude і Cursor як plugin OpenClaw
title: Набори Plugin
x-i18n:
generated_at: "2026-04-22T23:49:19Z"
generated_at: "2026-04-23T07:12:53Z"
model: gpt-5.4
provider: openai
source_hash: 91fec13cb1f807231c706318f3e81e27b350d5a0266821cb96c8494c45f01de0
source_hash: 8c9e48738e059c302157dd8733178109cf34840f32a3d7b5b767ac019fbc581b
source_path: plugins/bundles.md
workflow: 15
---
# Набори плагінів
# Набори Plugin
OpenClaw може встановлювати плагіни з трьох зовнішніх екосистем: **Codex**, **Claude**
і **Cursor**. Вони називаються **пакетами** — наборами вмісту та метаданих, які
OpenClaw зіставляє з нативними можливостями, як-от Skills, хуки та інструменти MCP.
OpenClaw може встановлювати plugin із трьох зовнішніх екосистем: **Codex**, **Claude**,
і **Cursor**. Вони називаються **наборами** — це пакети вмісту та метаданих, які
OpenClaw зіставляє з нативними функціями, такими як Skills, хуки та інструменти MCP.
<Info>
Пакети **не** є тим самим, що й нативні плагіни OpenClaw. Нативні плагіни працюють
у межах процесу та можуть реєструвати будь-яку можливість. Пакети — це набори
вмісту з вибірковим зіставленням можливостей і вужчою межею довіри.
Набори **не** є тим самим, що й нативні plugin OpenClaw. Нативні plugin працюють
у межах процесу й можуть реєструвати будь-які можливості. Набори — це пакети вмісту
із вибірковим зіставленням функцій і вужчою межею довіри.
</Info>
## Навіщо існують пакети
## Навіщо існують набори
Багато корисних плагінів публікуються у форматі Codex, Claude або Cursor. Замість
того щоб змушувати авторів переписувати їх як нативні плагіни OpenClaw, OpenClaw
виявляє ці формати та зіставляє підтримуваний у них вміст із нативним набором
можливостей. Це означає, що ви можете встановити пакет команд Claude або пакет
Skills для Codex і одразу почати ним користуватися.
Багато корисних plugin публікуються у форматах Codex, Claude або Cursor. Замість
того щоб вимагати від авторів переписувати їх як нативні plugin OpenClaw, OpenClaw
виявляє ці формати й зіставляє їхній підтримуваний вміст із нативним набором
функцій. Це означає, що ви можете встановити набір команд Claude або набір Skills Codex
і відразу ним користуватися.
## Встановлення пакета
## Установлення набору
<Steps>
<Step title="Встановіть із каталогу, архіву або marketplace">
<Step title="Установлення з каталогу, архіву або marketplace">
```bash
# Локальний каталог
# Local directory
openclaw plugins install ./my-bundle
# Архів
# Archive
openclaw plugins install ./my-bundle.tgz
# Claude marketplace
@ -52,13 +52,13 @@ Skills для Codex і одразу почати ним користуватис
</Step>
<Step title="Перевірте виявлення">
<Step title="Перевірка виявлення">
```bash
openclaw plugins list
openclaw plugins inspect <id>
```
Пакети відображаються як `Format: bundle` із підтипом `codex`, `claude` або `cursor`.
Набори відображаються як `Format: bundle` із підтипом `codex`, `claude` або `cursor`.
</Step>
@ -67,57 +67,56 @@ Skills для Codex і одразу почати ним користуватис
openclaw gateway restart
```
Зіставлені можливості (Skills, хуки, інструменти MCP, типові налаштування LSP) будуть доступні в наступному сеансі.
Зіставлені функції (Skills, хуки, інструменти MCP, типові значення LSP) будуть доступні в наступній сесії.
</Step>
</Steps>
## Що OpenClaw зіставляє з пакетів
## Що OpenClaw зіставляє з наборів
Сьогодні в OpenClaw працюють не всі можливості пакетів. Нижче наведено, що
працює, а що виявляється, але ще не підключене.
Не кожна функція набору сьогодні працює в OpenClaw. Ось що працює, а що
виявляється, але ще не під’єднано.
### Підтримується зараз
### Зараз підтримується
| Можливість | Як зіставляється | Застосовується до |
| ------------- | ------------------------------------------------------------------------------------------ | ----------------- |
| Вміст Skills | Кореневі каталоги Skills пакета завантажуються як звичайні Skills OpenClaw | Усі формати |
| Команди | `commands/` і `.cursor/commands/` обробляються як кореневі каталоги Skills | Claude, Cursor |
| Пакети хуків | Макети у стилі OpenClaw з `HOOK.md` + `handler.ts` | Codex |
| Інструменти MCP | Конфігурація MCP пакета об’єднується з вбудованими налаштуваннями Pi; підтримувані сервери stdio та HTTP завантажуються | Усі формати |
| Сервери LSP | Claude `.lsp.json` і оголошені в маніфесті `lspServers` об’єднуються з типовими налаштуваннями LSP вбудованого Pi | Claude |
| Налаштування | Claude `settings.json` імпортується як типові налаштування вбудованого Pi | Claude |
| Feature | How it maps | Applies to |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Вміст Skills | Корені Skills набору завантажуються як звичайні Skills OpenClaw | Усі формати |
| Команди | `commands/` і `.cursor/commands/` обробляються як корені Skills | Claude, Cursor |
| Пакети хуків | Макети у стилі OpenClaw `HOOK.md` + `handler.ts` | Codex |
| Інструменти MCP | Конфігурація MCP набору об’єднується з вбудованими налаштуваннями Pi; підтримувані сервери stdio та HTTP завантажуються | Усі формати |
| Сервери LSP | Claude `.lsp.json` і `lspServers`, оголошені в маніфесті, об’єднуються з типовими значеннями LSP вбудованого Pi | Claude |
| Налаштування | Claude `settings.json` імпортується як типові значення вбудованого Pi | Claude |
#### Вміст Skills
- кореневі каталоги Skills пакета завантажуються як звичайні кореневі каталоги Skills OpenClaw
- корені Claude `commands` обробляються як додаткові кореневі каталоги Skills
- корені Cursor `.cursor/commands` обробляються як додаткові кореневі каталоги Skills
- корені Skills набору завантажуються як звичайні корені Skills OpenClaw
- корені Claude `commands` обробляються як додаткові корені Skills
- корені Cursor `.cursor/commands` обробляються як додаткові корені Skills
Це означає, що markdown-файли команд Claude працюють через звичайний завантажувач
Skills в OpenClaw. Markdown-команди Cursor працюють через той самий шлях.
Це означає, що markdown-файли команд Claude працюють через звичайний завантажувач Skills OpenClaw.
Markdown-команди Cursor працюють через той самий шлях.
#### Пакети хуків
- кореневі каталоги хуків пакета працюють **лише** тоді, коли вони використовують
звичайний макет пакета хуків OpenClaw. Сьогодні це переважно випадок сумісності з Codex:
- корені хуків набору працюють **лише** тоді, коли вони використовують звичайний макет
пакетів хуків OpenClaw. Сьогодні це передусім випадок сумісності з Codex:
- `HOOK.md`
- `handler.ts` або `handler.js`
#### MCP для Pi
- увімкнені пакети можуть додавати конфігурацію сервера MCP
- OpenClaw об’єднує конфігурацію MCP пакета з ефективними вбудованими налаштуваннями Pi як
- увімкнені набори можуть додавати конфігурацію сервера MCP
- OpenClaw об’єднує конфігурацію MCP набору з ефективними вбудованими налаштуваннями Pi як
`mcpServers`
- OpenClaw показує підтримувані інструменти MCP пакета під час ходів агента вбудованого Pi,
- OpenClaw показує підтримувані інструменти MCP набору під час ходів агента вбудованого Pi,
запускаючи сервери stdio або підключаючись до HTTP-серверів
- профілі інструментів `coding` і `messaging` типово включають інструменти MCP пакета;
- профілі інструментів `coding` і `messaging` типово включають інструменти MCP набору;
використовуйте `tools.deny: ["bundle-mcp"]`, щоб вимкнути їх для агента або Gateway
- локальні налаштування Pi для проєкту все одно застосовуються після типових налаштувань пакета,
тож за потреби налаштування робочого простору можуть перевизначати записи MCP пакета
- каталоги інструментів MCP пакета сортуються детерміновано перед реєстрацією, щоб
зміни у вихідному порядку `listTools()` не спричиняли нестабільність блоків
інструментів prompt-cache
- локальні для проєкту налаштування Pi усе ще застосовуються після типових значень набору, тож
налаштування workspace можуть за потреби перевизначати записи MCP набору
- каталоги інструментів MCP набору сортуються детерміновано перед реєстрацією, тому
зміни у висхідному порядку `listTools()` не спричиняють зайву нестабільність блоків інструментів prompt-cache
##### Транспорти
@ -139,7 +138,7 @@ Skills в OpenClaw. Markdown-команди Cursor працюють через
}
```
**HTTP** підключається до вже запущеного сервера MCP через `sse` типово або через `streamable-http`, якщо це запитано:
**HTTP** підключається до запущеного сервера MCP через `sse` за замовчуванням або через `streamable-http`, якщо це запитано:
```json
{
@ -158,18 +157,18 @@ Skills в OpenClaw. Markdown-команди Cursor працюють через
}
```
- `transport` можна встановити в `"streamable-http"` або `"sse"`; якщо його пропущено, OpenClaw використовує `sse`
- дозволені лише схеми URL `http:` і `https:`
- значення `headers` підтримують підстановку `${ENV_VAR}`
- запис сервера, що містить одночасно `command` і `url`, відхиляється
- облікові дані URL (userinfo і параметри запиту) редагуються в описах інструментів
і журналах
- `connectionTimeoutMs` перевизначає типовий 30-секундний тайм-аут підключення
як для транспортів stdio, так і для HTTP
- для `transport` можна встановити `"streamable-http"` або `"sse"`; якщо значення пропущено, OpenClaw використовує `sse`
- дозволено лише схеми URL `http:` і `https:`
- значення в `headers` підтримують підстановку `${ENV_VAR}`
- запис сервера, який містить і `command`, і `url`, відхиляється
- облікові дані в URL (userinfo і параметри запиту) редагуються в описах
інструментів і журналах
- `connectionTimeoutMs` перевизначає типовий 30-секундний timeout підключення для
транспортів stdio та HTTP
##### Іменування інструментів
OpenClaw реєструє інструменти MCP пакета з безпечними для провайдерів іменами у форматі
OpenClaw реєструє інструменти MCP набору з безпечними для провайдера іменами у форматі
`serverName__toolName`. Наприклад, сервер із ключем `"vigil-harbor"`, який надає
інструмент `memory_search`, реєструється як `vigil-harbor__memory_search`.
@ -177,129 +176,141 @@ OpenClaw реєструє інструменти MCP пакета з безпе
- префікси серверів обмежуються 30 символами
- повні назви інструментів обмежуються 64 символами
- порожні назви серверів замінюються на `mcp`
- конфліктні санітизовані назви розрізняються числовими суфіксами
- остаточний порядок видимих інструментів є детермінованим за безпечною назвою, щоб
повторні ходи Pi залишалися стабільними для кешу
- фільтрація профілю розглядає всі інструменти з одного MCP-сервера пакета як такі,
що належать плагіну `bundle-mcp`, тому списки дозволів і заборон профілю можуть
містити або окремі видимі назви інструментів, або ключ плагіна `bundle-mcp`
- колізії очищених назв розрізняються числовими суфіксами
- остаточний відкритий порядок інструментів є детермінованим за безпечною назвою, щоб зберігати стабільність кешу в повторних
ходах Pi
- фільтрація профілів обробляє всі інструменти одного сервера MCP набору як такі, що належать plugin
`bundle-mcp`, тож allowlist і deny list профілів можуть включати як
окремі відкриті назви інструментів, так і ключ plugin `bundle-mcp`
#### Налаштування вбудованого Pi
- Claude `settings.json` імпортується як типові налаштування вбудованого Pi, коли
пакет увімкнено
набір увімкнено
- OpenClaw санітизує ключі перевизначення оболонки перед застосуванням
Санітизовані ключі:
Санітізовані ключі:
- `shellPath`
- `shellCommandPrefix`
#### Вбудований Pi LSP
#### LSP вбудованого Pi
- увімкнені пакети Claude можуть додавати конфігурацію сервера LSP
- OpenClaw завантажує `.lsp.json`, а також будь-які шляхи `lspServers`, оголошені в маніфесті
- конфігурація LSP пакета об’єднується з ефективними типовими налаштуваннями LSP вбудованого Pi
- сьогодні можна запускати лише підтримувані LSP-сервери на основі stdio; непідтримувані
- увімкнені набори Claude можуть додавати конфігурацію сервера LSP
- OpenClaw завантажує `.lsp.json` і будь-які шляхи `lspServers`, оголошені в маніфесті
- конфігурація LSP набору об’єднується з ефективними типовими значеннями LSP вбудованого Pi
- сьогодні можна запускати лише підтримувані сервери LSP на основі stdio; непідтримувані
транспорти все одно відображаються в `openclaw plugins inspect <id>`
### Виявляється, але не виконується
Ці можливості розпізнаються та показуються в діагностиці, але OpenClaw їх не запускає:
Ці елементи розпізнаються й показуються в діагностиці, але OpenClaw їх не запускає:
- Claude `agents`, автоматизація `hooks.json`, `outputStyles`
- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
- вбудовані/застосункові метадані Codex поза межами звітності про можливості
- Вбудовані/застосункові метадані Codex поза межами звітування про можливості
## Формати пакетів
## Формати наборів
<AccordionGroup>
<Accordion title="Пакети Codex">
<Accordion title="Набори Codex">
Маркери: `.codex-plugin/plugin.json`
Необов’язковий вміст: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
Пакети Codex найкраще підходять для OpenClaw, коли використовують кореневі каталоги Skills
та каталоги пакетів хуків у стилі OpenClaw (`HOOK.md` + `handler.ts`).
Набори Codex найкраще підходять OpenClaw, коли використовують корені Skills і каталоги
пакетів хуків у стилі OpenClaw (`HOOK.md` + `handler.ts`).
</Accordion>
<Accordion title="Пакети Claude">
<Accordion title="Набори Claude">
Два режими виявлення:
- **На основі маніфесту:** `.claude-plugin/plugin.json`
- **Без маніфесту:** типовий макет Claude (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)
Специфічна поведінка Claude:
Поведінка, специфічна для Claude:
- `commands/` обробляється як вміст Skills
- `settings.json` імпортується в налаштування вбудованого Pi (ключі перевизначення оболонки санітизуються)
- `.mcp.json` показує підтримувані інструменти stdio для вбудованого Pi
- `.lsp.json` разом із шляхами `lspServers`, оголошеними в маніфесті, завантажується до типових налаштувань LSP вбудованого Pi
- `.mcp.json` відкриває підтримувані інструменти stdio для вбудованого Pi
- `.lsp.json` разом зі шляхами `lspServers`, оголошеними в маніфесті, завантажується до типових значень LSP вбудованого Pi
- `hooks/hooks.json` виявляється, але не виконується
- спеціальні шляхи компонентів у маніфесті є адитивними (вони розширюють типові значення, а не замінюють їх)
- шляхи до користувацьких компонентів у маніфесті є додатковими (вони розширюють типові значення, а не замінюють їх)
</Accordion>
<Accordion title="Пакети Cursor">
<Accordion title="Набори Cursor">
Маркери: `.cursor-plugin/plugin.json`
Необов’язковий вміст: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
- `.cursor/commands/` обробляється як вміст Skills
- `.cursor/rules/`, `.cursor/agents/` і `.cursor/hooks.json` лише виявляються
- `.cursor/rules/`, `.cursor/agents/` і `.cursor/hooks.json` — лише виявлення
</Accordion>
</AccordionGroup>
## Пріоритет виявлення
OpenClaw спочатку перевіряє формат нативного плагіна:
OpenClaw спочатку перевіряє нативний формат plugin:
1. `openclaw.plugin.json` або дійсний `package.json` з `openclaw.extensions` — обробляється як **нативний плагін**
2. Маркери пакетів (`.codex-plugin/`, `.claude-plugin/` або типовий макет Claude/Cursor) — обробляються як **пакет**
1. `openclaw.plugin.json` або коректний `package.json` з `openclaw.extensions` — обробляється як **нативний plugin**
2. Маркери наборів (`.codex-plugin/`, `.claude-plugin/` або типовий макет Claude/Cursor) — обробляються як **набір**
Якщо каталог містить обидва варіанти, OpenClaw використовує нативний шлях. Це запобігає
частковому встановленню пакетів подвійного формату як пакетів.
частковому встановленню пакетів із подвійним форматом як наборів.
## Залежності runtime і очищення
- Залежності runtime пакетних plugin постачаються всередині пакета OpenClaw у
`dist/*`. OpenClaw **не** виконує `npm install` під час запуску для пакетних
plugin; конвеєр релізу відповідає за постачання повного пакетного набору
залежностей (див. правило перевірки після публікації в
[Releasing](/uk/reference/RELEASING)).
- Запуски субагентів, які запускають пакетні сервери MCP, вивільняють ці клієнти MCP
через спільний шлях очищення runtime, коли субагент завершує роботу, тому
життєві цикли субагентів не спричиняють витік дочірніх процесів stdio або довготривалих з’єднань MCP
між ходами.
## Безпека
Пакети мають вужчу межу довіри, ніж нативні плагіни:
Набори мають вужчу межу довіри, ніж нативні plugin:
- OpenClaw **не** завантажує довільні runtime-модулі пакета у межах процесу
- шляхи Skills і пакетів хуків мають залишатися всередині кореня плагіна (із перевіркою меж)
- файли налаштувань читаються з тією самою перевіркою меж
- підтримувані сервери MCP на stdio можуть запускатися як підпроцеси
- OpenClaw **не** завантажує довільні модулі runtime набору в межах процесу
- Шляхи Skills і пакетів хуків мають залишатися всередині кореня plugin (із перевіркою меж)
- Файли налаштувань читаються з тими самими перевірками меж
- Підтримувані сервери MCP stdio можуть запускатися як підпроцеси
Це робить пакети безпечнішими типово, але вам усе одно слід вважати сторонні
пакети довіреним вмістом для тих можливостей, які вони все ж надають.
Це робить набори безпечнішими за замовчуванням, але ви все одно маєте розглядати сторонні
набори як довірений вміст щодо тих функцій, які вони все ж відкривають.
## Усунення несправностей
## Усунення проблем
<AccordionGroup>
<Accordion title="Пакет виявляється, але можливості не працюють">
Виконайте `openclaw plugins inspect <id>`. Якщо можливість перелічено, але позначено як
не підключену, це обмеження продукту, а не проблема встановлення.
<Accordion title="Набір виявляється, але можливості не працюють">
Виконайте `openclaw plugins inspect <id>`. Якщо можливість указано, але позначено як
не під’єднану, це обмеження продукту, а не зламана інсталяція.
</Accordion>
<Accordion title="Файли команд Claude не з’являються">
Переконайтеся, що пакет увімкнено, а markdown-файли розташовані всередині
виявленого кореня `commands/` або `skills/`.
Переконайтеся, що набір увімкнено, а markdown-файли розташовані в одному з виявлених
коренів `commands/` або `skills/`.
</Accordion>
<Accordion title="Налаштування Claude не застосовуються">
Підтримуються лише налаштування вбудованого Pi із `settings.json`. OpenClaw
не розглядає налаштування пакета як сирі патчі конфігурації.
Підтримуються лише налаштування вбудованого Pi з `settings.json`. OpenClaw
не обробляє налаштування набору як необроблені патчі config.
</Accordion>
<Accordion title="Хуки Claude не виконуються">
`hooks/hooks.json` лише виявляється. Якщо вам потрібні виконувані хуки, використовуйте
макет пакета хуків OpenClaw або постачайте нативний плагін.
`hooks/hooks.json` — лише для виявлення. Якщо вам потрібні виконувані хуки, використовуйте
макет пакетів хуків OpenClaw або постачайте нативний plugin.
</Accordion>
</AccordionGroup>
## Пов’язане
- [Встановлення та налаштування плагінів](/uk/tools/plugin)
- [Створення плагінів](/uk/plugins/building-plugins) — створіть нативний плагін
- [Маніфест плагіна](/uk/plugins/manifest) — схема нативного маніфесту
- [Install and Configure Plugins](/uk/tools/plugin)
- [Building Plugins](/uk/plugins/building-plugins) — створення нативного plugin
- [Plugin Manifest](/uk/plugins/manifest) — схема нативного маніфесту

325
docs/uk/plugins/codex-harness.md
View File

@ -1,75 +1,80 @@
---
read_when:
- Ви хочете використовувати комплектний каркас app-server Codex
- Ви хочете використовувати bundled harness app-server Codex
- Вам потрібні посилання на моделі Codex і приклади конфігурації
- Ви хочете вимкнути резервний перехід на PI для розгортань лише з Codex
summary: Запускайте вбудовані ходи агента OpenClaw через комплектний каркас app-server Codex
title: Каркас Codex
- Ви хочете вимкнути резервний варіант Pi для розгортань лише з Codex
summary: Запускайте вбудовані ходи агента OpenClaw через bundled harness app-server Codex
title: Harness Codex
x-i18n:
generated_at: "2026-04-23T02:13:09Z"
generated_at: "2026-04-23T07:12:59Z"
model: gpt-5.4
provider: openai
source_hash: dc2acc3dc906d12e12a837a25a52ec0e72d44325786106771045d456e6327040
source_hash: f5eff5a2af66033d575bc05c9f31a23ed0367bedc518dc25364e60a3012bfdff
source_path: plugins/codex-harness.md
workflow: 15
---
# Каркас Codex
# Harness Codex
Комплектний Plugin `codex` дає OpenClaw змогу виконувати вбудовані ходи агента через
app-server Codex замість вбудованого каркаса PI.
Bundled plugin `codex` дає змогу OpenClaw запускати вбудовані ходи агента через
app-server Codex замість вбудованого harness Pi.
Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням
моделей, нативним відновленням потоку, нативною Compaction і виконанням через
app-server. OpenClaw і далі керує каналами чату, файлами сесій, вибором моделей, інструментами,
схваленнями, доставкою медіа та видимим дзеркалом стенограми.
моделей, нативним відновленням thread, нативною Compaction і виконанням через app-server.
OpenClaw, як і раніше, керує чат-каналами, файлами сесій, вибором моделей, інструментами,
погодженнями, доставкою медіа та видимим дзеркалом транскрипту.
Нативні ходи Codex також враховують спільні хуки Plugin `before_prompt_build`,
`before_compaction` і `after_compaction`, тож шими промптів і
автоматизація з урахуванням Compaction можуть залишатися узгодженими з каркасом PI.
Нативні ходи Codex також враховують спільні хуки Plugin `before_prompt_build`,
`before_compaction`, `after_compaction`, `llm_input`, `llm_output` і
`agent_end`, тож шими промптів, автоматизація з урахуванням Compaction і
спостерігачі життєвого циклу можуть залишатися узгодженими з каркасом PI.
Нативні ходи Codex також поважають спільні хуки plugin, тож shim-и prompt,
автоматизація з урахуванням Compaction, middleware інструментів і спостерігачі життєвого циклу залишаються
узгодженими з harness Pi:
Каркас вимкнено за замовчуванням. Його буде вибрано лише тоді, коли Plugin `codex`
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `tool_result`, `after_tool_call`
- `before_message_write`
- `agent_end`
Bundled plugins також можуть реєструвати фабрику розширення app-server Codex для додавання
асинхронного middleware `tool_result`, а дзеркальні записи транскрипту Codex маршрутизуються
через `before_message_write`.
За замовчуванням harness вимкнено. Його буде вибрано лише тоді, коли plugin `codex`
увімкнено і визначена модель є моделлю `codex/*`, або коли ви явно
примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`.
Якщо ви взагалі не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local
і custom-provider зберігають поточну поведінку.
Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски Pi, OpenAI, Anthropic, Gemini, local
і custom-provider зберігають свою поточну поведінку.
## Виберіть правильний префікс моделі
OpenClaw має окремі маршрути для доступу у форматі OpenAI та Codex:
OpenClaw має окремі маршрути для доступу у стилі OpenAI та Codex:
| Посилання на модель | Шлях виконання | Використовуйте, коли |
| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Вам потрібен ChatGPT/Codex OAuth без каркаса app-server Codex. |
| `codex/gpt-5.4` | Комплектний провайдер Codex плюс каркас Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. |
| Посилання на модель | Шлях runtime | Використовуйте, коли |
| --------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| `openai/gpt-5.4` | Провайдер OpenAI через plumbing OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.4` | Провайдер OAuth OpenAI Codex через PI | Вам потрібен ChatGPT/Codex OAuth без harness app-server Codex. |
| `codex/gpt-5.4` | Bundled провайдер Codex плюс harness Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. |
Каркас Codex обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`,
Harness Codex обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`,
`openai-codex/*`, Anthropic, Gemini, xAI, local і custom provider зберігають
свої звичайні шляхи.
## Вимоги
- OpenClaw із доступним комплектним Plugin `codex`.
- app-server Codex версії `0.118.0` або новішої.
- Автентифікація Codex, доступна процесу app-server.
- OpenClaw з доступним bundled plugin `codex`.
- Codex app-server `0.118.0` або новіший.
- Автентифікація Codex, доступна для процесу app-server.
Plugin блокує старіші або безверсійні рукостискання app-server. Це утримує
OpenClaw на поверхні протоколу, з якою його було протестовано.
Plugin блокує старіші або безверсійні handshake app-server. Це утримує
OpenClaw на тій поверхні протоколу, з якою його було протестовано.
Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також
Для живих і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також
з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і
`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний
app-server Codex.
`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, що й ваш локальний app-server Codex.
## Мінімальна конфігурація
Використовуйте `codex/gpt-5.4`, увімкніть комплектний Plugin і примусово задайте
каркас `codex`:
Використовуйте `codex/gpt-5.4`, увімкніть bundled plugin і примусово задайте harness `codex`:
```json5
{
@ -92,7 +97,7 @@ app-server Codex.
}
```
Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`:
Якщо у вашій конфігурації використовується `plugins.allow`, включіть туди також `codex`:
```json5
{
@ -108,12 +113,12 @@ app-server Codex.
```
Установлення `agents.defaults.model` або моделі агента в `codex/<model>` також
автоматично вмикає комплектний Plugin `codex`. Явний запис Plugin, як і раніше,
корисний у спільних конфігураціях, оскільки робить намір розгортання очевидним.
автоматично вмикає bundled plugin `codex`. Явний запис plugin як і раніше
корисний у спільних конфігураціях, бо робить намір розгортання очевидним.
## Додайте Codex без заміни інших моделей
## Додати Codex без заміни інших моделей
Залиште `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для
Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а Pi — для
всього іншого:
```json5
@ -146,17 +151,17 @@ app-server Codex.
}
```
За такої форми:
З такою формою:
- `/model codex` або `/model codex/gpt-5.4` використовує каркас app-server Codex.
- `/model gpt` або `/model openai/gpt-5.4` використовує шлях через провайдер OpenAI.
- `/model opus` використовує шлях через провайдер Anthropic.
- Якщо вибрано модель не Codex, PI залишається каркасом сумісності.
- `/model codex` або `/model codex/gpt-5.4` використовує harness app-server Codex.
- `/model gpt` або `/model openai/gpt-5.4` використовує шлях провайдера OpenAI.
- `/model opus` використовує шлях провайдера Anthropic.
- Якщо вибрано не-Codex модель, Pi залишається сумісним harness.
## Розгортання лише з Codex
Вимкніть резервний перехід на PI, коли потрібно підтвердити, що кожен вбудований хід агента використовує
каркас Codex:
Вимкніть резервний варіант Pi, коли потрібно довести, що кожен вбудований хід агента використовує
harness Codex:
```json5
{
@ -180,14 +185,14 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
Коли резервний перехід вимкнено, OpenClaw завершує роботу з помилкою на ранньому етапі, якщо Plugin Codex вимкнено,
потрібна модель не є посиланням `codex/*`, app-server надто старий або
app-server не вдається запустити.
Коли резервний варіант вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо plugin Codex вимкнено,
запитувана модель не є посиланням `codex/*`, app-server надто старий або
app-server не може запуститися.
## Codex для окремого агента
Ви можете зробити одного агента лише для Codex, тоді як агент за замовчуванням зберігатиме звичайний
автовибір:
Ви можете зробити один агент лише з Codex, а агент за замовчуванням залишити зі звичайним
автовибором:
```json5
{
@ -219,13 +224,13 @@ app-server не вдається запустити.
```
Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову
сесію OpenClaw, а каркас Codex створює або відновлює свій sidecar-потік app-server
за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку.
сесію OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server
за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього thread.
## Виявлення моделей
За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо
виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог:
За замовчуванням plugin Codex запитує app-server про доступні моделі. Якщо
виявлення не вдається або перевищує час очікування, він використовує bundled резервний каталог:
- `codex/gpt-5.4`
- `codex/gpt-5.4-mini`
@ -251,8 +256,8 @@ app-server не вдається запустити.
}
```
Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і
використовувався резервний каталог:
Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалась перевірка Codex і використовувався
резервний каталог:
```json5
{
@ -273,19 +278,19 @@ app-server не вдається запустити.
## Підключення до app-server і політика
За замовчуванням Plugin запускає Codex локально так:
За замовчуванням plugin локально запускає Codex так:
```bash
codex app-server --listen stdio://
```
За замовчуванням OpenClaw запускає локальні сесії каркаса Codex у режимі YOLO:
За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO:
`approvalPolicy: "never"`, `approvalsReviewer: "user"` і
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується
для автономних Heartbeat: Codex може використовувати інструменти shell і мережі без
зупинок на нативних запитах схвалення, на які нікому відповісти.
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, що використовується
для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти без
зупинки на нативних запитах погодження, на які нікому відповідати.
Щоб увімкнути схвалення Codex, переглянуті Guardian, установіть `appServer.mode:
Щоб увімкнути погодження Codex, що перевіряються guardian, задайте `appServer.mode:
"guardian"`:
```json5
@ -306,7 +311,7 @@ codex app-server --listen stdio://
}
```
Режим Guardian розгортається в таке:
Режим guardian розгортається в:
```json5
{
@ -328,24 +333,24 @@ codex app-server --listen stdio://
}
```
Guardian — це нативний рецензент схвалень Codex. Коли Codex просить вийти з
пісочниці, записати за межами робочого простору або додати дозволи, наприклад доступ до мережі,
Codex надсилає цей запит на схвалення до підлеглого агента-рецензента, а не людині через
підказку. Рецензент збирає контекст і застосовує модель ризиків Codex, а потім
схвалює або відхиляє конкретний запит. Guardian корисний, коли вам потрібні
сильніші запобіжники, ніж у режимі YOLO, але все одно потрібні агенти без нагляду та Heartbeat,
які можуть просуватися далі.
Guardian — це нативний reviewer погоджень Codex. Коли Codex просить вийти з
sandbox, писати поза робочим простором або додати дозволи, як-от доступ до мережі,
Codex маршрутизує цей запит на погодження reviewer-субагенту замість запиту людині.
Reviewer збирає контекст і застосовує framework ризиків Codex, а потім
погоджує або відхиляє конкретний запит. Guardian корисний, коли вам потрібні сильніші
обмеження, ніж у режимі YOLO, але при цьому потрібні unattended-агенти й Heartbeat, щоб
продовжувати роботу.
Docker live harness містить перевірку Guardian, коли
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`. Він запускає каркас Codex у
режимі Guardian, перевіряє, що нешкідлива shell-команда з підвищенням привілеїв схвалюється, і
перевіряє, що вивантаження фальшивого секрету до недовіреного зовнішнього призначення відхиляється,
щоб агент повторно запросив явне схвалення.
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`. Він запускає harness Codex у
режимі Guardian, перевіряє, що безпечна команда shell з підвищенням дозволів погоджується, і
перевіряє, що завантаження фальшивого секрету в ненадійне зовнішнє призначення відхиляється,
щоб агент повернувся із запитом на явне погодження.
Окремі поля політики, як і раніше, мають пріоритет над `mode`, тож розширені розгортання можуть
поєднувати готове налаштування з явними параметрами.
Окремі поля політики все одно мають пріоритет над `mode`, тож розширені розгортання можуть
поєднувати preset з явними налаштуваннями.
Для app-server, який уже запущено, використовуйте транспорт WebSocket:
Для вже запущеного app-server використовуйте transport WebSocket:
```json5
{
@ -369,22 +374,22 @@ Docker live harness містить перевірку Guardian, коли
Підтримувані поля `appServer`:
| Поле | За замовчуванням | Значення |
| ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
| `command` | `"codex"` | Виконуваний файл для транспорту stdio. |
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. |
| `url` | не задано | URL app-server WebSocket. |
| `authToken` | не задано | Bearer-токен для транспорту WebSocket. |
| `headers` | `{}` | Додаткові заголовки WebSocket. |
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів площини керування app-server. |
| `mode` | `"yolo"` | Готове налаштування для виконання в режимі YOLO або з рецензуванням Guardian. |
| `approvalPolicy` | `"never"` | Нативна політика схвалення Codex, що надсилається під час запуску/відновлення потоку та ходу. |
| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається під час запуску/відновлення потоку. |
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти запити. |
| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
| Поле | Типове значення | Значення |
| ------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
| `command` | `"codex"` | Виконуваний файл для transport stdio. |
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для transport stdio. |
| `url` | не задано | URL app-server WebSocket. |
| `authToken` | не задано | Bearer-токен для transport WebSocket. |
| `headers` | `{}` | Додаткові заголовки WebSocket. |
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. |
| `mode` | `"yolo"` | Preset для виконання в режимі YOLO або з перевіркою guardian. |
| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час start/resume/turn thread. |
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час start/resume thread. |
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дати Codex Guardian перевіряти prompts. |
| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Недійсні застарілі значення ігноруються. |
Старіші змінні середовища, як і раніше, працюють як резервні варіанти для локального тестування, коли
Старіші змінні середовища все ще працюють як резервні варіанти для локального тестування, коли
відповідне поле конфігурації не задано:
- `OPENCLAW_CODEX_APP_SERVER_BIN`
@ -395,13 +400,13 @@ Docker live harness містить перевірку Guardian, коли
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте
`plugins.entries.codex.config.appServer.mode: "guardian"` або
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація
є кращою для відтворюваних розгортань, оскільки зберігає поведінку Plugin в тому
самому перевіреному файлі, що й решта налаштувань каркаса Codex.
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Для
відтворюваних розгортань перевага надається конфігурації, оскільки вона зберігає поведінку plugin
в тому самому перевіреному файлі, що й решта налаштування harness Codex.
## Поширені рецепти
Локальний Codex зі стандартним транспортом stdio:
Локальний Codex із типовим transport stdio:
```json5
{
@ -415,7 +420,7 @@ Docker live harness містить перевірку Guardian, коли
}
```
Перевірка каркаса лише Codex, із вимкненим резервним переходом на PI:
Перевірка harness лише з Codex, з вимкненим резервним варіантом Pi:
```json5
{
@ -432,7 +437,7 @@ Docker live harness містить перевірку Guardian, коли
}
```
Схвалення Codex, перевірені Guardian:
Погодження Codex, перевірені guardian:
```json5
{
@ -477,92 +482,92 @@ Docker live harness містить перевірку Guardian, коли
}
```
Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw під’єднано
до наявного потоку Codex, наступний хід знову надсилає до
app-server поточні вибрані `codex/*` модель, провайдер, політику схвалення, пісочницю та рівень сервісу.
Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано
до наявного thread Codex, наступний хід знову надсилає до
app-server поточні вибрані `codex/*` модель, провайдера, політику погодження, sandbox і service tier.
Перемикання з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає
прив’язку до потоку, але просить Codex продовжити з нововибраною моделлю.
прив’язку до thread, але просить Codex продовжити з новою вибраною моделлю.
## Команда Codex
Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона
є універсальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw.
Bundled plugin реєструє `/codex` як авторизовану slash-команду. Вона є
універсальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw.
Поширені форми:
- `/codex status` показує стан підключення до live app-server, моделі, обліковий запис, обмеження швидкості, сервери MCP і skills.
- `/codex models` показує список live-моделей app-server Codex.
- `/codex threads [filter]` показує список нещодавніх потоків Codex.
- `/codex resume <thread-id>` приєднує поточну сесію OpenClaw до наявного потоку Codex.
- `/codex compact` просить app-server Codex виконати Compaction для приєднаного потоку.
- `/codex review` запускає нативне рев’ю Codex для приєднаного потоку.
- `/codex account` показує стан облікового запису та обмежень швидкості.
- `/codex mcp` показує стан серверів MCP app-server Codex.
- `/codex skills` показує Skills app-server Codex.
- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, rate limit, MCP-сервери та Skills.
- `/codex models` перелічує моделі живого app-server Codex.
- `/codex threads [filter]` перелічує нещодавні thread Codex.
- `/codex resume <thread-id>` приєднує поточну сесію OpenClaw до наявного thread Codex.
- `/codex compact` просить app-server Codex виконати Compaction для приєднаного thread.
- `/codex review` запускає нативне review Codex для приєднаного thread.
- `/codex account` показує стан облікового запису та rate limit.
- `/codex mcp` перелічує стан MCP-серверів app-server Codex.
- `/codex skills` перелічує Skills app-server Codex.
`/codex resume` записує той самий файл sidecar-прив’язки, який каркас використовує для
звичайних ходів. На наступному повідомленні OpenClaw відновлює цей потік Codex, передає
поточну вибрану в OpenClaw модель `codex/*` до app-server і зберігає увімкненою
розширену історію.
`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає
поточну вибрану модель OpenClaw `codex/*` до app-server і зберігає
розширену історію ввімкненою.
Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Окремі
методи керування повідомляються як `unsupported by this Codex app-server`, якщо
майбутній або користувацький app-server не надає цього JSON-RPC-методу.
Поверхня команд вимагає Codex app-server `0.118.0` або новішого. Окремі
методи керування позначаються як `unsupported by this Codex app-server`, якщо
майбутній або користувацький app-server не надає цей JSON-RPC-метод.
## Інструменти, медіа та Compaction
Каркас Codex змінює лише низькорівневий виконавець вбудованого агента.
Harness Codex змінює лише низькорівневий виконавець вбудованого агента.
OpenClaw і далі формує список інструментів і отримує динамічні результати інструментів від
каркаса. Текст, зображення, відео, музика, TTS, схвалення та вивід інструментів обміну повідомленнями
і далі проходять звичайним шляхом доставки OpenClaw.
OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від
harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями
і далі проходять через звичайний шлях доставки OpenClaw.
Запити на схвалення інструментів Codex MCP маршрутизуються через потік
схвалення Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
`"mcp_tool_call"`; інші запити на підтвердження та запити довільного введення, як і раніше, завершуються
заборонено за замовчуванням.
Запити на погодження інструментів Codex MCP маршрутизуються через plugin-потік
погодження OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
`"mcp_tool_call"`; інші запити elicitation і запити довільного введення, як і раніше, відхиляються
за принципом fail-closed.
Коли вибрана модель використовує каркас Codex, нативна Compaction потоку
делегується app-server Codex. OpenClaw зберігає дзеркало стенограми для
історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або каркаса. Дзеркало
містить запит користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex,
коли їх генерує app-server. Наразі OpenClaw записує лише сигнали
початку та завершення нативної Compaction. Він іще не показує
зрозуміле для людини зведення Compaction або придатний для аудиту список того, які записи Codex
зберіг після Compaction.
Коли вибрана модель використовує harness Codex, нативна Compaction thread
делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу,
пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало
містить prompt користувача, фінальний текст помічника та полегшені записи
міркувань або плану Codex, коли app-server їх видає. Наразі OpenClaw лише
записує сигнали початку й завершення нативної Compaction. Він поки не показує
людинозрозумілий підсумок Compaction або придатний для аудиту список того, які записи Codex
залишив після Compaction.
Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і
розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як
Генерація медіа не потребує Pi. Генерація зображень, відео, музики, PDF, TTS і
розуміння медіа, як і раніше, використовує відповідні налаштування провайдера/моделі, такі як
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і
`messages.tts`.
## Усунення неполадок
## Усунення несправностей
**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`,
задайте посилання на модель `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`.
**OpenClaw використовує PI замість Codex:** якщо жоден каркас Codex не обробляє запуск,
OpenClaw може використовувати PI як сумісний бекенд. Установіть
**OpenClaw використовує Pi замість Codex:** якщо жоден harness Codex не обробляє запуск,
OpenClaw може використовувати Pi як сумісний бекенд. Задайте
`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або
`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден каркас Plugin не підходить. Щойно
буде вибрано app-server Codex, його збої проявлятимуться безпосередньо, без додаткової
конфігурації резервного переходу.
`embeddedHarness.fallback: "none"`, щоб отримувати помилку, коли жоден plugin-harness не збігається. Коли
app-server Codex уже вибрано, його збої відображаються напряму без додаткової
конфігурації резервного варіанту.
**app-server відхиляється:** оновіть Codex, щоб рукостискання app-server
повідомляло версію `0.118.0` або новішу.
**app-server відхиляється:** оновіть Codex, щоб handshake app-server
повідомляв версію `0.118.0` або новішу.
**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs`
або вимкніть виявлення.
**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken`
і те, що віддалений app-server використовує ту саму версію протоколу app-server Codex.
**transport WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken`
і що віддалений app-server використовує ту саму версію протоколу app-server Codex.
**Модель не Codex використовує PI:** це очікувано. Каркас Codex обробляє лише
**Не-Codex модель використовує Pi:** це очікувана поведінка. Harness Codex обробляє лише
посилання на моделі `codex/*`.
## Пов’язані матеріали
## Пов’язане
- [Plugins каркаса агента](/uk/plugins/sdk-agent-harness)
- [Провайдери моделей](/uk/concepts/model-providers)
- [Довідник із конфігурації](/uk/gateway/configuration-reference)
- [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke)
- [Agent Harness Plugins](/uk/plugins/sdk-agent-harness)
- [Model Providers](/uk/concepts/model-providers)
- [Configuration Reference](/uk/gateway/configuration-reference)
- [Testing](/uk/help/testing#live-codex-app-server-harness-smoke)

258
docs/uk/reference/RELEASING.md
View File

@ -1,199 +1,203 @@
---
read_when:
- Пошук визначень публічних каналів релізів
- Пошук іменування версій і каденції
summary: Публічні канали релізів, іменування версій і каденція
title: Політика релізів
- Пошук визначень публічних каналів випуску
- Пошук іменування версій і cadence
summary: Публічні канали випуску, іменування версій і cadence
title: Політика випусків
x-i18n:
generated_at: "2026-04-23T05:16:41Z"
generated_at: "2026-04-23T07:12:59Z"
model: gpt-5.4
provider: openai
source_hash: 979fd30ec717e107858ff812ef4b46060b9a00a0b5a3c23085d95b8fb81723b8
source_hash: b31a9597d656ef33633e6aa1c1019287f7197bebff1e6b11d572e41c149c7cff
source_path: reference/RELEASING.md
workflow: 15
---
# Політика релізів
# Політика випусків
OpenClaw має три публічні гілки релізів:
OpenClaw має три публічні канали випуску:
- stable: теговані релізи, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, якщо це явно запитано
- beta: теги попередніх релізів, які публікуються в npm `beta`
- dev: рухома вершина `main`
- stable: позначені тегами випуски, які типово публікуються в npm `beta`, або в npm `latest`, якщо це явно запитано
- beta: prerelease-теги, які публікуються в npm `beta`
- dev: рухома голова `main`
## Іменування версій
- Версія stable-релізу: `YYYY.M.D`
- Версія stable-випуску: `YYYY.M.D`
- Git-тег: `vYYYY.M.D`
- Версія виправного stable-релізу: `YYYY.M.D-N`
- Версія stable-коригувального випуску: `YYYY.M.D-N`
- Git-тег: `vYYYY.M.D-N`
- Версія beta-пререлізу: `YYYY.M.D-beta.N`
- Версія beta prerelease: `YYYY.M.D-beta.N`
- Git-тег: `vYYYY.M.D-beta.N`
- Не додавайте нулі на початку місяця або дня
- `latest` означає поточний просунутий stable-реліз npm
- `beta` означає поточну ціль установлення beta
- Stable-релізи та виправні stable-релізи за замовчуванням публікуються в npm `beta`; оператори релізів можуть явно націлити `latest` або пізніше просунути перевірену beta-збірку
- Кожен stable-реліз OpenClaw постачається разом із npm-пакетом і застосунком macOS;
beta-релізи зазвичай спочатку перевіряють і публікують шлях npm/package, а
збирання/підписування/нотаризація застосунку macOS зарезервовані для stable, якщо явно не запитано інше
- Не додавайте ведучі нулі для місяця або дня
- `latest` означає поточний просунутий stable-випуск npm
- `beta` означає поточну ціль встановлення beta
- Stable і stable-коригувальні випуски типово публікуються в npm `beta`; оператори випуску можуть явно націлитися на `latest` або пізніше просунути перевірену beta-збірку
- Кожен stable-випуск OpenClaw постачається разом як npm-пакет і застосунок macOS;
beta-випуски зазвичай спочатку перевіряють і публікують шлях npm/package, а
збірка/підпис/нотаризація mac-застосунку зарезервовані для stable, якщо явно не запитано
## Каденція релізів
## Cadence випусків
- Релізи рухаються за схемою beta-first
- Stable з’являється лише після перевірки найновішої beta
- Мейнтейнери зазвичай роблять релізи з гілки `release/YYYY.M.D`, створеної
з поточної `main`, щоб перевірка релізу та виправлення не блокували нову
- Випуски рухаються beta-first
- Stable слідує лише після перевірки останньої beta
- Мейнтейнери зазвичай створюють випуски з гілки `release/YYYY.M.D`, створеної
з поточної `main`, щоб перевірка випуску й виправлення не блокували нову
розробку в `main`
- Якщо beta-тег уже було запушено або опубліковано й потрібне виправлення, мейнтейнери створюють
наступний тег `-beta.N` замість видалення або перевідтворення старого beta-тега
- Детальна процедура релізу, погодження, облікові дані та примітки щодо відновлення
- Якщо beta-тег уже був надісланий або опублікований і потребує виправлення, мейнтейнери створюють
наступний тег `-beta.N` замість видалення або повторного створення старого beta-тега
- Детальна процедура випуску, погодження, облікові дані та нотатки з відновлення
доступні лише мейнтейнерам
## Передрелізна перевірка
## Передстартова перевірка випуску
- Запустіть `pnpm check:test-types` перед передрелізною перевіркою, щоб покриття
тестового TypeScript зберігалося поза швидшою локальною перевіркою `pnpm check`
- Запустіть `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші
перевірки циклів імпортів і меж архітектури були зеленими поза швидшою локальною перевіркою
- Запустіть `pnpm check:test-types` перед передстартовою перевіркою випуску, щоб тестовий TypeScript
залишався покритим поза швидшим локальним gate `pnpm check`
- Запустіть `pnpm check:architecture` перед передстартовою перевіркою випуску, щоб ширші перевірки
циклів імпорту та меж архітектури були зеленими поза швидшим локальним gate
- Запустіть `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані
артефакти релізу `dist/*` і бандл Control UI існували для кроку
артефакти випуску `dist/*` і bundle Control UI існували для кроку
перевірки pack
- Запускайте `pnpm release:check` перед кожним тегованим релізом
- Перевірки релізу тепер запускаються в окремому ручному workflow:
- Запускайте `pnpm release:check` перед кожним випуском із тегом
- Перевірки випуску тепер запускаються в окремому ручному workflow:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` також запускає ворота паритету макетів QA Lab плюс
live-гілки QA для Matrix і Telegram перед погодженням релізу. Live-гілки використовують
- `OpenClaw Release Checks` також запускає gate mock parity QA Lab плюс live
канали QA Matrix і Telegram перед погодженням випуску. Live-канали використовують
середовище `qa-live-shared`; Telegram також використовує оренду облікових даних Convex CI.
- Крос-ОС перевірка виконання встановлення та оновлення надсилається з
- Валідація середовища виконання встановлення й оновлення між ОС запускається з
приватного caller-workflow
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`,
який викликає повторно використовуваний публічний workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- Цей поділ навмисний: зберегти реальний шлях npm-релізу коротким,
детермінованим і зосередженим на артефактах, тоді як повільніші live-перевірки залишаються у
власній гілці, щоб вони не затримували й не блокували публікацію
- Перевірки релізу потрібно запускати з workflow-ref `main` або з
workflow-ref `release/YYYY.M.D`, щоб логіка workflow і секрети залишалися
- Цей поділ навмисний: реальний шлях npm-випуску має залишатися коротким,
детермінованим і зосередженим на артефактах, тоді як повільніші live-перевірки залишаються
у власному каналі, щоб не затримувати й не блокувати публікацію
- Перевірки випуску мають запускатися з workflow ref `main` або з
workflow ref `release/YYYY.M.D`, щоб логіка workflow і секрети залишалися
контрольованими
- Цей workflow приймає або наявний тег релізу, або поточний повний
- Цей workflow приймає або наявний тег випуску, або поточний повний
40-символьний commit SHA гілки workflow
- У режимі commit-SHA він приймає лише поточний HEAD гілки workflow; для
старіших комітів релізу використовуйте тег релізу
- Передрелізна перевірка лише для валідації `OpenClaw NPM Release` також приймає поточний
повний 40-символьний commit SHA гілки workflow без вимоги запушеного тега
- Цей шлях через SHA призначений лише для валідації й не може бути просунутий до реальної публікації
старіших commit випуску використовуйте тег випуску
- Передстартова перевірка лише для валідації `OpenClaw NPM Release` також приймає поточний
повний 40-символьний commit SHA гілки workflow без вимоги надісланого тега
- Цей шлях SHA є лише валідаційним і не може бути просунутий до реальної публікації
- У режимі SHA workflow синтезує `v<package.json version>` лише для перевірки
метаданих пакета; реальна публікація все одно вимагає реального тега релізу
- Обидва workflow зберігають реальний шлях публікації та просування на GitHub-hosted
runners, тоді як немутаційний шлях валідації може використовувати більші
Linux-runners від Blacksmith
метаданих пакета; реальна публікація все одно потребує реального тега випуску
- Обидва workflow залишають реальний шлях публікації та просування на runner-ах GitHub-hosted, тоді як шлях валідації без змін стану може використовувати більші
Linux runner-и Blacksmith
- Цей workflow запускає
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
використовуючи обидва секрети workflow: `OPENAI_API_KEY` і `ANTHROPIC_API_KEY`
- Передрелізна перевірка npm-релізу більше не очікує на окрему гілку перевірок релізу
- Запустіть `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(або відповідний beta/виправний тег) перед погодженням
- Після публікації npm запустіть
використовуючи обидва workflow secrets: `OPENAI_API_KEY` і `ANTHROPIC_API_KEY`
- Передстартова перевірка npm-випуску більше не чекає на окремий канал перевірок випуску
- Запускайте `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(або відповідний beta/correction-тег) перед погодженням
- Після публікації в npm запустіть
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(або відповідну beta/виправну версію), щоб перевірити опублікований шлях
установлення з реєстру в новому тимчасовому prefix
- Автоматизація релізів мейнтейнерів тепер використовує схему preflight-then-promote:
- реальна публікація в npm повинна пройти успішний npm `preflight_run_id`
- реальна публікація в npm повинна бути запущена з тієї ж гілки `main` або
`release/YYYY.M.D`, що й успішний передрелізний запуск
- stable-релізи npm за замовчуванням націлені на `beta`
- stable-публікація npm може явно націлювати `latest` через вхід workflow
- мутація npm dist-tag на основі токена тепер розміщена в
(або відповідну beta/correction-версію), щоб перевірити опублікований шлях
встановлення з реєстру в новому тимчасовому префіксі
- Автоматизація випусків мейнтейнерів тепер використовує preflight-then-promote:
- реальна публікація в npm має пройти успішний npm `preflight_run_id`
- реальна публікація в npm має запускатися з тієї самої гілки `main` або
`release/YYYY.M.D`, що й успішний передстартовий запуск
- stable npm-випуски типово націлюються на `beta`
- stable npm-публікація може явно націлюватися на `latest` через вхідні дані workflow
- зміна npm dist-tag на основі токена тепер знаходиться в
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
з міркувань безпеки, оскільки `npm dist-tag add` усе ще потребує `NPM_TOKEN`, тоді як
з міркувань безпеки, тому що `npm dist-tag add` усе ще потребує `NPM_TOKEN`, тоді як
публічний репозиторій зберігає публікацію лише через OIDC
- публічний `macOS Release` призначений лише для валідації
- реальна приватна публікація mac повинна пройти успішні приватні mac
- публічний `macOS Release` — лише для валідації
- реальна приватна mac-публікація має пройти успішні приватні mac
`preflight_run_id` і `validate_run_id`
- реальні шляхи публікації просувають підготовлені артефакти замість їх повторного збирання
- Для виправних stable-релізів, таких як `YYYY.M.D-N`, засіб перевірки після публікації
також перевіряє той самий шлях оновлення в тимчасовому prefix з `YYYY.M.D` до `YYYY.M.D-N`,
щоб виправлення релізу не могли непомітно залишити старіші глобальні встановлення на
базовому stable-корисному навантаженні
- Передрелізна перевірка npm-релізу завершується з відмовою за замовчуванням, якщо tarball не містить і
`dist/control-ui/index.html`, і непорожнього вмісту `dist/control-ui/assets/`,
щоб ми знову не випустили порожню панель керування в браузері
- `pnpm test:install:smoke` також забезпечує дотримання бюджету `unpackedSize` для npm pack
на кандидатному tarball оновлення, тож e2e інсталятора виявляє випадкове
роздуття pack до шляху публікації релізу
- Якщо робота над релізом торкалася планування CI, маніфестів таймінгів розширень або
матриць тестів розширень, згенеруйте заново й перегляньте належні планувальнику
результати матриці workflow `checks-node-extensions` із `.github/workflows/ci.yml`
перед погодженням, щоб примітки до релізу не описували застарілу структуру CI
- Готовність stable-релізу macOS також охоплює поверхні оновлювача:
- GitHub-реліз повинен у підсумку містити запаковані `.zip`, `.dmg` і `.dSYM.zip`
- `appcast.xml` у `main` після публікації повинен вказувати на новий stable zip
- запакований застосунок повинен зберігати не-debug bundle id, непорожню Sparkle feed
URL і `CFBundleVersion` на рівні або вище за канонічну мінімальну межу збірки Sparkle
для цієї версії релізу
- реальні шляхи публікації просувають підготовлені артефакти замість повторної
їх збірки
- Для stable-коригувальних випусків на кшталт `YYYY.M.D-N` post-publish verifier
також перевіряє той самий шлях оновлення в тимчасовому префіксі з `YYYY.M.D` до `YYYY.M.D-N`,
щоб коригувальні випуски не могли непомітно залишити старіші глобальні встановлення на
базовому stable payload
- Передстартова перевірка npm-випуску завершується з відмовою за замовчуванням, якщо tarball не містить і `dist/control-ui/index.html`, і непорожнього payload `dist/control-ui/assets/`,
щоб ми знову не відправили порожню browser dashboard
- Post-publish verification також перевіряє, що опубліковане встановлення з реєстру
містить непорожні bundled runtime deps плагінів у кореневому макеті `dist/*`.
Випуск, який постачається з відсутнім або порожнім payload залежностей
bundled plugin, не проходить postpublish verifier і не може бути просунутий
до `latest`.
- `pnpm test:install:smoke` також забезпечує бюджет `unpackedSize` для npm pack
у tarball кандидата на оновлення, щоб e2e інсталятора виявляв випадкове роздуття pack
до шляху публікації випуску
- Якщо робота над випуском торкалася планування CI, маніфестів timing для extensions або
матриць тестування extensions, перед погодженням заново згенеруйте й перегляньте
виходи матриці workflow `checks-node-extensions`, що належать planner-у, з `.github/workflows/ci.yml`,
щоб примітки до випуску не описували застарілу структуру CI
- Готовність stable-випуску macOS також включає поверхні оновлювача:
- GitHub release має в підсумку містити запаковані `.zip`, `.dmg` і `.dSYM.zip`
- `appcast.xml` у `main` має вказувати на новий stable zip після публікації
- запакований застосунок має зберігати не-debug bundle id, непорожній Sparkle feed
URL і `CFBundleVersion` на рівні або вище канонічної нижньої межі Sparkle build
для цієї версії випуску
## Входи workflow NPM
## Вхідні дані workflow NPM
`OpenClaw NPM Release` приймає такі керовані оператором входи:
`OpenClaw NPM Release` приймає такі керовані оператором вхідні дані:
- `tag`: обов’язковий тег релізу, наприклад `v2026.4.2`, `v2026.4.2-1`, або
- `tag`: обов’язковий тег випуску, наприклад `v2026.4.2`, `v2026.4.2-1` або
`v2026.4.2-beta.1`; коли `preflight_only=true`, це також може бути поточний
повний 40-символьний commit SHA гілки workflow для передрелізної перевірки лише для валідації
- `preflight_only`: `true` для лише валідації/збирання/пакування, `false` для
повний 40-символьний commit SHA гілки workflow для передстартової перевірки лише з валідацією
- `preflight_only`: `true` для лише валідації/збірки/пакування, `false` для
реального шляху публікації
- `preflight_run_id`: обов’язковий на реальному шляху публікації, щоб workflow повторно використав
підготовлений tarball з успішного передрелізного запуску
- `npm_dist_tag`: цільовий npm-тег для шляху публікації; за замовчуванням `beta`
підготовлений tarball з успішного передстартового запуску
- `npm_dist_tag`: цільовий npm-tag для шляху публікації; типово `beta`
`OpenClaw Release Checks` приймає такі керовані оператором входи:
`OpenClaw Release Checks` приймає такі керовані оператором вхідні дані:
- `ref`: наявний тег релізу або поточний повний 40-символьний commit
SHA `main` для валідації при запуску з `main`; із гілки релізу використовуйте
наявний тег релізу або поточний повний 40-символьний commit
SHA гілки релізу
- `ref`: наявний тег випуску або поточний повний 40-символьний commit
SHA `main`, який потрібно перевірити під час запуску з `main`; із гілки випуску використовуйте
наявний тег випуску або поточний повний 40-символьний commit
SHA гілки випуску
Правила:
- Stable- і виправні теги можуть публікуватися або в `beta`, або в `latest`
- Beta-теги попередніх релізів можуть публікуватися лише в `beta`
- Для `OpenClaw NPM Release` повний вхід commit SHA дозволено лише коли
- Stable і correction-теги можуть публікуватися або в `beta`, або в `latest`
- Beta prerelease-теги можуть публікуватися лише в `beta`
- Для `OpenClaw NPM Release` повний вхідний commit SHA дозволений лише коли
`preflight_only=true`
- `OpenClaw Release Checks` завжди призначений лише для валідації й також приймає
- `OpenClaw Release Checks` завжди є лише валідаційним і також приймає
поточний commit SHA гілки workflow
- Режим commit-SHA для перевірок релізу також вимагає поточного HEAD гілки workflow
- Реальний шлях публікації повинен використовувати той самий `npm_dist_tag`, який використовувався під час передрелізної перевірки;
workflow перевіряє ці метадані перед продовженням публікації
- Режим commit-SHA для перевірок випуску також вимагає поточного HEAD гілки workflow
- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, що використовувався під час preflight;
workflow перевіряє ці метадані, перш ніж публікація продовжиться
## Послідовність stable npm-релізу
## Послідовність stable npm-випуску
Під час випуску stable npm-релізу:
Під час створення stable npm-випуску:
1. Запустіть `OpenClaw NPM Release` з `preflight_only=true`
- До появи тега ви можете використовувати поточний повний commit
SHA гілки workflow для dry run передрелізного workflow лише для валідації
2. Виберіть `npm_dist_tag=beta` для звичайного потоку beta-first або `latest` лише
коли ви свідомо хочете прямої stable-публікації
SHA гілки workflow для dry run передстартового workflow лише з валідацією
2. Виберіть `npm_dist_tag=beta` для звичайного потоку beta-first або `latest`, лише
коли ви навмисно хочете прямий stable-випуск
3. Окремо запустіть `OpenClaw Release Checks` з тим самим тегом або
повним поточним commit SHA гілки workflow, коли вам потрібне покриття live prompt cache,
паритету QA Lab, Matrix і Telegram
- Це навмисно винесено окремо, щоб live-покриття залишалося доступним без
parity QA Lab, Matrix і Telegram
- Це окремо навмисно, щоб live-покриття залишалося доступним без
повторного зв’язування довготривалих або нестабільних перевірок із workflow публікації
4. Збережіть успішний `preflight_run_id`
5. Знову запустіть `OpenClaw NPM Release` з `preflight_only=false`, тим самим
`tag`, тим самим `npm_dist_tag` і збереженим `preflight_run_id`
6. Якщо реліз потрапив у `beta`, використайте приватний workflow
6. Якщо випуск потрапив у `beta`, використайте приватний workflow
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
щоб просунути цю stable-версію з `beta` до `latest`
7. Якщо реліз навмисно був опублікований одразу в `latest`, а `beta`
має одразу наслідувати ту саму stable-збірку, використайте той самий приватний
workflow, щоб спрямувати обидва dist-tags на stable-версію, або дозвольте його запланованій
самовідновлювальній синхронізації перемістити `beta` пізніше
7. Якщо випуск був навмисно опублікований одразу в `latest`, а `beta`
має негайно слідувати за тією самою stable-збіркою, використайте той самий приватний
workflow, щоб спрямувати обидва dist-tag на stable-версію, або дозвольте запланованій
self-healing синхронізації перемістити `beta` пізніше
Мутація dist-tag розміщена в приватному репозиторії з міркувань безпеки, оскільки вона все ще
Зміна dist-tag живе в приватному репозиторії з міркувань безпеки, тому що вона все ще
потребує `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікацію лише через OIDC.
Це зберігає як шлях прямої публікації, так і шлях beta-first просування
задокументованими та видимими для операторів.
Це зберігає і шлях прямої публікації, і шлях просування beta-first
задокументованими та видимими для оператора.
## Публічні посилання
@ -204,6 +208,6 @@ OpenClaw має три публічні гілки релізів:
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
Мейнтейнери використовують приватну документацію з релізів у
Мейнтейнери використовують приватну документацію випусків у
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
як фактичний runbook.

611
docs/uk/tools/acp-agents.md
View File

File diff suppressed because it is too large Load Diff

153
docs/uk/tools/thinking.md
View File

@ -1,13 +1,13 @@
---
read_when:
- Налаштування аналізу директив для мислення, швидкого режиму або докладного режиму чи їхніх значень за замовчуванням
summary: Синтаксис директив для `/think`, `/fast`, `/verbose`, `/trace` і видимості міркувань
- Налаштування рівнів мислення, режиму fast або обробки чи типових значень директив verbose
summary: Синтаксис директив для /think, /fast, /verbose, /trace і видимості міркувань
title: Рівні мислення
x-i18n:
generated_at: "2026-04-21T18:02:10Z"
generated_at: "2026-04-23T07:13:38Z"
model: gpt-5.4
provider: openai
source_hash: c77f6f1318c428bbd21725ea5f32f8088506a10cbbf5b5cbca5973c72a5a81f9
source_hash: 66033bb9272c9b9ea8fc85dc91e33e95ce4c469c56a8cd10c19632a5aa8a2338
source_path: tools/thinking.md
workflow: 15
---
@ -16,29 +16,29 @@ x-i18n:
## Що це робить
- Вбудована директива в будь-якому вхідному тілі: `/t <рівень>`, `/think:<рівень>` або `/thinking <рівень>`.
- Рівні (аліаси): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- high → “ultrathink” (максимальний бюджет)
- xhigh → “ultrathink+” (GPT-5.2 + моделі Codex і рівень effort для Anthropic Claude Opus 4.7)
- adaptive → адаптивне мислення під керуванням провайдера (підтримується для Claude 4.6 на Anthropic/Bedrock і Anthropic Claude Opus 4.7)
- max → максимальне міркування провайдера (зараз Anthropic Claude Opus 4.7)
- Вбудована директива в будь-якому вхідному тілі: `/t <level>`, `/think:<level>` або `/thinking <level>`.
- Рівні (псевдоніми): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → «think»
- low → «think hard»
- medium → «think harder»
- high → «ultrathink» (максимальний бюджет)
- xhigh → «ultrathink+» (GPT-5.2 + моделі Codex і зусилля Anthropic Claude Opus 4.7)
- adaptive → кероване провайдером адаптивне мислення (підтримується для Claude 4.6 на Anthropic/Bedrock і Anthropic Claude Opus 4.7)
- max → максимальне міркування провайдера (наразі Anthropic Claude Opus 4.7)
- `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` зіставляються з `xhigh`.
- `highest` зіставляється з `high`.
- Примітки щодо провайдерів:
- Меню та селектори мислення керуються профілем провайдера. Плагіни провайдерів оголошують точний набір рівнів для вибраної моделі, включно з мітками на кшталт бінарного `on`.
- `adaptive`, `xhigh` і `max` рекламуються лише для профілів провайдера/моделі, які їх підтримують. Введені директиви з непідтримуваними рівнями відхиляються з переліком дійсних опцій для цієї моделі.
- Наявні збережені непідтримувані рівні повторно зіставляються за рангом профілю провайдера. `adaptive` повертається до `medium` на неадаптивних моделях, а `xhigh` і `max` повертаються до найбільшого підтримуваного рівня, відмінного від `off`, для вибраної моделі.
- Меню та перемикачі мислення керуються профілями провайдерів. Plugin провайдерів оголошують точний набір рівнів для вибраної моделі, включно з мітками на кшталт двійкового `on`.
- `adaptive`, `xhigh` і `max` рекламуються лише для профілів провайдер/модель, які їх підтримують. Введені директиви з непідтримуваними рівнями відхиляються з переліком коректних варіантів для цієї моделі.
- Наявні збережені непідтримувані рівні переназначаються за рангом профілю провайдера. `adaptive` повертається до `medium` на моделях без adaptive, а `xhigh` і `max` повертаються до найбільшого підтримуваного рівня, відмінного від `off`, для вибраної моделі.
- Моделі Anthropic Claude 4.6 за замовчуванням використовують `adaptive`, якщо явний рівень мислення не задано.
- Anthropic Claude Opus 4.7 за замовчуванням не використовує adaptive thinking. Типове значення effort в його API лишається під керуванням провайдера, якщо ви явно не задасте рівень мислення.
- Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з adaptive thinking плюс `output_config.effort: "xhigh"`, оскільки `/think` — це директива мислення, а `xhigh` — налаштування effort для Opus 4.7.
- Anthropic Claude Opus 4.7 також підтримує `/think max`; воно зіставляється з тим самим шляхом максимального effort під керуванням провайдера.
- Моделі OpenAI GPT зіставляють `/think` через підтримку effort у Responses API, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає payload вимкненого міркування замість надсилання непідтримуваного значення.
- MiniMax (`minimax/*`) на Anthropic-сумісному шляху потокової передачі за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не задали мислення в параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` із ненативного формату Anthropic-потоку MiniMax.
- Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який рівень, крім `off`, трактується як `on` (зіставляється з `low`).
- Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який рівень, відмінний від `off`, — з `thinking: { type: "enabled" }`. Коли мислення ввімкнене, Moonshot приймає для `tool_choice` лише `auto|none`; OpenClaw нормалізує несумісні значення до `auto`.
- Anthropic Claude Opus 4.7 за замовчуванням не використовує adaptive thinking. Типове значення effort API залишається у власності провайдера, якщо ви явно не встановите рівень мислення.
- Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з adaptive thinking плюс `output_config.effort: "xhigh"`, оскільки `/think` є директивою мислення, а `xhigh` — це налаштування effort для Opus 4.7.
- Anthropic Claude Opus 4.7 також підтримує `/think max`; це зіставляється з тим самим шляхом максимального effort, керованим провайдером.
- Моделі OpenAI GPT зіставляють `/think` через підтримку effort API Responses, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає payload вимкненого reasoning замість надсилання непідтримуваного значення.
- MiniMax (`minimax/*`) на Anthropic-сумісному шляху потокової передачі за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не встановите thinking у параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` із нерідного Anthropic-формату потоку MiniMax.
- Z.AI (`zai/*`) підтримує лише двійкове thinking (`on`/`off`). Будь-який рівень, відмінний від `off`, розглядається як `on` (зіставляється з `low`).
- Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який рівень, відмінний від `off`, — з `thinking: { type: "enabled" }`. Коли thinking увімкнено, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`.
## Порядок визначення
@ -46,86 +46,87 @@ x-i18n:
2. Перевизначення сесії (встановлюється надсиланням повідомлення, що містить лише директиву).
3. Типове значення для агента (`agents.list[].thinkingDefault` у config).
4. Глобальне типове значення (`agents.defaults.thinkingDefault` у config).
5. Резервний варіант: типове значення, оголошене провайдером, якщо доступне, `low` для інших моделей каталогу, позначених як здатні до міркування, і `off` в інших випадках.
5. Запасний варіант: типове значення, оголошене провайдером, якщо доступне, `low` для інших моделей каталогу, позначених як reasoning-capable, інакше `off`.
## Встановлення типового значення для сесії
## Установлення типового значення для сесії
- Надішліть повідомлення, яке **містить лише** директиву (пробіли дозволені), наприклад `/think:medium` або `/t high`.
- Це закріплюється для поточної сесії (типово для кожного відправника окремо); скидається через `/think:off` або скидання неактивної сесії.
- Надсилається підтверджувальна відповідь (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень недійсний (наприклад, `/thinking big`), команда відхиляється з підказкою, а стан сесії лишається без змін.
- Надішліть `/think` (або `/think:`) без аргументу, щоб побачити поточний рівень мислення.
- Надішліть повідомлення, яке **містить лише** директиву (дозволено пробіли), наприклад `/think:medium` або `/t high`.
- Це закріплюється для поточної сесії (типово окремо для кожного відправника); очищується через `/think:off` або скидання через бездіяльність сесії.
- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень некоректний (наприклад, `/thinking big`), команду буде відхилено з підказкою, а стан сесії залишиться без змін.
- Надішліть `/think` (або `/think:`) без аргументу, щоб переглянути поточний рівень мислення.
## Застосування за агентом
## Застосування для агента
- **Вбудований Pi**: визначений рівень передається у вбудоване середовище виконання агента Pi.
- **Вбудований Pi**: визначений рівень передається у runtime вбудованого агента Pi.
## Швидкий режим (/fast)
## Швидкий режим (`/fast`)
- Рівні: `on|off`.
- Повідомлення лише з директивою перемикає перевизначення швидкого режиму для сесії та повертає `Fast mode enabled.` / `Fast mode disabled.`.
- Надішліть `/fast` (або `/fast status`) без режиму, щоб побачити поточний ефективний стан швидкого режиму.
- OpenClaw визначає швидкий режим у такому порядку:
1. Вбудований/директивний `/fast on|off`
- Повідомлення лише з директивою перемикає перевизначення fast mode для сесії та повертає `Fast mode enabled.` / `Fast mode disabled.`.
- Надішліть `/fast` (або `/fast status`) без режиму, щоб переглянути поточний ефективний стан fast mode.
- OpenClaw визначає fast mode в такому порядку:
1. Вбудована/окрема директива `/fast on|off`
2. Перевизначення сесії
3. Типове значення для агента (`agents.list[].fastModeDefault`)
4. Конфігурація для моделі: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Резервний варіант: `off`
- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI шляхом надсилання `service_tier=priority` у підтримуваних запитах Responses.
- Для `openai-codex/*` швидкий режим надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw зберігає один спільний перемикач `/fast` для обох шляхів автентифікації.
- Для прямих публічних запитів `anthropic/*`, включно з трафіком з OAuth-автентифікацією, надісланим до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` встановлює `service_tier=auto`, `/fast off` встановлює `service_tier=standard_only`.
5. Запасний варіант: `off`
- Для `openai/*` fast mode зіставляється з пріоритетною обробкою OpenAI через надсилання `service_tier=priority` у підтримуваних запитах Responses.
- Для `openai-codex/*` fast mode надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw зберігає один спільний перемикач `/fast` для обох шляхів автентифікації.
- Для прямих публічних запитів `anthropic/*`, включно з трафіком, автентифікованим через OAuth і надісланим до `api.anthropic.com`, fast mode зіставляється з рівнями service tier Anthropic: `/fast on` встановлює `service_tier=auto`, `/fast off` встановлює `service_tier=standard_only`.
- Для `minimax/*` на Anthropic-сумісному шляху `/fast on` (або `params.fastMode: true`) переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають типове значення швидкого режиму, якщо задано обидва. OpenClaw усе одно пропускає інʼєкцію рівня сервісу Anthropic для проксі-базових URL, що не належать Anthropic.
- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають типове значення fast mode, коли задано обидва. OpenClaw, як і раніше, пропускає вставлення service tier Anthropic для базових URL не-Anthropic proxy.
- `/status` показує `Fast` лише тоді, коли fast mode увімкнено.
## Директиви докладного режиму (/verbose або /v)
## Докладні директиви (`/verbose` або `/v`)
- Рівні: `on` (мінімальний) | `full` | `off` (типово).
- Повідомлення лише з директивою перемикає докладний режим сесії та повертає `Verbose logging enabled.` / `Verbose logging disabled.`; недійсні рівні повертають підказку без зміни стану.
- `/verbose off` зберігає явне перевизначення сесії; очистити його можна через інтерфейс Sessions, вибравши `inherit`.
- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сесії/глобальні типові значення.
- Надішліть `/verbose` (або `/verbose:`) без аргументу, щоб побачити поточний рівень докладності.
- Коли докладний режим увімкнено, агенти, що видають структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, із префіксом `<emoji> <tool-name>: <arg>`, якщо доступно (path/command). Ці підсумки інструментів надсилаються щойно кожен інструмент запускається (окремими бульбашками), а не як потокові дельти.
- Підсумки збоїв інструментів лишаються видимими в нормальному режимі, але необроблені суфікси з деталями помилок приховуються, якщо verbose не має значення `on` або `full`.
- Коли verbose має значення `full`, після завершення також пересилаються виводи інструментів (окрема бульбашка, обрізана до безпечної довжини). Якщо ви перемкнете `/verbose on|full|off`, поки виконання ще триває, наступні бульбашки інструментів врахують нове налаштування.
- Повідомлення лише з директивою перемикає verbose для сесії та повертає `Verbose logging enabled.` / `Verbose logging disabled.`; некоректні рівні повертають підказку без зміни стану.
- `/verbose off` зберігає явне перевизначення сесії; очистити його можна в UI Sessions, вибравши `inherit`.
- Вбудована директива застосовується лише до цього повідомлення; інакше діють типові значення сесії/глобальні.
- Надішліть `/verbose` (або `/verbose:`) без аргументу, щоб переглянути поточний рівень verbose.
- Коли verbose увімкнено, агенти, що видають структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, із префіксом `<emoji> <tool-name>: <arg>`, коли доступно (шлях/команда). Ці зведення інструментів надсилаються щойно кожен інструмент запускається (окремими бульбашками), а не як дельти потоку.
- Зведення про збої інструментів залишаються видимими в нормальному режимі, але суфікси з необробленими деталями помилки приховуються, якщо verbose не має значення `on` або `full`.
- Коли verbose має значення `full`, результати інструментів також пересилаються після завершення (окрема бульбашка, обрізана до безпечної довжини). Якщо ви перемкнете `/verbose on|full|off`, поки виконання ще триває, наступні бульбашки інструментів врахують нове налаштування.
## Директиви трасування плагінів (/trace)
## Директиви trace Plugin (`/trace`)
- Рівні: `on` | `off` (типово).
- Повідомлення лише з директивою перемикає вивід трасування плагінів у сесії та повертає `Plugin trace enabled.` / `Plugin trace disabled.`.
- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сесії/глобальні типові значення.
- Надішліть `/trace` (або `/trace:`) без аргументу, щоб побачити поточний рівень трасування.
- `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать плагінам, наприклад зведення налагодження Active Memory.
- Рядки трасування можуть зʼявлятися в `/status` і як наступне діагностичне повідомлення після звичайної відповіді асистента.
- Повідомлення лише з директивою перемикає вивід trace plugin для сесії та повертає `Plugin trace enabled.` / `Plugin trace disabled.`.
- Вбудована директива застосовується лише до цього повідомлення; інакше діють типові значення сесії/глобальні.
- Надішліть `/trace` (або `/trace:`) без аргументу, щоб переглянути поточний рівень trace.
- `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать plugin, наприклад підсумки налагодження Active Memory.
- Рядки trace можуть з’являтися в `/status` і як додаткове діагностичне повідомлення після звичайної відповіді помічника.
## Видимість міркувань (/reasoning)
## Видимість міркувань (`/reasoning`)
- Рівні: `on|off|stream`.
- Повідомлення лише з директивою перемикає, чи показуються блоки мислення у відповідях.
- Якщо ввімкнено, міркування надсилаються як **окреме повідомлення** з префіксом `Reasoning:`.
- `stream` (лише Telegram): транслює міркування в чернеткову бульбашку Telegram, поки генерується відповідь, а потім надсилає фінальну відповідь без міркувань.
- Аліас: `/reason`.
- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень видимості міркувань.
- Порядок визначення: вбудована директива, потім перевизначення сесії, потім типове значення для агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`).
- Повідомлення лише з директивою перемикає показ блоків thinking у відповідях.
- Коли ввімкнено, reasoning надсилається як **окреме повідомлення** з префіксом `Reasoning:`.
- `stream` (лише Telegram): транслює reasoning у чернетку-бульбашку Telegram, поки генерується відповідь, а потім надсилає фінальну відповідь без reasoning.
- Псевдонім: `/reason`.
- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб переглянути поточний рівень reasoning.
- Порядок визначення: вбудована директива, потім перевизначення сесії, потім типове значення для агента (`agents.list[].reasoningDefault`), потім запасний варіант (`off`).
## Повʼязане
## Пов’язане
- Документація для elevated mode міститься в [Elevated mode](/uk/tools/elevated).
- Документація про Elevated mode доступна в [Elevated mode](/uk/tools/elevated).
## Heartbeat-и
## Heartbeat
- Тіло запиту перевірки Heartbeat — це налаштований запит Heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні Heartbeat застосовуються як завжди (але уникайте зміни типових значень сесії з Heartbeat-ів).
- Доставка Heartbeat типово використовує лише фінальний payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступно), встановіть `agents.defaults.heartbeat.includeReasoning: true` або `agents.list[].heartbeat.includeReasoning: true` для окремого агента.
- Тіло probe Heartbeat — це налаштований prompt heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні heartbeat застосовуються як зазвичай (але уникайте зміни типових значень сесії з heartbeat).
- Доставка Heartbeat за замовчуванням містить лише фінальний payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступне), установіть `agents.defaults.heartbeat.includeReasoning: true` або для окремого агента `agents.list[].heartbeat.includeReasoning: true`.
## Інтерфейс вебчату
## UI вебчату
- Селектор мислення у вебчаті відображає збережений рівень сесії зі сховища/конфігурації вхідної сесії, коли сторінка завантажується.
- Селектор thinking у вебчаті віддзеркалює збережений рівень сесії зі сховища/конфігурації вхідної сесії під час завантаження сторінки.
- Вибір іншого рівня негайно записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання і не є одноразовим перевизначенням `thinkingOnce`.
- Перший варіант завжди має вигляд `Default (<resolved level>)`, де визначене типове значення береться з профілю мислення провайдера для активної моделі сесії.
- Селектор використовує `thinkingOptions`, повернуті рядком сесії Gateway. Інтерфейс браузера не зберігає власний список regex провайдерів; плагіни керують наборами рівнів, специфічними для моделей.
- `/think:<level>` усе ще працює та оновлює той самий збережений рівень сесії, тож директиви чату й селектор залишаються синхронізованими.
- Перший варіант завжди має вигляд `Default (<resolved level>)`, де визначене типове значення походить із профілю thinking провайдера активної моделі сесії.
- Перемикач використовує `thinkingOptions`, повернені рядком сесії gateway. UI браузера не зберігає власний список regex провайдерів; набори рівнів, специфічні для моделі, належать plugin.
- `/think:<level>` як і раніше працює та оновлює той самий збережений рівень сесії, тому директиви чату й перемикач залишаються синхронізованими.
## Профілі провайдерів
- Плагіни провайдерів можуть відкривати `resolveThinkingProfile(ctx)` для визначення підтримуваних рівнів і типового значення моделі.
- Кожен рівень профілю має збережений канонічний `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` або `max`) і може містити відображувану `label`. Бінарні провайдери використовують `{ id: "low", label: "on" }`.
- Опубліковані застарілі хуки (`supportsXHighThinking`, `isBinaryThinking` і `resolveDefaultThinkingLevel`) лишаються адаптерами сумісності, але нові користувацькі набори рівнів мають використовувати `resolveThinkingProfile`.
- Рядки Gateway відкривають `thinkingOptions` і `thinkingDefault`, щоб ACP/чат-клієнти відображали той самий профіль, який використовується для валідації під час виконання.
- Plugin провайдерів можуть надавати `resolveThinkingProfile(ctx)` для визначення підтримуваних рівнів і типового значення моделі.
- Кожен рівень профілю має збережений канонічний `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` або `max`) і може містити відображувану `label`. Двійкові провайдери використовують `{ id: "low", label: "on" }`.
- Опубліковані застарілі хуки (`supportsXHighThinking`, `isBinaryThinking` і `resolveDefaultThinkingLevel`) залишаються адаптерами сумісності, але нові користувацькі набори рівнів мають використовувати `resolveThinkingProfile`.
- Рядки Gateway показують `thinkingOptions` і `thinkingDefault`, щоб клієнти ACP/чату відображали той самий профіль, який використовує перевірка runtime.

317
docs/uk/web/control-ui.md
View File

@ -2,13 +2,13 @@
read_when:
- Ви хочете керувати Gateway з браузера
- Ви хочете доступ через Tailnet без SSH-тунелів
summary: Браузерний Control UI для Gateway (чат, Node, конфігурація)
summary: Браузерний Control UI для Gateway (chat, Node, config)
title: Control UI
x-i18n:
generated_at: "2026-04-23T06:49:16Z"
generated_at: "2026-04-23T07:13:48Z"
model: gpt-5.4
provider: openai
source_hash: 05c5a1b9c0527d230b1657e15b1adf681817d279128af8197a14eb9bdde3d211
source_hash: 05bed9a917878d4849eb7502952e27b7c7a3bf848223735d513d545d51baef6d
source_path: web/control-ui.md
workflow: 15
---
@ -20,7 +20,7 @@ Control UI — це невеликий односторінковий засто
- типово: `http://<host>:18789/`
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
Він працює **безпосередньо з WebSocket Gateway** на тому самому порту.
Він взаємодіє **безпосередньо з WebSocket Gateway** на тому самому порту.
## Швидке відкриття (локально)
@ -30,7 +30,7 @@ Control UI — це невеликий односторінковий засто
Якщо сторінка не завантажується, спочатку запустіть Gateway: `openclaw gateway`.
Автентифікація передається під час рукостискання WebSocket через:
Автентифікація передається під час WebSocket handshake через:
- `connect.params.auth.token`
- `connect.params.auth.password`
@ -38,129 +38,155 @@ Control UI — це невеликий односторінковий засто
- заголовки ідентичності trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"`
Панель налаштувань dashboard зберігає токен для поточної сесії вкладки браузера
та вибраний URL gateway; паролі не зберігаються. Onboarding зазвичай
генерує токен gateway для автентифікації через спільний секрет при першому підключенні, але
автентифікація паролем теж працює, коли `gateway.auth.mode` дорівнює `"password"`.
та вибраної URL-адреси gateway; паролі не зберігаються. Onboarding зазвичай
генерує токен gateway для автентифікації через спільний секрет під час першого підключення, але
автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
## Pairing пристрою (перше підключення)
## Спарювання пристрою (перше підключення)
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway
потребує **одноразового схвалення pairing** — навіть якщо ви в тому самому Tailnet
вимагає **одноразове погодження спарювання** — навіть якщо ви перебуваєте в тій самій Tailnet
з `gateway.auth.allowTailscale: true`. Це захід безпеки для запобігання
несанкціонованому доступу.
**Що ви побачите:** "disconnected (1008): pairing required"
**Що ви побачите:** `"disconnected (1008): pairing required"`
**Щоб схвалити пристрій:**
**Щоб погодити пристрій:**
```bash
# Переглянути очікувані запити
# List pending requests
openclaw devices list
# Схвалити за ID запиту
# Approve by request ID
openclaw devices approve <requestId>
```
Якщо браузер повторює pairing зі зміненими даними автентифікації (роль/scopes/public
key), попередній очікуваний запит замінюється, і створюється новий `requestId`.
Перед схваленням знову виконайте `openclaw devices list`.
Якщо браузер повторює спробу спарювання зі зміненими даними автентифікації (role/scopes/public
key), попередній запит, що очікує розгляду, заміщується, і створюється новий `requestId`.
Перед погодженням знову виконайте `openclaw devices list`.
Якщо браузер уже paired і ви змінюєте його з доступу на читання на
доступ на запис/admin, це розглядається як підвищення рівня схвалення, а не як тихе
повторне підключення. OpenClaw зберігає старе схвалення активним, блокує ширше повторне підключення
і просить вас явно схвалити новий набір scope.
Якщо браузер уже спарений і ви змінюєте його з доступу read на
доступ write/admin, це розглядається як підвищення погодження, а не тихе
повторне підключення. OpenClaw зберігає старе погодження активним, блокує ширше повторне підключення
і просить вас явно погодити новий набір scope.
Після схвалення пристрій запам’ятовується і не вимагатиме повторного схвалення,
доки ви не відкличете його через `openclaw devices revoke --device <id> --role <role>`. Див.
[Devices CLI](/uk/cli/devices) щодо ротації токенів і відкликання.
Після погодження пристрій запам’ятовується і не вимагатиме повторного погодження, якщо
ви не відкличете його за допомогою `openclaw devices revoke --device <id> --role <role>`. Див.
[Devices CLI](/uk/cli/devices) для обертання токенів і відкликання.
**Примітки:**
- Прямі локальні браузерні підключення через loopback (`127.0.0.1` / `localhost`)
схвалюються автоматично.
- Підключення браузера через Tailnet і LAN усе одно потребують явного схвалення, навіть якщо
вони походять з тієї самої машини.
- Кожен профіль браузера генерує унікальний ID пристрою, тому зміна браузера або
очищення даних браузера потребуватиме повторного pairing.
- Прямі локальні браузерні підключення через loopback (`127.0.0.1` / `localhost`) погоджуються
автоматично.
- Браузерні підключення через Tailnet і LAN все одно потребують явного погодження, навіть коли
вони походять із тієї самої машини.
- Кожен профіль браузера генерує унікальний id пристрою, тому зміна браузера або
очищення даних браузера вимагатиме повторного спарювання.
## Персональна ідентичність (локально в браузері)
Control UI підтримує персональну ідентичність для кожного браузера — відображуване ім’я та
аватар, які додаються до вихідних повідомлень для атрибуції у спільних
сесіях. Ця ідентичність зберігається в сховищі браузера, прив’язана до поточного
профілю браузера і не залишає хост gateway, якщо ви явно не
надсилаєте її в запиті.
- Ідентичність є **лише локальною для браузера**. Вона не синхронізується з іншими пристроями і
не є частиною файлу конфігурації gateway.
- Очищення даних сайту або зміна браузера скидає ідентичність до порожнього значення; Control UI
не намагається відновити її зі стану сервера.
- Нічого, що стосується персональної ідентичності, не зберігається на стороні сервера, окрім
звичайних метаданих авторства в transcript для повідомлень, які ви справді надсилаєте.
## Кінцева точка конфігурації середовища виконання
Control UI отримує свої налаштування середовища виконання з
`/__openclaw/control-ui-config.json`. Ця кінцева точка захищена тією самою
автентифікацією gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть
її отримати, а успішне отримання вимагає або вже дійсного
токена/пароля gateway, ідентичності Tailscale Serve або ідентичності trusted-proxy. Це
запобігає витоку прапорців функцій і метаданих кінцевих точок Control UI до
неавтентифікованих сканерів на спільних хостах.
## Підтримка мов
Control UI може локалізувати себе під час першого завантаження на основі локалі браузера.
Щоб перевизначити це пізніше, відкрийте **Overview -> Gateway Access -> Language**. Засіб вибору
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`)
- Потокове передавання викликів tool + картки живого виводу tool у Chat (події агента)
- Канали: вбудовані плюс bundled/external plugin-канали, статус, вхід через QR і конфігурація для кожного каналу (`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`)
- Транслювати виклики інструментів + картки live-виводу інструментів у Chat (події агента)
- Канали: статус вбудованих каналів плюс bundled/external Plugin channels, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`)
- Instances: список присутності + оновлення (`system-presence`)
- Sessions: список + перевизначення model/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`)
- Dreams: статус dreaming, перемикач увімкнення/вимкнення та читання Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`)
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API key (`skills.*`)
- Nodes: список + caps (`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.schema` / `config.schema.lookup`,
включно з полями `title` / `description`, відповідними UI-підказками, зведеннями
безпосередніх дочірніх елементів, metadata документації на вузлах nested object/wildcard/array/composition,
а також схемами plugin + channel, коли вони доступні); редактор Raw JSON
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`)
- Node: список + caps (`node.list`)
- Погодження exec: редагування allowlist gateway або node + ask policy для `exec host=gateway/node` (`exec.approvals.*`)
- Config: перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`)
- Config: застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії
- Записи config включають захист base-hash для запобігання перезапису паралельних змін
- Записи config (`config.set`/`config.apply`/`config.patch`) також виконують передстартову перевірку активного розв’язання SecretRef для ref у надісланому payload конфігурації; активні надіслані ref, які не вдалося розв’язати, відхиляються до запису
- Schema config + рендеринг форм (`config.schema` / `config.schema.lookup`,
включно з полями `title` / `description`, відповідними UI-підказками, підсумками
безпосередніх дочірніх елементів, метаданими docs для nested object/wildcard/array/composition вузлів,
а також schema плагінів і каналів, коли доступні); Raw JSON editor
доступний лише тоді, коли snapshot має безпечний raw round-trip
- Якщо snapshot не може безпечно пройти round-trip у raw text, Control UI примусово використовує режим Form і вимикає режим Raw для цього snapshot
- Структуровані значення об’єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню object-to-string
- Налагодження: snapshots status/health/models + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`)
- Журнали: live tail журналів файлів gateway з фільтром/експортом (`logs.tail`)
- Оновлення: запуск оновлення package/git + перезапуск (`update.run`) зі звітом про перезапуск
- Якщо snapshot не може безпечно пройти raw round-trip, Control UI примусово використовує режим Form і вимикає режим Raw для цього snapshot
- Кнопка Raw JSON editor "Reset to saved" зберігає raw-authored форму (форматування, коментарі, макет `$include`) замість повторного рендерингу згорнутого snapshot, тож зовнішні редагування зберігаються під час скидання, коли snapshot може безпечно пройти round-trip
- Структуровані значення об’єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення object-to-string
- Debug: snapshots status/health/models + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`)
- Logs: live tail файлових журналів gateway із фільтрацією/експортом (`logs.tail`)
- Оновлення: запуск package/git update + restart (`update.run`) зі звітом про перезапуск
Примітки до панелі завдань Cron:
Примітки щодо панелі завдань Cron:
- Для ізольованих завдань типова доставка — оголошення зведення. Ви можете перемкнути на none, якщо хочете лише внутрішні запуски.
- Для ізольованих завдань доставка типово налаштована на announce summary. Ви можете переключити її на none, якщо хочете лише внутрішні запуски.
- Поля channel/target з’являються, коли вибрано announce.
- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, заданим як коректний HTTP(S) Webhook URL.
- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, встановленим на дійсну URL-адресу Webhook HTTP(S).
- Для завдань main-session доступні режими доставки webhook і none.
- Розширені елементи редагування включають delete-after-run, очищення перевизначення агента, точні/stagger-варіанти Cron,
перевизначення model/thinking агента та best-effort перемикачі доставки.
- Валідація форми є вбудованою з помилками на рівні полів; некоректні значення вимикають кнопку збереження, доки їх не буде виправлено.
- Задайте `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його пропущено, webhook надсилається без заголовка auth.
- Застарілий fallback: збережені legacy-завдання з `notify: true` все ще можуть використовувати `cron.webhook`, доки їх не буде мігровано.
- Розширені елементи редагування включають delete-after-run, очищення перевизначення агента, параметри cron exact/stagger,
перевизначення model/thinking агента та перемикачі доставки best-effort.
- Валідація форми виконується вбудовано з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не буде виправлено.
- Установіть `cron.webhookToken`, щоб надсилати окремий bearer token; якщо не вказано, Webhook надсилається без заголовка автентифікації.
- Застарілий fallback: збережені legacy jobs із `notify: true` усе ще можуть використовувати `cron.webhook`, доки їх не буде мігровано.
## Поведінка чату
## Поведінка Chat
- `chat.send` є **неблокувальним**: він одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`.
- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання і `{ status: "ok" }` після завершення.
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи transcript надто великі, Gateway може обрізати довгі текстові поля, пропускати великі блоки metadata та замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
- `chat.history` також прибирає display-only вбудовані теги директив із видимого тексту асистента (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML payload викликів tool (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками викликів tool), а також витеклі ASCII/full-width токени керування моделлю, і пропускає записи асистента, чий увесь видимий текст — це лише точний тихий токен `NO_REPLY` / `no_reply`.
- `chat.inject` додає примітку асистента до transcript сесії та транслює подію `chat` для оновлень лише в UI (без запуску агента, без доставки в канал).
- Вибір model і thinking у заголовку чату одразу patch-ить активну сесію через `sessions.patch`; це постійні перевизначення сесії, а не параметри надсилання лише на один хід.
- `chat.send` є **неблокувальним**: він одразу підтверджує `{ runId, status: "started" }`, а відповідь транслюється через події `chat`.
- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення.
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи transcript занадто великі, Gateway може обрізати довгі текстові поля, опускати важкі блоки метаданих і замінювати надто великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
- `chat.history` також прибирає з видимого тексту помічника inline-теги директив лише для відображення (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML payload викликів інструментів (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками викликів інструментів), а також leaked ASCII/full-width контрольні токени моделі, і опускає записи помічника, весь видимий текст яких складається лише з точного silent token `NO_REPLY` / `no_reply`.
- `chat.inject` додає примітку помічника до transcript сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставки каналом).
- Засоби вибору model і thinking в заголовку chat негайно змінюють активну сесію через `sessions.patch`; це постійні перевизначення сесії, а не параметри надсилання лише на один хід.
- Зупинка:
- Натисніть **Stop** (викликає `chat.abort`)
- Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) для позасмугового переривання
- Введіть `/stop` (або окремі фрази переривання на кшталт `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб виконати позасмугове переривання
- `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків цієї сесії
- Збереження часткового виводу після переривання:
- Коли запуск переривається, частковий текст асистента все ще може відображатися в UI
- Gateway зберігає частковий текст асистента після переривання в transcript history, якщо існує буферизований вивід
- Збережені записи містять metadata переривання, щоб споживачі transcript могли відрізняти часткові записи після переривання від звичайного завершеного виводу
- Збереження часткових результатів після переривання:
- Коли запуск переривається, частковий текст помічника все одно може показуватися в UI
- Gateway зберігає перерваний частковий текст помічника в transcript history, коли існує буферизований вивід
- Збережені записи містять метадані переривання, щоб споживачі transcript могли відрізняти часткові результати переривання від звичайного завершеного виводу
## Hosted embeds
Повідомлення асистента можуть вбудовано рендерити hosted web content за допомогою shortcode `[embed ...]`.
Повідомлення помічника можуть вбудовано відображати hosted web content за допомогою shortcode `[embed ...]`.
Політика sandbox iframe керується через
`gateway.controlUi.embedSandbox`:
- `strict`: вимикає виконання скриптів усередині hosted embeds
- `scripts`: дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це
типове значення, якого зазвичай достатньо для самодостатніх браузерних ігор/віджетів
- `trusted`: додає `allow-same-origin` поверх `allow-scripts` для same-site
документів, яким навмисно потрібні ширші привілеї
- `scripts`: дозволяє інтерактивні embeds, зберігаючи ізоляцію походження; це
значення за замовчуванням, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів
- `trusted`: додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту,
яким навмисно потрібні сильніші привілеї
Приклад:
@ -174,19 +200,19 @@ Control UI може локалізувати себе під час першог
}
```
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна same-origin
поведінка. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є
безпечнішим вибором.
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна
поведінка same-origin. Для більшості ігор та інтерактивних canvas, згенерованих агентом, `scripts` —
безпечніший вибір.
Абсолютні зовнішні `http(s)` embed URL типово залишаються заблокованими. Якщо ви
свідомо хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, задайте
Абсолютні зовнішні URL-адреси embed `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
@ -196,19 +222,20 @@ openclaw gateway --tailscale serve
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
Типово запити Serve до Control UI/WebSocket можуть проходити автентифікацію через заголовки ідентичності Tailscale
(`tailscale-user-login`), коли `gateway.auth.allowTailscale` дорівнює `true`. OpenClaw
перевіряє ідентичність, розв’язуючи адресу `x-forwarded-for` через
`tailscale whois` і зіставляючи її із заголовком, і приймає їх лише тоді, коли
запит потрапляє на loopback із заголовками `x-forwarded-*` від Tailscale. Задайте
`gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані зі спільним секретом
За замовчуванням запити 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"` або
`"password"`.
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта
та scope автентифікації серіалізуються перед записом обмеження частоти. Тому одночасні невдалі повтори
з того самого браузера можуть показати `retry later` у другому запиті замість двох звичайних невідповідностей, що змагаються паралельно.
Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості
може виконуватися недовірений local code, вимагайте автентифікацію токеном/паролем.
та області автентифікації серіалізуються перед записами обмеження швидкості. Тому одночасні невдалі повторні спроби
з того самого браузера можуть показувати `retry later` у другому запиті
замість двох звичайних невідповідностей, що змагаються паралельно.
Автентифікація Serve без токена передбачає, що хост gateway є довіреним. Якщо на цьому хості
може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
### Прив’язка до tailnet + токен
@ -220,20 +247,20 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
- `http://<tailscale-ip>:18789/` (або ваш налаштований `gateway.controlUi.basePath`)
Вставте відповідний спільний секрет у налаштування UI (він надсилається як
Вставте відповідний спільний секрет у налаштування UI (надсилається як
`connect.params.auth.token` або `connect.params.auth.password`).
## Незахищений HTTP
Якщо ви відкриваєте dashboard через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`),
браузер працює в **незахищеному контексті** і блокує WebCrypto. Типово
браузер працює в **незахищеному контексті** і блокує WebCrypto. За замовчуванням
OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
Задокументовані винятки:
- сумісність із незахищеним HTTP лише для localhost через `gateway.controlUi.allowInsecureAuth=true`
- успішна автентифікація оператора в Control UI через `gateway.auth.mode: "trusted-proxy"`
- аварійний варіант `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- успішна автентифікація operator Control UI через `gateway.auth.mode: "trusted-proxy"`
- аварійний режим `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкривайте UI локально:
@ -254,12 +281,12 @@ OpenClaw **блокує** підключення Control UI без іденти
`allowInsecureAuth` — це лише локальний перемикач сумісності:
- Він дозволяє сесіям Control UI на localhost працювати без ідентичності пристрою в
- Він дозволяє сесіям localhost Control UI продовжуватися без ідентичності пристрою в
незахищених HTTP-контекстах.
- Він не обходить перевірки pairing.
- Він не послаблює вимоги до ідентичності віддалених (не localhost) пристроїв.
- Він не обходить перевірки спарювання.
- Він не послаблює вимоги до ідентичності віддалених пристроїв (не localhost).
**Лише для аварійного використання:**
**Лише для аварійного режиму:**
```json5
{
@ -271,44 +298,44 @@ OpenClaw **блокує** підключення Control UI без іденти
}
```
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою в Control UI і є
серйозним погіршенням безпеки. Після аварійного використання швидко поверніть усе назад.
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є
серйозним зниженням рівня безпеки. Швидко скасуйте цю зміну після аварійного використання.
Примітка щодо trusted-proxy:
- успішна автентифікація trusted-proxy може допустити **operator**-сесії Control UI без
- успішна автентифікація trusted-proxy може допускати **operator** сесії Control UI без
ідентичності пристрою
- це **не** поширюється на node-role сесії Control UI
- reverse proxy на loopback того самого хоста все одно не задовольняють автентифікацію 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 з `http(s)` і protocol-relative image URL відхиляються браузером і не виконують мережевих запитів.
Control UI постачається з жорсткою політикою `img-src`: дозволені лише ресурси **same-origin** і URL `data:`. Віддалені URL `http(s)` і URL з відносним до протоколу записом відхиляються браузером і не ініціюють мережевих запитів.
Що це означає на практиці:
- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), як і раніше відображаються.
- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для payload у межах протоколу).
- Віддалені URL аватарів, які надходять із metadata каналу, прибираються в допоміжних функціях аватарів Control UI і замінюються вбудованими logo/badge, тож скомпрометований або зловмисний канал не може примусово змусити браузер оператора завантажувати довільні віддалені зображення.
- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), як і раніше відображаються.
- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для payload усередині протоколу).
- Віддалені URL аватарів, які надходять із метаданих каналів, прибираються в допоміжних функціях аватарів Control UI і замінюються вбудованим логотипом/бейджем, тож скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується.
Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена і не налаштовується.
## Автентифікація маршруту аватарів
## Автентифікація маршруту аватара
Коли налаштовано автентифікацію gateway, endpoint аватарів у Control UI потребує того самого токена gateway, що й решта API:
Коли налаштовано автентифікацію gateway, кінцева точка аватара в Control UI вимагає той самий токен gateway, що й решта API:
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим клієнтам. `GET /avatar/<agentId>?meta=1` повертає metadata аватара за тим самим правилом.
- Неавтентифіковані запити до обох маршрутів відхиляються (узгоджено із сусіднім маршрутом assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені.
- Сам Control UI передає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані blob URL, тож зображення все одно відображається в dashboard.
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
- Неавтентифіковані запити до обох маршрутів відхиляються (узгоджено із сусіднім маршрутом assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які в іншому випадку захищені.
- Сам Control UI передає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані blob URL, тому зображення все одно відображається в dashboard.
Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватарів також стане неавтентифікованим, відповідно до решти gateway.
Якщо ви вимкнете автентифікацію gateway (не рекомендується на спільних хостах), маршрут аватара також стане неавтентифікованим, узгоджено з рештою gateway.
## Збірка UI
Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх командою:
Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
```bash
pnpm ui:build
@ -320,7 +347,7 @@ pnpm ui:build
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```
Для локальної розробки (окремий dev server):
Для локальної розробки (окремий dev-сервер):
```bash
pnpm ui:dev
@ -328,13 +355,13 @@ pnpm ui:dev
Потім спрямуйте UI на URL Gateway WS (наприклад, `ws://127.0.0.1:18789`).
## Налагодження/тестування: dev server + віддалений Gateway
## Налагодження/тестування: dev-сервер + віддалений Gateway
Control UI — це статичні файли; target WebSocket налаштовується і може
відрізнятися від HTTP origin. Це зручно, коли ви хочете використовувати dev server Vite
локально, а Gateway працює деінде.
Control UI — це статичні файли; ціль WebSocket налаштовується і може
відрізнятися від походження HTTP. Це зручно, коли ви хочете мати локальний
dev-сервер Vite, а Gateway працює деінде.
1. Запустіть dev server UI: `pnpm ui:dev`
1. Запустіть dev-сервер UI: `pnpm ui:dev`
2. Відкрийте URL на кшталт:
```text
@ -349,20 +376,20 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
Примітки:
- `gatewayUrl` зберігається в localStorage після завантаження і прибирається з URL.
- `token` слід передавати через фрагмент URL (`#token=...`), коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку в журналах запитів і Referer. Застарілі query-параметри `?token=` усе ще одноразово імпортуються для сумісності, але лише як fallback, і негайно прибираються після bootstrap.
- `gatewayUrl` зберігається в localStorage після завантаження і видаляється з URL.
- `token` слід, за можливості, передавати через фрагмент URL (`#token=...`). Фрагменти не надсилаються на сервер, що запобігає витоку в журналах запитів і через Referer. Застарілі параметри запиту `?token=` усе ще одноразово імпортуються для сумісності, але лише як запасний варіант, і видаляються одразу після bootstrap.
- `password` зберігається лише в пам’яті.
- Коли задано `gatewayUrl`, UI не повертається до облікових даних із конфігурації чи середовища.
Передайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
- Коли задано `gatewayUrl`, UI не використовує як запасний варіант облікові дані з config або середовища.
Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
- Використовуйте `wss://`, коли Gateway стоїть за TLS (Tailscale Serve, HTTPS proxy тощо).
- `gatewayUrl` приймається лише у вікні верхнього рівня (не у вбудованому), щоб запобігти clickjacking.
- Для розгортань Control UI не на loopback потрібно явно задавати `gateway.controlUi.allowedOrigins`
(повні origin). Це також стосується віддалених dev-налаштувань.
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім як у жорстко контрольованому
локальному тестуванні. Це означає дозволити будь-який browser origin, а не «підібрати будь-який host, який я
- Розгортання Control UI не на loopback мають явно задавати `gateway.controlUi.allowedOrigins`
(повні origins). Це включає віддалені dev-налаштування.
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім як для жорстко контрольованого
локального тестування. Це означає дозвіл будь-якому browser origin, а не «підставити будь-який хост, який я
використовую».
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає
режим fallback origin за заголовком Host, але це небезпечний режим безпеки.
режим запасного походження за заголовком Host, але це небезпечний режим безпеки.
Приклад:
@ -376,11 +403,11 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
}
```
Докладніше про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
Докладніше про налаштування віддаленого доступу: [Remote access](/uk/gateway/remote).
## Пов’язане
## Пов’язано
- [Dashboard](/uk/web/dashboard) — dashboard gateway
- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
- [WebChat](/uk/web/webchat) — браузерний інтерфейс chat
- [TUI](/uk/web/tui) — terminal user interface
- [Health Checks](/uk/gateway/health) — моніторинг стану gateway