diff --git a/docs/uk/channels/broadcast-groups.md b/docs/uk/channels/broadcast-groups.md
index fd4c923f4..5c0620cfe 100644
--- a/docs/uk/channels/broadcast-groups.md
+++ b/docs/uk/channels/broadcast-groups.md
@@ -2,80 +2,82 @@
read_when:
- Налаштування груп розсилки
- Налагодження відповідей кількох агентів у WhatsApp
+sidebarTitle: Broadcast groups
status: experimental
summary: Надішліть повідомлення WhatsApp кільком агентам
title: Групи розсилки
x-i18n:
- generated_at: "2026-04-24T03:41:29Z"
+ generated_at: "2026-04-26T09:06:01Z"
model: gpt-5.4
provider: openai
- source_hash: d1f3991348570170855158e82089fa073ca62b98855f443d4a227829d7c945ee
+ source_hash: b7b36710d9cc3eb4e2b8ba3d57031bd020aedbb6a502b400ec02a835a320d609
source_path: channels/broadcast-groups.md
workflow: 15
---
-**Статус:** Експериментально
-**Версія:** Додано в 2026.1.9
+
+**Статус:** Експериментально. Додано в 2026.1.9.
+
## Огляд
-Групи розсилки дають змогу кільком агентам одночасно обробляти одне й те саме повідомлення та відповідати на нього. Це дозволяє створювати спеціалізовані команди агентів, які працюють разом в одній групі WhatsApp або DM — і все це з використанням одного номера телефону.
+Групи розсилки дають змогу кільком агентам одночасно обробляти те саме повідомлення та відповідати на нього. Це дає змогу створювати спеціалізовані команди агентів, які працюють разом в одній групі WhatsApp або DM — і все це з використанням одного номера телефону.
-Поточне охоплення: **лише WhatsApp** (вебканал).
+Поточна сфера дії: **лише WhatsApp** (веб-канал).
-Групи розсилки оцінюються після allowlist каналу та правил активації груп. У групах WhatsApp це означає, що розсилка спрацьовує тоді, коли OpenClaw зазвичай відповів би (наприклад, на згадку, залежно від ваших налаштувань групи).
+Групи розсилки оцінюються після allowlist каналів і правил активації груп. У групах WhatsApp це означає, що розсилки відбуваються тоді, коли OpenClaw зазвичай відповідав би (наприклад, при згадуванні, залежно від ваших налаштувань групи).
## Варіанти використання
-### 1. Спеціалізовані команди агентів
+
+
+ Розгорніть кількох агентів з атомарними, вузько сфокусованими обов’язками:
-Розгорніть кількох агентів з атомарними, вузькоспрямованими обов’язками:
+ ```
+ Group: "Development Team"
+ Agents:
+ - CodeReviewer (reviews code snippets)
+ - DocumentationBot (generates docs)
+ - SecurityAuditor (checks for vulnerabilities)
+ - TestGenerator (suggests test cases)
+ ```
-```
-Group: "Development Team"
-Agents:
- - CodeReviewer (reviews code snippets)
- - DocumentationBot (generates docs)
- - SecurityAuditor (checks for vulnerabilities)
- - TestGenerator (suggests test cases)
-```
+ Кожен агент обробляє те саме повідомлення та надає свою спеціалізовану перспективу.
-Кожен агент обробляє те саме повідомлення й надає свою спеціалізовану перспективу.
-
-### 2. Багатомовна підтримка
-
-```
-Group: "International Support"
-Agents:
- - Agent_EN (responds in English)
- - Agent_DE (responds in German)
- - Agent_ES (responds in Spanish)
-```
-
-### 3. Робочі процеси забезпечення якості
-
-```
-Group: "Customer Support"
-Agents:
- - SupportAgent (provides answer)
- - QAAgent (reviews quality, only responds if issues found)
-```
-
-### 4. Автоматизація завдань
-
-```
-Group: "Project Management"
-Agents:
- - TaskTracker (updates task database)
- - TimeLogger (logs time spent)
- - ReportGenerator (creates summaries)
-```
+
+
+ ```
+ Group: "International Support"
+ Agents:
+ - Agent_EN (responds in English)
+ - Agent_DE (responds in German)
+ - Agent_ES (responds in Spanish)
+ ```
+
+
+ ```
+ Group: "Customer Support"
+ Agents:
+ - SupportAgent (provides answer)
+ - QAAgent (reviews quality, only responds if issues found)
+ ```
+
+
+ ```
+ Group: "Project Management"
+ Agents:
+ - TaskTracker (updates task database)
+ - TimeLogger (logs time spent)
+ - ReportGenerator (creates summaries)
+ ```
+
+
## Конфігурація
### Базове налаштування
-Додайте секцію верхнього рівня `broadcast` (поруч із `bindings`). Ключі — це peer ID WhatsApp:
+Додайте секцію верхнього рівня `broadcast` (поруч із `bindings`). Ключі — це peer id WhatsApp:
- групові чати: JID групи (наприклад, `120363403215116621@g.us`)
- DM: номер телефону у форматі E.164 (наприклад, `+15551234567`)
@@ -94,31 +96,34 @@ Agents:
Керуйте тим, як агенти обробляють повідомлення:
-#### Parallel (за замовчуванням)
+
+
+ Усі агенти обробляють одночасно:
-Усі агенти обробляють повідомлення одночасно:
+ ```json
+ {
+ "broadcast": {
+ "strategy": "parallel",
+ "120363403215116621@g.us": ["alfred", "baerbel"]
+ }
+ }
+ ```
-```json
-{
- "broadcast": {
- "strategy": "parallel",
- "120363403215116621@g.us": ["alfred", "baerbel"]
- }
-}
-```
+
+
+ Агенти обробляють по черзі (кожен наступний чекає завершення попереднього):
-#### Послідовно
+ ```json
+ {
+ "broadcast": {
+ "strategy": "sequential",
+ "120363403215116621@g.us": ["alfred", "baerbel"]
+ }
+ }
+ ```
-Агенти обробляють повідомлення по черзі (один чекає, поки завершить попередній):
-
-```json
-{
- "broadcast": {
- "strategy": "sequential",
- "120363403215116621@g.us": ["alfred", "baerbel"]
- }
-}
-```
+
+
### Повний приклад
@@ -159,16 +164,26 @@ Agents:
### Потік повідомлення
-1. **Вхідне повідомлення** надходить у групу WhatsApp
-2. **Перевірка broadcast**: система перевіряє, чи є peer ID у `broadcast`
-3. **Якщо є у списку broadcast**:
- - Усі зазначені агенти обробляють повідомлення
- - Кожен агент має власний ключ сесії та ізольований контекст
- - Агенти обробляють повідомлення паралельно (за замовчуванням) або послідовно
-4. **Якщо немає у списку broadcast**:
- - Застосовується звичайна маршрутизація (перша binding, що збіглася)
+
+
+ Надходить повідомлення з групи WhatsApp або DM.
+
+
+ Система перевіряє, чи є peer ID у `broadcast`.
+
+
+ - Усі перелічені агенти обробляють повідомлення.
+ - Кожен агент має власний ключ сесії та ізольований контекст.
+ - Агенти обробляють паралельно (типово) або послідовно.
+
+
+ Застосовується звичайна маршрутизація (перше binding, що збіглося).
+
+
-Примітка: групи розсилки не обходять allowlist каналу чи правила активації групи (згадки/команди тощо). Вони змінюють лише _які агенти запускаються_, коли повідомлення відповідає умовам для обробки.
+
+Групи розсилки не обходять allowlist каналів або правила активації груп (згадування/команди тощо). Вони лише змінюють _які агенти запускаються_, коли повідомлення відповідає умовам для обробки.
+
### Ізоляція сесій
@@ -178,108 +193,111 @@ Agents:
- **Історію розмови** (агент не бачить повідомлень інших агентів)
- **Робочий простір** (окремі sandbox, якщо налаштовано)
- **Доступ до інструментів** (різні списки allow/deny)
-- **Пам’ять/контекст** (окремі IDENTITY.md, SOUL.md тощо)
-- **Буфер контексту групи** (останні повідомлення групи, що використовуються для контексту) є спільним для кожного peer, тому всі агенти розсилки бачать однаковий контекст під час спрацювання
+- **Пам’ять/контекст** (окремі `IDENTITY.md`, `SOUL.md` тощо)
+- **Буфер контексту групи** (останні повідомлення групи, що використовуються як контекст) є спільним для peer, тож усі агенти розсилки бачать однаковий контекст під час спрацювання
Це дає змогу кожному агенту мати:
- Різні особистості
- Різний доступ до інструментів (наприклад, лише читання або читання-запис)
-- Різні моделі (наприклад, opus чи sonnet)
+- Різні моделі (наприклад, opus vs. sonnet)
- Різні встановлені Skills
### Приклад: ізольовані сесії
У групі `120363403215116621@g.us` з агентами `["alfred", "baerbel"]`:
-**Контекст Alfred:**
+
+
+ ```
+ Session: agent:alfred:whatsapp:group:120363403215116621@g.us
+ History: [user message, alfred's previous responses]
+ Workspace: /Users/user/openclaw-alfred/
+ Tools: read, write, exec
+ ```
+
+
+ ```
+ Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
+ History: [user message, baerbel's previous responses]
+ Workspace: /Users/user/openclaw-baerbel/
+ Tools: read only
+ ```
+
+
-```
-Session: agent:alfred:whatsapp:group:120363403215116621@g.us
-History: [user message, alfred's previous responses]
-Workspace: /Users/user/openclaw-alfred/
-Tools: read, write, exec
-```
+## Найкращі практики
-**Контекст Bärbel:**
+
+
+ Проєктуйте кожного агента з однією чіткою відповідальністю:
-```
-Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
-History: [user message, baerbel's previous responses]
-Workspace: /Users/user/openclaw-baerbel/
-Tools: read only
-```
-
-## Рекомендовані практики
-
-### 1. Робіть агентів вузькоспрямованими
-
-Проєктуйте кожного агента з однією чіткою відповідальністю:
-
-```json
-{
- "broadcast": {
- "DEV_GROUP": ["formatter", "linter", "tester"]
- }
-}
-```
-
-✅ **Добре:** кожен агент має одну задачу
-❌ **Погано:** один універсальний агент "dev-helper"
-
-### 2. Використовуйте зрозумілі назви
-
-Назва має чітко показувати, що робить агент:
-
-```json
-{
- "agents": {
- "security-scanner": { "name": "Security Scanner" },
- "code-formatter": { "name": "Code Formatter" },
- "test-generator": { "name": "Test Generator" }
- }
-}
-```
-
-### 3. Налаштовуйте різний доступ до інструментів
-
-Надавайте агентам лише ті інструменти, які їм потрібні:
-
-```json
-{
- "agents": {
- "reviewer": {
- "tools": { "allow": ["read", "exec"] } // Лише читання
- },
- "fixer": {
- "tools": { "allow": ["read", "write", "edit", "exec"] } // Читання і запис
+ ```json
+ {
+ "broadcast": {
+ "DEV_GROUP": ["formatter", "linter", "tester"]
+ }
}
- }
-}
-```
+ ```
-### 4. Відстежуйте продуктивність
+ ✅ **Добре:** кожен агент має одне завдання. ❌ **Погано:** один універсальний агент "dev-helper".
-Якщо агентів багато, враховуйте таке:
+
+
+ Має бути зрозуміло, що саме робить кожен агент:
-- Використовуйте `"strategy": "parallel"` (за замовчуванням) для швидкості
-- Обмежуйте групи розсилки до 5–10 агентів
-- Використовуйте швидші моделі для простіших агентів
+ ```json
+ {
+ "agents": {
+ "security-scanner": { "name": "Security Scanner" },
+ "code-formatter": { "name": "Code Formatter" },
+ "test-generator": { "name": "Test Generator" }
+ }
+ }
+ ```
-### 5. Коректно обробляйте збої
+
+
+ Надавайте агентам лише ті інструменти, які їм потрібні:
-Агенти завершуються з помилками незалежно один від одного. Помилка одного агента не блокує інших:
+ ```json
+ {
+ "agents": {
+ "reviewer": {
+ "tools": { "allow": ["read", "exec"] } // Лише читання
+ },
+ "fixer": {
+ "tools": { "allow": ["read", "write", "edit", "exec"] } // Читання-запис
+ }
+ }
+ }
+ ```
-```
-Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
-Result: Agent A and C respond, Agent B logs error
-```
+
+
+ Якщо агентів багато, врахуйте таке:
+
+ - Використовуйте `"strategy": "parallel"` (типово) для швидкості
+ - Обмежуйте групи розсилки до 5–10 агентів
+ - Використовуйте швидші моделі для простіших агентів
+
+
+
+ Агенти дають збої незалежно один від одного. Помилка одного агента не блокує інших:
+
+ ```
+ Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
+ Result: Agent A and C respond, Agent B logs error
+ ```
+
+
+
## Сумісність
### Провайдери
-Наразі групи розсилки працюють із:
+Групи розсилки наразі працюють із:
- ✅ WhatsApp (реалізовано)
- 🚧 Telegram (заплановано)
@@ -304,106 +322,114 @@ Result: Agent A and C respond, Agent B logs error
}
```
-- `GROUP_A`: відповідає лише alfred (звичайна маршрутизація)
-- `GROUP_B`: відповідають і agent1, і agent2 (розсилка)
+- `GROUP_A`: відповідає лише alfred (звичайна маршрутизація).
+- `GROUP_B`: відповідають agent1 І agent2 (розсилка).
-**Пріоритет:** `broadcast` має вищий пріоритет за `bindings`.
+
+**Пріоритет:** `broadcast` має пріоритет над `bindings`.
+
## Усунення неполадок
-### Агенти не відповідають
+
+
+ **Перевірте:**
-**Перевірте:**
+ 1. ID агентів існують у `agents.list`.
+ 2. Формат peer ID правильний (наприклад, `120363403215116621@g.us`).
+ 3. Агенти не перебувають у списках deny.
-1. Ідентифікатори агентів існують у `agents.list`
-2. Формат peer ID правильний (наприклад, `120363403215116621@g.us`)
-3. Агенти не перебувають у списках deny
+ **Налагодження:**
-**Налагодження:**
+ ```bash
+ tail -f ~/.openclaw/logs/gateway.log | grep broadcast
+ ```
-```bash
-tail -f ~/.openclaw/logs/gateway.log | grep broadcast
-```
+
+
+ **Причина:** peer ID може бути у `bindings`, але не у `broadcast`.
-### Відповідає лише один агент
+ **Виправлення:** додайте його до конфігурації broadcast або видаліть із bindings.
-**Причина:** peer ID може бути в `bindings`, але не в `broadcast`.
+
+
+ Якщо повільно при великій кількості агентів:
-**Рішення:** додайте його до конфігурації broadcast або видаліть із bindings.
+ - Зменште кількість агентів на групу.
+ - Використовуйте легші моделі (sonnet замість opus).
+ - Перевірте час запуску sandbox.
-### Проблеми з продуктивністю
-
-**Якщо повільно при великій кількості агентів:**
-
-- Зменште кількість агентів у групі
-- Використовуйте легші моделі (sonnet замість opus)
-- Перевірте час запуску sandbox
+
+
## Приклади
-### Приклад 1: команда для перевірки коду
-
-```json
-{
- "broadcast": {
- "strategy": "parallel",
- "120363403215116621@g.us": [
- "code-formatter",
- "security-scanner",
- "test-coverage",
- "docs-checker"
- ]
- },
- "agents": {
- "list": [
- {
- "id": "code-formatter",
- "workspace": "~/agents/formatter",
- "tools": { "allow": ["read", "write"] }
+
+
+ ```json
+ {
+ "broadcast": {
+ "strategy": "parallel",
+ "120363403215116621@g.us": [
+ "code-formatter",
+ "security-scanner",
+ "test-coverage",
+ "docs-checker"
+ ]
},
- {
- "id": "security-scanner",
- "workspace": "~/agents/security",
- "tools": { "allow": ["read", "exec"] }
+ "agents": {
+ "list": [
+ {
+ "id": "code-formatter",
+ "workspace": "~/agents/formatter",
+ "tools": { "allow": ["read", "write"] }
+ },
+ {
+ "id": "security-scanner",
+ "workspace": "~/agents/security",
+ "tools": { "allow": ["read", "exec"] }
+ },
+ {
+ "id": "test-coverage",
+ "workspace": "~/agents/testing",
+ "tools": { "allow": ["read", "exec"] }
+ },
+ { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
+ ]
+ }
+ }
+ ```
+
+ **Користувач надсилає:** фрагмент коду.
+
+ **Відповіді:**
+
+ - code-formatter: "Виправлено відступи та додано підказки типів"
+ - security-scanner: "⚠️ Уразливість до SQL-ін’єкції в рядку 12"
+ - test-coverage: "Покриття становить 45%, бракує тестів для випадків помилок"
+ - docs-checker: "Бракує docstring для функції `process_data`"
+
+
+
+ ```json
+ {
+ "broadcast": {
+ "strategy": "sequential",
+ "+15555550123": ["detect-language", "translator-en", "translator-de"]
},
- {
- "id": "test-coverage",
- "workspace": "~/agents/testing",
- "tools": { "allow": ["read", "exec"] }
- },
- { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
- ]
- }
-}
-```
+ "agents": {
+ "list": [
+ { "id": "detect-language", "workspace": "~/agents/lang-detect" },
+ { "id": "translator-en", "workspace": "~/agents/translate-en" },
+ { "id": "translator-de", "workspace": "~/agents/translate-de" }
+ ]
+ }
+ }
+ ```
+
+
-**Користувач надсилає:** фрагмент коду
-**Відповіді:**
-
-- code-formatter: "Виправлено відступи та додано підказки типів"
-- security-scanner: "⚠️ Уразливість до SQL-ін’єкції в рядку 12"
-- test-coverage: "Покриття становить 45%, бракує тестів для випадків помилок"
-- docs-checker: "Відсутній docstring для функції `process_data`"
-
-### Приклад 2: багатомовна підтримка
-
-```json
-{
- "broadcast": {
- "strategy": "sequential",
- "+15555550123": ["detect-language", "translator-en", "translator-de"]
- },
- "agents": {
- "list": [
- { "id": "detect-language", "workspace": "~/agents/lang-detect" },
- { "id": "translator-en", "workspace": "~/agents/translate-en" },
- { "id": "translator-de", "workspace": "~/agents/translate-de" }
- ]
- }
-}
-```
-
-## Довідка API
+## Довідник API
### Схема конфігурації
@@ -418,32 +444,33 @@ interface OpenClawConfig {
### Поля
-- `strategy` (необов’язково): як обробляти агентів
- - `"parallel"` (за замовчуванням): усі агенти обробляють повідомлення одночасно
- - `"sequential"`: агенти обробляють повідомлення в порядку масиву
-- `[peerId]`: JID групи WhatsApp, номер E.164 або інший peer ID
- - Значення: масив ідентифікаторів агентів, які мають обробляти повідомлення
+
+ Як обробляти агентів. `parallel` запускає всіх агентів одночасно; `sequential` запускає їх у порядку масиву.
+
+
+ JID групи WhatsApp, номер E.164 або інший peer ID. Значення — це масив ID агентів, які мають обробляти повідомлення.
+
## Обмеження
-1. **Максимальна кількість агентів:** жорсткого обмеження немає, але 10+ агентів можуть працювати повільно
-2. **Спільний контекст:** агенти не бачать відповіді один одного (за задумом)
-3. **Порядок повідомлень:** паралельні відповіді можуть надходити в будь-якому порядку
-4. **Ліміти швидкості:** усі агенти враховуються в лімітах швидкості WhatsApp
+1. **Максимум агентів:** жорсткого ліміту немає, але 10+ агентів можуть працювати повільно.
+2. **Спільний контекст:** агенти не бачать відповіді один одного (за задумом).
+3. **Порядок повідомлень:** паралельні відповіді можуть надходити в будь-якому порядку.
+4. **Ліміти швидкості:** усі агенти враховуються в лімітах швидкості WhatsApp.
## Майбутні покращення
Заплановані можливості:
- [ ] Режим спільного контексту (агенти бачать відповіді один одного)
-- [ ] Координація агентів (агенти можуть сигналізувати один одному)
+- [ ] Координація агентів (агенти можуть подавати сигнали один одному)
- [ ] Динамічний вибір агентів (вибір агентів на основі вмісту повідомлення)
- [ ] Пріоритети агентів (деякі агенти відповідають раніше за інших)
## Пов’язане
+- [Маршрутизація каналів](/uk/channels/channel-routing)
- [Групи](/uk/channels/groups)
-- [Маршрутизація каналу](/uk/channels/channel-routing)
-- [Сполучення](/uk/channels/pairing)
- [Інструменти sandbox для кількох агентів](/uk/tools/multi-agent-sandbox-tools)
+- [Pairing](/uk/channels/pairing)
- [Керування сесіями](/uk/concepts/session)
diff --git a/docs/uk/channels/twitch.md b/docs/uk/channels/twitch.md
index a88a038f3..194dac533 100644
--- a/docs/uk/channels/twitch.md
+++ b/docs/uk/channels/twitch.md
@@ -1,59 +1,78 @@
---
read_when:
- Налаштування інтеграції чату Twitch для OpenClaw
-summary: Налаштування та конфігурація чат-бота Twitch
+sidebarTitle: Twitch
+summary: Конфігурація та налаштування чат-бота Twitch
title: Twitch
x-i18n:
- generated_at: "2026-04-23T20:45:15Z"
+ generated_at: "2026-04-26T09:05:58Z"
model: gpt-5.4
provider: openai
- source_hash: 82b9176deec21344a7cd22f8818277f94bc564d06c4422b149d0fc163ee92d5f
+ source_hash: 1d5f4bbad04e04cccc82fc1e2b1057acae3bf7b7684a8e7a4b1f54101731974a
source_path: channels/twitch.md
workflow: 15
---
-Підтримка чату Twitch через IRC-з’єднання. OpenClaw підключається як користувач Twitch (обліковий запис бота), щоб отримувати та надсилати повідомлення в каналах.
+Підтримка чату Twitch через підключення IRC. OpenClaw підключається як користувач Twitch (обліковий запис бота), щоб отримувати та надсилати повідомлення в каналах.
## Вбудований Plugin
-Twitch постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні
-пакетовані збірки не потребують окремого встановлення.
+
+Twitch постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайним пакетним збіркам не потрібне окреме встановлення.
+
-Якщо у вас старіша збірка або нестандартне встановлення без Twitch, установіть
-його вручну:
+Якщо ви використовуєте старішу збірку або власне встановлення без Twitch, установіть його вручну:
-Установлення через CLI (реєстр npm):
-
-```bash
-openclaw plugins install @openclaw/twitch
-```
-
-Локальний checkout (під час запуску з git-репозиторію):
-
-```bash
-openclaw plugins install ./path/to/local/twitch-plugin
-```
+
+
+ ```bash
+ openclaw plugins install @openclaw/twitch
+ ```
+
+
+ ```bash
+ openclaw plugins install ./path/to/local/twitch-plugin
+ ```
+
+
Докладніше: [Plugins](/uk/tools/plugin)
## Швидке налаштування (для початківців)
-1. Переконайтеся, що Plugin Twitch доступний.
- - Поточні пакетовані випуски OpenClaw уже містять його.
- - У старіших/нестандартних встановленнях його можна додати вручну командами вище.
-2. Створіть окремий обліковий запис Twitch для бота (або використайте наявний обліковий запис).
-3. Згенеруйте облікові дані: [Twitch Token Generator](https://twitchtokengenerator.com/)
- - Виберіть **Bot Token**
- - Переконайтеся, що вибрано області доступу `chat:read` і `chat:write`
- - Скопіюйте **Client ID** і **Access Token**
-4. Знайдіть свій ідентифікатор користувача Twitch: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
-5. Налаштуйте токен:
- - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (лише для типового облікового запису)
- - Або конфігурація: `channels.twitch.accessToken`
- - Якщо задано і те, і інше, конфігурація має пріоритет (резервний варіант env працює лише для типового облікового запису).
-6. Запустіть gateway.
+
+
+ У поточних пакетних релізах OpenClaw він уже вбудований. У старіших/власних встановленнях його можна додати вручну наведеними вище командами.
+
+
+ Створіть окремий обліковий запис Twitch для бота (або використайте наявний обліковий запис).
+
+
+ Скористайтеся [Twitch Token Generator](https://twitchtokengenerator.com/):
-**⚠️ Важливо:** Додайте керування доступом (`allowFrom` або `allowedRoles`), щоб неавторизовані користувачі не могли активувати бота. Типове значення `requireMention` — `true`.
+ - Виберіть **Bot Token**
+ - Переконайтеся, що вибрано області доступу `chat:read` і `chat:write`
+ - Скопіюйте **Client ID** і **Access Token**
+
+
+
+ Використайте [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/), щоб перетворити ім’я користувача на Twitch user ID.
+
+
+ - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (лише для облікового запису за замовчуванням)
+ - Або config: `channels.twitch.accessToken`
+
+ Якщо задано обидва варіанти, пріоритет має config (env використовується як резервне джерело лише для облікового запису за замовчуванням).
+
+
+
+ Запустіть Gateway з налаштованим каналом.
+
+
+
+
+Додайте керування доступом (`allowFrom` або `allowedRoles`), щоб запобігти запуску бота неавторизованими користувачами. Для `requireMention` типовим значенням є `true`.
+
Мінімальна конфігурація:
@@ -62,11 +81,11 @@ openclaw plugins install ./path/to/local/twitch-plugin
channels: {
twitch: {
enabled: true,
- username: "openclaw", // Bot's Twitch account
- accessToken: "oauth:abc123...", // OAuth Access Token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
- clientId: "xyz789...", // Client ID from Token Generator
- channel: "vevisk", // Which Twitch channel's chat to join (required)
- allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
+ username: "openclaw", // Обліковий запис Twitch бота
+ accessToken: "oauth:abc123...", // OAuth Access Token (або використайте змінну середовища OPENCLAW_TWITCH_ACCESS_TOKEN)
+ clientId: "xyz789...", // Client ID з Token Generator
+ channel: "vevisk", // До якого чату каналу Twitch підключатися (обов’язково)
+ allowFrom: ["123456789"], // (рекомендовано) Лише ваш Twitch user ID — отримайте його на https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
},
},
}
@@ -77,7 +96,7 @@ openclaw plugins install ./path/to/local/twitch-plugin
- Канал Twitch, яким володіє Gateway.
- Детермінована маршрутизація: відповіді завжди повертаються в Twitch.
- Кожен обліковий запис зіставляється з ізольованим ключем сесії `agent::twitch:`.
-- `username` — це обліковий запис бота (хто проходить автентифікацію), `channel` — це чат-кімната, до якої потрібно приєднатися.
+- `username` — це обліковий запис бота (який проходить автентифікацію), а `channel` — це чат-кімната, до якої треба підключитися.
## Налаштування (докладно)
@@ -89,33 +108,36 @@ openclaw plugins install ./path/to/local/twitch-plugin
- Переконайтеся, що вибрано області доступу `chat:read` і `chat:write`
- Скопіюйте **Client ID** і **Access Token**
+
Ручна реєстрація застосунку не потрібна. Термін дії токенів спливає через кілька годин.
+
### Налаштуйте бота
-**Змінна середовища (лише для типового облікового запису):**
+
+
+ ```bash
+ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
+ ```
+
+
+ ```json5
+ {
+ channels: {
+ twitch: {
+ enabled: true,
+ username: "openclaw",
+ accessToken: "oauth:abc123...",
+ clientId: "xyz789...",
+ channel: "vevisk",
+ },
+ },
+ }
+ ```
+
+
-```bash
-OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
-```
-
-**Або конфігурація:**
-
-```json5
-{
- channels: {
- twitch: {
- enabled: true,
- username: "openclaw",
- accessToken: "oauth:abc123...",
- clientId: "xyz789...",
- channel: "vevisk",
- },
- },
-}
-```
-
-Якщо задано і env, і конфігурацію, пріоритет має конфігурація.
+Якщо задано і env, і config, пріоритет має config.
### Керування доступом (рекомендовано)
@@ -123,25 +145,27 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
{
channels: {
twitch: {
- allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
+ allowFrom: ["123456789"], // (рекомендовано) Лише ваш Twitch user ID
},
},
}
```
-Надавайте перевагу `allowFrom` для жорсткого allowlist. Використовуйте `allowedRoles`, якщо хочете доступ на основі ролей.
+Для жорсткого списку дозволених користувачів надавайте перевагу `allowFrom`. Якщо потрібен доступ на основі ролей, натомість використовуйте `allowedRoles`.
**Доступні ролі:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
-**Чому ідентифікатори користувачів?** Імена користувачів можуть змінюватися, що дозволяє видавати себе за іншу особу. Ідентифікатори користувачів є постійними.
+
+**Чому саме user ID?** Імена користувачів можуть змінюватися, що відкриває можливість для видавання себе за іншу особу. User ID є постійними.
-Знайдіть свій ідентифікатор користувача Twitch: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (перетворення вашого імені користувача Twitch на ID)
+Знайдіть свій Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Перетворення імені користувача Twitch на ID)
+
## Оновлення токена (необов’язково)
-Токени з [Twitch Token Generator](https://twitchtokengenerator.com/) не можна автоматично оновлювати — згенеруйте нові після завершення строку дії.
+Токени з [Twitch Token Generator](https://twitchtokengenerator.com/) не можна автоматично оновлювати — згенеруйте їх повторно після завершення терміну дії.
-Для автоматичного оновлення токена створіть власний застосунок Twitch у [Twitch Developer Console](https://dev.twitch.tv/console) і додайте до конфігурації:
+Щоб увімкнути автоматичне оновлення токена, створіть власний застосунок Twitch у [Twitch Developer Console](https://dev.twitch.tv/console) і додайте в config:
```json5
{
@@ -154,13 +178,13 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
}
```
-Бот автоматично оновлює токени до завершення строку дії та записує події оновлення в логи.
+Бот автоматично оновлює токени до завершення їхнього терміну дії та записує події оновлення в журнали.
## Підтримка кількох облікових записів
-Використовуйте `channels.twitch.accounts` із токенами для кожного облікового запису. Див. [`gateway/configuration`](/uk/gateway/configuration) для спільного шаблону.
+Використовуйте `channels.twitch.accounts` із токенами для кожного облікового запису. Загальний шаблон див. у [Configuration](/uk/gateway/configuration).
-Приклад (один обліковий запис бота у двох каналах):
+Приклад (один обліковий запис бота в двох каналах):
```json5
{
@@ -185,141 +209,152 @@ OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
}
```
-**Примітка:** Кожному обліковому запису потрібен власний токен (один токен на канал).
+
+Кожному обліковому запису потрібен власний токен (один токен на канал).
+
## Керування доступом
-### Обмеження на основі ролей
-
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- allowedRoles: ["moderator", "vip"],
+
+
+ ```json5
+ {
+ channels: {
+ twitch: {
+ accounts: {
+ default: {
+ allowFrom: ["123456789", "987654321"],
+ },
+ },
},
},
- },
- },
-}
-```
-
-### Allowlist за User ID (найбезпечніше)
-
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- allowFrom: ["123456789", "987654321"],
+ }
+ ```
+
+
+ ```json5
+ {
+ channels: {
+ twitch: {
+ accounts: {
+ default: {
+ allowedRoles: ["moderator", "vip"],
+ },
+ },
},
},
- },
- },
-}
-```
+ }
+ ```
-### Доступ на основі ролей (альтернатива)
+ `allowFrom` — це жорсткий список дозволених користувачів. Якщо його задано, дозволено лише зазначені user ID. Якщо вам потрібен доступ на основі ролей, не задавайте `allowFrom`, а натомість налаштуйте `allowedRoles`.
-`allowFrom` — це жорсткий allowlist. Якщо його задано, дозволено лише цим ідентифікаторам користувачів.
-Якщо ви хочете доступ на основі ролей, не задавайте `allowFrom`, а натомість налаштуйте `allowedRoles`:
+
+
+ Типово `requireMention` має значення `true`. Щоб вимкнути це й відповідати на всі повідомлення:
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- allowedRoles: ["moderator"],
+ ```json5
+ {
+ channels: {
+ twitch: {
+ accounts: {
+ default: {
+ requireMention: false,
+ },
+ },
},
},
- },
- },
-}
-```
+ }
+ ```
-### Вимкнути вимогу @mention
+
+
-Типове значення `requireMention` — `true`. Щоб вимкнути її та відповідати на всі повідомлення:
+## Усунення несправностей
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- requireMention: false,
- },
- },
- },
- },
-}
-```
-
-## Усунення проблем
-
-Спочатку виконайте діагностичні команди:
+Спочатку виконайте команди діагностики:
```bash
openclaw doctor
openclaw channels status --probe
```
-### Бот не відповідає на повідомлення
+
+
+ - **Перевірте керування доступом:** Переконайтеся, що ваш user ID є в `allowFrom`, або тимчасово приберіть `allowFrom` і задайте `allowedRoles: ["all"]` для перевірки.
+ - **Перевірте, що бот перебуває в каналі:** Бот має приєднатися до каналу, заданого в `channel`.
+
+
+ "Failed to connect" або помилки автентифікації:
-**Перевірте керування доступом:** Переконайтеся, що ваш ідентифікатор користувача є в `allowFrom`, або тимчасово приберіть
-`allowFrom` і задайте `allowedRoles: ["all"]` для перевірки.
+ - Переконайтеся, що `accessToken` — це значення OAuth access token (зазвичай починається з префікса `oauth:`)
+ - Перевірте, що токен має області доступу `chat:read` і `chat:write`
+ - Якщо використовується оновлення токена, переконайтеся, що задано `clientSecret` і `refreshToken`
-**Перевірте, що бот перебуває в каналі:** Бот має приєднатися до каналу, указаного в `channel`.
+
+
+ Перевірте журнали на наявність подій оновлення:
-### Проблеми з токеном
+ ```
+ Using env token source for mybot
+ Access token refreshed for user 123456 (expires in 14400s)
+ ```
-**"Failed to connect" або помилки автентифікації:**
+ Якщо ви бачите "token refresh disabled (no refresh token)":
-- Переконайтеся, що `accessToken` — це значення токена доступу OAuth (зазвичай починається з префікса `oauth:`)
-- Переконайтеся, що токен має області доступу `chat:read` і `chat:write`
-- Якщо використовується оновлення токена, переконайтеся, що задано `clientSecret` і `refreshToken`
+ - Переконайтеся, що вказано `clientSecret`
+ - Переконайтеся, що вказано `refreshToken`
-### Оновлення токена не працює
+
+
-**Перевірте логи на події оновлення:**
+## Config
-```
-Using env token source for mybot
-Access token refreshed for user 123456 (expires in 14400s)
-```
+### Конфігурація облікового запису
-Якщо ви бачите "token refresh disabled (no refresh token)":
+
+ Ім’я користувача бота.
+
+
+ OAuth access token з `chat:read` і `chat:write`.
+
+
+ Twitch Client ID (із Token Generator або вашого застосунку).
+
+
+ Канал для підключення.
+
+
+ Увімкнути цей обліковий запис.
+
+
+ Необов’язково: для автоматичного оновлення токена.
+
+
+ Необов’язково: для автоматичного оновлення токена.
+
+
+ Термін дії токена в секундах.
+
+
+ Час отримання токена.
+
+
+ Список дозволених user ID.
+
+
+ Керування доступом на основі ролей.
+
+
+ Вимагати @mention.
+
-- Переконайтеся, що надано `clientSecret`
-- Переконайтеся, що надано `refreshToken`
-
-## Конфігурація
-
-**Конфігурація облікового запису:**
-
-- `username` - Ім’я користувача бота
-- `accessToken` - Токен доступу OAuth з `chat:read` і `chat:write`
-- `clientId` - Twitch Client ID (із Token Generator або вашого застосунку)
-- `channel` - Канал для приєднання (обов’язково)
-- `enabled` - Увімкнути цей обліковий запис (типово: `true`)
-- `clientSecret` - Необов’язково: для автоматичного оновлення токена
-- `refreshToken` - Необов’язково: для автоматичного оновлення токена
-- `expiresIn` - Строк дії токена в секундах
-- `obtainmentTimestamp` - Час отримання токена
-- `allowFrom` - allowlist ідентифікаторів користувачів
-- `allowedRoles` - Керування доступом на основі ролей (`"moderator" | "owner" | "vip" | "subscriber" | "all"`)
-- `requireMention` - Вимагати @mention (типово: `true`)
-
-**Параметри провайдера:**
+### Параметри провайдера
- `channels.twitch.enabled` - Увімкнути/вимкнути запуск каналу
- `channels.twitch.username` - Ім’я користувача бота (спрощена конфігурація одного облікового запису)
-- `channels.twitch.accessToken` - Токен доступу OAuth (спрощена конфігурація одного облікового запису)
+- `channels.twitch.accessToken` - OAuth access token (спрощена конфігурація одного облікового запису)
- `channels.twitch.clientId` - Twitch Client ID (спрощена конфігурація одного облікового запису)
-- `channels.twitch.channel` - Канал для приєднання (спрощена конфігурація одного облікового запису)
+- `channels.twitch.channel` - Канал для підключення (спрощена конфігурація одного облікового запису)
- `channels.twitch.accounts.` - Конфігурація кількох облікових записів (усі поля облікового запису вище)
Повний приклад:
@@ -377,23 +412,23 @@ Access token refreshed for user 123456 (expires in 14400s)
## Безпека та експлуатація
-- **Ставтеся до токенів як до паролів** — ніколи не комітьте токени в git
-- **Використовуйте автоматичне оновлення токена** для ботів, що працюють довго
-- **Використовуйте allowlist ідентифікаторів користувачів** замість імен користувачів для керування доступом
-- **Стежте за логами** подій оновлення токена та стану підключення
-- **Запитуйте мінімально необхідні області доступу** — лише `chat:read` і `chat:write`
-- **Якщо застрягли**: Перезапустіть gateway після підтвердження, що жоден інший процес не володіє сесією
+- **Ставтеся до токенів як до паролів** — ніколи не комітьте токени в git.
+- **Використовуйте автоматичне оновлення токенів** для довготривалих ботів.
+- **Використовуйте списки дозволених user ID** замість імен користувачів для керування доступом.
+- **Відстежуйте журнали** на предмет подій оновлення токенів і стану підключення.
+- **Надавайте токенам мінімально необхідні області доступу** — запитуйте лише `chat:read` і `chat:write`.
+- **Якщо застрягли**: перезапустіть Gateway після підтвердження, що жоден інший процес не володіє сесією.
## Обмеження
-- **500 символів** на повідомлення (автоматичне розбиття на межах слів)
-- Markdown видаляється перед розбиттям
-- Без обмеження частоти (використовуються вбудовані обмеження Twitch)
+- **500 символів** на повідомлення (автоматично розбивається на частини на межах слів).
+- Markdown видаляється перед розбиттям на частини.
+- Обмеження швидкості відсутнє (використовуються вбудовані обмеження Twitch).
-## Пов’язані матеріали
+## Пов’язане
-- [Channels Overview](/uk/channels) — усі підтримувані канали
-- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
-- [Groups](/uk/channels/groups) — поведінка групових чатів і шлюз згадок
- [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
+- [Channels Overview](/uk/channels) — усі підтримувані канали
+- [Groups](/uk/channels/groups) — поведінка групового чату та фільтрація за згадуваннями
+- [Pairing](/uk/channels/pairing) — автентифікація в DM і процес прив’язування
- [Security](/uk/gateway/security) — модель доступу та посилення безпеки
diff --git a/docs/uk/cli/gateway.md b/docs/uk/cli/gateway.md
index 64425c441..117e89ff5 100644
--- a/docs/uk/cli/gateway.md
+++ b/docs/uk/cli/gateway.md
@@ -1,30 +1,33 @@
---
read_when:
- - Запуск Gateway з CLI (розробка або сервери)
+ - Запуск Gateway із CLI (розробка або сервери)
- Налагодження автентифікації Gateway, режимів прив’язки та з’єднання
- - Виявлення шлюзів через Bonjour (локально + wide-area DNS-SD)
-summary: OpenClaw Gateway CLI (`openclaw gateway`) — запуск, запит і виявлення шлюзів
+ - Виявлення Gateway через Bonjour (локально + DNS-SD широкої області)
+sidebarTitle: Gateway
+summary: OpenClaw Gateway CLI (`openclaw gateway`) — запуск, запити та виявлення Gateway
title: Gateway
x-i18n:
- generated_at: "2026-04-26T04:24:25Z"
+ generated_at: "2026-04-26T09:06:00Z"
model: gpt-5.4
provider: openai
- source_hash: 9e5dcac41c065b321cfbb674e4341f593853b777d48a28a3fb20f85ac0ef9666
+ source_hash: c8cdca95676f0b098e2dd79ff4245a32eaae82711ed6c2b7e39522331872cfd9
source_path: cli/gateway.md
workflow: 15
---
-# Gateway CLI
+Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці доступні через `openclaw gateway …`.
-Gateway — це сервер WebSocket OpenClaw (канали, вузли, сесії, хуки).
-
-Підкоманди на цій сторінці доступні через `openclaw gateway …`.
-
-Пов’язана документація:
-
-- [/gateway/bonjour](/uk/gateway/bonjour)
-- [/gateway/discovery](/uk/gateway/discovery)
-- [/gateway/configuration](/uk/gateway/configuration)
+
+
+ Налаштування локального mDNS + DNS-SD широкої області.
+
+
+ Як OpenClaw рекламує та знаходить Gateway.
+
+
+ Ключі конфігурації Gateway верхнього рівня.
+
+
## Запуск Gateway
@@ -34,67 +37,111 @@ Gateway — це сервер WebSocket OpenClaw (канали, вузли, се
openclaw gateway
```
-Псевдонім для запуску у foreground:
+Псевдонім для запуску у передньому плані:
```bash
openclaw gateway run
```
-Примітки:
-
-- За замовчуванням Gateway відмовляється запускатися, якщо в `~/.openclaw/openclaw.json` не встановлено `gateway.mode=local`. Використовуйте `--allow-unconfigured` для ad-hoc/dev запусків.
-- Очікується, що `openclaw onboard --mode local` і `openclaw setup` записують `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією й виправте її, а не припускайте неявно локальний режим.
-- Якщо файл існує, а `gateway.mode` відсутній, Gateway розцінює це як підозріле пошкодження конфігурації й відмовляється «припускати локальний режим» за вас.
-- Прив’язка поза loopback без автентифікації блокується (захисне обмеження).
-- `SIGUSR1` запускає перезапуск у межах процесу за наявності дозволу (`commands.restart` увімкнено за замовчуванням; установіть `commands.restart: false`, щоб заблокувати ручний перезапуск, водночас інструменти gateway tool/config apply/update залишаться дозволеними).
-- Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жоден нестандартний стан термінала. Якщо ви обгортаєте CLI у TUI або raw-mode ввід, відновіть термінал перед виходом.
+
+
+ - За замовчуванням 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-режимі, відновіть термінал перед виходом.
+
+
### Параметри
-- `--port `: порт WebSocket (значення за замовчуванням береться з config/env; зазвичай `18789`).
-- `--bind `: режим прив’язки слухача.
-- `--auth `: перевизначення режиму автентифікації.
-- `--token `: перевизначення токена (також встановлює `OPENCLAW_GATEWAY_TOKEN` для процесу).
-- `--password `: перевизначення пароля. Попередження: паролі, передані напряму, можуть бути видимі в локальних списках процесів.
-- `--password-file `: прочитати пароль gateway з файлу.
-- `--tailscale `: відкрити Gateway через Tailscale.
-- `--tailscale-reset-on-exit`: скинути конфігурацію Tailscale serve/funnel під час завершення роботи.
-- `--allow-unconfigured`: дозволити запуск gateway без `gateway.mode=local` у конфігурації. Це обходить захисну перевірку запуску лише для ad-hoc/dev bootstrap; цей параметр не записує і не виправляє файл конфігурації.
-- `--dev`: створити dev-конфігурацію + workspace, якщо їх немає (пропускає BOOTSTRAP.md).
-- `--reset`: скинути dev-конфігурацію + облікові дані + сесії + workspace (потрібен `--dev`).
-- `--force`: завершити будь-який наявний listener на вибраному порту перед запуском.
-- `--verbose`: докладні логи.
-- `--cli-backend-logs`: показувати в консолі лише backend-логи CLI (і ввімкнути stdout/stderr).
-- `--ws-log `: стиль логів websocket (за замовчуванням `auto`).
-- `--compact`: псевдонім для `--ws-log compact`.
-- `--raw-stream`: логувати сирі події model stream у jsonl.
-- `--raw-stream-path `: шлях до jsonl для raw stream.
+
+ Порт WebSocket (типове значення надходить із config/env; зазвичай `18789`).
+
+
+ Режим прив’язки слухача.
+
+
+ Перевизначення режиму автентифікації.
+
+
+ Перевизначення токена (також встановлює `OPENCLAW_GATEWAY_TOKEN` для процесу).
+
+
+ Перевизначення пароля.
+
+
+ Зчитати пароль gateway із файла.
+
+
+ Відкрити Gateway через Tailscale.
+
+
+ Скинути конфігурацію Tailscale serve/funnel під час завершення роботи.
+
+
+ Дозволити запуск gateway без `gateway.mode=local` у конфігурації. Обходить захист під час запуску лише для разового/розробницького bootstrap; не записує і не виправляє файл конфігурації.
+
+
+ Створити конфігурацію розробки + робочий простір, якщо їх немає (пропускає BOOTSTRAP.md).
+
+
+ Скинути конфігурацію розробки + облікові дані + сесії + робочий простір (потребує `--dev`).
+
+
+ Завершити будь-який наявний слухач на вибраному порту перед запуском.
+
+
+ Докладні журнали.
+
+
+ Показувати в консолі лише журнали бекенда CLI (і вмикати stdout/stderr).
+
+
+ Стиль журналу WebSocket.
+
+
+ Псевдонім для `--ws-log compact`.
+
+
+ Журналювати сирі події потоку моделі в jsonl.
+
+
+ Шлях до jsonl для сирого потоку.
+
-Профілювання запуску:
+
+Вбудований `--password` може бути видимим у локальних списках процесів. Надавайте перевагу `--password-file`, env або `gateway.auth.password` на основі SecretRef.
+
-- Установіть `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
Усі команди запиту використовують WebSocket RPC.
-Режими виводу:
+
+
+ - За замовчуванням: зручний для читання людиною формат (кольоровий у TTY).
+ - `--json`: JSON для машинного читання (без стилізації/спінера).
+ - `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігши зручне для людини компонування.
+
+
+ - `--url `: URL WebSocket Gateway.
+ - `--token `: токен Gateway.
+ - `--password `: пароль Gateway.
+ - `--timeout `: тайм-аут/бюджет часу (залежить від команди).
+ - `--expect-final`: чекати на «final» відповідь (виклики агента).
+
+
-- За замовчуванням: зручний для читання людиною формат (кольоровий у TTY).
-- `--json`: JSON для машинної обробки (без стилізації/spinner).
-- `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігши формат для людини.
-
-Спільні параметри (де підтримуються):
-
-- `--url `: URL WebSocket Gateway.
-- `--token `: токен Gateway.
-- `--password `: пароль Gateway.
-- `--timeout `: timeout/бюджет часу (залежить від команди).
-- `--expect-final`: чекати на «final» відповідь (виклики агента).
-
-Примітка: коли ви встановлюєте `--url`, CLI не використовує як запасний варіант облікові дані з конфігурації чи середовища.
-Передайте `--token` або `--password` явно. Відсутність явно заданих облікових даних є помилкою.
+
+Коли ви встановлюєте `--url`, CLI не використовує як запасний варіант облікові дані з конфігурації або середовища. Явно передайте `--token` або `--password`. Відсутність явних облікових даних є помилкою.
+
### `gateway health`
@@ -102,11 +149,11 @@ openclaw gateway run
openclaw gateway health --url ws://127.0.0.1:18789
```
-HTTP-ендпойнт `/healthz` — це перевірка живучості: він повертає відповідь, щойно сервер може відповідати по HTTP. HTTP-ендпойнт `/readyz` суворіший і залишається неготовим, доки sidecar-процеси запуску, канали або налаштовані хуки ще не завершили стабілізацію.
+HTTP-ендпойнт `/healthz` — це перевірка живості: він повертає відповідь, щойно сервер може відповідати по HTTP. HTTP-ендпойнт `/readyz` суворіший і лишається недоступним, поки під час запуску ще ініціалізуються побічні служби, канали або налаштовані хуки.
### `gateway usage-cost`
-Отримати зведення usage-cost із логів сесій.
+Отримати зведення usage-cost із журналів сесій.
```bash
openclaw gateway usage-cost
@@ -114,13 +161,13 @@ openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
```
-Параметри:
-
-- `--days `: кількість днів, які слід включити (за замовчуванням `30`).
+
+ Кількість днів для включення.
+
### `gateway stability`
-Отримати нещодавній записувач діагностичної стабільності із запущеного Gateway.
+Отримати недавній діагностичний записувач стабільності із запущеного Gateway.
```bash
openclaw gateway stability
@@ -130,24 +177,35 @@ openclaw gateway stability --bundle latest --export
openclaw gateway stability --json
```
-Параметри:
+
+ Максимальна кількість недавніх подій для включення (максимум `1000`).
+
+
+ Фільтрувати за типом діагностичної події, наприклад `payload.large` або `diagnostic.memory.pressure`.
+
+
+ Включати лише події після номера послідовності діагностики.
+
+
+ Прочитати збережений пакет стабільності замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого пакета в каталозі стану, або передайте шлях до JSON пакета безпосередньо.
+
+
+ Записати zip із діагностикою підтримки, придатний для поширення, замість виведення подробиць стабільності.
+
+
+ Шлях виводу для `--export`.
+
-- `--limit `: максимальна кількість нещодавніх подій, які слід включити (за замовчуванням `25`, максимум `1000`).
-- `--type `: фільтр за типом діагностичної події, наприклад `payload.large` або `diagnostic.memory.pressure`.
-- `--since-seq `: включати лише події після номера діагностичної послідовності.
-- `--bundle [path]`: читати збережений stability bundle замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого bundle у каталозі стану або передайте шлях до JSON-файлу bundle напряму.
-- `--export`: записати shareable support diagnostics zip замість виведення подробиць stability.
-- `--output `: шлях виводу для `--export`.
-
-Примітки:
-
-- Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/Plugin і відредаговані зведення сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies, секретні значення, імена хостів або сирі id сесій. Установіть `diagnostics.enabled: false`, щоб повністю вимкнути записувач.
-- Під час фатального завершення Gateway, timeout під час вимкнення та збоїв запуску після перезапуску OpenClaw записує той самий діагностичний знімок у `~/.openclaw/logs/stability/openclaw-stability-*.json`, якщо записувач має події. Перегляньте найновіший bundle за допомогою `openclaw gateway stability --bundle latest`; параметри `--limit`, `--type` і `--since-seq` також застосовуються до виводу bundle.
+
+
+ - Записи зберігають операційні метадані: назви подій, кількість, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/плагінів і знеособлені зведення сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie, секретні значення, імена хостів або сирі ідентифікатори сесій. Установіть `diagnostics.enabled: false`, щоб повністю вимкнути записувач.
+ - У разі фатального завершення Gateway, тайм-аутів під час завершення роботи та збоїв запуску після перезапуску OpenClaw записує той самий знімок діагностики до `~/.openclaw/logs/stability/openclaw-stability-*.json`, якщо записувач має події. Перегляньте найновіший пакет за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу пакетів.
+
+
### `gateway diagnostics export`
-Записати локальний diagnostics zip, призначений для додавання до звітів про помилки.
-Про модель приватності та вміст bundle дивіться [Diagnostics Export](/uk/gateway/diagnostics).
+Записати локальний zip із діагностикою, призначений для прикріплення до звітів про помилки. Модель конфіденційності та вміст пакета див. у [Експорт діагностики](/uk/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@@ -155,25 +213,41 @@ openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
```
-Параметри:
+
+ Шлях до вихідного zip. За замовчуванням це експорт для підтримки в каталозі стану.
+
+
+ Максимальна кількість очищених рядків журналу для включення.
+
+
+ Максимальна кількість байтів журналу для перевірки.
+
+
+ URL WebSocket Gateway для знімка health.
+
+
+ Токен Gateway для знімка health.
+
+
+ Пароль Gateway для знімка health.
+
+
+ Тайм-аут знімка status/health.
+
+
+ Пропустити пошук збереженого пакета стабільності.
+
+
+ Вивести записаний шлях, розмір і маніфест у форматі JSON.
+
-- `--output `: шлях до вихідного zip. За замовчуванням — support export у каталозі стану.
-- `--log-lines `: максимальна кількість санітизованих рядків логів для включення (за замовчуванням `5000`).
-- `--log-bytes `: максимальна кількість байтів логів для аналізу (за замовчуванням `1000000`).
-- `--url `: URL WebSocket Gateway для знімка health.
-- `--token `: токен Gateway для знімка health.
-- `--password `: пароль Gateway для знімка health.
-- `--timeout `: timeout знімка status/health (за замовчуванням `3000`).
-- `--no-stability-bundle`: пропустити пошук збереженого stability bundle.
-- `--json`: вивести записаний шлях, розмір і маніфест у форматі JSON.
+Експорт містить маніфест, зведення у форматі Markdown, форму конфігурації, очищені відомості конфігурації, очищені зведення журналів, очищені знімки status/health Gateway і найновіший пакет стабільності, якщо він існує.
-Експорт містить маніфест, зведення у Markdown, форму конфігурації, санітизовані деталі конфігурації, санітизовані зведення логів, санітизовані знімки status/health Gateway і найновіший stability bundle, якщо він існує.
-
-Він призначений для поширення. Він зберігає операційні деталі, які допомагають у налагодженні, як-от безпечні поля логів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, id Plugin, id провайдерів, несекретні налаштування функцій і відредаговані операційні повідомлення логів. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookies, ідентифікатори облікових записів/повідомлень, текст prompt/instruction, імена хостів і секретні значення. Коли повідомлення у стилі LogTape виглядає як текст корисного навантаження користувача/чату/інструмента, експорт зберігає лише позначку, що повідомлення було пропущено, плюс кількість його байтів.
+Він призначений для поширення. Він зберігає операційні подробиці, які допомагають у налагодженні, наприклад безпечні поля журналів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, ідентифікатори плагінів, ідентифікатори провайдерів, несекретні налаштування функцій і знеособлені повідомлення операційних журналів. Він пропускає або знеособлює текст чату, тіла webhook, виводи інструментів, облікові дані, cookie, ідентифікатори облікових записів/повідомлень, текст prompt/інструкцій, імена хостів і секретні значення. Якщо повідомлення у стилі LogTape схоже на текст payload користувача/чату/інструмента, експорт зберігає лише факт пропуску повідомлення та кількість його байтів.
### `gateway status`
-`gateway status` показує сервіс Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливостей з’єднання/автентифікації.
+`gateway status` показує службу Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливостей з’єднання/автентифікації.
```bash
openclaw gateway status
@@ -181,93 +255,113 @@ openclaw gateway status --json
openclaw gateway status --require-rpc
```
-Параметри:
+
+ Додати явну ціль перевірки. Налаштований віддалений вузол + localhost усе одно перевіряються.
+
+
+ Автентифікація токеном для перевірки.
+
+
+ Автентифікація паролем для перевірки.
+
+
+ Тайм-аут перевірки.
+
+
+ Пропустити перевірку з’єднання (лише перегляд служби).
+
+
+ Також сканувати системні служби.
+
+
+ Підвищити стандартну перевірку з’єднання до перевірки читання і завершити роботу з ненульовим кодом, якщо ця перевірка читання не вдається. Не можна поєднувати з `--no-probe`.
+
-- `--url `: додати явну ціль перевірки. Налаштовані remote + localhost також перевіряються.
-- `--token `: автентифікація токеном для перевірки.
-- `--password `: автентифікація паролем для перевірки.
-- `--timeout `: timeout перевірки (за замовчуванням `10000`).
-- `--no-probe`: пропустити перевірку з’єднання (лише перегляд сервісу).
-- `--deep`: також сканувати системні сервіси.
-- `--require-rpc`: підвищити типову перевірку з’єднання до перевірки читання й завершуватися з ненульовим кодом, якщо перевірка читання не пройшла. Не можна поєднувати з `--no-probe`.
-
-Примітки:
-
-- `gateway status` залишається доступною для діагностики, навіть коли локальна конфігурація CLI відсутня або невалідна.
-- Типова `gateway status` підтверджує стан сервісу, WebSocket-з’єднання та можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування.
-- Діагностичні перевірки не змінюють стан для первинної автентифікації пристрою: вони повторно використовують
- наявний кешований токен пристрою, якщо він є, але не створюють нову
- ідентичність пристрою CLI або запис pairing read-only пристрою лише для перевірки статусу.
-- `gateway status` за можливості розв’язує налаштовані auth SecretRef для автентифікації перевірки.
-- Якщо в цьому шляху команди потрібний auth SecretRef не вдається розв’язати, `gateway status --json` повідомляє `rpc.authWarning`, коли перевірка з’єднання/автентифікації не проходить; передайте `--token`/`--password` явно або спочатку розв’яжіть джерело секрету.
-- Якщо перевірка проходить успішно, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибнопозитивних спрацьовувань.
-- Використовуйте `--require-rpc` у скриптах і автоматизації, коли сервісу, що слухає порт, недостатньо і потрібно, щоб виклики RPC з правом читання також були працездатні.
-- `--deep` додає best-effort сканування додаткових установок launchd/systemd/schtasks. Якщо виявлено кілька сервісів, схожих на gateway, у виводі для людини друкуються підказки щодо очищення й попередження, що в більшості налаштувань має працювати один gateway на машину.
-- Вивід для людини містить розв’язаний шлях до файлового логу плюс знімок шляхів/валідності конфігурації CLI-vs-service, щоб допомогти діагностувати розходження профілю або каталогу стану.
-- Для інсталяцій systemd у Linux перевірки розходжень автентифікації сервісу читають і значення `Environment=`, і `EnvironmentFile=` з unit-файлу (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами з `-`).
-- Перевірки розходжень розв’язують `gateway.auth.token` SecretRef, використовуючи об’єднане runtime env (спочатку env команди сервісу, потім process env як запасний варіант).
-- Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy`, або режим не задано, коли може перемогти пароль і жоден кандидат на токен не може перемогти), перевірки розходжень токена пропускають розв’язання токена конфігурації.
+
+
+ - `gateway status` лишається доступним для діагностики, навіть коли локальна конфігурація CLI відсутня або недійсна.
+ - Типовий `gateway status` підтверджує стан служби, WebSocket-з’єднання і можливість автентифікації, видиму під час handshake. Він не підтверджує операції читання/запису/адміністрування.
+ - Діагностичні перевірки не змінюють стан для першої автентифікації пристрою: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність пристрою CLI або запис прив’язки пристрою лише для читання лише для перевірки status.
+ - `gateway status` за можливості розв’язує налаштовані SecretRef автентифікації для перевірочної автентифікації.
+ - Якщо потрібний SecretRef автентифікації не розв’язується в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли перевірка з’єднання/автентифікації RPC не вдається; явно передайте `--token`/`--password` або спочатку розв’яжіть джерело секрету.
+ - Якщо перевірка успішна, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибнопозитивних результатів.
+ - Використовуйте `--require-rpc` у скриптах і автоматизації, коли служби, що слухає, недостатньо і потрібно, щоб також були справні RPC-виклики з областю читання.
+ - `--deep` додає найкращу можливу спробу сканування додаткових інсталяцій launchd/systemd/schtasks. Коли виявлено кілька служб, схожих на gateway, вивід для людини показує підказки з очищення та попереджає, що більшість налаштувань мають запускати один gateway на машину.
+ - Вивід для людини містить розв’язаний шлях до файла журналу, а також знімок шляхів/дійсності конфігурації CLI порівняно зі службою, щоб допомогти діагностувати дрейф профілю або каталогу стану.
+
+
+ - В інсталяціях Linux systemd перевірки дрейфу автентифікації служби читають значення `Environment=` і `EnvironmentFile=` з unit-файла (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами `-`).
+ - Перевірки дрейфу розв’язують SecretRef `gateway.auth.token`, використовуючи об’єднане runtime-середовище (спочатку командне середовище служби, потім запасний варіант із середовища процесу).
+ - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy`, або режим не встановлено, де може перемогти пароль і жоден кандидат токена не може перемогти), перевірки дрейфу токена пропускають розв’язання токена конфігурації.
+
+
### `gateway probe`
`gateway probe` — це команда «налагодити все». Вона завжди перевіряє:
-- ваш налаштований віддалений gateway (якщо задано), і
-- localhost (loopback) **навіть якщо remote налаштовано**.
+- ваш налаштований віддалений gateway (якщо встановлено), і
+- localhost (local loopback) **навіть якщо віддалений gateway налаштовано**.
-Якщо ви передасте `--url`, ця явна ціль буде додана перед обома. У виводі для людини
-цілі позначаються так:
+Якщо передати `--url`, ця явна ціль додається перед обома. Вивід для людини позначає цілі так:
-- `URL (explicit)`
-- `Remote (configured)` або `Remote (configured, inactive)`
+- `URL (явний)`
+- `Remote (налаштований)` або `Remote (налаштований, неактивний)`
- `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-виклики з подробицями в області читання (`health`/`status`/`system-presence`/`config.get`) також успішні.
+ - `Read probe: limited - missing scope: operator.read` означає, що з’єднання встановлено успішно, але RPC з областю читання обмежений. Це повідомляється як **погіршена** доступність, а не як повна невдача.
+ - Як і `gateway status`, probe повторно використовує наявну кешовану автентифікацію пристрою, але не створює стан першої ідентичності пристрою або прив’язки.
+ - Код виходу ненульовий лише тоді, коли жодна з перевірених цілей недоступна.
+
+
+ Верхній рівень:
-- `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-з’єднання.
-- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що саме перевірка змогла підтвердити щодо автентифікації. Це окремо від досяжності.
-- `Read probe: ok` означає, що також успішно виконалися RPC-виклики деталізації з областю читання (`health`/`status`/`system-presence`/`config.get`).
-- `Read probe: limited - missing scope: operator.read` означає, що з’єднання встановлено успішно, але RPC із областю читання обмежені. Це повідомляється як **погіршена** досяжність, а не повна невдача.
-- Як і `gateway status`, probe повторно використовує наявну кешовану автентифікацію пристрою, але не
- створює первинну ідентичність пристрою або стан pairing.
-- Код виходу є ненульовим лише тоді, коли жодна перевірена ціль недосяжна.
+ - `ok`: принаймні одна ціль доступна.
+ - `degraded`: принаймні одна ціль мала RPC із подробицями, обмежений областю.
+ - `capability`: найкраща можливість, побачена серед доступних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`).
+ - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем у такому порядку: явний URL, SSH-тунель, налаштований remote, потім local loopback.
+ - `warnings[]`: записи попереджень із найкращою можливою спробою, що містять `code`, `message` і необов’язкові `targetIds`.
+ - `network`: підказки URL для local loopback/tailnet, похідні від поточної конфігурації та мережі хоста.
+ - `discovery.timeoutMs` і `discovery.count`: фактичний бюджет/кількість результатів виявлення, використані для цього проходу probe.
-Примітки щодо JSON (`--json`):
+ Для кожної цілі (`targets[].connect`):
-- Верхній рівень:
- - `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.read`.
-- Для кожної цілі (`targets[].auth`):
- - `role`: роль автентифікації, повідомлена в `hello-ok`, якщо доступна.
- - `scopes`: надані області видимості, повідомлені в `hello-ok`, якщо доступні.
- - `capability`: класифікація можливостей автентифікації, відображена для цієї цілі.
+ - `ok`: доступність після з’єднання + класифікація погіршення.
+ - `rpcOk`: повний успіх RPC із подробицями.
+ - `scopeLimited`: RPC із подробицями не вдався через відсутню область оператора.
-Поширені коди попереджень:
+ Для кожної цілі (`targets[].auth`):
-- `ssh_tunnel_failed`: не вдалося налаштувати SSH-тунель; команда повернулася до прямих перевірок.
-- `multiple_gateways`: було досягнуто більше ніж одну ціль; це нетипово, якщо тільки ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot.
-- `auth_secretref_unresolved`: не вдалося розв’язати налаштований auth SecretRef для цілі, що завершилася невдачею.
-- `probe_scope_limited`: WebSocket-з’єднання встановлено успішно, але перевірка читання була обмежена через відсутність `operator.read`.
+ - `role`: роль автентифікації, повідомлена в `hello-ok`, коли доступна.
+ - `scopes`: надані області, повідомлені в `hello-ok`, коли доступні.
+ - `capability`: представлена класифікація можливостей автентифікації для цієї цілі.
+
+
+
+ - `ssh_tunnel_failed`: не вдалося налаштувати SSH-тунель; команда повернулася до прямих перевірок.
+ - `multiple_gateways`: доступною була більш ніж одна ціль; це незвично, якщо тільки ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot.
+ - `auth_secretref_unresolved`: налаштований SecretRef автентифікації не вдалося розв’язати для цілі, що завершилася невдачею.
+ - `probe_scope_limited`: WebSocket-з’єднання встановлено успішно, але перевірка читання була обмежена через відсутність `operator.read`.
+
+
#### Remote через SSH (паритет із застосунком Mac)
-Режим “Remote over SSH” у застосунку macOS використовує локальне перенаправлення порту, тому віддалений gateway (який може бути прив’язаний лише до loopback) стає доступним за адресою `ws://127.0.0.1:`.
+Режим «Remote over SSH» у застосунку macOS використовує локальне перенаправлення порту, щоб віддалений gateway (який може бути прив’язаний лише до loopback) став доступним за адресою `ws://127.0.0.1:`.
Еквівалент у CLI:
@@ -275,15 +369,17 @@ openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```
-Параметри:
+
+ `user@host` або `user@host:port` (типовий порт — `22`).
+
+
+ Файл ідентифікації.
+
+
+ Вибрати перший виявлений хост gateway як ціль SSH із розв’язаного endpoint виявлення (`local.` плюс налаштований домен широкої області, якщо є). Підказки лише TXT ігноруються.
+
-- `--ssh `: `user@host` або `user@host:port` (порт за замовчуванням `22`).
-- `--ssh-identity `: файл ідентичності.
-- `--ssh-auto`: вибрати перший виявлений хост gateway як SSH-ціль із розв’язаного
- ендпойнта виявлення (`local.` плюс налаштований wide-area домен, якщо є). Підказки
- лише з TXT ігноруються.
-
-Конфігурація (необов’язкова, використовується як значення за замовчуванням):
+Конфігурація (необов’язкова, використовується як типові значення):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
@@ -297,22 +393,33 @@ openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
-Параметри:
+
+ Рядок JSON-об’єкта для параметрів.
+
+
+ URL WebSocket Gateway.
+
+
+ Токен Gateway.
+
+
+ Пароль Gateway.
+
+
+ Бюджет тайм-ауту.
+
+
+ Переважно для RPC у стилі агента, які перед фінальним payload передають проміжні події потоку.
+
+
+ JSON-вивід для машинного читання.
+
-- `--params `: рядок JSON-об’єкта для параметрів (за замовчуванням `{}`)
-- `--url `
-- `--token `
-- `--password `
-- `--timeout `
-- `--expect-final`
-- `--json`
+
+`--params` має бути коректним JSON.
+
-Примітки:
-
-- `--params` має бути валідним JSON.
-- `--expect-final` призначений переважно для RPC у стилі агента, які перед остаточним payload передають проміжні події.
-
-## Керування сервісом Gateway
+## Керування службою Gateway
```bash
openclaw gateway install
@@ -322,41 +429,42 @@ openclaw gateway restart
openclaw gateway uninstall
```
-Параметри команд:
-
-- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
-- `gateway install`: `--port`, `--runtime `, `--token`, `--force`, `--json`
-- `gateway uninstall|start|stop|restart`: `--json`
-
-Примітки:
-
-- `gateway install` підтримує `--port`, `--runtime`, `--token`, `--force`, `--json`.
-- Використовуйте `gateway restart`, щоб перезапустити керований сервіс. Не поєднуйте `gateway stop` і `gateway start` як заміну перезапуску; у macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупинкою.
-- Коли автентифікація токеном вимагає токен, а `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у метадані середовища сервісу.
-- Якщо автентифікація токеном вимагає токен, а налаштований token SecretRef не розв’язується, установлення завершується із закритою помилкою замість збереження резервного plaintext.
-- Для автентифікації паролем у `gateway run` віддавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password`, підкріпленому SecretRef, замість inline `--password`.
-- У режимі inferred auth лише `OPENCLAW_GATEWAY_PASSWORD` в оболонці не послаблює вимоги до токена для install; використовуйте стійку конфігурацію (`gateway.auth.password` або config `env`) під час установлення керованого сервісу.
-- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, установлення блокується, доки режим не буде встановлено явно.
-- Команди життєвого циклу приймають `--json` для сценаріїв.
+
+
+ - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+ - `gateway install`: `--port`, `--runtime `, `--token`, `--force`, `--json`
+ - `gateway uninstall|start|stop|restart`: `--json`
+
+
+ - `gateway install` підтримує `--port`, `--runtime`, `--token`, `--force`, `--json`.
+ - Використовуйте `gateway restart`, щоб перезапустити керовану службу. Не поєднуйте `gateway stop` і `gateway start` як заміну перезапуску; на macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупинкою.
+ - Коли автентифікація токеном потребує токена і `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у метаданих середовища служби.
+ - Якщо автентифікація токеном потребує токена, а налаштований SecretRef токена не розв’язується, інсталяція завершується із закритою відмовою замість збереження запасного відкритого тексту.
+ - Для автентифікації паролем у `gateway run` надавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password` на основі SecretRef, а не вбудованому `--password`.
+ - У режимі виведеної автентифікації лише оболонковий `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час інсталяції; використовуйте стійку конфігурацію (`gateway.auth.password` або config `env`) під час інсталяції керованої служби.
+ - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, інсталяція блокується, доки режим не буде встановлено явно.
+ - Команди життєвого циклу приймають `--json` для сценаріїв.
+
+
## Виявлення gateway (Bonjour)
`gateway discover` сканує маяки Gateway (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
-- Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (наприклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [/gateway/bonjour](/uk/gateway/bonjour)
+- Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [Bonjour](/uk/gateway/bonjour).
-Маяк рекламують лише gateway з увімкненим виявленням Bonjour (за замовчуванням увімкнено).
+Лише gateway з увімкненим виявленням Bonjour (типово увімкнено) рекламують маяк.
-Записи Wide-Area discovery містять (TXT):
+Записи виявлення Wide-Area містять (TXT):
- `role` (підказка ролі gateway)
- `transport` (підказка транспорту, наприклад `gateway`)
- `gatewayPort` (порт WebSocket, зазвичай `18789`)
-- `sshPort` (необов’язково; за його відсутності клієнти використовують для SSH-цілей значення `22`)
+- `sshPort` (необов’язково; клієнти типово використовують `22` для SSH-цілей, якщо його немає)
- `tailnetDns` (ім’я хоста MagicDNS, якщо доступне)
- `gatewayTls` / `gatewayTlsSha256` (TLS увімкнено + відбиток сертифіката)
-- `cliPath` (підказка remote-install, записана до wide-area зони)
+- `cliPath` (підказка віддаленої інсталяції, записана до зони wide-area)
### `gateway discover`
@@ -364,10 +472,12 @@ openclaw gateway uninstall
openclaw gateway discover
```
-Параметри:
-
-- `--timeout `: timeout для кожної команди (browse/resolve); за замовчуванням `2000`.
-- `--json`: машинозчитуваний вивід (також вимикає стилізацію/spinner).
+
+ Тайм-аут для кожної команди (browse/resolve).
+
+
+ Вивід для машинного читання (також вимикає стилізацію/спінер).
+
Приклади:
@@ -376,16 +486,13 @@ openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
-Примітки:
-
-- CLI сканує `local.` плюс налаштований wide-area домен, якщо його ввімкнено.
-- `wsUrl` у JSON-виводі виводиться з розв’язаного ендпойнта сервісу, а не з підказок
- лише з TXT, таких як `lanHost` або `tailnetDns`.
-- У `local.` mDNS `sshPort` і `cliPath` транслюються лише тоді, коли
- `discovery.mdns.mode` має значення `full`. Wide-area DNS-SD усе одно записує `cliPath`; `sshPort`
- там теж залишається необов’язковим.
+
+- CLI сканує `local.` плюс налаштований домен wide-area, коли його увімкнено.
+- `wsUrl` у JSON-виводі виводиться з розв’язаного endpoint служби, а не з підказок лише TXT, таких як `lanHost` або `tailnetDns`.
+- У mDNS `local.` значення `sshPort` і `cliPath` транслюються лише тоді, коли `discovery.mdns.mode` має значення `full`. Wide-Area DNS-SD усе одно записує `cliPath`; `sshPort` там також лишається необов’язковим.
+
## Пов’язане
-- [Довідник CLI](/uk/cli)
-- [Інструкція з експлуатації Gateway](/uk/gateway)
+- [Довідка CLI](/uk/cli)
+- [Runbook Gateway](/uk/gateway)
diff --git a/docs/uk/cli/plugins.md b/docs/uk/cli/plugins.md
index 0abd0a5c2..8fe27c578 100644
--- a/docs/uk/cli/plugins.md
+++ b/docs/uk/cli/plugins.md
@@ -1,28 +1,35 @@
---
read_when:
- - Ви хочете встановити або керувати плагінами Gateway чи сумісними пакетами
- - Ви хочете налагодити збої завантаження плагінів
-summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
-title: Плагіни
+ - Ви хочете встановити або керувати Gateway plugins чи сумісними пакетами
+ - Ви хочете налагодити збої завантаження plugin
+sidebarTitle: Plugins
+summary: Довідник CLI для `openclaw plugins` (`list`, `install`, `marketplace`, `uninstall`, `enable`/`disable`, `doctor`)
+title: Plugins
x-i18n:
- generated_at: "2026-04-26T03:28:06Z"
+ generated_at: "2026-04-26T09:06:04Z"
model: gpt-5.4
provider: openai
- source_hash: 6dec5a7f48d8daaa5230280250642885cb355d1a5f83bacd78d81ba45fa6a7d8
+ source_hash: ee842072b725abbeb229282e1bd16478216f52145f0aa27355c4cbd7c7794966
source_path: cli/plugins.md
workflow: 15
---
-# `openclaw plugins`
+Керуйте Gateway plugins, пакетами hook та сумісними пакетами.
-Керуйте плагінами Gateway, наборами хуків і сумісними пакетами.
-
-Пов’язане:
-
-- Система Plugin: [Плагіни](/uk/tools/plugin)
-- Сумісність пакетів: [Пакети Plugin](/uk/plugins/bundles)
-- Маніфест Plugin + схема: [Маніфест Plugin](/uk/plugins/manifest)
-- Посилення безпеки: [Безпека](/uk/gateway/security)
+
+
+ Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення проблем із plugins.
+
+
+ Модель сумісності пакетів.
+
+
+ Поля маніфесту та схема конфігурації.
+
+
+ Посилення безпеки для встановлення plugins.
+
+
## Команди
@@ -48,78 +55,97 @@ openclaw plugins marketplace list
openclaw plugins marketplace list --json
```
-Вбудовані плагіни постачаються разом з OpenClaw. Деякі з них увімкнені типово (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований плагін браузера); інші потребують `plugins enable`.
+
+Вбудовані plugins постачаються разом з OpenClaw. Деякі увімкнені типово (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований browser plugin); інші потребують `plugins enable`.
-Нативні плагіни 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`) та виявлені можливості пакета.
+
-### Install
+### Встановлення
```bash
-openclaw plugins install # ClawHub first, then npm
-openclaw plugins install clawhub: # ClawHub only
-openclaw plugins install --force # overwrite existing install
-openclaw plugins install --pin # pin version
+openclaw plugins install # спочатку ClawHub, потім npm
+openclaw plugins install clawhub: # лише ClawHub
+openclaw plugins install --force # перезаписати наявне встановлення
+openclaw plugins install --pin # зафіксувати версію
openclaw plugins install --dangerously-force-unsafe-install
-openclaw plugins install # local path
+openclaw plugins install # локальний шлях
openclaw plugins install @ # marketplace
-openclaw plugins install --marketplace # marketplace (explicit)
+openclaw plugins install --marketplace # marketplace (явно)
openclaw plugins install --marketplace https://github.com//
```
-Прості назви пакетів спочатку звіряються з ClawHub, а потім з npm. Примітка щодо безпеки: ставтеся до встановлення плагінів так, ніби ви запускаєте код. Надавайте перевагу зафіксованим версіям.
+
+Імена пакетів без уточнень спочатку перевіряються в ClawHub, а потім у npm. Ставтеся до встановлення plugins так, ніби ви запускаєте код. Віддавайте перевагу зафіксованим версіям.
+
-Якщо ваш розділ `plugins` використовує однофайловий `$include`, `plugins install/update/enable/disable/uninstall` записують зміни до цього включеного файла та не змінюють `openclaw.json`. Кореневі includes, масиви include та includes із сусідніми перевизначеннями безпечно завершуються помилкою замість сплощення. Підтримувані форми див. у [Config includes](/uk/gateway/configuration).
+
+
+ Якщо ваш розділ `plugins` використовує однофайловий `$include`, `plugins install/update/enable/disable/uninstall` записують зміни до цього включеного файла й не змінюють `openclaw.json`. Кореневі включення, масиви включень і включення з сусідніми перевизначеннями завершуються без змін замість сплощення. Підтримувані форми описано в [Включення конфігурації](/uk/gateway/configuration).
-Якщо конфігурація невалідна, `plugins install` зазвичай безпечно завершується помилкою та пропонує спочатку виконати `openclaw doctor --fix`. Єдиний задокументований виняток — вузький шлях відновлення для вбудованих плагінів, які явно ввімкнули `openclaw.install.allowInvalidConfigRecovery`.
+ Якщо конфігурація невалідна, `plugins install` зазвичай завершується без змін і пропонує спочатку виконати `openclaw doctor --fix`. Єдиний задокументований виняток — вузький шлях відновлення для вбудованих plugins, які явно ввімкнули `openclaw.install.allowInvalidConfigRecovery`.
-`--force` повторно використовує наявну ціль встановлення та перезаписує вже встановлений плагін або набір хуків на місці. Використовуйте це, коли ви навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або npm-артефакту. Для звичайного оновлення вже відстежуваного npm-плагіна надавайте перевагу `openclaw plugins update `.
+
+
+ `--force` повторно використовує наявну ціль встановлення й перезаписує вже встановлений plugin або пакет hook на місці. Використовуйте його, коли ви свідомо перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакту npm. Для звичайних оновлень уже відстежуваного npm plugin віддавайте перевагу `openclaw plugins update `.
-Якщо ви запускаєте `plugins install` для id плагіна, який уже встановлено, OpenClaw зупиняється та вказує на `plugins update ` для звичайного оновлення або на `plugins install --force`, якщо ви справді хочете перезаписати поточне встановлення з іншого джерела.
+ Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється й вказує на `plugins update ` для звичайного оновлення або на `plugins install --force`, коли ви дійсно хочете перезаписати поточне встановлення з іншого джерела.
-`--pin` застосовується лише до встановлень через npm. Він не підтримується з `--marketplace`, оскільки встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
+
+
+ `--pin` застосовується лише до встановлень npm. Він не підтримується з `--marketplace`, оскільки встановлення з marketplace зберігають метадані джерела marketplace, а не специфікацію npm.
+
+
+ `--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацювань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про знахідки рівня `critical`, але **не** обходить блокування політики hook `before_install` plugin і **не** обходить помилки сканування.
-`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про знахідки рівня `critical`, але **не** обходить блокування політик хуків плагіна `before_install` і **не** обходить збої сканування.
+ Цей прапорець CLI застосовується до потоків встановлення/оновлення plugins. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` лишається окремим потоком завантаження/встановлення Skills із ClawHub.
-Цей прапорець CLI застосовується до потоків install/update для плагінів. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub.
+
+
+ `plugins install` також є поверхнею встановлення для пакетів hook, які надають `openclaw.hooks` у `package.json`. Для відфільтрованої видимості hook і вмикання окремих hook використовуйте `openclaw hooks`, а не встановлення пакетів.
-`plugins install` також є поверхнею встановлення для наборів хуків, які оголошують `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованого перегляду хуків і вмикання окремих хуків, а не для встановлення пакетів.
+ Специфікації npm є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file та діапазони semver відхиляються. Для безпеки встановлення залежностей виконуються локально для проєкту з `--ignore-scripts`, навіть якщо у вашій оболонці є глобальні налаштування npm install.
-Специфікації npm — **лише для реєстру** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Для безпеки встановлення залежностей виконуються локально в межах проєкту з `--ignore-scripts`, навіть якщо у вашій оболонці задано глобальні параметри встановлення npm.
+ Базові специфікації та `@latest` залишаються на стабільній гілці. Якщо npm розв’язує будь-яку з них до prerelease, OpenClaw зупиняється й просить вас явно погодитися на це за допомогою мітки prerelease, такої як `@beta`/`@rc`, або точної версії prerelease, такої як `@1.2.3-beta.4`.
-Прості специфікації та `@latest` залишаються на стабільній гілці. Якщо npm розв’язує будь-яку з них у пререліз, OpenClaw зупиняється та просить вас явно погодитися через тег пререлізу, наприклад `@beta`/`@rc`, або точну версію пререлізу, наприклад `@1.2.3-beta.4`.
+ Якщо базова специфікація встановлення збігається з id вбудованого plugin (наприклад, `diffs`), OpenClaw встановлює вбудований plugin безпосередньо. Щоб встановити npm-пакет із такою самою назвою, використовуйте явну scoped-специфікацію (наприклад, `@scope/diffs`).
-Якщо проста специфікація встановлення збігається з id вбудованого плагіна (наприклад, `diffs`), OpenClaw встановлює вбудований плагін безпосередньо. Щоб встановити npm-пакет із такою самою назвою, використовуйте явну scoped-специфікацію (наприклад, `@scope/diffs`).
+
+
+ Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних plugins OpenClaw мають містити валідний `openclaw.plugin.json` у корені розпакованого plugin; архіви, що містять лише `package.json`, відхиляються до того, як OpenClaw запише записи встановлення.
-Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
-Архіви нативних плагінів OpenClaw мають містити валідний `openclaw.plugin.json` у корені розпакованого плагіна; архіви, що містять лише `package.json`, відхиляються ще до того, як OpenClaw записує відомості про встановлення.
+ Також підтримуються встановлення з marketplace Claude.
-Також підтримуються встановлення з Claude marketplace.
+
+
-Встановлення з ClawHub використовують явний локатор `clawhub:`:
+Для встановлення з ClawHub використовується явний локатор `clawhub:`:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
-Тепер OpenClaw також надає перевагу ClawHub для простих безпечних для npm специфікацій плагінів. До npm він переходить лише тоді, коли в ClawHub немає такого пакета або версії:
+Тепер OpenClaw також надає перевагу ClawHub для базових безпечних для npm специфікацій plugins. До 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`:
+#### Скорочений запис Marketplace
+
+Використовуйте скорочений запис `plugin@marketplace`, коли назва marketplace існує в локальному кеші реєстру Claude за шляхом `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list
openclaw plugins install @
```
-Використовуйте `--marketplace`, коли хочете явно передати джерело marketplace:
+Використовуйте `--marketplace`, якщо хочете явно передати джерело marketplace:
```bash
openclaw plugins install --marketplace
@@ -128,26 +154,31 @@ openclaw plugins install --marketplace https://github.com//
openclaw plugins install --marketplace ./my-marketplace
```
-Джерелами marketplace можуть бути:
-
-- назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json`
-- локальний корінь marketplace або шлях до `marketplace.json`
-- скорочений запис GitHub repo на кшталт `owner/repo`
-- URL GitHub repo на кшталт `https://github.com/owner/repo`
-- git URL
-
-Для віддалених marketplace, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого repo marketplace. OpenClaw приймає відносні джерела шляхів із цього repo та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела плагінів із віддалених маніфестів.
+
+
+ - відома Claude назва marketplace з `~/.claude/plugins/known_marketplaces.json`
+ - локальний корінь marketplace або шлях до `marketplace.json`
+ - скорочений запис GitHub-репозиторію, наприклад `owner/repo`
+ - URL GitHub-репозиторію, наприклад `https://github.com/owner/repo`
+ - git URL
+
+
+ Для віддалених marketplace, завантажених із GitHub або git, записи plugins мають залишатися в межах клонованого репозиторію marketplace. OpenClaw приймає джерела відносних шляхів із цього репозиторію та відхиляє HTTP(S), absolute-path, git, GitHub та інші джерела plugins, що не є шляхами, з віддалених маніфестів.
+
+
Для локальних шляхів і архівів OpenClaw автоматично визначає:
-- нативні плагіни 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`)
-Сумісні пакети встановлюються у звичайний корінь плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються bundle Skills, Claude command-skills, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / `lspServers`, оголошені в маніфесті, Cursor command-skills і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в diagnostics/info, але ще не підключені до виконання під час роботи.
+
+Сумісні пакети встановлюються у звичайний корінь plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються bundle Skills, Claude command-skills, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / `lspServers`, оголошені в маніфесті, Cursor command-skills і сумісні каталоги hook Codex; інші виявлені можливості пакетів показуються в diagnostics/info, але ще не підключені до виконання під час роботи.
+
-### List
+### Список
```bash
openclaw plugins list
@@ -156,15 +187,25 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
-Використовуйте `--enabled`, щоб показувати лише ввімкнені плагіни. Використовуйте `--verbose`, щоб перейти від табличного подання до докладних рядків для кожного плагіна з метаданими source/origin/version/activation. Використовуйте `--json` для машиночитного інвентаря та diagnostics реєстру.
+
+ Показати лише увімкнені plugins.
+
+
+ Перемкнутися з табличного подання на докладні рядки для кожного plugin із метаданими джерела/походження/версії/активації.
+
+
+ Машиночитаний інвентар разом із діагностикою реєстру.
+
-`plugins list` спочатку читає збережений локальний реєстр плагінів із резервним варіантом побудови лише з маніфестів, якщо реєстр відсутній або невалідний. Це корисно для перевірки, чи встановлено, увімкнено та чи видимий плагін для планування холодного запуску, але це не жива перевірка середовища виконання вже запущеного процесу Gateway. Після зміни коду плагіна, його стану ввімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або хуків. Для віддалених/контейнерних розгортань переконайтеся, що ви перезапускаєте саме дочірній процес `openclaw gateway run`, а не лише процес-обгортку.
+
+`plugins list` спочатку читає збережений локальний реєстр plugins із похідним резервним варіантом лише з маніфесту, якщо реєстр відсутній або невалідний. Це корисно, щоб перевірити, чи plugin встановлено, увімкнено й чи він видимий для планування холодного запуску, але це не жива перевірка рантайму для вже запущеного процесу Gateway. Після зміни коду plugin, стану увімкнення, політики hook або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуск нового коду `register(api)` або hook. Для віддалених/контейнерних розгортань перевірте, що ви перезапускаєте саме дочірній процес `openclaw gateway run`, а не лише процес-обгортку.
+
-Для налагодження runtime-хуків:
+Для налагодження hook під час роботи:
-- `openclaw plugins inspect --json` показує зареєстровані хуки та diagnostics із проходу інспекції із завантаженням модуля.
+- `openclaw plugins inspect --json` показує зареєстровані hook і діагностику з проходу перевірки після завантаження модуля.
- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки щодо service/process, шлях до конфігурації та стан RPC.
-- Невбудовані хуки розмови (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`.
+- Не вбудовані hook розмов (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) вимагають `plugins.entries..hooks.allowConversationAccess=true`.
Використовуйте `--link`, щоб уникнути копіювання локального каталогу (додає до `plugins.load.paths`):
@@ -172,16 +213,19 @@ openclaw plugins list --json
openclaw plugins install -l ./my-plugin
```
-`--force` не підтримується разом із `--link`, оскільки linked-встановлення повторно використовують вихідний шлях замість копіювання поверх керованої цілі встановлення.
+
+`--force` не підтримується разом із `--link`, оскільки пов’язані встановлення повторно використовують вихідний шлях замість копіювання у керовану ціль встановлення.
-Використовуйте `--pin` для встановлень через npm, щоб зберегти розв’язану точну специфікацію (`name@version`) у керованому індексі плагінів, залишаючи типову поведінку без фіксації.
+Використовуйте `--pin` для встановлень npm, щоб зберегти розв’язану точну специфікацію (`name@version`) у керованому індексі plugins, зберігаючи типову поведінку без фіксації.
+
-### Plugin Index
+### Індекс Plugin
-Метадані встановлення Plugin — це машинно керований стан, а не користувацька конфігурація. Встановлення та оновлення записують їх у `plugins/installs.json` у межах активного каталогу стану OpenClaw. Його map верхнього рівня `installRecords` є довговічним джерелом метаданих встановлення, зокрема записів для зламаних або відсутніх маніфестів плагінів. Масив `plugins` — це кеш холодного реєстру, побудований із маніфестів. Файл містить попередження про заборону ручного редагування та використовується командами `openclaw plugins update`, uninstall, diagnostics і холодним реєстром плагінів.
-Коли OpenClaw бачить доставлені з попередніх версій записи `plugins.installs` у конфігурації, він переносить їх до індексу плагінів і видаляє ключ конфігурації; якщо будь-який із записів завершиться помилкою, записи конфігурації зберігаються, щоб не втратити метадані встановлення.
+Метадані встановлення plugin — це машинно керований стан, а не користувацька конфігурація. Встановлення та оновлення записують їх у `plugins/installs.json` у активному каталозі стану OpenClaw. Його мапа верхнього рівня `installRecords` є довговічним джерелом метаданих встановлення, зокрема записів для зламаних або відсутніх маніфестів plugin. Масив `plugins` є кешем холодного реєстру, похідним від маніфесту. Файл містить попередження не редагувати його вручну й використовується командами `openclaw plugins update`, uninstall, diagnostics і холодним реєстром plugins.
-### Uninstall
+Коли OpenClaw виявляє успадковані записи `plugins.installs`, що постачаються в конфігурації, він переносить їх до індексу plugins і видаляє ключ конфігурації; якщо будь-який запис не вдається, записи конфігурації зберігаються, щоб метадані встановлення не було втрачено.
+
+### Видалення
```bash
openclaw plugins uninstall
@@ -189,11 +233,13 @@ openclaw plugins uninstall --dry-run
openclaw plugins uninstall --keep-files
```
-`uninstall` видаляє записи плагінів із `plugins.entries`, збереженого індексу плагінів, allowlist плагінів і пов’язаних записів `plugins.load.paths` за потреби. Якщо не задано `--keep-files`, uninstall також видаляє відстежуваний каталог керованого встановлення, якщо він розташований усередині кореня розширень плагінів OpenClaw. Для плагінів active memory слот пам’яті скидається до `memory-core`.
+`uninstall` видаляє записи plugin з `plugins.entries`, збереженого індексу plugins, allowlist plugins і пов’язаних записів `plugins.load.paths`, якщо це застосовно. Якщо не вказано `--keep-files`, uninstall також видаляє відстежуваний керований каталог встановлення, якщо він розташований у корені розширень plugins OpenClaw. Для plugins Active Memory слот пам’яті скидається до `memory-core`.
+
`--keep-config` підтримується як застарілий псевдонім для `--keep-files`.
+
-### Update
+### Оновлення
```bash
openclaw plugins update
@@ -203,43 +249,49 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
-Оновлення застосовуються до відстежуваних встановлень плагінів у керованому індексі плагінів і до відстежуваних встановлень наборів хуків у `hooks.internal.installs`.
+Оновлення застосовуються до відстежуваних встановлень plugin у керованому індексі plugins і до відстежуваних встановлень пакетів hook у `hooks.internal.installs`.
-Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-tag, такі як `@beta`, і точно зафіксовані версії продовжують використовуватися під час наступних запусків `update `.
+
+
+ Коли ви передаєте id plugin, OpenClaw повторно використовує збережену специфікацію встановлення для цього plugin. Це означає, що раніше збережені dist-tag, такі як `@beta`, і точно зафіксовані версії й надалі використовуються в наступних запусках `update `.
-Для встановлень через npm ви також можете передати явну специфікацію npm-пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета назад із записом відстежуваного плагіна, оновлює цей встановлений плагін і записує нову специфікацію npm для майбутніх оновлень за id.
+ Для встановлень npm ви також можете передати явну специфікацію npm-пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета назад із записом відстежуваного plugin, оновлює цей встановлений plugin і зберігає нову специфікацію npm для майбутніх оновлень за id.
-Передавання назви npm-пакета без версії або тега також зіставляється назад із записом відстежуваного плагіна. Використовуйте це, коли плагін був зафіксований на точній версії, а ви хочете повернути його до типової лінії релізів реєстру.
+ Передавання назви npm-пакета без версії або тега також зіставляється назад із записом відстежуваного plugin. Використовуйте це, якщо plugin було зафіксовано на точній версії й ви хочете повернути його до типової лінії випусків реєстру.
-Перед живим оновленням npm OpenClaw перевіряє встановлену версію пакета щодо метаданих реєстру npm. Якщо встановлена версія та записана ідентичність артефакту вже збігаються з розв’язаною ціллю, оновлення пропускається без завантаження, перевстановлення чи перезапису `openclaw.json`.
+
+
+ Перед виконанням реального оновлення npm OpenClaw перевіряє версію встановленого пакета за метаданими реєстру npm. Якщо встановлена версія та ідентичність збереженого артефакту вже відповідають цільовому результату, оновлення пропускається без завантаження, перевстановлення чи перезапису `openclaw.json`.
-Коли існує збережений хеш цілісності, а хеш отриманого артефакту змінюється, OpenClaw розглядає це як дрейф npm-артефакту. Інтерактивна команда `openclaw plugins update` виводить очікуваний і фактичний хеші та просить підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення безпечно завершуються помилкою, якщо викликач не надає явну політику продовження.
+ Якщо збережено хеш цілісності й хеш завантаженого артефакту змінюється, OpenClaw розцінює це як дрейф артефакту npm. Інтерактивна команда `openclaw plugins update` виводить очікуваний і фактичний хеші та просить підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення завершуються без змін, якщо викликач не надає явну політику продовження.
-`--dangerously-force-unsafe-install` також доступний для `plugins update` як аварійне перевизначення для хибнопозитивних спрацьовувань вбудованого сканування небезпечного коду під час оновлення плагінів. Він так само не обходить блокування політик плагіна `before_install` або блокування через збої сканування і застосовується лише до оновлень плагінів, а не до оновлень наборів хуків.
+
+
+ `--dangerously-force-unsafe-install` також доступний для `plugins update` як аварійне перевизначення для хибнопозитивних спрацювань вбудованого сканування небезпечного коду під час оновлень plugin. Він, як і раніше, не обходить блокування політики `before_install` plugin або блокування через помилки сканування, і застосовується лише до оновлень plugin, а не до оновлень пакетів hook.
+
+
-### Inspect
+### Перевірка
```bash
openclaw plugins inspect
openclaw plugins inspect --json
```
-Глибока інтроспекція для одного плагіна. Показує ідентичність, стан завантаження, джерело, зареєстровані можливості, хуки, інструменти, команди, сервіси, методи gateway, HTTP-маршрути, прапорці політик, diagnostics, метадані встановлення, можливості пакетів і будь-яку виявлену підтримку MCP або LSP-сервера.
+Поглиблена перевірка одного plugin. Показує ідентичність, статус завантаження, джерело, зареєстровані можливості, hook, tools, commands, services, методи gateway, HTTP-маршрути, прапорці політики, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку MCP або LSP server.
-Кожен плагін класифікується за тим, що саме він реєструє під час виконання:
+Кожен plugin класифікується за тим, що саме він реєструє під час виконання:
-- **plain-capability** — один тип можливостей (наприклад, плагін лише для провайдера)
-- **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення)
-- **hook-only** — лише хуки, без можливостей або поверхонь
-- **non-capability** — інструменти/команди/сервіси, але без можливостей
+- **plain-capability** — один тип можливостей (наприклад, plugin лише з провайдером)
+- **hybrid-capability** — кілька типів можливостей (наприклад, text + speech + images)
+- **hook-only** — лише hook, без можливостей або поверхонь
+- **non-capability** — tools/commands/services без можливостей
Докладніше про модель можливостей див. у [Форми Plugin](/uk/plugins/architecture#plugin-shapes).
-Прапорець `--json` виводить машиночитний звіт, придатний для сценаріїв і аудиту.
-
-`inspect --all` відображає загальносистемну таблицю зі стовпцями shape, capability kinds, compatibility notices, bundle capabilities і summary хуків.
-
-`info` — це псевдонім для `inspect`.
+
+Прапорець `--json` виводить машиночитаний звіт, придатний для скриптів і аудиту. `inspect --all` відображає загальносистемну таблицю з колонками форми, типів можливостей, повідомлень про сумісність, можливостей пакетів і зведенням hook. `info` є псевдонімом для `inspect`.
+
### Doctor
@@ -247,11 +299,11 @@ openclaw plugins inspect --json
openclaw plugins doctor
```
-`doctor` повідомляє про помилки завантаження плагінів, diagnostics маніфестів/виявлення та повідомлення щодо сумісності. Якщо все гаразд, він виводить `No plugin issues detected.`
+`doctor` повідомляє про помилки завантаження plugin, діагностику маніфесту/виявлення та повідомлення про сумісність. Якщо все в порядку, він виводить `No plugin issues detected.`
-Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`, повторіть запуск із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити до diagnostic-виводу компактне зведення форми експорту.
+Для збоїв форми модуля, таких як відсутність експортів `register`/`activate`, запустіть повторно з `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити компактне зведення форми експорту до діагностичного виводу.
-### Registry
+### Реєстр
```bash
openclaw plugins registry
@@ -259,11 +311,13 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
-Локальний реєстр плагінів — це збережена холодна модель читання OpenClaw для встановленої ідентичності плагінів, стану ввімкнення, метаданих джерела та належності внесків. Звичайний запуск, пошук власника провайдера, класифікація налаштування каналу та інвентар плагінів можуть читати його без імпорту runtime-модулів плагінів.
+Локальний реєстр plugins — це збережена модель холодного читання OpenClaw для ідентичності встановлених plugins, стану увімкнення, метаданих джерела та належності внесків. Звичайний запуск, пошук власника провайдера, класифікація налаштування каналу та інвентаризація plugins можуть читати його без імпорту модулів runtime plugin.
-Використовуйте `plugins registry`, щоб перевірити, чи існує збережений реєстр, чи він актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його із збереженого індексу плагінів, політики конфігурації та метаданих маніфесту/пакета. Це шлях відновлення, а не шлях runtime-активації.
+Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр наявний, актуальний чи застарілий. Використовуйте `--refresh`, щоб перебудувати його із збереженого індексу plugins, політики конфігурації та метаданих маніфесту/пакета. Це шлях відновлення, а не шлях активації runtime.
-`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через env призначений лише для аварійного відновлення запуску, поки триває розгортання міграції.
+
+`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний env-варіант призначено лише для аварійного відновлення запуску під час розгортання міграції.
+
### Marketplace
@@ -272,10 +326,10 @@ openclaw plugins marketplace list
openclaw plugins marketplace list --json
```
-Список marketplace приймає локальний шлях до marketplace, шлях до `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL GitHub repo або git URL. `--json` виводить мітку розв’язаного джерела, а також розібраний маніфест marketplace і записи плагінів.
+Список marketplace приймає локальний шлях до marketplace, шлях до `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL GitHub-репозиторію або git URL. `--json` виводить мітку визначеного джерела разом із розібраним маніфестом marketplace і записами plugins.
## Пов’язане
+- [Створення plugins](/uk/plugins/building-plugins)
- [Довідник CLI](/uk/cli)
-- [Створення плагінів](/uk/plugins/building-plugins)
-- [Спільнотні плагіни](/uk/plugins/community)
+- [Спільнотні plugins](/uk/plugins/community)
diff --git a/docs/uk/tools/multi-agent-sandbox-tools.md b/docs/uk/tools/multi-agent-sandbox-tools.md
index a3382d128..265cffee4 100644
--- a/docs/uk/tools/multi-agent-sandbox-tools.md
+++ b/docs/uk/tools/multi-agent-sandbox-tools.md
@@ -1,184 +1,185 @@
---
-read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.”
+read_when: You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.
+sidebarTitle: Multi-agent sandbox and tools
status: active
-summary: «Пісочниця та обмеження інструментів для кожного агента, пріоритетність і приклади»
-title: Пісочниця багатьох агентів і інструменти
+summary: Пісочниця та обмеження інструментів для кожного агента, пріоритетність і приклади
+title: Пісочниця та інструменти для кількох агентів
x-i18n:
- generated_at: "2026-04-25T00:15:14Z"
+ generated_at: "2026-04-26T09:05:57Z"
model: gpt-5.4
provider: openai
- source_hash: 4473b8ea0f10c891b08cb56c9ba5a073f79c55b42f5b348b69ffb3c3d94c8f88
+ source_hash: 8b8d24252b03dbcd00a5eefcc8e58bd51577a99ae057008f19a0acc4016413ea
source_path: tools/multi-agent-sandbox-tools.md
workflow: 15
---
-# Конфігурація пісочниці та інструментів для багатьох агентів
+Кожен агент у багатoагентному налаштуванні може перевизначати глобальну політику пісочниці та інструментів. На цій сторінці описано конфігурацію для окремих агентів, правила пріоритетності та приклади.
-Кожен агент у конфігурації з багатьма агентами може перевизначати глобальну політику пісочниці та інструментів. На цій сторінці описано конфігурацію для окремих агентів, правила пріоритетності та приклади.
+
+
+ Бекенди та режими — повний довідник із пісочниці.
+
+
+ Налагодження «чому це заблоковано?»
+
+
+ Elevated exec для довірених відправників.
+
+
-- **Бекенди та режими пісочниці**: див. [Пісочниця](/uk/gateway/sandboxing).
-- **Налагодження заблокованих інструментів**: див. [Пісочниця vs політика інструментів vs підвищений режим](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) і `openclaw sandbox explain`.
-- **Підвищене виконання**: див. [Підвищений режим](/uk/tools/elevated).
-
-Auth є окремою для кожного агента: кожен агент читає зі свого сховища auth у `agentDir` за адресою
-`~/.openclaw/agents//agent/auth-profiles.json`.
-Облікові дані **не** спільні між агентами. Ніколи не використовуйте один `agentDir` повторно для кількох агентів.
-Якщо ви хочете поділитися обліковими даними, скопіюйте `auth-profiles.json` до `agentDir` іншого агента.
+
+Автентифікація прив’язана до агента: кожен агент читає зі свого сховища auth у `agentDir` за шляхом `~/.openclaw/agents//agent/auth-profiles.json`. Облікові дані **не** спільні між агентами. Ніколи не використовуйте один і той самий `agentDir` для кількох агентів. Якщо ви хочете поділитися обліковими даними, скопіюйте `auth-profiles.json` до `agentDir` іншого агента.
+
---
## Приклади конфігурації
-### Приклад 1: особистий агент + обмежений сімейний агент
-
-```json
-{
- "agents": {
- "list": [
- {
- "id": "main",
- "default": true,
- "name": "Personal Assistant",
- "workspace": "~/.openclaw/workspace",
- "sandbox": { "mode": "off" }
- },
- {
- "id": "family",
- "name": "Family Bot",
- "workspace": "~/.openclaw/workspace-family",
- "sandbox": {
- "mode": "all",
- "scope": "agent"
- },
- "tools": {
- "allow": ["read"],
- "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
- }
- }
- ]
- },
- "bindings": [
+
+
+ ```json
{
- "agentId": "family",
- "match": {
- "provider": "whatsapp",
- "accountId": "*",
- "peer": {
- "kind": "group",
- "id": "120363424282127706@g.us"
+ "agents": {
+ "list": [
+ {
+ "id": "main",
+ "default": true,
+ "name": "Personal Assistant",
+ "workspace": "~/.openclaw/workspace",
+ "sandbox": { "mode": "off" }
+ },
+ {
+ "id": "family",
+ "name": "Family Bot",
+ "workspace": "~/.openclaw/workspace-family",
+ "sandbox": {
+ "mode": "all",
+ "scope": "agent"
+ },
+ "tools": {
+ "allow": ["read"],
+ "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
+ }
+ }
+ ]
+ },
+ "bindings": [
+ {
+ "agentId": "family",
+ "match": {
+ "provider": "whatsapp",
+ "accountId": "*",
+ "peer": {
+ "kind": "group",
+ "id": "120363424282127706@g.us"
+ }
+ }
}
+ ]
+ }
+ ```
+
+ **Результат:**
+
+ - агент `main`: працює на хості, повний доступ до інструментів.
+ - агент `family`: працює в Docker (один контейнер на агента), лише інструмент `read`.
+
+
+
+ ```json
+ {
+ "agents": {
+ "list": [
+ {
+ "id": "personal",
+ "workspace": "~/.openclaw/workspace-personal",
+ "sandbox": { "mode": "off" }
+ },
+ {
+ "id": "work",
+ "workspace": "~/.openclaw/workspace-work",
+ "sandbox": {
+ "mode": "all",
+ "scope": "shared",
+ "workspaceRoot": "/tmp/work-sandboxes"
+ },
+ "tools": {
+ "allow": ["read", "write", "apply_patch", "exec"],
+ "deny": ["browser", "gateway", "discord"]
+ }
+ }
+ ]
}
}
- ]
-}
-```
+ ```
+
+
+ ```json
+ {
+ "tools": { "profile": "coding" },
+ "agents": {
+ "list": [
+ {
+ "id": "support",
+ "tools": { "profile": "messaging", "allow": ["slack"] }
+ }
+ ]
+ }
+ }
+ ```
-**Результат:**
+ **Результат:**
-- агент `main`: працює на хості, має повний доступ до інструментів
-- агент `family`: працює в Docker (один контейнер на агента), лише інструмент `read`
+ - агенти за замовчуванням отримують інструменти для кодування.
+ - агент `support` призначений лише для обміну повідомленнями (+ інструмент Slack).
----
-
-### Приклад 2: робочий агент зі спільною пісочницею
-
-```json
-{
- "agents": {
- "list": [
- {
- "id": "personal",
- "workspace": "~/.openclaw/workspace-personal",
- "sandbox": { "mode": "off" }
- },
- {
- "id": "work",
- "workspace": "~/.openclaw/workspace-work",
- "sandbox": {
- "mode": "all",
- "scope": "shared",
- "workspaceRoot": "/tmp/work-sandboxes"
+
+
+ ```json
+ {
+ "agents": {
+ "defaults": {
+ "sandbox": {
+ "mode": "non-main",
+ "scope": "session"
+ }
},
- "tools": {
- "allow": ["read", "write", "apply_patch", "exec"],
- "deny": ["browser", "gateway", "discord"]
- }
+ "list": [
+ {
+ "id": "main",
+ "workspace": "~/.openclaw/workspace",
+ "sandbox": {
+ "mode": "off"
+ }
+ },
+ {
+ "id": "public",
+ "workspace": "~/.openclaw/workspace-public",
+ "sandbox": {
+ "mode": "all",
+ "scope": "agent"
+ },
+ "tools": {
+ "allow": ["read"],
+ "deny": ["exec", "write", "edit", "apply_patch"]
+ }
+ }
+ ]
}
- ]
- }
-}
-```
-
----
-
-### Приклад 2b: глобальний профіль для кодування + агент лише для повідомлень
-
-```json
-{
- "tools": { "profile": "coding" },
- "agents": {
- "list": [
- {
- "id": "support",
- "tools": { "profile": "messaging", "allow": ["slack"] }
- }
- ]
- }
-}
-```
-
-**Результат:**
-
-- типові агенти отримують інструменти для кодування
-- агент `support` призначений лише для повідомлень (+ інструмент Slack)
-
----
-
-### Приклад 3: різні режими пісочниці для різних агентів
-
-```json
-{
- "agents": {
- "defaults": {
- "sandbox": {
- "mode": "non-main", // Глобальне значення за замовчуванням
- "scope": "session"
- }
- },
- "list": [
- {
- "id": "main",
- "workspace": "~/.openclaw/workspace",
- "sandbox": {
- "mode": "off" // Перевизначення: main ніколи не в пісочниці
- }
- },
- {
- "id": "public",
- "workspace": "~/.openclaw/workspace-public",
- "sandbox": {
- "mode": "all", // Перевизначення: public завжди в пісочниці
- "scope": "agent"
- },
- "tools": {
- "allow": ["read"],
- "deny": ["exec", "write", "edit", "apply_patch"]
- }
- }
- ]
- }
-}
-```
+ }
+ ```
+
+
---
## Пріоритетність конфігурації
-Коли існують і глобальні (`agents.defaults.*`), і агент-специфічні (`agents.list[].*`) конфігурації:
+Коли існують і глобальні (`agents.defaults.*`), і специфічні для агента (`agents.list[].*`) налаштування:
### Конфігурація пісочниці
-Налаштування окремого агента перевизначають глобальні:
+Налаштування агента мають пріоритет над глобальними:
```
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
@@ -190,194 +191,210 @@ agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
```
-**Примітки:**
-
-- `agents.list[].sandbox.{docker,browser,prune}.*` перевизначає `agents.defaults.sandbox.{docker,browser,prune}.*` для цього агента (ігнорується, коли область дії пісочниці зводиться до `"shared"`).
+
+`agents.list[].sandbox.{docker,browser,prune}.*` перевизначає `agents.defaults.sandbox.{docker,browser,prune}.*` для цього агента (ігнорується, коли область дії пісочниці зводиться до `"shared"`).
+
### Обмеження інструментів
Порядок фільтрації такий:
-1. **Профіль інструментів** (`tools.profile` або `agents.list[].tools.profile`)
-2. **Профіль інструментів провайдера** (`tools.byProvider[provider].profile` або `agents.list[].tools.byProvider[provider].profile`)
-3. **Глобальна політика інструментів** (`tools.allow` / `tools.deny`)
-4. **Політика інструментів провайдера** (`tools.byProvider[provider].allow/deny`)
-5. **Політика інструментів для окремого агента** (`agents.list[].tools.allow/deny`)
-6. **Політика провайдера для агента** (`agents.list[].tools.byProvider[provider].allow/deny`)
-7. **Політика інструментів пісочниці** (`tools.sandbox.tools` або `agents.list[].tools.sandbox.tools`)
-8. **Політика інструментів субагента** (`tools.subagents.tools`, якщо застосовується)
+
+
+ `tools.profile` або `agents.list[].tools.profile`.
+
+
+ `tools.byProvider[provider].profile` або `agents.list[].tools.byProvider[provider].profile`.
+
+
+ `tools.allow` / `tools.deny`.
+
+
+ `tools.byProvider[provider].allow/deny`.
+
+
+ `agents.list[].tools.allow/deny`.
+
+
+ `agents.list[].tools.byProvider[provider].allow/deny`.
+
+
+ `tools.sandbox.tools` або `agents.list[].tools.sandbox.tools`.
+
+
+ `tools.subagents.tools`, якщо застосовується.
+
+
-Кожен рівень може додатково обмежувати інструменти, але не може повернути інструменти, заборонені на попередніх рівнях.
-Якщо задано `agents.list[].tools.sandbox.tools`, воно замінює `tools.sandbox.tools` для цього агента.
-Якщо задано `agents.list[].tools.profile`, воно перевизначає `tools.profile` для цього агента.
-Ключі інструментів провайдера приймають або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`).
+
+
+ - Кожен рівень може додатково обмежувати інструменти, але не може повторно надати доступ до інструментів, заборонених на попередніх рівнях.
+ - Якщо встановлено `agents.list[].tools.sandbox.tools`, це замінює `tools.sandbox.tools` для цього агента.
+ - Якщо встановлено `agents.list[].tools.profile`, це перевизначає `tools.profile` для цього агента.
+ - Ключі інструментів провайдера можуть приймати або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`).
+
+
+ Якщо будь-який явний список дозволених інструментів у цьому ланцюжку призводить до того, що для запуску не залишається жодного викликаного інструмента, OpenClaw зупиняється до надсилання запиту моделі. Це зроблено навмисно: агент, налаштований із відсутнім інструментом, наприклад `agents.list[].tools.allow: ["query_db"]`, має завершуватися з явною помилкою, доки не буде увімкнено Plugin, який реєструє `query_db`, а не продовжувати працювати як текстовий агент.
+
+
-Якщо будь-який явний список дозволів у цьому ланцюжку призводить до того, що для запуску не лишається жодного викликного інструмента,
-OpenClaw зупиняється до надсилання запиту моделі. Це зроблено навмисно:
-агент, налаштований із відсутнім інструментом на кшталт
-`agents.list[].tools.allow: ["query_db"]`, має завершуватися з явною помилкою, доки не буде ввімкнено Plugin,
-який реєструє `query_db`, а не продовжувати працювати як агент лише з текстом.
+Політики інструментів підтримують скорочення `group:*`, які розгортаються в кілька інструментів. Повний список див. у [Групи інструментів](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands).
-Політики інструментів підтримують скорочення `group:*`, які розгортаються у кілька інструментів. Повний список див. у [Групи інструментів](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands).
-
-Перевизначення підвищеного режиму для окремого агента (`agents.list[].tools.elevated`) можуть додатково обмежувати підвищене виконання для конкретних агентів. Докладніше див. у [Підвищений режим](/uk/tools/elevated).
+Перевизначення elevated для окремих агентів (`agents.list[].tools.elevated`) можуть додатково обмежувати elevated exec для конкретних агентів. Докладніше див. у [Режим elevated](/uk/tools/elevated).
---
## Міграція з одного агента
-**До (один агент):**
-
-```json
-{
- "agents": {
- "defaults": {
- "workspace": "~/.openclaw/workspace",
- "sandbox": {
- "mode": "non-main"
- }
- }
- },
- "tools": {
- "sandbox": {
+
+
+ ```json
+ {
+ "agents": {
+ "defaults": {
+ "workspace": "~/.openclaw/workspace",
+ "sandbox": {
+ "mode": "non-main"
+ }
+ }
+ },
"tools": {
- "allow": ["read", "write", "apply_patch", "exec"],
- "deny": []
+ "sandbox": {
+ "tools": {
+ "allow": ["read", "write", "apply_patch", "exec"],
+ "deny": []
+ }
+ }
}
}
- }
-}
-```
-
-**Після (багато агентів із різними профілями):**
-
-```json
-{
- "agents": {
- "list": [
- {
- "id": "main",
- "default": true,
- "workspace": "~/.openclaw/workspace",
- "sandbox": { "mode": "off" }
+ ```
+
+
+ ```json
+ {
+ "agents": {
+ "list": [
+ {
+ "id": "main",
+ "default": true,
+ "workspace": "~/.openclaw/workspace",
+ "sandbox": { "mode": "off" }
+ }
+ ]
}
- ]
- }
-}
-```
+ }
+ ```
+
+
-Застарілі конфігурації `agent.*` мігруються командою `openclaw doctor`; надалі віддавайте перевагу `agents.defaults` + `agents.list`.
+
+Застарілі конфігурації `agent.*` мігруються через `openclaw doctor`; надалі віддавайте перевагу `agents.defaults` + `agents.list`.
+
---
-## Приклади обмеження інструментів
+## Приклади обмежень інструментів
-### Агент лише для читання
+
+
+ ```json
+ {
+ "tools": {
+ "allow": ["read"],
+ "deny": ["exec", "write", "edit", "apply_patch", "process"]
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "tools": {
+ "allow": ["read", "exec", "process"],
+ "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "tools": {
+ "sessions": { "visibility": "tree" },
+ "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
+ "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
+ }
+ }
+ ```
-```json
-{
- "tools": {
- "allow": ["read"],
- "deny": ["exec", "write", "edit", "apply_patch", "process"]
- }
-}
-```
+ `sessions_history` у цьому профілі все одно повертає обмежене, санітизоване подання для згадування, а не сирий дамп транскрипту. Згадування асистента прибирає thinking-теги, каркас ``, XML-пейлоади викликів інструментів у відкритому тексті (включно з `...`, `...`, `...`, `...` і усіченими блоками викликів інструментів), спрощений каркас викликів інструментів, витеклі ASCII/повноширинні токени керування моделлю та некоректний XML викликів інструментів MiniMax до редагування/усічення.
-### Агент для безпечного виконання (без змін файлів)
-
-```json
-{
- "tools": {
- "allow": ["read", "exec", "process"],
- "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
- }
-}
-```
-
-### Агент лише для комунікації
-
-```json
-{
- "tools": {
- "sessions": { "visibility": "tree" },
- "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
- "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
- }
-}
-```
-
-`sessions_history` у цьому профілі все одно повертає обмежене, очищене представлення згадування, а не сирий дамп транскрипту. Згадування помічника прибирає thinking-теги,
-каркас ``,
-простотекстові XML-пейлоади викликів інструментів
-(включно з `...`,
-`...`, `...`,
-`...`, а також обрізаними блоками викликів інструментів),
-понижений каркас викликів інструментів, витоки ASCII/повноширинних
-керувальних токенів моделі та некоректний MiniMax XML викликів інструментів перед редагуванням/обрізанням.
+
+
---
-## Поширена помилка: `"non-main"`
+## Поширена пастка: "non-main"
-`agents.defaults.sandbox.mode: "non-main"` базується на `session.mainKey` (типово `"main"`),
-а не на id агента. Сесії груп/каналів завжди отримують власні ключі, тому
-вони вважаються не-main і будуть запускатися в пісочниці. Якщо ви хочете, щоб агент ніколи не використовував пісочницю, встановіть `agents.list[].sandbox.mode: "off"`.
+
+`agents.defaults.sandbox.mode: "non-main"` ґрунтується на `session.mainKey` (типове значення `"main"`), а не на id агента. Сесії груп/каналів завжди отримують власні ключі, тому вважаються non-main і будуть ізольовані в пісочниці. Якщо ви хочете, щоб агент ніколи не використовував пісочницю, установіть `agents.list[].sandbox.mode: "off"`.
+
---
## Тестування
-Після налаштування пісочниці та інструментів для багатьох агентів:
+Після налаштування багатoагентної пісочниці та інструментів:
-1. **Перевірте визначення агента:**
-
- ```exec
- openclaw agents list --bindings
- ```
-
-2. **Переконайтеся в наявності контейнерів пісочниці:**
-
- ```exec
- docker ps --filter "name=openclaw-sbx-"
- ```
-
-3. **Перевірте обмеження інструментів:**
- - Надішліть повідомлення, яке потребує обмежених інструментів
- - Переконайтеся, що агент не може використовувати заборонені інструменти
-
-4. **Відстежуйте логи:**
-
- ```exec
- tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
- ```
+
+
+ ```bash
+ openclaw agents list --bindings
+ ```
+
+
+ ```bash
+ docker ps --filter "name=openclaw-sbx-"
+ ```
+
+
+ - Надішліть повідомлення, яке вимагає обмежених інструментів.
+ - Переконайтеся, що агент не може використовувати заборонені інструменти.
+
+
+ ```bash
+ tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
+ ```
+
+
---
## Усунення несправностей
-### Агент не запускається в пісочниці попри `mode: "all"`
-
-- Перевірте, чи немає глобального `agents.defaults.sandbox.mode`, яке це перевизначає
-- Конфігурація окремого агента має вищий пріоритет, тож встановіть `agents.list[].sandbox.mode: "all"`
-
-### Інструменти все ще доступні попри список заборон
-
-- Перевірте порядок фільтрації інструментів: глобальний → агент → пісочниця → субагент
-- Кожен рівень може лише додатково обмежувати, а не повертати дозволи
-- Перевірте в логах: `[tools] filtering tools for agent:${agentId}`
-
-### Контейнер не ізольований для кожного агента
-
-- Встановіть `scope: "agent"` в агент-специфічній конфігурації пісочниці
-- Типове значення — `"session"`, яке створює один контейнер на сесію
+
+
+ - Перевірте, чи немає глобального `agents.defaults.sandbox.mode`, яке це перевизначає.
+ - Конфігурація агента має пріоритет, тож установіть `agents.list[].sandbox.mode: "all"`.
+
+
+ - Перевірте порядок фільтрації інструментів: global → agent → sandbox → subagent.
+ - Кожен рівень може лише додатково обмежувати, а не повертати доступ.
+ - Перевірте через журнали: `[tools] filtering tools for agent:${agentId}`.
+
+
+ - Установіть `scope: "agent"` у конфігурації пісочниці для конкретного агента.
+ - Типове значення — `"session"`, яке створює один контейнер на сесію.
+
+
---
## Пов’язане
-- [Пісочниця](/uk/gateway/sandboxing) -- повний довідник щодо пісочниці (режими, області, бекенди, образи)
-- [Пісочниця vs політика інструментів vs підвищений режим](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження питання «чому це заблоковано?»
-- [Підвищений режим](/uk/tools/elevated)
-- [Маршрутизація багатьох агентів](/uk/concepts/multi-agent)
+- [Режим elevated](/uk/tools/elevated)
+- [Маршрутизація кількох агентів](/uk/concepts/multi-agent)
- [Конфігурація пісочниці](/uk/gateway/config-agents#agentsdefaultssandbox)
+- [Пісочниця vs політика інструментів vs elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — налагодження «чому це заблоковано?»
+- [Пісочниця](/uk/gateway/sandboxing) — повний довідник із пісочниці (режими, області дії, бекенди, образи)
- [Керування сесіями](/uk/concepts/session)