diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index 6af66b724..8702b9c9d 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -1,24 +1,24 @@ --- read_when: - Робота над функціями каналу Discord -summary: Стан підтримки бота Discord, можливості та конфігурація +summary: Стан підтримки, можливості та конфігурація бота Discord title: Discord x-i18n: - generated_at: "2026-05-02T06:09:33Z" + generated_at: "2026-05-02T09:29:18Z" model: gpt-5.5 provider: openai - source_hash: f5526523b55dc2c861206eaf6b016c025da33bc5c47d196ba7aed6fb4c3e6595 + source_hash: 42223982a8bfd288d29a1f402b37141557718a407537011956b878b91b894e62 source_path: channels/discord.md workflow: 16 --- -Готово для особистих повідомлень і каналів гільдії через офіційний Discord Gateway. +Готово для особистих повідомлень і каналів гільдій через офіційний Discord Gateway. Особисті повідомлення Discord за замовчуванням працюють у режимі спарювання. - + Нативна поведінка команд і каталог команд. @@ -28,27 +28,27 @@ x-i18n: ## Швидке налаштування -Вам потрібно створити нову програму з ботом, додати бота на свій сервер і спарувати його з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спершу створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). +Вам потрібно створити нову програму з ботом, додати бота на свій сервер і спарувати його з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спочатку створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). - Перейдіть до [Discord Developer Portal](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть її на кшталт "OpenClaw". + Перейдіть до [Discord Developer Portal](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть її, наприклад, "OpenClaw". - Натисніть **Bot** на бічній панелі. Установіть **Username** на те, як ви називаєте свого агента OpenClaw. + Натисніть **Bot** на бічній панелі. Установіть **Username** на ім’я, яким ви називаєте свого агента OpenClaw. - - Залишаючись на сторінці **Bot**, прокрутіть униз до **Privileged Gateway Intents** і ввімкніть: + + Залишаючись на сторінці **Bot**, прокрутіть вниз до **Privileged Gateway Intents** і ввімкніть: - **Message Content Intent** (обов’язково) - - **Server Members Intent** (рекомендовано; потрібно для списків дозволених ролей і зіставлення імен з ID) + - **Server Members Intent** (рекомендовано; обов’язково для списків дозволених ролей і зіставлення імен з ID) - **Presence Intent** (необов’язково; потрібно лише для оновлень присутності) - Прокрутіть угору на сторінці **Bot** і натисніть **Reset Token**. + Прокрутіть назад угору на сторінці **Bot** і натисніть **Reset Token**. Попри назву, це створює ваш перший токен — нічого не "скидається". @@ -61,7 +61,7 @@ x-i18n: Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з потрібними дозволами, щоб додати бота на свій сервер. - Прокрутіть униз до **OAuth2 URL Generator** і ввімкніть: + Прокрутіть вниз до **OAuth2 URL Generator** і ввімкніть: - `bot` - `applications.commands` @@ -77,8 +77,8 @@ x-i18n: - Attach Files - Add Reactions (необов’язково) - Це базовий набір для звичайних текстових каналів. Якщо ви плануєте писати в треди Discord, зокрема у робочих процесах форумних або медіаканалів, які створюють чи продовжують тред, також увімкніть **Send Messages in Threads**. - Скопіюйте згенерований URL унизу, вставте його в браузер, виберіть свій сервер і натисніть **Continue**, щоб під’єднати. Тепер ви маєте бачити свого бота на сервері Discord. + Це базовий набір для звичайних текстових каналів. Якщо ви плануєте писати в тредах Discord, зокрема у сценаріях форумів або медіаканалів, які створюють або продовжують тред, також увімкніть **Send Messages in Threads**. + Скопіюйте згенерований URL унизу, вставте його в браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте бачити свого бота на сервері Discord. @@ -86,15 +86,15 @@ x-i18n: Повернувшись у програму Discord, потрібно ввімкнути Developer Mode, щоб копіювати внутрішні ID. 1. Натисніть **User Settings** (іконка шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** - 2. Клацніть правою кнопкою вашу **іконку сервера** на бічній панелі → **Copy Server ID** - 3. Клацніть правою кнопкою ваш **власний аватар** → **Copy User ID** + 2. Клацніть правою кнопкою миші **іконку сервера** на бічній панелі → **Copy Server ID** + 3. Клацніть правою кнопкою миші **власний аватар** → **Copy User ID** - Збережіть ваші **Server ID** і **User ID** поруч із Bot Token — на наступному кроці ви надішлете всі три до OpenClaw. + Збережіть свої **Server ID** і **User ID** поруч із Bot Token — на наступному кроці ви надішлете всі три до OpenClaw. - Щоб спарювання працювало, Discord має дозволити вашому боту надсилати вам особисті повідомлення. Клацніть правою кнопкою вашу **іконку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. + Щоб спарювання працювало, Discord має дозволити вашому боту надсилати вам особисті повідомлення. Клацніть правою кнопкою миші **іконку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. Це дозволяє учасникам сервера (зокрема ботам) надсилати вам особисті повідомлення. Залиште це ввімкненим, якщо хочете використовувати особисті повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, можете вимкнути особисті повідомлення після спарювання. @@ -120,9 +120,9 @@ openclaw config patch --file ./discord.patch.json5 openclaw gateway ``` - Якщо OpenClaw уже працює як фонова служба, перезапустіть його через програму OpenClaw для Mac або зупинивши й повторно запустивши процес `openclaw gateway run`. - Для встановлень керованої служби запустіть `openclaw gateway install` з оболонки, де присутній `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб служба могла розв’язати env SecretRef після перезапуску. - Якщо ваш хост заблоковано або обмежено за частотою запитів під час стартового пошуку програми Discord, задайте ID програми/клієнта Discord із Developer Portal, щоб запуск міг пропустити цей REST-виклик. Використовуйте `channels.discord.applicationId` для облікового запису за замовчуванням або `channels.discord.accounts..applicationId`, коли запускаєте кількох ботів Discord. + Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через програму OpenClaw для Mac або зупинивши й повторно запустивши процес `openclaw gateway run`. + Для встановлень як керованого сервісу запустіть `openclaw gateway install` з shell, де присутній `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб сервіс міг розв’язати env SecretRef після перезапуску. + Якщо ваш хост заблокований або обмежений за частотою запитів під час стартового пошуку програми Discord, задайте ID програми/клієнта Discord з Developer Portal, щоб запуск міг пропустити цей REST-виклик. Використовуйте `channels.discord.applicationId` для типового облікового запису або `channels.discord.accounts..applicationId`, коли запускаєте кількох ботів Discord. @@ -130,12 +130,12 @@ openclaw gateway - Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому це. Якщо Discord — ваш перший канал, скористайтеся вкладкою CLI / config. + Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому. Якщо Discord є вашим першим каналом, натомість скористайтеся вкладкою CLI / config. - > "Я вже задав токен свого бота Discord у конфігурації. Будь ласка, заверши налаштування Discord з User ID `` і Server ID ``." + > "I already set my Discord bot token in config. Please finish Discord setup with User ID `` and Server ID ``." - Якщо ви віддаєте перевагу файловій конфігурації, задайте: + Якщо ви надаєте перевагу файловій конфігурації, задайте: ```json5 { @@ -152,15 +152,15 @@ openclaw gateway } ``` - Резервний env-варіант для облікового запису за замовчуванням: + Env fallback для типового облікового запису: ```bash DISCORD_BOT_TOKEN=... ``` - Для скриптового або віддаленого налаштування запишіть той самий блок JSON5 за допомогою `openclaw config patch --file ./discord.patch.json5 --dry-run`, а потім повторіть запуск без `--dry-run`. Значення `token` у відкритому тексті підтримуються. Значення SecretRef також підтримуються для `channels.discord.token` через постачальників env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Для сценарного або віддаленого налаштування запишіть той самий блок JSON5 за допомогою `openclaw config patch --file ./discord.patch.json5 --dry-run`, а потім повторно запустіть без `--dry-run`. Значення `token` у відкритому тексті підтримуються. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). - Для кількох ботів Discord зберігайте токен і ID програми кожного бота в його обліковому записі. `channels.discord.applicationId` верхнього рівня успадковується обліковими записами, тому задавайте його там лише тоді, коли кожен обліковий запис має використовувати той самий ID програми. + Для кількох ботів Discord тримайте токен і ID програми кожного бота в його обліковому записі. Верхньорівневий `channels.discord.applicationId` успадковується обліковими записами, тому задавайте його там лише тоді, коли кожен обліковий запис має використовувати той самий ID програми. ```json5 { @@ -187,14 +187,14 @@ DISCORD_BOT_TOKEN=... - - Зачекайте, доки Gateway запуститься, а потім напишіть своєму боту в Discord в особисті повідомлення. Він відповість кодом спарювання. + + Дочекайтеся, доки Gateway запрацює, а потім напишіть своєму боту в особисті повідомлення Discord. Він відповість кодом спарювання. - Надішліть код спарювання своєму агенту в наявному каналі: + Надішліть код спарювання своєму агенту у вашому наявному каналі: - > "Схвали цей код спарювання Discord: ``" + > "Approve this Discord pairing code: ``" @@ -214,9 +214,9 @@ openclaw pairing approve discord -Розв’язання токена враховує обліковий запис. Значення токена в конфігурації мають пріоритет над резервним env-варіантом. `DISCORD_BOT_TOKEN` використовується лише для облікового запису за замовчуванням. -Якщо два ввімкнені облікові записи Discord розв’язуються до того самого токена бота, OpenClaw запускає лише один монітор Gateway для цього токена. Токен із конфігурації має пріоритет над резервним env-варіантом за замовчуванням; інакше перемагає перший увімкнений обліковий запис, а дубльований обліковий запис позначається як вимкнений. -Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` для кожного виклику використовується для цього виклику. Це застосовується до дій надсилання та читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису та налаштування повторів усе ще беруться з вибраного облікового запису в активному знімку runtime. +Розв’язання токенів враховує обліковий запис. Значення токена в конфігурації мають пріоритет над env fallback. `DISCORD_BOT_TOKEN` використовується лише для типового облікового запису. +Якщо два ввімкнені облікові записи Discord розв’язуються в той самий токен бота, OpenClaw запускає лише один монітор Gateway для цього токена. Токен із конфігурації має пріоритет над типовим env fallback; інакше перемагає перший увімкнений обліковий запис, а дубльований обліковий запис повідомляється як вимкнений. +Для розширених вихідних викликів (дії інструмента повідомлень/каналу) явний `token` для кожного виклику використовується для цього виклику. Це стосується дій надсилання та дій стилю читання/перевірки (наприклад read/search/fetch/thread/pins/permissions). Політика облікового запису та налаштування повторних спроб усе ще беруться з вибраного облікового запису в активному runtime-знімку. ## Рекомендовано: налаштуйте робочий простір гільдії @@ -225,11 +225,11 @@ openclaw pairing approve discord - Це дає змогу вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в особистих повідомленнях. + Це дає вашому агенту змогу відповідати в будь-якому каналі на вашому сервері, а не лише в особистих повідомленнях. - > "Додай мій Discord Server ID `` до списку дозволених гільдій" + > "Add my Discord Server ID `` to the guild allowlist" @@ -254,14 +254,14 @@ openclaw pairing approve discord - - За замовчуванням ваш агент відповідає в каналах гільдії лише коли його @згадують. Для приватного сервера ви, ймовірно, хочете, щоб він відповідав на кожне повідомлення. + + За замовчуванням ваш агент відповідає в каналах гільдії лише коли його @mentioned. Для приватного сервера ви, ймовірно, хочете, щоб він відповідав на кожне повідомлення. - У каналах гільдії звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід Discord потрібно явно надсилати за допомогою інструмента `message`, тож агент може за замовчуванням спостерігати й публікувати лише тоді, коли вирішить, що відповідь у каналі корисна. + У каналах гільдії звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід Discord потрібно надсилати явно за допомогою інструмента `message`, щоб агент міг за замовчуванням лишатися непомітним і писати лише тоді, коли вирішить, що відповідь у каналі корисна. - > "Дозволь моєму агенту відповідати на цьому сервері без потреби бути @згаданим" + > "Allow my agent to respond on this server without having to be @mentioned" Задайте `requireMention: false` у конфігурації гільдії: @@ -288,14 +288,14 @@ openclaw pairing approve discord - За замовчуванням довгострокова пам’ять (MEMORY.md) завантажується лише в сесіях особистих повідомлень. Канали гільдії не завантажують MEMORY.md автоматично. + За замовчуванням довготривала пам’ять (MEMORY.md) завантажується лише в сесіях особистих повідомлень. Канали гільдії не завантажують MEMORY.md автоматично. - > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо тобі потрібен довгостроковий контекст із MEMORY.md." + > "When I ask questions in Discord channels, use memory_search or memory_get if you need long-term context from MEMORY.md." - Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони впроваджуються в кожну сесію). Зберігайте довгострокові нотатки в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам’яті. + Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони ін’єктуються в кожну сесію). Тримайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них за потреби через інструменти пам’яті. @@ -304,48 +304,48 @@ openclaw pairing approve discord Тепер створіть кілька каналів на своєму сервері Discord і починайте спілкуватися. Ваш агент може бачити назву каналу, і кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що пасує вашому робочому процесу. -## Runtime-модель +## Модель виконання -- Gateway відповідає за з’єднання з Discord. -- Маршрутизація відповідей детермінована: вхідні відповіді з Discord повертаються в Discord. -- Метадані гільдії/каналу Discord додаються до підказки моделі як недовірений - контекст, а не як видимий користувачу префікс відповіді. Якщо модель скопіює цю обгортку - назад, OpenClaw видаляє скопійовані метадані з вихідних відповідей і з +- Gateway володіє з’єднанням Discord. +- Маршрутизація відповідей детермінована: вхідні відповіді Discord повертаються до Discord. +- Метадані guild/каналу Discord додаються до запиту моделі як недовірений + контекст, а не як видимий користувачеві префікс відповіді. Якщо модель скопіює цей конверт + назад, OpenClaw вилучить скопійовані метадані з вихідних відповідей і з майбутнього контексту відтворення. -- За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують основну сесію агента (`agent:main:main`). -- Канали гільдій ізольовані ключами сесій (`agent::discord:channel:`). -- Групові DM за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). -- Нативні слеш-команди виконуються в ізольованих командних сесіях (`agent::discord:slash:`), водночас усе ще передаючи `CommandTargetSessionKey` до маршрутизованої сесії розмови. -- Доставлення текстових оголошень Cron/Heartbeat у Discord використовує остаточну - видиму асистенту відповідь один раз. Медіа та структуровані payload компонентів залишаються - багатоповідомленнєвими, коли агент випускає кілька payload, придатних до доставлення. +- За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують головну сесію агента (`agent:main:main`). +- Канали guild ізольовані ключами сесій (`agent::discord:channel:`). +- Group DM за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). +- Нативні slash-команди виконуються в ізольованих командних сесіях (`agent::discord:slash:`), водночас передаючи `CommandTargetSessionKey` до маршрутизованої сесії розмови. +- Доставка текстових оголошень cron/heartbeat до Discord використовує остаточну + видиму для асистента відповідь один раз. Медіа та структуровані payload компонентів залишаються + багатоповідомленнєвими, коли агент емiтує кілька deliverable payloads. -## Форумні канали +## Forum-канали -Форумні та медіаканали Discord приймають лише дописи в гілках. OpenClaw підтримує два способи їх створення: +Forum-канали та медіаканали Discord приймають лише дописи в thread. OpenClaw підтримує два способи їх створення: -- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити гілку. Назва гілки використовує перший непорожній рядок вашого повідомлення. -- Використайте `openclaw message thread create`, щоб створити гілку напряму. Не передавайте `--message-id` для форумних каналів. +- Надішліть повідомлення до батьківського forum (`channel:`), щоб автоматично створити thread. Назва thread використовує перший непорожній рядок вашого повідомлення. +- Використайте `openclaw message thread create`, щоб створити thread напряму. Не передавайте `--message-id` для forum-каналів. -Приклад: надіслати до батьківського форуму, щоб створити гілку +Приклад: надіслати до батьківського forum, щоб створити thread ```bash openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -Приклад: явно створити форумну гілку +Приклад: явно створити forum thread ```bash openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Батьківські форуми не приймають компоненти Discord. Якщо вам потрібні компоненти, надсилайте до самої гілки (`channel:`). +Батьківські forum не приймають компоненти Discord. Якщо вам потрібні компоненти, надсилайте до самого thread (`channel:`). ## Інтерактивні компоненти -OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення й дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери Discord components v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. Підтримувані блоки: @@ -353,21 +353,21 @@ OpenClaw підтримує контейнери компонентів Discord - Рядки дій дозволяють до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, виборів і форм, доки вони не завершать дію. +За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, списків вибору та форм до завершення їхнього строку дії. -Щоб обмежити, хто може натискати кнопку, задайте `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, користувачі без збігу отримують ефемерну відмову. +Щоб обмежити, хто може натиснути кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, користувачі без збігу отримують ефемерну відмову. -Слеш-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору є ефемерною, і користуватися нею може лише користувач, який її викликав. +Slash-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору є ефемерною, і використовувати її може лише користувач, який її викликав. -Файлові вкладення: +Вкладення файлів: -- Блоки `file` мають посилатися на reference вкладення (`attachment://`) +- Блоки `file` мають вказувати на посилання вкладення (`attachment://`) - Надайте вкладення через `media`/`path`/`filePath` (один файл); використовуйте `media-gallery` для кількох файлів -- Використовуйте `filename`, щоб перевизначити ім’я завантаження, коли воно має збігатися з reference вкладення +- Використовуйте `filename`, щоб перевизначити назву завантаження, коли вона має відповідати посиланню вкладення Модальні форми: -- Додайте `components.modal` з до 5 полями +- Додайте `components.modal` із до 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` - OpenClaw автоматично додає кнопку запуску @@ -429,37 +429,37 @@ OpenClaw підтримує контейнери компонентів Discord - `channels.discord.dmPolicy` керує доступом до DM. `channels.discord.allowFrom` є канонічним allowlist для DM. + `channels.discord.dmPolicy` керує доступом DM. `channels.discord.allowFrom` є канонічним allowlist для DM. - `pairing` (за замовчуванням) - `allowlist` - `open` (потребує, щоб `channels.discord.allowFrom` містив `"*"`) - `disabled` - Якщо політика DM не відкрита, невідомих користувачів блокують (або пропонують pairing у режимі `pairing`). + Якщо політика DM не є відкритою, невідомі користувачі блокуються (або отримують запит на pairing у режимі `pairing`). - Пріоритетність кількох акаунтів: + Пріоритет для кількох облікових записів: - - `channels.discord.accounts.default.allowFrom` застосовується лише до акаунта `default`. - - Для одного акаунта `allowFrom` має пріоритет над застарілим `dm.allowFrom`. - - Іменовані акаунти успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не задані. - - Іменовані акаунти не успадковують `channels.discord.accounts.default.allowFrom`. + - `channels.discord.accounts.default.allowFrom` застосовується лише до облікового запису `default`. + - Для одного облікового запису `allowFrom` має пріоритет над застарілим `dm.allowFrom`. + - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не задані. + - Іменовані облікові записи не успадковують `channels.discord.accounts.default.allowFrom`. - Застарілі `channels.discord.dm.policy` і `channels.discord.dm.allowFrom` все ще зчитуються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. + Застарілі `channels.discord.dm.policy` і `channels.discord.dm.allowFrom` усе ще зчитуються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли це можна зробити без зміни доступу. - Формат цілі DM для доставлення: + Формат цілі DM для доставки: - `user:` - згадка `<@id>` - Голі числові ID зазвичай розпізнаються як ID каналів, коли активний типовий канал, але ID, перелічені в ефективному DM `allowFrom` акаунта, для сумісності трактуються як цілі користувацьких DM. + Голі числові ID зазвичай розв’язуються як ID каналів, коли активний стандартний канал, але ID, перелічені в ефективному DM `allowFrom` облікового запису, для сумісності трактуються як цілі user DM. DM Discord можуть використовувати динамічні записи `accessGroup:` у `channels.discord.allowFrom`. - Імена груп доступу спільні для каналів повідомлень. Використовуйте `type: "message.senders"` для статичної групи, учасники якої виражаються звичайним синтаксисом `allowFrom` кожного каналу, або `type: "discord.channelAudience"`, коли поточна аудиторія `ViewChannel` каналу Discord має динамічно визначати членство. Поведінка спільних груп доступу задокументована тут: [Групи доступу](/uk/channels/access-groups). + Імена груп доступу спільні для каналів повідомлень. Використовуйте `type: "message.senders"` для статичної групи, учасники якої виражені у звичайному синтаксисі `allowFrom` кожного каналу, або `type: "discord.channelAudience"`, коли поточна аудиторія `ViewChannel` каналу Discord має динамічно визначати членство. Спільну поведінку груп доступу задокументовано тут: [Групи доступу](/uk/channels/access-groups). ```json5 { @@ -482,9 +482,9 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Текстовий канал Discord не має окремого списку учасників. `type: "discord.channelAudience"` моделює членство так: відправник DM є учасником налаштованої гільдії та наразі має ефективний дозвіл `ViewChannel` на налаштованому каналі після застосування ролей і перевизначень каналу. + Текстовий канал Discord не має окремого списку учасників. `type: "discord.channelAudience"` моделює членство так: відправник DM є учасником налаштованої guild і наразі має ефективний дозвіл `ViewChannel` на налаштованому каналі після застосування ролей і перевизначень каналу. - Приклад: дозволити всім, хто бачить `#maintainers`, писати боту в DM, водночас залишаючи DM закритими для всіх інших. + Приклад: дозволити будь-кому, хто бачить `#maintainers`, надсилати DM боту, водночас залишаючи DM закритими для всіх інших. ```json5 { @@ -505,7 +505,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Ви можете змішувати динамічні та статичні записи: + Можна змішувати динамічні та статичні записи: ```json5 { @@ -525,29 +525,29 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Пошуки завершуються закрито. Якщо Discord повертає `Missing Access`, пошук учасника зазнає невдачі або канал належить іншій гільдії, відправник DM вважається неавторизованим. + Пошуки закривають доступ у разі помилки. Якщо Discord повертає `Missing Access`, пошук учасника завершується невдало або канал належить іншій guild, відправник DM вважається неавторизованим. - Увімкніть **Server Members Intent** у Discord Developer Portal для бота, коли використовуєте групи доступу на основі аудиторії каналу. DM не містять стану учасника гільдії, тому OpenClaw розв’язує учасника через Discord REST під час авторизації. + Увімкніть **Server Members Intent** у Discord Developer Portal для бота, коли використовуєте групи доступу на основі аудиторії каналу. DM не містять стану учасника guild, тому OpenClaw розв’язує учасника через Discord REST під час авторизації. - Обробкою гільдій керує `channels.discord.groupPolicy`: + Обробка guild керується `channels.discord.groupPolicy`: - `open` - `allowlist` - `disabled` - Безпечна базова лінія, коли існує `channels.discord`, — `allowlist`. + Безпечна базова конфігурація, коли `channels.discord` існує, — це `allowlist`. Поведінка `allowlist`: - - гільдія має збігатися з `channels.discord.guilds` (переважно `id`, slug приймається) - - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправників дозволено, коли вони збігаються з `users` АБО `roles` - - прямий збіг за іменем/тегом за замовчуванням вимкнено; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як режим сумісності break-glass + - guild має відповідати `channels.discord.guilds` (переважно `id`, slug приймається) + - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволені, коли вони збігаються з `users` АБО `roles` + - прямий збіг імен/тегів вимкнено за замовчуванням; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності - імена/теги підтримуються для `users`, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи імен/тегів - - якщо гільдія має налаштовані `channels`, канали поза списком заборонені - - якщо гільдія не має блока `channels`, дозволені всі канали в цій allowlisted гільдії + - якщо guild має налаштовані `channels`, канали поза списком відхиляються + - якщо guild не має блока `channels`, дозволені всі канали в цій allowlisted guild Приклад: @@ -573,23 +573,25 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Якщо ви задаєте лише `DISCORD_BOT_TOKEN` і не створюєте блок `channels.discord`, runtime fallback — `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` дорівнює `open`. + Якщо ви лише встановили `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, runtime fallback — `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` дорівнює `open`. - Повідомлення гільдій за замовчуванням пропускаються через перевірку згадки. + Повідомлення guild за замовчуванням проходять через перевірку згадки. - Виявлення згадки включає: + Виявлення згадок включає: - явну згадку бота - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - - неявну поведінку відповіді боту в підтримуваних випадках + - неявну поведінку reply-to-bot у підтримуваних випадках - `requireMention` налаштовується для кожної гільдії/каналу (`channels.discord.guilds...`). - `ignoreOtherMentions` необов’язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). + Під час написання вихідних повідомлень Discord використовуйте канонічний синтаксис згадок: `<@USER_ID>` для користувачів, `<#CHANNEL_ID>` для каналів і `<@&ROLE_ID>` для ролей. Не використовуйте застарілу форму згадки nickname `<@!USER_ID>`. - Групові DM: + `requireMention` налаштовується для кожної guild/каналу (`channels.discord.guilds...`). + `ignoreOtherMentions` необов’язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (крім @everyone/@here). + + Group DM: - за замовчуванням: ігноруються (`dm.groupEnabled=false`) - необов’язковий allowlist через `dm.groupChannels` (ID каналів або slugs) @@ -599,7 +601,7 @@ OpenClaw підтримує контейнери компонентів Discord ### Маршрутизація агентів на основі ролей -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і оцінюються після прив’язок peer або parent-peer та перед прив’язками лише гільдії. Якщо прив’язка також задає інші поля збігу (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників guild Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і оцінюються після прив’язок peer або parent-peer та перед прив’язками лише guild. Якщо прив’язка також задає інші поля match (наприклад `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. ```json5 { @@ -623,25 +625,25 @@ OpenClaw підтримує контейнери компонентів Discord } ``` -## Нативні команди та автентифікація команд +## Нативні команди та авторизація команд -- `commands.native` за замовчуванням дорівнює `"auto"` і ввімкнено для Discord. +- `commands.native` за замовчуванням має значення `"auto"` і ввімкнено для Discord. - Перевизначення для окремого каналу: `channels.discord.commands.native`. - `commands.native=false` явно очищає раніше зареєстровані нативні команди Discord. -- Автентифікація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. -- Команди все ще можуть бути видимими в UI Discord для користувачів, які не авторизовані; виконання все одно застосовує автентифікацію OpenClaw і повертає "not authorized". +- Автентифікація нативних команд використовує ті самі списки дозволених користувачів і політики Discord, що й звичайна обробка повідомлень. +- Команди все ще можуть бути видимими в UI Discord для користувачів без авторизації; виконання все одно застосовує автентифікацію OpenClaw і повертає "not authorized". -Див. [Слеш-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. +Див. [слеш-команди](/uk/tools/slash-commands), щоб переглянути каталог команд і їхню поведінку. -Налаштування слеш-команд за замовчуванням: +Стандартні налаштування слеш-команд: - `ephemeral: true` -## Деталі функцій +## Деталі функції - - Discord підтримує теги відповідей у виводі агента: + + Discord підтримує теги відповіді у виводі агента: - `[[reply_to_current]]` - `[[reply_to:]]` @@ -653,21 +655,21 @@ OpenClaw підтримує контейнери компонентів Discord - `all` - `batched` - Примітка: `off` вимикає неявне створення ланцюжків відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord у цьому ході. + Примітка: `off` вимикає неявне створення гілок відповідей. Явні теги `[[reply_to_*]]` все одно враховуються. + `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord за хід. `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли - вхідний хід був дебаунсованою групою з кількох повідомлень. Це корисно, - коли нативні відповіді потрібні переважно для неоднозначних активних чатів, - а не для кожного ходу з одним повідомленням. + вхідний хід був відкладеною групою з кількох повідомлень. Це корисно, + коли потрібні нативні відповіді переважно для неоднозначних активних чатів, а не для кожного + ходу з одним повідомленням. - ID повідомлень доступні в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. + ID повідомлень відображаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. - + OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення й редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` зіставляється з `partial` у Discord; `streamMode` є застарілим псевдонімом і мігрується автоматично. - За замовчуванням лишається `off`, бо редагування попереднього перегляду Discord швидко впирається в обмеження частоти, коли кілька ботів або Gateway використовують один обліковий запис. + За замовчуванням лишається `off`, оскільки редагування попереднього перегляду Discord швидко впираються в обмеження частоти, коли кілька ботів або Gateway використовують один обліковий запис. ```json5 { @@ -685,15 +687,15 @@ OpenClaw підтримує контейнери компонентів Discord ``` - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` випускає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву; обмежується `textChunkLimit`). - - Медіа, помилки та фінальні відповіді з явною відповіддю скасовують очікувані редагування попереднього перегляду. - - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. + - `block` надсилає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). + - Медіа, помилки й фінальні повідомлення з явною відповіддю скасовують очікувані редагування попереднього перегляду. + - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи повторно використовують оновлення інструментів/прогресу повідомлення попереднього перегляду. - Потоковий попередній перегляд працює лише з текстом; відповіді з медіа повертаються до звичайної доставки. Коли потокове передавання `block` явно ввімкнене, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Трансляція попереднього перегляду підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли трансляцію `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної трансляції. - + Контекст історії гільдії: - `channels.discord.historyLimit` за замовчуванням `20` @@ -705,28 +707,28 @@ OpenClaw підтримує контейнери компонентів Discord - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` - Поведінка потоків: + Поведінка гілок: - - Потоки Discord маршрутизуються як сеанси каналів і успадковують конфігурацію батьківського каналу, якщо її не перевизначено. - - Сеанси потоків успадковують вибір `/model` на рівні сеансу батьківського каналу як резерв лише для моделі; локальні для потоку вибори `/model` усе одно мають пріоритет, а історія транскрипту батьківського каналу не копіюється, якщо не ввімкнено успадкування транскрипту. - - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових автоматичних потоків початкове наповнення з батьківського транскрипту. Перевизначення для окремих облікових записів розміщені в `channels.discord.accounts..thread.inheritParent`. - - Реакції інструменту повідомлень можуть розпізнавати DM-цілі `user:`. + - Гілки Discord маршрутизуються як сесії каналів і успадковують конфігурацію батьківського каналу, якщо її не перевизначено. + - Сесії гілок успадковують вибір `/model` на рівні сесії батьківського каналу як резервне значення лише для моделі; локальні для гілки вибори `/model` все одно мають пріоритет, а історія транскрипта батьківського каналу не копіюється, якщо успадкування транскрипта не ввімкнено. + - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових автоматичних гілок початкове заповнення з батьківського транскрипта. Перевизначення для окремих облікових записів розташовані в `channels.discord.accounts..thread.inheritParent`. + - Реакції інструмента повідомлень можуть розв’язувати цілі DM `user:`. - `guilds..channels..requireMention: false` зберігається під час резервної активації на етапі відповіді. - Теми каналів вставляються як **ненадійний** контекст. Списки дозволених визначають, хто може запускати агента, а не є повною межею редагування додаткового контексту. + Теми каналів вставляються як **ненадійний** контекст. Списки дозволених користувачів контролюють, хто може запускати агента, але не є повною межею редагування додаткового контексту. - - Discord може прив'язати потік до цілі сеансу, щоб подальші повідомлення в цьому потоці продовжували маршрутизуватися до того самого сеансу (зокрема сеансів субагентів). + + Discord може прив’язати гілку до цілі сесії, щоб подальші повідомлення в цій гілці продовжували маршрутизуватися до тієї самої сесії (зокрема сесій субагентів). Команди: - - `/focus ` прив'язати поточний/новий потік до цілі субагента/сеансу - - `/unfocus` видалити прив'язку поточного потоку - - `/agents` показати активні запуски та стан прив'язки - - `/session idle ` переглянути/оновити автоматичне скасування фокуса через неактивність для сфокусованих прив'язок - - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив'язок + - `/focus ` прив’язати поточну/нову гілку до цілі субагента/сесії + - `/unfocus` видалити прив’язку поточної гілки + - `/agents` показати активні запуски та стан прив’язки + - `/session idle ` переглянути/оновити автоматичне зняття фокуса через неактивність для сфокусованих прив’язок + - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив’язок Конфігурація: @@ -757,17 +759,17 @@ OpenClaw підтримує контейнери компонентів Discord - `session.threadBindings.*` задає глобальні значення за замовчуванням. - `channels.discord.threadBindings.*` перевизначає поведінку Discord. - - `spawnSessions` керує автоматичним створенням/прив'язкою потоків для `sessions_spawn({ thread: true })` і породжень потоків ACP. За замовчуванням: `true`. - - `defaultSpawnContext` керує нативним контекстом субагента для породжень, прив'язаних до потоку. За замовчуванням: `"fork"`. - - Застарілі ключі `spawnSubagentSessions`/`spawnAcpSessions` мігруються через `openclaw doctor --fix`. - - Якщо прив'язки потоків вимкнені для облікового запису, `/focus` і пов'язані операції прив'язки потоків недоступні. + - `spawnSessions` керує автоматичним створенням/прив’язуванням гілок для `sessions_spawn({ thread: true })` і створенням гілок ACP. За замовчуванням: `true`. + - `defaultSpawnContext` керує нативним контекстом субагента для створень, прив’язаних до гілок. За замовчуванням: `"fork"`. + - Застарілі ключі `spawnSubagentSessions`/`spawnAcpSessions` мігруються командою `openclaw doctor --fix`. + - Якщо прив’язки гілок вимкнено для облікового запису, `/focus` і пов’язані операції прив’язування гілок недоступні. - Див. [Субагенти](/uk/tools/subagents), [Агенти ACP](/uk/tools/acp-agents) і [Довідник конфігурації](/uk/gateway/configuration-reference). + Див. [субагенти](/uk/tools/subagents), [агенти ACP](/uk/tools/acp-agents) і [довідник із конфігурації](/uk/gateway/configuration-reference). - - Для стабільних "завжди ввімкнених" робочих просторів ACP налаштуйте типізовані прив'язки ACP верхнього рівня, націлені на розмови Discord. + + Для стабільних "always-on" робочих просторів ACP налаштуйте типізовані прив’язки ACP верхнього рівня, націлені на розмови Discord. Шлях конфігурації: @@ -823,11 +825,11 @@ OpenClaw підтримує контейнери компонентів Discord Примітки: - - `/acp spawn codex --bind here` прив'язує поточний канал або потік на місці й зберігає майбутні повідомлення в тому самому сеансі ACP. Повідомлення потоків успадковують прив'язку батьківського каналу. - - У прив'язаному каналі або потоці `/new` і `/reset` скидають той самий сеанс ACP на місці. Тимчасові прив'язки потоків можуть перевизначати розпізнавання цілі, доки активні. - - `spawnSessions` обмежує створення/прив'язку дочірніх потоків через `--thread auto|here`. + - `/acp spawn codex --bind here` прив’язує поточний канал або гілку на місці й лишає майбутні повідомлення в тій самій сесії ACP. Повідомлення гілки успадковують прив’язку батьківського каналу. + - У прив’язаному каналі або гілці `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив’язки гілок можуть перевизначати розв’язання цілі, поки активні. + - `spawnSessions` контролює створення/прив’язування дочірніх гілок через `--thread auto|here`. - Див. [Агенти ACP](/uk/tools/acp-agents), щоб дізнатися подробиці поведінки прив'язок. + Див. [агенти ACP](/uk/tools/acp-agents), щоб дізнатися більше про поведінку прив’язування. @@ -839,14 +841,14 @@ OpenClaw підтримує контейнери компонентів Discord - `all` - `allowlist` (використовує `guilds..users`) - Події реакцій перетворюються на системні події та додаються до маршрутизованого сеансу Discord. + Події реакцій перетворюються на системні події та додаються до маршрутизованої сесії Discord. - + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. - Порядок розпізнавання: + Порядок розв’язання: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` @@ -855,15 +857,15 @@ OpenClaw підтримує контейнери компонентів Discord Примітки: - - Discord приймає Unicode-емодзі або назви власних емодзі. + - Discord приймає unicode-емодзі або власні назви емодзі. - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації, ініційовані каналом, увімкнені за замовчуванням. + Записи конфігурації, ініційовані каналом, увімкнено за замовчуванням. - Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). + Це впливає на потоки `/config set|unset` (коли функції команд увімкнено). Вимкнення: @@ -880,7 +882,7 @@ OpenClaw підтримує контейнери компонентів Discord - Маршрутизуйте WebSocket-трафік Gateway Discord і стартові REST-пошуки (ID застосунку + розпізнавання списку дозволених) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. + Маршрутизуйте WebSocket-трафік Gateway Discord і стартові REST-запити (ID застосунку + розв’язання списку дозволених користувачів) через HTTP(S)-проксі з `channels.discord.proxy`. ```json5 { @@ -911,7 +913,7 @@ OpenClaw підтримує контейнери компонентів Discord - Увімкніть розпізнавання PluralKit, щоб зіставляти проксійовані повідомлення з ідентичністю учасника системи: + Увімкніть розв’язання PluralKit, щоб зіставляти проксійовані повідомлення з ідентичністю учасника системи: ```json5 { @@ -928,15 +930,15 @@ OpenClaw підтримує контейнери компонентів Discord Примітки: - - списки дозволених можуть використовувати `pk:` - - відображувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` - - пошуки використовують ID вихідного повідомлення й обмежені часовим вікном - - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо не встановлено `allowBots=true` + - списки дозволених користувачів можуть використовувати `pk:` + - відображувані імена учасників зіставляються за назвою/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` + - пошуки використовують ID оригінального повідомлення й обмежені часовим вікном + - якщо пошук завершується невдало, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо `allowBots=true` не встановлено - Використовуйте `mentionAliases`, коли агентам потрібні детерміновані вихідні згадки для відомих користувачів Discord. Ключі — це імена без початкового `@`; значення — ID користувачів Discord. Невідомі імена, `@everyone`, `@here` і згадки всередині code span Markdown лишаються без змін. + Використовуйте `mentionAliases`, коли агентам потрібні детерміновані вихідні згадки відомих користувачів Discord. Ключі — це handles без початкового `@`; значення — ID користувачів Discord. Невідомі handles, `@everyone`, `@here` і згадки всередині Markdown code spans лишаються без змін. ```json5 { @@ -974,7 +976,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Приклад активності (власний статус є типом активності за замовчуванням): + Приклад активності (кастомний статус є типом активності за замовчуванням): ```json5 { @@ -987,7 +989,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Приклад потокового передавання: + Приклад трансляції: ```json5 { @@ -1007,7 +1009,7 @@ OpenClaw підтримує контейнери компонентів Discord - 1: Транслює (потребує `activityUrl`) - 2: Слухає - 3: Дивиться - - 4: Користувацька (використовує текст активності як стан статусу; емодзі необов'язковий) + - 4: Кастомний (використовує текст активності як стан статусу; емодзі необов’язковий) - 5: Змагається Приклад автоматичної присутності (сигнал стану runtime): @@ -1027,50 +1029,50 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Автоматична присутність зіставляє доступність runtime зі статусом Discord: справний => онлайн, погіршений або невідомий => неактивний, вичерпаний або недоступний => dnd. Необов'язкові перевизначення тексту: + Автоматична присутність зіставляє доступність runtime зі статусом Discord: здоровий => online, погіршений або невідомий => idle, вичерпаний або недоступний => dnd. Необов’язкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` - - `autoPresence.exhaustedText` (підтримує заповнювач `{reason}`) + - `autoPresence.exhaustedText` (підтримує placeholder `{reason}`) - Discord підтримує обробку схвалень на основі кнопок у DM і може необов'язково публікувати запити на схвалення в початковому каналі. + Discord підтримує обробку схвалень на основі кнопок у DM і може необов’язково публікувати запити на схвалення в початковому каналі. Шлях конфігурації: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов'язково; коли можливо, повертається до `commands.ownerAllowFrom`) + - `channels.discord.execApprovals.approvers` (необов’язково; за можливості повертається до `commands.ownerAllowFrom`) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord автоматично вмикає нативні схвалення виконання, коли `enabled` не задано або має значення `"auto"` і можна розпізнати принаймні одного схвалювача — або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не виводить схвалювачів виконання з `allowFrom` каналу, застарілого `dm.allowFrom` або `defaultTo` прямих повідомлень. Встановіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт схвалень. + Discord автоматично вмикає власні схвалення виконання, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного схвалювача з `execApprovals.approvers` або `commands.ownerAllowFrom`. Discord не виводить схвалювачів виконання з канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для особистих повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як власний клієнт схвалення. - Для чутливих команд групи, доступних лише власнику, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити на схвалення та фінальні результати приватно. Спершу він намагається використати Discord DM, коли власник, який викликав команду, має маршрут власника Discord; якщо він недоступний, OpenClaw повертається до першого доступного маршруту власника з `commands.ownerAllowFrom`, наприклад Telegram. + Для чутливих групових команд лише для власника, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити на схвалення та фінальні результати приватно. Спершу він пробує Discord DM, якщо власник, який викликав команду, має маршрут власника Discord; якщо він недоступний, OpenClaw повертається до першого доступного маршруту власника з `commands.ownerAllowFrom`, наприклад Telegram. - Коли `target` має значення `channel` або `both`, запит на схвалення видимий у каналі. Лише визначені особи, що схвалюють, можуть використовувати кнопки; інші користувачі отримують ефемерну відмову. Запити на схвалення містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ідентифікатор каналу неможливо отримати з ключа сеансу, OpenClaw повертається до доставки через DM. + Коли `target` має значення `channel` або `both`, запит на схвалення видно в каналі. Кнопками можуть користуватися лише визначені схвалювачі; інші користувачі отримують ефемерну відмову. Запити на схвалення містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу не можна вивести з ключа сеансу, OpenClaw повертається до доставки через DM. - Discord також відображає спільні кнопки схвалення, які використовують інші чат-канали. Нативний адаптер Discord переважно додає маршрутизацію DM для осіб, що схвалюють, і розсилання в канали. - Коли ці кнопки присутні, вони є основним інтерфейсом схвалення; OpenClaw - має додавати ручну команду `/approve` лише тоді, коли результат інструмента повідомляє, + Discord також відображає спільні кнопки схвалення, які використовують інші чат-канали. Власний адаптер Discord переважно додає маршрутизацію DM для схвалювачів і розсилання в канали. + Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw + має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що схвалення в чаті недоступні або ручне схвалення є єдиним шляхом. - Якщо нативне середовище виконання схвалень Discord не активне, OpenClaw залишає - видимим локальний детермінований запит `/approve `. Якщо - середовище виконання активне, але нативну картку неможливо доставити до жодної цілі, + Якщо власне середовище виконання схвалення Discord не активне, OpenClaw залишає + локальну детерміновану підказку `/approve ` видимою. Якщо + середовище виконання активне, але власну картку не можна доставити жодній цілі, OpenClaw надсилає резервне сповіщення в той самий чат із точною командою `/approve` з очікуваного схвалення. - Автентифікація Gateway і розв’язання схвалень дотримуються спільного контракту клієнта Gateway (ідентифікатори `plugin:` розв’язуються через `plugin.approval.resolve`; інші ідентифікатори — через `exec.approval.resolve`). За замовчуванням термін дії схвалень спливає через 30 хвилин. + Автентифікація Gateway і визначення схвалень дотримуються спільного контракту клієнта Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID — через `exec.approval.resolve`). За замовчуванням схвалення спливають через 30 хвилин. - Див. [схвалення Exec](/uk/tools/exec-approvals). + Див. [схвалення виконання](/uk/tools/exec-approvals). -## Інструменти та гейти дій +## Інструменти та шлюзи дій -Дії повідомлень Discord охоплюють обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. +Дії повідомлень Discord включають обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. Основні приклади: @@ -1079,26 +1081,26 @@ OpenClaw підтримує контейнери компонентів Discord - модерація: `timeout`, `kick`, `ban` - присутність: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файла), щоб установити зображення обкладинки запланованої події. +Дія `event-create` приймає необов’язковий параметр `image` (URL або локальний шлях до файлу), щоб установити обкладинку запланованої події. -Гейти дій розташовані в `channels.discord.actions.*`. +Шлюзи дій розташовані в `channels.discord.actions.*`. -Поведінка гейтів за замовчуванням: +Поведінка шлюзів за замовчуванням: -| Група дій | За замовчуванням | +| Група дій | За замовчуванням | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | | reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | | roles | вимкнено | | moderation | вимкнено | | presence | вимкнено | -## Інтерфейс компонентів v2 +## Інтерфейс Components v2 -OpenClaw використовує компоненти Discord v2 для схвалень exec і маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для користувацького інтерфейсу (розширений режим; потребує створення навантаження компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. +OpenClaw використовує Discord components v2 для схвалень виконання та маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для власного інтерфейсу (розширено; потребує створення компонентного payload через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. -- `channels.discord.ui.components.accentColor` задає колір акценту, який використовують контейнери компонентів Discord (hex). -- Налаштовуйте для кожного облікового запису через `channels.discord.accounts..ui.components.accentColor`. -- `embeds` ігноруються, коли присутні компоненти v2. +- `channels.discord.ui.components.accentColor` задає акцентний колір, який використовують контейнери компонентів Discord (hex). +- Задайте для кожного облікового запису через `channels.discord.accounts..ui.components.accentColor`. +- `embeds` ігноруються, коли присутні components v2. Приклад: @@ -1118,7 +1120,7 @@ OpenClaw використовує компоненти Discord v2 для схв ## Голос -Discord має дві окремі голосові поверхні: **голосові канали** в реальному часі (безперервні розмови) і **вкладення голосових повідомлень** (формат попереднього перегляду з хвильовою формою). Gateway підтримує обидві. +Discord має дві окремі голосові поверхні: голосові канали в реальному часі (безперервні розмови) та вкладення голосових повідомлень (формат попереднього перегляду хвильової форми). Gateway підтримує обидві. ### Голосові канали @@ -1126,12 +1128,12 @@ Discord має дві окремі голосові поверхні: **голо 1. Увімкніть Message Content Intent у Discord Developer Portal. 2. Увімкніть Server Members Intent, коли використовуються списки дозволених ролей/користувачів. -3. Запросіть бота з областями доступу `bot` і `applications.commands`. +3. Запросіть бота зі scopes `bot` і `applications.commands`. 4. Надайте Connect, Speak, Send Messages і Read Message History у цільовому голосовому каналі. -5. Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). +5. Увімкніть власні команди (`commands.native` або `channels.discord.commands.native`). 6. Налаштуйте `channels.discord.voice`. -Використовуйте `/vc join|leave|status` для керування сеансами. Команда використовує агента облікового запису за замовчуванням і дотримується тих самих правил списків дозволених і групової політики, що й інші команди Discord. +Використовуйте `/vc join|leave|status`, щоб керувати сеансами. Команда використовує агент за замовчуванням облікового запису та дотримується тих самих правил списків дозволених і групової політики, що й інші команди Discord. ```bash /vc join channel: @@ -1168,39 +1170,39 @@ Discord має дві окремі голосові поверхні: **голо } ``` -Нотатки: +Примітки: - `voice.tts` перевизначає `messages.tts` лише для голосового відтворення. -- `voice.model` перевизначає LLM, який використовується лише для відповідей у голосових каналах Discord. Залиште його незаданим, щоб успадкувати модель маршрутизованого агента. -- STT використовує `tools.media.audio`; `voice.model` не впливає на транскрибування. -- Перевизначення `systemPrompt` для окремих каналів Discord застосовуються до ходів голосової транскрипції для цього голосового каналу. -- Ходи голосової транскрипції визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад `gateway` і `cron`). -- Голос Discord є опційним для конфігурацій лише з текстом; задайте `channels.discord.voice.enabled=true` (або залиште наявний блок `channels.discord.voice`), щоб увімкнути команди `/vc`, голосове середовище виконання та Gateway intent `GuildVoiceStates`. -- `channels.discord.intents.voiceStates` може явно перевизначати підписку на voice-state intent. Залиште його незаданим, щоб intent відповідав ефективному ввімкненню голосу. -- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються до параметрів приєднання `@discordjs/voice`. -- Значення `@discordjs/voice` за замовчуванням — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. -- `voice.connectTimeoutMs` керує початковим очікуванням Ready у `@discordjs/voice` для `/vc join` і спроб автоматичного приєднання. За замовчуванням: `30000`. -- `voice.reconnectGraceMs` керує тим, як довго OpenClaw чекає, доки від’єднаний голосовий сеанс почне повторне підключення, перш ніж знищити його. За замовчуванням: `15000`. -- OpenClaw також відстежує збої розшифрування отриманих даних і автоматично відновлюється, виходячи з голосового каналу та повторно приєднуючись до нього після повторних збоїв у короткому вікні. -- Якщо після оновлення журнали отримання повторно показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована лінійка `@discordjs/voice` містить upstream-виправлення padding з PR discord.js #11449, яке закрило проблему discord.js #11419. +- `voice.model` перевизначає LLM, який використовується лише для відповідей голосового каналу Discord. Залиште його незаданим, щоб успадкувати модель маршрутизованого агента. +- STT використовує `tools.media.audio`; `voice.model` не впливає на транскрипцію. +- Перевизначення Discord `systemPrompt` для окремого каналу застосовуються до ходів голосового transcript для цього голосового каналу. +- Ходи голосового transcript виводять статус власника з Discord `allowFrom` (або `dm.allowFrom`); спікери, які не є власниками, не можуть отримати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). +- Голос Discord є opt-in для конфігурацій лише з текстом; установіть `channels.discord.voice.enabled=true` (або залиште наявний блок `channels.discord.voice`), щоб увімкнути команди `/vc`, голосове середовище виконання та Gateway intent `GuildVoiceStates`. +- `channels.discord.intents.voiceStates` може явно перевизначити підписку на voice-state intent. Залиште незаданим, щоб intent слідував ефективному ввімкненню голосу. +- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються в параметри приєднання `@discordjs/voice`. +- Значення за замовчуванням `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. +- `voice.connectTimeoutMs` керує початковим очікуванням Ready `@discordjs/voice` для `/vc join` і спроб автоматичного приєднання. За замовчуванням: `30000`. +- `voice.reconnectGraceMs` керує тим, як довго OpenClaw очікує, доки від’єднаний голосовий сеанс почне повторно підключатися, перш ніж знищити його. За замовчуванням: `15000`. +- OpenClaw також відстежує помилки розшифрування отримання та автоматично відновлюється, виходячи з голосового каналу й повторно приєднуючись після повторюваних помилок у короткому вікні. +- Якщо після оновлення журнали отримання повторно показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована лінійка `@discordjs/voice` містить upstream-виправлення padding з discord.js PR #11449, яке закрило issue discord.js #11419. Конвеєр голосового каналу: -- Захоплення PCM Discord перетворюється на тимчасовий WAV-файл. +- PCM-захоплення Discord перетворюється на тимчасовий WAV-файл. - `tools.media.audio` обробляє STT, наприклад `openai/gpt-4o-mini-transcribe`. -- Транскрипція надсилається через вхідний потік і маршрутизацію Discord, тоді як LLM відповіді працює з політикою голосового виводу, яка приховує інструмент агента `tts` і просить повернути текст, оскільки голос Discord відповідає за фінальне відтворення TTS. +- Transcript надсилається через ingress і маршрутизацію Discord, тоді як LLM відповіді працює з політикою голосового виводу, яка приховує агентський інструмент `tts` і просить повернути текст, оскільки голос Discord відповідає за фінальне відтворення TTS. - `voice.model`, якщо задано, перевизначає лише LLM відповіді для цього ходу голосового каналу. -- `voice.tts` зливається поверх `messages.tts`; отримане аудіо відтворюється в приєднаному каналі. +- `voice.tts` об’єднується поверх `messages.tts`; отримане аудіо відтворюється у приєднаному каналі. -Облікові дані розв’язуються для кожного компонента: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. +Облікові дані визначаються для кожного компонента: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. ### Голосові повідомлення -Голосові повідомлення Discord показують попередній перегляд хвильової форми та потребують аудіо OGG/Opus. OpenClaw автоматично генерує хвильову форму, але потребує `ffmpeg` і `ffprobe` на хості Gateway, щоб перевіряти та конвертувати. +Голосові повідомлення Discord показують попередній перегляд хвильової форми та потребують аудіо OGG/Opus. OpenClaw генерує хвильову форму автоматично, але потребує `ffmpeg` і `ffprobe` на хості Gateway для перевірки та конвертації. -- Надайте **шлях до локального файла** (URL відхиляються). -- Пропустіть текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному навантаженні). -- Приймається будь-який аудіоформат; OpenClaw конвертує в OGG/Opus за потреби. +- Надайте **локальний шлях до файлу** (URL відхиляються). +- Пропустіть текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). +- Приймається будь-який аудіоформат; OpenClaw за потреби конвертує в OGG/Opus. ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1209,19 +1211,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Усунення несправностей - + - увімкніть Message Content Intent - - увімкніть Server Members Intent, коли ви залежите від розв’язання користувача/учасника + - увімкніть Server Members Intent, коли ви залежите від визначення користувача/учасника - перезапустіть gateway після зміни intents - + - перевірте `groupPolicy` - - перевірте список дозволених гільдій у `channels.discord.guilds` - - якщо існує мапа guild `channels`, дозволені лише перелічені канали + - перевірте список дозволених guild у `channels.discord.guilds` + - якщо існує мапа `channels` guild, дозволені лише перелічені канали - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1237,9 +1239,9 @@ openclaw logs --follow Поширені причини: - - `groupPolicy="allowlist"` без відповідного списку дозволених гільдій/каналів - - `requireMention` налаштовано не в тому місці (має бути в `channels.discord.guilds` або записі каналу) - - відправника заблоковано списком дозволених `users` гільдії/каналу + - `groupPolicy="allowlist"` без відповідного списку дозволених guild/каналу + - `requireMention` налаштовано не в тому місці (має бути під `channels.discord.guilds` або записом каналу) + - відправника заблоковано списком дозволених `users` guild/каналу @@ -1256,7 +1258,7 @@ openclaw logs --follow - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` - це керує лише роботою слухача Gateway Discord, а не тривалістю ходу агента - Discord не застосовує тайм-аут, що належить каналу, до поставлених у чергу ходів агента. Слухачі повідомлень передають керування негайно, а поставлені в чергу запуски Discord зберігають порядок у межах сеансу, доки життєвий цикл сеансу/інструмента/середовища виконання не завершить або не перерве роботу. + Discord не застосовує timeout, що належить каналу, до поставлених у чергу ходів агента. Слухачі повідомлень негайно передають роботу далі, а поставлені в чергу запуски Discord зберігають порядок у межах сеансу, доки життєвий цикл сеансу/інструмента/середовища виконання не завершиться або не перерве роботу. ```json5 { @@ -1276,10 +1278,10 @@ openclaw logs --follow - + OpenClaw отримує метадані Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартного URL Gateway Discord і обмежуються за частотою в журналах. - Налаштування тайм-ауту метаданих: + Налаштування timeout метаданих: - один обліковий запис: `channels.discord.gatewayInfoTimeoutMs` - кілька облікових записів: `channels.discord.accounts..gatewayInfoTimeoutMs` @@ -1289,25 +1291,25 @@ openclaw logs --follow - OpenClaw чекає на подію Gateway Discord `READY` під час запуску та після повторних підключень середовища виконання. Налаштування з кількома обліковими записами та staggered-запуском можуть потребувати довшого вікна READY під час запуску, ніж стандартне. + OpenClaw очікує подію `READY` Discord Gateway під час запуску та після повторних підключень під час виконання. Налаштування з кількома обліковими записами та поетапним запуском можуть потребувати довшого вікна READY під час запуску, ніж стандартне. - Налаштування тайм-ауту READY: + Параметри тайм-ауту READY: - - startup для одного облікового запису: `channels.discord.gatewayReadyTimeoutMs` - - startup для кількох облікових записів: `channels.discord.accounts..gatewayReadyTimeoutMs` - - резервне значення startup з env, коли config не задано: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` - - стандартне значення startup: `15000` (15 секунд), максимум: `120000` - - runtime для одного облікового запису: `channels.discord.gatewayRuntimeReadyTimeoutMs` - - runtime для кількох облікових записів: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` - - резервне значення runtime з env, коли config не задано: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` - - стандартне значення runtime: `30000` (30 секунд), максимум: `120000` + - запуск одного облікового запису: `channels.discord.gatewayReadyTimeoutMs` + - запуск кількох облікових записів: `channels.discord.accounts..gatewayReadyTimeoutMs` + - резервне значення env для запуску, коли конфігурацію не задано: `OPENCLAW_DISCORD_READY_TIMEOUT_MS` + - стандартне значення для запуску: `15000` (15 секунд), максимум: `120000` + - виконання для одного облікового запису: `channels.discord.gatewayRuntimeReadyTimeoutMs` + - виконання для кількох облікових записів: `channels.discord.accounts..gatewayRuntimeReadyTimeoutMs` + - резервне значення env для виконання, коли конфігурацію не задано: `OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS` + - стандартне значення для виконання: `30000` (30 секунд), максимум: `120000` Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. - Якщо ви використовуєте ключі-slug, зіставлення під час runtime все одно може працювати, але probe не може повністю перевірити дозволи. + Якщо ви використовуєте ключі-slug, зіставлення під час виконання все ще може працювати, але probe не може повністю перевірити дозволи. @@ -1322,63 +1324,63 @@ openclaw logs --follow За замовчуванням повідомлення, створені ботами, ігноруються. - Якщо ви встановлюєте `channels.discord.allowBots=true`, використовуйте суворі правила згадування й allowlist, щоб уникнути зациклення. + Якщо ви задаєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. Надавайте перевагу `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. - + - підтримуйте OpenClaw актуальним (`openclaw update`), щоб була наявна логіка відновлення приймання голосу Discord - - підтвердьте `channels.discord.voice.daveEncryption=true` (за замовчуванням) - - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (типове значення upstream) і налаштовуйте лише за потреби + - підтвердьте `channels.discord.voice.daveEncryption=true` (стандартне значення) + - почніть із `channels.discord.voice.decryptionFailureTolerance=24` (стандартне значення upstream) і налаштовуйте лише за потреби - стежте за журналами на наявність: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - якщо після автоматичного повторного приєднання збої тривають, зберіть журнали й порівняйте з upstream-історією приймання DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) + - якщо збої тривають після автоматичного повторного приєднання, зберіть журнали та порівняйте з upstream-історією приймання DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) -## Довідник з конфігурації +## Довідник конфігурації -Основний довідник: [Довідник з конфігурації - Discord](/uk/gateway/config-channels#discord). +Основний довідник: [Довідник конфігурації - Discord](/uk/gateway/config-channels#discord). - + -- startup/auth: `enabled`, `token`, `accounts.*`, `allowBots` +- запуск/auth: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - команда: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - черга подій: `eventQueue.listenerTimeout` (бюджет слухача), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` - gateway: `gatewayInfoTimeoutMs`, `gatewayReadyTimeoutMs`, `gatewayRuntimeReadyTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- streaming: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- медіа/повтор: `mediaMaxMb` (обмежує вихідні завантаження Discord, за замовчуванням `100MB`), `retry` +- потокове передавання: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- медіа/повтор: `mediaMaxMb` (обмежує вихідні завантаження Discord, стандартно `100MB`), `retry` - дії: `actions.*` - присутність: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` -- функції: `threadBindings`, `bindings[]` верхнього рівня (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` +- функції: `threadBindings`, верхньорівневі `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` ## Безпека та експлуатація -- Розглядайте токени ботів як секрети (у керованих середовищах бажано `DISCORD_BOT_TOKEN`). +- Розглядайте токени ботів як секрети (`DISCORD_BOT_TOKEN` бажано використовувати в керованих середовищах). - Надавайте мінімально необхідні дозволи Discord. -- Якщо розгортання/стан команд застарілі, перезапустіть gateway і повторно перевірте за допомогою `openclaw channels status --probe`. +- Якщо deploy/state команд застарілий, перезапустіть Gateway і повторно перевірте за допомогою `openclaw channels status --probe`. ## Пов’язане - Сполучіть користувача Discord із gateway. + Сполучіть користувача Discord із Gateway. - Поведінка групового чату й allowlist. + Поведінка групового чату та allowlist. - Спрямовуйте вхідні повідомлення до агентів. + Маршрутизуйте вхідні повідомлення до агентів. Модель загроз і посилення захисту. @@ -1386,7 +1388,7 @@ openclaw logs --follow Зіставляйте guilds і канали з агентами. - + Поведінка нативних команд. diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 698c49b76..183e01b1e 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - - Робота з функціями Telegram або вебхуками -summary: Стан підтримки Telegram-бота, можливості та налаштування + - Робота над функціями Telegram або Webhook +summary: Стан підтримки, можливості та конфігурація бота Telegram title: Telegram x-i18n: - generated_at: "2026-05-02T06:09:35Z" + generated_at: "2026-05-02T09:29:15Z" model: gpt-5.5 provider: openai - source_hash: af04e95d6011ab568e07c309bc7c154d9242a53e24b7f52a2381dbf30ed842a0 + source_hash: dde2a15c6529365e6174f8e0640c1955b63fdfafa952b675159db93c5d43041c source_path: channels/telegram.md workflow: 16 --- -Готово до продакшену для DM ботів і груп через grammY. Long polling є режимом за замовчуванням; режим webhook необов’язковий. +Готово до продакшену для DM ботів і груп через grammY. Довге опитування є стандартним режимом; режим Webhook необовʼязковий. - - Стандартна політика DM для Telegram — сполучення. + + Стандартна політика DM для Telegram — спарювання. - Кросканальна діагностика та інструкції з відновлення. + Міжканальна діагностика й інструкції з відновлення. Повні шаблони й приклади конфігурації каналів. @@ -30,9 +30,9 @@ x-i18n: - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`). + Відкрийте Telegram і поспілкуйтеся з **@BotFather** (переконайтеся, що handle точно `@BotFather`). - Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен. + Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. @@ -51,8 +51,8 @@ x-i18n: } ``` - Резервний env-варіант: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway. + Резервне значення env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації/env, а потім запустіть gateway. @@ -64,31 +64,31 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди сполучення діють 1 годину. + Коди спарювання спливають через 1 годину. - Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. + Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. -Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env-значенням, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. +Порядок визначення токена враховує обліковий запис. На практиці значення конфігурації мають пріоритет над резервним значенням env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису. -## Налаштування на боці Telegram +## Налаштування на стороні Telegram - - Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. + + Для ботів Telegram стандартно ввімкнено **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. - Якщо бот має бачити всі групові повідомлення, зробіть одне з цього: + Якщо бот має бачити всі групові повідомлення, зробіть одне з такого: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і повторно додайте бота в кожну групу, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну. @@ -107,38 +107,38 @@ openclaw pairing approve telegram -## Контроль доступу й активація +## Контроль доступу та активація `channels.telegram.dmPolicy` керує доступом до прямих повідомлень: - - `pairing` (за замовчуванням) - - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) - - `open` (потрібно, щоб `allowFrom` містив `"*"`) + - `pairing` (стандартно) + - `allowlist` (потребує принаймні одного ID відправника в `allowFrom`) + - `open` (потребує, щоб `allowFrom` містив `"*"`) - `disabled` - `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. + `dmPolicy: "open"` з `allowFrom: ["*"]` дає змогу будь-якому обліковому запису Telegram, який знайде або вгадає імʼя користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються. - У конфігураціях із кількома обліковими записами обмежувальний `channels.telegram.allowFrom` верхнього рівня вважається межею безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після злиття все ще не містить явного wildcard. - `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється перевіркою конфігурації. + У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний список allowlist облікового запису після обʼєднання все ще не містить явного wildcard. + `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації. Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися і ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (найкраща спроба; потрібен токен бота Telegram). - Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + Якщо ви оновилися й ваша конфігурація містить записи allowlist виду `@username`, запустіть `openclaw doctor --fix`, щоб їх розвʼязати (найкраще зусилля; потребує токена бота Telegram). + Якщо раніше ви покладалися на файли allowlist зі сховища спарювання, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення). + Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була надійно зафіксована в конфігурації (замість залежності від попередніх схвалень спарювання). - Поширена плутанина: схвалення DM-сполучення не означає «цей відправник авторизований усюди». - Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення exec мали явний обліковий запис оператора. - Авторизація відправника в групі все одно походить з явних allowlist у конфігурації. - Якщо ви хочете «я авторизований один раз, і працюють і DM, і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. + Типова плутанина: схвалення спарювання DM не означає «цей відправник авторизований усюди». + Спарювання надає доступ до DM. Якщо власника команд ще немає, перше схвалене спарювання також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. + Авторизація відправників у групах усе ще надходить із явних allowlist у конфігурації. + Якщо ви хочете «я авторизований один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram Безпечніше (без стороннього бота): - 1. Надішліть DM своєму боту. + 1. Напишіть своєму боту в DM. 2. Виконайте `openclaw logs --follow`. 3. Прочитайте `from.id`. @@ -158,25 +158,25 @@ curl "https://api.telegram.org/bot/getUpdates" 1. **Які групи дозволені** (`channels.telegram.groups`) - немає конфігурації `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки group-ID - - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) + - з `groupPolicy: "allowlist"` (стандартно): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - - `allowlist` (за замовчуванням) + - `allowlist` (стандартно) - `disabled` - `groupAllowFrom` використовується для фільтрації відправників у групі. Якщо не задано, Telegram повертається до `allowFrom`. + `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). - Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`. - Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища DM-сполучень. - Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. - Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень. + Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Відʼємні ID чатів належать до `channels.telegram.groups`. + Нечислові записи ігноруються для авторизації відправників. + Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища спарювання DM. + Спарювання лишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища спарювання. Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. + Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime стандартно закривається без доступу з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. - Приклад: дозволити будь-якому учаснику в одній конкретній групі: + Приклад: дозволити будь-якого учасника в одній конкретній групі: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи: + Приклад: дозволити лише конкретних користувачів в одній конкретній групі: ```json5 { @@ -211,18 +211,18 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. + Типова помилка: `groupAllowFrom` не є allowlist груп Telegram. - - Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, хто саме в дозволеній групі може запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом. + - Додавайте відʼємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, до `channels.telegram.groups`. + - Додавайте ID користувачів Telegram, як-от `8734062810`, до `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. - Групові відповіді за замовчуванням потребують згадки. + Групові відповіді стандартно потребують згадки. Згадка може надходити з: @@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд на рівні сесії: + Перемикачі команд рівня сеансу: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сесії. Для сталості використовуйте конфігурацію. + Вони оновлюють лише стан сеансу. Для збереження використовуйте конфігурацію. Приклад сталої конфігурації: @@ -254,9 +254,9 @@ curl "https://api.telegram.org/bot/getUpdates" Отримання ID групового чату: - - перешліть групове повідомлення до `@userinfobot` / `@getidsbot` - - або прочитайте `chat.id` з `openclaw logs --follow` - - або перегляньте Bot API `getUpdates` + - переслати групове повідомлення до `@userinfobot` / `@getidsbot` + - або прочитати `chat.id` з `openclaw logs --follow` + - або перевірити Bot API `getUpdates` @@ -264,32 +264,32 @@ curl "https://api.telegram.org/bot/getUpdates" ## Поведінка runtime - Telegram належить процесу gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали). -- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді й заповнювачами медіа. -- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми лишалися ізольованими. -- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає thread ID для відповідей. -- Long polling використовує grammY runner із послідовністю на рівні чату/thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. -- Long polling захищений усередині кожного процесу gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, script або зовнішній poller. -- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски polling-stall під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали). +- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа. +- Групові сеанси ізольовані за ID групи. Теми форуму додають `:topic:`, щоб тримати теми ізольованими. +- DM-повідомлення можуть містити `message_thread_id`; OpenClaw зберігає ID потоку для відповідей, але стандартно лишає DM у плоскому сеансі. Налаштуйте `channels.telegram.direct..threadReplies: "inbound"` або `requireTopic: true`, коли навмисно хочете ізоляцію сеансів за темами DM. +- Довге опитування використовує grammY runner із послідовністю за чатом/потоком. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller. +- Перезапуски watchdog для довгого опитування стандартно спрацьовують після 120 секунд без завершеного liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зависання опитування під час тривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. - Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується). ## Довідник функцій - + OpenClaw може транслювати часткові відповіді в реальному часі: - - прямі чати: повідомлення попереднього перегляду + `editMessageText` - - групи/теми: повідомлення попереднього перегляду + `editMessageText` + - прямі чати: preview-повідомлення + `editMessageText` + - групи/теми: preview-повідомлення + `editMessageText` Вимога: - - `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` відображається на `partial` у Telegram (сумісність із кросканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний preview streaming) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode` + - `channels.telegram.streaming` має значення `off | partial | block | progress` (стандартно: `partial`) + - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане preview-повідомлення (стандартно: `true`, коли preview streaming активний) + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і новіших версій. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Preview-оновлення прогресу інструментів — це короткі рядки "Working...", які показуються під час виконання інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram лишає їх увімкненими стандартно, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніше. Щоб зберегти редагований preview для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -306,43 +306,43 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальний службовий текст інструментів/прогресу приглушується замість надсилання як окремі повідомлення «Працюємо...». Запити на схвалення, медіа payloads і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду в Telegram вимикаються, а звичайні повідомлення інструментів/прогресу пригнічуються замість надсилання окремими повідомленнями "Working...". Запити на схвалення, медіа-вміст і помилки все одно проходять через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли потрібно зберегти лише редагування попереднього перегляду відповіді, приховуючи рядки стану прогресу інструментів. Для відповідей лише з текстом: - - короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці + - короткі попередні перегляди в DM/групі/темі: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу Telegram відображала час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, медіа payloads) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Потокове передавання попереднього перегляду відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. Потік міркувань лише для Telegram: - - `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерування + - `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерації - фінальна відповідь надсилається без тексту міркувань - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Markdown-подібний текст відтворюється як безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити збої розбору Telegram. + - Текст у стилі Markdown відтворюється як HTML, безпечний для Telegram. + - Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`. - - Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. + + Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`. Типові значення нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram - Додайте користувацькі записи меню команд: + Додайте власні записи меню команд: ```json5 { @@ -359,47 +359,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - імена нормалізуються (видаляється початковий `/`, переводиться в нижній регістр) + - імена нормалізуються (прибирається початковий `/`, нижній регістр) - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - - користувацькі команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються й записуються в журнал + - власні команди не можуть перевизначати нативні команди + - конфлікти/дублікати пропускаються й журналюються - Примітки: + Нотатки: - - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично - - команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram + - власні команди є лише записами меню; вони не реалізують поведінку автоматично + - команди plugin/skill усе одно можуть працювати під час введення, навіть якщо їх не показано в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо налаштовані. + Якщо нативні команди вимкнені, вбудовані команди видаляються. Власні команди або команди plugin усе ще можуть реєструватися, якщо це налаштовано. - Поширені збої налаштування: + Поширені помилки налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`. - - Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повний endpoint `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд plugin/skill/власних команд або вимкніть `channels.telegram.commands.native`. + - Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як збій очищення webhook. - - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. + - `setMyCommands failed` з помилками мережі/завантаження зазвичай означає, що вихідні DNS/HTTPS-з'єднання до `api.telegram.org` заблоковані. - ### Команди сполучення пристрою (plugin `device-pair`) + ### Команди сполучення пристроїв (`device-pair` plugin) - Коли встановлено plugin `device-pair`: + Коли встановлено `device-pair` plugin: 1. `/pair` генерує код налаштування - 2. вставте код у застосунок iOS - 3. `/pair pending` перелічує запити в очікуванні (включно з роллю/областями) + 2. вставте код у застосунку iOS + 3. `/pair pending` перелічує запити в очікуванні (зокрема роль/області) 4. схваліть запит: - `/pair approve ` для явного схвалення - `/pair approve`, коли є лише один запит в очікуванні - `/pair approve latest` для найновішого - Код налаштування переносить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області під власним префіксом ролі. + Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий операторський токен залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише операторські запити; неоператорські ролі все одно потребують областей під власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно запустіть `/pair pending` перед схваленням. + Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). - Налаштуйте область вбудованої клавіатури: + Налаштуйте область дії вбудованої клавіатури: ```json5 { @@ -459,7 +459,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Натискання callback передаються агенту як текст: + Кліки callback передаються агенту як текст: `callback_data: ` @@ -467,15 +467,15 @@ curl "https://api.telegram.org/bot/getUpdates" Дії інструментів Telegram включають: - - `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, необов'язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, необов'язкові `iconColor`, `iconCustomEmojiId`) - Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Елементи керування обмеженнями: + Керування обмеженнями: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` @@ -483,16 +483,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. + Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціальне повторне розв'язання SecretRef для кожного надсилання. Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги потоків відповідей у згенерованому виводі: + + Telegram підтримує явні теги гілок відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, яке запустило обробку + - `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -501,29 +501,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли потоки відповідей увімкнені й доступний початковий текст або підпис Telegram, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. + Коли гілки відповідей увімкнені й доступний початковий текст або підпис Telegram, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. + Примітка: `off` вимикає неявні гілки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - + Форумні супергрупи: - - ключі сесій тем додають `:topic:` - - відповіді та індикатор набору спрямовуються в потік теми + - ключі сесій теми додають `:topic:` + - відповіді й індикація набору спрямовуються в гілку теми - шлях конфігурації теми: `channels.telegram.groups..topics.` - Спеціальний випадок загальної теми (`threadId=1`): + Особливий випадок загальної теми (`threadId=1`): - - надсилання повідомлень пропускають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - - дії набору все ще включають `message_thread_id` + - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) + - дії набору тексту все одно включають `message_thread_id` - Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` застосовується лише до теми й не успадковується з типових значень групи. + Успадкування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` стосується лише теми й не успадковується з типових налаштувань групи. - **Маршрутизація агентів для кожної теми**: кожна тема може маршрутизуватися до іншого агента через установлення `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизувати до іншого агента, якщо встановити `agentId` у конфігурації теми. Це надає кожній темі власний ізольований робочий простір, пам'ять і сесію. Приклад: ```json5 { @@ -543,26 +543,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та topic-кваліфікованим id на кшталт `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Стійке прив'язування тем ACP**: Теми форуму можуть закріплювати сесії ACP harness через типізовані прив'язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Створення ACP, прив’язане до потоку, з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). + **Запуск ACP, прив'язаний до гілки, з чату**: `/acp spawn --thread here|auto` прив'язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно, щоб `channels.telegram.threadBindings.spawnSessions` залишалося ввімкненим (за замовчуванням: `true`). - Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням потоку. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM і метадані відповіді; вони використовують ключі сесій з урахуванням гілок лише тоді, коли DM налаштовано з `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` або відповідною конфігурацією теми. - + ### Аудіоповідомлення - Telegram розрізняє голосові нотатки та аудіофайли. + Telegram розрізняє голосові нотатки й аудіофайли. - за замовчуванням: поведінка аудіофайлу - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосову нотатку - вхідні транскрипти голосових нотаток оформлюються як машинно згенерований, - ненадійний текст у контексті агента; виявлення згадок усе ще використовує сирий - транскрипт, тому голосові повідомлення з gating за згадкою продовжують працювати. + ненадійний текст у контексті агента; виявлення згадок усе одно використовує сирий + транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати. Приклад дії повідомлення: @@ -578,7 +578,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли та відеонотатки. + Telegram розрізняє відеофайли й відеонотатки. Приклад дії повідомлення: @@ -594,15 +594,15 @@ curl "https://api.telegram.org/bot/getUpdates" Відеонотатки не підтримують підписи; наданий текст повідомлення надсилається окремо. - ### Стікери + ### Наліпки - Обробка вхідних стікерів: + Обробка вхідних наліпок: - - статичний WEBP: завантажується й обробляється (placeholder ``) + - статичний WEBP: завантажується й обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається - Поля контексту стікера: + Поля контексту наліпки: - `Sticker.emoji` - `Sticker.setName` @@ -610,13 +610,13 @@ curl "https://api.telegram.org/bot/getUpdates" - `Sticker.fileUniqueId` - `Sticker.cachedDescription` - Файл кешу стікерів: + Файл кешу наліпок: - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision. + Наліпки описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору. - Увімкніть дії зі стікерами: + Увімкніть дії з наліпками: ```json5 { @@ -630,7 +630,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Дія надсилання стікера: + Дія надсилання наліпки: ```json5 { @@ -655,7 +655,7 @@ curl "https://api.telegram.org/bot/getUpdates" - Реакції Telegram надходять як оновлення `message_reaction` (окремо від payloads повідомлень). + Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлення). Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: @@ -663,44 +663,44 @@ curl "https://api.telegram.org/bot/getUpdates" Конфігурація: - - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`) - - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`) Примітки: - - `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). - - Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - - Telegram не надає ID гілок у оновленнях реакцій. - - групи не-форуми маршрутизуються до сесії групового чату - - форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми + - `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). + - Події реакцій усе одно поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає ідентифікатори потоків в оновленнях реакцій. + - групи без форумів маршрутизуються до сесії групового чату + - групи з форумами маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми `allowed_updates` для polling/webhook автоматично включає `message_reaction`. - - `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. + + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") - Нотатки: + Примітки: - - Telegram очікує unicode emoji (наприклад "👀"). - - Використайте `""`, щоб вимкнути реакцію для каналу або акаунта. + - Telegram очікує unicode-емодзі (наприклад, "👀"). + - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`). + Записи конфігурації каналу ввімкнені типово (`configWrites !== false`). Записи, ініційовані Telegram, включають: - - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` + - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - `/config set` і `/config unset` (потребує ввімкнення команд) Вимкнення: @@ -718,37 +718,37 @@ curl "https://api.telegram.org/bot/getUpdates" - За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). + Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захисти запиту, секретний токен Telegram і JSON body перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі lane-и бота для кожного чату/кожної теми, що й у long polling, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим Webhook перевіряє захисти запитів, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram. + Потім OpenClaw асинхронно обробляє оновлення через ті самі bot lanes для кожного чату/кожної теми, що використовуються long polling, тому повільні ходи агента не затримують delivery ACK Telegram. - - `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000. - - `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. - - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів Telegram. - - `channels.telegram.timeoutSeconds` перевизначає timeout API-клієнта Telegram (якщо не задано, застосовується стандартне значення grammY). Клієнти бота з long-polling обмежують налаштовані значення нижче 45-секундного guard запиту `getUpdates`, щоб idle polls не переривалися до завершення 30-секундного вікна poll. - - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling. - - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. - - додатковий контекст reply/quote/forward наразі передається як отриманий. - - Allowlist-и Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - - Керування історією DM: + - Типове значення `channels.telegram.textChunkLimit` — 4000. + - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. + - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram. + - `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів long-polling обмежують налаштовані значення нижче за 45-секундний захист запиту `getUpdates`, щоб idle polls не переривалися до завершення 30-секундного вікна опитування. + - `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через polling-stall. + - Історія групового контексту використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає. + - Додатковий контекст відповіді/цитати/пересилання наразі передається так, як отриманий. + - Allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + - Елементи керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка фінальної відповіді на вхідні повідомлення також використовує обмежений safe-send retry для помилок Telegram до підключення, але не повторює неоднозначні мережеві envelopes після надсилання, які могли б дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API. Доставка фінальної вхідної відповіді також використовує обмежену повторну спробу безпечного надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві envelope після надсилання, які могли б дублювати видимі повідомлення. - Ціль надсилання CLI може бути числовим ID чату або username: + Ціль надсилання CLI може бути числовим ID чату або іменем користувача: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Poll-и Telegram використовують `openclaw message poll` і підтримують форумні теми: + Опитування Telegram використовують `openclaw message poll` і підтримують теми форумів: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -758,57 +758,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Прапорці poll лише для Telegram: + Прапорці опитувань лише для Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для форумних тем (або використайте ціль `:topic:`) + - `--thread-id` для тем форумів (або використовуйте ціль `:topic:`) Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для inline keyboards, коли `channels.telegram.capabilities.inlineButtons` це дозволяє + - `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті - - `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media + - `--force-document`, щоб надсилати вихідні зображення й GIF як документи замість стиснених фото або завантажень animated-media Обмеження дій: - - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з poll-ами - - `channels.telegram.actions.poll=false` вимикає створення poll-ів Telegram, залишаючи звичайне надсилання ввімкненим + - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим - - Telegram підтримує exec approvals у DM approver-ів і може необов’язково публікувати prompts у початковому чаті або темі. Approver-и мають бути числовими ID користувачів Telegram. + + Telegram підтримує підтвердження exec у DM підтверджувачів і може необов’язково публікувати prompts у початковому чаті або темі. Підтверджувачі мають бути числовими ID користувачів Telegram. Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного approver-а) - - `channels.telegram.execApprovals.approvers` (fallback до числових ID власників з `commands.ownerAllowFrom`) - - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного підтверджувача) + - `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver-ом. Перше схвалене DM pairing bootstrap-ить `commands.ownerAllowFrom`, коли власника команд ще не існує, тому налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось підтверджувачем exec. Перше затверджене спарювання DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником і далі працює без дублювання ID у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє у форумну тему, OpenClaw зберігає тему для prompt-а схвалення та наступного повідомлення. Exec approvals за замовчуванням спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє в тему форуму, OpenClaw зберігає тему для prompt підтвердження та подальшого повідомлення. Підтвердження exec типово спливають через 30 хвилин. - Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалення з префіксом `plugin:` визначаються через approvals Plugin; інші спочатку визначаються через exec approvals. + Кнопки inline-підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` визначаються через підтвердження plugin; інші спочатку визначаються через підтвердження exec. - Див. [Exec approvals](/uk/tools/exec-approvals). + Див. [Підтвердження exec](/uk/tools/exec-approvals). -## Керування відповідями про помилки +## Елементи керування відповідями про помилки -Коли агент стикається з помилкою доставки або provider-а, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації: +Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації: -| Ключ | Значення | За замовчуванням | Опис | -| ----------------------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час outages. | +| Ключ | Значення | Типово | Опис | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилок під час перебоїв. | -Підтримуються перевизначення для кожного акаунта, групи та теми (те саме успадкування, що й для інших ключів конфігурації Telegram). +Підтримуються перевизначення для кожного облікового запису, кожної групи та кожної теми (таке саме успадкування, як для інших ключів конфігурації Telegram). ```json5 { @@ -831,53 +831,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - - Якщо `requireMention=false`, режим privacy Telegram має дозволяти повну видимість. + - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на membership. + - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - швидкий тест сесії: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути вказана (або включати `"*"`) - - перевірте membership бота в групі - - перегляньте логи: `openclaw logs --follow` для причин пропуску + - коли `channels.telegram.groups` існує, група має бути в списку (або включати `"*"`) + - перевірте членство бота в групі + - перегляньте журнали: `openclaw logs --follow` для причин пропуску - - авторизуйте свою ідентичність відправника (pairing і/або числовий `allowFrom`) + - авторизуйте ідентичність свого відправника (спарювання та/або числовий `allowFrom`) - авторизація команд усе одно застосовується, навіть коли політика групи — `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість команд Plugin/Skills/custom або вимкніть нативні меню - - стартові виклики `deleteMyCommands` / `setMyCommands` обмежені та повторюються один раз через транспортний fallback Telegram у разі timeout запиту. Постійні помилки network/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість plugin/skill/користувацьких команд або вимкніть нативні меню + - startup-виклики `deleteMyCommands` / `setMyCommands` обмежені й повторюються один раз через транспортний fallback Telegram у разі timeout запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org` - + - - `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота. - - Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для акаунта за замовчуванням. - - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою auth; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий токен до пізніших викликів API. - - Якщо `deleteWebhook` завершується з transient network error під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній webhook URL, polling продовжується, бо очищення вже задоволено. + - `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота. + - Повторно скопіюйте або згенеруйте заново токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. + - `deleteWebhook 401 Unauthorized` під час startup — це також збій автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій поганого токена до пізніших API-викликів. + - Якщо `deleteWebhook` завершується з тимчасовою мережевою помилкою під час polling startup, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо cleanup уже виконано. - - Node 22+ + власний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спочатку розв’язують `api.telegram.org` в IPv6; несправний IPv6 egress може спричиняти періодичні збої Telegram API. - - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки. - - Якщо сокети Telegram повторно створюються з коротким фіксованим інтервалом, перевірте, чи не замалий `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче запобіжника запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. - - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис із polling не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис із webhook не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність polling-транспорту застаріла. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли тривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через polling-stall. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`. - - Telegram також враховує proxy env процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. - - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й стандартних proxy env немає, Telegram також використовує цю URL-адресу для транспорту Bot API. - - На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`: + - Node 22+ + користувацький fetch/proxy може спричиняти негайне переривання, якщо типи AbortSignal не збігаються. + - Деякі хости спершу розв’язують `api.telegram.org` в IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API. + - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці спроби як відновлювані мережеві помилки. + - Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не задано низьке значення `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче захисного ліміту запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування й перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням. + - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис з опитуванням не завершив `getUpdates` після стартового пільгового періоду, коли запущений обліковий запис webhook не завершив `setWebhook` після стартового пільгового періоду або коли остання успішна активність транспорту опитування застаріла. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми проксі, DNS, IPv6 або вихідного TLS між хостом і `api.telegram.org`. + - Telegram також враховує змінні середовища проксі процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. + - Якщо керований проксі OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й немає стандартної змінної середовища проксі, Telegram також використовує цей URL для транспорту Bot API. + - На VPS-хостах із нестабільним прямим вихідним трафіком/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -885,7 +885,7 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім типовий порядок процесу, наприклад `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо жодне не застосовується, Node 22+ повертається до `ipv4first`. + - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS для Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, а потім типовий порядок процесу, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо нічого не застосовується, Node 22+ повертається до `ipv4first`. - Якщо ваш хост є WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства: ```yaml @@ -895,10 +895,10 @@ channels: autoSelectFamily: false ``` - - Відповіді з діапазону бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені + - Відповіді з діапазону RFC 2544 для бенчмаркінгу (`198.18.0.0/15`) уже дозволені для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або - прозорий proxy переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете + прозорий проксі переписує `api.telegram.org` на якусь іншу + приватну/внутрішню/спеціального використання адресу під час завантаження медіа, ви можете увімкнути обхід лише для Telegram: ```yaml @@ -908,25 +908,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Та сама опція доступна для кожного облікового запису за адресою + - Такий самий явний дозвіл доступний для кожного облікового запису в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште - небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон - бенчмарків RFC 2544 за замовчуванням. + - Якщо ваш проксі розв’язує медіахости Telegram у `198.18.x.x`, спершу залиште + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон RFC 2544 + для бенчмаркінгу за замовчуванням. `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти Telegram - media від SSRF. Використовуйте це лише для довірених, контрольованих оператором proxy - середовищ, таких як Clash, Mihomo або Surge fake-IP routing, коли вони - синтезують приватні або спеціального використання відповіді поза діапазоном бенчмарків - RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет. + media SSRF. Використовуйте це лише для довірених проксі-середовищ, контрольованих оператором, + як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони + синтезують приватні або спеціального використання відповіді поза діапазоном RFC 2544 для + бенчмаркінгу. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет. - Перевизначення середовища (тимчасові): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірте відповіді DNS: + - Перевірте DNS-відповіді: ```bash dig +short api.telegram.org A @@ -936,23 +936,23 @@ dig +short api.telegram.org AAAA -Додаткова довідка: [усунення несправностей каналів](/uk/channels/troubleshooting). +Докладніше: [Усунення проблем із каналами](/uk/channels/troubleshooting). ## Довідник конфігурації -Основний довідник: [довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). +Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`) -- схвалення exec: `execApprovals`, `accounts.*.execApprovals` +- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) +- підтвердження exec: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` - потоки/відповіді: `replyToMode` -- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` +- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- власний корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) +- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot`) - webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` @@ -962,14 +962,14 @@ dig +short api.telegram.org AAAA -Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритет для кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане - Сполучіть користувача Telegram із Gateway. + Зв’яжіть користувача Telegram із gateway. Поведінка списку дозволених груп і тем. @@ -984,6 +984,6 @@ dig +short api.telegram.org AAAA Зіставляйте групи й теми з агентами. - Діагностика між каналами. + Міжканальна діагностика. diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 44e13fe31..852c4b7e9 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,40 +1,40 @@ --- read_when: - - Вам потрібна точна семантика конфігурації на рівні полів або значення за замовчуванням + - Вам потрібна точна семантика конфігурації на рівні полів або точні значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідка з конфігурації Gateway для основних ключів OpenClaw, типових значень і посилань на окремі довідники підсистем +summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник із конфігурації x-i18n: - generated_at: "2026-05-02T07:52:33Z" + generated_at: "2026-05-02T09:29:32Z" model: gpt-5.5 provider: openai - source_hash: afdbe56195982130603f02ff2350f253c32db4d72723035bba52d630a971602a + source_hash: fa8aeec6143ae70905e75f1034005c97c3a72fcaa34f14f61294dece561f4ce6 source_path: gateway/configuration-reference.md workflow: 16 --- -Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Конфігурація](/uk/gateway/configuration). +Основна довідка з конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Конфігурації](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і містить посилання на окремі глибші довідники, коли підсистема має власну довідку. Каталоги команд, що належать каналам і plugins, а також поглиблені параметри пам’яті/QMD розміщені на власних сторінках, а не на цій. +Охоплює основні поверхні конфігурації OpenClaw і посилається назовні, коли підсистема має власну глибшу довідку. Каталоги команд, що належать каналам і plugin, а також глибокі параметри пам'яті/QMD розміщені на власних сторінках, а не на цій. -Джерело істини в коді: +Істина в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для перевірки та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації +- `openclaw config schema` виводить поточну JSON Schema, що використовується для валідації та Control UI, з об'єднаними метаданими вбудованих/plugin/каналів, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми, обмежений шляхом, для інструментів деталізації - `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми Шлях пошуку для агента: використовуйте дію інструмента `gateway` `config.schema.lookup` для -точної документації й обмежень на рівні полів перед редагуванням. Використовуйте -[Конфігурація](/uk/gateway/configuration) для настанов, орієнтованих на завдання, і цю сторінку -для ширшої мапи полів, стандартних значень і посилань на довідники підсистем. +точної документації та обмежень на рівні полів перед редагуванням. Використовуйте +[Конфігурацію](/uk/gateway/configuration) для порад, орієнтованих на завдання, а цю сторінку +для ширшої карти полів, значень за замовчуванням і посилань на довідки підсистем. -Окремі поглиблені довідники: +Окремі глибокі довідки: -- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Команди slash](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки каналів/plugins-власників для поверхонь команд, специфічних для каналів +- [Довідка з конфігурації пам'яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` +- [Slash-команди](/uk/tools/slash-commands) для поточного каталогу вбудованих + bundled команд +- сторінки відповідних власників каналів/plugin для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні стандартні значення, коли їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов'язкові — OpenClaw використовує безпечні значення за замовчуванням, коли їх пропущено. --- @@ -42,33 +42,33 @@ x-i18n: Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. [Конфігурація — канали](/uk/gateway/config-channels) для `channels.*`, -зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших -bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження згадок). +включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими +bundled каналами (автентифікація, контроль доступу, кілька акаунтів, керування згадками). -## Стандартні налаштування агента, мультиагентність, сесії та повідомлення +## Значення агента за замовчуванням, multi-agent, сеанси та повідомлення Перенесено на окрему сторінку — див. [Конфігурація — агенти](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робочий простір, модель, мислення, heartbeat, пам’ять, медіа, skills, sandbox) -- `multiAgent.*` (маршрутизація та прив’язки кількох агентів) -- `session.*` (життєвий цикл сесії, compaction, pruning) +- `agents.defaults.*` (робоча область, модель, мислення, Heartbeat, пам'ять, медіа, Skills, sandbox) +- `multiAgent.*` (маршрутизація та прив'язки multi-agent) +- `session.*` (життєвий цикл сеансу, Compaction, обрізання) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - - `talk.speechLocale`: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS - - `talk.silenceTimeoutMs`: коли не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.speechLocale`: необов'язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS + - `talk.silenceTimeoutMs`: коли не задано, Talk зберігає стандартне вікно паузи платформи перед надсиланням транскрипту (`700 ms on macOS and Android, 900 ms on iOS`) -## Інструменти та користувацькі провайдери +## Інструменти та власні провайдери -Політику інструментів, експериментальні перемикачі, конфігурацію інструментів на основі провайдерів і налаштування користувацьких -провайдерів / base URL перенесено на окрему сторінку — див. -[Конфігурація — інструменти та користувацькі провайдери](/uk/gateway/config-tools). +Політику інструментів, експериментальні перемикачі, конфігурацію інструментів на базі провайдерів і налаштування власного +провайдера / базового URL перенесено на окрему сторінку — див. +[Конфігурація — інструменти та власні провайдери](/uk/gateway/config-tools). ## Моделі -Визначення провайдерів, allowlist моделей і налаштування користувацьких провайдерів розміщено в -[Конфігурація — інструменти та користувацькі провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls). -Корінь `models` також керує глобальною поведінкою каталогу моделей. +Визначення провайдерів, allowlist моделей і налаштування власного провайдера розміщені в +[Конфігурація — інструменти та власні провайдери](/uk/gateway/config-tools#custom-providers-and-base-urls). +Корінь `models` також відповідає за глобальну поведінку каталогу моделей. ```json5 { @@ -80,16 +80,15 @@ bundled каналів (автентифікація, контроль дост ``` - `models.mode`: поведінка каталогу провайдера (`merge` або `replace`). -- `models.providers`: мапа користувацьких провайдерів із ключами за id провайдера. -- `models.pricing.enabled`: керує фоновою ініціалізацією ціноутворення. Коли +- `models.providers`: мапа власних провайдерів із ключами за id провайдера. +- `models.pricing.enabled`: керує фоновою ініціалізацією цін. Коли `false`, запуск Gateway пропускає отримання каталогів цін OpenRouter і LiteLLM; - налаштовані значення `models.providers.*.models[].cost` усе ще працюють для локальних - оцінок вартості. + налаштовані значення `models.providers.*.models[].cost` все одно працюють для локальних оцінок вартості. ## MCP -Визначення MCP-серверів, керовані OpenClaw, розміщені в `mcp.servers` і -споживаються вбудованим Pi та іншими runtime adapters. Команди `openclaw mcp list`, +Визначення MCP-серверів, керованих OpenClaw, розміщені в `mcp.servers` і +використовуються вбудованим Pi та іншими runtime-адаптерами. Команди `openclaw mcp list`, `show`, `set` і `unset` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -115,20 +114,20 @@ bundled каналів (автентифікація, контроль дост } ``` -- `mcp.servers`: іменовані stdio або віддалені визначення MCP-серверів для runtime, які +- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для runtime, які надають налаштовані MCP-інструменти. Віддалені записи використовують `transport: "streamable-http"` або `transport: "sse"`; - `type: "http"` — це CLI-native псевдонім, який `openclaw mcp set` і + `type: "http"` — це CLI-нативний alias, який `openclaw mcp set` і `openclaw doctor --fix` нормалізують у канонічне поле `transport`. -- `mcp.sessionIdleTtlMs`: idle TTL для bundled MCP runtime з прив’язкою до сесії. - Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є запасним механізмом для - довготривалих сесій і майбутніх викликачів. -- Зміни в `mcp.*` застосовуються без перезапуску шляхом звільнення кешованих MCP runtime сесії. - Наступне виявлення/використання інструментів відтворює їх із нової конфігурації, тому видалені - записи `mcp.servers` прибираються негайно, а не чекають на idle TTL. +- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP runtime, обмежених сеансом. + Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є резервним механізмом для + довготривалих сеансів і майбутніх викликачів. +- Зміни в `mcp.*` застосовуються гаряче шляхом звільнення кешованих MCP runtime сеансу. + Наступне виявлення/використання інструментів відтворює їх із нової конфігурації, тож видалені + записи `mcp.servers` прибираються негайно, а не чекають на TTL простою. Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і -[CLI бекенди](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки runtime. +[CLI-бекенди](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки runtime. ## Skills @@ -155,14 +154,14 @@ bundled каналів (автентифікація, контроль дост } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled skills (managed/workspace skills не зачіпаються). -- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). -- `install.preferBrew`: коли `true`, віддавати перевагу інсталяторам Homebrew, коли `brew` - доступний, перед fallback до інших типів інсталяторів. -- `install.nodeManager`: уподобання Node-інсталятора для специфікацій `metadata.openclaw.install` +- `allowBundled`: необов'язковий allowlist лише для bundled Skills (керовані/робочі Skills не зачіпаються). +- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). +- `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, якщо `brew` + доступний, перед переходом до інших типів інсталяторів. +- `install.nodeManager`: перевага інсталятора node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає skill, навіть якщо він bundled/installed. -- `entries..apiKey`: зручний спосіб для skills, що оголошують основну env var (рядок plaintext або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручність для Skills, що оголошують основну змінну env (plaintext string або об'єкт SecretRef). --- @@ -190,41 +189,41 @@ bundled каналів (автентифікація, контроль дост } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, плюс `plugins.load.paths`. -- Виявлення приймає нативні OpenClaw plugins, а також сумісні Codex bundles і Claude bundles, включно з manifestless Claude default-layout bundles. +- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. +- Виявлення приймає нативні plugins OpenClaw, а також сумісні Codex bundles і Claude bundles, включно з manifestless Claude bundles зі стандартним layout. - **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені plugins). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API-ключа рівня plugin (коли підтримується plugin). -- `plugins.entries..env`: мапа env vars з областю видимості plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, зі старого `before_agent_start`, зберігаючи старі `modelOverride` і `providerOverride`. Застосовується до нативних hook’ів plugin і підтримуваних bundle-provided каталогів hook’ів. -- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені non-bundled plugins можуть читати необроблений вміст розмови з typed hooks, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довіряє цьому plugin запитувати per-run перевизначення `provider` і `model` для фонових запусків subagent. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений plugin (перевіряється нативною схемою OpenClaw plugin, коли вона доступна). -- Налаштування облікового запису/runtime для channel plugin розміщені в `channels.` і мають описуватися метаданими `channelConfigs` у manifest відповідного plugin-власника, а не центральним реєстром опцій OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує fallback до `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env var `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (стандартно: `https://api.firecrawl.dev`; self-hosted перевизначення мають вказувати на приватні/внутрішні endpoints). - - `onlyMainContent`: витягувати зі сторінок лише основний вміст (стандартно: `true`). - - `maxAgeMs`: максимальний вік кешу в мілісекундах (стандартно: `172800000` / 2 дні). - - `timeoutSeconds`: timeout запиту scrape у секундах (стандартно: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web search). +- `allow`: необов'язковий allowlist (завантажуються лише перелічені plugins). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні plugin (коли підтримується plugin). +- `plugins.entries..env`: мапа змінних env, обмежена plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля, що змінюють prompt, із legacy `before_agent_start`, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook plugin і підтримуваних директорій hook, наданих bundle. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небудовані bundled plugins можуть читати сирий вміст розмови з типізованих hook, як-от `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довірити цьому plugin запитувати per-run перевизначення `provider` і `model` для фонових запусків subagent. +- `plugins.entries..subagent.allowedModels`: необов'язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. +- `plugins.entries..config`: об'єкт конфігурації, визначений plugin (валідується нативною схемою plugin OpenClaw, коли доступна). +- Налаштування акаунта/runtime channel plugin розміщені в `channels.` і мають описуватися метаданими `channelConfigs` маніфесту plugin-власника, а не центральним реєстром опцій OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. + - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Резервно використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або змінну env `FIRECRAWL_API_KEY`. + - `baseUrl`: базовий URL API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`; self-hosted перевизначення мають вказувати на приватні/внутрішні endpoints). + - `onlyMainContent`: витягувати зі сторінок лише основний вміст (за замовчуванням: `true`). + - `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні). + - `timeoutSeconds`: timeout запиту scrape в секундах (за замовчуванням: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). + - `model`: модель Grok для використання в пошуку (наприклад, `"grok-4-1-fast"`). - `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - - `enabled`: головний перемикач dreaming (стандартно `false`). - - `frequency`: cron cadence для кожного повного проходу dreaming (`"0 3 * * *"` стандартно). - - `model`: необов’язкове перевизначення моделі subagent Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. Помилки недоступності моделі повторюються один раз зі стандартною моделлю сесії; збої довіри або allowlist не виконують silent fallback. - - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті розміщена в [Довідник конфігурації пам’яті](/uk/reference/memory-config): + - `enabled`: головний перемикач dreaming (за замовчуванням `false`). + - `frequency`: cron-періодичність для кожного повного проходу dreaming (`"0 3 * * *"` за замовчуванням). + - `model`: необов'язкове перевизначення моделі subagent Dream Diary. Потребує `plugins.entries.memory-core.subagent.allowModelOverride: true`; поєднуйте з `allowedModels`, щоб обмежити цілі. Помилки недоступності моделі повторюються один раз із моделлю сеансу за замовчуванням; збої довіри або allowlist не мають тихого fallback. + - політика фаз і пороги є деталями реалізації (не user-facing ключами конфігурації). +- Повна конфігурація пам'яті розміщена в [Довідці з конфігурації пам'яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Claude bundle plugins також можуть додавати вбудовані стандартні налаштування Pi з `settings.json`; OpenClaw застосовує їх як sanitized налаштування агента, а не як raw patches конфігурації OpenClaw. -- `plugins.slots.memory`: виберіть id активного memory plugin або `"none"`, щоб вимкнути memory plugins. -- `plugins.slots.contextEngine`: виберіть id активного context engine plugin; стандартно `"legacy"`, якщо ви не встановите й не виберете інший engine. +- Увімкнені Claude bundle plugins також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного memory plugin або `"none"`, щоб вимкнути memory plugins. +- `plugins.slots.contextEngine`: вибрати id активного context engine plugin; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший engine. Див. [Plugins](/uk/tools/plugin). @@ -277,53 +276,53 @@ bundled каналів (автентифікація, контроль дост ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли - сеанс перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб +- `tabCleanup` звільняє відстежувані вкладки основного агента після часу простою або коли сеанс + перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація браузера за замовчуванням лишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте браузерній навігації в приватній мережі. -- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватних мереж під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація браузера за замовчуванням залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера приватною мережею. +- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності та виявлення. +- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. - Віддалені профілі працюють лише в режимі підключення (запуск/зупинка/скидання вимкнені). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), - коли ваш провайдер надає прямий URL DevTools WebSocket. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до перевірки доступності віддалених і - `attachOnly` CDP, а також до запитів відкриття вкладок. Керовані профілі loopback - зберігають локальні стандартні значення CDP. + коли ваш провайдер надає прямий URL WebSocket DevTools. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддаленої та + `attachOnly` доступності CDP, а також до запитів відкриття вкладок. Керовані профілі + loopback зберігають локальні стандартні значення CDP. - Якщо зовнішньо керована служба CDP доступна через loopback, установіть для цього - профілю `attachOnly: true`; інакше OpenClaw трактує порт loopback як + профілю `attachOnly: true`; інакше OpenClaw розглядатиме порт loopback як локально керований профіль браузера й може повідомляти про помилки володіння локальним портом. - Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на - вибраному хості або через підключений вузол браузера. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний + вибраному хості або через підключений браузерний вузол. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на певний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання CSS-селекторами, хуки завантаження - одного файла, без перевизначень таймауту діалогів, без `wait --load networkidle` і без + дії на основі snapshot/ref замість націлювання CSS-селектором, хуки завантаження + одного файлу, без перевизначень тайм-аутів діалогів, без `wait --load networkidle` і без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. -- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно - задавайте `cdpUrl` лише для віддаленого CDP. -- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний +- Локально керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; задавайте + `cdpUrl` явно лише для віддаленого CDP. +- Локально керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший у Brave. -- Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP +- Локально керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP після запуску процесу та `browser.localCdpReadyTimeoutMs` для - готовності CDP WebSocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome - запускається успішно, але перевірки готовності випереджають запуск. Обидва значення мають бути + готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome + успішно запускається, але перевірки готовності змагаються зі стартом. Обидва значення мають бути додатними цілими числами до `120000` мс; недійсні значення конфігурації відхиляються. - Порядок автовиявлення: стандартний браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - `browser.executablePath` і `browser.profiles..executablePath` обидва приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium. - `userDataDir` для кожного профілю в профілях `existing-session` також розгортається з тильдою. -- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). + `userDataDir` для кожного профілю на профілях `existing-session` також розгортається з тильдою. +- Служба керування: лише loopback (порт виводиться з `gateway.port`, стандартно `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад `--disable-gpu`, розмір вікна або прапорці налагодження). --- -## Інтерфейс користувача +## UI ```json5 { @@ -337,8 +336,8 @@ bundled каналів (автентифікація, контроль дост } ``` -- `seamColor`: акцентний колір для хрому інтерфейсу нативного застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності Control UI. Повертається до ідентичності активного агента. +- `seamColor`: акцентний колір для хрому UI нативного застосунку (відтінок бульбашки Talk Mode тощо). +- `assistant`: перевизначення ідентичності Control UI. Відступає до ідентичності активного агента. --- @@ -413,66 +412,74 @@ bundled каналів (автентифікація, контроль дост } ``` - + -- `mode`: `local` (запустити gateway) або `remote` (під'єднатися до віддаленого gateway). Gateway відмовиться запускатися, якщо значення не `local`. +- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо значення не `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типовий bind `loopback` слухає на `127.0.0.1` усередині контейнера. З мережевим мостом Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host` або задайте `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Автентифікація**: потрібна за замовчуванням. Bind не на loopback вимагає автентифікації gateway. На практиці це означає спільний токен/пароль або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRefs), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки запуску та встановлення/ремонту служби завершуються помилкою, коли обидва значення налаштовані, а режим не заданий. -- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених налаштувань local loopback; це навмисно не пропонується в підказках онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегує автентифікацію браузера/користувача reverse proxy з урахуванням ідентичності та довіряє заголовкам ідентичності з `gateway.trustedProxies` (див. [Автентифікація довіреного proxy](/uk/gateway/trusted-proxy-auth)). Цей режим типово очікує джерело proxy **не з loopback**; reverse proxy same-host loopback вимагають явного `gateway.auth.trustedProxy.allowLoopback = true`. Внутрішні виклики same-host можуть використовувати `gateway.auth.password` як локальний прямий fallback; `gateway.auth.token` залишається взаємовиключним із режимом trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію інтерфейсу керування/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю автентифікацію через заголовки Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей потік без токена припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов'язковий обмежувач невдалих автентифікацій. Застосовується для кожної IP-адреси клієнта та кожної області автентифікації (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху інтерфейсу керування Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні невдалі спроби від того самого клієнта можуть спрацювати на обмежувачі вже на другому запиті, замість того щоб обидві пройшли як прості невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово `true`; задайте `false`, коли навмисно хочете також обмежувати трафік localhost (для тестових налаштувань або суворих proxy-розгортань). -- Спроби WS-автентифікації з browser-origin завжди обмежуються з вимкненим винятком для loopback (захист у глибину проти браузерного brute force на localhost). -- На loopback такі блокування browser-origin ізольовані за нормалізованим значенням `Origin`, тому повторні помилки з одного origin localhost не блокують автоматично інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує автентифікації). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для WebSocket-підключень Gateway. Потрібен, коли очікуються браузерні клієнти з origin не на loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback origin за заголовком Host для розгортань, що навмисно покладаються на політику origin за заголовком Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: break-glass перевизначення на стороні клієнтського середовища процесу, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типове значення для plaintext залишається лише loopback. Еквівалента в `openclaw.json` немає, а приватномережеві налаштування браузера, такі як `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливають на WebSocket-клієнтів Gateway. -- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують автентифікацію gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього APNs relay, який використовується офіційними/TestFlight iOS-збірками після публікації реєстрацій із relay-backed до gateway. Цей URL має збігатися з URL relay, скомпільованим у iOS-збірку. -- `gateway.push.apns.relay.timeoutMs`: timeout надсилання від gateway до relay у мілісекундах. Типово `10000`. -- Реєстрації relay-backed делегуються конкретній ідентичності gateway. Спарений iOS-застосунок отримує `gateway.identity.get`, включає цю ідентичність до реєстрації relay та пересилає gateway scoped для реєстрації дозвіл на надсилання. Інший gateway не може повторно використати цю збережену реєстрацію. +- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: типовий bind `loopback` слухає на `127.0.0.1` всередині контейнера. З мережевим мостом Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Автентифікація**: типово обов’язкова. Bind не на loopback вимагає автентифікації gateway. На практиці це означає спільний токен/пароль або reverse proxy з підтримкою ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує токен. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (зокрема SecretRefs), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки запуску та встановлення/ремонту служби завершуються помилкою, коли обидва параметри налаштовані, а режим не задано. +- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених налаштувань local loopback; це навмисно не пропонується підказками онбордингу. +- `gateway.auth.mode: "trusted-proxy"`: делегує автентифікацію браузера/користувача reverse proxy з підтримкою ідентичності та довіряє заголовкам ідентичності з `gateway.trustedProxies` (див. [Автентифікація через довірений proxy](/uk/gateway/trusted-proxy-auth)). Цей режим типово очікує джерело proxy **не на loopback**; reverse proxy на loopback того самого хоста вимагають явного `gateway.auth.trustedProxy.allowLoopback = true`. Внутрішні виклики з того самого хоста можуть використовувати `gateway.auth.password` як локальний прямий резервний варіант; `gateway.auth.token` залишається взаємовиключним із режимом trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію інтерфейсу керування/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю автентифікацію заголовками Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей потік без токена припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожної IP-адреси клієнта та кожної області автентифікації (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху інтерфейсу керування Tailscale Serve невдалі спроби для тієї самої пари `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати обмежувачем уже на другому запиті, замість того щоб обидві пройшли як прості невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; задайте `false`, коли навмисно хочете обмежувати частоту й для localhost-трафіку (для тестових налаштувань або суворих розгортань proxy). +- Спроби автентифікації WS з браузерного origin завжди обмежуються з вимкненим винятком для loopback (додатковий захист від браузерного перебору localhost). +- На loopback такі блокування з браузерного origin ізольовані за нормалізованим значенням `Origin`, + тому повторні помилки з одного localhost-origin не блокують автоматично + інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний, вимагає автентифікації). +- `controlUi.allowedOrigins`: явний список дозволених браузерних origin для підключень WebSocket до Gateway. Обов’язковий, коли очікуються браузерні клієнти з origin не на loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення origin за заголовком Host для розгортань, які навмисно покладаються на політику origin за заголовком Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення середовища процесу на боці клієнта, + яке дозволяє plaintext `ws://` до довірених IP приватної мережі; + типово plaintext лишається дозволеним лише для loopback. Еквівалента в `openclaw.json` + немає, а конфігурація приватної мережі браузера, така як + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів + WebSocket Gateway. +- `gateway.remote.token` / `.password` — поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію gateway. +- `gateway.push.apns.relay.baseUrl`: базова HTTPS-URL для зовнішнього relay APNs, який використовується офіційними/TestFlight збірками iOS після публікації реєстрацій із підтримкою relay до gateway. Ця URL має збігатися з URL relay, скомпільованою в iOS-збірку. +- `gateway.push.apns.relay.timeoutMs`: таймаут надсилання від gateway до relay у мілісекундах. Типово `10000`. +- Реєстрації з підтримкою relay делегуються конкретній ідентичності gateway. Спарений iOS-застосунок отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає gateway дозвіл надсилання, обмежений реєстрацією. Інший gateway не може повторно використати цю збережену реєстрацію. - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch лише для розробки для loopback HTTP URL relay. Production URL relay мають залишатися на HTTPS. -- `gateway.handshakeTimeoutMs`: timeout pre-auth WebSocket handshake Gateway у мілісекундах. Типово: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` має пріоритет, коли задано. Збільште це значення на навантажених або малопотужних хостах, де локальні клієнти можуть під'єднуватися, поки startup warmup ще стабілізується. -- `gateway.channelHealthCheckMinutes`: інтервал health-monitor каналу у хвилинах. Задайте `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг stale-socket у хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor для каналу/акаунта в ковзну годину. Типово: `10`. -- `channels..healthMonitor.enabled`: opt-out для окремого каналу від перезапусків health-monitor, зберігаючи глобальний монітор увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого акаунта в багатоканальних каналах. Коли задано, воно має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв'язано, розв'язання завершується закритою відмовою (без маскування remote fallback). -- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або ін'єктують заголовки forwarded-client. Вказуйте лише proxy, які ви контролюєте. Записи loopback усе ще чинні для same-host proxy/local-detection налаштувань (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний обхід для HTTP-URL relay на loopback. Production-URL relay мають залишатися на HTTPS. +- `gateway.handshakeTimeoutMs`: таймаут WebSocket-рукостискання Gateway до автентифікації в мілісекундах. Типово: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` має пріоритет, коли задано. Збільшуйте це значення на навантажених або малопотужних хостах, де локальні клієнти можуть підключатися, поки прогрів запуску ще стабілізується. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Задайте `0`, щоб глобально вимкнути перезапуски монітора стану. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис у ковзній годині. Типово: `10`. +- `channels..healthMonitor.enabled`: вимкнення перезапусків монітора стану для окремого каналу з увімкненим глобальним монітором. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Коли задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резерв лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується закрито (без маскування віддаленим резервом). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Вказуйте лише proxy, які ви контролюєте. Записи loopback усе ще чинні для налаштувань proxy/локального виявлення на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs`: необов'язковий CIDR/IP allowlist для автоматичного схвалення першого спарювання node-пристрою без запитаних scopes. Вимкнено, коли не задано. Це не схвалює автоматично спарювання оператора/браузера/інтерфейсу керування/WebChat і не схвалює автоматично оновлення role, scope, metadata або public-key. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне allow/deny shaping для оголошених команд node після спарювання та оцінювання platform allowlist. Використовуйте `allowCommands`, щоб увімкнути небезпечні команди node, як-от `camera.snap`, `camera.clip` і `screen.record`; `denyCommands` вилучає команду, навіть якщо platform default або явний allow інакше включив би її. Після того як node змінює свій оголошений список команд, відхиліть і повторно схваліть це спарювання пристрою, щоб gateway зберіг оновлений command snapshot. -- `gateway.tools.deny`: додаткові назви tool, заблоковані для HTTP `POST /tools/invoke` (розширює default deny list). -- `gateway.tools.allow`: вилучає назви tool зі стандартного HTTP deny list. +- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання пристрою node без запитаних scopes. Вимкнено, коли не задано. Це не схвалює автоматично спарювання оператора/браузера/інтерфейсу керування/вебчату, а також не схвалює автоматично оновлення ролі, scope, metadata або публічного ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд node після спарювання та оцінки списку дозволеного платформою. Використовуйте `allowCommands`, щоб увімкнути небезпечні команди node, як-от `camera.snap`, `camera.clip` і `screen.record`; `denyCommands` вилучає команду, навіть якщо типовий дозвіл платформи або явний allow інакше включив би її. Після того як node змінює свій оголошений список команд, відхиліть і повторно схваліть спарювання цього пристрою, щоб gateway зберіг оновлений знімок команд. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). +- `gateway.tools.allow`: вилучити назви інструментів із типового списку HTTP-заборон. ### OpenAI-сумісні кінцеві точки -- Chat Completions: вимкнено за замовчуванням. Увімкніть за допомогою `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: типово вимкнено. Увімкніть за допомогою `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилення захисту URL-входу Responses: +- Посилення безпеки URL-вводу Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlists вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов'язковий заголовок посилення захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS origins, які ви контролюєте; див. [Автентифікація довіреного proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні списки дозволених вважаються незаданими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посилення безпеки відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, які ви контролюєте; див. [Автентифікація через довірений proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів -Запускайте кілька gateways на одному хості з унікальними портами та state dirs: +Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -482,7 +489,7 @@ openclaw gateway --port 19001 Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Кілька Gateways](/uk/gateway/multiple-gateways). +Див. [Кілька Gateway](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -500,11 +507,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на listener gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовані; лише для local/dev використання. -- `certPath`: шлях файлової системи до файлу TLS certificate. -- `keyPath`: шлях файлової системи до файлу TLS private key; тримайте дозволи обмеженими. -- `caPath`: необов'язковий шлях до CA bundle для перевірки клієнта або custom trust chains. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару сертифікат/ключ, коли явні файли не налаштовані; лише для локального використання/розробки. +- `certPath`: шлях у файловій системі до файлу TLS-сертифіката. +- `keyPath`: шлях у файловій системі до файлу приватного TLS-ключа; тримайте права доступу обмеженими. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнтів або власних ланцюгів довіри. ### `gateway.reload` @@ -520,17 +527,17 @@ openclaw gateway --port 19001 } ``` -- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати live edits; зміни потребують явного restart. - - `"restart"`: завжди restart процес gateway при зміні конфігурації. - - `"hot"`: застосовувати зміни in-process без restart. - - `"hybrid"` (типово): спочатку спробувати hot reload; fallback до restart, якщо потрібно. -- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід'ємне ціле число). -- `deferralTimeoutMs`: необов'язковий максимальний час у мс для очікування in-flight операцій перед примусовим restart. Опустіть його, щоб використовувати типове обмежене очікування (`300000`); задайте `0`, щоб чекати необмежено довго та періодично логувати попередження still-pending. +- `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. + - `"off"`: ігнорувати live-зміни; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway у разі зміни конфігурації. + - `"hot"`: застосовувати зміни в процесі без перезапуску. + - `"hybrid"` (типово): спочатку спробувати гаряче перезавантаження; за потреби перейти до перезапуску. +- `debounceMs`: debounce-вікно в мс перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: необов’язковий максимальний час у мс для очікування операцій у процесі перед примусовим перезапуском. Не вказуйте, щоб використати типове обмежене очікування (`300000`); задайте `0`, щоб чекати безстроково й періодично записувати попередження про ще незавершені операції. --- -## Hooks +## Хуки ```json5 { @@ -564,46 +571,47 @@ openclaw gateway --port 19001 ``` Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook у query-string відхиляються. +Токени hook у рядку запиту відхиляються. -Примітки щодо перевірки та безпеки: +Примітки щодо валідації та безпеки: -- `hooks.enabled=true` потребує непорожнього `hooks.token`. +- `hooks.enabled=true` вимагає непорожнього `hooks.token`. - `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо зіставлення або пресет використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі зіставлення не потребують цього явного ввімкнення. +- Якщо зіставлення або пресет використовує шаблонний `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі зіставлення не потребують такого opt-in. **Кінцеві точки:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` з корисного навантаження запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`). -- `POST /hooks/` → визначається через `hooks.mappings` - - Значення `sessionKey` зіставлення, відрендерені з шаблону, вважаються наданими зовні й також потребують `hooks.allowRequestSessionKey=true`. + - `sessionKey` з payload запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`). +- `POST /hooks/` → розв'язується через `hooks.mappings` + - Значення `sessionKey` зіставлення, відрендерені шаблоном, вважаються наданими ззовні й також потребують `hooks.allowRequestSessionKey=true`. - + - `match.path` зіставляє підшлях після `/hooks` (наприклад `/hooks/gmail` → `gmail`). -- `match.source` зіставляє поле корисного навантаження для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають дані з корисного навантаження. -- `transform` може вказувати на модуль JS/TS, який повертає дію хуку. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та обхід каталогів відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ідентифікатори повертаються до типового. +- `match.source` зіставляє поле payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають із payload. +- `transform` може вказувати на JS/TS-модуль, який повертає дію hook. + - `transform.module` має бути відносним шляхом і лишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). + - Тримайте `hooks.transformsDir` у `~/.openclaw/hooks/transforms`; директорії Skills у workspace відхиляються. Якщо `openclaw doctor` повідомляє, що цей шлях недійсний, перемістіть модуль transform у директорію hooks transforms або приберіть `hooks.transformsDir`. +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового. - `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків агента хука без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і керованим шаблонами ключам сесій зіставлень задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-яке зіставлення або пресет використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`. -- `model` перевизначає LLM для цього запуску хука (має бути дозволено, якщо задано каталог моделей). +- `defaultSessionKey`: необов'язковий фіксований ключ сесії для запусків агента hook без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і керованим шаблонами ключам сесії зіставлення задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов'язковий allowlist префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. Він стає обов'язковим, коли будь-яке зіставлення або пресет використовує шаблонний `sessionKey`. +- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). ### Інтеграція Gmail - Вбудований пресет Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте пресет статичним `sessionKey` замість типового шаблонізованого значення. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` відповідно до простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте пресет статичним `sessionKey` замість типового шаблонного значення. ```json5 { @@ -627,11 +635,11 @@ openclaw gateway --port 19001 ``` - Gateway автоматично запускає `gog gmail watch serve` під час завантаження, коли це налаштовано. Задайте `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. -- Не запускайте окремий `gog gmail watch serve` поруч із Gateway. +- Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- -## Хост canvas +## Хост Canvas ```json5 { @@ -643,18 +651,18 @@ openclaw gateway --port 19001 } ``` -- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway: +- Обслуговує доступні для редагування агентом HTML/CSS/JS і A2UI через HTTP під портом Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: залиште `gateway.bind: "loopback"` (типово). -- Прив’язки не до loopback: маршрути canvas потребують автентифікації Gateway (токен/пароль/довірений проксі), як і інші HTTP-поверхні Gateway. -- Node WebViews зазвичай не надсилають заголовки автентифікації; після спарювання та підключення вузла Gateway оголошує URL-адреси можливостей, обмежені вузлом, для доступу до canvas/A2UI. -- URL-адреси можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Резервний варіант на основі IP не використовується. -- Ін’єктує клієнт live-reload в обслуговуваний HTML. -- Автоматично створює стартовий `index.html`, коли каталог порожній. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Прив'язки не до loopback: маршрути canvas потребують автентифікації Gateway (токен/пароль/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки автентифікації; після pairing і підключення node Gateway оголошує URL можливостей, scoped до node, для доступу до canvas/A2UI. +- URL можливостей прив'язані до активної WS-сесії node і швидко закінчуються. Fallback на основі IP не використовується. +- Вставляє клієнт live-reload в обслуговуваний HTML. +- Автоматично створює стартовий `index.html`, коли порожньо. - Також обслуговує A2UI за `/__openclaw__/a2ui/`. -- Зміни потребують перезапуску Gateway. -- Вимкніть live reload для великих каталогів або помилок `EMFILE`. +- Зміни потребують перезапуску gateway. +- Вимикайте live reload для великих директорій або помилок `EMFILE`. --- @@ -672,11 +680,11 @@ openclaw gateway --port 19001 } ``` -- `minimal` (типово): не включати `cliPath` + `sshPort` до TXT-записів. +- `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. - `full`: включати `cliPath` + `sshPort`. -- Ім’я хоста типово дорівнює системному імені хоста, якщо воно є коректною DNS-міткою, інакше використовується `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. +- Ім'я хоста типово дорівнює системному імені хоста, коли воно є дійсною DNS-міткою, і повертається до `openclaw` інакше. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. -### Глобальна зона (DNS-SD) +### Wide-area (DNS-SD) ```json5 { @@ -694,7 +702,7 @@ openclaw gateway --port 19001 ## Середовище -### `env` (вбудовані змінні середовища) +### `env` (inline змінні середовища) ```json5 { @@ -711,14 +719,14 @@ openclaw gateway --port 19001 } ``` -- Inline-змінні середовища застосовуються лише якщо в середовищі процесу бракує ключа. +- Inline змінні середовища застосовуються лише якщо в process env відсутній ключ. - Файли `.env`: CWD `.env` + `~/.openclaw/.env` (жоден не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Див. [Середовище](/uk/help/environment) для повного порядку пріоритетності. +- `shellEnv`: імпортує відсутні очікувані ключі з вашого профілю login shell. +- Див. [Середовище](/uk/help/environment) для повного пріоритету. ### Підстановка змінних середовища -Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -730,18 +738,18 @@ openclaw gateway --port 19001 - Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте за допомогою `$${VAR}` для літерального `${VAR}`. +- Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є адитивними: значення відкритим текстом усе ще працюють. +Посилання на секрети є additive: plaintext значення все ще працюють. ### `SecretRef` -Використовуйте одну форму об’єкта: +Використовуйте одну форму об'єкта: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -749,19 +757,19 @@ openclaw gateway --port 19001 Валідація: -- Шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- Шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- id для `source: "file"`: абсолютний JSON-вказівник (наприклад `"/providers/openai/apiKey"`) -- Шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id для `source: "exec"` не мають містити сегменти шляху, розділені скісними рисками, `.` або `..` (наприклад `a/../b` відхиляється) +- шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` +- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- id для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- id для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені скісними рисками (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) -- Цілі `secrets apply` підтримують шляхи облікових даних `openclaw.json`. -- Посилання `auth-profiles.json` включено до runtime-розв’язання й покриття аудиту. +- `secrets apply` націлюється на підтримувані шляхи облікових даних `openclaw.json`. +- Посилання `auth-profiles.json` включені в runtime resolution і audit coverage. -### Конфігурація провайдерів секретів +### Конфігурація постачальників секретів ```json5 { @@ -789,16 +797,16 @@ openclaw gateway --port 19001 } ``` -Нотатки: +Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). -- Шляхи провайдерів file та exec завершуються закрито, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує протокольні payload-и через stdin/stdout. -- За замовчуванням шляхи команд через symlink відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink, водночас валідуючи розв’язаний цільовий шлях. -- Якщо налаштовано `trustedDirs`, перевірка довіреного каталогу застосовується до розв’язаного цільового шляху. -- Дочірнє середовище `exec` за замовчуванням мінімальне; явно передавайте потрібні змінні через `passEnv`. -- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях зривають запуск/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` в режимі singleValue). +- Шляхи провайдерів file і exec fail closed, коли перевірка Windows ACL недоступна. Задавайте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` вимагає абсолютного шляху `command` і використовує protocol payloads через stdin/stdout. +- Типово symlink шляхи команд відхиляються. Задайте `allowSymlinkCommand: true`, щоб дозволити symlink шляхи під час валідації розв'язаного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв'язаного цільового шляху. +- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети розв'язуються під час активації в in-memory snapshot, після чого шляхи запитів читають лише snapshot. +- Фільтрація active-surface застосовується під час активації: нерозв'язані посилання на ввімкнених поверхнях зупиняють startup/reload з помилкою, тоді як неактивні поверхні пропускаються з diagnostics. --- @@ -821,11 +829,11 @@ openclaw gateway --port 19001 ``` - Профілі для кожного агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. +- `auth-profiles.json` підтримує refs на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. - Застарілі плоскі мапи `auth-profiles.json`, як-от `{ "provider": { "apiKey": "..." } }`, не є runtime-форматом; `openclaw doctor --fix` переписує їх у канонічні API-key-профілі `provider:default` із резервною копією `.legacy-flat.*.bak`. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. -- Статичні runtime-облікові дані походять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` видаляються під час виявлення. -- Застарілі імпорти OAuth беруться з `~/.openclaw/credentials/oauth.json`. +- Профілі в OAuth-режимі (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. +- Статичні runtime облікові дані надходять з in-memory resolved snapshots; застарілі статичні записи `auth.json` очищаються, коли їх виявлено. +- Застарілі OAuth імпорти з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). - Runtime-поведінка секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). @@ -849,24 +857,19 @@ openclaw gateway --port 19001 } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - помилки billing/недостатнього кредиту (за замовчуванням: `5`). Явний текст billing може - все ще потрапити сюди навіть у відповідях `401`/`403`, але специфічні для провайдера текстові - зіставлювачі лишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані HTTP `402` usage-window або - повідомлення про ліміт витрат організації/робочого простору натомість лишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для кожного провайдера. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (за замовчуванням: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високонадійних збоїв `auth_permanent` (за замовчуванням: `10`). -- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (за замовчуванням: `60`). -- `failureWindowHours`: рухоме вікно в годинах, що використовується для лічильників backoff (за замовчуванням: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед перемиканням на запасну модель (за замовчуванням: `1`). Форми зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють сюди. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate-limit перед перемиканням на запасну модель (за замовчуванням: `1`). Цей bucket rate-limit містить текст у формі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг усе ще може потрапити сюди навіть у відповідях `401`/`403`, але специфічні для провайдера текстові зіставлення залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Повідомлення повторюваного HTTP `402` про вікно використання або ліміти витрат організації/робочого простору натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу за провайдерами. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високодостовірних збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: рухоме вікно в годинах, що використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій профілів автентифікації того самого провайдера для помилок ліміту частоти перед перемиканням на резервну модель (типово: `1`). Цей кошик ліміту частоти включає текст у форматі провайдера, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- -## Логування +## Журналювання ```json5 { @@ -884,8 +887,8 @@ openclaw gateway --port 19001 - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Задайте `logging.file` для стабільного шляху. - `consoleLevel` підвищується до `debug`, коли використано `--verbose`. -- `maxFileBytes`: максимальний розмір активного файлу журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 МБ). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. -- `redactSensitive` / `redactPatterns`: маскування за принципом найкращих зусиль для виводу в консоль, файлових журналів, записів журналу OTLP і збереженого тексту стенограми сеансу. `redactSensitive: "off"` вимикає лише цю загальну політику журналів/стенограм; поверхні безпеки UI/інструментів/діагностики все одно редагують секрети перед випуском. +- `maxFileBytes`: максимальний розмір активного файла журналу в байтах перед ротацією (додатне ціле число; типово: `104857600` = 100 MB). OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом. +- `redactSensitive` / `redactPatterns`: маскування за найкращим зусиллям для виводу консолі, файлових журналів, записів журналів OTLP і збереженого тексту транскрипту сесії. `redactSensitive: "off"` вимикає лише цю загальну політику журналів/транскриптів; поверхні безпеки UI/інструментів/діагностики все одно редагують секрети перед виведенням. --- @@ -933,23 +936,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`: головний перемикач для виводу інструментації (типово: `true`). -- `flags`: масив рядків прапорів, які вмикають цільовий вивід журналів (підтримує символи узагальнення, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку без прогресу в мс для класифікації тривалих сеансів обробки як `session.long_running`, `session.stalled` або `session.stuck`. Відповідь, інструмент, статус, блок і прогрес ACP скидають таймер; повторні діагностичні повідомлення `session.stuck` відступають, доки стан не змінюється. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. в [експорті OpenTelemetry](/uk/gateway/opentelemetry). -- `otel.endpoint`: URL збирача для експорту OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові кінцеві точки OTLP для окремих сигналів. Якщо задано, вони перевизначають `otel.endpoint` лише для цього сигналу. +- `enabled`: головний перемикач для виводу інструментування (типово: `true`). +- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналів (підтримує шаблони на кшталт `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку без прогресу в мс для класифікації довготривалих сесій обробки як `session.long_running`, `session.stalled` або `session.stuck`. Відповідь, інструмент, статус, блок і прогрес ACP скидають таймер; повторна діагностика `session.stuck` виконує backoff, доки стан не змінюється. +- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель приватності див. у [експорті OpenTelemetry](/uk/gateway/opentelemetry). +- `otel.endpoint`: URL колектора для експорту OTel. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: необов’язкові OTLP-ендпоїнти для конкретних сигналів. Коли задано, вони перевизначають `otel.endpoint` лише для цього сигналу. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. - `otel.serviceName`: назва сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт трас, метрик або журналів. -- `otel.sampleRate`: частота вибірки трас `0`–`1`. -- `otel.flushIntervalMs`: періодичний інтервал скидання телеметрії в мс. -- `otel.captureContent`: увімкнення захоплення сирого вмісту для атрибутів проміжків OTEL. Типово вимкнено. Булеве `true` захоплює несистемний вміст повідомлень/інструментів; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів постачальника проміжків GenAI. Типово проміжки зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. -- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/зупинку SDK, яким володіє Plugin, залишаючи діагностичні слухачі активними. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища кінцевих точок для окремих сигналів, які використовуються, коли відповідний ключ конфігурації не задано. -- `cacheTrace.enabled`: записувати знімки трасування кешу для вбудованих запусків (типово: `false`). +- `otel.sampleRate`: частота семплювання трас `0`–`1`. +- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. +- `otel.captureContent`: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве `true` захоплює несистемний вміст повідомлень/інструментів; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. Типово spans зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути. +- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, зберігаючи діагностичні слухачі активними. +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` і `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: змінні середовища для ендпоїнтів конкретних сигналів, що використовуються, коли відповідний ключ конфігурації не задано. +- `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). - `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). @@ -973,12 +976,12 @@ openclaw gateway --port 19001 } ``` -- `channel`: канал випусків для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `channel`: канал випуску для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. - `checkOnStart`: перевіряти оновлення npm під час запуску Gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням у стабільному каналі (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання стабільного каналу в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки бета-каналу в годинах (типово: `1`; максимум: `24`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; макс.: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; макс.: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; макс.: `24`). --- @@ -1011,23 +1014,23 @@ openclaw gateway --port 19001 } ``` -- `enabled`: глобальний шлюз функції ACP (типово: `true`; задайте `false`, щоб приховати можливості диспетчеризації та створення ACP). -- `dispatch.enabled`: незалежний шлюз для диспетчеризації ходу сеансу ACP (типово: `true`). Задайте `false`, щоб залишити команди ACP доступними, блокуючи виконання. -- `backend`: типовий ідентифікатор бекенду середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP). - Спочатку встановіть бекенд-Plugin, а якщо задано `plugins.allow`, додайте ідентифікатор бекенд-Plugin (наприклад `acpx`), інакше бекенд ACP не завантажиться. -- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли створення не вказує явну ціль. -- `allowedAgents`: список дозволених ідентифікаторів агентів для сеансів середовища виконання ACP; порожній означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сеансів ACP. -- `stream.coalesceIdleMs`: вікно скидання під час простою в мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір фрагмента перед поділом проєкції потокового блоку. -- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів на хід (типово: `true`). -- `stream.deliveryMode`: `"live"` транслює інкрементально; `"final_only"` буферизує до завершальних подій ходу. -- `stream.hiddenBoundarySeparator`: розділювач перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується на хід ACP. +- `enabled`: глобальний feature gate ACP (типово: `true`; задайте `false`, щоб приховати dispatch ACP і можливості spawn). +- `dispatch.enabled`: незалежний gate для dispatch ходу сесії ACP (типово: `true`). Задайте `false`, щоб зберегти команди ACP доступними, але заблокувати виконання. +- `backend`: стандартний ідентифікатор бекенда середовища виконання ACP (має збігатися із зареєстрованим Plugin середовища виконання ACP). + Спочатку встановіть Plugin бекенда, і якщо задано `plugins.allow`, додайте ідентифікатор Plugin бекенда (наприклад `acpx`), інакше бекенд ACP не завантажиться. +- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawns не вказують явну ціль. +- `allowedAgents`: allowlist ідентифікаторів агентів, дозволених для сесій середовища виконання ACP; порожній означає відсутність додаткового обмеження. +- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. +- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір фрагмента перед поділом проєкції потокового блока. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів за хід (типово: `true`). +- `stream.deliveryMode`: `"live"` транслює інкрементально; `"final_only"` буферизує до термінальних подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за хід ACP. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис назв тегів у булеві перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: TTL простою в хвилинах для робітників сеансів ACP перед тим, як вони стануть придатними до очищення. -- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час початкового налаштування середовища виконання ACP. +- `stream.tagVisibility`: запис імен тегів у булеві перевизначення видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для працівників сесії ACP перед тим, як вони стають придатними для очищення. +- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища виконання ACP. --- @@ -1043,11 +1046,11 @@ openclaw gateway --port 19001 } ``` -- `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (типово): змінні смішні/сезонні слогани. - - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (не лише слогани), задайте env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем tagline банера: + - `"random"` (типово): змінні смішні/сезонні taglines. + - `"default"`: фіксована нейтральна tagline (`All your chats, one OpenClaw.`). + - `"off"`: без тексту tagline (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише taglines), задайте env `OPENCLAW_HIDE_BANNER=1`. --- @@ -1071,15 +1074,15 @@ openclaw gateway --port 19001 ## Ідентичність -Див. поля ідентичності `agents.list` у [типових значеннях агента](/uk/gateway/config-agents#agent-defaults). +Див. поля ідентичності `agents.list` у [стандартних налаштуваннях агента](/uk/gateway/config-agents#agent-defaults). --- -## Bridge (застаріле, вилучено) +## Міст (застарілий, вилучено) -Поточні збірки більше не містять TCP bridge. Node-и підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (перевірка не проходить, доки їх не вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP-міст. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація не проходить, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -1117,11 +1120,11 @@ openclaw gateway --port 19001 } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сеанси запусків Cron перед обрізанням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типово: `24h`; задайте `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір на файл журналу запуску (`cron/runs/.jsonl`) перед обрізанням. Типово: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, що зберігаються, коли спрацьовує обрізання журналу запуску. Типово: `2000`. -- `webhookToken`: bearer-токен, який використовується для доставки POST Cron Webhook (`delivery.mode = "webhook"`); якщо пропущено, заголовок авторизації не надсилається. -- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед видаленням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; задайте `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/.jsonl`) перед обрізанням. Типово: `2_000_000` байтів. +- `runLog.keepLines`: найновіші рядки, що зберігаються, коли запускається обрізання журналу запуску. Типово: `2000`. +- `webhookToken`: bearer-токен, що використовується для доставки cron webhook POST (`delivery.mode = "webhook"`); якщо пропущено, заголовок автентифікації не надсилається. +- `webhook`: застарілий резервний URL webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. ### `cron.retry` @@ -1137,11 +1140,11 @@ openclaw gateway --port 19001 } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (типово: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (за замовчуванням: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок відступу в мс для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Опустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань Cron. Повторювані завдання використовують окрему обробку збоїв. +Застосовується лише до одноразових завдань cron. Повторювані завдання використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -1160,12 +1163,12 @@ openclaw gateway --port 19001 } ``` -- `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). -- `after`: кількість послідовних збоїв перед надсиланням сповіщення (додатне ціле число, мін.: `1`). +- `enabled`: увімкнути сповіщення про збої для завдань cron (за замовчуванням: `false`). +- `after`: кількість послідовних збоїв до спрацювання сповіщення (додатне ціле число, мін.: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `includeSkipped`: зараховувати послідовні пропущені запуски до порогу сповіщення (типово: `false`). Пропущені запуски відстежуються окремо й не впливають на backoff помилок виконання. -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований Webhook. -- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження області доставки сповіщень. +- `includeSkipped`: враховувати послідовні пропущені запуски в порозі сповіщення (за замовчуванням: `false`). Пропущені запуски відстежуються окремо й не впливають на відступ після помилок виконання. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований webhook. +- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження області доставки сповіщення. ### `cron.failureDestination` @@ -1182,44 +1185,44 @@ openclaw gateway --port 19001 } ``` -- Типове призначення для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. +- Типове призначення для сповіщень про збої cron в усіх завданнях. +- `mode`: `"announce"` або `"webhook"`; за замовчуванням `"announce"`, коли є достатньо даних цілі. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму Webhook. +- `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобальне призначення для збоїв, ні призначення для окремого завдання, завдання, які вже доставляються через `announce`, у разі збою повертаються до цієї основної цілі announce. -- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний `delivery.mode` завдання не є `"webhook"`. +- `delivery.failureDestination` на рівні завдання перевизначає це глобальне значення за замовчуванням. +- Коли ні глобальне, ні задане на рівні завдання призначення збою не встановлено, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron завдання](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Завдання Cron](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). --- -## Змінні шаблонів медіамоделі +## Змінні шаблону медіамоделі Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повне тіло вхідного повідомлення | -| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Тіло з вилученими згадками групи | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Текст із вилученими згадками групи | | `{{From}}` | Ідентифікатор відправника | | `{{To}}` | Ідентифікатор призначення | | `{{MessageSid}}` | Ідентифікатор повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | | `{{IsNewSession}}` | `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Вхідний псевдо-URL медіа | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (зображення/аудіо/документ/…) | | `{{Transcript}}` | Транскрипт аудіо | | `{{Prompt}}` | Визначений медіапромпт для записів CLI | | `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}` | Тема групи (наскільки можливо) | -| `{{GroupMembers}}` | Попередній перегляд учасників групи (наскільки можливо) | -| `{{SenderName}}` | Відображуване ім’я відправника (наскільки можливо) | -| `{{SenderE164}}` | Номер телефону відправника (наскільки можливо) | +| `{{GroupSubject}}` | Тема групи (за можливості) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (за можливості) | +| `{{SenderName}}` | Відображуване ім’я відправника (за можливості) | +| `{{SenderE164}}` | Номер телефону відправника (за можливості) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- @@ -1242,19 +1245,19 @@ openclaw gateway --port 19001 **Поведінка злиття:** - Один файл: замінює об’єкт, що його містить. -- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні). +- Масив файлів: глибоко зливається по порядку (пізніші значення перевизначають попередні). - Сусідні ключі: зливаються після включень (перевизначають включені значення). - Вкладені включення: до 10 рівнів углиб. -- Шляхи: визначаються відносно файлу, що виконує включення, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми та форми з `../` дозволені лише тоді, коли вони все одно визначаються всередині цієї межі. -- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений однофайловим включенням, записуються наскрізно до цього включеного файлу. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями доступні лише для читання для записів, керованих OpenClaw; такі записи завершуються закритою помилкою замість вирівнювання конфігурації. +- Шляхи: розв’язуються відносно файлу, що виконує включення, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` файлу `openclaw.json`). Абсолютні форми або форми з `../` дозволені лише тоді, коли вони все одно розв’язуються в цих межах. +- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений включенням одного файлу, записуються наскрізно в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями є лише для читання для записів, керованих OpenClaw; такі записи завершуються закритою помилкою замість вирівнювання конфігурації. - Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних включень. --- -_Пов’язано: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Діагностика](/uk/gateway/doctor)_ -## Пов’язано +## Пов’язане - [Конфігурація](/uk/gateway/configuration) - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/plugins/dependency-resolution.md b/docs/uk/plugins/dependency-resolution.md index cc72476fc..9d208a792 100644 --- a/docs/uk/plugins/dependency-resolution.md +++ b/docs/uk/plugins/dependency-resolution.md @@ -1,16 +1,16 @@ --- read_when: - - Ви налагоджуєте встановлення пакетів плагінів - - Ви змінюєте поведінку запуску Plugin, doctor або встановлення через менеджер пакетів - - Ви супроводжуєте пакетовані інсталяції OpenClaw або маніфести Plugin, що постачаються в комплекті + - Ви налагоджуєте встановлення пакетів Plugin + - Ви змінюєте поведінку запуску Plugin, діагностики або встановлення через менеджер пакетів + - Ви супроводжуєте пакетовані інсталяції OpenClaw або маніфести вбудованих Plugin sidebarTitle: Dependencies -summary: Як OpenClaw встановлює Plugin-пакети та розв’язує залежності Plugin -title: Розв’язання залежностей Plugin +summary: Як OpenClaw встановлює пакети Plugin і розв’язує залежності Plugin +title: Вирішення залежностей Plugin x-i18n: - generated_at: "2026-05-02T02:02:07Z" + generated_at: "2026-05-02T09:29:42Z" model: gpt-5.5 provider: openai - source_hash: 43d8008c837d519fd7c886f9615ad53941da340d753b559dfb0a32877716bc1f + source_hash: c9476529ad1d44ed1b17caca628c58acfbb1d8c73393f58fa7d3d76944a71aea source_path: plugins/dependency-resolution.md workflow: 16 --- @@ -25,11 +25,11 @@ OpenClaw виконує роботу із залежностями Plugin під Пакети Plugin відповідають за власний граф залежностей: -- залежності часу виконання розміщуються в `dependencies` або +- залежності часу виконання містяться в `dependencies` або `optionalDependencies` пакета Plugin -- імпорти SDK/ядра є peer-імпортами або наданими імпортами OpenClaw -- локальні Plugin для розробки постачаються зі своїми вже встановленими залежностями -- npm і git Plugin установлюються в корені пакетів, що належать OpenClaw +- імпорти SDK/core є peer-імпортами або імпортами, наданими OpenClaw +- локальні Plugin для розробки мають власні вже встановлені залежності +- npm- і git-Plugin установлюються в корені пакетів, якими керує OpenClaw OpenClaw відповідає лише за життєвий цикл Plugin: @@ -37,54 +37,54 @@ OpenClaw відповідає лише за життєвий цикл Plugin: - установити або оновити пакет, коли це явно запитано - записати метадані встановлення - завантажити точку входу Plugin -- завершити роботу з дієвою помилкою, коли залежності відсутні +- завершити з дієвою помилкою, коли залежностей бракує ## Корені встановлення OpenClaw використовує стабільні корені для кожного джерела: -- пакети npm установлюються в `~/.openclaw/npm` -- пакети git клонуються в `~/.openclaw/git` -- локальні/шляхові/архівні встановлення копіюються або використовуються за посиланням без ремонту залежностей +- npm-пакети встановлюються в `~/.openclaw/npm` +- git-пакети клонуються в `~/.openclaw/git` +- локальні/path/archive-встановлення копіюються або використовуються за посиланням без ремонту залежностей -Встановлення npm виконуються в корені npm за допомогою: +npm-встановлення виконуються в корені npm за допомогою: ```bash npm install --prefix ~/.openclaw/npm --omit=dev --ignore-scripts --no-audit --no-fund ``` -npm може підняти транзитивні залежності до `~/.openclaw/npm/node_modules` поруч із -пакетом Plugin. OpenClaw сканує керований корінь npm перед тим, як довіряти +npm може піднімати транзитивні залежності в `~/.openclaw/npm/node_modules` поруч +із пакетом Plugin. OpenClaw сканує керований корінь npm, перш ніж довіряти встановленню, і використовує npm для видалення керованих npm пакетів під час деінсталяції, тож підняті -залежності часу виконання залишаються всередині керованої межі очищення. +залежності часу виконання залишаються в межах керованого очищення. -Встановлення git клонують або оновлюють репозиторій, а потім виконують: +git-встановлення клонують або оновлюють репозиторій, а потім виконують: ```bash npm install --omit=dev --ignore-scripts --no-audit --no-fund ``` Після цього встановлений Plugin завантажується з каталогу цього пакета, тому розв’язання -локальних для пакета та батьківських `node_modules` працює так само, як для звичайного -пакета Node. +package-local і батьківських `node_modules` працює так само, як для звичайного +Node-пакета. ## Локальні Plugin -Локальні Plugin розглядаються як каталоги, керовані розробником. OpenClaw не -виконує для них `npm install`, `pnpm install` або ремонт залежностей. Якщо локальний +Локальні Plugin розглядаються як каталоги, контрольовані розробником. OpenClaw не +запускає для них `npm install`, `pnpm install` або ремонт залежностей. Якщо локальний Plugin має залежності, установіть їх у цьому Plugin перед його завантаженням. -Сторонні локальні Plugin TypeScript можуть використовувати аварійний шлях Jiti. Запаковані -JavaScript Plugin і вбудовані внутрішні Plugin завантажуються через нативні +Сторонні локальні TypeScript-Plugin можуть використовувати аварійний шлях Jiti. Пакетовані +JavaScript-Plugin і вбудовані внутрішні Plugin завантажуються через нативний import/require замість Jiti. ## Запуск і перезавантаження Запуск Gateway і перезавантаження конфігурації ніколи не встановлюють залежності Plugin. Вони читають -записи встановлення Plugin, обчислюють точку входу та завантажують її. +записи встановлення Plugin, обчислюють точку входу й завантажують її. -Якщо залежність відсутня під час виконання, Plugin не завантажується, а помилка -має вказати оператору явне виправлення: +Якщо залежності бракує під час виконання, Plugin не завантажується, а помилка +має спрямувати оператора до явного виправлення: ```bash openclaw plugins update @@ -93,37 +93,40 @@ openclaw doctor --fix ``` `doctor --fix` може очистити застарілий стан залежностей, згенерований OpenClaw, і встановити -налаштовані завантажувані Plugin, яких немає в локальних записах встановлення. +налаштовані завантажувані Plugin, яких бракує в локальних записах встановлення. Він не ремонтує залежності для вже встановленого локального Plugin. ## Вбудовані Plugin -Легкі та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw. -Вони мають або не мати важкого дерева залежностей часу виконання, або бути винесені в -завантажуваний пакет на ClawHub/npm. +Легковагові та критично важливі для ядра вбудовані Plugin постачаються як частина OpenClaw. +Вони або не повинні мати важкого дерева залежностей часу виконання, або мають бути винесені +в завантажуваний пакет на ClawHub/npm. -Маніфести вбудованих Plugin не повинні запитувати підготовку залежностей. Велику або необов’язкову -функціональність Plugin слід пакувати як звичайний Plugin і встановлювати через +Поточний згенерований список Plugin, які постачаються в основному пакеті, встановлюються +зовнішньо або залишаються лише у вихідному коді, див. в [інвентарі Plugin](/uk/plugins/plugin-inventory). + +Маніфести вбудованих Plugin не повинні запитувати стадіювання залежностей. Велика або необов’язкова +функціональність Plugin має пакуватися як звичайний Plugin і встановлюватися через той самий шлях npm/git/ClawHub, що й сторонні Plugin. -У вихідних checkout OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після -`pnpm install` вбудовані Plugin завантажуються з `extensions/`, тож локальні для пакета -залежності workspace доступні, а зміни підхоплюються напряму. Розробка з вихідного -checkout підтримується лише з pnpm; звичайний `npm install` у корені репозиторію +У checkout-ах вихідного коду OpenClaw розглядає репозиторій як pnpm-монорепозиторій. Після +`pnpm install` вбудовані Plugin завантажуються з `extensions/`, тож package-local +залежності workspace доступні, а зміни підхоплюються напряму. Розробка в checkout-і +вихідного коду підтримується лише з pnpm; звичайний `npm install` у корені репозиторію не є підтримуваним способом підготувати залежності вбудованих Plugin. -| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей | +| Форма встановлення | Розташування вбудованого Plugin | Власник залежностей | | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- | | `npm install -g openclaw` | Побудоване дерево часу виконання всередині пакета | Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для Plugin | -| Git checkout плюс `pnpm install` | Пакети workspace `extensions/` | pnpm workspace, включно з власними залежностями кожного пакета Plugin | +| Git checkout plus `pnpm install` | Workspace-пакети `extensions/` | pnpm-workspace, включно з власними залежностями кожного пакета Plugin | | `openclaw plugins install ...` | Керований корінь Plugin npm/git/ClawHub | Потік встановлення/оновлення Plugin | ## Очищення застарілого стану Старіші версії OpenClaw генерували корені залежностей вбудованих Plugin під час запуску або -під час ремонту doctor. Поточне очищення doctor видаляє ці застарілі каталоги та -символьні посилання, коли використовується `--fix`, включно зі старими коренями `plugin-runtime-deps`, -маніфестами `.openclaw-runtime-deps*`, згенерованими `node_modules` Plugin, каталогами -етапів встановлення та локальними для пакета сховищами pnpm. +під час ремонту doctor. Поточне очищення doctor видаляє ці застарілі каталоги й +символьні посилання, коли використовується `--fix`, зокрема старі корені `plugin-runtime-deps`, +маніфести `.openclaw-runtime-deps*`, згенеровані `node_modules` Plugin, каталоги +стадії встановлення та package-local pnpm-сховища. Ці шляхи є лише застарілими залишками. Нові встановлення не повинні їх створювати. diff --git a/docs/uk/plugins/google-meet.md b/docs/uk/plugins/google-meet.md index c9c335849..7a18e574a 100644 --- a/docs/uk/plugins/google-meet.md +++ b/docs/uk/plugins/google-meet.md @@ -3,40 +3,41 @@ read_when: - Ви хочете, щоб агент OpenClaw приєднався до дзвінка Google Meet - Ви хочете, щоб агент OpenClaw створив новий дзвінок Google Meet - Ви налаштовуєте Chrome, вузол Chrome або Twilio як транспорт Google Meet -summary: 'Plugin Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio з типовими налаштуваннями голосу в реальному часі' +summary: 'Plugin Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio зі стандартними налаштуваннями голосу в реальному часі' title: Plugin Google Meet x-i18n: - generated_at: "2026-05-02T07:17:07Z" + generated_at: "2026-05-02T09:29:38Z" model: gpt-5.5 provider: openai - source_hash: ef6945172fed00e5583f655789fab9734e5232c6820bd3fafe7d7c4a48e2f33a + source_hash: d97ad823b34264f0a1d8117d4517a4375ae414341c521b4c6d6d9a4db3f9d2bf source_path: plugins/google-meet.md workflow: 16 --- -Підтримка учасника Google Meet для OpenClaw — Plugin навмисно працює лише явно: +Підтримка учасника Google Meet для OpenClaw — Plugin навмисно працює явно: -- Він приєднується тільки до явної URL-адреси `https://meet.google.com/...`. +- Він приєднується лише до явної URL-адреси `https://meet.google.com/...`. - Він може створити новий простір Meet через Google Meet API, а потім приєднатися до поверненої URL-адреси. -- Голос `realtime` є режимом за замовчуванням. -- Голос у реальному часі може викликати повного агента OpenClaw, коли потрібні глибші +- Голосовий режим `realtime` є типовим. +- Голосовий режим реального часу може звертатися назад до повного агента OpenClaw, коли потрібні глибші міркування або інструменти. -- Агенти вибирають поведінку приєднання через `mode`: використовуйте `realtime` для живого +- Агенти вибирають поведінку приєднання за допомогою `mode`: використовуйте `realtime` для живого прослуховування/відповіді голосом або `transcribe`, щоб приєднатися/керувати браузером без - голосового мосту реального часу. + мосту голосу реального часу. - Автентифікація починається як особистий Google OAuth або вже виконаний вхід у профіль Chrome. -- Автоматичного оголошення згоди немає. +- Автоматичного оголошення про згоду немає. - Типовий аудіобекенд Chrome — `BlackHole 2ch`. -- Chrome може працювати локально або на спареному вузловому хості. -- Twilio приймає номер для дозвону плюс необов'язковий PIN або послідовність DTMF. +- Chrome може працювати локально або на спареному Node-хості. +- Twilio приймає номер для дзвінка плюс необов’язковий PIN або послідовність DTMF; він + не може напряму набрати URL Meet. - Команда CLI — `googlemeet`; `meet` зарезервовано для ширших - телеконференц-процесів агента. + агентських телеконференційних робочих процесів. ## Швидкий старт -Установіть локальні аудіозалежності та налаштуйте бекенд-провайдера голосу -реального часу. OpenAI є типовим; Google Gemini Live також працює з +Установіть локальні аудіозалежності та налаштуйте бекенд-провайдера голосу реального часу. +OpenAI є типовим; Google Gemini Live також працює з `realtime.provider: "google"`: ```bash @@ -46,14 +47,14 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` встановлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор -Homebrew потребує перезавантаження, перш ніж macOS покаже пристрій: +`blackhole-2ch` установлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор Homebrew +потребує перезавантаження, перш ніж macOS покаже пристрій: ```bash sudo reboot ``` -Після перезавантаження перевірте обидві частини: +Після перезавантаження перевірте обидва компоненти: ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -81,11 +82,11 @@ command -v sox openclaw googlemeet setup ``` -Вивід налаштування призначений бути придатним для читання агентом і враховувати режим. Він повідомляє профіль Chrome -, прив'язування вузла, а для приєднань Chrome у реальному часі — аудіоміст -BlackHole/SoX і перевірки відкладеного вступу реального часу. Для приєднань лише для спостереження перевірте той самий +Вивід налаштування призначений бути читабельним для агента й обізнаним про режим. Він повідомляє про профіль Chrome, +прив’язку Node і, для приєднань Chrome у реальному часі, аудіоміст BlackHole/SoX +та відкладені перевірки вступу реального часу. Для приєднань лише для спостереження перевірте той самий транспорт із `--mode transcribe`; цей режим пропускає передумови аудіо реального часу, -оскільки не слухає через міст і не говорить через нього: +бо він не слухає й не говорить через міст: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe @@ -93,23 +94,23 @@ openclaw googlemeet setup --transport chrome-node --mode transcribe Коли налаштовано делегування Twilio, налаштування також повідомляє, чи готові Plugin `voice-call`, облікові дані Twilio та публічна доступність Webhook. -Ставтеся до будь-якої перевірки `ok: false` як до блокера для перевіреного транспорту й режиму -перед тим, як просити агента приєднатися. Використовуйте `openclaw googlemeet setup --json` для -скриптів або машинозчитуваного виводу. Використовуйте `--transport chrome`, +Сприймайте будь-яку перевірку `ok: false` як блокер для перевіреного транспорту й режиму, +перш ніж просити агента приєднатися. Використовуйте `openclaw googlemeet setup --json` для +скриптів або машинно-читабельного виводу. Використовуйте `--transport chrome`, `--transport chrome-node` або `--transport twilio`, щоб попередньо перевірити конкретний -транспорт до того, як агент спробує його. +транспорт до спроби агента. -Для Twilio завжди явно виконуйте попередню перевірку транспорту, коли типовим транспортом -є Chrome: +Для Twilio завжди явно попередньо перевіряйте транспорт, коли типовий транспорт +— Chrome: ```bash openclaw googlemeet setup --transport twilio ``` -Це виявляє відсутню прив'язку `voice-call`, облікові дані Twilio або недосяжну +Це виявляє відсутню проводку `voice-call`, облікові дані Twilio або недосяжну публічну доступність Webhook до того, як агент спробує набрати зустріч. -Приєднайтеся до зустрічі: +Приєднатися до зустрічі: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -127,37 +128,37 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` Інструмент `google_meet` для агента залишається доступним на хостах не macOS для -артефактів, календаря, налаштування, транскрибування, Twilio та потоків `chrome-node`. -Локальні дії Chrome у реальному часі там заблоковані, оскільки вбудований аудіошлях Chrome -реального часу наразі залежить від macOS `BlackHole 2ch`. У Linux використовуйте -`mode: "transcribe"`, дозвін Twilio або macOS-хост `chrome-node` для участі Chrome +артефактів, календаря, налаштування, транскрибування, Twilio та потоків `chrome-node`. Локальні +дії Chrome у реальному часі там заблоковані, бо вбудований аудіошлях Chrome реального часу +зараз залежить від macOS `BlackHole 2ch`. На Linux використовуйте +`mode: "transcribe"`, дзвінок через Twilio або macOS-хост `chrome-node` для участі Chrome у реальному часі. -Створіть нову зустріч і приєднайтеся до неї: +Створити нову зустріч і приєднатися до неї: ```bash openclaw googlemeet create --transport chrome-node --mode realtime ``` Для кімнат, створених через API, використовуйте Google Meet `SpaceConfig.accessType`, коли хочете, -щоб політика кімнати без запиту на вхід була явною, а не успадкованою з типових налаштувань -облікового запису Google: +щоб політика кімнати без очікування допуску була явною, а не успадкованою з типових параметрів Google +облікового запису: ```bash openclaw googlemeet create --access-type OPEN --transport chrome-node --mode realtime ``` -`OPEN` дозволяє будь-кому з URL-адресою Meet приєднатися без запиту на вхід. `TRUSTED` дозволяє -довіреним користувачам організації хоста, запрошеним зовнішнім користувачам і користувачам -дозвону приєднуватися без запиту на вхід. `RESTRICTED` обмежує вхід без запиту -лише запрошеними. Ці налаштування застосовуються тільки до офіційного шляху створення -Google Meet API, тому облікові дані OAuth мають бути налаштовані. +`OPEN` дозволяє будь-кому з URL Meet приєднатися без очікування допуску. `TRUSTED` дозволяє +довіреним користувачам організації хоста, запрошеним зовнішнім користувачам і користувачам, що набирають номер, +приєднуватися без очікування допуску. `RESTRICTED` обмежує вхід без очікування допуску запрошеними. Ці +налаштування застосовуються лише до офіційного шляху створення через Google Meet API, тому +облікові дані OAuth мають бути налаштовані. -Якщо ви автентифікували Google Meet до появи цієї опції, повторно запустіть -`openclaw googlemeet auth login --json` після додавання області доступу -`meetings.space.settings` до екрана згоди Google OAuth. +Якщо ви автентифікували Google Meet до появи цієї опції, повторно виконайте +`openclaw googlemeet auth login --json` після додавання scope +`meetings.space.settings` на екрані згоди Google OAuth. -Створіть лише URL-адресу без приєднання: +Створити лише URL без приєднання: ```bash openclaw googlemeet create --no-join @@ -165,26 +166,26 @@ openclaw googlemeet create --no-join `googlemeet create` має два шляхи: -- Створення через API: використовується, коли налаштовані облікові дані Google Meet OAuth. Це - найдетермінованіший шлях, який не залежить від стану UI браузера. -- Резервний шлях через браузер: використовується, коли облікові дані OAuth відсутні. OpenClaw використовує - прив'язаний вузол Chrome, відкриває `https://meet.google.com/new`, чекає, доки Google +- Створення через API: використовується, коли налаштовано облікові дані Google Meet OAuth. Це + найбільш детермінований шлях, який не залежить від стану UI браузера. +- Резервний браузерний шлях: використовується, коли облікових даних OAuth немає. OpenClaw використовує + прив’язаний Chrome Node, відкриває `https://meet.google.com/new`, чекає, доки Google перенаправить на справжню URL-адресу з кодом зустрічі, а потім повертає цю URL-адресу. Цей шлях потребує, - щоб у профілі OpenClaw Chrome на вузлі вже було виконано вхід у Google. - Автоматизація браузера обробляє власний запит Meet на мікрофон під час першого запуску; цей запит - не вважається помилкою входу Google. + щоб у профілі Chrome OpenClaw на Node вже був виконаний вхід у Google. + Браузерна автоматизація обробляє власний первинний запит Meet на доступ до мікрофона; цей запит + не вважається помилкою входу в Google. Потоки приєднання та створення також намагаються повторно використати наявну вкладку Meet перед відкриттям - нової. Зіставлення ігнорує нешкідливі рядки запиту URL, як-от `authuser`, тому повторна спроба - агента має сфокусувати вже відкриту зустріч замість створення другої + нової. Зіставлення ігнорує нешкідливі рядки запиту URL, як-от `authuser`, тож + повторна спроба агента має сфокусувати вже відкриту зустріч замість створення другої вкладки Chrome. Вивід команди/інструмента містить поле `source` (`api` або `browser`), щоб агенти -могли пояснити, який шлях було використано. `create` типово приєднується до нової зустрічі й -повертає `joined: true` плюс сесію приєднання. Щоб лише створити URL-адресу, використовуйте -`create --no-join` у CLI або передайте `"join": false` інструменту. +могли пояснити, який шлях було використано. `create` типово приєднується до нової зустрічі та +повертає `joined: true` плюс сесію приєднання. Щоб лише створити URL, використовуйте +`create --no-join` у CLI або передайте `"join": false` в інструмент. -Або скажіть агенту: "Створи Google Meet, приєднайся до нього з голосом у реальному часі та надішли -мені посилання." Агент має викликати `google_meet` з `action: "create"` і +Або скажіть агенту: "Створи Google Meet, приєднайся до нього з голосом реального часу й надішли +мені посилання." Агент має викликати `google_meet` з `action: "create"`, а потім поділитися поверненим `meetingUri`. ```json @@ -195,52 +196,52 @@ openclaw googlemeet create --no-join } ``` -Для приєднання лише для спостереження/керування браузером установіть `"mode": "transcribe"`. Це +Для приєднання лише для спостереження/керування браузером задайте `"mode": "transcribe"`. Це не запускає дуплексний міст моделі реального часу, не потребує BlackHole або SoX -і не відповідатиме голосом у зустрічі. Приєднання Chrome у цьому режимі також уникають -надання OpenClaw дозволів на мікрофон/камеру та уникають шляху Meet **Use +і не відповідатиме голосом у зустріч. Приєднання Chrome у цьому режимі також уникають +надання OpenClaw дозволів на мікрофон/камеру й уникають шляху Meet **Use microphone**. Якщо Meet показує проміжний екран вибору аудіо, автоматизація намагається -вибрати шлях без мікрофона, а інакше повідомляє про ручну дію замість відкриття -локального мікрофона. У режимі transcribe керовані транспорти Chrome також установлюють -спостерігач субтитрів Meet на основі найкращих зусиль. `googlemeet status --json` і +шлях без мікрофона, а інакше повідомляє про ручну дію замість відкриття +локального мікрофона. У режимі транскрибування керовані транспорти Chrome також установлюють +найкращий можливий спостерігач субтитрів Meet. `googlemeet status --json` і `googlemeet doctor` показують `captioning`, `captionsEnabledAttempted`, -`transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText`, +`transcriptLines`, `lastCaptionAt`, `lastCaptionSpeaker`, `lastCaptionText` і короткий хвіст `recentTranscript`, щоб оператори могли зрозуміти, чи браузер -приєднався до дзвінка та чи субтитри Meet створюють текст. +приєднався до дзвінка і чи субтитри Meet створюють текст. Використовуйте `openclaw googlemeet test-listen --transport chrome-node`, коли -потрібна перевірка так/ні: вона приєднується в режимі transcribe, чекає на свіжий рух субтитрів або -транскрипту та повертає `listenVerified`, `listenTimedOut`, поля ручної -дії та найновіший стан субтитрів. +потрібна перевірка так/ні: він приєднується в режимі транскрибування, чекає на свіжі субтитри або +зміни транскрипту й повертає `listenVerified`, `listenTimedOut`, поля +ручної дії та найновіший стан субтитрів. -Під час сесій реального часу статус `google_meet` містить стан браузера й аудіомосту, +Під час сесій реального часу статус `google_meet` містить стан браузера й аудіомоста, як-от `inCall`, `manualActionRequired`, `providerConnected`, -`realtimeReady`, `audioInputActive`, `audioOutputActive`, останні часові мітки -вводу/виводу, лічильники байтів і закритий стан мосту. Якщо з'являється безпечний -запит сторінки Meet, автоматизація браузера обробляє його, коли може. Вхід, допуск хостом і -запити дозволів браузера/ОС повідомляються як ручна дія з причиною та -повідомленням, які агент має передати. Керовані сесії Chrome відтворюють вступ або -тестову фразу лише після того, як стан браузера повідомляє `inCall: true`; інакше статус повідомляє -`speechReady: false`, а спробу мовлення заблоковано замість удавання, що +`realtimeReady`, `audioInputActive`, `audioOutputActive`, останні часові мітки введення/виведення, +лічильники байтів і стан закриття моста. Якщо з’являється безпечний запит сторінки Meet, +браузерна автоматизація обробляє його, коли може. Запити входу, допуску хостом і +дозволів браузера/ОС повідомляються як ручна дія з причиною та +повідомленням для агента. Керовані сесії Chrome відтворюють вступ або +тестову фразу лише після того, як стан браузера повідомить `inCall: true`; інакше статус повідомляє +`speechReady: false`, а спроба мовлення блокується замість імітації, що агент говорив у зустріч. -Локальні приєднання Chrome використовують профіль браузера OpenClaw із виконаним входом. Режим реального часу +Локальні приєднання Chrome проходять через профіль браузера OpenClaw із виконаним входом. Режим реального часу потребує `BlackHole 2ch` для шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого дуплексного аудіо використовуйте окремі віртуальні пристрої або граф у стилі Loopback; одного -пристрою BlackHole достатньо для першого smoke-тесту, але він може давати відлуння. +пристрою BlackHole достатньо для першого smoke test, але він може створювати відлуння. ### Локальний Gateway + Parallels Chrome -Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM, -щоб лише зробити VM власником Chrome. Запустіть Gateway і агента локально, а потім запустіть -вузловий хост у VM. Увімкніть вбудований Plugin у VM один раз, щоб вузол +Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM +лише для того, щоб VM володіла Chrome. Запустіть Gateway і агента локально, потім запустіть +Node-хост у VM. Увімкніть вбудований Plugin у VM один раз, щоб Node оголошував команду Chrome: Що де працює: -- Хост Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, провайдер - реального часу та конфігурація Plugin Google Meet. -- Parallels macOS VM: OpenClaw CLI/вузловий хост, Google Chrome, SoX, BlackHole 2ch - і профіль Chrome із виконаним входом у Google. +- Хост Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, провайдер реального часу + і конфігурація Plugin Google Meet. +- Parallels macOS VM: OpenClaw CLI/Node-хост, Google Chrome, SoX, BlackHole 2ch + і профіль Chrome із входом у Google. - Не потрібно у VM: сервіс Gateway, конфігурація агента, ключ OpenAI/GPT або налаштування провайдера моделі. @@ -263,27 +264,27 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Установіть або оновіть OpenClaw у VM, а потім увімкніть там вбудований Plugin: +Установіть або оновіть OpenClaw у VM, потім увімкніть там вбудований Plugin: ```bash openclaw plugins enable google-meet ``` -Запустіть вузловий хост у VM: +Запустіть Node-хост у VM: ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -Якщо `` — це LAN IP і ви не використовуєте TLS, вузол відхиляє -відкритий WebSocket, якщо ви не погодитеся на це для цієї довіреної приватної мережі: +Якщо `` — LAN IP і ви не використовуєте TLS, Node відхиляє +відкритий WebSocket, якщо ви не погодитеся на нього для цієї довіреної приватної мережі: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Використовуйте ту саму змінну середовища під час встановлення вузла як LaunchAgent: +Використовуйте ту саму змінну середовища під час встановлення Node як LaunchAgent: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -291,25 +292,25 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` є середовищем процесу, а не налаштуванням +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це середовище процесу, а не налаштування `openclaw.json`. `openclaw node install` зберігає його в середовищі LaunchAgent, коли воно присутнє в команді встановлення. -Схваліть вузол із хоста Gateway: +Схваліть Node з хоста Gateway: ```bash openclaw devices list openclaw devices approve ``` -Підтвердьте, що Gateway бачить вузол і що він оголошує як `googlemeet.chrome`, +Підтвердьте, що Gateway бачить Node і що він оголошує як `googlemeet.chrome`, так і можливість браузера/`browser.proxy`: ```bash openclaw nodes status ``` -Спрямуйте Meet через цей вузол на хості Gateway: +Маршрутизуйте Meet через цей Node на хості Gateway: ```json5 { @@ -339,7 +340,7 @@ openclaw nodes status } ``` -Тепер приєднайтеся звичайним способом із хоста Gateway: +Тепер приєднуйтеся звичайно з хоста Gateway: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -347,56 +348,105 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij або попросіть агента використати інструмент `google_meet` з `transport: "chrome-node"`. -Для smoke-тесту однією командою, який створює або повторно використовує сесію, промовляє відому -фразу та друкує стан сесії: +Для smoke test однією командою, який створює або повторно використовує сесію, промовляє відому +фразу й друкує стан сесії: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Під час realtime-приєднання автоматизація браузера OpenClaw заповнює ім’я гостя, натискає Join/Ask to join і приймає перший вибір Meet "Use microphone", коли з’являється цей запит. Під час observe-only приєднання або створення зустрічі лише в браузері вона продовжує після того самого запиту без мікрофона, коли такий вибір доступний. Якщо профіль браузера не ввійшов в обліковий запис, Meet очікує допуску від організатора, Chrome потребує дозволу на мікрофон/камеру для realtime-приєднання або Meet застряг на запиті, який автоматизація не змогла вирішити, результат join/test-speech повідомляє `manualActionRequired: true` з `manualActionReason` і `manualActionMessage`. Агенти мають припинити повторювати приєднання, повідомити це точне повідомлення разом із поточними `browserUrl`/`browserTitle` і повторити спробу лише після завершення ручної дії в браузері. +Під час realtime-приєднання автоматизація браузера OpenClaw заповнює ім'я гостя, натискає +Join/Ask to join і приймає перший вибір Meet "Use microphone", коли цей +запит з'являється. Під час observe-only-приєднання або створення зустрічі лише через браузер вона +продовжує після такого самого запиту без мікрофона, коли цей вибір доступний. +Якщо профіль браузера не має виконаного входу, Meet очікує допуску від організатора, +Chrome потребує дозволу на мікрофон/камеру для realtime-приєднання, або Meet застряг +на запиті, який автоматизація не змогла обробити, результат join/test-speech повідомляє +`manualActionRequired: true` з `manualActionReason` і +`manualActionMessage`. Агенти мають припинити повторювати приєднання, повідомити це точне +повідомлення разом із поточними `browserUrl`/`browserTitle` і повторити спробу лише після +завершення ручної дії в браузері. -Якщо `chromeNode.node` пропущено, OpenClaw автоматично вибирає лише тоді, коли рівно один підключений Node оголошує і `googlemeet.chrome`, і керування браузером. Якщо підключено кілька придатних Node, установіть `chromeNode.node` на ідентифікатор Node, відображуване ім’я або віддалену IP-адресу. +Якщо `chromeNode.node` пропущено, OpenClaw автоматично вибирає лише тоді, коли рівно один +підключений node оголошує і `googlemeet.chrome`, і керування браузером. Якщо +підключено кілька придатних nodes, задайте для `chromeNode.node` id node, +відображуване ім'я або віддалену IP-адресу. -Поширені перевірки збоїв: +Типові перевірки збоїв: -- `Configured Google Meet node ... is not usable: offline`: закріплений Node відомий Gateway, але недоступний. Агенти мають розглядати цей Node як діагностичний стан, а не як придатний хост Chrome, і повідомити про блокер налаштування замість переходу на інший транспорт, якщо користувач цього не просив. -- `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, підтвердьте pairing і переконайтеся, що `openclaw plugins enable google-meet` та `openclaw plugins enable browser` були виконані у VM. Також підтвердьте, що хост Gateway дозволяє обидві команди Node через `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. -- `BlackHole 2ch audio device not found`: установіть `blackhole-2ch` на хості, який перевіряється, і перезавантажтеся перед використанням локального аудіо Chrome. -- `BlackHole 2ch audio device not found on the node`: установіть `blackhole-2ch` у VM і перезавантажте VM. -- Chrome відкривається, але не може приєднатися: увійдіть у профіль браузера всередині VM або залиште `chrome.guestName` заданим для приєднання гостя. Автоматичне приєднання гостя використовує браузерну автоматизацію OpenClaw через браузерний проксі Node; переконайтеся, що конфігурація браузера Node вказує на потрібний профіль, наприклад `browser.defaultProfile: "user"` або іменований профіль existing-session. -- Дублікати вкладок Meet: залиште `chrome.reuseExistingTab: true` увімкненим. OpenClaw активує наявну вкладку для тієї самої URL-адреси Meet перед відкриттям нової, а створення зустрічі в браузері повторно використовує вкладку `https://meet.google.com/new` або запиту Google account, що вже в процесі, перед відкриттям іншої. -- Немає аудіо: у Meet скеруйте аудіо мікрофона/динаміка через шлях віртуального аудіопристрою, який використовує OpenClaw; використовуйте окремі віртуальні пристрої або маршрутизацію у стилі Loopback для чистого duplex-аудіо. +- `Configured Google Meet node ... is not usable: offline`: закріплений node + відомий Gateway, але недоступний. Агенти мають трактувати цей node як + діагностичний стан, а не як придатний хост Chrome, і повідомити про блокер налаштування + замість переходу на інший транспорт, якщо користувач не просив про це. +- `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, + схваліть pairing і переконайтеся, що `openclaw plugins enable google-meet` та + `openclaw plugins enable browser` були виконані у VM. Також підтвердьте, що + хост Gateway дозволяє обидві команди node через + `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. +- `BlackHole 2ch audio device not found`: установіть `blackhole-2ch` на хості, + який перевіряється, і перезавантажте його перед використанням локального аудіо Chrome. +- `BlackHole 2ch audio device not found on the node`: установіть `blackhole-2ch` + у VM і перезавантажте VM. +- Chrome відкривається, але не може приєднатися: увійдіть у профіль браузера всередині VM або + залиште `chrome.guestName` заданим для гостьового приєднання. Гостьове автоприєднання використовує + автоматизацію браузера OpenClaw через браузерний проксі node; переконайтеся, що конфігурація браузера node + вказує на потрібний профіль, наприклад + `browser.defaultProfile: "user"` або іменований профіль наявного сеансу. +- Дублікати вкладок Meet: залиште `chrome.reuseExistingTab: true` увімкненим. OpenClaw + активує наявну вкладку для тієї самої URL-адреси Meet перед відкриттям нової, а + браузерне створення зустрічі повторно використовує поточну вкладку `https://meet.google.com/new` + або вкладку запиту облікового запису Google перед відкриттям іншої. +- Немає аудіо: у Meet скеруйте аудіо мікрофона/динаміка через шлях віртуального аудіопристрою, + який використовує OpenClaw; використовуйте окремі віртуальні пристрої або маршрутизацію у стилі Loopback + для чистого дуплексного аудіо. -## Нотатки щодо встановлення +## Примітки щодо встановлення -Стандартний realtime-режим Chrome використовує два зовнішні інструменти: +Типове Chrome realtime використовує два зовнішні інструменти: -- `sox`: аудіоутиліта командного рядка. Plugin використовує явні команди CoreAudio device для стандартного 24 kHz PCM16 audio bridge. -- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, через який Chrome/Meet може маршрутизувати аудіо. +- `sox`: аудіоутиліта командного рядка. Plugin використовує явні команди пристроїв CoreAudio + для типового аудіомоста 24 kHz PCM16. +- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, + через який Chrome/Meet можуть маршрутизувати аудіо. -OpenClaw не пакує й не поширює жоден із цих пакетів. Документація просить користувачів установлювати їх як залежності хоста через Homebrew. SoX ліцензовано як `LGPL-2.0-only AND GPL-2.0-only`; BlackHole має ліцензію GPL-3.0. Якщо ви створюєте інсталятор або appliance, який пакує BlackHole разом з OpenClaw, перегляньте умови ліцензування upstream BlackHole або отримайте окрему ліцензію від Existential Audio. +OpenClaw не постачає й не розповсюджує жоден із цих пакетів. Документація просить користувачів +установити їх як залежності хоста через Homebrew. SoX ліцензовано як +`LGPL-2.0-only AND GPL-2.0-only`; BlackHole має ліцензію GPL-3.0. Якщо ви створюєте +інсталятор або appliance, що постачає BlackHole разом з OpenClaw, перегляньте +умови ліцензування upstream BlackHole або отримайте окрему ліцензію від Existential Audio. ## Транспорти ### Chrome -Транспорт Chrome відкриває URL-адресу Meet через керування браузером OpenClaw і приєднується як профіль браузера OpenClaw, що ввійшов в обліковий запис. На macOS Plugin перевіряє наявність `BlackHole 2ch` перед запуском. Якщо налаштовано, він також запускає команду перевірки стану audio bridge і команду запуску перед відкриттям Chrome. Використовуйте `chrome`, коли Chrome/аудіо працюють на хості Gateway; використовуйте `chrome-node`, коли Chrome/аудіо працюють на спареному Node, наприклад Parallels macOS VM. Для локального Chrome виберіть профіль через `browser.defaultProfile`; `chrome.browserProfile` передається хостам `chrome-node`. +Транспорт Chrome відкриває URL-адресу Meet через керування браузером OpenClaw і приєднується +як профіль браузера OpenClaw із виконаним входом. На macOS Plugin перевіряє наявність +`BlackHole 2ch` перед запуском. Якщо налаштовано, він також запускає команду перевірки стану +аудіомоста і команду запуску перед відкриттям Chrome. Використовуйте `chrome`, коли +Chrome/аудіо працюють на хості Gateway; використовуйте `chrome-node`, коли Chrome/аудіо працюють +на paired node, наприклад Parallels macOS VM. Для локального Chrome виберіть +профіль через `browser.defaultProfile`; `chrome.browserProfile` передається +хостам `chrome-node`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Скеруйте аудіо мікрофона й динаміка Chrome через локальний audio bridge OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднання завершується помилкою налаштування замість тихого приєднання без аудіошляху. +Скеруйте аудіо мікрофона та динаміка Chrome через локальний аудіоміст OpenClaw. +Якщо `BlackHole 2ch` не встановлено, приєднання завершується помилкою налаштування +замість беззвучного приєднання без аудіошляху. ### Twilio -Транспорт Twilio — це строгий план набору, делегований Plugin Voice Call. Він не аналізує сторінки Meet для пошуку телефонних номерів. +Транспорт Twilio — це суворий план набору, делегований Plugin Voice Call. Він +не аналізує сторінки Meet для пошуку телефонних номерів. -Використовуйте це, коли участь через Chrome недоступна або потрібен резервний варіант телефонного дозвону. Google Meet має надати номер телефонного дозвону й PIN для зустрічі; OpenClaw не виявляє їх зі сторінки Meet. +Використовуйте це, коли участь через Chrome недоступна або потрібен резервний варіант +телефонного набору. Google Meet має показувати номер телефонного набору та PIN для +зустрічі; OpenClaw не виявляє їх зі сторінки Meet. -Увімкніть Plugin Voice Call на хості Gateway, а не на Node Chrome: +Увімкніть Plugin Voice Call на хості Gateway, а не на Chrome node: ```json5 { @@ -421,7 +471,8 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome } ``` -Надайте облікові дані Twilio через середовище або конфігурацію. Середовище не допускає потрапляння секретів у `openclaw.json`: +Надайте облікові дані Twilio через середовище або config. Середовище не дає +секретам потрапити в `openclaw.json`: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -429,7 +480,8 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни конфігурації Plugin не з’являються в уже запущеному процесі Gateway, доки він не перезавантажиться. +Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни config Plugin +не з'являються у вже запущеному процесі Gateway, доки він не перезавантажиться. Потім перевірте: @@ -439,7 +491,9 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Коли делегування Twilio підключено, `googlemeet setup` містить успішні перевірки `twilio-voice-call-plugin`, `twilio-voice-call-credentials` і `twilio-voice-call-webhook`. +Коли делегування Twilio підключено, `googlemeet setup` містить успішні перевірки +`twilio-voice-call-plugin`, `twilio-voice-call-credentials` і +`twilio-voice-call-webhook`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -448,7 +502,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -Використовуйте `--dtmf-sequence`, коли зустріч потребує спеціальної послідовності: +Використовуйте `--dtmf-sequence`, коли зустріч потребує власної послідовності: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -459,11 +513,20 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth і preflight -OAuth є необов’язковим для створення посилання Meet, оскільки `googlemeet create` може перейти на браузерну автоматизацію. Налаштуйте OAuth, коли потрібне офіційне створення через API, розв’язання space або preflight-перевірки Meet Media API. +OAuth необов'язковий для створення посилання Meet, оскільки `googlemeet create` може +повертатися до автоматизації браузера. Налаштуйте OAuth, коли потрібне офіційне створення через API, +розв'язання простору або preflight-перевірки Meet Media API. -Доступ до Google Meet API використовує user OAuth: створіть OAuth-клієнт Google Cloud, запитайте потрібні scopes, авторизуйте обліковий запис Google, а потім збережіть отриманий refresh token у конфігурації Plugin Google Meet або надайте змінні середовища `OPENCLAW_GOOGLE_MEET_*`. +Доступ до Google Meet API використовує користувацький OAuth: створіть OAuth-клієнт Google Cloud, +запитайте потрібні scopes, авторизуйте обліковий запис Google, а потім збережіть +отриманий refresh token у config Plugin Google Meet або надайте +змінні середовища `OPENCLAW_GOOGLE_MEET_*`. -OAuth не замінює шлях приєднання Chrome. Транспорти Chrome і Chrome-node все ще приєднуються через профіль Chrome, що ввійшов в обліковий запис, BlackHole/SoX і підключений Node, коли ви використовуєте участь через браузер. OAuth призначений лише для офіційного шляху Google Meet API: створення meeting spaces, розв’язання spaces і запуск preflight-перевірок Meet Media API. +OAuth не замінює шлях приєднання Chrome. Транспорти Chrome і Chrome-node +досі приєднуються через профіль Chrome із виконаним входом, BlackHole/SoX і підключений +node, коли ви використовуєте участь через браузер. OAuth призначений лише для офіційного +шляху Google Meet API: створення просторів зустрічей, розв'язання просторів і виконання +preflight-перевірок Meet Media API. ### Створення облікових даних Google @@ -472,8 +535,9 @@ OAuth не замінює шлях приєднання Chrome. Транспор 1. Створіть або виберіть проєкт Google Cloud. 2. Увімкніть **Google Meet REST API** для цього проєкту. 3. Налаштуйте екран згоди OAuth. - - **Internal** — найпростіше для організації Google Workspace. - - **External** працює для особистих/тестових налаштувань; доки застосунок у Testing, додайте кожен обліковий запис Google, який авторизуватиме застосунок, як test user. + - **Internal** найпростіший для організації Google Workspace. + - **External** працює для особистих/тестових налаштувань; поки застосунок перебуває в Testing, + додайте кожен обліковий запис Google, який авторизуватиме застосунок, як тестового користувача. 4. Додайте scopes, які запитує OpenClaw: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` @@ -489,17 +553,26 @@ OAuth не замінює шлях приєднання Chrome. Транспор 6. Скопіюйте client ID і client secret. -`meetings.space.created` потрібен Google Meet `spaces.create`. `meetings.space.readonly` дає OpenClaw змогу розв’язувати URL-адреси/коди Meet у spaces. `meetings.space.settings` дає OpenClaw змогу передавати налаштування `SpaceConfig`, як-от `accessType`, під час створення кімнати через API. `meetings.conference.media.readonly` призначений для preflight Meet Media API і media-робіт; Google може вимагати участі в Developer Preview для фактичного використання Media API. Якщо вам потрібні лише приєднання Chrome на основі браузера, повністю пропустіть OAuth. +`meetings.space.created` потрібен Google Meet `spaces.create`. +`meetings.space.readonly` дає OpenClaw змогу розв'язувати URL-адреси/коди Meet у простори. +`meetings.space.settings` дає OpenClaw змогу передавати налаштування `SpaceConfig`, такі як +`accessType`, під час створення кімнати через API. +`meetings.conference.media.readonly` призначений для preflight Meet Media API і роботи з медіа; +Google може вимагати реєстрації Developer Preview для фактичного використання Media API. +Якщо вам потрібні лише браузерні приєднання Chrome, повністю пропустіть OAuth. -### Отримання refresh token +### Створення refresh token -Налаштуйте `oauth.clientId` і, за потреби, `oauth.clientSecret`, або передайте їх як змінні середовища, а потім виконайте: +Налаштуйте `oauth.clientId` і, за потреби, `oauth.clientSecret`, або передайте їх як +змінні середовища, а потім виконайте: ```bash openclaw googlemeet auth login --json ``` -Команда виводить блок конфігурації `oauth` з refresh token. Вона використовує PKCE, localhost callback на `http://localhost:8085/oauth2callback` і ручний потік копіювання/вставлення з `--manual`. +Команда виводить блок config `oauth` з refresh token. Вона використовує PKCE, +localhost callback на `http://localhost:8085/oauth2callback` і ручний +потік copy/paste з `--manual`. Приклади: @@ -517,7 +590,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json --manual ``` -JSON-вивід містить: +Вивід JSON містить: ```json { @@ -532,7 +605,7 @@ JSON-вивід містить: } ``` -Збережіть об’єкт `oauth` у конфігурації Plugin Google Meet: +Збережіть об'єкт `oauth` у config Plugin Google Meet: ```json5 { @@ -553,9 +626,14 @@ JSON-вивід містить: } ``` -Надавайте перевагу змінним середовища, коли не хочете зберігати refresh token у конфігурації. Якщо присутні і значення конфігурації, і значення середовища, Plugin спочатку використовує конфігурацію, а потім fallback середовища. +Надавайте перевагу змінним середовища, коли не хочете зберігати refresh token у config. +Якщо присутні і значення config, і значення середовища, Plugin спочатку розв'язує config, +а потім використовує fallback середовища. -Згода OAuth включає створення Meet space, доступ для читання Meet space і доступ для читання conference media Meet. Якщо ви автентифікувалися до появи підтримки створення зустрічей, повторно виконайте `openclaw googlemeet auth login --json`, щоб refresh token мав scope `meetings.space.created`. +Згода OAuth охоплює створення просторів Meet, доступ на читання до просторів Meet і доступ +на читання медіа конференцій Meet. Якщо ви автентифікувалися до появи підтримки створення +зустрічей, повторно виконайте `openclaw googlemeet auth login --json`, щоб refresh +token мав scope `meetings.space.created`. ### Перевірка OAuth через doctor @@ -565,45 +643,41 @@ JSON-вивід містить: openclaw googlemeet doctor --oauth --json ``` -Це не завантажує runtime Chrome і не потребує підключеного Node Chrome. Перевіряється, що конфігурація OAuth існує і що refresh token може отримати access token. JSON-звіт містить лише поля стану, як-от `ok`, `configured`, `tokenSource`, `expiresAt`, і повідомлення перевірок; він не виводить access token, refresh token або client secret. +Це не завантажує runtime Chrome і не потребує підключеного Chrome node. Воно +перевіряє, що config OAuth існує і що refresh token може створити access +token. Звіт JSON містить лише поля стану, такі як `ok`, `configured`, +`tokenSource`, `expiresAt`, і повідомлення перевірок; він не друкує access +token, refresh token або client secret. -Поширені результати: +Типові результати: | Перевірка | Значення | | -------------------- | --------------------------------------------------------------------------------------- | -| `oauth-config` | Наявний `oauth.clientId` плюс `oauth.refreshToken` або кешований access token. | -| `oauth-token` | Кешований access token усе ще дійсний або refresh token отримав новий access token. | -| `meet-spaces-get` | Необов’язкова перевірка `--meeting` розв’язала наявний Meet space. | -| `meet-spaces-create` | Необов’язкова перевірка `--create-space` створила новий Meet space. | +| `oauth-config` | Присутній `oauth.clientId` плюс `oauth.refreshToken` або cached access token. | +| `oauth-token` | Cached access token ще дійсний або refresh token створив новий access token. | +| `meet-spaces-get` | Необов'язкова перевірка `--meeting` розв'язала наявний простір Meet. | +| `meet-spaces-create` | Необов'язкова перевірка `--create-space` створила новий простір Meet. | -Щоб також підтвердити ввімкнення Google Meet API і scope `spaces.create`, виконайте перевірку створення з побічним ефектом: +Щоб також довести ввімкнення Google Meet API і scope `spaces.create`, запустіть +перевірку створення з побічним ефектом: ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` створює тимчасову URL-адресу Meet. Використовуйте її, коли потрібно підтвердити, -що в проєкті Google Cloud увімкнено Meet API і що авторизований -обліковий запис має scope `meetings.space.created`. +`--create-space` створює одноразову Meet URL. Використовуйте його, коли потрібно підтвердити, що в проєкті Google Cloud увімкнено Meet API і що авторизований обліковий запис має scope `meetings.space.created`. -Щоб підтвердити доступ на читання для наявного простору зустрічі: +Щоб підтвердити доступ для читання до наявного простору зустрічі: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` і `resolve-space` підтверджують доступ на читання до наявного -простору, до якого має доступ авторизований обліковий запис Google. `403` від цих перевірок -зазвичай означає, що Google Meet REST API вимкнено, погоджений refresh token -не має потрібного scope або обліковий запис Google не може отримати доступ до цього простору -Meet. Помилка refresh-token означає, що потрібно повторно запустити `openclaw googlemeet auth login ---json` і зберегти новий блок `oauth`. +`doctor --oauth --meeting` і `resolve-space` підтверджують доступ для читання до наявного простору, до якого має доступ авторизований обліковий запис Google. `403` від цих перевірок зазвичай означає, що Google Meet REST API вимкнено, погоджений refresh token не має потрібного scope, або обліковий запис Google не має доступу до цього простору Meet. Помилка refresh-token означає, що потрібно повторно виконати `openclaw googlemeet auth login --json` і зберегти новий блок `oauth`. -Для резервного браузерного режиму облікові дані OAuth не потрібні. У цьому режимі автентифікація Google -надходить із профілю Chrome, у який виконано вхід на вибраному вузлі, а не з -конфігурації OpenClaw. +Для резервного браузерного режиму облікові дані OAuth не потрібні. У цьому режимі автентифікація Google надходить із профілю Chrome, у який виконано вхід на вибраному вузлі, а не з конфігурації OpenClaw. Ці змінні середовища приймаються як резервні: @@ -616,7 +690,7 @@ Meet. Помилка refresh-token означає, що потрібно пов - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` або `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` або `GOOGLE_MEET_PREVIEW_ACK` -Розв’яжіть URL-адресу Meet, код або `spaces/{id}` через `spaces.get`: +Розв’яжіть Meet URL, код або `spaces/{id}` через `spaces.get`: ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij @@ -628,7 +702,7 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Виведіть список артефактів зустрічі та відвідуваності після того, як Meet створить записи конференції: +Перелічіть артефакти зустрічі та відвідуваність після того, як Meet створить записи конференції: ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij @@ -636,12 +710,9 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export ``` -З `--meeting`, `artifacts` і `attendance` за замовчуванням використовують найновіший запис конференції. -Передайте `--all-conference-records`, коли потрібні всі збережені записи -для цієї зустрічі. +З `--meeting` команди `artifacts` і `attendance` типово використовують останній запис конференції. Передайте `--all-conference-records`, коли потрібні всі збережені записи для цієї зустрічі. -Пошук у Calendar може розв’язати URL-адресу зустрічі з Google Calendar перед читанням -артефактів Meet: +Пошук у Calendar може визначити URL зустрічі з Google Calendar перед читанням артефактів Meet: ```bash openclaw googlemeet latest --today @@ -650,12 +721,8 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` шукає в сьогоднішньому календарі `primary` подію Calendar із -посиланням Google Meet. Використовуйте `--event ` для пошуку відповідного тексту події та -`--calendar ` для неосновного календаря. Пошук у Calendar потребує нового -входу OAuth, який включає readonly scope для подій Calendar. -`calendar-events` попередньо показує відповідні події Meet і позначає подію, яку -виберуть `latest`, `artifacts`, `attendance` або `export`. +`--today` шукає в сьогоднішньому календарі `primary` подію Calendar із посиланням Google Meet. Використовуйте `--event ` для пошуку відповідного тексту події, а `--calendar ` для неосновного календаря. Пошук у Calendar потребує свіжого входу OAuth, який включає scope Calendar events readonly. +`calendar-events` попередньо показує відповідні події Meet і позначає подію, яку вибере `latest`, `artifacts`, `attendance` або `export`. Якщо ви вже знаєте ідентифікатор запису конференції, звертайтеся до нього напряму: @@ -665,20 +732,14 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -Завершіть активну конференцію для простору, створеного через API, коли потрібно закрити -кімнату після дзвінка: +Завершіть активну конференцію для простору, створеного через API, коли потрібно закрити кімнату після дзвінка: ```bash openclaw googlemeet end-active-conference https://meet.google.com/abc-defg-hij ``` -Це викликає Google Meet `spaces.endActiveConference` і потребує OAuth зі -scope `meetings.space.created` для простору, яким авторизований обліковий запис може керувати. -OpenClaw приймає URL-адресу Meet, код зустрічі або вхідні дані `spaces/{id}` і розв’язує їх -до ресурсу простору API перед завершенням активної конференції. -Це окремо від `googlemeet leave`: `leave` зупиняє локальну/сесійну -участь OpenClaw, тоді як `end-active-conference` просить Google Meet завершити активну -конференцію для простору. +Це викликає Google Meet `spaces.endActiveConference` і потребує OAuth зі scope `meetings.space.created` для простору, яким може керувати авторизований обліковий запис. OpenClaw приймає Meet URL, код зустрічі або вхідні дані `spaces/{id}` і розв’язує їх у ресурс простору API перед завершенням активної конференції. +Це окремо від `googlemeet leave`: `leave` зупиняє локальну/сесійну участь OpenClaw, тоді як `end-active-conference` просить Google Meet завершити активну конференцію для простору. Запишіть читабельний звіт: @@ -695,32 +756,10 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ --include-doc-bodies --dry-run ``` -`artifacts` повертає метадані запису конференції, а також метадані ресурсів учасників, записів, -транскриптів, структурованих записів транскрипту та smart-note, коли -Google надає їх для зустрічі. Використовуйте `--no-transcript-entries`, щоб пропустити -пошук записів для великих зустрічей. `attendance` розгортає учасників у -рядки participant-session із часом першої/останньої появи, загальною тривалістю сесії, -прапорцями запізнення/раннього виходу та дубльованими ресурсами учасників, об’єднаними за користувачем, -який увійшов у систему, або відображуваним ім’ям. Передайте `--no-merge-duplicates`, щоб залишити необроблені ресурси учасників -окремими, `--late-after-minutes`, щоб налаштувати визначення запізнення, і -`--early-before-minutes`, щоб налаштувати визначення раннього виходу. +`artifacts` повертає метадані запису конференції, а також метадані ресурсів учасників, записів, транскриптів, структурованих записів транскрипту та smart-note, коли Google надає їх для зустрічі. Використовуйте `--no-transcript-entries`, щоб пропустити пошук записів для великих зустрічей. `attendance` розгортає учасників у рядки participant-session із часом першої/останньої появи, загальною тривалістю сесії, прапорцями запізнення/раннього виходу та об’єднанням дубльованих ресурсів учасників за користувачем, який увійшов у систему, або відображуваним іменем. Передайте `--no-merge-duplicates`, щоб залишити сирі ресурси учасників окремо, `--late-after-minutes`, щоб налаштувати виявлення запізнення, і `--early-before-minutes`, щоб налаштувати виявлення раннього виходу. -`export` записує папку, що містить `summary.md`, `attendance.csv`, -`transcript.md`, `artifacts.json`, `attendance.json` і `manifest.json`. -`manifest.json` фіксує вибрані вхідні дані, параметри експорту, записи конференції, -вихідні файли, лічильники, джерело токена, подію Calendar, якщо її було використано, і будь-які -попередження про часткове отримання. Передайте `--zip`, щоб також записати портативний архів поруч -із папкою. Передайте `--include-doc-bodies`, щоб експортувати текст пов’язаних транскриптів і -smart-note Google Docs через Google Drive `files.export`; для цього потрібен -новий вхід OAuth, який включає Drive Meet readonly scope. Без -`--include-doc-bodies` експорт містить лише метадані Meet і структуровані записи транскрипту. -Якщо Google повертає частковий збій артефакту, наприклад помилку списку smart-note, -запису транскрипту або тіла документа Drive, summary і -manifest зберігають попередження замість того, щоб провалити весь експорт. -Використовуйте `--dry-run`, щоб отримати ті самі дані артефактів/відвідуваності та вивести -JSON маніфесту без створення папки або ZIP. Це корисно перед записом -великого експорту або коли агенту потрібні лише лічильники, вибрані записи та -попередження. +`export` записує папку, що містить `summary.md`, `attendance.csv`, `transcript.md`, `artifacts.json`, `attendance.json` і `manifest.json`. `manifest.json` фіксує вибрані вхідні дані, параметри експорту, записи конференції, вихідні файли, лічильники, джерело токена, подію Calendar, якщо вона використовувалась, і будь-які попередження про часткове отримання. Передайте `--zip`, щоб також записати переносний архів поряд із папкою. Передайте `--include-doc-bodies`, щоб експортувати пов’язаний текст транскрипту та smart-note Google Docs через Google Drive `files.export`; для цього потрібен свіжий вхід OAuth, який включає scope Drive Meet readonly. Без `--include-doc-bodies` експорти містять лише метадані Meet і структуровані записи транскрипту. Якщо Google повертає часткову помилку артефакту, наприклад помилку списку smart-note, запису транскрипту або тіла документа Drive, зведення й маніфест зберігають попередження замість того, щоб провалити весь експорт. +Використовуйте `--dry-run`, щоб отримати ті самі дані артефактів/відвідуваності й надрукувати JSON маніфесту без створення папки або ZIP. Це корисно перед записом великого експорту або коли агенту потрібні лише лічильники, вибрані записи та попередження. Агенти також можуть створити той самий пакет через інструмент `google_meet`: @@ -734,7 +773,7 @@ JSON маніфесту без створення папки або ZIP. Це к } ``` -Установіть `"dryRun": true`, щоб повернути лише маніфест експорту й пропустити запис файлів. +Установіть `"dryRun": true`, щоб повернути лише маніфест експорту й пропустити записи файлів. Агенти також можуть створити кімнату на базі API з явною політикою доступу: @@ -756,8 +795,7 @@ JSON маніфесту без створення папки або ZIP. Це к } ``` -Для валідації з пріоритетом прослуховування агенти мають використовувати `test_listen`, перш ніж стверджувати, що -зустріч корисна: +Для валідації з пріоритетом слухання агенти мають використовувати `test_listen`, перш ніж стверджувати, що зустріч корисна: ```json { @@ -768,7 +806,7 @@ JSON маніфесту без створення папки або ZIP. Це к } ``` -Запустіть захищену live smoke-перевірку проти реальної збереженої зустрічі: +Запустіть захищений live smoke проти реальної збереженої зустрічі: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -776,18 +814,17 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Запустіть браузерну live-перевірку з пріоритетом прослуховування проти зустрічі, де хтось -говоритиме і будуть доступні субтитри Meet: +Запустіть live браузерну перевірку з пріоритетом слухання проти зустрічі, де хтось говоритиме й доступні субтитри Meet: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport chrome-node --timeout-ms 30000 ``` -Середовище live smoke-перевірки: +Середовище live smoke: -- `OPENCLAW_LIVE_TEST=1` вмикає захищені live-тести. -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` вказує на збережену URL-адресу Meet, код або +- `OPENCLAW_LIVE_TEST=1` вмикає захищені live тести. +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` вказує на збережений Meet URL, код або `spaces/{id}`. - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` або `GOOGLE_MEET_CLIENT_ID` надає OAuth client id. @@ -798,12 +835,7 @@ openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` використовують ті самі резервні назви без префікса `OPENCLAW_`. -Базовій live smoke-перевірці артефактів/відвідуваності потрібні -`https://www.googleapis.com/auth/meetings.space.readonly` і -`https://www.googleapis.com/auth/meetings.conference.media.readonly`. Пошуку в Calendar -потрібен `https://www.googleapis.com/auth/calendar.events.readonly`. Експорту -тіла документа Drive потрібен -`https://www.googleapis.com/auth/drive.meet.readonly`. +Базовий live smoke для артефактів/відвідуваності потребує `https://www.googleapis.com/auth/meetings.space.readonly` і `https://www.googleapis.com/auth/meetings.conference.media.readonly`. Пошук у Calendar потребує `https://www.googleapis.com/auth/calendar.events.readonly`. Експорт тіла документа Drive потребує `https://www.googleapis.com/auth/drive.meet.readonly`. Створіть новий простір Meet: @@ -811,11 +843,7 @@ openclaw googlemeet test-listen https://meet.google.com/abc-defg-hij --transport openclaw googlemeet create ``` -Команда виводить новий `meeting uri`, джерело та сесію приєднання. З обліковими даними OAuth -вона використовує офіційний Google Meet API. Без облікових даних OAuth вона -використовує як резервний варіант браузерний профіль закріпленого вузла Chrome, у який виконано вхід. Агенти можуть -використовувати інструмент `google_meet` з `action: "create"`, щоб створити й приєднатися за один -крок. Для створення лише URL-адреси передайте `"join": false`. +Команда друкує новий `meeting uri`, джерело та сесію приєднання. З обліковими даними OAuth вона використовує офіційний Google Meet API. Без облікових даних OAuth вона використовує як резервний варіант профіль браузера вузла pinned Chrome, у який виконано вхід. Агенти можуть використовувати інструмент `google_meet` з `action: "create"`, щоб створити й приєднатися за один крок. Для створення лише URL передайте `"join": false`. Приклад JSON-виводу з браузерного резервного режиму: @@ -837,9 +865,7 @@ openclaw googlemeet create } ``` -Якщо браузерний резервний режим натрапляє на вхід Google або блокування дозволів Meet до того, як -зможе створити URL-адресу, метод Gateway повертає невдалу відповідь, а -інструмент `google_meet` повертає структуровані деталі замість простого рядка: +Якщо браузерний резервний режим натрапляє на вхід у Google або блокувальник дозволів Meet до того, як зможе створити URL, метод Gateway повертає невдалу відповідь, а інструмент `google_meet` повертає структуровані деталі замість простого рядка: ```json { @@ -857,11 +883,9 @@ openclaw googlemeet create } ``` -Коли агент бачить `manualActionRequired: true`, він має повідомити -`manualActionMessage` разом із контекстом браузерного вузла/вкладки й припинити відкривати нові -вкладки Meet, доки оператор не завершить крок у браузері. +Коли агент бачить `manualActionRequired: true`, він має повідомити `manualActionMessage` разом із контекстом вузла/вкладки браузера й припинити відкривати нові вкладки Meet, доки оператор не завершить браузерний крок. -Приклад JSON-виводу створення через API: +Приклад JSON-виводу зі створення через API: ```json { @@ -882,21 +906,13 @@ openclaw googlemeet create } ``` -Створення Meet за замовчуванням приєднує до зустрічі. Транспорту Chrome або Chrome-node все одно -потрібен профіль Google Chrome, у який виконано вхід, щоб приєднатися через браузер. Якщо з -профілю виконано вихід, OpenClaw повідомляє `manualActionRequired: true` або -помилку браузерного резервного режиму й просить оператора завершити вхід Google перед -повторною спробою. +Створення Meet типово приєднує до зустрічі. Транспорт Chrome або Chrome-node все одно потребує профілю Google Chrome, у який виконано вхід, щоб приєднатися через браузер. Якщо профіль вийшов із системи, OpenClaw повідомляє `manualActionRequired: true` або помилку браузерного резервного режиму й просить оператора завершити вхід у Google перед повторною спробою. -Установлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш Cloud -проєкт, OAuth principal і учасники зустрічі зареєстровані в Google -Workspace Developer Preview Program для Meet media APIs. +Установлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш проєкт Cloud, OAuth principal і учасники зустрічі зареєстровані в Google Workspace Developer Preview Program для Meet media APIs. ## Конфігурація -Загальному realtime-шляху Chrome потрібні лише ввімкнений plugin, BlackHole, SoX -і ключ backend realtime voice provider. OpenAI є типовим; установіть -`realtime.provider: "google"`, щоб використовувати Google Gemini Live: +Загальний realtime шлях Chrome потребує лише ввімкненого плагіна, BlackHole, SoX і ключа бекенд-провайдера realtime voice. OpenAI є типовим; установіть `realtime.provider: "google"`, щоб використовувати Google Gemini Live: ```bash brew install blackhole-2ch sox @@ -924,39 +940,39 @@ export GEMINI_API_KEY=... - `defaultTransport: "chrome"` - `defaultMode: "realtime"` -- `chromeNode.node`: необов’язковий ідентифікатор/назва/IP вузла для `chrome-node` +- `chromeNode.node`: необов’язковий ідентифікатор/назва/IP node для `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: ім’я, що використовується на екрані гостя Meet без входу - в обліковий запис -- `chrome.autoJoin: true`: найкраща можлива спроба заповнити ім’я гостя й натиснути Join Now - через браузерну автоматизацію OpenClaw на `chrome-node` +- `chrome.guestName: "OpenClaw Agent"`: ім’я, що використовується на екрані + гостя Meet без входу в обліковий запис +- `chrome.autoJoin: true`: заповнення імені гостя та натискання Join Now за + можливості через браузерну автоматизацію OpenClaw на `chrome-node` - `chrome.reuseExistingTab: true`: активувати наявну вкладку Meet замість - відкриття дублікатів -- `chrome.waitForInCallMs: 20000`: чекати, доки вкладка Meet повідомить, що вона у виклику, - перш ніж буде запущено realtime-вступ -- `chrome.audioFormat: "pcm16-24khz"`: формат аудіо для пари команд. Використовуйте - `"g711-ulaw-8khz"` лише для застарілих/кастомних пар команд, які все ще видають - телефонне аудіо. + відкривання дублікатів +- `chrome.waitForInCallMs: 20000`: чекати, доки вкладка Meet повідомить, що вона + в дзвінку, перш ніж запускати realtime-вступ +- `chrome.audioFormat: "pcm16-24khz"`: аудіоформат пари команд. Використовуйте + `"g711-ulaw-8khz"` лише для застарілих/користувацьких пар команд, які все ще + передають телефонний звук. - `chrome.audioInputCommand`: команда SoX, що читає з CoreAudio `BlackHole 2ch` - і записує аудіо у форматі `chrome.audioFormat` -- `chrome.audioOutputCommand`: команда SoX, що читає аудіо у форматі `chrome.audioFormat` - і записує в CoreAudio `BlackHole 2ch` -- `chrome.bargeInInputCommand`: необов’язкова команда локального мікрофона, яка записує - signed 16-bit little-endian mono PCM для виявлення людського втручання, поки - відтворення асистента активне. Наразі це застосовується до розміщеного на Gateway - мосту пар команд `chrome`. -- `chrome.bargeInRmsThreshold: 650`: рівень RMS, що вважається людським + і записує аудіо у `chrome.audioFormat` +- `chrome.audioOutputCommand`: команда SoX, що читає аудіо у `chrome.audioFormat` + і записує до CoreAudio `BlackHole 2ch` +- `chrome.bargeInInputCommand`: необов’язкова команда локального мікрофона, яка + записує підписаний 16-бітний little-endian моно PCM для виявлення втручання + людини, поки активне відтворення асистента. Наразі це стосується + розміщеного на Gateway мосту пари команд `chrome`. +- `chrome.bargeInRmsThreshold: 650`: RMS-рівень, що рахується людським перериванням на `chrome.bargeInInputCommand` -- `chrome.bargeInPeakThreshold: 2500`: піковий рівень, що вважається людським +- `chrome.bargeInPeakThreshold: 2500`: піковий рівень, що рахується людським перериванням на `chrome.bargeInInputCommand` - `chrome.bargeInCooldownMs: 900`: мінімальна затримка між повторними очищеннями - людських переривань + людського переривання - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` - `realtime.instructions`: короткі усні відповіді, з `openclaw_agent_consult` для глибших відповідей -- `realtime.introMessage`: коротка усна перевірка готовності, коли realtime-міст - під’єднується; установіть `""`, щоб приєднатися беззвучно +- `realtime.introMessage`: коротка усна перевірка готовності, коли + realtime-міст підключається; встановіть `""`, щоб приєднуватися мовчки - `realtime.agentId`: необов’язковий ідентифікатор агента OpenClaw для `openclaw_agent_consult`; типове значення — `main` @@ -1025,12 +1041,12 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` типово має значення `true`; із транспортом Twilio він делегує -фактичний PSTN-виклик, DTMF і вступне привітання до Plugin Voice Call. Voice Call -відтворює послідовність DTMF перед відкриттям realtime-медіапотоку, а потім використовує -збережений вступний текст як початкове realtime-привітання. Якщо `voice-call` не -увімкнено, Google Meet усе ще може перевірити та записати план набору, але не може -здійснити виклик Twilio. +Типове значення `voiceCall.enabled` — `true`; із транспортом Twilio вона +делегує фактичний PSTN-дзвінок, DTMF і вступне привітання Plugin Voice Call. +Voice Call відтворює послідовність DTMF перед відкриттям realtime-медіапотоку, +а потім використовує збережений вступний текст як початкове realtime-привітання. +Якщо `voice-call` не ввімкнено, Google Meet усе ще може перевірити й записати +план набору, але не може здійснити Twilio-дзвінок. ## Інструмент @@ -1045,36 +1061,40 @@ export GEMINI_API_KEY=... } ``` -Використовуйте `transport: "chrome"`, коли Chrome працює на хості Gateway. Використовуйте -`transport: "chrome-node"`, коли Chrome працює на спареному вузлі, наприклад у Parallels -VM. В обох випадках realtime-модель і `openclaw_agent_consult` працюють на хості -Gateway, тому облікові дані моделі залишаються там. +Використовуйте `transport: "chrome"`, коли Chrome працює на хості Gateway. +Використовуйте `transport: "chrome-node"`, коли Chrome працює на спареному node, +наприклад Parallels VM. В обох випадках realtime-модель і +`openclaw_agent_consult` працюють на хості Gateway, тому облікові дані моделі +залишаються там. -Використовуйте `action: "status"`, щоб перелічити активні сесії або перевірити ідентифікатор сесії. Використовуйте -`action: "speak"` із `sessionId` і `message`, щоб realtime-агент -заговорив негайно. Використовуйте `action: "test_speech"`, щоб створити або повторно використати сесію, -запустити відому фразу й повернути стан `inCall`, коли хост Chrome може -про нього повідомити. `test_speech` завжди примусово встановлює `mode: "realtime"` і завершується помилкою, якщо його просять -працювати в `mode: "transcribe"`, оскільки сесії лише для спостереження навмисно не можуть -видавати мовлення. Його результат `speechOutputVerified` базується на збільшенні байтів realtime-аудіовиходу -під час цього тестового виклику, тому повторно використана сесія зі старішим аудіо -не вважається новою успішною перевіркою мовлення. Використовуйте `action: "leave"`, щоб позначити -сесію завершеною. +Використовуйте `action: "status"`, щоб перелічити активні сесії або перевірити +ідентифікатор сесії. Використовуйте `action: "speak"` з `sessionId` і `message`, +щоб realtime-агент заговорив негайно. Використовуйте `action: "test_speech"`, +щоб створити або повторно використати сесію, запустити відому фразу та повернути +стан `inCall`, коли хост Chrome може про нього повідомити. `test_speech` завжди +примусово встановлює `mode: "realtime"` і завершується помилкою, якщо попросити +його запуститися в `mode: "transcribe"`, бо сесії лише для спостереження +навмисно не можуть видавати мовлення. Його результат `speechOutputVerified` +базується на збільшенні байтів realtime-аудіовиходу під час цього тестового +виклику, тому повторно використана сесія зі старішим аудіо не рахується як +свіжа успішна перевірка мовлення. Використовуйте `action: "leave"`, щоб +позначити сесію завершеною. `status` містить стан Chrome, коли він доступний: -- `inCall`: Chrome, схоже, перебуває всередині виклику Meet -- `micMuted`: найкраща можлива оцінка стану мікрофона Meet -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профілю - браузера потрібен ручний вхід, допуск від організатора Meet, дозволи або - відновлення керування браузером, перш ніж мовлення зможе працювати -- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: чи - кероване мовлення Chrome дозволене зараз. `speechReady: false` означає, що OpenClaw - не надіслав вступну/тестову фразу в аудіоміст. -- `providerConnected` / `realtimeReady`: стан realtime-голосового мосту -- `lastInputAt` / `lastOutputAt`: останнє аудіо, побачене з мосту або надіслане до нього -- `lastSuppressedInputAt` / `suppressedInputBytes`: вхід local loopback, проігнорований, поки - відтворення асистента активне +- `inCall`: Chrome, схоже, перебуває всередині дзвінка Meet +- `micMuted`: стан мікрофона Meet за принципом найкращого зусилля +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профіль + браузера потребує ручного входу, допуску від хоста Meet, дозволів або ремонту + керування браузером, перш ніж мовлення зможе працювати +- `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: чи дозволене + кероване мовлення Chrome зараз. `speechReady: false` означає, що OpenClaw не + надіслав вступну/тестову фразу до аудіомоста. +- `providerConnected` / `realtimeReady`: стан realtime-голосового моста +- `lastInputAt` / `lastOutputAt`: останнє аудіо, побачене з моста або надіслане + до нього +- `lastSuppressedInputAt` / `suppressedInputBytes`: local loopback-вхід, + проігнорований, поки активне відтворення асистента ```json { @@ -1086,39 +1106,44 @@ Gateway, тому облікові дані моделі залишаються ## Realtime-консультація агента -Realtime-режим Chrome оптимізований для живого голосового циклу. Realtime-голосовий -провайдер чує аудіо зустрічі й говорить через налаштований аудіоміст. -Коли realtime-моделі потрібне глибше міркування, актуальна інформація або звичайні -інструменти OpenClaw, вона може викликати `openclaw_agent_consult`. +Realtime-режим Chrome оптимізований для живого голосового циклу. Realtime +голосовий провайдер чує аудіо зустрічі й говорить через налаштований +аудіоміст. Коли realtime-моделі потрібне глибше міркування, актуальна інформація +або звичайні інструменти OpenClaw, вона може викликати +`openclaw_agent_consult`. -Інструмент консультації запускає звичайного агента OpenClaw у фоновому режимі з контекстом -нещодавньої стенограми зустрічі й повертає стислу усну відповідь до realtime- -голосової сесії. Потім голосова модель може вимовити цю відповідь назад у зустріч. -Він використовує той самий спільний realtime-інструмент консультації, що й Voice Call. +Інструмент консультації запускає звичайного агента OpenClaw у фоновому режимі з +контекстом нещодавньої транскрипції зустрічі та повертає стислу усну відповідь +до realtime-голосової сесії. Голосова модель потім може промовити цю відповідь +назад у зустріч. Він використовує той самий спільний інструмент +realtime-консультації, що й Voice Call. -Типово консультації виконуються для агента `main`. Установіть `realtime.agentId`, коли -канал Meet має консультуватися зі спеціальним робочим простором агента OpenClaw, типовими параметрами моделі, -політикою інструментів, пам’яттю та історією сесій. +Типово консультації виконуються для агента `main`. Встановіть +`realtime.agentId`, коли lane Meet має консультуватися з окремим робочим +простором агента OpenClaw, типовими значеннями моделі, політикою інструментів, +пам’яттю та історією сесії. `realtime.toolPolicy` керує запуском консультації: -- `safe-read-only`: надати інструмент консультації й обмежити звичайного агента до - `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і +- `safe-read-only`: відкрити інструмент консультації та обмежити звичайного + агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. -- `owner`: надати інструмент консультації й дозволити звичайному агенту використовувати стандартну - політику інструментів агента. -- `none`: не надавати інструмент консультації realtime-голосовій моделі. +- `owner`: відкрити інструмент консультації та дозволити звичайному агенту + використовувати звичайну політику інструментів агента. +- `none`: не відкривати інструмент консультації для realtime голосової моделі. -Ключ сесії консультації обмежений кожною сесією Meet, тому подальші виклики консультації -можуть повторно використовувати попередній контекст консультації протягом тієї самої зустрічі. +Ключ сесії консультації обмежений кожною сесією Meet, тому подальші виклики +консультації можуть повторно використовувати попередній контекст консультації +під час тієї самої зустрічі. -Щоб примусово запустити усну перевірку готовності після того, як Chrome повністю приєднався до виклику: +Щоб примусово виконати усну перевірку готовності після повного приєднання +Chrome до дзвінка: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Для повної перевірки smoke з приєднанням і мовленням: +Для повного smoke-тесту приєднання й мовлення: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1126,9 +1151,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --message "Say exactly: I'm here and listening." ``` -## Чеклист live-тесту +## Чекліст live-тесту -Використовуйте цю послідовність, перш ніж передавати зустріч агенту без нагляду: +Використовуйте цю послідовність перед передаванням зустрічі автономному агенту: ```bash openclaw googlemeet setup @@ -1141,14 +1166,14 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ Очікуваний стан Chrome-node: - `googlemeet setup` повністю зелений. -- `googlemeet setup` включає `chrome-node-connected`, коли Chrome-node є - стандартним транспортом або вузол закріплено. -- `nodes status` показує вибраний вузол як підключений. -- Вибраний вузол оголошує і `googlemeet.chrome`, і `browser.proxy`. -- Вкладка Meet приєднується до виклику, а `test-speech` повертає стан Chrome з +- `googlemeet setup` містить `chrome-node-connected`, коли Chrome-node є + типовим транспортом або node закріплено. +- `nodes status` показує, що вибраний node підключено. +- Вибраний node оголошує і `googlemeet.chrome`, і `browser.proxy`. +- Вкладка Meet приєднується до дзвінка, а `test-speech` повертає стан Chrome з `inCall: true`. -Для віддаленого хоста Chrome, наприклад macOS VM у Parallels, це найкоротша +Для віддаленого хоста Chrome, наприклад Parallels macOS VM, це найкоротша безпечна перевірка після оновлення Gateway або VM: ```bash @@ -1160,12 +1185,11 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Це підтверджує, що Plugin Gateway завантажено, вузол VM підключено з поточним +Це доводить, що Plugin Gateway завантажено, node VM підключено з поточним токеном, а аудіоміст Meet доступний до того, як агент відкриє реальну вкладку зустрічі. -Для smoke-перевірки Twilio використовуйте зустріч, яка надає дані для -телефонного дозвону: +Для Twilio smoke використовуйте зустріч, що надає телефонні дані для набору: ```bash openclaw googlemeet setup @@ -1177,19 +1201,20 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Очікуваний стан Twilio: -- `googlemeet setup` включає зелені перевірки `twilio-voice-call-plugin`, +- `googlemeet setup` містить зелені перевірки `twilio-voice-call-plugin`, `twilio-voice-call-credentials` і `twilio-voice-call-webhook`. - `voicecall` доступний у CLI після перезавантаження Gateway. -- Повернута сесія має `transport: "twilio"` і `twilio.voiceCallId`. -- `openclaw logs --follow` показує, що DTMF TwiML віддано перед realtime TwiML, - а потім realtime-міст із початковим привітанням у черзі. -- `googlemeet leave ` завершує делегований голосовий виклик. +- Повернена сесія має `transport: "twilio"` і `twilio.voiceCallId`. +- `openclaw logs --follow` показує, що DTMF TwiML надано перед realtime TwiML, + а потім realtime-міст із поставленим у чергу початковим привітанням. +- `googlemeet leave ` завершує делегований голосовий дзвінок. ## Усунення несправностей ### Агент не бачить інструмент Google Meet -Підтвердьте, що Plugin увімкнено в конфігурації Gateway, і перезавантажте Gateway: +Підтвердьте, що Plugin увімкнено в конфігурації Gateway, і перезавантажте +Gateway: ```bash openclaw plugins list | grep google-meet @@ -1200,16 +1225,16 @@ openclaw googlemeet setup перезавантажте Gateway. Запущений агент бачить лише інструменти Plugin, зареєстровані поточним процесом Gateway. -На хостах Gateway не з macOS інструмент `google_meet`, видимий агенту, залишається -доступним, але локальні realtime-дії Chrome блокуються до потрапляння в -аудіоміст. Локальне realtime-аудіо Chrome наразі залежить від macOS -`BlackHole 2ch`, тож агенти Linux мають використовувати `mode: "transcribe"`, -дозвін Twilio або хост `chrome-node` на macOS замість стандартного локального +На хостах Gateway не з macOS агентський інструмент `google_meet` залишається +видимим, але локальні realtime-дії Chrome блокуються до того, як потраплять до +аудіомоста. Локальне realtime-аудіо Chrome наразі залежить від macOS +`BlackHole 2ch`, тому Linux-агентам слід використовувати `mode: "transcribe"`, +Twilio-набір або хост macOS `chrome-node` замість типового локального realtime-шляху Chrome. -### Немає підключеного вузла з підтримкою Google Meet +### Немає підключеного node з підтримкою Google Meet -На хості вузла виконайте: +На хості node виконайте: ```bash openclaw plugins enable google-meet @@ -1218,7 +1243,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -На хості Gateway схваліть вузол і перевірте команди: +На хості Gateway схваліть node і перевірте команди: ```bash openclaw devices list @@ -1226,8 +1251,8 @@ openclaw devices approve openclaw nodes status ``` -Вузол має бути підключений і містити `googlemeet.chrome` плюс `browser.proxy`. -Конфігурація Gateway має дозволяти ці команди вузла: +Node має бути підключений і перелічувати `googlemeet.chrome` плюс +`browser.proxy`. Конфігурація Gateway має дозволяти ці команди node: ```json5 { @@ -1240,7 +1265,7 @@ openclaw nodes status ``` Якщо `googlemeet setup` не проходить `chrome-node-connected` або журнал Gateway -повідомляє `gateway token mismatch`, перевстановіть або перезапустіть вузол із +повідомляє `gateway token mismatch`, перевстановіть або перезапустіть node з поточним токеном Gateway. Для LAN Gateway це зазвичай означає: ```bash @@ -1252,7 +1277,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -Потім перезавантажте службу вузла й повторно виконайте: +Потім перезавантажте службу node і повторно виконайте: ```bash openclaw googlemeet setup @@ -1261,59 +1286,57 @@ openclaw nodes status --connected ### Браузер відкривається, але агент не може приєднатися -Виконайте `googlemeet test-listen` для приєднань лише для спостереження або -`googlemeet test-speech` для realtime-приєднань, а потім перевірте повернутий -стан Chrome. Якщо будь-яка з перевірок повідомляє `manualActionRequired: true`, +Запустіть `googlemeet test-listen` для приєднань лише для спостереження або +`googlemeet test-speech` для realtime-приєднань, а потім перегляньте повернений +стан Chrome. Якщо будь-яка перевірка повідомляє `manualActionRequired: true`, покажіть `manualActionMessage` оператору й припиніть повторні спроби, доки дію в браузері не буде завершено. Поширені ручні дії: -- Увійти в профіль Chrome. -- Допустити гостя з облікового запису організатора Meet. -- Надати Chrome дозволи на мікрофон/камеру, коли з’явиться нативний запит - дозволу Chrome. -- Закрити або виправити завислий діалог дозволів Meet. +- Увійти до профілю Chrome. +- Допустити гостя з облікового запису хоста Meet. +- Надати дозволи Chrome на мікрофон/камеру, коли з’явиться нативний запит + дозволів Chrome. +- Закрити або відремонтувати завислий діалог дозволів Meet. -Не повідомляйте "не виконано вхід" лише тому, що Meet показує "Хочете, щоб люди чули вас -на зустрічі?" Це проміжний екран вибору аудіо в Meet; OpenClaw -натискає **Використовувати мікрофон** через браузерну автоматизацію, коли це доступно, і продовжує -чекати на справжній стан зустрічі. Для резервного браузерного режиму лише створення OpenClaw -може натиснути **Продовжити без мікрофона**, бо для створення URL не потрібен -шлях аудіо в реальному часі. +Не повідомляйте "не виконано вхід" лише тому, що Meet показує "Чи хочете ви, щоб люди чули вас на зустрічі?" Це аудіо-проміжний екран вибору Meet; OpenClaw натискає **Використовувати мікрофон** через браузерну автоматизацію, коли це доступно, і продовжує чекати на реальний стан зустрічі. Для браузерного резервного режиму лише створення OpenClaw може натиснути **Продовжити без мікрофона**, бо створення URL не потребує шляху realtime-аудіо. ### Не вдається створити зустріч `googlemeet create` спочатку використовує endpoint Google Meet API `spaces.create`, коли налаштовано облікові дані OAuth. Без облікових даних OAuth він переходить -до закріпленого браузера Chrome node. Перевірте: +до резервного використання закріпленого браузера вузла Chrome. Перевірте: - Для створення через API: налаштовано `oauth.clientId` і `oauth.refreshToken`, або наявні відповідні змінні середовища `OPENCLAW_GOOGLE_MEET_*`. -- Для створення через API: refresh token було згенеровано після додавання підтримки +- Для створення через API: refresh token було випущено після додавання підтримки створення. У старіших токенах може бракувати scope `meetings.space.created`; повторно виконайте - `openclaw googlemeet auth login --json` і оновіть конфігурацію Plugin. -- Для резервного браузерного режиму: `defaultTransport: "chrome-node"` і - `chromeNode.node` вказують на підключений node з `browser.proxy` і + `openclaw googlemeet auth login --json` і оновіть конфігурацію plugin. +- Для браузерного резервного режиму: `defaultTransport: "chrome-node"` і + `chromeNode.node` вказують на підключений вузол із `browser.proxy` та `googlemeet.chrome`. -- Для резервного браузерного режиму: профіль OpenClaw Chrome на цьому node увійшов - у Google і може відкрити `https://meet.google.com/new`. -- Для резервного браузерного режиму: повторні спроби повторно використовують наявну вкладку `https://meet.google.com/new` - або вкладку запиту облікового запису Google перед відкриттям нової вкладки. Якщо агент перевищує час очікування, - повторіть виклик інструмента, а не відкривайте вручну ще одну вкладку Meet. -- Для резервного браузерного режиму: якщо інструмент повертає `manualActionRequired: true`, використовуйте - повернені `browser.nodeId`, `browser.targetId`, `browserUrl` і - `manualActionMessage`, щоб скерувати оператора. Не повторюйте спроби в циклі, доки цю - дію не буде завершено. -- Для резервного браузерного режиму: якщо Meet показує "Хочете, щоб люди чули вас на - зустрічі?", залиште вкладку відкритою. OpenClaw має натиснути **Використовувати мікрофон** або, для - резервного режиму лише створення, **Продовжити без мікрофона** через браузерну - автоматизацію та продовжити чекати на згенерований URL Meet. Якщо це неможливо, в - помилці має згадуватися `meet-audio-choice-required`, а не `google-login-required`. +- Для браузерного резервного режиму: профіль OpenClaw Chrome на цьому вузлі + увійшов у Google і може відкрити `https://meet.google.com/new`. +- Для браузерного резервного режиму: повторні спроби повторно використовують + наявну вкладку `https://meet.google.com/new` або вкладку запиту облікового + запису Google перед відкриттям нової вкладки. Якщо agent перевищує час + очікування, повторіть виклик інструмента замість ручного відкриття іншої + вкладки Meet. +- Для браузерного резервного режиму: якщо інструмент повертає + `manualActionRequired: true`, використайте повернені `browser.nodeId`, + `browser.targetId`, `browserUrl` і `manualActionMessage`, щоб скерувати + оператора. Не повторюйте спроби в циклі, доки цю дію не буде завершено. +- Для браузерного резервного режиму: якщо Meet показує "Чи хочете ви, щоб люди + чули вас на зустрічі?", залиште вкладку відкритою. OpenClaw має натиснути + **Використовувати мікрофон** або, для резервного режиму лише створення, + **Продовжити без мікрофона** через браузерну автоматизацію і продовжити + чекати на згенерований URL Meet. Якщо це неможливо, помилка має згадувати + `meet-audio-choice-required`, а не `google-login-required`. -### Агент приєднується, але не говорить +### Agent приєднується, але не говорить -Перевірте шлях реального часу: +Перевірте realtime-шлях: ```bash openclaw googlemeet setup @@ -1321,37 +1344,38 @@ openclaw googlemeet doctor ``` Використовуйте `mode: "realtime"` для прослуховування/відповіді голосом. `mode: "transcribe"` навмисно -не запускає дуплексний голосовий міст реального часу. Для налагодження лише спостереження -виконайте `openclaw googlemeet status --json ` після того, як учасники заговорять, -і перевірте `captioning`, `transcriptLines` та `lastCaptionText`. Якщо `inCall` має -значення true, але `transcriptLines` залишається `0`, субтитри Meet можуть бути вимкнені, ніхто -не говорив після встановлення спостерігача, інтерфейс Meet змінився або живі -субтитри недоступні для мови/облікового запису зустрічі. +не запускає duplex realtime voice bridge. Для налагодження лише спостереження +запустіть `openclaw googlemeet status --json ` після того, як учасники +заговорять, і перевірте `captioning`, `transcriptLines` та `lastCaptionText`. Якщо `inCall` має +значення true, але `transcriptLines` залишається `0`, субтитри Meet можуть бути +вимкнені, ніхто не говорив після встановлення спостерігача, UI Meet змінився або +live captions недоступні для мови/облікового запису цієї зустрічі. -`googlemeet test-speech` завжди перевіряє шлях реального часу й повідомляє, чи -було помічено байти виходу моста для цього виклику. Якщо `speechOutputVerified` має значення false і -`speechOutputTimedOut` має значення true, провайдер реального часу міг прийняти -висловлювання, але OpenClaw не побачив, щоб нові вихідні байти дійшли до аудіомоста Chrome. +`googlemeet test-speech` завжди перевіряє realtime-шлях і повідомляє, чи було +зафіксовано вихідні байти bridge для цього виклику. Якщо `speechOutputVerified` має значення false, а +`speechOutputTimedOut` має значення true, realtime provider міг прийняти +висловлювання, але OpenClaw не побачив, що нові вихідні байти досягли Chrome audio +bridge. Також перевірте: -- Ключ провайдера реального часу доступний на хості Gateway, наприклад +- Ключ realtime provider доступний на хості Gateway, наприклад `OPENAI_API_KEY` або `GEMINI_API_KEY`. - `BlackHole 2ch` видно на хості Chrome. - `sox` існує на хості Chrome. -- Мікрофон і динамік Meet маршрутизовано через віртуальний аудіошлях, який використовує - OpenClaw. +- Мікрофон і динамік Meet спрямовано через віртуальний аудіошлях, який + використовує OpenClaw. -`googlemeet doctor [session-id]` друкує сесію, node, стан перебування у дзвінку, -причину ручної дії, підключення провайдера реального часу, `realtimeReady`, активність -аудіовходу/аудіовиходу, останні часові мітки аудіо, лічильники байтів і URL браузера. -Використовуйте `googlemeet status [session-id] --json`, коли потрібен сирий JSON. Використовуйте -`googlemeet doctor --oauth`, коли потрібно перевірити оновлення Google Meet OAuth -без розкриття токенів; додайте `--meeting` або `--create-space`, коли також потрібне -підтвердження Google Meet API. +`googlemeet doctor [session-id]` виводить session, node, стан in-call, +причину ручної дії, підключення realtime provider, `realtimeReady`, активність +аудіовходу/аудіовиходу, останні audio timestamps, byte counters і browser URL. +Використовуйте `googlemeet status [session-id] --json`, коли потрібен raw JSON. Використовуйте +`googlemeet doctor --oauth`, коли потрібно перевірити Google Meet OAuth refresh +без розкриття токенів; додайте `--meeting` або `--create-space`, коли також +потрібен доказ Google Meet API. -Якщо агент перевищив час очікування й ви бачите вже відкриту вкладку Meet, перевірте цю вкладку, -не відкриваючи ще одну: +Якщо agent перевищив час очікування і ви бачите, що вкладка Meet уже відкрита, +перевірте цю вкладку, не відкриваючи іншу: ```bash openclaw googlemeet recover-tab @@ -1359,21 +1383,21 @@ openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` Еквівалентна дія інструмента — `recover_current_tab`. Вона фокусує та перевіряє -наявну вкладку Meet для вибраного транспорту. З `chrome` вона використовує локальне +наявну вкладку Meet для вибраного transport. З `chrome` вона використовує локальне керування браузером через Gateway; з `chrome-node` вона використовує налаштований -Chrome node. Вона не відкриває нову вкладку й не створює нову сесію; вона повідомляє -поточний блокувальник, наприклад стан входу, допуску, дозволів або вибору аудіо. -Команда CLI звертається до налаштованого Gateway, тож Gateway має бути запущений; -`chrome-node` також вимагає, щоб Chrome node був підключений. +вузол Chrome. Вона не відкриває нову вкладку й не створює нову session; вона +повідомляє поточний blocker, наприклад стан login, admission, permissions або +audio-choice. Команда CLI звертається до налаштованого Gateway, тому Gateway має +бути запущений; `chrome-node` також вимагає, щоб вузол Chrome був підключений. -### Перевірки налаштування Twilio не проходять +### Не проходять перевірки налаштування Twilio -`twilio-voice-call-plugin` завершується помилкою, коли `voice-call` не дозволено або не ввімкнено. -Додайте його до `plugins.allow`, увімкніть `plugins.entries.voice-call` і перезавантажте -Gateway. +`twilio-voice-call-plugin` завершується помилкою, коли `voice-call` не дозволено +або не ввімкнено. Додайте його до `plugins.allow`, увімкніть +`plugins.entries.voice-call` і перезавантажте Gateway. -`twilio-voice-call-credentials` завершується помилкою, коли бекенду Twilio бракує account -SID, auth token або номера абонента. Установіть їх на хості Gateway: +`twilio-voice-call-credentials` завершується помилкою, коли в backend Twilio +бракує account SID, auth token або caller number. Налаштуйте їх на хості Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1381,12 +1405,12 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -`twilio-voice-call-webhook` завершується помилкою, коли `voice-call` не має публічного Webhook -експонування або коли `publicUrl` вказує на loopback чи приватний мережевий простір. -Установіть `plugins.entries.voice-call.config.publicUrl` на публічний URL провайдера або -налаштуйте тунель/Tailscale експонування `voice-call`. +`twilio-voice-call-webhook` завершується помилкою, коли `voice-call` не має +публічного доступу webhook або коли `publicUrl` вказує на loopback чи простір +приватної мережі. Установіть `plugins.entries.voice-call.config.publicUrl` на +публічний URL provider або налаштуйте tunnel/Tailscale exposure для `voice-call`. -Loopback і приватні URL непридатні для carrier callbacks. Не використовуйте +Loopback і приватні URL недійсні для carrier callbacks. Не використовуйте `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, `192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`. @@ -1409,8 +1433,8 @@ Loopback і приватні URL непридатні для carrier callbacks. } ``` -Для локальної розробки використовуйте тунель або Tailscale експонування замість приватного -URL хоста: +Для локальної розробки використовуйте tunnel або Tailscale exposure замість URL +приватного хоста: ```json5 { @@ -1436,23 +1460,24 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` за замовчуванням перевіряє лише готовність. Щоб виконати dry-run для конкретного номера: +`voicecall smoke` за замовчуванням перевіряє лише готовність. Щоб виконати dry-run +для конкретного номера: ```bash openclaw voicecall smoke --to "+15555550123" ``` -Додавайте `--yes` лише тоді, коли навмисно хочете здійснити живий вихідний -дзвінок-сповіщення: +Додавайте `--yes` лише тоді, коли навмисно хочете здійснити реальний вихідний +notify call: ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### Дзвінок Twilio починається, але ніколи не входить у зустріч +### Виклик Twilio починається, але ніколи не входить у зустріч -Переконайтеся, що подія Meet містить дані телефонного dial-in. Передайте точний dial-in -номер і PIN або власну DTMF послідовність: +Переконайтеся, що подія Meet містить дані phone dial-in. Передайте точний +dial-in number і PIN або власну DTMF sequence: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1461,73 +1486,76 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -Використовуйте початкові `w` або коми в `--dtmf-sequence`, якщо провайдеру потрібна пауза -перед введенням PIN. +Використовуйте початкові `w` або коми в `--dtmf-sequence`, якщо provider потребує +паузи перед введенням PIN. -Якщо телефонний дзвінок створено, але список учасників Meet ніколи не показує dial-in -учасника: +Якщо телефонний виклик створено, але roster Meet ніколи не показує dial-in +participant: -- Виконайте `openclaw googlemeet doctor `, щоб підтвердити делегований Twilio - call ID, чи було поставлено DTMF у чергу та чи було запрошено вступне привітання. -- Виконайте `openclaw voicecall status --call-id ` і підтвердьте, що дзвінок досі - активний. -- Виконайте `openclaw voicecall tail` і перевірте, що Twilio webhooks надходять до - Gateway. -- Виконайте `openclaw logs --follow` і шукайте послідовність Twilio Meet: Google +- Запустіть `openclaw googlemeet doctor `, щоб підтвердити делегований + Twilio call ID, чи було поставлено DTMF у чергу, і чи було запитано вступне + привітання. +- Запустіть `openclaw voicecall status --call-id ` і переконайтеся, що виклик + усе ще активний. +- Запустіть `openclaw voicecall tail` і перевірте, що Twilio webhooks надходять + до Gateway. +- Запустіть `openclaw logs --follow` і знайдіть послідовність Twilio Meet: Google Meet делегує приєднання, Voice Call зберігає pre-connect DTMF TwiML, віддає - цей початковий TwiML, потім віддає realtime TwiML і запускає міст реального часу + цей початковий TwiML, потім віддає realtime TwiML і запускає realtime bridge з `initialGreeting=queued`. -- Повторно виконайте `openclaw googlemeet setup --transport twilio`; зелена перевірка налаштування - обов’язкова, але вона не доводить, що PIN послідовність зустрічі правильна. -- Переконайтеся, що dial-in номер належить до того самого запрошення Meet і регіону, що й - PIN. -- Збільште початкові паузи в `--dtmf-sequence`, якщо Meet відповідає повільно, наприклад - `wwww123456#`. -- Якщо учасник приєднується, але ви не чуєте привітання, перевірте - `openclaw logs --follow` на realtime TwiML, запуск моста реального часу та - `initialGreeting=queued`. Привітання генерується з початкового - повідомлення `voicecall.start` після підключення моста реального часу. +- Повторно запустіть `openclaw googlemeet setup --transport twilio`; успішна + перевірка setup потрібна, але вона не доводить, що PIN sequence зустрічі + правильна. +- Переконайтеся, що dial-in number належить тому самому запрошенню Meet і регіону, + що й PIN. +- Збільште початкові паузи в `--dtmf-sequence`, якщо Meet відповідає повільно, + наприклад `wwww123456#`. +- Якщо participant приєднується, але ви не чуєте привітання, перевірте + `openclaw logs --follow` на наявність realtime TwiML, запуску realtime bridge і + `initialGreeting=queued`. Привітання генерується з початкового повідомлення + `voicecall.start` після підключення realtime bridge. -Якщо webhooks не надходять, спочатку налагодьте Voice Call plugin: провайдер має -досягати `plugins.entries.voice-call.config.publicUrl` або налаштованого тунелю. -Див. [Усунення несправностей голосових дзвінків](/uk/plugins/voice-call#troubleshooting). +Якщо webhooks не надходять, спочатку налагодьте Voice Call plugin: provider має +досягати `plugins.entries.voice-call.config.publicUrl` або налаштованого tunnel. +Див. [Усунення несправностей голосових викликів](/uk/plugins/voice-call#troubleshooting). ## Примітки -Офіційний медіа-API Google Meet орієнтований на отримання, тож для мовлення в дзвінок Meet -досі потрібен шлях учасника. Цей Plugin залишає цю межу видимою: -Chrome обробляє участь у браузері та локальну маршрутизацію аудіо; Twilio обробляє -участь через телефонний dial-in. +Офіційний media API Google Meet орієнтований на приймання, тому мовлення в +дзвінок Meet усе ще потребує participant path. Цей plugin робить цю межу +видимою: Chrome обробляє браузерну участь і локальну маршрутизацію аудіо; Twilio +обробляє участь через phone dial-in. -Режим реального часу Chrome потребує `BlackHole 2ch` плюс одне з такого: +Chrome realtime mode потребує `BlackHole 2ch` плюс одне з наведеного: - `chrome.audioInputCommand` плюс `chrome.audioOutputCommand`: OpenClaw володіє - мостом моделі реального часу й передає аудіо у `chrome.audioFormat` між цими - командами та вибраним провайдером голосу реального часу. Типовий шлях Chrome — - 24 kHz PCM16; 8 kHz G.711 mu-law залишається доступним для застарілих пар команд. -- `chrome.audioBridgeCommand`: зовнішня команда моста володіє всім локальним - аудіошляхом і має завершитися після запуску або перевірки свого демона. + realtime model bridge і передає аудіо у `chrome.audioFormat` між цими + командами та вибраним realtime voice provider. Стандартний шлях Chrome — це + 24 kHz PCM16; 8 kHz G.711 mu-law залишається доступним для legacy command pairs. +- `chrome.audioBridgeCommand`: зовнішня bridge command володіє всім локальним + аудіошляхом і має завершитися після запуску або перевірки свого daemon. -Для чистого дуплексного аудіо маршрутизуйте вихід Meet і мікрофон Meet через окремі -віртуальні пристрої або граф віртуального пристрою в стилі Loopback. Один спільний -пристрій BlackHole може відлунювати інших учасників назад у дзвінок. +Для чистого duplex-аудіо спрямовуйте вихід Meet і мікрофон Meet через окремі +віртуальні пристрої або граф віртуальних пристроїв у стилі Loopback. Один +спільний пристрій BlackHole може повертати інших учасників назад у дзвінок як +луна. -З командною парою моста Chrome `chrome.bargeInInputCommand` може слухати окремий -локальний мікрофон і очищати відтворення асистента, коли людина починає -говорити. Це тримає людське мовлення попереду виходу асистента, навіть коли спільний -loopback вхід BlackHole тимчасово приглушений під час відтворення асистента. -Як і `chrome.audioInputCommand` та `chrome.audioOutputCommand`, це -локальна команда, налаштована оператором. Використовуйте явний довірений шлях команди або -список аргументів і не спрямовуйте її на скрипти з недовірених розташувань. +З command-pair Chrome bridge `chrome.bargeInInputCommand` може слухати окремий +локальний мікрофон і очищати відтворення assistant, коли людина починає говорити. +Це зберігає людське мовлення попереду виводу assistant навіть тоді, коли спільний +BlackHole loopback input тимчасово приглушено під час відтворення assistant. +Як і `chrome.audioInputCommand` та `chrome.audioOutputCommand`, це локальна +команда, налаштована оператором. Використовуйте явний trusted command path або +argument list і не вказуйте на scripts із ненадійних розташувань. -`googlemeet speak` запускає активний аудіоміст реального часу для сесії Chrome. -`googlemeet leave` зупиняє цей міст. Для сесій Twilio, делегованих -через Voice Call plugin, `leave` також завершує базовий голосовий дзвінок. -Використовуйте `googlemeet end-active-conference`, коли також хочете закрити активну -конференцію Google Meet для простору, керованого API. +`googlemeet speak` запускає активний realtime audio bridge для session Chrome. +`googlemeet leave` зупиняє цей bridge. Для sessions Twilio, делегованих через +Voice Call plugin, `leave` також завершує базовий voice call. Використовуйте +`googlemeet end-active-conference`, коли також хочете закрити активну конференцію +Google Meet для API-managed space. ## Пов’язане -- [Voice call plugin](/uk/plugins/voice-call) +- [Voice Call plugin](/uk/plugins/voice-call) - [Режим розмови](/uk/nodes/talk) - [Створення plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/plugin-inventory.md b/docs/uk/plugins/plugin-inventory.md new file mode 100644 index 000000000..736198730 --- /dev/null +++ b/docs/uk/plugins/plugin-inventory.md @@ -0,0 +1,164 @@ +--- +read_when: + - Ви вирішуєте, чи постачається Plugin у основному пакеті npm, чи встановлюється окремо + - Ви оновлюєте метадані пакета вбудованого Plugin або автоматизацію випуску + - Вам потрібен канонічний список внутрішніх і зовнішніх плагінів +summary: Згенерований інвентар плагінів OpenClaw, що постачаються в ядрі, публікуються зовнішньо або зберігаються лише у вихідному коді +title: Інвентаризація Plugin +x-i18n: + generated_at: "2026-05-02T09:29:49Z" + model: gpt-5.5 + provider: openai + source_hash: 49e4471cfd5e217e0ac8a55d3ed942c8b32f2606fdcfe19797144038d5eb75e2 + source_path: plugins/plugin-inventory.md + workflow: 16 +--- + +# Інвентар Plugin + +Ця сторінка згенерована з `extensions/*/package.json`, `openclaw.plugin.json`, +і виключень `files` кореневого npm-пакета. Перегенеруйте її за допомогою: + +```bash +pnpm plugins:inventory:gen +``` + +## Визначення + +- **Основний npm-пакет:** вбудований у npm-пакет `openclaw` і доступний без окремого встановлення Plugin. +- **Офіційний зовнішній пакет:** Plugin, який підтримує OpenClaw, вилучений з основного npm-пакета та встановлюється через ClawHub і/або npm. +- **Лише checkout вихідного коду:** локальний для репозиторію Plugin, вилучений з опублікованих npm-артефактів і не рекламується як пакет, доступний для встановлення. + +Checkout-и вихідного коду відрізняються від встановлень npm: після `pnpm install` вбудовані +Plugin завантажуються з `extensions/`, тому локальні зміни та локальні для пакета workspace-залежності +доступні. + +## Основний npm-пакет + +| Plugin | Пакет | Поверхня | Документація | Встановлення | +| --------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------- | +| alibaba | `@openclaw/alibaba-provider` | contracts: videoGenerationProviders | [alibaba](/uk/providers/alibaba) | включено до OpenClaw | +| amazon-bedrock | `@openclaw/amazon-bedrock-provider` | providers: amazon-bedrock; contracts: memoryEmbeddingProviders | [amazon-bedrock](/uk/providers/bedrock) | включено до OpenClaw | +| amazon-bedrock-mantle | `@openclaw/amazon-bedrock-mantle-provider` | providers: amazon-bedrock-mantle | [amazon-bedrock-mantle](/uk/providers/bedrock-mantle) | включено до OpenClaw | +| anthropic | `@openclaw/anthropic-provider` | providers: anthropic; contracts: mediaUnderstandingProviders | [anthropic](/uk/providers/anthropic) | включено до OpenClaw | +| anthropic-vertex | `@openclaw/anthropic-vertex-provider` | providers: anthropic-vertex | - | включено до OpenClaw | +| arcee | `@openclaw/arcee-provider` | providers: arcee | [arcee](/uk/providers/arcee) | включено до OpenClaw | +| azure-speech | `@openclaw/azure-speech` | contracts: speechProviders | [azure-speech](/uk/providers/azure-speech) | включено до OpenClaw | +| bonjour | `@openclaw/bonjour` | plugin | - | включено до OpenClaw | +| browser | `@openclaw/browser-plugin` | contracts: tools; skills | [browser](/uk/tools/browser) | включено до OpenClaw | +| byteplus | `@openclaw/byteplus-provider` | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders | - | включено до OpenClaw | +| cerebras | `@openclaw/cerebras-provider` | providers: cerebras | [cerebras](/uk/providers/cerebras) | включено до OpenClaw | +| chutes | `@openclaw/chutes-provider` | providers: chutes | [chutes](/uk/providers/chutes) | включено до OpenClaw | +| cloudflare-ai-gateway | `@openclaw/cloudflare-ai-gateway-provider` | providers: cloudflare-ai-gateway | [cloudflare-ai-gateway](/uk/providers/cloudflare-ai-gateway) | включено до OpenClaw | +| comfy | `@openclaw/comfy-provider` | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders | [comfy](/uk/providers/comfy) | включено до OpenClaw | +| copilot-proxy | `@openclaw/copilot-proxy` | providers: copilot-proxy | - | включено до OpenClaw | +| deepgram | `@openclaw/deepgram-provider` | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders | [deepgram](/uk/providers/deepgram) | включено до OpenClaw | +| deepinfra | `@openclaw/deepinfra-provider` | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders | [deepinfra](/uk/providers/deepinfra) | включено до OpenClaw | +| deepseek | `@openclaw/deepseek-provider` | providers: deepseek | [deepseek](/uk/providers/deepseek) | включено до OpenClaw | +| document-extract | `@openclaw/document-extract-plugin` | contracts: documentExtractors | [document-extract](/uk/tools/pdf) | включено до OpenClaw | +| duckduckgo | `@openclaw/duckduckgo-plugin` | contracts: webSearchProviders | [duckduckgo](/uk/tools/duckduckgo-search) | включено до OpenClaw | +| elevenlabs | `@openclaw/elevenlabs-speech` | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders | [elevenlabs](/uk/providers/elevenlabs) | включено до OpenClaw | +| exa | `@openclaw/exa-plugin` | contracts: webSearchProviders | [exa](/uk/tools/exa-search) | включено до OpenClaw | +| fal | `@openclaw/fal-provider` | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders | [fal](/uk/providers/fal) | включено до OpenClaw | +| file-transfer | `@openclaw/file-transfer` | contracts: tools | - | включено до OpenClaw | +| firecrawl | `@openclaw/firecrawl-plugin` | contracts: tools, webFetchProviders, webSearchProviders | [firecrawl](/uk/tools/firecrawl) | включено до OpenClaw | +| fireworks | `@openclaw/fireworks-provider` | providers: fireworks | [fireworks](/uk/providers/fireworks) | включено до OpenClaw | +| github-copilot | `@openclaw/github-copilot-provider` | providers: github-copilot; contracts: memoryEmbeddingProviders | [github-copilot](/uk/providers/github-copilot) | включено до OpenClaw | +| google | `@openclaw/google-plugin` | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders | [google](/uk/providers/google) | включено до OpenClaw | +| gradium | `@openclaw/gradium-speech` | contracts: speechProviders | [gradium](/uk/providers/gradium) | включено до OpenClaw | +| groq | `@openclaw/groq-provider` | providers: groq; contracts: mediaUnderstandingProviders | [groq](/uk/providers/groq) | включено до OpenClaw | +| huggingface | `@openclaw/huggingface-provider` | providers: huggingface | [huggingface](/uk/providers/huggingface) | включено до OpenClaw | +| imessage | `@openclaw/imessage` | channels: imessage | [imessage](/uk/channels/imessage) | включено до OpenClaw | +| inworld | `@openclaw/inworld-speech` | contracts: speechProviders | [inworld](/uk/providers/inworld) | включено до OpenClaw | +| irc | `@openclaw/irc` | channels: irc | [irc](/uk/channels/irc) | включено до OpenClaw | +| kilocode | `@openclaw/kilocode-provider` | providers: kilocode | [kilocode](/uk/providers/kilocode) | включено до OpenClaw | +| kimi | `@openclaw/kimi-provider` | providers: kimi, kimi-coding | [kimi](/uk/providers/moonshot) | включено до OpenClaw | +| litellm | `@openclaw/litellm-provider` | providers: litellm; contracts: imageGenerationProviders | [litellm](/uk/providers/litellm) | включено до OpenClaw | +| llm-task | `@openclaw/llm-task` | contracts: tools | - | включено до OpenClaw | +| lmstudio | `@openclaw/lmstudio-provider` | providers: lmstudio; contracts: memoryEmbeddingProviders | [lmstudio](/uk/providers/lmstudio) | включено до OpenClaw | +| memory-core | `@openclaw/memory-core` | contracts: memoryEmbeddingProviders, tools | - | включено до OpenClaw | +| memory-wiki | `@openclaw/memory-wiki` | contracts: tools; skills | [memory-wiki](/uk/plugins/memory-wiki) | включено до OpenClaw | +| microsoft | `@openclaw/microsoft-speech` | contracts: speechProviders | - | включено до OpenClaw | +| microsoft-foundry | `@openclaw/microsoft-foundry` | providers: microsoft-foundry | - | включено до OpenClaw | +| migrate-claude | `@openclaw/migrate-claude` | contracts: migrationProviders | - | включено до OpenClaw | +| migrate-hermes | `@openclaw/migrate-hermes` | contracts: migrationProviders | - | включено до OpenClaw | +| minimax | `@openclaw/minimax-provider` | providers: minimax, minimax-portal; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders, webSearchProviders | [minimax](/uk/providers/minimax) | включено до OpenClaw | +| mistral | `@openclaw/mistral-provider` | providers: mistral; contracts: mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders | [mistral](/uk/providers/mistral) | включено до OpenClaw | +| moonshot | `@openclaw/moonshot-provider` | providers: moonshot; contracts: mediaUnderstandingProviders, webSearchProviders | [moonshot](/uk/providers/moonshot) | включено до OpenClaw | +| nvidia | `@openclaw/nvidia-provider` | providers: nvidia | [nvidia](/uk/providers/nvidia) | включено до OpenClaw | +| ollama | `@openclaw/ollama-provider` | providers: ollama; contracts: memoryEmbeddingProviders, webSearchProviders | [ollama](/uk/providers/ollama) | включено до OpenClaw | +| open-prose | `@openclaw/open-prose` | skills | - | включено до OpenClaw | +| openai | `@openclaw/openai-provider` | providers: openai, openai-codex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders | [openai](/uk/providers/openai) | включено до OpenClaw | +| opencode | `@openclaw/opencode-provider` | providers: opencode; contracts: mediaUnderstandingProviders | [opencode](/uk/providers/opencode) | включено до OpenClaw | +| opencode-go | `@openclaw/opencode-go-provider` | providers: opencode-go; contracts: mediaUnderstandingProviders | [opencode-go](/uk/providers/opencode-go) | включено до OpenClaw | +| openrouter | `@openclaw/openrouter-provider` | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, speechProviders, videoGenerationProviders | [openrouter](/uk/providers/openrouter) | включено до OpenClaw | +| openshell | `@openclaw/openshell-sandbox` | plugin | - | включено до OpenClaw | +| perplexity | `@openclaw/perplexity-plugin` | contracts: webSearchProviders | [perplexity](/uk/tools/perplexity-search) | входить до OpenClaw | +| qianfan | `@openclaw/qianfan-provider` | providers: qianfan | [qianfan](/uk/providers/qianfan) | входить до OpenClaw | +| qwen | `@openclaw/qwen-provider` | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders | [qwen](/uk/providers/qwen) | входить до OpenClaw | +| runway | `@openclaw/runway-provider` | contracts: videoGenerationProviders | [runway](/uk/providers/runway) | входить до OpenClaw | +| searxng | `@openclaw/searxng-plugin` | contracts: webSearchProviders | - | входить до OpenClaw | +| senseaudio | `@openclaw/senseaudio-provider` | contracts: mediaUnderstandingProviders | [senseaudio](/uk/providers/senseaudio) | входить до OpenClaw | +| sglang | `@openclaw/sglang-provider` | providers: sglang | [sglang](/uk/providers/sglang) | входить до OpenClaw | +| signal | `@openclaw/signal` | channels: signal | [signal](/uk/channels/signal) | входить до OpenClaw | +| skill-workshop | `@openclaw/skill-workshop` | contracts: tools | [skill-workshop](/uk/plugins/skill-workshop) | входить до OpenClaw | +| slack | `@openclaw/slack` | channels: slack | [slack](/uk/channels/slack) | входить до OpenClaw | +| stepfun | `@openclaw/stepfun-provider` | providers: stepfun, stepfun-plan | [stepfun](/uk/providers/stepfun) | входить до OpenClaw | +| synthetic | `@openclaw/synthetic-provider` | providers: synthetic | [synthetic](/uk/providers/synthetic) | входить до OpenClaw | +| tavily | `@openclaw/tavily-plugin` | contracts: tools, webSearchProviders; skills | [tavily](/uk/tools/tavily) | входить до OpenClaw | +| telegram | `@openclaw/telegram` | channels: telegram | [telegram](/uk/channels/telegram) | входить до OpenClaw | +| tencent | `@openclaw/tencent-provider` | providers: tencent-tokenhub | [tencent](/uk/providers/tencent) | входить до OpenClaw | +| together | `@openclaw/together-provider` | providers: together; contracts: videoGenerationProviders | [together](/uk/providers/together) | входить до OpenClaw | +| tokenjuice | `@openclaw/tokenjuice` | contracts: agentToolResultMiddleware | [tokenjuice](/uk/tools/tokenjuice) | входить до OpenClaw | +| tts-local-cli | `@openclaw/tts-local-cli` | contracts: speechProviders | - | входить до OpenClaw | +| venice | `@openclaw/venice-provider` | providers: venice | [venice](/uk/providers/venice) | входить до OpenClaw | +| vercel-ai-gateway | `@openclaw/vercel-ai-gateway-provider` | providers: vercel-ai-gateway | [vercel-ai-gateway](/uk/providers/vercel-ai-gateway) | входить до OpenClaw | +| vllm | `@openclaw/vllm-provider` | providers: vllm | [vllm](/uk/providers/vllm) | входить до OpenClaw | +| volcengine | `@openclaw/volcengine-provider` | providers: volcengine, volcengine-plan; contracts: speechProviders | [volcengine](/uk/providers/volcengine) | входить до OpenClaw | +| voyage | `@openclaw/voyage-provider` | contracts: memoryEmbeddingProviders | - | входить до OpenClaw | +| vydra | `@openclaw/vydra-provider` | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders | [vydra](/uk/providers/vydra) | входить до OpenClaw | +| web-readability | `@openclaw/web-readability-plugin` | contracts: webContentExtractors | - | входить до OpenClaw | +| webhooks | `@openclaw/webhooks` | plugin | [webhooks](/uk/plugins/webhooks) | входить до OpenClaw | +| xai | `@openclaw/xai-plugin` | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders | [xai](/uk/providers/xai) | входить до OpenClaw | +| xiaomi | `@openclaw/xiaomi-provider` | providers: xiaomi; contracts: speechProviders | [xiaomi](/uk/providers/xiaomi) | входить до OpenClaw | +| zai | `@openclaw/zai-provider` | providers: zai; contracts: mediaUnderstandingProviders | [zai](/uk/providers/zai) | входить до OpenClaw | + +## Офіційні зовнішні пакети + +| Plugin | Пакет | Поверхня | Документація | Встановлення | +| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------- | +| acpx | `@openclaw/acpx` | Skills | [acpx](/uk/tools/acp-agents-setup) | ClawHub + npm: `@openclaw/acpx` | +| bluebubbles | `@openclaw/bluebubbles` | channels: bluebubbles | [bluebubbles](/uk/channels/bluebubbles) | ClawHub + npm: `@openclaw/bluebubbles` | +| brave | `@openclaw/brave-plugin` | contracts: webSearchProviders | [brave](/uk/tools/brave-search) | ClawHub + npm: `@openclaw/brave-plugin` | +| codex | `@openclaw/codex` | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders | [codex](/uk/plugins/codex-harness) | ClawHub + npm: `@openclaw/codex` | +| diagnostics-otel | `@openclaw/diagnostics-otel` | Plugin | - | ClawHub + npm: `@openclaw/diagnostics-otel` | +| diagnostics-prometheus | `@openclaw/diagnostics-prometheus` | Plugin | - | ClawHub + npm: `@openclaw/diagnostics-prometheus` | +| diffs | `@openclaw/diffs` | contracts: tools; Skills | - | ClawHub + npm: `@openclaw/diffs` | +| discord | `@openclaw/discord` | channels: discord | [discord](/uk/channels/discord) | ClawHub + npm: `@openclaw/discord` | +| feishu | `@openclaw/feishu` | channels: feishu; contracts: tools; Skills | [feishu](/uk/channels/feishu) | ClawHub + npm: `@openclaw/feishu` | +| google-meet | `@openclaw/google-meet` | contracts: tools | [google-meet](/uk/plugins/google-meet) | ClawHub + npm: `@openclaw/google-meet` | +| googlechat | `@openclaw/googlechat` | channels: googlechat | [googlechat](/uk/channels/googlechat) | ClawHub + npm: `@openclaw/googlechat` | +| line | `@openclaw/line` | channels: line | [line](/uk/channels/line) | ClawHub + npm: `@openclaw/line` | +| lobster | `@openclaw/lobster` | contracts: tools | - | ClawHub + npm: `@openclaw/lobster` | +| matrix | `@openclaw/matrix` | channels: matrix | [matrix](/uk/channels/matrix) | ClawHub + npm: `@openclaw/matrix` | +| mattermost | `@openclaw/mattermost` | channels: mattermost | [mattermost](/uk/channels/mattermost) | ClawHub + npm: `@openclaw/mattermost` | +| memory-lancedb | `@openclaw/memory-lancedb` | contracts: tools | [memory-lancedb](/uk/plugins/memory-lancedb) | ClawHub + npm: `@openclaw/memory-lancedb` | +| msteams | `@openclaw/msteams` | channels: msteams | [msteams](/uk/channels/msteams) | ClawHub + npm: `@openclaw/msteams` | +| nextcloud-talk | `@openclaw/nextcloud-talk` | channels: nextcloud-talk | [nextcloud-talk](/uk/channels/nextcloud-talk) | ClawHub + npm: `@openclaw/nextcloud-talk` | +| nostr | `@openclaw/nostr` | channels: nostr | [nostr](/uk/channels/nostr) | ClawHub + npm: `@openclaw/nostr` | +| qqbot | `@openclaw/qqbot` | channels: qqbot; contracts: tools; Skills | [qqbot](/uk/channels/qqbot) | ClawHub + npm: `@openclaw/qqbot` | +| synology-chat | `@openclaw/synology-chat` | channels: synology-chat | [synology-chat](/uk/channels/synology-chat) | ClawHub + npm: `@openclaw/synology-chat` | +| tlon | `@openclaw/tlon` | channels: tlon; contracts: tools; Skills | [tlon](/uk/channels/tlon) | ClawHub + npm: `@openclaw/tlon` | +| twitch | `@openclaw/twitch` | channels: twitch | [twitch](/uk/channels/twitch) | ClawHub + npm: `@openclaw/twitch` | +| voice-call | `@openclaw/voice-call` | contracts: tools | [voice-call](/uk/plugins/voice-call) | ClawHub + npm: `@openclaw/voice-call` | +| whatsapp | `@openclaw/whatsapp` | channels: whatsapp | [whatsapp](/uk/channels/whatsapp) | ClawHub + npm: `@openclaw/whatsapp` | +| zalo | `@openclaw/zalo` | channels: zalo | [zalo](/uk/channels/zalo) | ClawHub + npm: `@openclaw/zalo` | +| zalouser | `@openclaw/zalouser` | channels: zalouser; contracts: tools | [zalouser](/uk/channels/zalouser), [zalouser](/uk/plugins/zalouser) | ClawHub + npm: `@openclaw/zalouser` | + +## Лише checkout із вихідного коду + +| Plugin | Пакет | Поверхня | Документація | Встановлення | +| ---------- | ---------------------- | -------------------- | ---------------------------------- | -------------------- | +| qa-channel | `@openclaw/qa-channel` | channels: qa-channel | [qa-channel](/uk/channels/qa-channel) | лише checkout із вихідного коду | +| qa-lab | `@openclaw/qa-lab` | Plugin | - | лише checkout із вихідного коду | +| qa-matrix | `@openclaw/qa-matrix` | Plugin | - | лише checkout із вихідного коду | diff --git a/docs/uk/plugins/voice-call.md b/docs/uk/plugins/voice-call.md index e3b9165b5..f4a782589 100644 --- a/docs/uk/plugins/voice-call.md +++ b/docs/uk/plugins/voice-call.md @@ -1,21 +1,21 @@ --- read_when: - Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw - - Ви налаштовуєте або розробляєте Plugin для голосових викликів - - Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція для телефонії + - Ви налаштовуєте або розробляєте Plugin голосових викликів + - Вам потрібен голос у реальному часі або потокова транскрипція в телефонії sidebarTitle: Voice call -summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з опційною голосовою взаємодією в реальному часі та потоковою транскрипцією +summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з опційним голосом у реальному часі та потоковою транскрипцією title: Plugin голосових викликів x-i18n: - generated_at: "2026-05-02T07:52:42Z" + generated_at: "2026-05-02T09:29:40Z" model: gpt-5.5 provider: openai - source_hash: fc27646aca94c88d50d42838e166ac81eba3373154797cbb564e9c2eab0533fa + source_hash: 8f04b14ad1aafcc6036aff2301d9d0210c0cde333051ed89d498c51b4e0c0353 source_path: plugins/voice-call.md workflow: 16 --- -Voice calls for OpenClaw через Plugin. Підтримує вихідні сповіщення, +Голосові виклики для OpenClaw через plugin. Підтримує вихідні сповіщення, багатоходові розмови, повнодуплексний голос у реальному часі, потокову транскрипцію та вхідні виклики з політиками allowlist. @@ -24,7 +24,7 @@ Voice calls for OpenClaw через Plugin. Підтримує вихідні с speech), `mock` (розробка/без мережі). -Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте +Plugin Voice Call працює **усередині процесу Gateway**. Якщо ви використовуєте віддалений Gateway, установіть і налаштуйте plugin на машині, де працює Gateway, а потім перезапустіть Gateway, щоб завантажити його. @@ -32,14 +32,14 @@ Gateway, а потім перезапустіть Gateway, щоб заванта ## Швидкий старт - + - + ```bash openclaw plugins install @openclaw/voice-call ``` - + ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin openclaw plugins install "$PLUGIN_SRC" @@ -48,39 +48,38 @@ Gateway, а потім перезапустіть Gateway, щоб заванта - Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія - пакета походить зі старішої зовнішньої гілки пакування; використовуйте - поточну пакетовану збірку OpenClaw або шлях до локальної папки, доки не буде - опубліковано новіший npm-пакет. + Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія пакета + походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку + OpenClaw або шлях до локальної папки, доки не буде опубліковано новіший npm-пакет. Після цього перезапустіть Gateway, щоб plugin завантажився. - - Задайте конфігурацію в `plugins.entries.voice-call.config` (повну форму див. - у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні: + + Установіть конфігурацію в `plugins.entries.voice-call.config` (див. + [Конфігурація](#configuration) нижче для повної структури). Мінімально потрібні: `provider`, облікові дані провайдера, `fromNumber` і публічно - доступний URL Webhook. + доступний URL webhook. - + ```bash openclaw voicecall setup ``` - Типовий вивід зручно читати в журналах чату й терміналах. Він перевіряє, - чи plugin увімкнений, облікові дані провайдера, доступність Webhook і те, + Типовий вивід зручний для читання в журналах чату й терміналах. Він перевіряє + увімкнення plugin, облікові дані провайдера, доступність webhook, а також те, що активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте `--json` для скриптів. - + ```bash openclaw voicecall smoke openclaw voicecall smoke --to "+15555550123" ``` - Обидві команди за замовчуванням виконують пробний запуск. Додайте `--yes`, - щоб фактично здійснити короткий вихідний виклик-сповіщення: + Обидві команди за замовчуванням виконують пробний запуск без реального виклику. Додайте `--yes`, щоб фактично здійснити короткий + вихідний виклик-сповіщення: ```bash openclaw voicecall smoke --to "+15555550123" --yes @@ -90,23 +89,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта -Для Twilio, Telnyx і Plivo налаштування має визначати **публічний URL Webhook**. -Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний serve-варіант -визначається як loopback чи приватний мережевий простір, налаштування -завершується помилкою замість запуску провайдера, який не зможе отримувати -Webhook від операторів. +Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічний URL webhook**. +Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve +визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість +запуску провайдера, який не зможе отримувати carrier webhooks. ## Конфігурація Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних, -під час запуску Gateway записує попередження про неповне налаштування з -відсутніми ключами та пропускає запуск runtime. Команди, RPC-виклики й -інструменти агента все одно повертають точну відсутню конфігурацію провайдера -під час використання. +під час запуску Gateway у журнал записується попередження setup-incomplete з відсутніми ключами, і +runtime не запускається. Команди, RPC-виклики та інструменти агента все одно +повертають точну відсутню конфігурацію провайдера під час використання. -Облікові дані voice-call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Облікові дані voice-call підтримують SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface). ```json5 @@ -120,6 +117,17 @@ Webhook від операторів. fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio toNumber: "+15550005678", sessionScope: "per-phone", // per-phone | per-call + numbers: { + "+15550009999": { + inboundGreeting: "Silver Fox Cards, how can I help?", + responseSystemPrompt: "You are a concise baseball card specialist.", + tts: { + providers: { + openai: { voice: "alloy" }, + }, + }, + }, + }, twilio: { accountSid: "ACxxxxxxxx", @@ -168,28 +176,28 @@ Webhook від операторів. ``` - - - Twilio, Telnyx і Plivo всі потребують **публічно доступного** URL Webhook. + + - Twilio, Telnyx і Plivo вимагають **публічно доступного** URL webhook. - `mock` — локальний dev-провайдер (без мережевих викликів). - - Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true. - - `skipSignatureVerification` призначено лише для локального тестування. - - На безкоштовному рівні ngrok задайте `publicUrl` як точний URL ngrok; перевірка підпису завжди примусова. - - `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки. - - URL безкоштовного рівня ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Для production надавайте перевагу стабільному домену або funnel Tailscale. + - Telnyx вимагає `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true. + - `skipSignatureVerification` призначений лише для локального тестування. + - На безкоштовному рівні ngrok установіть `publicUrl` у точний URL ngrok; перевірка підпису завжди примусово застосовується. + - `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Twilio webhooks з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки. + - URL безкоштовного рівня Ngrok можуть змінюватися або додавати проміжну сторінку; якщо `publicUrl` зміститься, підписи Twilio не пройдуть перевірку. Для продакшну надавайте перевагу стабільному домену або Tailscale funnel. - + - `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`. - - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів. - - `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих pre-start сокетів на IP-адресу джерела. - - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (pending + active). + - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту. + - `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети до старту для кожної вихідної IP-адреси. + - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних). - - Старіші конфігурації, які використовують `provider: "log"`, `twilio.from` або застарілі + + Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`. - Runtime fallback поки що все ще приймає старі ключі voice-call, але - шлях переписування — `openclaw doctor --fix`, а compat shim є + Runtime fallback поки що приймає старі ключі voice-call, але + шлях переписування — це `openclaw doctor --fix`, а сумісний shim є тимчасовим. Автоматично мігровані ключі streaming: @@ -205,16 +213,16 @@ Webhook від операторів. ## Область сесії -За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, тож -повторні виклики від того самого абонента зберігають пам’ять розмови. Задайте -`sessionScope: "per-call"`, коли кожен операторський виклик має починатися зі -свіжим контекстом, наприклад для рецепції, бронювання, IVR або потоків мосту -Google Meet, де той самий номер телефону може представляти різні зустрічі. +За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, щоб повторні виклики від +того самого абонента зберігали пам’ять розмови. Установіть `sessionScope: "per-call"`, коли +кожен carrier call має починатися зі свіжого контексту, наприклад для рецепції, +бронювання, IVR або bridge-потоків Google Meet, де той самий номер телефону може +представляти різні зустрічі. ## Голосові розмови в реальному часі -`realtime` вибирає повнодуплексного голосового провайдера реального часу для -живого аудіо виклику. Це окремо від `streaming`, який лише передає аудіо +`realtime` вибирає провайдера повнодуплексного голосу в реальному часі для live call +audio. Це окремо від `streaming`, який лише пересилає аудіо провайдерам транскрипції в реальному часі. @@ -225,25 +233,25 @@ Google Meet, де той самий номер телефону може пре Поточна поведінка runtime: - `realtime.enabled` підтримується для Twilio Media Streams. -- `realtime.provider` необов’язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу. -- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми provider plugins. +- `realtime.provider` необов’язковий. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі. +- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми provider plugins. - Сира конфігурація, якою володіє провайдер, розміщується в `realtime.providers.`. -- Voice Call за замовчуванням надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абонент просить глибше міркування, актуальну інформацію або звичайні інструменти OpenClaw. -- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спочатку шукає проіндексовану пам’ять/контекст сесії для запитання consult і повертає ці фрагменти моделі реального часу в межах `realtime.fastContext.timeoutMs`, перш ніж переходити до повного consult agent лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true. -- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного голосового провайдера реального часу, Voice Call записує попередження й пропускає realtime media замість того, щоб зупиняти весь plugin. -- Ключі сесії consult повторно використовують збережену сесію виклику, коли вона доступна, а потім повертаються до налаштованого `sessionScope` (`per-phone` за замовчуванням або `per-call` для ізольованих викликів). +- Voice Call за замовчуванням надає спільний realtime-інструмент `openclaw_agent_consult`. Модель realtime може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw. +- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спочатку шукає індексовану пам’ять/контекст сесії для consult-запитання й повертає ці фрагменти realtime-моделі в межах `realtime.fastContext.timeoutMs`, перш ніж повертатися до повного consult-агента лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true. +- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жоден провайдер голосу в реальному часі взагалі не зареєстрований, Voice Call записує попередження в журнал і пропускає realtime media замість того, щоб завершити роботу всього plugin з помилкою. +- Ключі consult-сесії повторно використовують збережену сесію виклику, коли вона доступна, а потім повертаються до налаштованого `sessionScope` (`per-phone` за замовчуванням або `per-call` для ізольованих викликів). ### Політика інструментів -`realtime.toolPolicy` керує запуском consult: +`realtime.toolPolicy` керує consult-запуском: -| Політика | Поведінка | +| Політика | Поведінка | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `safe-read-only` | Надає інструмент consult і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. | -| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати стандартну політику інструментів агента. | -| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` все одно передаються провайдеру реального часу. | +| `safe-read-only` | Надає consult-інструмент і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. | +| `owner` | Надає consult-інструмент і дозволяє звичайному агенту використовувати нормальну політику інструментів агента. | +| `none` | Не надає consult-інструмент. Користувацькі `realtime.tools` усе одно передаються провайдеру realtime. | -### Приклади провайдерів реального часу +### Приклади провайдерів realtime @@ -304,23 +312,22 @@ Google Meet, де той самий номер телефону може пре -Див. [провайдер Google](/uk/providers/google) і -[провайдер OpenAI](/uk/providers/openai), щоб переглянути специфічні для провайдера -параметри голосу реального часу. +Див. [провайдера Google](/uk/providers/google) і +[провайдера OpenAI](/uk/providers/openai) для специфічних для провайдера опцій голосу realtime. ## Потокова транскрипція -`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику. +`streaming` вибирає провайдера транскрипції в реальному часі для live call audio. Поточна поведінка runtime: -- `streaming.provider` є необов’язковим. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера транскрибування в реальному часі. -- Вбудовані провайдери транскрибування в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми провайдерськими plugins. -- Необроблена конфігурація, якою володіє провайдер, розміщується в `streaming.providers.`. -- Після того як Twilio надсилає прийняте повідомлення `start` для потоку, Voice Call негайно реєструє потік, ставить вхідні медіадані в чергу через провайдера транскрибування, доки провайдер підключається, і запускає початкове привітання лише після готовності транскрибування в реальному часі. -- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жоден провайдер не зареєстрований, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб спричинити збій усього plugin. +- `streaming.provider` необов'язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого постачальника транскрипції в реальному часі. +- Вбудовані постачальники транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми provider plugins. +- Сира конфігурація, що належить постачальнику, зберігається в `streaming.providers.`. +- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через постачальника транскрипції, поки постачальник підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі. +- Якщо `streaming.provider` вказує на незареєстрованого постачальника або жодного постачальника не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість того, щоб спричинити збій усього Plugin. -### Приклади провайдерів потокового передавання +### Приклади постачальників потокового передавання @@ -391,8 +398,8 @@ Google Meet, де той самий номер телефону може пре ## TTS для викликів Voice Call використовує основну конфігурацію `messages.tts` для потокового -мовлення під час викликів. Її можна перевизначити в конфігурації plugin з -**такою самою структурою** — вона глибоко об’єднується з `messages.tts`. +мовлення під час викликів. Її можна перевизначити в конфігурації Plugin з +**такою самою формою** — вона глибоко зливається з `messages.tts`. ```json5 { @@ -409,17 +416,17 @@ Voice Call використовує основну конфігурацію `mes ``` -**Microsoft speech ігнорується для голосових викликів.** Телефонне аудіо потребує PCM; +**Microsoft speech ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM; поточний транспорт Microsoft не надає телефонний PCM-вивід. -Нотатки щодо поведінки: +Примітки щодо поведінки: -- Застарілі ключі `tts.` у конфігурації plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; закомічена конфігурація має використовувати `tts.providers.`. -- Основний TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до нативних голосів провайдера. -- Якщо медіапотік Twilio уже активний, Voice Call не повертається до TwiML ``. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується з помилкою замість змішування двох шляхів відтворення. -- Коли телефонний TTS повертається до резервного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження. -- Коли barge-in Twilio або завершення потоку очищає чергу очікування TTS, запити відтворення в черзі завершуються, а не залишають абонентів у завислому стані в очікуванні завершення відтворення. +- Застарілі ключі `tts.` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована в репозиторії конфігурація має використовувати `tts.providers.`. +- Основний TTS використовується, коли ввімкнено потокове передавання медіа Twilio; інакше виклики повертаються до нативних голосів постачальника. +- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML ``. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується помилкою замість змішування двох шляхів відтворення. +- Коли телефонний TTS повертається до вторинного постачальника, Voice Call записує попередження з ланцюжком постачальників (`from`, `to`, `attempts`) для налагодження. +- Коли втручання Twilio або демонтаж потоку очищає чергу TTS, запити на відтворення в черзі завершуються замість того, щоб залишати абонентів у стані очікування завершення відтворення. ### Приклади TTS @@ -462,7 +469,7 @@ Voice Call використовує основну конфігурацію `mes } ``` - + ```json5 { plugins: { @@ -499,64 +506,110 @@ Voice Call використовує основну конфігурацію `mes ``` -`inboundPolicy: "allowlist"` — це перевірка caller-ID з низьким рівнем гарантії. -Plugin нормалізує надане провайдером значення `From` і порівнює його з -`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і -цілісність payload, але вона **не** доводить володіння номером абонента -PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію caller-ID, а не як надійну -ідентифікацію абонента. +`inboundPolicy: "allowlist"` — це перевірка ідентифікатора абонента з низькою гарантією. Plugin нормалізує надане постачальником значення `From` і порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку постачальником і цілісність корисного навантаження, але **не** доводить володіння номером абонента PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію за caller ID, а не як надійну ідентичність абонента. -Автовідповіді використовують агентну систему. Налаштовуйте за допомогою `responseModel`, +Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`, `responseSystemPrompt` і `responseTimeoutMs`. -### Контракт мовленнєвого виводу +### Маршрутизація за номером -Для автовідповідей Voice Call додає до системного prompt строгий контракт -мовленнєвого виводу: +Використовуйте `numbers`, коли один Voice Call plugin приймає виклики для кількох телефонних +номерів і кожен номер має поводитися як окрема лінія. Наприклад, один +номер може використовувати невимушеного персонального помічника, а інший — бізнес- +персону, іншого агента відповіді та інший голос TTS. + +Маршрути вибираються з наданого постачальником набраного номера `To`. Ключі мають бути +номерами E.164. Коли надходить виклик, Voice Call один раз визначає відповідний маршрут, +зберігає зіставлений маршрут у записі виклику та повторно використовує цю ефективну конфігурацію +для привітання, класичного шляху автовідповіді, шляху консультації в реальному часі та +відтворення TTS. Якщо жоден маршрут не збігається, використовується глобальна конфігурація Voice Call. +Вихідні виклики не використовують `numbers`; передавайте вихідну ціль, повідомлення та +сеанс явно під час ініціювання виклику. + +Перевизначення маршрутів наразі підтримують: + +- `inboundGreeting` +- `tts` +- `agentId` +- `responseModel` +- `responseSystemPrompt` +- `responseTimeoutMs` + +Значення маршруту `tts` глибоко зливається поверх глобальної конфігурації Voice Call `tts`, тож +зазвичай можна перевизначити лише голос постачальника: + +```json5 +{ + inboundGreeting: "Hello from the main line.", + responseSystemPrompt: "You are the default voice assistant.", + tts: { + provider: "openai", + providers: { + openai: { voice: "coral" }, + }, + }, + numbers: { + "+15550001111": { + inboundGreeting: "Silver Fox Cards, how can I help?", + responseSystemPrompt: "You are a concise baseball card specialist.", + tts: { + providers: { + openai: { voice: "alloy" }, + }, + }, + }, + }, +} +``` + +### Контракт мовленого виводу + +Для автовідповідей Voice Call додає строгий контракт мовленого виводу до +системного prompt: ```text {"spoken":"..."} ``` -Voice Call обережно витягує текст мовлення: +Voice Call захисно витягує текст мовлення: -- Ігнорує payload, позначені як вміст reasoning/error. -- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`. -- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци з плануванням або метаданими. +- Ігнорує корисні навантаження, позначені як вміст reasoning/помилки. +- Розбирає прямий JSON, JSON у fenced-блоці або вбудовані ключі `"spoken"`. +- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаопису. -Це утримує мовленнєве відтворення зосередженим на тексті для абонента й запобігає +Це зосереджує мовлене відтворення на тексті для абонента й запобігає потраплянню тексту планування в аудіо. ### Поведінка запуску розмови -Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до -поточного стану відтворення: +Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного +стану відтворення: -- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється. -- Якщо початкове відтворення завершується з помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби. -- Початкове відтворення для потокового передавання Twilio починається під час підключення потоку без додаткової затримки. -- Barge-in перериває активне відтворення й очищає записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворене. -- Голосові розмови в реальному часі використовують власний початковий хід потоку в реальному часі. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сесії `` залишаються приєднаними. +- Очищення черги через втручання й автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється. +- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби. +- Початкове відтворення для потокового передавання Twilio запускається під час підключення потоку без додаткової затримки. +- Втручання перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворено. +- Голосові розмови в реальному часі використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сеанси `` залишаються приєднаними. -### Пільговий період відключення потоку Twilio +### Пільговий період від'єднання потоку Twilio -Коли медіапотік Twilio відключається, Voice Call очікує **2000 ms** перед +Коли медіапотік Twilio від'єднується, Voice Call чекає **2000 мс** перед автоматичним завершенням виклику: -- Якщо потік повторно підключається впродовж цього вікна, автоматичне завершення скасовується. +- Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується. - Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам. -## Очищення застарілих викликів +## Прибирач застарілих викликів -Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінальний -webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення +Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний +Webhook (наприклад, виклики в режимі сповіщення, що ніколи не завершуються). Типове значення — `0` (вимкнено). Рекомендовані діапазони: -- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень. -- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Добра початкова точка — `maxDurationSeconds + 30–60` секунд. +- **Production:** `120`–`300` секунд для потоків у стилі сповіщення. +- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд. ```json5 { @@ -575,26 +628,26 @@ webhook (наприклад, виклики в режимі сповіщення ## Безпека Webhook -Коли proxy або tunnel розташований перед Gateway, plugin -відтворює публічну URL-адресу для перевірки підпису. Ці параметри -контролюють, яким forwarded headers довіряти: +Коли перед Gateway стоїть проксі або тунель, Plugin +реконструює публічну URL-адресу для перевірки підпису. Ці параметри +керують тим, яким forwarded-заголовкам довіряти: - Список дозволених хостів із forwarding headers. + Список дозволених хостів із forwarding-заголовків. - Довіряти forwarded headers без списку дозволених. + Довіряти forwarded-заголовкам без списку дозволених. - Довіряти forwarded headers лише тоді, коли remote IP запиту відповідає списку. + Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. -Додаткові захисти: +Додатковий захист: -- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні webhook-запити підтверджуються, але пропускаються для побічних ефектів. -- Ходи розмови Twilio містять токен на кожен хід у callbacks ``, тому застарілі або повторно відтворені callbacks мовлення не можуть задовольнити новіший очікуваний хід transcript. -- Неавтентифіковані webhook-запити відхиляються до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера. -- Webhook voice-call використовує спільний pre-auth профіль тіла (64 KB / 5 секунд) плюс per-IP ліміт одночасних запитів до перевірки підпису. +- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені чинні webhook-запити підтверджуються, але пропускаються для побічних ефектів. +- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах ``, тому застарілі/повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід транскрипту. +- Неавтентифіковані webhook-запити відхиляються до читання тіла, коли відсутні обов'язкові signature-заголовки постачальника. +- Webhook voice-call використовує спільний pre-auth профіль тіла (64 КБ / 5 секунд) плюс ліміт одночасних запитів на IP перед перевіркою підпису. Приклад зі стабільним публічним хостом: @@ -631,14 +684,14 @@ openclaw voicecall expose --mode funnel ``` Коли Gateway уже запущено, операційні команди `voicecall` делегуються -runtime голосових викликів, яким володіє Gateway, щоб CLI не прив’язував другий +voice-call runtime, що належить Gateway, щоб CLI не прив'язував другий webhook-сервер. Якщо Gateway недоступний, команди повертаються до -автономного CLI runtime. +самостійного CLI runtime. -`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call. -Використовуйте `--file `, щоб вказати інший журнал, і `--last `, щоб обмежити -аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99 -для затримки ходу й часу очікування прослуховування. +`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call. +Використовуйте `--file `, щоб указати інший журнал, і `--last `, щоб обмежити +аналіз останніми N записами (за замовчуванням 200). Вивід містить p50/p90/p99 +для затримки ходу та часу очікування слухання. ## Інструмент агента @@ -653,11 +706,11 @@ webhook-сервер. Якщо Gateway недоступний, команди п | `end_call` | `callId` | | `get_status` | `callId` | -Цей repo постачає відповідний документ skill за шляхом `skills/voice-call/SKILL.md`. +Цей репозиторій постачається з відповідним документом Skills за адресою `skills/voice-call/SKILL.md`. ## Gateway RPC -| Метод | Аргументи | +| Метод | Аргументи | | -------------------- | ------------------------------------------ | | `voicecall.initiate` | `to?`, `message`, `mode?`, `dtmfSequence?` | | `voicecall.continue` | `callId`, `message` | @@ -666,13 +719,13 @@ webhook-сервер. Якщо Gateway недоступний, команди п | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі сповіщення +`dtmfSequence` чинний лише з `mode: "conversation"`. Виклики в режимі сповіщення мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні -цифри після підключення. +цифри після з’єднання. ## Усунення несправностей -### Налаштування не може виставити Webhook +### Налаштування не проходить через доступність webhook Запустіть налаштування з того самого середовища, у якому працює Gateway: @@ -681,11 +734,19 @@ openclaw voicecall setup openclaw voicecall setup --json ``` -Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований `publicUrl` усе одно завершується помилкою, коли він указує на локальний або приватний мережевий простір, оскільки оператор не може виконати зворотний виклик на ці адреси. Не використовуйте `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, `192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`. +Для `twilio`, `telnyx` і `plivo` стан `webhook-exposure` має бути зеленим. Налаштований +`publicUrl` усе одно не проходить перевірку, якщо він указує на локальний або приватний мережевий +простір, оскільки оператор не може виконати зворотний виклик на ці адреси. Не використовуйте +`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, +`192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`. -Вихідні дзвінки Twilio у режимі сповіщень надсилають початковий `` TwiML безпосередньо в запиті створення дзвінка, тому перше озвучене повідомлення не залежить від того, чи Twilio отримає webhook TwiML. Публічний webhook усе ще потрібен для зворотних викликів стану, розмовних дзвінків, DTMF перед з’єднанням, потоків реального часу та керування дзвінком після з’єднання. +Вихідні виклики Twilio в режимі сповіщення надсилають початковий `` TwiML безпосередньо в +запиті створення виклику, тому перше промовлене повідомлення не залежить від того, чи Twilio +отримає webhook TwiML. Публічний webhook усе одно потрібен для зворотних викликів стану, +розмовних викликів, DTMF до з’єднання, потоків у реальному часі та керування викликом +після з’єднання. -Використайте один шлях публічної доступності: +Використовуйте один шлях публічного доступу: ```json5 { @@ -712,19 +773,23 @@ openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` виконує пробний запуск, якщо не передати `--yes`. +`voicecall smoke` є пробним запуском, якщо не передати `--yes`. -### Облікові дані провайдера не працюють +### Облікові дані провайдера не проходять перевірку Перевірте вибраного провайдера та обов’язкові поля облікових даних: -- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber`, або `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`. -- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` і `fromNumber`. +- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber` або + `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`. +- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` і + `fromNumber`. - Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`. -Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє середовище. +Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки +не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить своє +середовище. -### Дзвінки запускаються, але webhook провайдера не надходять +### Виклики починаються, але webhook-и провайдера не надходять Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу webhook: @@ -732,7 +797,7 @@ openclaw voicecall smoke https://voice.example.com/voice/webhook ``` -Потім перегляньте стан виконання: +Потім перевірте стан виконання: ```bash openclaw voicecall status --call-id @@ -743,23 +808,30 @@ openclaw logs --follow Поширені причини: - `publicUrl` указує на інший шлях, ніж `serve.path`. -- URL тунелю змінився після запуску Gateway. +- URL тунелю змінилася після запуску Gateway. - Проксі пересилає запит, але видаляє або переписує заголовки host/proto. -- Брандмауер або DNS спрямовує публічне ім’я хоста не на Gateway. +- Брандмауер або DNS спрямовує публічне ім’я хоста кудись, окрім Gateway. - Gateway було перезапущено без увімкненого Plugin Voice Call. -Коли перед Gateway стоїть зворотний проксі або тунель, установіть `webhookSecurity.allowedHosts` на публічне ім’я хоста або використайте `webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте `webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під вашим контролем. +Коли перед Gateway стоїть зворотний проксі або тунель, задайте +`webhookSecurity.allowedHosts` як публічне ім’я хоста або використовуйте +`webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте +`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває +під вашим контролем. ### Перевірка підпису не проходить -Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відтворює з вхідного запиту. Якщо підписи не проходять перевірку: +Підписи провайдера перевіряються за публічною URL-адресою, яку OpenClaw відтворює +з вхідного запиту. Якщо перевірка підписів не проходить: -- Переконайтеся, що URL webhook у провайдера точно збігається з `publicUrl`, включно зі схемою, хостом і шляхом. -- Для URL ngrok безплатного рівня оновлюйте `publicUrl`, коли ім’я хоста тунелю змінюється. -- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте `webhookSecurity.allowedHosts`. +- Переконайтеся, що URL webhook провайдера точно збігається з `publicUrl`, включно зі + схемою, хостом і шляхом. +- Для URL ngrok безплатного рівня оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю. +- Переконайтеся, що проксі зберігає оригінальні заголовки host і proto, або налаштуйте + `webhookSecurity.allowedHosts`. - Не вмикайте `skipSignatureVerification` поза локальним тестуванням. -### Приєднання Google Meet через Twilio не працює +### Не вдається приєднатися до Google Meet через Twilio Google Meet використовує цей Plugin для приєднання через телефонний набір Twilio. Спочатку перевірте Voice Call: @@ -774,33 +846,43 @@ openclaw voicecall smoke --to "+15555550123" openclaw googlemeet setup --transport twilio ``` -Якщо Voice Call має зелений статус, але учасник Meet так і не приєднується, перевірте номер для телефонного підключення Meet, PIN і `--dtmf-sequence`. Телефонний дзвінок може бути справним, тоді як зустріч відхиляє або ігнорує неправильну послідовність DTMF. +Якщо Voice Call має зелений стан, але учасник Meet так і не приєднується, перевірте номер +для телефонного підключення Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як +зустріч відхиляє або ігнорує неправильну DTMF-послідовність. -Google Meet передає послідовність DTMF Meet і вступний текст у `voicecall.start`. Для дзвінків Twilio Voice Call спочатку обслуговує DTMF TwiML, перенаправляє назад на webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ було згенеровано після приєднання телефонного учасника до зустрічі. +Google Meet передає DTMF-послідовність Meet і вступний текст у `voicecall.start`. +Для викликів Twilio Voice Call спочатку віддає DTMF TwiML, переспрямовує назад до +webhook, а потім відкриває медіапотік у реальному часі, щоб збережений вступ генерувався +після того, як телефонний учасник приєднався до зустрічі. -Використовуйте `openclaw logs --follow` для трасування фази в реальному часі. Справне приєднання Twilio Meet записує такий порядок: +Використовуйте `openclaw logs --follow` для живого трасування фази. Справне приєднання Twilio Meet +реєструє такий порядок: - Google Meet делегує приєднання Twilio до Voice Call. -- Voice Call зберігає DTMF TwiML перед з’єднанням. -- Початковий TwiML Twilio споживається й обслуговується перед обробкою в реальному часі. -- Voice Call обслуговує TwiML реального часу для дзвінка Twilio. -- Міст реального часу запускається з поставленим у чергу початковим привітанням. +- Voice Call зберігає DTMF TwiML до з’єднання. +- Початковий TwiML Twilio споживається й віддається перед обробкою в реальному часі. +- Voice Call віддає TwiML реального часу для виклику Twilio. +- Міст реального часу запускається з початковим привітанням у черзі. -`openclaw voicecall tail` усе ще показує збережені записи дзвінків; це корисно для стану дзвінка й транскриптів, але не кожен перехід webhook або реального часу з’являється там. +`openclaw voicecall tail` усе ще показує збережені записи викликів; це корисно для +стану виклику й транскриптів, але не кожен webhook-перехід або перехід реального часу +там з’являється. -### У дзвінку реального часу немає мовлення +### Виклик у реальному часі не має мовлення -Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і `streaming.enabled` не можуть одночасно мати значення true. +Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і +`streaming.enabled` не можуть одночасно бути true. -Для дзвінків Twilio у реальному часі також перевірте: +Для викликів Twilio у реальному часі також перевірте: -- Plugin провайдера реального часу завантажено й зареєстровано. -- `realtime.provider` не встановлено або вказує на зареєстрованого провайдера. -- Ключ API провайдера доступний процесу Gateway. -- `openclaw logs --follow` показує, що TwiML реального часу обслуговується, міст реального часу запущено, а початкове привітання поставлено в чергу. +- Plugin провайдера реального часу завантажено та зареєстровано. +- `realtime.provider` не задано або він називає зареєстрованого провайдера. +- API-ключ провайдера доступний процесу Gateway. +- `openclaw logs --follow` показує, що TwiML реального часу віддано, міст реального часу + запущено, а початкове привітання поставлено в чергу. ## Пов’язане - [Режим розмови](/uk/nodes/talk) -- [Перетворення тексту на мовлення](/uk/tools/tts) +- [Синтез мовлення](/uk/tools/tts) - [Голосове пробудження](/uk/nodes/voicewake) diff --git a/docs/uk/tools/slash-commands.md b/docs/uk/tools/slash-commands.md index f9b025b2b..22e98c7c8 100644 --- a/docs/uk/tools/slash-commands.md +++ b/docs/uk/tools/slash-commands.md @@ -3,40 +3,40 @@ read_when: - Використання або налаштування чат-команд - Налагодження маршрутизації команд або дозволів sidebarTitle: Slash commands -summary: 'Слеш-команди: текстові проти нативних, конфігурація та підтримувані команди' +summary: 'Слеш-команди: текстові й нативні, конфігурація та підтримувані команди' title: Слеш-команди x-i18n: - generated_at: "2026-05-02T02:49:16Z" + generated_at: "2026-05-02T09:29:27Z" model: gpt-5.5 provider: openai - source_hash: 00a00619cc0eff25b81b475eab5b0b3d808bf067e6e004a491a90ec3982149b7 + source_hash: b469c4436dec92eb3712f71e5f54bf2c96b9b0b17d60a1533d8669c127caefee source_path: tools/slash-commands.md workflow: 16 --- Команди обробляє Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. Команда bash-чату лише для хоста використовує `! ` (з `/bash ` як псевдонімом). -Коли розмову або гілку прив’язано до ACP-сесії, звичайний подальший текст спрямовується до цього ACP harness. Команди керування Gateway усе одно залишаються локальними: `/acp ...` завжди потрапляє до обробника команд OpenClaw ACP, а `/status` і `/unfocus` залишаються локальними, коли для цієї поверхні ввімкнено обробку команд. +Коли розмову або тред прив’язано до сесії ACP, звичайний текст подальших повідомлень спрямовується до цього ACP harness. Команди керування Gateway все одно залишаються локальними: `/acp ...` завжди потрапляє до обробника команд ACP OpenClaw, а `/status` і `/unfocus` залишаються локальними щоразу, коли для поверхні ввімкнено обробку команд. Є дві пов’язані системи: - + Окремі повідомлення `/...`. - + `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - - Directives вилучаються з повідомлення до того, як модель його побачить. - - У звичайних повідомленнях чату (не лише з directives) вони трактуються як «вбудовані підказки» і **не** зберігають налаштування сесії. - - У повідомленнях лише з directives (повідомлення містить тільки directives) вони зберігаються в сесії й відповідають підтвердженням. - - Directives застосовуються лише для **авторизованих відправників**. Якщо встановлено `commands.allowFrom`, використовується тільки цей список дозволених; інакше авторизація походить зі списків дозволених каналу/сполучення плюс `commands.useAccessGroups`. Неавторизовані відправники бачать directives як звичайний текст. + - Директиви вилучаються з повідомлення до того, як його побачить модель. + - У звичайних повідомленнях чату (не лише з директивами) вони розглядаються як "вбудовані підказки" і **не** зберігають налаштування сесії. + - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та повертають підтвердження. + - Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, використовується тільки цей список дозволених; інакше авторизація надходить зі списків дозволених/спарювання каналу плюс `commands.useAccessGroups`. Для неавторизованих відправників директиви розглядаються як звичайний текст. - - Лише відправники зі списку дозволених/авторизовані: `/help`, `/commands`, `/status`, `/whoami` (`/id`). + + Лише для відправників зі списку дозволених/авторизованих: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - Вони виконуються негайно, вилучаються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайним потоком. + Вони виконуються негайно, вилучаються до того, як модель побачить повідомлення, а решта тексту продовжує проходити звичайний потік. @@ -69,104 +69,105 @@ x-i18n: ``` - Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення на `false`. + Вмикає розбір `/...` у повідомленнях чату. На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди працюють навіть якщо встановити це значення на `false`. - Реєструє нативні команди. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash commands); ігнорується для провайдерів без нативної підтримки. Установіть `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити для окремого провайдера (bool або `"auto"`). `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Командами Slack керують у застосунку Slack, і вони не видаляються автоматично. + Реєструє нативні команди. Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash-команди); ігнорується для провайдерів без нативної підтримки. Задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native`, щоб перевизначити для окремого провайдера (bool або `"auto"`). `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Командами Slack керують у застосунку Slack, і вони не видаляються автоматично. -У Discord специфікації нативних команд можуть містити `descriptionLocalizations`, які OpenClaw публікує як Discord `description_localizations` і включає до порівнянь узгодження. +У Discord специфікації нативних команд можуть містити `descriptionLocalizations`, які OpenClaw публікує як Discord `description_localizations` і включає в порівняння узгодження. - Реєструє команди **skill** нативно, коли це підтримується. Авто: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення slash command для кожного skill). Установіть `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити для окремого провайдера (bool або `"auto"`). + Реєструє команди **skill** нативно, коли це підтримується. Auto: увімкнено для Discord/Telegram; вимкнено для Slack (Slack вимагає створення slash-команди для кожного skill). Задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills`, щоб перевизначити для окремого провайдера (bool або `"auto"`). - Вмикає `! ` для запуску команд оболонки хоста (`/bash ` є псевдонімом; потрібні списки дозволених `tools.elevated`). + Вмикає `! ` для запуску команд оболонки хоста (`/bash ` є псевдонімом; потребує списків дозволених `tools.elevated`). - Керує тим, як довго bash очікує перед переходом у фоновий режим (`0` одразу переводить у фон). + Керує тим, як довго bash очікує перед перемиканням у фоновий режим (`0` одразу переводить у фон). Вмикає `/config` (читає/записує `openclaw.json`). - Вмикає `/mcp` (читає/записує MCP-конфігурацію, керовану OpenClaw, у `mcp.servers`). + Вмикає `/mcp` (читає/записує керовану OpenClaw конфігурацію MCP у `mcp.servers`). - Вмикає `/plugins` (виявлення/статус plugin, а також елементи керування встановленням і ввімкненням/вимкненням). + Вмикає `/plugins` (виявлення/статус Plugin плюс елементи керування встановленням і ввімкненням/вимкненням). - Вмикає `/debug` (лише runtime-перевизначення). + Вмикає `/debug` (перевизначення лише під час виконання). - Вмикає `/restart` плюс дії інструментів перезапуску Gateway. + Вмикає `/restart` плюс дії інструментів перезапуску gateway. - Задає явний список дозволених власника для командних/інструментальних поверхонь лише для власника. Це обліковий запис людини-оператора, який може схвалювати небезпечні дії та запускати команди, як-от `/diagnostics`, `/export-trajectory` і `/config`. Він відокремлений від `commands.allowFrom` і від доступу через DM-сполучення. + Задає явний список дозволених власників для командних/інструментальних поверхонь лише для власника. Це обліковий запис людини-оператора, який може схвалювати небезпечні дії та виконувати команди на кшталт `/diagnostics`, `/export-trajectory` і `/config`. Він окремий від `commands.allowFrom` і від доступу через спарювання DM. - Для окремого каналу: змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Коли `true`, відправник має або збігатися з визначеним кандидатом-власником (наприклад, записом у `commands.ownerAllowFrom` або нативними метаданими власника провайдера), або мати внутрішній scope `operator.admin` у внутрішньому каналі повідомлень. Запис із wildcard у канальному `allowFrom` або порожній/невизначений список кандидатів-власників **не** є достатнім — команди лише для власника в цьому каналі fail closed. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними списками дозволених команд. + Для кожного каналу: змушує команди лише для власника вимагати **ідентичність власника** для запуску на цій поверхні. Коли `true`, відправник має або збігатися з розв’язаним кандидатом-власником (наприклад, записом у `commands.ownerAllowFrom` або нативними метаданими власника провайдера), або мати внутрішній scope `operator.admin` у внутрішньому каналі повідомлень. Запис із wildcard у `allowFrom` каналу або порожній/нерозв’язаний список кандидатів-власників **не** є достатнім — команди лише для власника на цьому каналі закриті за замовчуванням. Залиште це вимкненим, якщо хочете, щоб команди лише для власника обмежувалися тільки `ownerAllowFrom` і стандартними списками дозволених команд. - Керує тим, як owner ids відображаються в системному prompt. + Керує тим, як owner ids з’являються в системному prompt. - За бажанням задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`. + Необов’язково задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`. - Список дозволених для кожного провайдера для авторизації команд. Коли він налаштований, це єдине джерело авторизації для команд і directives (списки дозволених каналу/сполучення та `commands.useAccessGroups` ігноруються). Використовуйте `"*"` як глобальне значення за замовчуванням; ключі конкретних провайдерів його перевизначають. + Список дозволених для авторизації команд за провайдерами. Коли налаштовано, це єдине джерело авторизації для команд і директив (списки дозволених/спарювання каналу та `commands.useAccessGroups` ігноруються). Використовуйте `"*"` як глобальне значення за замовчуванням; ключі конкретних провайдерів його перевизначають. - Забезпечує застосування списків дозволених/політик для команд, коли `commands.allowFrom` не встановлено. + Застосовує списки дозволених/політики для команд, коли `commands.allowFrom` не задано. ## Список команд Поточне джерело істини: -- вбудовані core-команди походять із `src/auto-reply/commands-registry.shared.ts` -- згенеровані команди dock походять із `src/auto-reply/commands-registry.data.ts` -- команди plugin походять із викликів plugin `registerCommand()` -- фактична доступність на вашому gateway усе ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugins +- вбудовані команди ядра надходять із `src/auto-reply/commands-registry.shared.ts` +- згенеровані команди dock надходять із `src/auto-reply/commands-registry.data.ts` +- команди Plugin надходять із викликів Plugin `registerCommand()` +- фактична доступність на вашому gateway все ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених Plugin -### Вбудовані core-команди +### Вбудовані команди ядра - + - `/new [model]` запускає нову сесію; `/reset` є псевдонімом скидання. - - `/reset soft [message]` зберігає поточну стенограму, відкидає повторно використані ідентифікатори сесій CLI backend і повторно запускає завантаження startup/system-prompt на місці. - - `/compact [instructions]` стискає контекст сесії. Див. [Compaction](/uk/concepts/compaction). + - Control UI перехоплює введений `/new`, щоб створити та перемкнутися на свіжу сесію dashboard; введений `/reset` усе ще запускає скидання Gateway на місці. + - `/reset soft [message]` зберігає поточний transcript, відкидає повторно використані ids сесій backend CLI та повторно виконує завантаження startup/system-prompt на місці. + - `/compact [instructions]` ущільнює контекст сесії. Див. [Compaction](/uk/concepts/compaction). - `/stop` перериває поточний запуск. - - `/session idle ` і `/session max-age ` керують закінченням терміну прив’язки гілки. + - `/session idle ` і `/session max-age ` керують завершенням прив’язки треду. - `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`. - - `/export-trajectory [path]` запитує схвалення exec, а потім експортує JSONL [пакет trajectory](/uk/tools/trajectory) для поточної сесії. Використовуйте це, коли потрібна хронологія prompt, tool і стенограми для однієї сесії OpenClaw. У групових чатах prompt схвалення та результат експорту надсилаються власнику приватно. Псевдонім: `/trajectory`. + - `/export-trajectory [path]` запитує схвалення exec, а потім експортує JSONL [пакет траєкторії](/uk/tools/trajectory) для поточної сесії. Використовуйте це, коли вам потрібна хронологія prompt, tool і transcript для однієї сесії OpenClaw. У групових чатах prompt схвалення та результат експорту надсилаються власнику приватно. Псевдонім: `/trajectory`. - - - `/think ` задає рівень мислення. Варіанти походять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а спеціальні рівні, як-от `xhigh`, `adaptive`, `max`, або бінарний `on`, доступні лише там, де підтримуються. Псевдоніми: `/thinking`, `/t`. + + - `/think ` задає рівень мислення. Варіанти надходять із профілю провайдера активної моделі; поширені рівні: `off`, `minimal`, `low`, `medium` і `high`, а власні рівні, як-от `xhigh`, `adaptive`, `max` або двійковий `on`, доступні лише там, де підтримуються. Псевдоніми: `/thinking`, `/t`. - `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`. - - `/trace on|off` перемикає вивід trace plugin для поточної сесії. - - `/fast [status|on|off]` показує або задає fast mode. + - `/trace on|off` перемикає вивід трасування Plugin для поточної сесії. + - `/fast [status|on|off]` показує або задає швидкий режим. - `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`. - `/elevated [on|off|ask|full]` перемикає elevated mode. Псевдонім: `/elev`. - - `/exec host= security= ask= node=` показує або задає exec defaults. + - `/exec host= security= ask= node=` показує або задає типові значення exec. - `/model [name|#|status]` показує або задає модель. - - `/models [provider] [page] [limit=|size=|all]` перелічує налаштованих/доступних через auth провайдерів або моделі для провайдера; додайте `all`, щоб переглянути повний каталог цього провайдера. - - `/queue ` керує поведінкою черги (`steer`, застаріле `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) плюс параметрами на кшталт `debounce:0.5s cap:25 drop:summarize`; `/queue default` або `/queue reset` очищає перевизначення сесії. Див. [Черга команд](/uk/concepts/queue) і [Steering queue](/uk/concepts/queue-steering). + - `/models [provider] [page] [limit=|size=|all]` перелічує налаштованих/доступних через автентифікацію провайдерів або моделі для провайдера; додайте `all`, щоб переглянути повний каталог цього провайдера. + - `/queue ` керує поведінкою черги (`steer`, legacy `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) плюс опції на кшталт `debounce:0.5s cap:25 drop:summarize`; `/queue default` або `/queue reset` очищає перевизначення сесії. Див. [Черга команд](/uk/concepts/queue) і [Черга спрямування](/uk/concepts/queue-steering). - - - `/help` показує коротке зведення допомоги. + + - `/help` показує коротке зведення довідки. - `/commands` показує згенерований каталог команд. - - `/tools [compact|verbose]` показує, що поточний agent може використовувати просто зараз. - - `/status` показує статус виконання/runtime, включно з мітками `Execution`/`Runtime` та використанням/квотою провайдера, коли доступно. - - `/diagnostics [note]` — це support-report flow лише для власника для багів Gateway і запусків Codex harness. Він щоразу запитує явне схвалення exec перед запуском `openclaw gateway diagnostics export --json`; не схвалюйте diagnostics правилом allow-all. Після схвалення він надсилає звіт, придатний для вставлення, з локальним шляхом до bundle, зведенням manifest, нотатками про приватність і релевантними ідентифікаторами сесій. У групових чатах prompt схвалення та звіт надсилаються власнику приватно. Коли активна сесія використовує OpenAI Codex harness, те саме схвалення також надсилає релевантний Codex feedback на сервери OpenAI, а завершена відповідь перелічує ідентифікатори сесій OpenClaw, ідентифікатори гілок Codex і команди `codex resume `. Див. [Експорт діагностики](/uk/gateway/diagnostics). - - `/crestodian ` запускає помічник налаштування та відновлення Crestodian з DM власника. - - `/tasks` перелічує активні/нещодавні фонові задачі для поточної сесії. - - `/context [list|detail|json]` пояснює, як складається контекст. + - `/tools [compact|verbose]` показує, що поточний агент може використовувати просто зараз. + - `/status` показує статус виконання/runtime, зокрема мітки `Execution`/`Runtime` і використання/квоту провайдера, коли доступно. + - `/diagnostics [note]` — це потік support-report лише для власника для помилок Gateway і запусків Codex harness. Він щоразу запитує явне схвалення exec перед запуском `openclaw gateway diagnostics export --json`; не схвалюйте діагностику правилом allow-all. Після схвалення він надсилає звіт, який можна вставити, з локальним шляхом пакета, зведенням manifest, нотатками про приватність і релевантними ids сесій. У групових чатах prompt схвалення та звіт надсилаються власнику приватно. Коли активна сесія використовує OpenAI Codex harness, те саме схвалення також надсилає релевантний feedback Codex на сервери OpenAI, а завершена відповідь перелічує ids сесій OpenClaw, ids тредів Codex і команди `codex resume `. Див. [Експорт діагностики](/uk/gateway/diagnostics). + - `/crestodian ` запускає помічник налаштування та виправлення Crestodian з owner DM. + - `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії. + - `/context [list|detail|json]` пояснює, як збирається контекст. - `/whoami` показує ваш sender id. Псевдонім: `/id`. - - `/usage off|tokens|full|cost` керує футером використання для кожної відповіді або друкує локальне зведення вартості. + - `/usage off|tokens|full|cost` керує footer використання для кожної відповіді або друкує локальне зведення вартості. - + - `/skill [input]` запускає skill за назвою. - `/allowlist [list|add|remove] ...` керує записами списку дозволених. Лише текст. - `/approve ` вирішує prompts схвалення exec. @@ -174,62 +175,63 @@ x-i18n: - - `/subagents list|kill|log|info|send|steer|spawn` керує запусками sub-agent для поточної сесії. - - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує ACP-сесіями та runtime-параметрами. - - `/focus ` прив’язує поточну гілку Discord або тему/розмову Telegram до цільової сесії. + - `/subagents list|kill|log|info|send|steer|spawn` керує запусками під-агентів для поточного сеансу. + - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сеансами ACP і параметрами середовища виконання. + - `/focus ` прив’язує поточну гілку Discord або тему/розмову Telegram до цілі сеансу. - `/unfocus` видаляє поточну прив’язку. - - `/agents` перелічує прив’язаних до гілки agents для поточної сесії. - - `/kill ` перериває одного або всіх запущених sub-agents. - - `/steer ` надсилає steering запущеному sub-agent. Псевдонім: `/tell`. + - `/agents` показує агентів, прив’язаних до гілки, для поточного сеансу. + - `/kill ` перериває один або всі запущені під-агенти. + - `/steer ` надсилає керування запущеному під-агенту. Псевдонім: `/tell`. - + - `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потребує `commands.config: true`. - `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, керовану OpenClaw, у `mcp.servers`. Лише для власника. Потребує `commands.mcp: true`. - - `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` є псевдонімом. Записи лише для власника. Потребує `commands.plugins: true`. - - `/debug show|set|unset|reset` керує лише runtime-перевизначеннями конфігурації. Лише для власника. Потребує `commands.debug: true`. + - `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` — це псевдонім. Записи лише для власника. Потребує `commands.plugins: true`. + - `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише для середовища виконання. Лише для власника. Потребує `commands.debug: true`. - `/restart` перезапускає OpenClaw, коли ввімкнено. Типово: ввімкнено; задайте `commands.restart: false`, щоб вимкнути. - `/send on|off|inherit` задає політику надсилання. Лише для власника. - + - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` керує TTS. Див. [TTS](/uk/tools/tts). - - `/activation mention|always` задає режим активації в групі. - - `/bash ` запускає команду оболонки хоста. Лише текст. Псевдонім: `! `. Потребує `commands.bash: true` плюс списки дозволів `tools.elevated`. - - `!poll [sessionId]` перевіряє фонове завдання bash. - - `!stop [sessionId]` зупиняє фонове завдання bash. + - `/activation mention|always` задає режим активації групи. + - `/bash ` запускає команду оболонки хоста. Лише текст. Псевдонім: `! `. Потребує `commands.bash: true` і списків дозволеного `tools.elevated`. + - `!poll [sessionId]` перевіряє фонове bash-завдання. + - `!stop [sessionId]` зупиняє фонове bash-завдання. -### Згенеровані команди dock +### Згенеровані dock-команди -Команди dock перемикають маршрут відповіді поточного сеансу на інший пов’язаний -канал. Налаштування, приклади й усунення несправностей див. у [стикуванні каналів](/uk/concepts/channel-docking). +Dock-команди перемикають маршрут відповіді поточного сеансу на інший пов’язаний +канал. Див. [стикування каналів](/uk/concepts/channel-docking) для налаштування, +прикладів і усунення несправностей. -Команди dock генеруються з channel plugins із підтримкою нативних команд. Поточний вбудований набір: +Dock-команди генеруються з channel plugins із підтримкою native-command. Поточний вбудований набір: - `/dock-discord` (псевдонім: `/dock_discord`) - `/dock-mattermost` (псевдонім: `/dock_mattermost`) - `/dock-slack` (псевдонім: `/dock_slack`) - `/dock-telegram` (псевдонім: `/dock_telegram`) -Використовуйте команди dock із прямого чату, щоб перемкнути маршрут відповіді поточного сеансу на інший пов’язаний канал. Агент зберігає той самий контекст сеансу, але майбутні відповіді для цього сеансу доставляються вибраному peer каналу. +Використовуйте dock-команди з прямого чату, щоб перемкнути маршрут відповіді поточного сеансу на інший пов’язаний канал. Агент зберігає той самий контекст сеансу, але майбутні відповіді для цього сеансу доставляються вибраному учаснику каналу. -Команди dock потребують `session.identityLinks`. Відправник-джерело й цільовий peer мають бути в одній групі ідентичностей, наприклад `["telegram:123", "discord:456"]`. Якщо користувач Telegram з id `123` надсилає `/dock_discord`, OpenClaw зберігає `lastChannel: "discord"` і `lastTo: "456"` в активному сеансі. Якщо відправник не пов’язаний із peer Discord, команда відповідає підказкою з налаштування замість переходу до звичайного чату. +Dock-команди потребують `session.identityLinks`. Відправник-джерело й цільовий учасник мають бути в одній групі ідентичностей, наприклад `["telegram:123", "discord:456"]`. Якщо користувач Telegram з id `123` надсилає `/dock_discord`, OpenClaw зберігає `lastChannel: "discord"` і `lastTo: "456"` в активному сеансі. Якщо відправник не пов’язаний з учасником Discord, команда відповідає підказкою з налаштування замість передавання у звичайний чат. -Docking змінює лише маршрут активного сеансу. Це не створює облікові записи каналів, не надає доступ, не обходить списки дозволів каналів і не переносить історію транскрипта до іншого сеансу. Використовуйте `/dock-telegram`, `/dock-slack`, `/dock-mattermost` або іншу згенеровану команду dock, щоб знову перемкнути маршрут. +Стикування змінює лише маршрут активного сеансу. Воно не створює облікові записи каналів, не надає доступ, не обходить списки дозволеного каналів і не переносить історію транскрипту в інший сеанс. Використовуйте `/dock-telegram`, `/dock-slack`, `/dock-mattermost` або іншу згенеровану dock-команду, щоб знову перемкнути маршрут. -### Команди вбудованих plugins +### Команди вбудованих plugin Вбудовані plugins можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії: -- `/dreaming [on|off|status|help]` перемикає Dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming). -- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком сполучення/налаштування пристрою. Див. [Pairing](/uk/channels/pairing). -- `/phone status|arm [duration]|disarm` тимчасово озброює високоризикові команди телефонного вузла. -- `/voice status|list [limit]|set ` керує конфігурацією голосу Talk. У Discord нативна назва команди — `/talkvoice`. -- `/card ...` надсилає пресети насичених карток LINE. Див. [LINE](/uk/channels/line). -- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` перевіряє й керує вбудованим app-server harness Codex. Див. [Codex harness](/uk/plugins/codex-harness). +- `/dreaming [on|off|status|help]` вмикає або вимикає memory dreaming. Див. [Dreaming](/uk/concepts/dreaming). +- `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком сполучення/налаштування пристрою. Див. [сполучення](/uk/channels/pairing). +- `/phone status|arm [duration]|disarm` тимчасово вмикає високоризикові команди телефонного вузла. +- `/voice status|list [limit]|set ` керує конфігурацією голосу Talk. У Discord назва нативної команди — `/talkvoice`. +- `/card ...` надсилає пресети LINE rich card. Див. [LINE](/uk/channels/line). +- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` перевіряє та керує вбудованою обв’язкою сервера застосунку Codex. Див. [обв’язку Codex](/uk/plugins/codex-harness). - Команди лише для QQBot: - `/bot-ping` - `/bot-version` @@ -237,90 +239,90 @@ Docking змінює лише маршрут активного сеансу. Ц - `/bot-upgrade` - `/bot-logs` -### Динамічні команди skills +### Динамічні команди Skills Skills, які може викликати користувач, також доступні як slash-команди: -- `/skill [input]` завжди працює як загальна точка входу. +- `/skill [input]` завжди працює як універсальна точка входу. - skills також можуть з’являтися як прямі команди на кшталт `/prose`, коли skill/plugin їх реєструє. -- реєстрацією нативних команд skill керують `commands.nativeSkills` і `channels..commands.nativeSkills`. +- реєстрація нативних skill-команд керується `commands.nativeSkills` і `channels..commands.nativeSkills`. - специфікації команд можуть надавати `descriptionLocalizations` для нативних поверхонь, які підтримують локалізовані описи, зокрема Discord. - - - Команди приймають необов’язковий `:` між командою й аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). - - `/new ` приймає псевдонім моделі, `provider/model` або назву provider (нечіткий збіг); якщо збігу немає, текст обробляється як тіло повідомлення. - - Для повної розбивки використання provider скористайтеся `openclaw status --usage`. + + - Команди приймають необов’язковий `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). + - `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст обробляється як тіло повідомлення. + - Для повної розбивки використання провайдера використовуйте `openclaw status --usage`. - `/allowlist add|remove` потребує `commands.config=true` і враховує `configWrites` каналу. - - У каналах із кількома обліковими записами орієнтовані на конфігурацію `/allowlist --account ` і `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. - - `/usage` керує футером використання для кожної відповіді; `/usage cost` друкує локальний підсумок вартості з журналів сеансу OpenClaw. - - `/restart` типово ввімкнено; задайте `commands.restart: false`, щоб вимкнути. + - У каналах із кількома обліковими записами `/allowlist --account `, націлена на конфігурацію, і `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. + - `/usage` керує футером використання для кожної відповіді; `/usage cost` друкує локальний підсумок вартості з журналів сеансів OpenClaw. + - `/restart` увімкнено типово; задайте `commands.restart: false`, щоб вимкнути. - `/plugins install ` приймає ті самі специфікації plugin, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет, `git:` або `clawhub:`. - - `/plugins enable|disable` оновлює конфігурацію plugin і може запропонувати перезапуск. + - `/plugins enable|disable` оновлює конфігурацію plugin і може попросити перезапуск. - - - Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступно як текст). `join` потребує guild і вибраного голосового/stage-каналу. Потребує `channels.discord.voice` і нативних команд. - - Команди прив’язки thread у Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив’язок thread (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). - - Довідник команд ACP і поведінка runtime: [агенти ACP](/uk/tools/acp-agents). + + - Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (недоступна як текст). `join` потребує guild і вибраного голосового/stage-каналу. Потребує `channels.discord.voice` і нативних команд. + - Команди прив’язки гілок Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) потребують увімкнених ефективних прив’язок гілок (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). + - Довідник команд ACP і поведінка середовища виконання: [агенти ACP](/uk/tools/acp-agents). - - - `/verbose` призначено для налагодження й додаткової видимості; тримайте його **вимкненим** під час звичайного використання. - - `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать plugin, і залишає звичайний докладний шум інструментів вимкненим. - - `/fast on|off` зберігає перевизначення сеансу. Використовуйте опцію `inherit` в інтерфейсі Sessions, щоб очистити його й повернутися до типових значень конфігурації. - - `/fast` залежить від provider: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних endpoints Responses, тоді як прямі публічні запити Anthropic, зокрема OAuth-автентифікований трафік, надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). + + - `/verbose` призначено для налагодження та додаткової видимості; тримайте його **вимкненим** під час звичайного використання. + - `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать plugin, і не вмикає звичайний докладний шум інструментів. + - `/fast on|off` зберігає перевизначення сеансу. Використовуйте опцію `inherit` в інтерфейсі Sessions UI, щоб очистити його й повернутися до типових значень конфігурації. + - `/fast` залежить від провайдера: OpenAI/OpenAI Codex відображають його на `service_tier=priority` у нативних Responses endpoint, тоді як прямі публічні запити Anthropic, зокрема трафік з автентифікацією OAuth, надісланий до `api.anthropic.com`, відображають його на `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). - Підсумки збоїв інструментів усе ще показуються, коли доречно, але докладний текст збою включається лише коли `/verbose` має значення `on` або `full`. - - `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішнє reasoning, вивід інструментів або діагностику plugin, які ви не мали наміру показувати. Бажано залишати їх вимкненими, особливо в групових чатах. + - `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішні міркування, вихід інструментів або діагностику plugin, яку ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах. - + - `/model` негайно зберігає нову модель сеансу. - - Якщо агент неактивний, наступний запуск одразу використовує її. - - Якщо запуск уже активний, OpenClaw позначає live-перемикання як очікуване й перезапускається в нову модель лише в чистій точці повторної спроби. - - Якщо активність інструментів або вивід відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача. - - У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від режиму rescue для каналів повідомлень і не надає віддалених повноважень конфігурації. + - Якщо агент неактивний, наступний запуск одразу її використовує. + - Якщо запуск уже активний, OpenClaw позначає live-перемикання як відкладене й перезапускається з новою моделлю лише в чистій точці повторної спроби. + - Якщо активність інструментів або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача. + - У локальному TUI `/crestodian [request]` повертає зі звичайного TUI агента до Crestodian. Це окремо від режиму порятунку каналу повідомлень і не надає віддалених повноважень конфігурації. - - - **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволів обробляються негайно (обхід черги + моделі). - - **Обмеження згадками в групі:** повідомлення лише з командами від відправників зі списку дозволів обходять вимоги до згадок. - - **Inline-скорочення (лише відправники зі списку дозволів):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту. - - Приклад: `hey /status` викликає відповідь зі статусом, а решта тексту продовжує проходити звичайним потоком. + + - **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволеного обробляються негайно (в обхід черги + моделі). + - **Фільтр згадок у групі:** повідомлення лише з командами від відправників зі списку дозволеного обходять вимоги до згадок. + - **Вбудовані скорочення (лише відправники зі списку дозволеного):** певні команди також працюють, коли вбудовані у звичайне повідомлення, і вилучаються до того, як модель побачить решту тексту. + - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує звичайний потік. - Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - - Неавторизовані повідомлення лише з командами мовчки ігноруються, а inline-токени `/...` обробляються як звичайний текст. + - Неавторизовані повідомлення лише з командами мовчки ігноруються, а вбудовані токени `/...` обробляються як звичайний текст. - - - **Команди Skills:** skills `user-invocable` доступні як slash-команди. Імена нормалізуються до `a-z0-9_` (макс. 32 символи); колізії отримують числові суфікси (наприклад, `_2`). - - `/skill [input]` запускає skill за назвою (корисно, коли обмеження нативних команд не дають створити окремі команди для кожного skill). - - Типово команди skill пересилаються моделі як звичайний запит. - - Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб спрямувати команду безпосередньо до інструмента (детерміновано, без моделі). + + - **Команди Skills:** Skills типу `user-invocable` доступні як slash-команди. Назви очищуються до `a-z0-9_` (макс. 32 символи); колізії отримують числові суфікси (наприклад, `_2`). + - `/skill [input]` запускає skill за назвою (корисно, коли обмеження нативних команд заважають створити окремі команди для кожного skill). + - Типово команди Skills передаються моделі як звичайний запит. + - Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі). - Приклад: `/prose` (OpenProse plugin) — див. [OpenProse](/uk/prose). - - **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних опцій (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти розв’язуються відносно цільової моделі сеансу, тому специфічні для моделі опції, як-от рівні `/think`, наслідують перевизначення `/model` цього сеансу. + - **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. Динамічні варіанти визначаються відносно цільової моделі сеансу, тому специфічні для моделі параметри, як-от рівні `/think`, відповідають перевизначенню `/model` цього сеансу. ## `/tools` -`/tools` відповідає на runtime-запитання, а не на запитання конфігурації: **що цей агент може використовувати прямо зараз у цій розмові**. +`/tools` відповідає на питання середовища виконання, а не конфігурації: **що цей агент може використовувати просто зараз у цій розмові**. - Типовий `/tools` компактний і оптимізований для швидкого перегляду. - `/tools verbose` додає короткі описи. - Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму `compact|verbose`. -- Результати прив’язані до сеансу, тому зміна агента, каналу, thread, авторизації відправника або моделі може змінити вивід. -- `/tools` включає інструменти, які фактично доступні під час runtime, зокрема core-інструменти, підключені інструменти plugin та інструменти, що належать каналу. +- Результати обмежені сеансом, тому зміна агента, каналу, гілки, авторизації відправника або моделі може змінити вивід. +- `/tools` включає інструменти, які фактично доступні під час виконання, зокрема основні інструменти, підключені інструменти plugin та інструменти, що належать каналу. -Для редагування профілю й перевизначень використовуйте панель Tools в Control UI або поверхні конфігурації/каталогу, замість того щоб трактувати `/tools` як статичний каталог. +Для редагування профілю й перевизначень використовуйте панель Control UI Tools або поверхні конфігурації/каталогу замість того, щоб розглядати `/tools` як статичний каталог. ## Поверхні використання (що де показується) -- **Використання/квота provider** (приклад: "Claude 80% left") показується в `/status` для provider поточної моделі, коли відстеження використання ввімкнено. OpenClaw нормалізує вікна provider до `% left`; для MiniMax поля відсотків лише залишку інвертуються перед показом, а відповіді `model_remains` надають перевагу запису chat-моделі плюс позначці plan із тегом моделі. -- **Рядки token/cache** у `/status` можуть повертатися до останнього запису використання транскрипта, коли live-знімок сеансу розріджений. Наявні ненульові live-значення все ще мають пріоритет, а fallback транскрипта також може відновити активну мітку runtime-моделі плюс більший prompt-орієнтований підсумок, коли збережені підсумки відсутні або менші. -- **Execution проти runtime:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично запускає сеанс: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend. -- **Token/cost для кожної відповіді** керується `/usage off|tokens|full` (додається до звичайних відповідей). -- `/model status` стосується **models/auth/endpoints**, а не використання. +- **Використання/квота провайдера** (приклад: "Claude 80% left") показується в `/status` для поточного провайдера моделі, коли ввімкнено відстеження використання. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля відсотків лише із залишком інвертуються перед відображенням, а відповіді `model_remains` віддають перевагу запису chat-моделі плюс позначці плану з тегом моделі. +- **Рядки токенів/кешу** в `/status` можуть відступати до останнього запису використання з транскрипту, коли live-знімок сеансу розріджений. Наявні ненульові live-значення все одно мають пріоритет, а fallback на транскрипт також може відновити активну мітку моделі середовища виконання плюс більшу загальну суму, орієнтовану на prompt, коли збережені підсумки відсутні або менші. +- **Виконання проти середовища виконання:** `/status` повідомляє `Execution` для ефективного шляху sandbox і `Runtime` для того, хто фактично запускає сеанс: `OpenClaw Pi Default`, `OpenAI Codex`, CLI backend або ACP backend. +- **Токени/вартість на відповідь** керуються через `/usage off|tokens|full` (додається до звичайних відповідей). +- `/model status` стосується **моделей/автентифікації/endpoint-ів**, а не використання. ## Вибір моделі (`/model`) @@ -337,16 +339,16 @@ Skills, які може викликати користувач, також до /model status ``` -Нотатки: +Примітки: -- `/model` і `/model list` показують компактний нумерований вибір (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадними списками провайдера й моделі, а також кроком Submit. -- `/model <#>` вибирає з цього списку (і за можливості надає перевагу поточному провайдеру). -- `/model status` показує детальний вигляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. +- `/model` і `/model list` показують компактний нумерований вибір (родина моделі + доступні провайдери). +- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадаючими списками провайдера й моделі та кроком надсилання. +- `/model <#>` вибирає з цього списку (і віддає перевагу поточному провайдеру, коли це можливо). +- `/model status` показує детальний перегляд, включно з налаштованим endpoint-ом провайдера (`baseUrl`) і режимом API (`api`), коли вони доступні. -## Перевизначення для налагодження +## Debug-перевизначення -`/debug` дає змогу встановити **лише runtime** перевизначення конфігурації (у пам’яті, не на диску). Лише для власника. Вимкнено за замовчуванням; увімкніть за допомогою `commands.debug: true`. +`/debug` дає змогу задавати **лише runtime** перевизначення конфігурації (у пам'яті, не на диску). Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.debug: true`. Приклади: @@ -359,12 +361,12 @@ Skills, які може викликати користувач, також до ``` -Перевизначення негайно застосовуються до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. +Перевизначення одразу застосовуються до нових читань конфігурації, але **не** записуються в `openclaw.json`. Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. -## Вивід трасування Plugin +## Виведення трасування Plugin -`/trace` дає змогу перемикати **прив’язані до сесії рядки трасування/налагодження Plugin** без увімкнення повного докладного режиму. +`/trace` дає змогу перемикати **обмежені сеансом рядки трасування/debug Plugin** без увімкнення повного verbose-режиму. Приклади: @@ -376,16 +378,16 @@ Skills, які може викликати користувач, також до Примітки: -- `/trace` без аргументу показує поточний стан трасування сесії. -- `/trace on` вмикає рядки трасування Plugin для поточної сесії. +- `/trace` без аргументу показує поточний стан трасування сеансу. +- `/trace on` вмикає рядки трасування Plugin для поточного сеансу. - `/trace off` знову вимикає їх. -- Рядки трасування Plugin можуть з’являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента. +- Рядки трасування Plugin можуть з'являтися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента. - `/trace` не замінює `/debug`; `/debug` і далі керує лише runtime перевизначеннями конфігурації. -- `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/статусу й далі належить до `/verbose`. +- `/trace` не замінює `/verbose`; звичайне verbose-виведення інструментів/статусу й далі належить до `/verbose`. ## Оновлення конфігурації -`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Вимкнено за замовчуванням; увімкніть за допомогою `commands.config: true`. +`/config` записує у вашу конфігурацію на диску (`openclaw.json`). Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.config: true`. Приклади: @@ -398,12 +400,12 @@ Skills, які може викликати користувач, також до ``` -Конфігурацію перевіряють перед записом; недійсні зміни відхиляються. Оновлення `/config` зберігаються після перезапусків. +Конфігурація перевіряється перед записом; недійсні зміни відхиляються. Оновлення `/config` зберігаються між перезапусками. ## Оновлення MCP -`/mcp` записує визначення MCP-серверів, керовані OpenClaw, у `mcp.servers`. Лише для власника. Вимкнено за замовчуванням; увімкніть за допомогою `commands.mcp: true`. +`/mcp` записує керовані OpenClaw визначення MCP-серверів у `mcp.servers`. Лише для власника. Вимкнено за замовчуванням; увімкніть через `commands.mcp: true`. Приклади: @@ -415,12 +417,12 @@ Skills, які може викликати користувач, також до ``` -`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, якими володіє Pi. Runtime-адаптери вирішують, які транспорти фактично можна виконати. +`/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. Runtime-адаптери вирішують, які транспорти фактично виконувані. ## Оновлення Plugin -`/plugins` дає операторам змогу переглядати виявлені Plugin і перемикати ввімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено за замовчуванням; увімкніть за допомогою `commands.plugins: true`. +`/plugins` дає операторам змогу переглядати виявлені plugins і перемикати ввімкнення в конфігурації. Потоки лише для читання можуть використовувати `/plugin` як псевдонім. Вимкнено за замовчуванням; увімкніть через `commands.plugins: true`. Приклади: @@ -433,43 +435,43 @@ Skills, які може викликати користувач, також до ``` -- `/plugins list` і `/plugins show` використовують реальне виявлення Plugin у поточній робочій області разом із конфігурацією на диску. -- `/plugins enable|disable` оновлює лише конфігурацію Plugin; це не встановлює й не видаляє Plugin. -- Після змін увімкнення/вимкнення перезапустіть Gateway, щоб застосувати їх. +- `/plugins list` і `/plugins show` використовують справжнє виявлення Plugin у поточному workspace плюс конфігурацію на диску. +- `/plugins enable|disable` оновлює лише конфігурацію Plugin; це не встановлює й не видаляє plugins. +- Після змін enable/disable перезапустіть gateway, щоб застосувати їх. ## Примітки щодо поверхонь - - - **Текстові команди** виконуються у звичайній чат-сесії (DM використовують спільну `main`, групи мають власну сесію). - - **Нативні команди** використовують ізольовані сесії: + + - **Текстові команди** виконуються у звичайному чат-сеансі (DM спільно використовують `main`, групи мають власний сеанс). + - **Нативні команди** використовують ізольовані сеанси: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (спрямовує на чат-сесію через `CommandTargetSessionKey`) - - **`/stop`** спрямовується на активну чат-сесію, щоб вона могла перервати поточний запуск. + - Telegram: `telegram:slash:` (спрямовується на чат-сеанс через `CommandTargetSessionKey`) + - **`/stop`** спрямовується на активний чат-сеанс, щоб він міг перервати поточний запуск. - `channels.slack.slashCommand` усе ще підтримується для однієї команди в стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash-команду Slack для кожної вбудованої команди (ті самі назви, що й у `/help`). Меню аргументів команд для Slack доставляються як ephemeral кнопки Block Kit. + `channels.slack.slashCommand` і далі підтримується для однієї команди в стилі `/openclaw`. Якщо ввімкнути `commands.native`, потрібно створити по одній slash-команді Slack для кожної вбудованої команди (ті самі назви, що й у `/help`). Меню аргументів команд для Slack доставляються як ephemeral-кнопки Block Kit. - Виняток для нативних команд Slack: зареєструйте `/agentstatus` (не `/status`), бо Slack резервує `/status`. Текстова `/status` і далі працює в повідомленнях Slack. + Виняток для нативних команд Slack: зареєструйте `/agentstatus` (а не `/status`), бо Slack резервує `/status`. Текстовий `/status` і далі працює в повідомленнях Slack. ## Побічні запитання BTW -`/btw` — це швидке **побічне запитання** щодо поточної сесії. +`/btw` — це швидке **побічне запитання** про поточний сеанс. На відміну від звичайного чату: -- воно використовує поточну сесію як фоновий контекст, -- воно виконується як окремий одноразовий виклик **без інструментів**, -- воно не змінює майбутній контекст сесії, -- воно не записується в історію транскрипта, -- воно доставляється як живий побічний результат, а не як звичайне повідомлення асистента. +- він використовує поточний сеанс як фоновий контекст, +- він виконується як окремий одноразовий виклик **без інструментів**, +- він не змінює майбутній контекст сеансу, +- він не записується в історію транскрипту, +- він доставляється як live побічний результат замість звичайного повідомлення асистента. Це робить `/btw` корисним, коли потрібне тимчасове уточнення, поки основне завдання триває. @@ -479,10 +481,10 @@ Skills, які може викликати користувач, також до /btw what are we doing right now? ``` -Див. [Побічні запитання BTW](/uk/tools/btw), щоб ознайомитися з повною поведінкою та деталями UX клієнта. +Див. [Побічні запитання BTW](/uk/tools/btw), щоб отримати повний опис поведінки та деталей UX клієнта. -## Пов’язане +## Пов'язане -- [Створення skills](/uk/tools/creating-skills) +- [Створення Skills](/uk/tools/creating-skills) - [Skills](/uk/tools/skills) - [Конфігурація Skills](/uk/tools/skills-config) diff --git a/docs/uk/web/control-ui.md b/docs/uk/web/control-ui.md index 3f7f9cd0a..7e6514f5d 100644 --- a/docs/uk/web/control-ui.md +++ b/docs/uk/web/control-ui.md @@ -1,22 +1,22 @@ --- read_when: - - Ви хочете керувати Gateway з браузера + - Ви хочете керувати Gateway через браузер - Вам потрібен доступ до Tailnet без SSH-тунелів sidebarTitle: Control UI summary: Браузерний інтерфейс керування для Gateway (чат, вузли, конфігурація) title: Інтерфейс керування x-i18n: - generated_at: "2026-04-30T00:05:08Z" + generated_at: "2026-05-02T09:30:24Z" model: gpt-5.5 provider: openai - source_hash: 982d25d48770b753faa4e57d9a284e9bff10c15cda21dd9c00848d2a6b912d41 + source_hash: b49118ee964f9efb68479494d2bc1ba4029f0ec5c12fc69bd3975c3ea5082e14 source_path: web/control-ui.md workflow: 16 --- -Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговує Gateway: +Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway: -- типово: `http://:18789/` +- стандартно: `http://:18789/` - необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`) Він працює **напряму з Gateway WebSocket** на тому самому порту. @@ -29,124 +29,124 @@ Control UI — це невеликий односторінковий засто Якщо сторінка не завантажується, спочатку запустіть Gateway: `openclaw gateway`. -Автентифікація передається під час WebSocket handshake через: +Автентифікація передається під час WebSocket-рукостискання через: - `connect.params.auth.token` - `connect.params.auth.password` - заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true` -- заголовки ідентичності trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"` +- заголовки ідентичності довіреного проксі, коли `gateway.auth.mode: "trusted-proxy"` -Панель налаштувань dashboard зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси gateway; паролі не зберігаються. Onboarding зазвичай генерує gateway token для автентифікації зі спільним секретом під час першого підключення, але password auth також працює, коли `gateway.auth.mode` має значення `"password"`. +Панель налаштувань дашборда зберігає токен для поточної сесії вкладки браузера та вибраної URL-адреси Gateway; паролі не зберігаються. Onboarding зазвичай генерує токен Gateway для автентифікації зі спільним секретом під час першого підключення, але автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`. -## Спарювання пристрою (перше підключення) +## Сполучення пристрою (перше підключення) -Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення спарювання**. Це захід безпеки для запобігання несанкціонованому доступу. +Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway зазвичай вимагає **одноразового схвалення сполучення**. Це захід безпеки, що запобігає несанкціонованому доступу. **Що ви побачите:** "disconnected (1008): pairing required" - + ```bash openclaw devices list ``` - + ```bash openclaw devices approve ``` -Якщо браузер повторює спарювання зі зміненими даними автентифікації (role/scopes/public key), попередній запит в очікуванні замінюється, і створюється новий `requestId`. Перед схваленням повторно запустіть `openclaw devices list`. +Якщо браузер повторює спробу сполучення зі зміненими даними автентифікації (роль/області дії/публічний ключ), попередній запит, що очікував, замінюється, і створюється новий `requestId`. Перед схваленням повторно запустіть `openclaw devices list`. -Якщо браузер уже спарено, і ви змінюєте його з доступу для читання на доступ для запису/admin, це обробляється як підвищення схвалення, а не як тихе повторне підключення. OpenClaw залишає старе схвалення активним, блокує ширше повторне підключення та просить вас явно схвалити новий набір scope. +Якщо браузер уже сполучено, і ви змінюєте його доступ із читання на запис/адміністрування, це розглядається як підвищення схвалення, а не як непомітне повторне підключення. OpenClaw зберігає старе схвалення активним, блокує повторне підключення з ширшими правами й просить явно схвалити новий набір областей дії. -Після схвалення пристрій запам’ятовується і не потребуватиме повторного схвалення, якщо ви не відкличете його за допомогою `openclaw devices revoke --device --role `. Див. [CLI пристроїв](/uk/cli/devices) щодо ротації та відкликання токенів. +Після схвалення пристрій запам’ятовується й не потребуватиме повторного схвалення, якщо ви не відкличете його за допомогою `openclaw devices revoke --device --role `. Див. [CLI пристроїв](/uk/cli/devices) щодо ротації та відкликання токенів. - Прямі браузерні підключення через local loopback (`127.0.0.1` / `localhost`) схвалюються автоматично. -- Tailscale Serve може пропустити цикл спарювання для operator sessions у Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale підтверджується, а браузер надає свою ідентичність пристрою. -- Прямі прив’язки Tailnet, браузерні підключення з LAN і профілі браузера без ідентичності пристрою все ще потребують явного схвалення. -- Кожен профіль браузера генерує унікальний ID пристрою, тому перехід між браузерами або очищення даних браузера потребуватиме повторного спарювання. +- Tailscale Serve може пропустити цикл сполучення для операторських сесій Control UI, коли `gateway.auth.allowTailscale: true`, ідентичність Tailscale підтверджена, а браузер надає ідентичність свого пристрою. +- Прямі прив’язки Tailnet, браузерні підключення LAN і профілі браузера без ідентичності пристрою все ще потребують явного схвалення. +- Кожен профіль браузера генерує унікальний ID пристрою, тому перемикання браузерів або очищення даних браузера вимагатиме повторного сполучення. ## Особиста ідентичність (локальна для браузера) -Control UI підтримує персональну ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона зберігається у сховищі браузера, обмежена поточним профілем браузера і не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства transcript для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або зміна браузера скидає її до порожнього стану. +Control UI підтримує особисту ідентичність для кожного браузера (відображуване ім’я та аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона зберігається у сховищі браузера, обмежена поточним профілем браузера й не синхронізується з іншими пристроями та не зберігається на сервері, окрім звичайних метаданих авторства стенограми для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або перемикання браузерів скидає її до порожнього стану. -Та сама локальна для браузера модель застосовується до перевизначення аватара assistant. Завантажені аватари assistant накладаються на ідентичність, визначену gateway, лише в локальному браузері та ніколи не проходять зворотний обмін через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів не з UI, які записують поле напряму (наприклад, scripted gateways або custom dashboards). +Та сама локальна для браузера схема застосовується до перевизначення аватара асистента. Завантажені аватари асистента накладаються на визначену Gateway ідентичність лише в локальному браузері й ніколи не передаються через `config.patch`. Спільне поле конфігурації `ui.assistant.avatar` усе ще доступне для клієнтів не з UI, які записують поле напряму (наприклад, скриптові шлюзи або власні дашборди). -## Endpoint runtime-конфігурації +## Кінцева точка runtime-конфігурації -Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Цей endpoint захищений тією самою gateway auth, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть його отримати, а успішне отримання потребує вже дійсного gateway token/password, ідентичності Tailscale Serve або ідентичності trusted-proxy. +Control UI отримує свої runtime-налаштування з `/__openclaw/control-ui-config.json`. Ця кінцева точка захищена тією самою автентифікацією Gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть її отримати, а успішне отримання потребує або вже чинного токена/пароля Gateway, ідентичності Tailscale Serve, або ідентичності довіреного проксі. ## Підтримка мов -Control UI може локалізуватися під час першого завантаження на основі locale вашого браузера. Щоб змінити це пізніше, відкрийте **Overview -> Gateway Access -> Language**. Вибір locale міститься в картці Gateway Access, а не в Appearance. +Control UI може локалізуватися під час першого завантаження на основі локалі вашого браузера. Щоб змінити це пізніше, відкрийте **Огляд -> Доступ до Gateway -> Мова**. Вибір локалі розташований у картці Доступ до Gateway, а не в розділі Вигляд. -- Підтримувані locale: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` -- Неанглійські переклади lazy-loaded у браузері. -- Вибраний locale зберігається у сховищі браузера та повторно використовується під час майбутніх відвідувань. +- Підтримувані локалі: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa` +- Переклади неанглійськими мовами ліниво завантажуються в браузері. +- Вибрану локаль збережено в сховищі браузера й повторно використано під час майбутніх відвідувань. - Відсутні ключі перекладу повертаються до англійської. -Переклади документації генеруються для того самого набору неанглійських locale, але вбудований у сайт документації перемикач мов Mintlify обмежений кодами locale, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) все ще генерується в publish repo; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди. +Переклади документації генеруються для того самого набору неанглійських локалей, але вбудований у сайт документації перемикач мов Mintlify обмежений кодами локалей, які приймає Mintlify. Документація тайською (`th`) і перською (`fa`) усе ще генерується в репозиторії публікації; вона може не з’являтися в цьому перемикачі, доки Mintlify не підтримуватиме ці коди. ## Теми вигляду -Панель Appearance зберігає вбудовані теми Claw, Knot і Dash, а також один локальний для браузера слот імпорту tweakcn. Щоб імпортувати тему, відкрийте [tweakcn themes](https://tweakcn.com/themes), виберіть або створіть тему, натисніть **Share** і вставте скопійоване посилання на тему в Appearance. Імпортер також приймає registry URL `https://tweakcn.com/r/themes/`, URL редактора на кшталт `https://tweakcn.com/editor/theme?theme=amethyst-haze`, відносні шляхи `/themes/`, сирі ID тем і назви типових тем, як-от `amethyst-haze`. +Панель Вигляд зберігає вбудовані теми Claw, Knot і Dash, а також один локальний для браузера слот імпорту tweakcn. Щоб імпортувати тему, відкрийте [теми tweakcn](https://tweakcn.com/themes), виберіть або створіть тему, натисніть **Поділитися** та вставте скопійоване посилання на тему у Вигляд. Імпортер також приймає URL-адреси реєстру `https://tweakcn.com/r/themes/`, URL-адреси редактора на кшталт `https://tweakcn.com/editor/theme?theme=amethyst-haze`, відносні шляхи `/themes/`, сирі ID тем і стандартні назви тем, як-от `amethyst-haze`. -Імпортовані теми зберігаються лише в поточному профілі браузера. Вони не записуються в gateway config і не синхронізуються між пристроями. Заміна імпортованої теми оновлює один локальний слот; очищення перемикає активну тему назад на Claw, якщо імпортовану тему було вибрано. +Імпортовані теми зберігаються лише в поточному профілі браузера. Вони не записуються в конфігурацію Gateway і не синхронізуються між пристроями. Заміна імпортованої теми оновлює один локальний слот; очищення перемикає активну тему назад на Claw, якщо імпортовану тему було вибрано. ## Що він може робити (сьогодні) - Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`). - - Розмовляти через browser realtime sessions. OpenAI використовує direct WebRTC, Google Live використовує constrained одноразовий browser token через WebSocket, а backend-only realtime voice plugins використовують relay transport Gateway. Relay зберігає provider credentials на Gateway, тоді як браузер stream-ить microphone PCM через RPC `talk.realtime.relay*` і надсилає tool calls `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw. - - Stream tool calls + картки live tool output у Chat (agent events). + - Розмовляти через realtime-сесії браузера. OpenAI використовує прямий WebRTC, Google Live використовує обмежений одноразовий браузерний токен через WebSocket, а realtime voice plugins, що працюють лише на бекенді, використовують ретрансляційний транспорт Gateway. Ретранслятор зберігає облікові дані провайдера на Gateway, поки браузер передає PCM з мікрофона через RPC `talk.realtime.relay*` і надсилає виклики інструмента `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої моделі OpenClaw. + - Стримити виклики інструментів + живі картки виводу інструментів у Chat (події агента). - - - Канали: вбудовані плюс стан bundled/external plugin channels, QR login і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`). - - Інстанси: список присутності + оновлення (`system-presence`). - - Сесії: список + перевизначення model/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`). - - Сни: стан dreaming, перемикач увімкнення/вимкнення та reader Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). + + - Канали: статус вбудованих і bundled/external plugin каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`). + - Екземпляри: список присутності + оновлення (`system-presence`). + - Сесії: список + перевизначення моделі/мислення/швидкого режиму/детальності/трасування/reasoning для кожної сесії (`sessions.list`, `sessions.patch`). + - Сни: статус dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`). - - - Cron jobs: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`). - - Skills: стан, увімкнення/вимкнення, встановлення, оновлення API key (`skills.*`). - - Nodes: список + caps (`node.list`). - - Exec approvals: редагування gateway або node allowlists + ask policy для `exec host=gateway/node` (`exec.approvals.*`). + + - Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`). + - Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`). + - Nodes: список + можливості (`node.list`). + - Схвалення exec: редагування allowlist Gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`). - Перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`). - Застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії. - - Записи містять base-hash guard, щоб запобігти перезапису паралельних редагувань. - - Записи (`config.set`/`config.apply`/`config.patch`) виконують preflight resolution активних SecretRef для refs у надісланому config payload; unresolved active submitted refs відхиляються до запису. - - Schema + rendering форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, matched UI hints, immediate child summaries, docs metadata на вкладених object/wildcard/array/composition nodes, а також plugin + channel schemas, коли доступні); Raw JSON editor доступний лише тоді, коли snapshot має безпечний raw round-trip. - - Якщо snapshot не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає Form mode і вимикає Raw mode для цього snapshot. - - У Raw JSON editor "Reset to saved" зберігає raw-authored shape (форматування, коментарі, layout `$include`) замість повторного rendering плаского snapshot, тому зовнішні редагування переживають reset, коли snapshot може безпечно виконати round-trip. - - Структуровані значення об’єктів SecretRef відображаються read-only у текстових input форми, щоб запобігти випадковому пошкодженню object-to-string. + - Записи містять захист base-hash, щоб запобігти перезапису паралельних змін. + - Записи (`config.set`/`config.apply`/`config.patch`) попередньо перевіряють розв’язання активних SecretRef для refs у надісланому payload конфігурації; нерозв’язані активні надіслані refs відхиляються перед записом. + - Рендеринг схеми + форми (`config.schema` / `config.schema.lookup`, включно з полями `title` / `description`, відповідними UI-підказками, підсумками безпосередніх дочірніх елементів, метаданими документації на вкладених вузлах об’єктів/wildcard/масивів/композицій, а також схемами plugin + channel, коли доступно); редактор Raw JSON доступний лише тоді, коли знімок має безпечний raw round-trip. + - Якщо знімок не може безпечно виконати round-trip сирого тексту, Control UI примусово вмикає режим Форми й вимикає режим Raw для цього знімка. + - У редакторі Raw JSON дія "Скинути до збереженого" зберігає створену в raw форму (форматування, коментарі, розташування `$include`) замість повторного рендерингу сплощеного знімка, тому зовнішні редагування переживають скидання, коли знімок може безпечно виконати round-trip. + - Структуровані значення об’єктів SecretRef рендеряться лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню object-to-string. - - - Налагодження: snapshots status/health/models + event log + ручні RPC calls (`status`, `health`, `models.list`). - - Логи: live tail gateway file logs із фільтром/експортом (`logs.tail`). - - Оновлення: запуск package/git update + перезапуск (`update.run`) зі звітом про перезапуск, потім polling `update.status` після повторного підключення для перевірки версії запущеного gateway. + + - Налагодження: знімки статусу/health/models + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`). + - Журнали: live tail файлових журналів Gateway із фільтром/експортом (`logs.tail`). + - Оновлення: запуск package/git оновлення + перезапуск (`update.run`) зі звітом про перезапуск, потім опитування `update.status` після повторного підключення, щоб перевірити версію запущеного Gateway. - - - Для ізольованих jobs delivery типово налаштовано на announce summary. Ви можете перемкнути на none, якщо потрібні internal-only runs. - - Поля channel/target з’являються, коли вибрано announce. - - Webhook mode використовує `delivery.mode = "webhook"` з `delivery.to`, встановленим на дійсну HTTP(S) webhook URL. - - Для main-session jobs доступні webhook і none delivery modes. - - Advanced edit controls містять delete-after-run, clear agent override, cron exact/stagger options, agent model/thinking overrides і best-effort delivery toggles. - - Валідація форми inline з помилками на рівні полів; недійсні значення вимикають кнопку save, доки їх не буде виправлено. - - Задайте `cron.webhookToken`, щоб надсилати dedicated bearer token; якщо пропущено, webhook надсилається без auth header. - - Deprecated fallback: збережені legacy jobs із `notify: true` все ще можуть використовувати `cron.webhook` до міграції. + + - Для ізольованих завдань доставка за замовчуванням оголошує підсумок. Можна перемкнути на none, якщо потрібні лише внутрішні запуски. + - Поля каналу/цілі з’являються, коли вибрано announce. + - Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, заданим як дійсна HTTP(S) webhook URL-адреса. + - Для завдань main-session доступні режими доставки webhook і none. + - Розширені елементи керування редагуванням містять delete-after-run, очищення перевизначення агента, точні/зміщені параметри cron, перевизначення моделі/мислення агента та перемикачі доставки best-effort. + - Валідація форми вбудована з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не виправлено. + - Задайте `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його пропущено, webhook надсилається без заголовка автентифікації. + - Застарілий fallback: збережені legacy jobs із `notify: true` все ще можуть використовувати `cron.webhook` до міграції. @@ -154,81 +154,82 @@ Control UI може локалізуватися під час першого з ## Поведінка чату - - - `chat.send` є **неблокувальним**: він одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`. - - Завантаження в чат приймають зображення та невідеофайли. Зображення зберігають власний шлях до зображення; інші файли зберігаються як керовані медіа й показуються в історії як посилання на вкладення. - - Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання і `{ status: "ok" }` після завершення. - - Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи транскрипту завеликі, Gateway може обрізати довгі текстові поля, опускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`). - - Зображення асистента або згенеровані зображення зберігаються як керовані медіапосилання й повертаються через автентифіковані медіа-URL Gateway, тому перезавантаження не залежать від того, чи лишаються сирі base64-навантаження зображень у відповіді історії чату. - - `chat.history` також прибирає з видимого тексту асистента службові inline-теги директив лише для відображення (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML-навантаження викликів інструментів (зокрема `...`, `...`, `...`, `...` і обрізані блоки викликів інструментів), а також витоки ASCII/повноширинних контрольних токенів моделі, і опускає записи асистента, весь видимий текст яких є лише точним silent-токеном `NO_REPLY` / `no_reply`. - - Під час активного надсилання та фінального оновлення історії подання чату зберігає видимими локальні оптимістичні повідомлення користувача/асистента, якщо `chat.history` на короткий час повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє стан. - - `chat.inject` додає нотатку асистента до транскрипту сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставки в канал). - - Пікери моделі та thinking у заголовку чату негайно змінюють активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не параметри надсилання лише для одного ходу. - - Пікер моделі чату запитує налаштоване подання моделей Gateway. Якщо присутній `agents.defaults.models`, цей allowlist керує пікером. Інакше пікер показує явні записи `models.providers.*.models` і провайдерів із придатною автентифікацією. Повний каталог лишається доступним через debug RPC `models.list` з `view: "all"`. - - Коли свіжі звіти Gateway про використання сесії показують високий тиск контексту, область composer чату показує сповіщення про контекст, а на рекомендованих рівнях Compaction - кнопку compact, що запускає звичайний шлях Compaction сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить свіже використання. + + - `chat.send` є **неблокувальним**: одразу підтверджує отримання через `{ runId, status: "started" }`, а відповідь транслюється через події `chat`. + - Завантаження в чат приймають зображення та невідеофайли. Зображення зберігають нативний шлях до зображення; інші файли зберігаються як керовані медіа й показуються в історії як посилання на вкладення. + - Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення. + - Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи транскрипту надто великі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати завеликі повідомлення заповнювачем (`[chat.history omitted: message too large]`). + - Зображення, створені асистентом, зберігаються як керовані медіапосилання й повертаються через автентифіковані медіа-URL Gateway, тож перезавантаження не залежать від того, чи залишаються необроблені base64-навантаження зображень у відповіді історії чату. + - `chat.history` також вилучає з видимого тексту асистента лише-відображувальні вбудовані теги директив (наприклад `[[reply_to_*]]` і `[[audio_as_voice]]`), plain-text XML-навантаження викликів інструментів (зокрема `...`, `...`, `...`, `...` і обрізані блоки викликів інструментів), а також витеклі ASCII/повноширинні керівні токени моделі, і пропускає записи асистента, увесь видимий текст яких є лише точним тихим токеном `NO_REPLY` / `no_reply`. + - Під час активного надсилання та фінального оновлення історії подання чату залишає видимими локальні оптимістичні повідомлення користувача/асистента, якщо `chat.history` на мить повертає старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно історія Gateway наздоганяє стан. + - `chat.inject` додає нотатку асистента до транскрипту сесії та транслює подію `chat` для оновлень лише в UI (без запуску агента, без доставки в канал). + - Вибирачі моделі та режиму мислення в заголовку чату негайно патчать активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не одноразові параметри надсилання. + - Введення `/new` у Control UI створює й перемикає на ту саму нову сесію панелі, що й Новий чат. Введення `/reset` зберігає явне скидання Gateway на місці для поточної сесії. + - Вибирач моделі чату запитує налаштоване подання моделей Gateway. Якщо наявний `agents.defaults.models`, цей список дозволених значень керує вибирачем. Інакше вибирач показує явні записи `models.providers.*.models` плюс провайдерів із придатною автентифікацією. Повний каталог залишається доступним через налагоджувальний RPC `models.list` з `view: "all"`. + - Коли свіжі звіти про використання сесії Gateway показують високий тиск контексту, область композитора чату показує повідомлення про контекст, а на рекомендованих рівнях Compaction - компактну кнопку, що запускає звичайний шлях Compaction сесії. Застарілі знімки токенів приховуються, доки Gateway знову не повідомить свіже використання. - Режим розмови використовує зареєстрованого провайдера голосу realtime. Налаштуйте OpenAI за допомогою `talk.provider: "openai"` разом із `talk.providers.openai.apiKey`, або налаштуйте Google за допомогою `talk.provider: "google"` разом із `talk.providers.google.apiKey`; конфігурацію realtime-провайдера Voice Call усе ще можна повторно використати як fallback. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний клієнтський секрет Realtime для WebRTC. Google Live отримує одноразовий обмежений auth-токен Live API для браузерної WebSocket-сесії, з інструкціями та деклараціями інструментів, зафіксованими в токені Gateway. Провайдери, які надають лише backend realtime bridge, працюють через relay-транспорт Gateway, тож облікові дані й vendor-сокети лишаються на сервері, а браузерний аудіопотік проходить через автентифіковані RPC Gateway. Prompt realtime-сесії збирає Gateway; `talk.realtime.session` не приймає надані викликачем перевизначення інструкцій. + Режим розмови використовує зареєстрованого realtime-провайдера голосу. Налаштуйте OpenAI з `talk.provider: "openai"` плюс `talk.providers.openai.apiKey` або налаштуйте Google з `talk.provider: "google"` плюс `talk.providers.google.apiKey`; конфігурацію realtime-провайдера Voice Call усе ще можна повторно використати як резервну. Браузер ніколи не отримує стандартний API-ключ провайдера. OpenAI отримує ефемерний Realtime client secret для WebRTC. Google Live отримує одноразовий обмежений токен автентифікації Live API для браузерної WebSocket-сесії, з інструкціями й деклараціями інструментів, зафіксованими в токені Gateway. Провайдери, які надають лише backend realtime bridge, працюють через relay-транспорт Gateway, тож облікові дані й vendor sockets залишаються на серверному боці, а браузерний аудіопотік проходить через автентифіковані RPC Gateway. Підказку Realtime-сесії збирає Gateway; `talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем. - У composer чату елемент керування Talk - це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли Talk запускається, рядок стану composer показує `Connecting Talk...`, потім `Talk live`, коли аудіо підключено, або `Asking OpenClaw...`, коли realtime-виклик інструмента консультується з налаштованою більшою моделлю через `chat.send`. + У композиторі чату елемент керування розмовою - це кнопка з хвилями поруч із кнопкою диктування через мікрофон. Коли розмова запускається, рядок стану композитора показує `Connecting Talk...`, потім `Talk live`, доки аудіо підключене, або `Asking OpenClaw...`, доки realtime-виклик інструмента звертається до налаштованої більшої моделі через `chat.send`. - Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє OpenAI браузерний WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup і Gateway relay browser adapter з фейковими медіа мікрофона. Команда друкує лише статус провайдера й не журналює секрети. + Maintainer live smoke: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` перевіряє OpenAI browser WebRTC SDP exchange, Google Live constrained-token browser WebSocket setup і Gateway relay browser adapter із фейковими медіа мікрофона. Команда друкує лише стан провайдера й не логує секрети. - - Натисніть **Stop** (викликає `chat.abort`). - - Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це подальше повідомлення в поточний хід. + - Натисніть **Зупинити** (викликає `chat.abort`). + - Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Спрямувати** на повідомленні в черзі, щоб ввести це подальше повідомлення в поточний хід. - Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза основним каналом. - `chat.abort` підтримує `{ sessionKey }` (без `runId`), щоб перервати всі активні запуски для цієї сесії. - - - Коли запуск перервано, частковий текст асистента все ще може показуватися в UI. + + - Коли запуск перервано, частковий текст асистента все одно може показуватися в UI. - Gateway зберігає перерваний частковий текст асистента в історії транскрипту, коли існує буферизований вивід. - - Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізнити часткові результати переривання від звичайного виводу завершення. + - Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізняти перервані часткові дані від нормального виводу завершення. -## Установлення PWA та web push +## Встановлення PWA та веб push -Control UI постачається з `manifest.webmanifest` і service worker, тому сучасні браузери можуть установити його як автономну PWA. Web Push дає Gateway змогу будити встановлену PWA сповіщеннями, навіть коли вкладку або вікно браузера не відкрито. +Control UI постачається з `manifest.webmanifest` і service worker, тож сучасні браузери можуть встановлювати його як окрему PWA. Web Push дає Gateway змогу будити встановлену PWA сповіщеннями, навіть коли вкладка або вікно браузера не відкриті. -| Поверхня | Що вона робить | +| Поверхня | Що робить | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують "Install app", щойно він стає доступним. | -| `ui/public/sw.js` | Service worker, що обробляє події `push` і кліки сповіщень. | -| `push/vapid-keys.json` (у директорії стану OpenClaw) | Автоматично згенерована пара ключів VAPID, яку використовують для підписування Web Push-навантажень. | -| `push/web-push-subscriptions.json` | Збережені endpoint-и браузерних підписок. | +| `ui/public/manifest.webmanifest` | Маніфест PWA. Браузери пропонують «Встановити застосунок», щойно він стає доступним. | +| `ui/public/sw.js` | Service worker, що обробляє події `push` і кліки сповіщень. | +| `push/vapid-keys.json` (у каталозі стану OpenClaw) | Автоматично згенерована пара ключів VAPID, що використовується для підпису Web Push-навантажень. | +| `push/web-push-subscriptions.json` | Збережені endpoints браузерних підписок. | -Перевизначте пару ключів VAPID через змінні середовища в процесі Gateway, коли потрібно зафіксувати ключі (для multi-host розгортань, ротації секретів або тестів): +Перевизначайте пару ключів VAPID через змінні середовища процесу Gateway, коли потрібно закріпити ключі (для розгортань на кількох хостах, ротації секретів або тестів): - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` -- `OPENCLAW_VAPID_SUBJECT` (типово `mailto:openclaw@localhost`) +- `OPENCLAW_VAPID_SUBJECT` (за замовчуванням `mailto:openclaw@localhost`) Control UI використовує ці scope-gated методи Gateway, щоб реєструвати й тестувати браузерні підписки: - `push.web.vapidPublicKey` — отримує активний публічний ключ VAPID. -- `push.web.subscribe` — реєструє `endpoint` разом із `keys.p256dh`/`keys.auth`. -- `push.web.unsubscribe` — видаляє зареєстрований endpoint. +- `push.web.subscribe` — реєструє `endpoint` плюс `keys.p256dh`/`keys.auth`. +- `push.web.unsubscribe` — вилучає зареєстрований endpoint. - `push.web.test` — надсилає тестове сповіщення до підписки викликача. -Web Push незалежний від шляху relay iOS APNS (див. [Конфігурація](/uk/gateway/configuration) для push із підтримкою relay) і наявного методу `push.test`, націленого на нативне мобільне спарювання. +Web Push не залежить від шляху iOS APNS relay (див. [Конфігурація](/uk/gateway/configuration) для relay-backed push) і наявного методу `push.test`, які націлені на нативне мобільне pairing. -## Розміщені embeds +## Hosted embeds -Повідомлення асистента можуть рендерити розміщений вебвміст inline через shortcode `[embed ...]`. Політикою iframe sandbox керує `gateway.controlUi.embedSandbox`: +Повідомлення асистента можуть рендерити hosted web content inline за допомогою shortcode `[embed ...]`. Політикою iframe sandbox керує `gateway.controlUi.embedSandbox`: - Вимикає виконання скриптів усередині розміщених embeds. + Вимикає виконання скриптів усередині hosted embeds. - Дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це типовий режим, і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів. + Дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це стандартний режим, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів. Додає `allow-same-origin` поверх `allow-scripts` для same-site документів, яким навмисно потрібні сильніші привілеї. @@ -248,12 +249,12 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон ``` -Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна same-origin поведінка. Для більшості згенерованих агентом ігор та інтерактивних canvas `scripts` є безпечнішим вибором. +Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна same-origin поведінка. Для більшості ігор і інтерактивних canvas, створених агентом, `scripts` є безпечнішим вибором. -Абсолютні зовнішні URL embeds `http(s)` типово лишаються заблокованими. Якщо ви навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, встановіть `gateway.controlUi.allowExternalEmbedUrls: true`. +Абсолютні зовнішні URL вбудовування `http(s)` за замовчуванням залишаються заблокованими. Якщо ви свідомо хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, встановіть `gateway.controlUi.allowExternalEmbedUrls: true`. -## Доступ tailnet (рекомендовано) +## Доступ через tailnet (рекомендовано) @@ -267,16 +268,16 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон - `https:///` (або ваш налаштований `gateway.controlUi.basePath`) - Типово запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` через `tailscale whois` і зіставляючи її із заголовком, і приймає їх лише тоді, коли запит потрапляє на loopback із заголовками `x-forwarded-*` від Tailscale. Для operator-сесій Control UI з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає round trip спарювання пристрою; браузери без пристрою та з'єднання node-role усе ще проходять звичайні перевірки пристрою. Встановіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані shared-secret навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`. + За замовчуванням запити Control UI/WebSocket Serve можуть автентифікуватися через заголовки ідентичності Tailscale (`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw перевіряє ідентичність, розв'язуючи адресу `x-forwarded-for` через `tailscale whois` і зіставляючи її із заголовком, та приймає їх лише коли запит надходить на loopback із заголовками Tailscale `x-forwarded-*`. Для операторських сесій Control UI з ідентичністю браузерного пристрою цей перевірений шлях Serve також пропускає повторний цикл pairing пристрою; браузери без пристрою та з'єднання з роллю node усе ще проходять звичайні перевірки пристрою. Установіть `gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані shared-secret навіть для трафіку Serve. Потім використовуйте `gateway.auth.mode: "token"` або `"password"`. - Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта та auth scope серіалізуються перед записами rate-limit. Тому одночасні невдалі повтори з того самого браузера можуть показати `retry later` на другому запиті замість двох звичайних невідповідностей, що змагаються паралельно. + Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта й області автентифікації серіалізуються перед записами rate-limit. Тому одночасні хибні повторні спроби з того самого браузера можуть показати `retry later` на другому запиті замість двох простих невідповідностей, що виконуються паралельно. - Auth Serve без токена припускає, що host gateway є довіреним. Якщо на цьому host може виконуватися недовірений локальний код, вимагайте token/password auth. + Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем. - + ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` @@ -292,18 +293,18 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон ## Небезпечний HTTP -Якщо ви відкриваєте dashboard через plain HTTP (`http://` або `http://`), браузер працює в **non-secure context** і блокує WebCrypto. Типово OpenClaw **блокує** з'єднання Control UI без ідентичності пристрою. +Якщо відкрити панель через plain HTTP (`http://` або `http://`), браузер працює в **небезпечному контексті** й блокує WebCrypto. За замовчуванням OpenClaw **блокує** з'єднання Control UI без ідентичності пристрою. -Задокументовані винятки: +Документовані винятки: -- сумісність insecure HTTP лише для localhost із `gateway.controlUi.allowInsecureAuth=true` -- успішна auth operator Control UI через `gateway.auth.mode: "trusted-proxy"` -- break-glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- сумісність localhost-only insecure HTTP з `gateway.controlUi.allowInsecureAuth=true` +- успішна операторська автентифікація Control UI через `gateway.auth.mode: "trusted-proxy"` +- аварійний `gateway.controlUi.dangerouslyDisableDeviceAuth=true` **Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте UI локально: - `https:///` (Serve) -- `http://127.0.0.1:18789/` (на gateway host) +- `http://127.0.0.1:18789/` (на хості gateway) @@ -319,12 +320,12 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон `allowInsecureAuth` є лише локальним перемикачем сумісності: - - Він дозволяє localhost-сесіям Control UI продовжуватися без ідентичності пристрою в non-secure HTTP contexts. - - Він не обходить перевірки спарювання. - - Він не послаблює вимоги до ідентичності віддаленого (не localhost) пристрою. + - Він дозволяє localhost-сесіям Control UI продовжувати роботу без ідентичності пристрою в небезпечних HTTP-контекстах. + - Він не обходить перевірки pairing. + - Він не послаблює вимоги до ідентичності пристрою для віддалених (не-localhost) з'єднань. - + ```json5 { gateway: { @@ -336,42 +337,42 @@ Web Push незалежний від шляху relay iOS APNS (див. [Кон ``` - `dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI та є серйозним зниженням рівня безпеки. Швидко поверніть налаштування після екстреного використання. + `dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою Control UI і є суттєвим зниженням рівня безпеки. Швидко скасуйте це налаштування після аварійного використання. - - - Успішна автентифікація через довірений proxy може дозволити сеанси Control UI рівня **оператор** без ідентичності пристрою. + + - Успішна автентифікація довіреного проксі може допускати сеанси Control UI з роллю **оператора** без ідентичності пристрою. - Це **не** поширюється на сеанси Control UI з роллю вузла. - - Зворотні proxy того самого хоста через loopback усе ще не задовольняють автентифікацію через довірений proxy; див. [Автентифікація через довірений proxy](/uk/gateway/trusted-proxy-auth). + - Зворотні проксі same-host loopback усе одно не задовольняють автентифікацію довіреного проксі; див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth). -Див. [Tailscale](/uk/gateway/tailscale), щоб отримати вказівки з налаштування HTTPS. +Див. [Tailscale](/uk/gateway/tailscale) для вказівок із налаштування HTTPS. ## Політика безпеки вмісту -Control UI постачається зі строгою політикою `img-src`: дозволено лише ресурси **того самого джерела**, URL-адреси `data:` і локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і URL-адреси зображень, відносні до протоколу, відхиляються браузером і не створюють мережевих запитів. +Control UI постачається зі строгою політикою `img-src`: дозволені лише ресурси **same-origin**, URL-адреси `data:` та локально згенеровані URL-адреси `blob:`. Віддалені URL-адреси зображень `http(s)` і protocol-relative відхиляються браузером і не спричиняють мережевих запитів. Що це означає на практиці: -- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/`), усе ще відображаються, включно з автентифікованими маршрутами аватарів, які UI отримує та перетворює на локальні URL-адреси `blob:`. -- Вбудовані URL-адреси `data:image/...` усе ще відображаються (корисно для навантажень у межах протоколу). +- Аватари й зображення, що обслуговуються за відносними шляхами (наприклад `/avatars/`), усе ще відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує й перетворює на локальні URL-адреси `blob:`. +- Вбудовані URL-адреси `data:image/...` усе ще відображаються (корисно для payload у протоколі). - Локальні URL-адреси `blob:`, створені Control UI, усе ще відображаються. -- Віддалені URL-адреси аватарів, що надходять із метаданих каналу, видаляються допоміжними функціями аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може примусити браузер оператора виконувати довільні віддалені запити зображень. +- Віддалені URL-адреси аватарів, створені метаданими каналу, видаляються допоміжними засобами аватарів Control UI і замінюються вбудованим логотипом/бейджем, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень. -Вам не потрібно нічого змінювати, щоб отримати таку поведінку — вона завжди ввімкнена й не налаштовується. +Вам не потрібно нічого змінювати, щоб отримати цю поведінку — вона завжди ввімкнена й не налаштовується. ## Автентифікація маршруту аватара -Коли автентифікацію gateway налаштовано, кінцева точка аватара Control UI вимагає той самий токен gateway, що й решта API: +Коли автентифікацію gateway налаштовано, кінцева точка аватарів Control UI вимагає той самий токен gateway, що й решта API: -- `GET /avatar/` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/?meta=1` повертає метадані аватара за тим самим правилом. -- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до спорідненого маршруту медіа асистента). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені. -- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, щоб зображення все одно відображалося на панелях. +- `GET /avatar/` повертає зображення аватара лише автентифікованим викликам. `GET /avatar/?meta=1` повертає метадані аватара за тим самим правилом. +- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (відповідно до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які інакше захищені. +- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL-адреси blob, тож зображення все одно відображається на dashboard. -Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, відповідно до решти gateway. +Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стає неавтентифікованим, відповідно до решти gateway. ## Збирання UI @@ -381,26 +382,26 @@ Gateway обслуговує статичні файли з `dist/control-ui`. pnpm ui:build ``` -Необов’язкова абсолютна база (коли потрібні фіксовані URL-адреси ресурсів): +Необов’язкова абсолютна база (коли вам потрібні фіксовані URL-адреси ресурсів): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build ``` -Для локальної розробки (окремий dev-сервер): +Для локальної розробки (окремий сервер розробки): ```bash pnpm ui:dev ``` -Потім спрямуйте UI на URL Gateway WS (наприклад, `ws://127.0.0.1:18789`). +Потім спрямуйте UI на URL-адресу WS вашого Gateway (наприклад, `ws://127.0.0.1:18789`). -## Налагодження/тестування: dev-сервер + віддалений Gateway +## Налагодження/тестування: сервер розробки + віддалений Gateway -Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP-джерела. Це зручно, коли ви хочете використовувати локальний dev-сервер Vite, але Gateway працює деінде. +Control UI — це статичні файли; ціль WebSocket налаштовується й може відрізнятися від HTTP origin. Це зручно, коли ви хочете використовувати локальний сервер розробки Vite, але Gateway працює деінде. - + ```bash pnpm ui:dev ``` @@ -422,16 +423,16 @@ Control UI — це статичні файли; ціль WebSocket налашт - `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL. - - Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, закодуйте значення `gatewayUrl` для URL, щоб браузер правильно розібрав рядок запиту. - - `token` слід передавати через фрагмент URL (`#token=...`), коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку в журналах запитів і Referer. Застарілі параметри запиту `?token=` усе ще імпортуються один раз для сумісності, але лише як запасний варіант, і негайно видаляються після bootstrap. + - Якщо ви передаєте повну кінцеву точку `ws://` або `wss://` через `gatewayUrl`, URL-кодуйте значення `gatewayUrl`, щоб браузер правильно розібрав рядок запиту. + - `token` слід передавати через фрагмент URL (`#token=...`) за можливості. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще одноразово імпортуються для сумісності, але лише як fallback, і видаляються одразу після bootstrap. - `password` зберігається лише в пам’яті. - Коли `gatewayUrl` задано, UI не повертається до облікових даних із конфігурації або середовища. Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою. - - Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS proxy тощо). + - Використовуйте `wss://`, коли Gateway розташований за TLS (Tailscale Serve, HTTPS-проксі тощо). - `gatewayUrl` приймається лише у вікні верхнього рівня (не вбудованому), щоб запобігти clickjacking. - - Розгортання Control UI не через loopback мають явно задати `gateway.controlUi.allowedOrigins` (повні джерела). Це включає віддалені dev-налаштування. - - Під час запуску Gateway може додати локальні джерела, як-от `http://localhost:` і `http://127.0.0.1:`, з ефективної прив’язки та порту середовища виконання, але віддалені джерела браузера все одно потребують явних записів. - - Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, крім випадків суворо контрольованого локального тестування. Це означає дозволити будь-яке джерело браузера, а не «зіставити будь-який хост, який я використовую». - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback для джерела з Host-заголовка, але це небезпечний режим безпеки. + - Розгортання Control UI не через loopback повинні явно задавати `gateway.controlUi.allowedOrigins` (повні origins). Це стосується й віддалених середовищ розробки. + - Запуск Gateway може заповнювати локальні origins, як-от `http://localhost:` і `http://127.0.0.1:`, на основі ефективних runtime bind і port, але віддалені browser origins усе одно потребують явних записів. + - Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім суворо контрольованого локального тестування. Це означає дозволити будь-який browser origin, а не «зіставити з будь-яким хостом, який я використовую». + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback для origin із Host-заголовка, але це небезпечний режим безпеки. @@ -448,11 +449,11 @@ Control UI — це статичні файли; ціль WebSocket налашт } ``` -Деталі налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote). +Докладніше про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote). ## Пов’язане -- [Панель](/uk/web/dashboard) — панель gateway -- [Перевірки стану](/uk/gateway/health) — моніторинг стану gateway +- [Dashboard](/uk/web/dashboard) — dashboard gateway +- [Перевірки працездатності](/uk/gateway/health) — моніторинг працездатності gateway - [TUI](/uk/web/tui) — термінальний інтерфейс користувача -- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату +- [WebChat](/uk/web/webchat) — інтерфейс чату в браузері