From a435d2c261d88cb3a5578ff987ad242dab772973 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 2 May 2026 21:07:51 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/matrix-migration.md | 221 +++++++-------- docs/uk/channels/msteams.md | 406 +++++++++++++-------------- docs/uk/channels/nextcloud-talk.md | 85 +++--- docs/uk/channels/nostr.md | 107 ++++--- docs/uk/channels/tlon.md | 171 ++++++----- docs/uk/channels/twitch.md | 144 +++++----- docs/uk/channels/whatsapp.md | 357 ++++++++++++----------- docs/uk/channels/zalo.md | 199 ++++++------- docs/uk/channels/zalouser.md | 89 +++--- docs/uk/cli/plugins.md | 240 ++++++++-------- docs/uk/gateway/config-channels.md | 343 +++++++++++----------- docs/uk/plugins/voice-call.md | 374 ++++++++++++------------ docs/uk/plugins/zalouser.md | 37 ++- 13 files changed, 1383 insertions(+), 1390 deletions(-) diff --git a/docs/uk/channels/matrix-migration.md b/docs/uk/channels/matrix-migration.md index 7b95a8817..b70a1de18 100644 --- a/docs/uk/channels/matrix-migration.md +++ b/docs/uk/channels/matrix-migration.md @@ -1,21 +1,21 @@ --- read_when: - Оновлення наявної інсталяції Matrix - - Міграція зашифрованої історії Matrix і стану пристрою -summary: Як OpenClaw оновлює попередній Plugin Matrix на місці, включно з обмеженнями відновлення зашифрованого стану та кроками ручного відновлення. + - Перенесення зашифрованої історії Matrix і стану пристрою +summary: Як OpenClaw оновлює попередній Matrix Plugin на місці, включно з обмеженнями відновлення зашифрованого стану та кроками ручного відновлення. title: Міграція Matrix x-i18n: - generated_at: "2026-04-29T05:36:42Z" + generated_at: "2026-05-02T21:04:42Z" model: gpt-5.5 provider: openai - source_hash: fff409eef1b7da7be4b63d8459a62b8365a04adf989f271a2f2c4aef46e90716 + source_hash: 8bc9b875fef0ae08978061a9fc7cbb076617009d79487ca8329e03076103b32c source_path: channels/matrix-migration.md workflow: 16 --- -Оновіть попередній публічний Plugin `matrix` до поточної реалізації. +Оновлення з попереднього публічного Plugin `matrix` до поточної реалізації. -Для більшості користувачів оновлення відбувається на місці: +Для більшості користувачів оновлення виконується на місці: - Plugin залишається `@openclaw/matrix` - канал залишається `matrix` @@ -27,89 +27,89 @@ x-i18n: ## Що міграція робить автоматично -Коли Gateway запускається, а також коли ви виконуєте [`openclaw doctor --fix`](/uk/gateway/doctor), OpenClaw намагається автоматично виправити старий стан Matrix. +Коли запускається Gateway, а також коли ви запускаєте [`openclaw doctor --fix`](/uk/gateway/doctor), OpenClaw намагається автоматично відновити старий стан Matrix. Перед тим як будь-який дієвий крок міграції Matrix змінює стан на диску, OpenClaw створює або повторно використовує цільовий знімок відновлення. Коли ви використовуєте `openclaw update`, точний тригер залежить від того, як установлено OpenClaw: -- установлення з вихідного коду виконують `openclaw doctor --fix` під час процесу оновлення, а потім типово перезапускають Gateway -- установлення через менеджер пакетів оновлюють пакет, виконують неінтерактивний прохід doctor, а потім покладаються на типовий перезапуск Gateway, щоб запуск міг завершити міграцію Matrix -- якщо ви використовуєте `openclaw update --no-restart`, міграція Matrix, що виконується під час запуску, відкладається, доки пізніше ви не виконаєте `openclaw doctor --fix` і не перезапустите Gateway +- встановлення з вихідного коду запускають `openclaw doctor --fix` під час процесу оновлення, а потім за замовчуванням перезапускають Gateway +- встановлення через менеджер пакетів оновлюють пакет, запускають неінтерактивний прохід doctor, а потім покладаються на стандартний перезапуск Gateway, щоб запуск міг завершити міграцію Matrix +- якщо ви використовуєте `openclaw update --no-restart`, міграція Matrix, що виконується під час запуску, відкладається, доки ви пізніше не запустите `openclaw doctor --fix` і не перезапустите Gateway Автоматична міграція охоплює: - створення або повторне використання знімка перед міграцією в `~/Backups/openclaw-migrations/` - повторне використання ваших кешованих облікових даних Matrix -- збереження того самого вибору облікового запису та конфігурації `channels.matrix` -- переміщення найстарішого плаского сховища синхронізації Matrix у поточне розташування з прив’язкою до облікового запису -- переміщення найстарішого плаского криптосховища Matrix у поточне розташування з прив’язкою до облікового запису, коли цільовий обліковий запис можна безпечно визначити -- витягнення раніше збереженого ключа розшифрування резервної копії ключів кімнат Matrix зі старого криптосховища rust, коли цей ключ існує локально -- повторне використання найповнішого наявного кореня сховища з хешем токена для того самого облікового запису Matrix, homeserver і користувача, коли токен доступу пізніше змінюється -- сканування сусідніх коренів сховища з хешем токена на наявність очікуваних метаданих відновлення зашифрованого стану, коли токен доступу Matrix змінився, але ідентичність облікового запису/пристрою залишилася тією самою -- відновлення резервних ключів кімнат у нове криптосховище під час наступного запуску Matrix +- збереження того самого вибору облікового запису й конфігурації `channels.matrix` +- переміщення найстарішого плоского сховища синхронізації Matrix у поточне розташування, прив’язане до облікового запису +- переміщення найстарішого плоского криптосховища Matrix у поточне розташування, прив’язане до облікового запису, коли цільовий обліковий запис можна безпечно визначити +- витягування раніше збереженого ключа розшифрування резервної копії ключів кімнат Matrix зі старого rust-криптосховища, коли цей ключ існує локально +- повторне використання найповнішого наявного кореня сховища з хешем токена для того самого облікового запису Matrix, homeserver і користувача, коли access token згодом змінюється +- сканування сусідніх коренів сховища з хешем токена на наявність метаданих очікуваного відновлення зашифрованого стану, коли access token Matrix змінився, але ідентичність облікового запису/пристрою залишилася тією самою +- відновлення резервних копій ключів кімнат у нове криптосховище під час наступного запуску Matrix Деталі знімка: -- OpenClaw записує файл-маркер у `~/.openclaw/matrix/migration-snapshot.json` після успішного знімка, щоб подальші проходи запуску та виправлення могли повторно використати той самий архів. -- Ці автоматичні знімки міграції Matrix резервують лише конфігурацію + стан (`includeWorkspace: false`). -- Якщо Matrix має лише попереджувальний стан міграції, наприклад через те, що `userId` або `accessToken` досі відсутні, OpenClaw ще не створює знімок, бо жодна зміна Matrix не є дієвою. -- Якщо крок знімка завершується помилкою, OpenClaw пропускає міграцію Matrix для цього запуску замість того, щоб змінювати стан без точки відновлення. +- OpenClaw записує файл-маркер у `~/.openclaw/matrix/migration-snapshot.json` після успішного знімка, щоб подальші проходи запуску й відновлення могли повторно використати той самий архів. +- Ці автоматичні знімки міграції Matrix створюють резервну копію лише конфігурації + стану (`includeWorkspace: false`). +- Якщо Matrix має лише попереджувальний стан міграції, наприклад через те, що `userId` або `accessToken` усе ще відсутні, OpenClaw ще не створює знімок, бо жодна зміна Matrix не є дієвою. +- Якщо крок знімка не вдається, OpenClaw пропускає міграцію Matrix для цього запуску замість того, щоб змінювати стан без точки відновлення. Про оновлення з кількома обліковими записами: -- найстаріше пласке сховище Matrix (`~/.openclaw/matrix/bot-storage.json` і `~/.openclaw/matrix/crypto/`) походило з макета з одним сховищем, тому OpenClaw може мігрувати його лише в одну визначену ціль облікового запису Matrix -- уже прив’язані до облікового запису застарілі сховища Matrix виявляються та готуються для кожного налаштованого облікового запису Matrix +- найстаріше плоске сховище Matrix (`~/.openclaw/matrix/bot-storage.json` і `~/.openclaw/matrix/crypto/`) походить із макета з одним сховищем, тому OpenClaw може мігрувати його лише в одну визначену ціль облікового запису Matrix +- уже прив’язані до облікового запису застарілі сховища Matrix виявляються й готуються окремо для кожного налаштованого облікового запису Matrix ## Що міграція не може зробити автоматично -Попередній публічний Plugin Matrix **не** створював автоматично резервні копії ключів кімнат Matrix. Він зберігав локальний криптостан і запитував перевірку пристрою, але не гарантував, що ваші ключі кімнат були зарезервовані на homeserver. +Попередній публічний Matrix Plugin **не** створював автоматично резервні копії ключів кімнат Matrix. Він зберігав локальний криптографічний стан і запитував перевірку пристрою, але не гарантував, що ваші ключі кімнат були зарезервовані на homeserver. Це означає, що деякі зашифровані встановлення можна мігрувати лише частково. OpenClaw не може автоматично відновити: -- локальні ключі кімнат, які ніколи не резервувалися -- зашифрований стан, коли цільовий обліковий запис Matrix ще не можна визначити, бо `homeserver`, `userId` або `accessToken` досі недоступні -- автоматичну міграцію одного спільного плаского сховища Matrix, коли налаштовано кілька облікових записів Matrix, але `channels.matrix.defaultAccount` не встановлено -- встановлення Plugin зі спеціальним шляхом, які закріплені за шляхом до репозиторію замість стандартного пакета Matrix -- відсутній ключ відновлення, коли старе сховище мало резервні ключі, але не зберегло ключ розшифрування локально +- ключі кімнат, що існували лише локально й ніколи не були зарезервовані +- зашифрований стан, коли цільовий обліковий запис Matrix ще не можна визначити, бо `homeserver`, `userId` або `accessToken` усе ще недоступні +- автоматичну міграцію одного спільного плоского сховища Matrix, коли налаштовано кілька облікових записів Matrix, але `channels.matrix.defaultAccount` не задано +- встановлення Plugin за користувацьким шляхом, які прив’язані до шляху репозиторію замість стандартного пакета Matrix +- відсутній ключ відновлення, коли старе сховище мало зарезервовані ключі, але не зберегло ключ розшифрування локально Поточна область попереджень: -- встановлення Plugin Matrix зі спеціальним шляхом показуються як під час запуску Gateway, так і в `openclaw doctor` +- встановлення Matrix Plugin за користувацьким шляхом показуються як під час запуску Gateway, так і через `openclaw doctor` -Якщо ваша стара інсталяція мала локальну зашифровану історію, яку ніколи не було зарезервовано, деякі старіші зашифровані повідомлення можуть залишитися нечитабельними після оновлення. +Якщо ваша стара інсталяція мала локальну зашифровану історію, для якої ніколи не створювали резервну копію, деякі старіші зашифровані повідомлення можуть залишитися нечитабельними після оновлення. ## Рекомендований процес оновлення -1. Оновіть OpenClaw і Plugin Matrix звичайним способом. +1. Оновіть OpenClaw і Matrix Plugin звичайним способом. Надавайте перевагу простому `openclaw update` без `--no-restart`, щоб запуск міг одразу завершити міграцію Matrix. -2. Виконайте: +2. Запустіть: ```bash openclaw doctor --fix ``` - Якщо Matrix має дієву роботу з міграції, doctor спершу створить або повторно використає знімок перед міграцією та надрукує шлях до архіву. + Якщо Matrix має дієву роботу міграції, doctor спочатку створить або повторно використає знімок перед міграцією та виведе шлях до архіву. 3. Запустіть або перезапустіть Gateway. -4. Перевірте поточний стан верифікації та резервного копіювання: +4. Перевірте поточний стан перевірки й резервного копіювання: ```bash openclaw matrix verify status openclaw matrix verify backup status ``` -5. Помістіть ключ відновлення для облікового запису Matrix, який ви виправляєте, у змінну середовища для конкретного облікового запису. Для одного типового облікового запису достатньо `MATRIX_RECOVERY_KEY`. Для кількох облікових записів використовуйте окрему змінну для кожного, наприклад `MATRIX_RECOVERY_KEY_ASSISTANT`, і додайте `--account assistant` до команди. +5. Помістіть ключ відновлення для облікового запису Matrix, який ви ремонтуєте, в змінну середовища, специфічну для облікового запису. Для одного стандартного облікового запису `MATRIX_RECOVERY_KEY` підходить. Для кількох облікових записів використовуйте по одній змінній на обліковий запис, наприклад `MATRIX_RECOVERY_KEY_ASSISTANT`, і додайте `--account assistant` до команди. -6. Якщо OpenClaw повідомляє, що потрібен ключ відновлення, виконайте команду для відповідного облікового запису: +6. Якщо OpenClaw повідомляє, що потрібен ключ відновлення, запустіть команду для відповідного облікового запису: ```bash printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin printf '%s\n' "$MATRIX_RECOVERY_KEY_ASSISTANT" | openclaw matrix verify backup restore --recovery-key-stdin --account assistant ``` -7. Якщо цей пристрій досі не перевірено, виконайте команду для відповідного облікового запису: +7. Якщо цей пристрій усе ще не перевірено, запустіть команду для відповідного облікового запису: ```bash printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin @@ -117,23 +117,23 @@ OpenClaw не може автоматично відновити: ``` Якщо ключ відновлення прийнято й резервна копія придатна до використання, але `Cross-signing verified` - досі має значення `no`, завершіть самоверифікацію з іншого клієнта Matrix: + усе ще має значення `no`, завершіть самоперевірку з іншого клієнта Matrix: ```bash openclaw matrix verify self ``` Прийміть запит в іншому клієнті Matrix, порівняйте емодзі або десяткові числа - і введіть `yes` лише коли вони збігаються. Команда завершується успішно лише + і введіть `yes` лише тоді, коли вони збігаються. Команда завершується успішно лише після того, як `Cross-signing verified` стане `yes`. -8. Якщо ви свідомо відмовляєтеся від старої історії, яку неможливо відновити, і хочете створити свіжу базову резервну копію для майбутніх повідомлень, виконайте: +8. Якщо ви свідомо відмовляєтеся від невідновлюваної старої історії й хочете створити свіжу базову резервну копію для майбутніх повідомлень, запустіть: ```bash openclaw matrix verify backup reset --yes ``` -9. Якщо резервної копії ключів на стороні сервера ще немає, створіть її для майбутніх відновлень: +9. Якщо серверної резервної копії ключів ще не існує, створіть її для майбутніх відновлень: ```bash openclaw matrix verify bootstrap @@ -143,120 +143,114 @@ OpenClaw не може автоматично відновити: Міграція зашифрованих даних — це двоетапний процес: -1. Запуск або `openclaw doctor --fix` створює або повторно використовує знімок перед міграцією, якщо міграція зашифрованих даних є дієвою. -2. Запуск або `openclaw doctor --fix` перевіряє старе криптосховище Matrix через активне встановлення Plugin Matrix. -3. Якщо знайдено ключ розшифрування резервної копії, OpenClaw записує його в новий процес ключа відновлення та позначає відновлення ключів кімнат як очікуване. -4. Під час наступного запуску Matrix OpenClaw автоматично відновлює резервні ключі кімнат у нове криптосховище. +1. Запуск або `openclaw doctor --fix` створює чи повторно використовує знімок перед міграцією, якщо міграція зашифрованих даних є дієвою. +2. Запуск або `openclaw doctor --fix` перевіряє старе криптосховище Matrix через активну інсталяцію Matrix Plugin. +3. Якщо знайдено ключ розшифрування резервної копії, OpenClaw записує його в новий потік ключа відновлення й позначає відновлення ключів кімнат як очікуване. +4. Під час наступного запуску Matrix OpenClaw автоматично відновлює зарезервовані ключі кімнат у нове криптосховище. -Якщо старе сховище повідомляє про ключі кімнат, які ніколи не резервувалися, OpenClaw попереджає замість того, щоб удавати, що відновлення успішне. +Якщо старе сховище повідомляє про ключі кімнат, які ніколи не були зарезервовані, OpenClaw попереджає, а не вдає, що відновлення успішне. -## Поширені повідомлення та що вони означають +## Поширені повідомлення та їх значення -### Повідомлення про оновлення та виявлення +### Повідомлення про оновлення й виявлення `Matrix plugin upgraded in place.` -- Значення: старий стан Matrix на диску було виявлено та мігровано в поточний макет. +- Значення: старий стан Matrix на диску було виявлено й мігровано в поточний макет. - Що робити: нічого, якщо той самий вивід також не містить попереджень. `Matrix migration snapshot created before applying Matrix upgrades.` - Значення: OpenClaw створив архів відновлення перед зміною стану Matrix. -- Що робити: збережіть надрукований шлях до архіву, доки не підтвердите, що міграція успішна. +- Що робити: збережіть виведений шлях до архіву, доки не підтвердите, що міграція успішна. `Matrix migration snapshot reused before applying Matrix upgrades.` - Значення: OpenClaw знайшов наявний маркер знімка міграції Matrix і повторно використав цей архів замість створення дубліката резервної копії. -- Що робити: збережіть надрукований шлях до архіву, доки не підтвердите, що міграція успішна. +- Що робити: збережіть виведений шлях до архіву, доки не підтвердите, що міграція успішна. `Legacy Matrix state detected at ... but channels.matrix is not configured yet.` - Значення: старий стан Matrix існує, але OpenClaw не може зіставити його з поточним обліковим записом Matrix, бо Matrix не налаштовано. -- Що робити: налаштуйте `channels.matrix`, потім повторно виконайте `openclaw doctor --fix` або перезапустіть Gateway. +- Що робити: налаштуйте `channels.matrix`, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).` -- Значення: OpenClaw знайшов старий стан, але досі не може визначити точний поточний корінь облікового запису/пристрою. -- Що робити: один раз запустіть Gateway із робочим входом Matrix або повторно виконайте `openclaw doctor --fix` після появи кешованих облікових даних. +- Значення: OpenClaw знайшов старий стан, але все ще не може визначити точний поточний корінь облікового запису/пристрою. +- Що робити: один раз запустіть Gateway із робочим входом Matrix або повторно запустіть `openclaw doctor --fix` після появи кешованих облікових даних. `Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.` -- Значення: OpenClaw знайшов одне спільне пласке сховище Matrix, але відмовляється вгадувати, який іменований обліковий запис Matrix має його отримати. -- Що робити: установіть `channels.matrix.defaultAccount` на потрібний обліковий запис, потім повторно виконайте `openclaw doctor --fix` або перезапустіть Gateway. +- Значення: OpenClaw знайшов одне спільне плоске сховище Matrix, але відмовляється вгадувати, який іменований обліковий запис Matrix має його отримати. +- Що робити: задайте `channels.matrix.defaultAccount` для потрібного облікового запису, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Matrix legacy sync store not migrated because the target already exists (...)` -- Значення: нове розташування з прив’язкою до облікового запису вже має сховище синхронізації або криптосховище, тому OpenClaw не перезаписав його автоматично. +- Значення: нове розташування, прив’язане до облікового запису, вже має сховище синхронізації або криптосховище, тому OpenClaw не перезаписав його автоматично. - Що робити: переконайтеся, що поточний обліковий запис правильний, перш ніж вручну видаляти або переміщувати конфліктну ціль. `Failed migrating Matrix legacy sync store (...)` або `Failed migrating Matrix legacy crypto store (...)` -- Значення: OpenClaw спробував перемістити старий стан Matrix, але операція файлової системи завершилася помилкою. -- Що робити: перевірте дозволи файлової системи та стан диска, потім повторно виконайте `openclaw doctor --fix`. +- Значення: OpenClaw спробував перемістити старий стан Matrix, але файлова операція не вдалася. +- Що робити: перевірте дозволи файлової системи й стан диска, потім повторно запустіть `openclaw doctor --fix`. `Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.` -- Значення: OpenClaw знайшов старе зашифроване сховище Matrix, але немає поточної конфігурації Matrix, до якої його можна приєднати. -- Що робити: налаштуйте `channels.matrix`, потім повторно виконайте `openclaw doctor --fix` або перезапустіть Gateway. +- Значення: OpenClaw знайшов старе зашифроване сховище Matrix, але немає поточної конфігурації Matrix, до якої його можна прив’язати. +- Що робити: налаштуйте `channels.matrix`, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).` - Значення: зашифроване сховище існує, але OpenClaw не може безпечно вирішити, до якого поточного облікового запису/пристрою воно належить. -- Що робити: один раз запустіть Gateway із робочим входом Matrix або повторно виконайте `openclaw doctor --fix` після появи кешованих облікових даних. +- Що робити: один раз запустіть Gateway із робочим входом Matrix або повторно запустіть `openclaw doctor --fix` після появи кешованих облікових даних. `Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.` -- Значення: OpenClaw знайшов одне спільне пласке застаріле криптосховище Matrix, але відмовляється вгадувати, який іменований обліковий запис Matrix має його отримати. -- Що робити: установіть `channels.matrix.defaultAccount` на потрібний обліковий запис, потім повторно виконайте `openclaw doctor --fix` або перезапустіть Gateway. +- Значення: OpenClaw знайшов одне спільне плоске застаріле криптосховище, але відмовляється вгадувати, який іменований обліковий запис Matrix має його отримати. +- Що робити: задайте `channels.matrix.defaultAccount` для потрібного облікового запису, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.` -- Значення: OpenClaw виявив старий стан Matrix, але міграцію досі заблоковано через відсутні дані ідентичності або облікових даних. -- Що робити: завершіть вхід у Matrix або налаштування конфігурації, потім повторно виконайте `openclaw doctor --fix` або перезапустіть Gateway. +- Значення: OpenClaw виявив старий стан Matrix, але міграція все ще заблокована через відсутні дані ідентичності або облікових даних. +- Що робити: завершіть вхід у Matrix або налаштування конфігурації, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @openclaw/matrix so OpenClaw can inspect the old rust crypto store before upgrading.` - Значення: OpenClaw знайшов старий зашифрований стан Matrix, але не зміг завантажити допоміжну точку входу з Matrix Plugin, яка зазвичай перевіряє це сховище. -- Що робити: перевстановіть або відновіть Matrix Plugin (`openclaw plugins install @openclaw/matrix`, або `openclaw plugins install ./path/to/local/matrix-plugin` для checkout репозиторію), потім повторно запустіть `openclaw doctor --fix` або перезапустіть gateway. -- Якщо npm повідомляє, що пакет Matrix, який належить OpenClaw, застарілий, використовуйте вбудований - plugin з поточної пакетованої збірки OpenClaw або шлях до локального checkout, доки - не буде опубліковано новіший npm-пакет. +- Що робити: перевстановіть або відновіть Matrix Plugin (`openclaw plugins install @openclaw/matrix` або `openclaw plugins install ./path/to/local/matrix-plugin` для checkout репозиторію), потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.` - Значення: OpenClaw знайшов шлях до допоміжного файла, який виходить за межі кореня plugin або не проходить перевірки меж plugin, тому відмовився його імпортувати. -- Що робити: перевстановіть Matrix Plugin із довіреного шляху, потім повторно запустіть `openclaw doctor --fix` або перезапустіть gateway. +- Що робити: перевстановіть Matrix plugin з довіреного шляху, потім повторно запустіть `openclaw doctor --fix` або перезапустіть gateway. `- Failed creating a Matrix migration snapshot before repair: ...` `- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".` -- Значення: OpenClaw відмовився змінювати стан Matrix, бо спершу не зміг створити snapshot для відновлення. +- Значення: OpenClaw відмовився змінювати стан Matrix, бо спочатку не зміг створити знімок для відновлення. - Що робити: усуньте помилку резервного копіювання, потім повторно запустіть `openclaw doctor --fix` або перезапустіть gateway. `Failed migrating legacy Matrix client storage: ...` -- Значення: клієнтський fallback Matrix знайшов старе пласке сховище, але переміщення не вдалося. OpenClaw тепер перериває цей fallback замість того, щоб тихо стартувати з новим порожнім сховищем. -- Що робити: перевірте дозволи файлової системи або конфлікти, збережіть старий стан недоторканим і повторіть спробу після виправлення помилки. +- Значення: резервний механізм на боці клієнта Matrix знайшов старе пласке сховище, але переміщення не вдалося. Тепер OpenClaw перериває цей резервний шлях замість того, щоб мовчки запускатися з новим порожнім сховищем. +- Що робити: перевірте права доступу до файлової системи або конфлікти, збережіть старий стан без змін і повторіть спробу після виправлення помилки. `Matrix is installed from a custom path: ...` -- Значення: Matrix закріплено за встановленням із шляху, тому основні оновлення не замінюють його автоматично стандартним пакетом Matrix із репозиторію. -- Що робити: перевстановіть за допомогою `openclaw plugins install @openclaw/matrix`, коли хочете повернутися до типового Matrix Plugin. -- Якщо npm повідомляє, що пакет Matrix, який належить OpenClaw, застарілий, використовуйте вбудований - plugin з поточної пакетованої збірки OpenClaw, доки не буде - опубліковано новіший npm-пакет. +- Значення: Matrix закріплено як встановлення зі шляху, тому основні оновлення не замінюють його автоматично стандартним пакетом Matrix з репозиторію. +- Що робити: перевстановіть за допомогою `openclaw plugins install @openclaw/matrix`, коли захочете повернутися до стандартного Matrix plugin. ### Повідомлення відновлення зашифрованого стану `matrix: restored X/Y room key(s) from legacy encrypted-state backup` -- Значення: резервні ключі кімнат успішно відновлено в нове crypto-сховище. +- Значення: резервні копії ключів кімнат успішно відновлено в нове криптосховище. - Що робити: зазвичай нічого. `matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically` -- Значення: деякі старі ключі кімнат існували лише в старому локальному сховищі й ніколи не були завантажені до резервної копії Matrix. +- Значення: деякі старі ключі кімнат існували лише у старому локальному сховищі й ніколи не були завантажені до резервної копії Matrix. - Що робити: очікуйте, що частина старої зашифрованої історії залишиться недоступною, якщо ви не зможете вручну відновити ці ключі з іншого перевіреного клієнта. `Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "openclaw matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.` @@ -267,48 +261,48 @@ OpenClaw не може автоматично відновити: `Failed inspecting legacy Matrix encrypted state for account "..." (...): ...` - Значення: OpenClaw знайшов старе зашифроване сховище, але не зміг перевірити його достатньо безпечно, щоб підготувати відновлення. -- Що робити: повторно запустіть `openclaw doctor --fix`. Якщо це повторюється, залиште каталог старого стану недоторканим і виконайте відновлення за допомогою іншого перевіреного клієнта Matrix плюс `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. +- Що робити: повторно запустіть `openclaw doctor --fix`. Якщо це повториться, збережіть старий каталог стану без змін і виконайте відновлення за допомогою іншого перевіреного клієнта Matrix плюс `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. `Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.` -- Значення: OpenClaw виявив конфлікт ключа резервної копії й відмовився автоматично перезаписувати поточний файл recovery-key. -- Що робити: перевірте, який ключ відновлення правильний, перед повторною спробою будь-якої команди відновлення. +- Значення: OpenClaw виявив конфлікт ключів резервної копії та відмовився автоматично перезаписати поточний файл recovery-key. +- Що робити: перевірте, який ключ відновлення правильний, перш ніж повторювати будь-яку команду відновлення. `Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.` - Значення: це жорстке обмеження старого формату сховища. -- Що робити: резервні ключі все ще можна відновити, але локальна зашифрована історія може залишитися недоступною. +- Що робити: ключі з резервної копії все ще можна відновити, але локальна зашифрована історія може залишитися недоступною. `matrix: failed restoring room keys from legacy encrypted-state backup: ...` -- Значення: новий plugin спробував виконати відновлення, але Matrix повернув помилку. -- Що робити: запустіть `openclaw matrix verify backup status`, потім за потреби повторіть із `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. +- Значення: новий plugin спробував відновлення, але Matrix повернув помилку. +- Що робити: запустіть `openclaw matrix verify backup status`, потім за потреби повторіть спробу з `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. ### Повідомлення ручного відновлення `Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.` - Значення: OpenClaw знає, що у вас має бути ключ резервної копії, але він не активний на цьому пристрої. -- Що робити: запустіть `openclaw matrix verify backup restore`, або встановіть `MATRIX_RECOVERY_KEY` і за потреби запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. +- Що робити: запустіть `openclaw matrix verify backup restore` або встановіть `MATRIX_RECOVERY_KEY` і за потреби запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. `Store a recovery key with 'openclaw matrix verify device --recovery-key-stdin', then run 'openclaw matrix verify backup restore'.` -- Значення: на цьому пристрої наразі не збережено ключ відновлення. +- Значення: на цьому пристрої зараз не збережено ключ відновлення. - Що робити: встановіть `MATRIX_RECOVERY_KEY`, запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`, потім відновіть резервну копію. `Backup key mismatch on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin' with the matching recovery key.` - Значення: збережений ключ не відповідає активній резервній копії Matrix. -- Що робити: встановіть `MATRIX_RECOVERY_KEY` на правильний ключ і запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. +- Що робити: встановіть `MATRIX_RECOVERY_KEY` у правильний ключ і запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. -Якщо ви погоджуєтеся втратити невідновлювану стару зашифровану історію, натомість можна скинути +Якщо ви погоджуєтеся втратити стару зашифровану історію, яку неможливо відновити, натомість можна скинути поточну базову лінію резервної копії за допомогою `openclaw matrix verify backup reset --yes`. Коли -збережений секрет резервної копії пошкоджений, це скидання також може повторно створити сховище секретів, щоб +збережений секрет резервної копії пошкоджено, це скидання також може повторно створити secret storage, щоб новий ключ резервної копії міг коректно завантажитися після перезапуску. `Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin'.` -- Значення: резервна копія існує, але цей пристрій ще недостатньо довіряє ланцюжку cross-signing. +- Значення: резервна копія існує, але цей пристрій ще недостатньо довіряє ланцюжку кроспідписування. - Що робити: встановіть `MATRIX_RECOVERY_KEY` і запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. `Matrix recovery key is required` @@ -318,40 +312,37 @@ OpenClaw не може автоматично відновити: `Invalid Matrix recovery key: ...` -- Значення: наданий ключ не вдалося розібрати або він не відповідає очікуваному формату. +- Значення: наданий ключ не вдалося розібрати або він не відповідав очікуваному формату. - Що робити: повторіть спробу з точним ключем відновлення з вашого клієнта Matrix або файла recovery-key. `Matrix recovery key was applied, but this device still lacks full Matrix identity trust.` - Значення: OpenClaw зміг застосувати ключ відновлення, але Matrix досі не - встановив повну довіру до ідентичності cross-signing для цього пристрою. Перевірте - вивід команди на `Recovery key accepted`, `Backup usable`, + встановив повну довіру до ідентичності кроспідписування для цього пристрою. Перевірте + вивід команди на наявність `Recovery key accepted`, `Backup usable`, `Cross-signing verified` і `Device verified by owner`. - Що робити: запустіть `openclaw matrix verify self`, прийміть запит в іншому клієнті Matrix, порівняйте SAS і введіть `yes` лише якщо він збігається. Команда - чекає повної довіри до ідентичності Matrix, перш ніж повідомити про успіх. Використовуйте + очікує повної довіри до ідентичності Matrix перед повідомленням про успіх. Використовуйте `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing` - лише коли ви навмисно хочете замінити поточну ідентичність cross-signing. + лише тоді, коли ви навмисно хочете замінити поточну ідентичність кроспідписування. `Matrix key backup is not active on this device after loading from secret storage.` -- Значення: сховище секретів не створило активний сеанс резервної копії на цьому пристрої. -- Що робити: спершу перевірте пристрій, потім повторно перевірте за допомогою `openclaw matrix verify backup status`. +- Значення: secret storage не створило активний сеанс резервної копії на цьому пристрої. +- Що робити: спочатку перевірте пристрій, потім повторно перевірте за допомогою `openclaw matrix verify backup status`. `Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device --recovery-key-stdin' first.` -- Значення: цей пристрій не може відновити дані зі сховища секретів, доки перевірку пристрою не завершено. -- Що робити: спершу запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. +- Значення: цей пристрій не може відновлюватися з secret storage, доки перевірку пристрою не буде завершено. +- Що робити: спочатку запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. ### Повідомлення встановлення користувацького plugin `Matrix is installed from a custom path that no longer exists: ...` -- Значення: ваш запис встановлення plugin вказує на локальний шлях, якого вже немає. -- Що робити: перевстановіть за допомогою `openclaw plugins install @openclaw/matrix`, або, якщо ви запускаєте з checkout репозиторію, `openclaw plugins install ./path/to/local/matrix-plugin`. -- Якщо npm повідомляє, що пакет Matrix, який належить OpenClaw, застарілий, використовуйте вбудований - plugin з поточної пакетованої збірки OpenClaw або шлях до локального checkout, доки - не буде опубліковано новіший npm-пакет. +- Значення: запис встановлення вашого plugin вказує на локальний шлях, якого вже немає. +- Що робити: перевстановіть за допомогою `openclaw plugins install @openclaw/matrix` або, якщо ви запускаєте з checkout репозиторію, `openclaw plugins install ./path/to/local/matrix-plugin`. ## Якщо зашифрована історія все ще не повертається @@ -363,11 +354,11 @@ openclaw matrix verify backup status --verbose printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose ``` -Якщо резервна копія успішно відновлюється, але в деяких старих кімнатах усе ще немає історії, ці відсутні ключі, ймовірно, ніколи не були збережені в резервній копії попереднім plugin. +Якщо резервна копія відновлюється успішно, але в деяких старих кімнатах усе ще бракує історії, ці відсутні ключі, ймовірно, ніколи не були збережені в резервній копії попереднім plugin. ## Якщо ви хочете почати заново для майбутніх повідомлень -Якщо ви погоджуєтеся втратити невідновлювану стару зашифровану історію й хочете лише чисту базову лінію резервної копії надалі, запустіть ці команди по порядку: +Якщо ви погоджуєтеся втратити стару зашифровану історію, яку неможливо відновити, і хочете лише чисту базову лінію резервної копії надалі, запустіть ці команди по порядку: ```bash openclaw matrix verify backup reset --yes @@ -375,12 +366,12 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Якщо після цього пристрій усе ще не перевірено, завершіть перевірку зі свого клієнта Matrix, порівнявши emoji SAS або десяткові коди й підтвердивши, що вони збігаються. +Якщо після цього пристрій усе ще не перевірено, завершіть перевірку з вашого клієнта Matrix, порівнявши емодзі SAS або десяткові коди й підтвердивши, що вони збігаються. ## Пов’язане -- [Matrix](/uk/channels/matrix): налаштування й конфігурація каналу. +- [Matrix](/uk/channels/matrix): налаштування каналу й конфігурація. - [Правила push Matrix](/uk/channels/matrix-push-rules): маршрутизація сповіщень. -- [Doctor](/uk/gateway/doctor): перевірка справності й автоматичний тригер міграції. -- [Посібник із міграції](/uk/install/migrating): усі шляхи міграції (перенесення машин, імпорти між системами). -- [Plugins](/uk/tools/plugin): встановлення й реєстрація plugin. +- [Doctor](/uk/gateway/doctor): перевірка стану та автоматичний тригер міграції. +- [Посібник із міграції](/uk/install/migrating): усі шляхи міграції (перенесення між машинами, імпорт між системами). +- [Plugins](/uk/tools/plugin): встановлення та реєстрація plugin. diff --git a/docs/uk/channels/msteams.md b/docs/uk/channels/msteams.md index 13ddbaaf9..f213a42a3 100644 --- a/docs/uk/channels/msteams.md +++ b/docs/uk/channels/msteams.md @@ -1,30 +1,30 @@ --- read_when: - Робота над функціями каналу Microsoft Teams -summary: Стан підтримки, можливості та налаштування бота Microsoft Teams +summary: Стан підтримки бота Microsoft Teams, можливості та налаштування title: Microsoft Teams x-i18n: - generated_at: "2026-04-30T00:42:15Z" + generated_at: "2026-05-02T21:04:36Z" model: gpt-5.5 provider: openai - source_hash: c2c8cd13a72941a18d609b1f7263d9b9ed3284873f9b1483975ca1356b543979 + source_hash: a4639844c8caea8120e375d042ad10e41c5dda1e532fdceb460040c90bd767fe source_path: channels/msteams.md workflow: 16 --- -Стан: підтримуються текст і вкладення в DM; надсилання файлів у канал/групу потребує `sharePointSiteId` + дозволів Graph (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). Опитування надсилаються через Adaptive Cards. Дії з повідомленнями надають явний `upload-file` для надсилань, де файл є першим. +Статус: підтримуються текст + вкладення в DM; надсилання файлів у каналах/групах потребує `sharePointSiteId` + дозволів Graph (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). Опитування надсилаються через Adaptive Cards. Дії повідомлень надають явний `upload-file` для надсилань, де файл є основним. ## Вбудований Plugin -Microsoft Teams постачається як вбудований Plugin у поточних випусках OpenClaw, тому в звичайній пакетованій збірці окреме встановлення не потрібне. +Microsoft Teams постачається як вбудований Plugin у поточних випусках OpenClaw, тож окреме встановлення у звичайній пакетованій збірці не потрібне. -Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає вбудований Teams, встановіть поточний npm-пакет, коли його буде опубліковано: +Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає вбудований Teams, установіть npm-пакет напряму: ```bash openclaw plugins install @openclaw/msteams ``` -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, використовуйте поточну пакетовану збірку OpenClaw або шлях до локального checkout, доки не буде опубліковано новіший npm-пакет. +Використовуйте `@openclaw/msteams@beta`, коли стежите за beta-каналом OpenClaw, а npmjs показує `beta` попереду `latest`. Локальний checkout (під час запуску з git-репозиторію): @@ -32,13 +32,13 @@ openclaw plugins install @openclaw/msteams openclaw plugins install ./path/to/local/msteams-plugin ``` -Докладно: [Plugins](/uk/tools/plugin) +Докладніше: [Plugins](/uk/tools/plugin) ## Швидке налаштування -[`@microsoft/teams.cli`](https://www.npmjs.com/package/@microsoft/teams.cli) обробляє реєстрацію бота, створення маніфесту та генерування облікових даних однією командою. +[`@microsoft/teams.cli`](https://www.npmjs.com/package/@microsoft/teams.cli) обробляє реєстрацію бота, створення маніфесту й генерування облікових даних однією командою. -**1. Встановіть і ввійдіть** +**1. Установіть і ввійдіть** ```bash npm install -g @microsoft/teams.cli@preview @@ -47,12 +47,12 @@ teams status # verify you're logged in and see your tenant info ``` -Teams CLI наразі перебуває в preview. Команди й прапорці можуть змінюватися між випусками. +Teams CLI зараз перебуває в preview. Команди й прапорці можуть змінюватися між випусками. -**2. Запустіть тунель** (Teams не може дістатися localhost) +**2. Запустіть тунель** (Teams не може звертатися до localhost) -Встановіть і автентифікуйте devtunnel CLI, якщо ви ще цього не зробили ([посібник із початку роботи](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started)). +Установіть і автентифікуйте devtunnel CLI, якщо ще цього не зробили ([посібник із початку роботи](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started)). ```bash # One-time setup (persistent URL across sessions): @@ -65,10 +65,10 @@ devtunnel host my-openclaw-bot ``` -`--allow-anonymous` потрібен, оскільки Teams не може автентифікуватися з devtunnels. Кожен вхідний запит бота все одно автоматично перевіряється Teams SDK. +`--allow-anonymous` обов’язковий, оскільки Teams не може автентифікуватися з devtunnels. Кожен вхідний запит бота все одно автоматично перевіряється Teams SDK. -Альтернативи: `ngrok http 3978` або `tailscale funnel 3978` (але вони можуть змінювати URL кожної сесії). +Альтернативи: `ngrok http 3978` або `tailscale funnel 3978` (але вони можуть змінювати URL під час кожного сеансу). **3. Створіть застосунок** @@ -81,11 +81,11 @@ teams app create \ Ця одна команда: - Створює застосунок Entra ID (Azure AD) -- Генерує client secret +- Генерує секрет клієнта - Збирає й завантажує маніфест застосунку Teams (з іконками) -- Реєструє бота (типово керується Teams — підписка Azure не потрібна) +- Реєструє бота (типово керований Teams — підписка Azure не потрібна) -Вивід покаже `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID` і **Teams App ID** — занотуйте їх для наступних кроків. Він також запропонує встановити застосунок безпосередньо в Teams. +Вивід покаже `CLIENT_ID`, `CLIENT_SECRET`, `TENANT_ID` і **Teams App ID** — занотуйте їх для наступних кроків. Він також запропонує встановити застосунок у Teams напряму. **4. Налаштуйте OpenClaw** за допомогою облікових даних із виводу: @@ -103,11 +103,11 @@ teams app create \ } ``` -Або використовуйте змінні середовища напряму: `MSTEAMS_APP_ID`, `MSTEAMS_APP_PASSWORD`, `MSTEAMS_TENANT_ID`. +Або використайте змінні середовища напряму: `MSTEAMS_APP_ID`, `MSTEAMS_APP_PASSWORD`, `MSTEAMS_TENANT_ID`. -**5. Встановіть застосунок у Teams** +**5. Установіть застосунок у Teams** -`teams app create` запропонує встановити застосунок — виберіть "Install in Teams". Якщо ви пропустили це, можете отримати посилання пізніше: +`teams app create` запропонує встановити застосунок — виберіть "Установити в Teams". Якщо ви пропустили цей крок, посилання можна отримати пізніше: ```bash teams app get --install-link @@ -121,17 +121,17 @@ teams app doctor Це запускає діагностику реєстрації бота, конфігурації застосунку AAD, чинності маніфесту й налаштування SSO. -Для production-розгортань розгляньте використання [федеративної автентифікації](/uk/channels/msteams#federated-authentication-certificate-plus-managed-identity) (сертифікат або managed identity) замість client secrets. +Для production-розгортань розгляньте використання [федеративної автентифікації](/uk/channels/msteams#federated-authentication-certificate-plus-managed-identity) (сертифіката або керованої ідентичності) замість секретів клієнта. -Групові чати типово заблоковані (`channels.msteams.groupPolicy: "allowlist"`). Щоб дозволити відповіді в групах, задайте `channels.msteams.groupAllowFrom` або використайте `groupPolicy: "open"`, щоб дозволити будь-якого учасника (з обмеженням за згадкою). +Групові чати типово заблоковані (`channels.msteams.groupPolicy: "allowlist"`). Щоб дозволити відповіді в групах, задайте `channels.msteams.groupAllowFrom` або використайте `groupPolicy: "open"`, щоб дозволити будь-якому учаснику (з обмеженням через згадку). ## Цілі - Спілкуватися з OpenClaw через DM, групові чати або канали Teams. -- Зберігати детермінізм маршрутизації: відповіді завжди повертаються в канал, з якого надійшли. -- Типово використовувати безпечну поведінку каналів (згадки обов’язкові, якщо не налаштовано інакше). +- Зберігати детермінований routing: відповіді завжди повертаються до каналу, з якого вони надійшли. +- Типово використовувати безпечну поведінку каналу (згадки обов’язкові, якщо не налаштовано інакше). ## Записи конфігурації @@ -149,16 +149,16 @@ teams app doctor **Доступ до DM** -- Типово: `channels.msteams.dmPolicy = "pairing"`. Невідомі відправники ігноруються, доки їх не схвалено. -- `channels.msteams.allowFrom` має використовувати стабільні object IDs AAD. +- Типово: `channels.msteams.dmPolicy = "pairing"`. Невідомі відправники ігноруються, доки їх не буде схвалено. +- `channels.msteams.allowFrom` має використовувати стабільні object ID AAD. - Не покладайтеся на зіставлення UPN/display-name для allowlists — вони можуть змінюватися. OpenClaw типово вимикає пряме зіставлення імен; увімкніть його явно через `channels.msteams.dangerouslyAllowNameMatching: true`. -- Майстер може зіставляти імена з IDs через Microsoft Graph, коли облікові дані це дозволяють. +- Майстер може зіставляти імена з ID через Microsoft Graph, коли облікові дані це дозволяють. -**Доступ груп** +**Доступ до груп** -- Типово: `channels.msteams.groupPolicy = "allowlist"` (заблоковано, якщо ви не додасте `groupAllowFrom`). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, коли воно не задане. -- `channels.msteams.groupAllowFrom` керує тим, які відправники можуть запускати дії в групових чатах/каналах (із fallback до `channels.msteams.allowFrom`). -- Задайте `groupPolicy: "open"`, щоб дозволити будь-якого учасника (типово все одно з обмеженням за згадкою). +- Типово: `channels.msteams.groupPolicy = "allowlist"` (заблоковано, якщо ви не додасте `groupAllowFrom`). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, коли його не задано. +- `channels.msteams.groupAllowFrom` керує тим, які відправники можуть запускати взаємодію в групових чатах/каналах (із fallback на `channels.msteams.allowFrom`). +- Задайте `groupPolicy: "open"`, щоб дозволити будь-якому учаснику (типово все ще з обмеженням через згадку). - Щоб не дозволяти **жодних каналів**, задайте `channels.msteams.groupPolicy: "disabled"`. Приклад: @@ -176,12 +176,12 @@ teams app doctor **Teams + allowlist каналів** -- Обмежуйте відповіді в групах/каналах, перелічуючи команди й канали в `channels.msteams.teams`. -- Ключі мають використовувати стабільні Teams conversation IDs із посилань Teams, а не змінні відображувані назви. -- Коли `groupPolicy="allowlist"` і наявний allowlist команд, приймаються лише перелічені команди/канали (з обмеженням за згадкою). +- Обмежуйте відповіді груп/каналів, перелічуючи команди й канали в `channels.msteams.teams`. +- Ключі мають використовувати стабільні Teams conversation IDs із посилань Teams, а не змінювані відображувані імена. +- Коли `groupPolicy="allowlist"` і присутній teams allowlist, приймаються лише перелічені команди/канали (з обмеженням через згадку). - Майстер налаштування приймає записи `Team/Channel` і зберігає їх для вас. -- Під час запуску OpenClaw зіставляє назви team/channel і user allowlist з IDs (коли дозволи Graph це дозволяють) - і логує мапінг; нерозв’язані назви team/channel зберігаються так, як введені, але типово ігноруються для маршрутизації, якщо не ввімкнено `channels.msteams.dangerouslyAllowNameMatching: true`. +- Під час запуску OpenClaw зіставляє імена team/channel і user allowlist з ID (коли дозволи Graph це дозволяють) + і журналює mapping; нерозв’язані імена team/channel зберігаються як введені, але типово ігноруються для routing, якщо не ввімкнено `channels.msteams.dangerouslyAllowNameMatching: true`. Приклад: @@ -205,25 +205,25 @@ teams app doctor
Ручне налаштування (без Teams CLI) -Якщо ви не можете використовувати Teams CLI, можете налаштувати бота вручну через Azure Portal. +Якщо ви не можете використовувати Teams CLI, можна налаштувати бота вручну через Azure Portal. ### Як це працює -1. Переконайтеся, що Microsoft Teams Plugin доступний (вбудований у поточні випуски). -2. Створіть **Azure Bot** (App ID + secret + tenant ID). +1. Переконайтеся, що Microsoft Teams plugin доступний (вбудований у поточних випусках). +2. Створіть **Azure Bot** (App ID + секрет + tenant ID). 3. Зберіть **пакет застосунку Teams**, який посилається на бота й містить дозволи RSC нижче. -4. Завантажте/встановіть застосунок Teams у команду (або personal scope для DM). -5. Налаштуйте `msteams` у `~/.openclaw/openclaw.json` (або env vars) і запустіть Gateway. -6. Gateway типово слухає трафік Bot Framework Webhook на `/api/messages`. +4. Завантажте/установіть застосунок Teams у команду (або personal scope для DM). +5. Налаштуйте `msteams` у `~/.openclaw/openclaw.json` (або env vars) і запустіть gateway. +6. Gateway типово прослуховує Webhook-трафік Bot Framework на `/api/messages`. ### Крок 1: Створіть Azure Bot -1. Перейдіть до [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) +1. Перейдіть до [Створити Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) 2. Заповніть вкладку **Basics**: | Поле | Значення | | ------------------ | -------------------------------------------------------- | - | **Bot handle** | Назва вашого бота, напр., `openclaw-msteams` (має бути унікальною) | + | **Bot handle** | Ім’я вашого бота, напр., `openclaw-msteams` (має бути унікальним) | | **Subscription** | Виберіть вашу підписку Azure | | **Resource group** | Створіть нову або використайте наявну | | **Pricing tier** | **Free** для розробки/тестування | @@ -247,9 +247,9 @@ teams app doctor ### Крок 3: Налаштуйте Messaging Endpoint 1. В Azure Bot → **Configuration** -2. Задайте **Messaging endpoint** як URL вашого Webhook: +2. Задайте **Messaging endpoint** як ваш Webhook URL: - Production: `https://your-domain.com/api/messages` - - Локальна розробка: використовуйте тунель (див. [Локальна розробка](#local-development-tunneling) нижче) + - Локальна розробка: використайте тунель (див. [Локальна розробка](#local-development-tunneling) нижче) ### Крок 4: Увімкніть канал Teams @@ -259,12 +259,12 @@ teams app doctor ### Крок 5: Зберіть маніфест застосунку Teams -- Додайте запис `bot` із `botId = `. +- Додайте запис `bot` з `botId = `. - Scopes: `personal`, `team`, `groupChat`. - `supportsFiles: true` (потрібно для обробки файлів у personal scope). - Додайте дозволи RSC (див. [Дозволи RSC](#current-teams-rsc-permissions-manifest)). - Створіть іконки: `outline.png` (32x32) і `color.png` (192x192). -- Запакуйте всі три файли разом у zip: `manifest.json`, `outline.png`, `color.png`. +- Запакуйте всі три файли разом: `manifest.json`, `outline.png`, `color.png`. ### Крок 6: Налаштуйте OpenClaw @@ -286,15 +286,15 @@ teams app doctor ### Крок 7: Запустіть Gateway -Канал Teams запускається автоматично, коли Plugin доступний і конфігурація `msteams` існує з обліковими даними. +Канал Teams запускається автоматично, коли plugin доступний і існує конфігурація `msteams` з обліковими даними.
-## Федеративна автентифікація (сертифікат плюс managed identity) +## Федеративна автентифікація (сертифікат плюс керована ідентичність) > Додано у 2026.4.11 -Для production-розгортань OpenClaw підтримує **федеративну автентифікацію** як безпечнішу альтернативу client secrets. Доступні два методи: +Для production-розгортань OpenClaw підтримує **федеративну автентифікацію** як безпечнішу альтернативу секретам клієнта. Доступні два методи: ### Варіант A: Автентифікація на основі сертифіката @@ -329,18 +329,18 @@ teams app doctor ### Варіант B: Azure Managed Identity -Використовуйте Azure Managed Identity для автентифікації без пароля. Це ідеально для розгортань в інфраструктурі Azure (AKS, App Service, Azure VMs), де доступна managed identity. +Використовуйте Azure Managed Identity для автентифікації без пароля. Це ідеально для розгортань на інфраструктурі Azure (AKS, App Service, Azure VMs), де доступна керована ідентичність. **Як це працює:** -1. Pod/VM бота має managed identity (system-assigned або user-assigned). -2. **Federated identity credential** пов’язує managed identity із реєстрацією застосунку Entra ID. -3. Під час виконання OpenClaw використовує `@azure/identity`, щоб отримувати токени з Azure IMDS endpoint (`169.254.169.254`). -4. Токен передається в Teams SDK для автентифікації бота. +1. Pod/VM бота має керовану ідентичність (system-assigned або user-assigned). +2. **Federated identity credential** пов’язує керовану ідентичність із реєстрацією застосунку Entra ID. +3. Під час виконання OpenClaw використовує `@azure/identity`, щоб отримати токени з endpoint Azure IMDS (`169.254.169.254`). +4. Токен передається до Teams SDK для автентифікації бота. **Передумови:** -- Інфраструктура Azure з увімкненою managed identity (AKS workload identity, App Service, VM) +- Інфраструктура Azure з увімкненою керованою ідентичністю (AKS workload identity, App Service, VM) - Federated identity credential, створений у реєстрації застосунку Entra ID - Мережевий доступ до IMDS (`169.254.169.254:80`) з pod/VM @@ -385,7 +385,7 @@ teams app doctor - `MSTEAMS_USE_MANAGED_IDENTITY=true` - `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=` (лише для призначеної користувачем) -### Налаштування ідентичності робочого навантаження AKS +### Налаштування AKS Workload Identity Для розгортань AKS, що використовують ідентичність робочого навантаження: @@ -401,7 +401,7 @@ teams app doctor }' ``` -3. **Додайте анотацію до сервісного облікового запису Kubernetes** з ID клієнта застосунку: +3. **Додайте анотацію до облікового запису служби Kubernetes** з клієнтським ID застосунку: ```yaml apiVersion: v1 @@ -412,7 +412,7 @@ teams app doctor azure.workload.identity/client-id: "" ``` -4. **Додайте мітку до пода** для інʼєкції ідентичності робочого навантаження: +4. **Додайте мітку до pod** для ін’єкції ідентичності робочого навантаження: ```yaml metadata: @@ -420,21 +420,21 @@ teams app doctor azure.workload.identity/use: "true" ``` -5. **Забезпечте мережевий доступ** до IMDS (`169.254.169.254`) — якщо використовується NetworkPolicy, додайте правило вихідного трафіку, яке дозволяє трафік до `169.254.169.254/32` на порті 80. +5. **Забезпечте мережевий доступ** до IMDS (`169.254.169.254`) — якщо використовуєте NetworkPolicy, додайте правило вихідного трафіку, яке дозволяє трафік до `169.254.169.254/32` на порту 80. ### Порівняння типів автентифікації -| Метод | Конфігурація | Переваги | Недоліки | -| ------------------------ | --------------------------------------------- | ------------------------------------- | --------------------------------------------- | -| **Секрет клієнта** | `appPassword` | Просте налаштування | Потрібна ротація секрету, менш безпечно | -| **Сертифікат** | `authType: "federated"` + `certificatePath` | Немає спільного секрету через мережу | Додаткове керування сертифікатами | -| **Керована ідентичність** | `authType: "federated"` + `useManagedIdentity` | Без пароля, не потрібно керувати секретами | Потрібна інфраструктура Azure | +| Метод | Конфігурація | Переваги | Недоліки | +| ------------------------ | --------------------------------------------- | ---------------------------------- | --------------------------------------------- | +| **Клієнтський секрет** | `appPassword` | Просте налаштування | Потрібна ротація секрету, менш безпечно | +| **Сертифікат** | `authType: "federated"` + `certificatePath` | Немає спільного секрету в мережі | Додаткове керування сертифікатами | +| **Керована ідентичність** | `authType: "federated"` + `useManagedIdentity` | Без паролів, без секретів для керування | Потрібна інфраструктура Azure | -**Поведінка за замовчуванням:** Коли `authType` не задано, OpenClaw за замовчуванням використовує автентифікацію через секрет клієнта. Наявні конфігурації продовжують працювати без змін. +**Типова поведінка:** Коли `authType` не задано, OpenClaw типово використовує автентифікацію клієнтським секретом. Наявні конфігурації продовжують працювати без змін. ## Локальна розробка (тунелювання) -Teams не може звертатися до `localhost`. Використовуйте постійний dev-тунель, щоб ваша URL-адреса залишалася однаковою між сеансами: +Teams не може звертатися до `localhost`. Використовуйте постійний тунель для розробки, щоб ваша URL-адреса залишалася однаковою між сеансами: ```bash # One-time setup: @@ -447,7 +447,7 @@ devtunnel host my-openclaw-bot Альтернативи: `ngrok http 3978` або `tailscale funnel 3978` (URL-адреси можуть змінюватися в кожному сеансі). -Якщо URL-адреса вашого тунелю зміниться, оновіть кінцеву точку: +Якщо URL-адреса вашого тунелю змінюється, оновіть кінцеву точку: ```bash teams app update --endpoint "https:///api/messages" @@ -466,45 +466,45 @@ teams app doctor **Надішліть тестове повідомлення:** 1. Установіть застосунок Teams (скористайтеся посиланням для встановлення з `teams app get --install-link`) -2. Знайдіть бота в Teams і надішліть йому DM -3. Перевірте журнали Gateway на наявність вхідної активності +2. Знайдіть бота в Teams і надішліть особисте повідомлення +3. Перевірте журнали gateway на наявність вхідної активності ## Змінні середовища -Усі ключі конфігурації натомість можна задавати через змінні середовища: +Натомість усі ключі конфігурації можна задати через змінні середовища: - `MSTEAMS_APP_ID` - `MSTEAMS_APP_PASSWORD` - `MSTEAMS_TENANT_ID` -- `MSTEAMS_AUTH_TYPE` (необовʼязково: `"secret"` або `"federated"`) +- `MSTEAMS_AUTH_TYPE` (необов’язково: `"secret"` або `"federated"`) - `MSTEAMS_CERTIFICATE_PATH` (федеративна автентифікація + сертифікат) -- `MSTEAMS_CERTIFICATE_THUMBPRINT` (необовʼязково, не потрібно для автентифікації) +- `MSTEAMS_CERTIFICATE_THUMBPRINT` (необов’язково, не потрібен для автентифікації) - `MSTEAMS_USE_MANAGED_IDENTITY` (федеративна автентифікація + керована ідентичність) -- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (лише призначена користувачем керована ідентичність) +- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (лише призначена користувачем MI) -## Дія з інформацією про учасника +## Дія відомостей про учасника -OpenClaw надає дію `member-info` на основі Graph для Microsoft Teams, щоб агенти й автоматизації могли отримувати відомості про учасників каналу (відображуване імʼя, електронна пошта, роль) безпосередньо з Microsoft Graph. +OpenClaw надає дію `member-info` на базі Graph для Microsoft Teams, щоб агенти й автоматизації могли отримувати дані про учасників каналу (відображуване ім’я, електронну пошту, роль) безпосередньо з Microsoft Graph. Вимоги: - Дозвіл RSC `Member.Read.Group` (уже є в рекомендованому маніфесті) -- Для пошуку між командами: дозвіл Graph Application `User.Read.All` зі згодою адміністратора +- Для пошуку між командами: дозвіл застосунку Graph `User.Read.All` зі згодою адміністратора -Дія керується параметром `channels.msteams.actions.memberInfo` (за замовчуванням: увімкнено, коли доступні облікові дані Graph). +Дія керується параметром `channels.msteams.actions.memberInfo` (типово: увімкнено, коли доступні облікові дані Graph). ## Контекст історії -- `channels.msteams.historyLimit` керує тим, скільки останніх повідомлень каналу/групи загортається в запит. -- Має резервне значення `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути (за замовчуванням 50). -- Отримана історія треду фільтрується за списками дозволених відправників (`allowFrom` / `groupAllowFrom`), тому початкове наповнення контексту треду містить лише повідомлення від дозволених відправників. -- Контекст цитованих вкладень (отриманий із HTML-відповіді Teams `ReplyTo*`) наразі передається як отримано. -- Іншими словами, списки дозволених визначають, хто може запускати агента; сьогодні фільтруються лише окремі шляхи додаткового контексту. -- Історію DM можна обмежити за допомогою `channels.msteams.dmHistoryLimit` (ходи користувача). Перевизначення для окремих користувачів: `channels.msteams.dms[""].historyLimit`. +- `channels.msteams.historyLimit` контролює, скільки останніх повідомлень каналу/групи загортається в підказку. +- Використовує резервне значення `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути (типово 50). +- Отримана історія треду фільтрується за списками дозволених відправників (`allowFrom` / `groupAllowFrom`), тому заповнення контексту треду включає лише повідомлення від дозволених відправників. +- Контекст цитованих вкладень (`ReplyTo*`, отриманий із HTML-відповіді Teams) наразі передається в отриманому вигляді. +- Іншими словами, списки дозволів визначають, хто може запускати агента; сьогодні фільтруються лише окремі додаткові шляхи контексту. +- Історію особистих повідомлень можна обмежити за допомогою `channels.msteams.dmHistoryLimit` (ходи користувача). Перевизначення для окремих користувачів: `channels.msteams.dms[""].historyLimit`. -## Поточні дозволи RSC Teams (маніфест) +## Поточні дозволи Teams RSC (маніфест) -Це **наявні ресурсно-специфічні дозволи** в маніфесті нашого застосунку Teams. Вони застосовуються лише всередині команди/чату, де встановлено застосунок. +Це **наявні resourceSpecific дозволи** в нашому маніфесті застосунку Teams. Вони застосовуються лише всередині команди/чату, де встановлено застосунок. **Для каналів (область команди):** @@ -526,9 +526,9 @@ OpenClaw надає дію `member-info` на основі Graph для Microsof teams app rsc add ChannelMessage.Read.Group --type Application ``` -## Приклад маніфесту Teams (відредаговано) +## Приклад маніфесту Teams (редаговано) -Мінімальний, чинний приклад із потрібними полями. Замініть ID та URL-адреси. +Мінімальний коректний приклад із потрібними полями. Замініть ID та URL-адреси. ```json5 { @@ -576,13 +576,13 @@ teams app rsc add ChannelMessage.Read.Group --type Application } ``` -### Застереження щодо маніфесту (обовʼязкові поля) +### Застереження щодо маніфесту (обов’язкові поля) - `bots[].botId` **має** збігатися з Azure Bot App ID. - `webApplicationInfo.id` **має** збігатися з Azure Bot App ID. - `bots[].scopes` має включати поверхні, які ви плануєте використовувати (`personal`, `team`, `groupChat`). - `bots[].supportsFiles: true` потрібен для обробки файлів в особистій області. -- `authorization.permissions.resourceSpecific` має включати читання/надсилання для каналів, якщо вам потрібен трафік каналів. +- `authorization.permissions.resourceSpecific` має включати читання/надсилання для каналу, якщо ви хочете трафік каналу. ### Оновлення наявного застосунку @@ -596,37 +596,37 @@ teams app manifest upload manifest.json # Version is auto-bumped if content changed ``` -Після оновлення перевстановіть застосунок у кожній команді, щоб нові дозволи набули чинності, і **повністю закрийте та перезапустіть Teams** (не просто закрийте вікно), щоб очистити кешовані метадані застосунку. +Після оновлення перевстановіть застосунок у кожній команді, щоб нові дозволи набрали чинності, і **повністю закрийте та перезапустіть Teams** (не просто закрийте вікно), щоб очистити кешовані метадані застосунку.
Ручне оновлення маніфесту (без CLI) 1. Оновіть ваш `manifest.json` новими налаштуваннями 2. **Збільште поле `version`** (наприклад, `1.0.0` → `1.1.0`) -3. **Заново запакуйте в zip** маніфест з іконками (`manifest.json`, `outline.png`, `color.png`) +3. **Повторно запакуйте в zip** маніфест з іконками (`manifest.json`, `outline.png`, `color.png`) 4. Завантажте новий zip: - - **Teams Admin Center:** застосунки Teams → Керування застосунками → знайдіть ваш застосунок → Завантажити нову версію + - **Teams Admin Center:** застосунки Teams → Керування застосунками → знайдіть свій застосунок → Завантажити нову версію - **Sideload:** у Teams → Застосунки → Керування вашими застосунками → Завантажити власний застосунок
## Можливості: лише RSC проти Graph -### З **лише Teams RSC** (застосунок установлено, дозволів Graph API немає) +### З **лише Teams RSC** (застосунок установлено, без дозволів Graph API) Працює: - Читання **текстового** вмісту повідомлень каналу. - Надсилання **текстового** вмісту повідомлень каналу. -- Отримання файлових вкладень **особистих (DM)** повідомлень. +- Отримання файлових вкладень **особистих повідомлень**. Не працює: -- **Вміст зображень або файлів** у каналі/групі (корисне навантаження містить лише HTML-заглушку). +- **Зображення або вміст файлів** у каналах/групах (payload містить лише HTML-заглушку). - Завантаження вкладень, збережених у SharePoint/OneDrive. -- Читання історії повідомлень (поза межами події live Webhook). +- Читання історії повідомлень (поза подією live webhook). -### З **Teams RSC + дозволами Microsoft Graph Application** +### З **Teams RSC + дозволами застосунку Microsoft Graph** Додає: @@ -636,82 +636,82 @@ teams app manifest upload manifest.json ### RSC проти Graph API -| Можливість | Дозволи RSC | Graph API | -| --------------------------- | ------------------- | ------------------------------------------ | -| **Повідомлення в реальному часі** | Так (через Webhook) | Ні (лише опитування) | -| **Історичні повідомлення** | Ні | Так (можна запитувати історію) | -| **Складність налаштування** | Лише маніфест застосунку | Потрібна згода адміністратора + потік токенів | -| **Працює офлайн** | Ні (має бути запущено) | Так (запит у будь-який час) | +| Можливість | Дозволи RSC | Graph API | +| ------------------------------- | --------------------- | ---------------------------------------- | +| **Повідомлення в реальному часі** | Так (через webhook) | Ні (лише опитування) | +| **Історичні повідомлення** | Ні | Так (можна запитувати історію) | +| **Складність налаштування** | Лише маніфест застосунку | Потрібна згода адміністратора + потік токенів | +| **Працює офлайн** | Ні (має бути запущено) | Так (запит у будь-який час) | -**Підсумок:** RSC призначено для прослуховування в реальному часі; Graph API — для доступу до історії. Щоб наздоганяти пропущені повідомлення під час офлайну, потрібен Graph API з `ChannelMessage.Read.All` (потрібна згода адміністратора). +**Підсумок:** RSC призначений для прослуховування в реальному часі; Graph API — для історичного доступу. Щоб наздогнати пропущені повідомлення під час офлайну, потрібен Graph API з `ChannelMessage.Read.All` (потрібна згода адміністратора). -## Медіа та історія з увімкненим Graph (потрібно для каналів) +## Медіа та історія з Graph (потрібно для каналів) Якщо вам потрібні зображення/файли в **каналах** або ви хочете отримувати **історію повідомлень**, потрібно ввімкнути дозволи Microsoft Graph і надати згоду адміністратора. -1. В **реєстрації застосунку** Entra ID (Azure AD) додайте **дозволи Application** Microsoft Graph: +1. В **App Registration** Entra ID (Azure AD) додайте **дозволи застосунку** Microsoft Graph: - `ChannelMessage.Read.All` (вкладення каналу + історія) - `Chat.Read.All` або `ChatMessage.Read.All` (групові чати) -2. **Надайте згоду адміністратора** для клієнта. -3. Підвищте **версію маніфесту** застосунку Teams, повторно завантажте його та **перевстановіть застосунок у Teams**. +2. **Надайте згоду адміністратора** для tenant. +3. Збільште **версію маніфесту** застосунку Teams, повторно завантажте його та **перевстановіть застосунок у Teams**. 4. **Повністю закрийте та перезапустіть Teams**, щоб очистити кешовані метадані застосунку. -**Додатковий дозвіл для згадок користувачів:** @згадки користувачів працюють одразу для користувачів у розмові. Однак, якщо ви хочете динамічно шукати й згадувати користувачів, яких **немає в поточній розмові**, додайте дозвіл `User.Read.All` (Application) і надайте згоду адміністратора. +**Додатковий дозвіл для згадок користувачів:** @згадки користувачів працюють одразу для користувачів у розмові. Однак, якщо ви хочете динамічно шукати та згадувати користувачів, які **не перебувають у поточній розмові**, додайте дозвіл `User.Read.All` (Application) і надайте згоду адміністратора. ## Відомі обмеження -### Тайм-аути Webhook +### Тайм-аути webhook -Teams доставляє повідомлення через HTTP Webhook. Якщо обробка триває надто довго (наприклад, повільні відповіді LLM), ви можете побачити: +Teams доставляє повідомлення через HTTP webhook. Якщо обробка триває надто довго (наприклад, повільні відповіді LLM), ви можете побачити: -- Тайм-аути Gateway -- Повторні спроби Teams надіслати повідомлення (що спричиняє дублікати) -- Відкинуті відповіді +- Тайм-аути gateway +- Повторне надсилання повідомлення Teams (що спричиняє дублікати) +- Втрачені відповіді -OpenClaw обробляє це, швидко повертаючи відповідь і проактивно надсилаючи повідомлення, але дуже повільні відповіді все одно можуть спричиняти проблеми. +OpenClaw обробляє це, швидко повертаючи відповідь і проактивно надсилаючи відповіді, але дуже повільні відповіді все одно можуть спричиняти проблеми. ### Форматування -Markdown у Teams обмеженіший, ніж у Slack або Discord: +Markdown Teams обмеженіший, ніж у Slack або Discord: - Базове форматування працює: **жирний**, _курсив_, `code`, посилання -- Складний markdown (таблиці, вкладені списки) може відображатися некоректно -- Adaptive Cards підтримуються для опитувань і семантичних presentation-відправлень (див. нижче) +- Складний Markdown (таблиці, вкладені списки) може відображатися некоректно +- Adaptive Cards підтримуються для опитувань і надсилань семантичних презентацій (див. нижче) ## Конфігурація -Ключові налаштування (див. `/gateway/configuration` для спільних патернів каналів): +Ключові налаштування (див. `/gateway/configuration` для спільних шаблонів каналів): - `channels.msteams.enabled`: увімкнути/вимкнути канал. - `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: облікові дані бота. - `channels.msteams.webhook.port` (типово `3978`) - `channels.msteams.webhook.path` (типово `/api/messages`) - `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (типово: pairing) -- `channels.msteams.allowFrom`: allowlist для DM (рекомендовано AAD object IDs). Майстер зіставляє імена з ID під час налаштування, коли доступний доступ до Graph. -- `channels.msteams.dangerouslyAllowNameMatching`: аварійний перемикач для повторного ввімкнення зіставлення за змінними UPN/display-name і прямої маршрутизації за назвою команди/каналу. +- `channels.msteams.allowFrom`: allowlist для DM (рекомендовано AAD object IDs). Майстер під час налаштування перетворює імена на ID, коли доступ до Graph доступний. +- `channels.msteams.dangerouslyAllowNameMatching`: аварійний перемикач для повторного ввімкнення змінного зіставлення UPN/display-name і прямої маршрутизації за назвою команди/каналу. - `channels.msteams.textChunkLimit`: розмір фрагмента вихідного тексту. -- `channels.msteams.chunkMode`: `length` (типово) або `newline`, щоб ділити за порожніми рядками (межами абзаців) перед поділом за довжиною. +- `channels.msteams.chunkMode`: `length` (типово) або `newline`, щоб розбивати за порожніми рядками (межами абзаців) перед розбиттям за довжиною. - `channels.msteams.mediaAllowHosts`: allowlist для хостів вхідних вкладень (типово домени Microsoft/Teams). -- `channels.msteams.mediaAuthAllowHosts`: allowlist для додавання заголовків Authorization під час повторних спроб роботи з медіа (типово хости Graph + Bot Framework). +- `channels.msteams.mediaAuthAllowHosts`: allowlist для додавання заголовків Authorization під час повторних спроб отримання медіа (типово хости Graph + Bot Framework). - `channels.msteams.requireMention`: вимагати @mention у каналах/групах (типово true). - `channels.msteams.replyStyle`: `thread | top-level` (див. [Стиль відповіді](#reply-style-threads-vs-posts)). - `channels.msteams.teams..replyStyle`: перевизначення для окремої команди. - `channels.msteams.teams..requireMention`: перевизначення для окремої команди. -- `channels.msteams.teams..tools`: стандартні перевизначення політики інструментів для окремої команди (`allow`/`deny`/`alsoAllow`), що використовуються, коли немає перевизначення для каналу. -- `channels.msteams.teams..toolsBySender`: стандартні перевизначення політики інструментів для окремої команди й окремого відправника (підтримується wildcard `"*"`). +- `channels.msteams.teams..tools`: типові перевизначення політики інструментів для окремої команди (`allow`/`deny`/`alsoAllow`), які використовуються, коли перевизначення каналу відсутнє. +- `channels.msteams.teams..toolsBySender`: типові перевизначення політики інструментів для окремої команди й відправника (підтримується wildcard `"*"`). - `channels.msteams.teams..channels..replyStyle`: перевизначення для окремого каналу. - `channels.msteams.teams..channels..requireMention`: перевизначення для окремого каналу. - `channels.msteams.teams..channels..tools`: перевизначення політики інструментів для окремого каналу (`allow`/`deny`/`alsoAllow`). -- `channels.msteams.teams..channels..toolsBySender`: перевизначення політики інструментів для окремого каналу й окремого відправника (підтримується wildcard `"*"`). +- `channels.msteams.teams..channels..toolsBySender`: перевизначення політики інструментів для окремого каналу й відправника (підтримується wildcard `"*"`). - Ключі `toolsBySender` мають використовувати явні префікси: - `id:`, `e164:`, `username:`, `name:` (застарілі ключі без префікса все ще зіставляються лише з `id:`). -- `channels.msteams.actions.memberInfo`: увімкнути або вимкнути дію отримання інформації про учасника на основі Graph (типово: увімкнено, коли доступні облікові дані Graph). + `id:`, `e164:`, `username:`, `name:` (застарілі ключі без префікса й надалі зіставляються лише з `id:`). +- `channels.msteams.actions.memberInfo`: увімкнути або вимкнути дію отримання інформації про учасника на основі Graph (типово: увімкнено, коли облікові дані Graph доступні). - `channels.msteams.authType`: тип автентифікації — `"secret"` (типово) або `"federated"`. -- `channels.msteams.certificatePath`: шлях до PEM-файлу сертифіката (федеративна автентифікація + автентифікація сертифікатом). -- `channels.msteams.certificateThumbprint`: відбиток сертифіката (необов’язково, не потрібно для автентифікації). -- `channels.msteams.useManagedIdentity`: увімкнути автентифікацію managed identity (федеративний режим). -- `channels.msteams.managedIdentityClientId`: client ID для призначеної користувачем managed identity. -- `channels.msteams.sharePointSiteId`: SharePoint site ID для завантаження файлів у групових чатах/каналах (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). +- `channels.msteams.certificatePath`: шлях до файлу PEM-сертифіката (federated + автентифікація сертифікатом). +- `channels.msteams.certificateThumbprint`: відбиток сертифіката (необов’язково, не потрібен для автентифікації). +- `channels.msteams.useManagedIdentity`: увімкнути автентифікацію керованою ідентичністю (режим federated). +- `channels.msteams.managedIdentityClientId`: client ID для керованої ідентичності, призначеної користувачем. +- `channels.msteams.sharePointSiteId`: ID сайту SharePoint для завантаження файлів у групових чатах/каналах (див. [Надсилання файлів у групових чатах](#sending-files-in-group-chats)). ## Маршрутизація та сесії @@ -721,21 +721,21 @@ Markdown у Teams обмеженіший, ніж у Slack або Discord: - `agent::msteams:channel:` - `agent::msteams:group:` -## Стиль відповіді: треди проти дописів +## Стиль відповіді: потоки проти дописів -Teams нещодавно запровадив два стилі UI каналу поверх тієї самої базової моделі даних: +Teams нещодавно запровадив два стилі інтерфейсу каналів поверх тієї самої базової моделі даних: | Стиль | Опис | Рекомендований `replyStyle` | | ------------------------ | --------------------------------------------------------- | ------------------------ | -| **Posts** (класичний) | Повідомлення відображаються як картки з тредовими відповідями під ними | `thread` (типово) | -| **Threads** (як у Slack) | Повідомлення йдуть лінійно, більше схоже на Slack | `top-level` | +| **Дописи** (класичний) | Повідомлення відображаються як картки з відповідями в потоці під ними | `thread` (типово) | +| **Потоки** (як у Slack) | Повідомлення йдуть лінійно, більше схоже на Slack | `top-level` | -**Проблема:** Teams API не показує, який стиль UI використовує канал. Якщо використати неправильний `replyStyle`: +**Проблема:** Teams API не показує, який стиль інтерфейсу використовує канал. Якщо використати неправильний `replyStyle`: -- `thread` у каналі стилю Threads → відповіді виглядають незручно вкладеними -- `top-level` у каналі стилю Posts → відповіді відображаються як окремі дописи верхнього рівня, а не всередині треду +- `thread` у каналі зі стилем Threads → відповіді виглядають незручно вкладеними +- `top-level` у каналі зі стилем Posts → відповіді виглядають як окремі дописи верхнього рівня замість відповідей у потоці -**Рішення:** Налаштуйте `replyStyle` для кожного каналу залежно від того, як налаштовано канал: +**Рішення:** Налаштуйте `replyStyle` для кожного каналу відповідно до того, як налаштовано канал: ```json5 { @@ -760,37 +760,37 @@ Teams нещодавно запровадив два стилі UI каналу **Поточні обмеження:** -- **DM:** Зображення й файлові вкладення працюють через файлові API бота Teams. -- **Канали/групи:** Вкладення зберігаються в сховищі M365 (SharePoint/OneDrive). Webhook payload містить лише HTML-заглушку, а не фактичні байти файлу. **Для завантаження вкладень каналів потрібні дозволи Graph API**. -- Для явних надсилань, де файл є основним вмістом, використовуйте `action=upload-file` з `media` / `filePath` / `path`; необов’язковий `message` стає супровідним текстом/коментарем, а `filename` перевизначає назву завантаженого файлу. +- **DMs:** Зображення й файлові вкладення працюють через файлові API бота Teams. +- **Канали/групи:** Вкладення зберігаються в сховищі M365 (SharePoint/OneDrive). Корисне навантаження Webhook містить лише HTML-заглушку, а не фактичні байти файлу. **Дозволи Graph API обов’язкові** для завантаження вкладень каналу. +- Для явного надсилання, де файл є основним, використовуйте `action=upload-file` з `media` / `filePath` / `path`; необов’язковий `message` стає супровідним текстом/коментарем, а `filename` перевизначає завантажену назву. -Без дозволів Graph повідомлення каналів із зображеннями надходитимуть лише як текст (вміст зображення недоступний боту). -Типово OpenClaw завантажує медіа лише з імен хостів Microsoft/Teams. Перевизначте це за допомогою `channels.msteams.mediaAllowHosts` (використовуйте `["*"]`, щоб дозволити будь-який хост). -Заголовки Authorization додаються лише для хостів у `channels.msteams.mediaAuthAllowHosts` (типово хости Graph + Bot Framework). Тримайте цей список суворим (уникайте багатотенантних суфіксів). +Без дозволів Graph повідомлення каналу із зображеннями отримуватимуться лише як текст (вміст зображення недоступний боту). +Типово OpenClaw завантажує медіа лише з імен хостів Microsoft/Teams. Перевизначте через `channels.msteams.mediaAllowHosts` (використовуйте `["*"]`, щоб дозволити будь-який хост). +Заголовки Authorization додаються лише для хостів у `channels.msteams.mediaAuthAllowHosts` (типово хости Graph + Bot Framework). Тримайте цей список суворим (уникайте суфіксів для кількох орендарів). ## Надсилання файлів у групових чатах -Боти можуть надсилати файли в DM за допомогою потоку FileConsentCard (вбудовано). Однак **надсилання файлів у групових чатах/каналах** потребує додаткового налаштування: +Боти можуть надсилати файли в DMs за допомогою потоку FileConsentCard (вбудовано). Однак **надсилання файлів у групових чатах/каналах** потребує додаткового налаштування: | Контекст | Як надсилаються файли | Потрібне налаштування | | ------------------------ | -------------------------------------------- | ----------------------------------------------- | -| **DM** | FileConsentCard → користувач приймає → бот завантажує | Працює одразу | +| **DMs** | FileConsentCard → користувач приймає → бот завантажує | Працює без додаткового налаштування | | **Групові чати/канали** | Завантаження в SharePoint → поширення посилання | Потрібні `sharePointSiteId` + дозволи Graph | -| **Зображення (будь-який контекст)** | Вбудовано з кодуванням Base64 | Працює одразу | +| **Зображення (будь-який контекст)** | Вбудовано з кодуванням Base64 | Працює без додаткового налаштування | ### Чому груповим чатам потрібен SharePoint -Боти не мають особистого диска OneDrive (endpoint Graph API `/me/drive` не працює для ідентичностей застосунків). Щоб надсилати файли в групові чати/канали, бот завантажує їх на **сайт SharePoint** і створює посилання для поширення. +Боти не мають особистого диска OneDrive (кінцева точка Graph API `/me/drive` не працює для ідентичностей застосунків). Щоб надсилати файли в групових чатах/каналах, бот завантажує їх на **сайт SharePoint** і створює посилання для спільного доступу. ### Налаштування 1. **Додайте дозволи Graph API** в Entra ID (Azure AD) → App Registration: - `Sites.ReadWrite.All` (Application) - завантаження файлів у SharePoint - - `Chat.Read.All` (Application) - необов’язково, вмикає посилання для поширення для окремих користувачів + - `Chat.Read.All` (Application) - необов’язково, вмикає посилання для спільного доступу для окремих користувачів -2. **Надайте згоду адміністратора** для tenant. +2. **Надайте згоду адміністратора** для орендаря. -3. **Отримайте свій SharePoint site ID:** +3. **Отримайте ID вашого сайту SharePoint:** ```bash # Via Graph Explorer or curl with a valid token: @@ -817,42 +817,42 @@ Teams нещодавно запровадив два стилі UI каналу } ``` -### Поведінка поширення +### Поведінка спільного доступу -| Дозвіл | Поведінка поширення | +| Дозвіл | Поведінка спільного доступу | | --------------------------------------- | --------------------------------------------------------- | -| лише `Sites.ReadWrite.All` | Посилання для поширення на всю організацію (доступ має будь-хто в організації) | -| `Sites.ReadWrite.All` + `Chat.Read.All` | Посилання для поширення для окремих користувачів (доступ мають лише учасники чату) | +| Лише `Sites.ReadWrite.All` | Посилання для спільного доступу в межах організації (доступ має будь-хто в організації) | +| `Sites.ReadWrite.All` + `Chat.Read.All` | Посилання для спільного доступу для окремих користувачів (доступ мають лише учасники чату) | -Поширення для окремих користувачів безпечніше, оскільки доступ до файлу мають лише учасники чату. Якщо дозволу `Chat.Read.All` бракує, бот повертається до поширення на всю організацію. +Спільний доступ для окремих користувачів безпечніший, оскільки лише учасники чату можуть отримати доступ до файлу. Якщо дозвіл `Chat.Read.All` відсутній, бот повертається до спільного доступу в межах організації. ### Резервна поведінка | Сценарій | Результат | | ------------------------------------------------- | -------------------------------------------------- | -| Груповий чат + файл + налаштовано `sharePointSiteId` | Завантаження в SharePoint, надсилання посилання для поширення | -| Груповий чат + файл + немає `sharePointSiteId` | Спроба завантаження в OneDrive (може завершитися помилкою), надсилання лише тексту | +| Груповий чат + файл + налаштований `sharePointSiteId` | Завантаження в SharePoint, надсилання посилання для спільного доступу | +| Груповий чат + файл + немає `sharePointSiteId` | Спроба завантаження в OneDrive (може не вдатися), надсилання лише тексту | | Особистий чат + файл | Потік FileConsentCard (працює без SharePoint) | | Будь-який контекст + зображення | Вбудовано з кодуванням Base64 (працює без SharePoint) | -### Розташування збережених файлів +### Місце зберігання файлів Завантажені файли зберігаються в папці `/OpenClawShared/` у стандартній бібліотеці документів налаштованого сайту SharePoint. ## Опитування (Adaptive Cards) -OpenClaw надсилає опитування Teams як Adaptive Cards (нативного API опитувань Teams немає). +OpenClaw надсилає опитування Teams як Adaptive Cards (нативного Teams poll API немає). - CLI: `openclaw message poll --channel msteams --target conversation: ...` - Голоси записуються Gateway у `~/.openclaw/msteams-polls.json`. - Gateway має залишатися онлайн, щоб записувати голоси. - Опитування поки що не публікують автоматично підсумки результатів (за потреби перегляньте файл сховища). -## Presentation-картки +## Картки презентацій -Надсилайте семантичні presentation payloads користувачам або conversations Teams за допомогою інструмента `message` або CLI. OpenClaw рендерить їх як Teams Adaptive Cards із загального presentation-контракту. +Надсилайте семантичні презентаційні payload до користувачів або розмов Teams за допомогою інструмента `message` або CLI. OpenClaw відображає їх як Teams Adaptive Cards із загального контракту презентацій. -Параметр `presentation` приймає семантичні блоки. Коли надано `presentation`, текст повідомлення необов’язковий. +Параметр `presentation` приймає семантичні блоки. Коли `presentation` надано, текст повідомлення необов’язковий. **Інструмент агента:** @@ -876,13 +876,13 @@ openclaw message send --channel msteams \ --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}' ``` -Докладніше про формат target див. у розділі [Формати target](#target-formats) нижче. +Докладніше про формат цілі див. [Формати цілей](#target-formats) нижче. -## Формати target +## Формати цілей -Targets MSTeams використовують префікси, щоб розрізняти користувачів і conversations: +Цілі MSTeams використовують префікси, щоб розрізняти користувачів і розмови: -| Тип target | Формат | Приклад | +| Тип цілі | Формат | Приклад | | ------------------- | -------------------------------- | --------------------------------------------------- | | Користувач (за ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | | Користувач (за іменем) | `user:` | `user:John Smith` (потрібен Graph API) | @@ -935,19 +935,19 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. ## Проактивні повідомлення -- Проактивні повідомлення можливі лише **після** взаємодії користувача, оскільки в цей момент ми зберігаємо посилання на розмову. -- Див. `/gateway/configuration` для `dmPolicy` і керування allowlist. +- Проактивні повідомлення можливі лише **після** взаємодії користувача, оскільки саме тоді ми зберігаємо посилання на розмову. +- Див. `/gateway/configuration` для `dmPolicy` та обмеження через список дозволених. -## ID команди та каналу (поширена помилка) +## Ідентифікатори команд і каналів (поширена помилка) -Параметр запиту `groupId` в URL Teams **НЕ** є ID команди, що використовується для конфігурації. Натомість витягуйте ID зі шляху URL: +Параметр запиту `groupId` в URL Teams **НЕ** є ідентифікатором команди, який використовується для конфігурації. Натомість витягайте ідентифікатори зі шляху URL: **URL команди:** ``` https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... └────────────────────────────┘ - ID розмови команди (URL-декодуйте це) + Ідентифікатор розмови команди (URL-декодуйте його) ``` **URL каналу:** @@ -955,62 +955,62 @@ https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?gro ``` https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... └─────────────────────────┘ - ID каналу (URL-декодуйте це) + Ідентифікатор каналу (URL-декодуйте його) ``` **Для конфігурації:** -- Ключ команди = сегмент шляху після `/team/` (URL-декодований, напр., `19:Bk4j...@thread.tacv2`; старіші тенанти можуть показувати `@thread.skype`, що також є чинним) +- Ключ команди = сегмент шляху після `/team/` (URL-декодований, наприклад `19:Bk4j...@thread.tacv2`; старіші клієнти можуть показувати `@thread.skype`, що також є коректним) - Ключ каналу = сегмент шляху після `/channel/` (URL-декодований) -- **Ігноруйте** параметр запиту `groupId` для маршрутизації OpenClaw. Це ID групи Microsoft Entra, а не ID розмови Bot Framework, що використовується у вхідних активностях Teams. +- **Ігноруйте** параметр запиту `groupId` для маршрутизації OpenClaw. Це ідентифікатор групи Microsoft Entra, а не ідентифікатор розмови Bot Framework, який використовується у вхідних діях Teams. ## Приватні канали -Боти мають обмежену підтримку в приватних каналах: +Боти мають обмежену підтримку приватних каналів: -| Функція | Стандартні канали | Приватні канали | -| ----------------------------- | ----------------- | ---------------------------- | -| Встановлення бота | Так | Обмежено | -| Повідомлення в реальному часі (Webhook) | Так | Може не працювати | -| Дозволи RSC | Так | Можуть поводитися інакше | -| @mentions | Так | Якщо бот доступний | -| Історія Graph API | Так | Так (з дозволами) | +| Функція | Стандартні канали | Приватні канали | +| ---------------------------- | ----------------- | ---------------------- | +| Встановлення бота | Так | Обмежено | +| Повідомлення в реальному часі (webhook) | Так | Може не працювати | +| Дозволи RSC | Так | Можуть поводитися інакше | +| @згадки | Так | Якщо бот доступний | +| Історія Graph API | Так | Так (з дозволами) | **Обхідні варіанти, якщо приватні канали не працюють:** 1. Використовуйте стандартні канали для взаємодії з ботом -2. Використовуйте приватні повідомлення - користувачі завжди можуть написати боту напряму +2. Використовуйте особисті повідомлення - користувачі завжди можуть написати боту напряму 3. Використовуйте Graph API для доступу до історії (потрібен `ChannelMessage.Read.All`) -## Усунення неполадок +## Усунення несправностей ### Поширені проблеми - **Зображення не відображаються в каналах:** відсутні дозволи Graph або згода адміністратора. Перевстановіть застосунок Teams і повністю закрийте та знову відкрийте Teams. -- **Немає відповідей у каналі:** згадки потрібні за замовчуванням; задайте `channels.msteams.requireMention=false` або налаштуйте для конкретної команди/каналу. -- **Невідповідність версії (Teams досі показує старий маніфест):** видаліть і повторно додайте застосунок, а також повністю закрийте Teams для оновлення. -- **401 Unauthorized від Webhook:** очікувано під час ручного тестування без Azure JWT - це означає, що endpoint доступний, але автентифікація не пройшла. Використовуйте Azure Web Chat для коректного тестування. +- **Немає відповідей у каналі:** згадки потрібні за замовчуванням; встановіть `channels.msteams.requireMention=false` або налаштуйте для окремої команди/каналу. +- **Невідповідність версій (Teams досі показує старий маніфест):** видаліть і знову додайте застосунок, а також повністю закрийте Teams для оновлення. +- **401 Unauthorized від webhook:** очікувано під час ручного тестування без Azure JWT - це означає, що endpoint доступний, але автентифікація не пройшла. Використовуйте Azure Web Chat для коректного тестування. ### Помилки завантаження маніфесту - **"Icon file cannot be empty":** маніфест посилається на файли іконок розміром 0 байтів. Створіть коректні PNG-іконки (32x32 для `outline.png`, 192x192 для `color.png`). -- **"webApplicationInfo.Id already in use":** застосунок досі встановлений в іншій команді/чаті. Спершу знайдіть і видаліть його або зачекайте 5-10 хвилин на поширення змін. -- **"Something went wrong" під час завантаження:** натомість завантажте через [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), відкрийте DevTools браузера (F12) → вкладку Network і перевірте тіло відповіді на фактичну помилку. -- **Sideload не вдається:** спробуйте "Upload an app to your org's app catalog" замість "Upload a custom app" - це часто обходить обмеження sideload. +- **"webApplicationInfo.Id already in use":** застосунок досі встановлено в іншій команді/чаті. Спершу знайдіть і видаліть його або зачекайте 5-10 хвилин на поширення змін. +- **"Something went wrong" під час завантаження:** натомість завантажте через [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), відкрийте DevTools браузера (F12) → вкладку Network і перевірте тіло відповіді, щоб побачити фактичну помилку. +- **Помилка sideload:** спробуйте "Upload an app to your org's app catalog" замість "Upload a custom app" - це часто обходить обмеження sideload. ### Дозволи RSC не працюють -1. Переконайтеся, що `webApplicationInfo.id` точно збігається з App ID вашого бота +1. Перевірте, що `webApplicationInfo.id` точно збігається з App ID вашого бота 2. Повторно завантажте застосунок і перевстановіть його в команді/чаті 3. Перевірте, чи адміністратор вашої організації не заблокував дозволи RSC -4. Підтвердьте, що використовуєте правильний scope: `ChannelMessage.Read.Group` для команд, `ChatMessage.Read.Chat` для групових чатів +4. Підтвердьте, що ви використовуєте правильну область: `ChannelMessage.Read.Group` для команд, `ChatMessage.Read.Chat` для групових чатів ## Посилання - [Створення Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - посібник із налаштування Azure Bot -- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - створення й керування застосунками Teams +- [Портал розробника Teams](https://dev.teams.microsoft.com/apps) - створення й керування застосунками Teams - [Схема маніфесту застосунку Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) -- [Отримання повідомлень каналу з RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) +- [Отримання повідомлень каналів за допомогою RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) - [Довідник дозволів RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) - [Обробка файлів ботом Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (для каналу/групи потрібен Graph) - [Проактивні повідомлення](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) @@ -1019,7 +1019,7 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Сполучення](/uk/channels/pairing) — автентифікація в приватних повідомленнях і потік сполучення -- [Групи](/uk/channels/groups) — поведінка групового чату та керування згадками +- [Сполучення](/uk/channels/pairing) — автентифікація в особистих повідомленнях і процес сполучення +- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження згадками - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Безпека](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/channels/nextcloud-talk.md b/docs/uk/channels/nextcloud-talk.md index 3ab448253..d09afb7a8 100644 --- a/docs/uk/channels/nextcloud-talk.md +++ b/docs/uk/channels/nextcloud-talk.md @@ -1,38 +1,37 @@ --- read_when: - Робота над функціями каналу Nextcloud Talk -summary: Стан підтримки, можливості та конфігурація Nextcloud Talk +summary: Статус підтримки Nextcloud Talk, можливості та конфігурація title: Nextcloud Talk x-i18n: - generated_at: "2026-04-29T05:36:31Z" + generated_at: "2026-05-02T21:04:32Z" model: gpt-5.5 provider: openai - source_hash: fcbe8a65adfddc95d2b4944af88f9982e23a1676752efec2bbf40cfc4dd846d2 + source_hash: b05d31a3e57cd8989ccb2ac122f2cd548de4120a54a8a04aa979e5ebc94eab61 source_path: channels/nextcloud-talk.md workflow: 16 --- -Стан: вбудований Plugin (бот Webhook). Підтримуються прямі повідомлення, кімнати, реакції та markdown-повідомлення. +Статус: вбудований Plugin (Webhook-бот). Підтримуються прямі повідомлення, кімнати, реакції та повідомлення з markdown. ## Вбудований Plugin -Nextcloud Talk постачається як вбудований Plugin у поточних випусках OpenClaw, тому -звичайні пакетовані збірки не потребують окремого встановлення. +Nextcloud Talk постачається як вбудований Plugin у поточних релізах OpenClaw, тому +звичайні пакетні збірки не потребують окремого встановлення. -Якщо ви використовуєте старішу збірку або власне встановлення, яке не містить Nextcloud Talk, -установіть поточний npm-пакет, коли його буде опубліковано: +Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Nextcloud Talk, +встановіть npm-пакет напряму: -Встановлення через CLI (npm registry, коли існує поточний пакет): +Встановлення через CLI (реєстр npm): ```bash openclaw plugins install @openclaw/nextcloud-talk ``` -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарів, використовуйте поточну пакетовану -збірку OpenClaw або шлях до локального checkout, доки не буде -опубліковано новіший npm-пакет. +Використовуйте `@openclaw/nextcloud-talk@beta`, коли стежите за beta-каналом OpenClaw і +npmjs показує `beta` попереду `latest`. -Локальний checkout (під час запуску з git repo): +Локальний checkout (коли запуск відбувається з git-репозиторію): ```bash openclaw plugins install ./path/to/local/nextcloud-talk-plugin @@ -43,8 +42,8 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin ## Швидке налаштування (для початківців) 1. Переконайтеся, що Plugin Nextcloud Talk доступний. - - Поточні пакетовані випуски OpenClaw уже містять його. - - Старіші/власні встановлення можуть додати його вручну за допомогою команд вище. + - Поточні пакетні релізи OpenClaw уже містять його. + - Старіші або власні встановлення можуть додати його вручну за допомогою команд вище. 2. На вашому сервері Nextcloud створіть бота: ```bash @@ -99,24 +98,24 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin ## Примітки -- Боти не можуть ініціювати DM. Користувач має спершу написати боту. -- URL Webhook має бути доступним для Gateway; установіть `webhookPublicUrl`, якщо використовується проксі. -- Завантаження медіа не підтримуються API бота; медіа надсилаються як URL. -- Payload Webhook не розрізняє DM і кімнати; установіть `apiUser` + `apiPassword`, щоб увімкнути визначення типу кімнати (інакше DM обробляються як кімнати). +- Боти не можуть ініціювати DM. Користувач має спочатку написати боту. +- URL Webhook має бути доступним для Gateway; установіть `webhookPublicUrl`, якщо він за проксі. +- Завантаження медіа не підтримується API бота; медіа надсилаються як URL. +- Payload Webhook не розрізняє DM і кімнати; задайте `apiUser` + `apiPassword`, щоб увімкнути визначення типу кімнати (інакше DM обробляються як кімнати). -## Керування доступом (DM) +## Контроль доступу (DM) - Типово: `channels.nextcloud-talk.dmPolicy = "pairing"`. Невідомі відправники отримують код сполучення. - Схвалення через: - `openclaw pairing list nextcloud-talk` - `openclaw pairing approve nextcloud-talk ` - Публічні DM: `channels.nextcloud-talk.dmPolicy="open"` плюс `channels.nextcloud-talk.allowFrom=["*"]`. -- `allowFrom` зіставляється лише з ID користувачів Nextcloud; відображувані імена ігноруються. +- `allowFrom` збігається лише з ID користувачів Nextcloud; відображувані імена ігноруються. ## Кімнати (групи) -- Типово: `channels.nextcloud-talk.groupPolicy = "allowlist"` (доступ за згадкою). -- Додавайте кімнати до allowlist за допомогою `channels.nextcloud-talk.rooms`: +- Типово: `channels.nextcloud-talk.groupPolicy = "allowlist"` (доступ через згадку). +- Дозвольте кімнати списком дозволених у `channels.nextcloud-talk.rooms`: ```json5 { @@ -130,18 +129,18 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin } ``` -- Щоб не дозволяти жодних кімнат, залиште allowlist порожнім або встановіть `channels.nextcloud-talk.groupPolicy="disabled"`. +- Щоб не дозволяти жодних кімнат, залиште список дозволених порожнім або встановіть `channels.nextcloud-talk.groupPolicy="disabled"`. ## Можливості -| Функція | Стан | -| --------------- | ------------- | +| Функція | Статус | +| ----------------- | ----------------- | | Прямі повідомлення | Підтримується | | Кімнати | Підтримується | -| Потоки | Не підтримується | -| Медіа | Лише URL | -| Реакції | Підтримується | -| Нативні команди | Не підтримується | +| Потоки | Не підтримується | +| Медіа | Лише URL | +| Реакції | Підтримується | +| Нативні команди | Не підтримується | ## Довідник конфігурації (Nextcloud Talk) @@ -152,32 +151,32 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin - `channels.nextcloud-talk.enabled`: увімкнути/вимкнути запуск каналу. - `channels.nextcloud-talk.baseUrl`: URL інстансу Nextcloud. - `channels.nextcloud-talk.botSecret`: спільний секрет бота. -- `channels.nextcloud-talk.botSecretFile`: шлях до секрету у звичайному файлі. Символьні посилання відхиляються. -- `channels.nextcloud-talk.apiUser`: користувач API для визначення кімнат (виявлення DM). -- `channels.nextcloud-talk.apiPassword`: пароль API/застосунку для визначення кімнат. +- `channels.nextcloud-talk.botSecretFile`: шлях до секрету у звичайному файлі. Символічні посилання відхиляються. +- `channels.nextcloud-talk.apiUser`: користувач API для пошуку кімнат (виявлення DM). +- `channels.nextcloud-talk.apiPassword`: пароль API/застосунку для пошуку кімнат. - `channels.nextcloud-talk.apiPasswordFile`: шлях до файлу пароля API. - `channels.nextcloud-talk.webhookPort`: порт слухача Webhook (типово: 8788). - `channels.nextcloud-talk.webhookHost`: хост Webhook (типово: 0.0.0.0). - `channels.nextcloud-talk.webhookPath`: шлях Webhook (типово: /nextcloud-talk-webhook). - `channels.nextcloud-talk.webhookPublicUrl`: зовнішньо доступний URL Webhook. - `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`. -- `channels.nextcloud-talk.allowFrom`: allowlist DM (ID користувачів). `open` вимагає `"*"`. +- `channels.nextcloud-talk.allowFrom`: список дозволених для DM (ID користувачів). `open` вимагає `"*"`. - `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`. -- `channels.nextcloud-talk.groupAllowFrom`: allowlist груп (ID користувачів). -- `channels.nextcloud-talk.rooms`: налаштування для кожної кімнати та allowlist. +- `channels.nextcloud-talk.groupAllowFrom`: список дозволених для груп (ID користувачів). +- `channels.nextcloud-talk.rooms`: налаштування й список дозволених для кожної кімнати. - `channels.nextcloud-talk.historyLimit`: ліміт історії групи (0 вимикає). - `channels.nextcloud-talk.dmHistoryLimit`: ліміт історії DM (0 вимикає). -- `channels.nextcloud-talk.dms`: перевизначення для кожного DM (historyLimit). +- `channels.nextcloud-talk.dms`: перевизначення для окремих DM (historyLimit). - `channels.nextcloud-talk.textChunkLimit`: розмір фрагмента вихідного тексту (символи). - `channels.nextcloud-talk.chunkMode`: `length` (типово) або `newline`, щоб розділяти за порожніми рядками (межами абзаців) перед поділом за довжиною. -- `channels.nextcloud-talk.blockStreaming`: вимкнути блокове потокове передавання для цього каналу. -- `channels.nextcloud-talk.blockStreamingCoalesce`: налаштування об’єднання блокового потокового передавання. -- `channels.nextcloud-talk.mediaMaxMb`: ліміт вхідних медіа (MB). +- `channels.nextcloud-talk.blockStreaming`: вимкнути потокове передавання блоків для цього каналу. +- `channels.nextcloud-talk.blockStreamingCoalesce`: налаштування об’єднання потокового передавання блоків. +- `channels.nextcloud-talk.mediaMaxMb`: обмеження вхідних медіа (МБ). ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Сполучення](/uk/channels/pairing) — автентифікація DM і потік сполучення -- [Групи](/uk/channels/groups) — поведінка групового чату та доступ за згадкою -- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень +- [Сполучення](/uk/channels/pairing) — автентифікація DM і процес сполучення +- [Групи](/uk/channels/groups) — поведінка групового чату та доступ через згадку +- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень - [Безпека](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/channels/nostr.md b/docs/uk/channels/nostr.md index 93fd945bb..191886184 100644 --- a/docs/uk/channels/nostr.md +++ b/docs/uk/channels/nostr.md @@ -2,47 +2,46 @@ read_when: - Ви хочете, щоб OpenClaw отримував приватні повідомлення через Nostr - Ви налаштовуєте децентралізований обмін повідомленнями -summary: Канал прямих повідомлень Nostr через зашифровані повідомлення NIP-04 +summary: Канал приватних повідомлень Nostr через зашифровані повідомлення NIP-04 title: Nostr x-i18n: - generated_at: "2026-04-29T05:36:38Z" + generated_at: "2026-05-02T21:04:41Z" model: gpt-5.5 provider: openai - source_hash: 545d68077c9fe81d5fa5a17262d37e3688185a1fb12d67b8b1053b27b96c3c7f + source_hash: c3bf033d99b779cdf7b038461c9155694e22f65b1d54dbc28d0314bcf5424ddf source_path: channels/nostr.md workflow: 16 --- -**Стан:** Необов’язковий вбудований плагін (вимкнений за замовчуванням, доки його не налаштовано). +**Стан:** необов’язковий вбудований plugin (вимкнений за замовчуванням, доки його не налаштовано). -Nostr — це децентралізований протокол для соціальних мереж. Цей канал дає OpenClaw змогу отримувати зашифровані прямі повідомлення (DM) через NIP-04 і відповідати на них. +Nostr — це децентралізований протокол для соціальних мереж. Цей канал дає OpenClaw змогу отримувати зашифровані прямі повідомлення (DM) і відповідати на них через NIP-04. -## Вбудований плагін +## Вбудований plugin -Поточні випуски OpenClaw постачають Nostr як вбудований плагін, тому звичайні пакетовані +Поточні випуски OpenClaw постачають Nostr як вбудований plugin, тому звичайні пакетовані збірки не потребують окремого встановлення. ### Старіші/власні встановлення -- Онбординг (`openclaw onboard`) і `openclaw channels add` досі показують +- Onboarding (`openclaw onboard`) і `openclaw channels add` досі показують Nostr зі спільного каталогу каналів. -- Якщо ваша збірка не містить вбудованого Nostr, установіть актуальний npm-пакет, коли його - буде опубліковано. +- Якщо ваша збірка не містить вбудований Nostr, установіть npm-пакет напряму. ```bash openclaw plugins install @openclaw/nostr ``` -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарів, використовуйте актуальну пакетовану -збірку OpenClaw або локальний checkout, доки не буде опубліковано новіший npm-пакет. +Використовуйте `@openclaw/nostr@beta`, коли працюєте з beta-каналом OpenClaw, а npmjs +показує `beta` попереду `latest`. -Використовуйте локальний checkout (робочі процеси розробки): +Використовуйте локальну робочу копію (робочі процеси розробки): ```bash openclaw plugins install --link ``` -Перезапустіть Gateway після встановлення або ввімкнення плагінів. +Перезапустіть Gateway після встановлення або ввімкнення plugins. ### Неінтерактивне налаштування @@ -51,7 +50,7 @@ openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net" ``` -Використовуйте `--use-env`, щоб тримати `NOSTR_PRIVATE_KEY` у середовищі замість збереження ключа в конфігурації. +Використовуйте `--use-env`, щоб залишити `NOSTR_PRIVATE_KEY` у середовищі замість збереження ключа в конфігурації. ## Швидке налаштування @@ -84,19 +83,19 @@ export NOSTR_PRIVATE_KEY="nsec1..." ## Довідник конфігурації -| Ключ | Тип | Типове значення | Опис | -| ------------ | -------- | ------------------------------------------- | ----------------------------------- | -| `privateKey` | string | обов’язково | Приватний ключ у форматі `nsec` або hex | -| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | URL ретрансляторів (WebSocket) | -| `dmPolicy` | string | `pairing` | Політика доступу до DM | -| `allowFrom` | string[] | `[]` | Дозволені pubkey відправників | -| `enabled` | boolean | `true` | Увімкнути/вимкнути канал | -| `name` | string | - | Відображуване ім’я | -| `profile` | object | - | Метадані профілю NIP-01 | +| Ключ | Тип | Типове значення | Опис | +| ------------ | -------- | ----------------------------------------- | ----------------------------------- | +| `privateKey` | string | required | Приватний ключ у форматі `nsec` або hex | +| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | URL-адреси ретрансляторів (WebSocket) | +| `dmPolicy` | string | `pairing` | Політика доступу до DM | +| `allowFrom` | string[] | `[]` | Дозволені pubkeys відправників | +| `enabled` | boolean | `true` | Увімкнути/вимкнути канал | +| `name` | string | - | Відображуване ім’я | +| `profile` | object | - | Метадані профілю NIP-01 | ## Метадані профілю -Дані профілю публікуються як подія NIP-01 `kind:0`. Ви можете керувати ними з Control UI (Channels -> Nostr -> Profile) або задати їх безпосередньо в конфігурації. +Дані профілю публікуються як подія NIP-01 `kind:0`. Ви можете керувати ними з Control UI (Channels -> Nostr -> Profile) або задати їх напряму в конфігурації. Приклад: @@ -122,23 +121,23 @@ export NOSTR_PRIVATE_KEY="nsec1..." Примітки: -- URL профілю мають використовувати `https://`. -- Імпортування з ретрансляторів об’єднує поля та зберігає локальні перевизначення. +- URL-адреси профілю мають використовувати `https://`. +- Імпорт із ретрансляторів об’єднує поля й зберігає локальні перевизначення. ## Контроль доступу ### Політики DM - **pairing** (типово): невідомі відправники отримують код сполучення. -- **allowlist**: лише pubkey у `allowFrom` можуть надсилати DM. +- **allowlist**: надсилати DM можуть лише pubkeys у `allowFrom`. - **open**: публічні вхідні DM (потребує `allowFrom: ["*"]`). - **disabled**: ігнорувати вхідні DM. Примітки щодо застосування: -- Підписи вхідних подій перевіряються перед політикою відправника та розшифруванням NIP-04, тому підроблені події відхиляються на ранньому етапі. -- Відповіді для сполучення надсилаються без обробки початкового тіла DM. -- Вхідні DM обмежуються за частотою, а завеликі payload відкидаються до розшифрування. +- Підписи вхідних подій перевіряються перед політикою відправника й розшифруванням NIP-04, тому підроблені події відхиляються завчасно. +- Відповіді для сполучення надсилаються без обробки тіла початкового DM. +- Вхідні DM мають обмеження частоти, а завеликі payloads відкидаються перед розшифруванням. ### Приклад списку дозволених @@ -156,14 +155,14 @@ export NOSTR_PRIVATE_KEY="nsec1..." ## Формати ключів -Прийнятні формати: +Підтримувані формати: - **Приватний ключ:** `nsec...` або 64-символьний hex -- **Pubkey (`allowFrom`):** `npub...` або hex +- **Pubkeys (`allowFrom`):** `npub...` або hex ## Ретранслятори -Типово: `relay.damus.io` і `nos.lol`. +Типові значення: `relay.damus.io` і `nos.lol`. ```json5 { @@ -180,17 +179,17 @@ export NOSTR_PRIVATE_KEY="nsec1..." - Використовуйте 2-3 ретранслятори для резервування. - Уникайте надмірної кількості ретрансляторів (затримка, дублювання). -- Платні ретранслятори можуть підвищити надійність. +- Платні ретранслятори можуть покращити надійність. - Локальні ретранслятори підходять для тестування (`ws://localhost:7777`). -## Підтримка протоколу +## Підтримка протоколів -| NIP | Стан | Опис | -| ------ | ---------- | ------------------------------------- | -| NIP-01 | Підтримується | Базовий формат події + метадані профілю | -| NIP-04 | Підтримується | Зашифровані DM (`kind:4`) | -| NIP-17 | Заплановано | DM у форматі gift-wrap | -| NIP-44 | Заплановано | Версійне шифрування | +| NIP | Стан | Опис | +| ------ | ------------ | ----------------------------------------- | +| NIP-01 | Підтримується | Базовий формат подій + метадані профілю | +| NIP-04 | Підтримується | Зашифровані DM (`kind:4`) | +| NIP-17 | Заплановано | DM у gift-wrap | +| NIP-44 | Заплановано | Версійне шифрування | ## Тестування @@ -214,48 +213,48 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry ### Ручний тест -1. Занотуйте pubkey бота (npub) з логів. +1. Занотуйте pubkey бота (npub) із журналів. 2. Відкрийте клієнт Nostr (Damus, Amethyst тощо). 3. Надішліть DM на pubkey бота. 4. Перевірте відповідь. -## Усунення несправностей +## Усунення неполадок ### Повідомлення не надходять - Перевірте, що приватний ключ чинний. -- Переконайтеся, що URL ретрансляторів доступні та використовують `wss://` (або `ws://` для локального). +- Переконайтеся, що URL-адреси ретрансляторів доступні й використовують `wss://` (або `ws://` для локального). - Підтвердьте, що `enabled` не дорівнює `false`. -- Перевірте логи Gateway на помилки підключення до ретрансляторів. +- Перевірте журнали Gateway на помилки підключення до ретрансляторів. ### Відповіді не надсилаються - Перевірте, що ретранслятор приймає записи. -- Перевірте вихідне підключення. +- Перевірте вихідне з’єднання. - Стежте за обмеженнями частоти ретранслятора. ### Дубльовані відповіді - Очікувано під час використання кількох ретрансляторів. -- Повідомлення дедуплікуються за ID події; лише перша доставка запускає відповідь. +- Повідомлення дедуплікуються за ідентифікатором події; лише перша доставка запускає відповідь. ## Безпека - Ніколи не комітьте приватні ключі. - Використовуйте змінні середовища для ключів. -- Розгляньте `allowlist` для продакшн-ботів. -- Підписи перевіряються перед політикою відправника, а політика відправника застосовується перед розшифруванням, тому підроблені події відхиляються на ранньому етапі, а невідомі відправники не можуть примусово запускати повну криптографічну роботу. +- Розгляньте `allowlist` для production-ботів. +- Підписи перевіряються перед політикою відправника, а політика відправника застосовується перед розшифруванням, тому підроблені події відхиляються завчасно, а невідомі відправники не можуть примусити виконувати повну криптографічну роботу. ## Обмеження (MVP) - Лише прямі повідомлення (без групових чатів). - Без медіавкладень. -- Лише NIP-04 (gift-wrap NIP-17 заплановано). +- Лише NIP-04 (заплановано gift-wrap NIP-17). ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Сполучення](/uk/channels/pairing) — автентифікація DM і процес сполучення -- [Групи](/uk/channels/groups) — поведінка групового чату та gating згадок +- [Сполучення](/uk/channels/pairing) — автентифікація DM і потік сполучення +- [Групи](/uk/channels/groups) — поведінка групових чатів і gate для згадок - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень -- [Безпека](/uk/gateway/security) — модель доступу та зміцнення +- [Безпека](/uk/gateway/security) — модель доступу й посилення захисту diff --git a/docs/uk/channels/tlon.md b/docs/uk/channels/tlon.md index fbfab5b83..8b343d652 100644 --- a/docs/uk/channels/tlon.md +++ b/docs/uk/channels/tlon.md @@ -1,59 +1,58 @@ --- read_when: - Робота над функціями каналу Tlon/Urbit -summary: Стан підтримки Tlon/Urbit, можливості та конфігурація +summary: Статус підтримки Tlon/Urbit, можливості та конфігурація title: Tlon x-i18n: - generated_at: "2026-04-29T05:37:08Z" + generated_at: "2026-05-02T21:04:41Z" model: gpt-5.5 provider: openai - source_hash: bec632f946796a0ea4bceb5ad26f1ff1825c4304bf7252e9d2fd4d3889d36b52 + source_hash: 39dd46d94c708b5be9eae9457aa5b2b945fe701b3900207f996719b48090dd45 source_path: channels/tlon.md workflow: 16 --- -Tlon — це децентралізований месенджер, побудований на Urbit. OpenClaw підключається до вашого Urbit ship і може -відповідати на DM та повідомлення групових чатів. Групові відповіді за замовчуванням потребують @ згадки і можуть -бути додатково обмежені через allowlist. +Tlon — це децентралізований месенджер, побудований на Urbit. OpenClaw підключається до вашого корабля Urbit і може +відповідати на приватні повідомлення та повідомлення групового чату. Групові відповіді за замовчуванням потребують @-згадки й можуть +додатково обмежуватися списками дозволених. -Статус: вбудований плагін. Підтримуються DM, групові згадки, відповіді в гілках, форматування rich text і -завантаження зображень. Реакції й опитування поки не підтримуються. +Статус: вбудований plugin. Підтримуються приватні повідомлення, групові згадки, відповіді в тредах, форматування rich text і +завантаження зображень. Реакції та опитування поки не підтримуються. -## Вбудований плагін +## Вбудований plugin -Tlon постачається як вбудований плагін у поточних випусках OpenClaw, тому звичайні packaged +Tlon постачається як вбудований plugin у поточних випусках OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення. -Якщо ви користуєтеся старішою збіркою або кастомним встановленням, яке виключає Tlon, установіть -поточний npm-пакет, коли його буде опубліковано: +Якщо ви використовуєте старішу збірку або кастомне встановлення, яке виключає Tlon, встановіть +поточний пакет npm: -Установлення через CLI (npm registry, коли поточний пакет існує): +Встановлення через CLI (реєстр npm): ```bash openclaw plugins install @openclaw/tlon ``` -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, використовуйте поточну packaged -збірку OpenClaw або шлях до локального checkout, доки не буде -опубліковано новіший npm-пакет. +Використовуйте `@openclaw/tlon@beta`, коли стежите за beta-каналом OpenClaw, а npmjs +показує `beta` попереду `latest`. -Локальний checkout (під час запуску з git-репозиторію): +Локальна робоча копія (коли запускаєте з git-репозиторію): ```bash openclaw plugins install ./path/to/local/tlon-plugin ``` -Докладніше: [Плагіни](/uk/tools/plugin) +Докладніше: [Plugins](/uk/tools/plugin) ## Налаштування -1. Переконайтеся, що плагін Tlon доступний. - - Поточні packaged випуски OpenClaw уже містять його. - - Старіші/кастомні встановлення можуть додати його вручну командами вище. -2. Зберіть URL вашого ship і код входу. +1. Переконайтеся, що plugin Tlon доступний. + - Поточні пакетовані випуски OpenClaw уже містять його. + - Старіші/кастомні встановлення можуть додати його вручну за допомогою команд вище. +2. Зберіть URL вашого корабля та код входу. 3. Налаштуйте `channels.tlon`. 4. Перезапустіть gateway. -5. Надішліть DM боту або згадайте його в груповому каналі. +5. Напишіть боту в приватні повідомлення або згадайте його в груповому каналі. Мінімальна конфігурація (один обліковий запис): @@ -71,11 +70,11 @@ openclaw plugins install ./path/to/local/tlon-plugin } ``` -## Приватні/LAN ships +## Приватні/LAN-кораблі За замовчуванням OpenClaw блокує приватні/внутрішні імена хостів і діапазони IP для захисту від SSRF. -Якщо ваш ship працює в приватній мережі (localhost, LAN IP або внутрішнє ім’я хоста), -потрібно явно увімкнути це: +Якщо ваш корабель працює в приватній мережі (localhost, LAN IP або внутрішнє ім’я хоста), +потрібно явно ввімкнути це: ```json5 { @@ -94,12 +93,12 @@ openclaw plugins install ./path/to/local/tlon-plugin - `http://192.168.x.x:8080` - `http://my-ship.local:8080` -⚠️ Умикайте це лише тоді, коли довіряєте своїй локальній мережі. Це налаштування вимикає захист від SSRF -для запитів до URL вашого ship. +⚠️ Вмикайте це лише якщо довіряєте своїй локальній мережі. Це налаштування вимикає захист SSRF +для запитів до URL вашого корабля. ## Групові канали -Автовиявлення ввімкнене за замовчуванням. Ви також можете закріпити канали вручну: +Автовиявлення ввімкнене за замовчуванням. Також можна закріпити канали вручну: ```json5 { @@ -111,7 +110,7 @@ openclaw plugins install ./path/to/local/tlon-plugin } ``` -Вимкнення автовиявлення: +Вимкнути автовиявлення: ```json5 { @@ -125,7 +124,7 @@ openclaw plugins install ./path/to/local/tlon-plugin ## Контроль доступу -Allowlist для DM (порожній = DM не дозволені, використовуйте `ownerShip` для потоку схвалення): +Список дозволених для приватних повідомлень (порожній = приватні повідомлення не дозволені, використовуйте `ownerShip` для потоку схвалення): ```json5 { @@ -160,9 +159,9 @@ Allowlist для DM (порожній = DM не дозволені, викори } ``` -## Власник і система схвалення +## Власник і система схвалень -Задайте owner ship, щоб отримувати запити на схвалення, коли неавторизовані користувачі намагаються взаємодіяти: +Установіть корабель власника, щоб отримувати запити на схвалення, коли неавторизовані користувачі намагаються взаємодіяти: ```json5 { @@ -174,19 +173,19 @@ Allowlist для DM (порожній = DM не дозволені, викори } ``` -Owner ship **автоматично авторизований усюди** — запрошення DM приймаються автоматично, а -повідомлення каналів завжди дозволені. Вам не потрібно додавати власника до `dmAllowlist` або +Корабель власника **автоматично авторизований усюди** — запрошення в приватні повідомлення приймаються автоматично, а +повідомлення в каналах завжди дозволені. Не потрібно додавати власника до `dmAllowlist` або `defaultAuthorizedShips`. -Якщо це налаштовано, власник отримує DM-сповіщення про: +Коли це налаштовано, власник отримує сповіщення в приватних повідомленнях про: -- DM-запити від ships, яких немає в allowlist +- Запити на приватні повідомлення від кораблів, яких немає в списку дозволених - Згадки в каналах без авторизації -- Запити на групові запрошення +- Запити на запрошення до групи -## Налаштування автоматичного прийняття +## Налаштування автоприйняття -Автоматично приймати DM-запрошення (для ships у dmAllowlist): +Автоматично приймати запрошення в приватні повідомлення (для кораблів у dmAllowlist): ```json5 { @@ -198,7 +197,7 @@ Owner ship **автоматично авторизований усюди** — } ``` -Автоматично приймати групові запрошення: +Автоматично приймати запрошення до груп: ```json5 { @@ -210,39 +209,39 @@ Owner ship **автоматично авторизований усюди** — } ``` -## Цілі доставки (CLI/cron) +## Цілі доставлення (CLI/Cron) -Використовуйте їх з `openclaw message send` або cron-доставкою: +Використовуйте їх з `openclaw message send` або доставленням Cron: -- DM: `~sampel-palnet` або `dm/~sampel-palnet` +- Приватне повідомлення: `~sampel-palnet` або `dm/~sampel-palnet` - Група: `chat/~host-ship/channel` або `group:~host-ship/channel` -## Вбудований skill +## Вбудована навичка -Плагін Tlon містить вбудований skill ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)), -який надає CLI-доступ до операцій Tlon: +Plugin Tlon містить вбудовану навичку ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)), +яка надає CLI-доступ до операцій Tlon: -- **Контакти**: отримання/оновлення профілів, список контактів -- **Канали**: список, створення, публікація повідомлень, отримання історії -- **Групи**: список, створення, керування учасниками -- **DM**: надсилання повідомлень, реагування на повідомлення -- **Реакції**: додавання/видалення emoji-реакцій до дописів і DM -- **Налаштування**: керування дозволами плагіна через slash-команди +- **Контакти**: отримання/оновлення профілів, перелік контактів +- **Канали**: перелік, створення, публікація повідомлень, отримання історії +- **Групи**: перелік, створення, керування учасниками +- **Приватні повідомлення**: надсилання повідомлень, реакції на повідомлення +- **Реакції**: додавання/видалення emoji-реакцій до дописів і приватних повідомлень +- **Налаштування**: керування дозволами plugin через slash-команди -Skill автоматично доступний, коли плагін установлено. +Навичка автоматично доступна, коли plugin встановлено. ## Можливості -| Функція | Статус | -| --------------- | --------------------------------------- | -| Прямі повідомлення | ✅ Підтримується | -| Групи/канали | ✅ Підтримується (за замовчуванням через згадки) | -| Гілки | ✅ Підтримується (автовідповіді в гілці) | -| Rich text | ✅ Markdown перетворюється у формат Tlon | -| Зображення | ✅ Завантажуються в сховище Tlon | -| Реакції | ✅ Через [вбудований skill](#bundled-skill) | -| Опитування | ❌ Поки не підтримується | -| Нативні команди | ✅ Підтримується (за замовчуванням лише для власника) | +| Функція | Статус | +| ------------------ | -------------------------------------------------- | +| Прямі повідомлення | ✅ Підтримується | +| Групи/канали | ✅ Підтримується (за замовчуванням через згадки) | +| Треди | ✅ Підтримується (автовідповіді в треді) | +| Rich text | ✅ Markdown перетворюється у формат Tlon | +| Зображення | ✅ Завантажуються в сховище Tlon | +| Реакції | ✅ Через [вбудовану навичку](#bundled-skill) | +| Опитування | ❌ Поки не підтримується | +| Нативні команди | ✅ Підтримується (за замовчуванням лише власник) | ## Усунення несправностей @@ -255,45 +254,45 @@ openclaw logs --follow openclaw doctor ``` -Поширені збої: +Типові збої: -- **DM ігноруються**: відправника немає в `dmAllowlist` і `ownerShip` не налаштовано для потоку схвалення. +- **Приватні повідомлення ігноруються**: відправника немає в `dmAllowlist`, і `ownerShip` не налаштовано для потоку схвалення. - **Групові повідомлення ігноруються**: канал не виявлено або відправник не авторизований. -- **Помилки з’єднання**: перевірте, що URL ship доступний; увімкніть `allowPrivateNetwork` для локальних ships. -- **Помилки автентифікації**: переконайтеся, що код входу актуальний (коди змінюються). +- **Помилки підключення**: перевірте, що URL корабля доступний; увімкніть `allowPrivateNetwork` для локальних кораблів. +- **Помилки автентифікації**: перевірте, що код входу актуальний (коди змінюються). ## Довідник конфігурації -Повна конфігурація: [Конфігурація](/uk/gateway/configuration) +Повна конфігурація: [Configuration](/uk/gateway/configuration) Параметри провайдера: - `channels.tlon.enabled`: увімкнути/вимкнути запуск каналу. -- `channels.tlon.ship`: ім’я Urbit ship бота (наприклад, `~sampel-palnet`). -- `channels.tlon.url`: URL ship (наприклад, `https://sampel-palnet.tlon.network`). -- `channels.tlon.code`: код входу ship. +- `channels.tlon.ship`: ім’я Urbit-корабля бота (наприклад, `~sampel-palnet`). +- `channels.tlon.url`: URL корабля (наприклад, `https://sampel-palnet.tlon.network`). +- `channels.tlon.code`: код входу на корабель. - `channels.tlon.allowPrivateNetwork`: дозволити localhost/LAN URL (обхід SSRF). -- `channels.tlon.ownerShip`: owner ship для системи схвалення (завжди авторизований). -- `channels.tlon.dmAllowlist`: ships, яким дозволено надсилати DM (порожньо = жодного). -- `channels.tlon.autoAcceptDmInvites`: автоматично приймати DM від ships з allowlist. -- `channels.tlon.autoAcceptGroupInvites`: автоматично приймати всі групові запрошення. +- `channels.tlon.ownerShip`: корабель власника для системи схвалення (завжди авторизований). +- `channels.tlon.dmAllowlist`: кораблі, яким дозволено писати приватні повідомлення (порожній = жодні). +- `channels.tlon.autoAcceptDmInvites`: автоматично приймати приватні повідомлення від кораблів зі списку дозволених. +- `channels.tlon.autoAcceptGroupInvites`: автоматично приймати всі запрошення до груп. - `channels.tlon.autoDiscoverChannels`: автоматично виявляти групові канали (за замовчуванням: true). -- `channels.tlon.groupChannels`: вручну закріплені channel nests. -- `channels.tlon.defaultAuthorizedShips`: ships, авторизовані для всіх каналів. -- `channels.tlon.authorization.channelRules`: правила автентифікації для кожного каналу. +- `channels.tlon.groupChannels`: вручну закріплені гнізда каналів. +- `channels.tlon.defaultAuthorizedShips`: кораблі, авторизовані для всіх каналів. +- `channels.tlon.authorization.channelRules`: правила автентифікації для окремих каналів. - `channels.tlon.showModelSignature`: додавати назву моделі до повідомлень. ## Примітки - Групові відповіді потребують згадки (наприклад, `~your-bot-ship`), щоб відповісти. -- Відповіді в гілках: якщо вхідне повідомлення належить до гілки, OpenClaw відповідає в цій гілці. -- Rich text: форматування Markdown (жирний, курсив, code, заголовки, списки) перетворюється у нативний формат Tlon. -- Зображення: URL завантажуються до сховища Tlon і вбудовуються як блоки зображень. +- Відповіді в треді: якщо вхідне повідомлення міститься в треді, OpenClaw відповідає в цьому треді. +- Rich text: форматування Markdown (жирний, курсив, код, заголовки, списки) перетворюється в нативний формат Tlon. +- Зображення: URL завантажуються в сховище Tlon і вбудовуються як блоки зображень. ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing -- [Групи](/uk/channels/groups) — поведінка групових чатів і обмеження через згадки -- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Безпека](/uk/gateway/security) — модель доступу й посилення захисту +- [Сполучення](/uk/channels/pairing) — автентифікація через приватні повідомлення та потік сполучення +- [Групи](/uk/channels/groups) — поведінка групового чату та обмеження через згадки +- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень +- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/channels/twitch.md b/docs/uk/channels/twitch.md index 9f7f7965b..d6a86dafe 100644 --- a/docs/uk/channels/twitch.md +++ b/docs/uk/channels/twitch.md @@ -1,14 +1,14 @@ --- read_when: - - Налаштування інтеграції з чатом Twitch для OpenClaw + - Налаштування інтеграції чату Twitch для OpenClaw sidebarTitle: Twitch summary: Конфігурація та налаштування чат-бота Twitch title: Twitch x-i18n: - generated_at: "2026-04-29T05:37:17Z" + generated_at: "2026-05-02T21:04:33Z" model: gpt-5.5 provider: openai - source_hash: 897079687a243c9c2ce2be63167e59f4413bbd89735fb79f03928547023bd787 + source_hash: 0738d0a2095370f771fa5a1967c8bbcb88e052648c6da8c0d9f8367600e101e0 source_path: channels/twitch.md workflow: 16 --- @@ -18,66 +18,66 @@ x-i18n: ## Вбудований plugin -Twitch постачається як вбудований plugin у поточних випусках OpenClaw, тому звичайні пакетні збірки не потребують окремого встановлення. +Twitch постачається як вбудований plugin у поточних випусках OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення. -Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Twitch, установіть актуальний npm-пакет, коли його буде опубліковано: +Якщо ви використовуєте старішу збірку або власне встановлення без Twitch, установіть npm-пакет напряму: - + ```bash openclaw plugins install @openclaw/twitch ``` - + ```bash openclaw plugins install ./path/to/local/twitch-plugin ``` -Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, використовуйте поточну пакетну збірку -OpenClaw або шлях до локального checkout, доки не буде опубліковано новіший npm-пакет. +Використовуйте `@openclaw/twitch@beta`, коли стежите за beta-каналом OpenClaw і npmjs +показує `beta` попереду `latest`. Докладно: [Plugins](/uk/tools/plugin) ## Швидке налаштування (для початківців) - - Поточні пакетні випуски OpenClaw уже містять його. Старіші або власні встановлення можуть додати його вручну за допомогою наведених вище команд. + + Поточні пакетовані випуски OpenClaw уже містять його. Старіші або власні встановлення можуть додати його вручну командами вище. - + Створіть окремий обліковий запис Twitch для бота (або використайте наявний обліковий запис). - + Використайте [Twitch Token Generator](https://twitchtokengenerator.com/): - Виберіть **Bot Token** - - Переконайтеся, що вибрано scopes `chat:read` і `chat:write` + - Переконайтеся, що вибрано області доступу `chat:read` і `chat:write` - Скопіюйте **Client ID** і **Access Token** - + Використайте [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/), щоб перетворити ім’я користувача на ID користувача Twitch. - + - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (лише обліковий запис за замовчуванням) - Або config: `channels.twitch.accessToken` - Якщо задано обидва варіанти, config має пріоритет (резервне env застосовується лише для облікового запису за замовчуванням). + Якщо задано обидва варіанти, config має пріоритет (env fallback діє лише для облікового запису за замовчуванням). - - Запустіть Gateway із налаштованим каналом. + + Запустіть gateway із налаштованим каналом. -Додайте контроль доступу (`allowFrom` або `allowedRoles`), щоб неавторизовані користувачі не могли запускати бота. `requireMention` за замовчуванням має значення `true`. +Додайте контроль доступу (`allowFrom` або `allowedRoles`), щоб запобігти запуску бота неавторизованими користувачами. `requireMention` за замовчуванням має значення `true`. -Мінімальна config: +Мінімальна конфігурація: ```json5 { @@ -97,18 +97,18 @@ OpenClaw або шлях до локального checkout, доки не бу ## Що це таке - Канал Twitch, яким володіє Gateway. -- Детермінована маршрутизація: відповіді завжди повертаються в Twitch. -- Кожен обліковий запис зіставляється з ізольованим ключем сеансу `agent::twitch:`. -- `username` — це обліковий запис бота (який проходить автентифікацію), `channel` — чат-кімната, до якої потрібно приєднатися. +- Детермінована маршрутизація: відповіді завжди повертаються до Twitch. +- Кожен обліковий запис зіставляється з ізольованим ключем сесії `agent::twitch:`. +- `username` — це обліковий запис бота (який автентифікується), `channel` — це чат-кімната, до якої треба приєднатися. -## Налаштування (детально) +## Налаштування (докладно) ### Згенеруйте облікові дані Використайте [Twitch Token Generator](https://twitchtokengenerator.com/): - Виберіть **Bot Token** -- Переконайтеся, що вибрано scopes `chat:read` і `chat:write` +- Переконайтеся, що вибрано області доступу `chat:read` і `chat:write` - Скопіюйте **Client ID** і **Access Token** @@ -118,7 +118,7 @@ OpenClaw або шлях до локального checkout, доки не бу ### Налаштуйте бота - + ```bash OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... ``` @@ -154,19 +154,19 @@ OpenClaw або шлях до локального checkout, доки не бу } ``` -Надавайте перевагу `allowFrom` для суворого списку дозволених. Натомість використовуйте `allowedRoles`, якщо потрібен доступ на основі ролей. +Надавайте перевагу `allowFrom` для суворого списку дозволених. Використовуйте натомість `allowedRoles`, якщо потрібен доступ на основі ролей. **Доступні ролі:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`. **Чому ID користувачів?** Імена користувачів можуть змінюватися, що дає змогу видавати себе за інших. ID користувачів є постійними. -Знайдіть свій ID користувача Twitch: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Перетворіть своє ім’я користувача Twitch на ID) +Знайдіть свій ID користувача Twitch: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (перетворіть своє ім’я користувача Twitch на ID) ## Оновлення токена (необов’язково) -Токени з [Twitch Token Generator](https://twitchtokengenerator.com/) не можна автоматично оновлювати — згенеруйте їх повторно після спливання. +Токени з [Twitch Token Generator](https://twitchtokengenerator.com/) не можна автоматично оновлювати — згенеруйте їх повторно після завершення строку дії. Для автоматичного оновлення токена створіть власний застосунок Twitch у [Twitch Developer Console](https://dev.twitch.tv/console) і додайте до config: @@ -181,11 +181,11 @@ OpenClaw або шлях до локального checkout, доки не бу } ``` -Бот автоматично оновлює токени до спливання терміну дії та записує події оновлення в журнали. +Бот автоматично оновлює токени перед завершенням строку дії та записує події оновлення в журнал. ## Підтримка кількох облікових записів -Використовуйте `channels.twitch.accounts` із токенами для кожного облікового запису. Спільний шаблон див. у [Конфігурації](/uk/gateway/configuration). +Використовуйте `channels.twitch.accounts` із токенами для кожного облікового запису. Див. [Конфігурація](/uk/gateway/configuration) для спільного шаблону. Приклад (один обліковий запис бота у двох каналах): @@ -219,7 +219,7 @@ OpenClaw або шлях до локального checkout, доки не бу ## Контроль доступу - + ```json5 { channels: { @@ -234,7 +234,7 @@ OpenClaw або шлях до локального checkout, доки не бу } ``` - + ```json5 { channels: { @@ -249,10 +249,10 @@ OpenClaw або шлях до локального checkout, доки не бу } ``` - `allowFrom` — це суворий список дозволених. Коли його задано, дозволені лише ці ID користувачів. Якщо потрібен доступ на основі ролей, не задавайте `allowFrom` і натомість налаштуйте `allowedRoles`. + `allowFrom` — це суворий список дозволених. Якщо його задано, дозволені лише ці ID користувачів. Якщо потрібен доступ на основі ролей, не задавайте `allowFrom` і натомість налаштуйте `allowedRoles`. - + За замовчуванням `requireMention` має значення `true`. Щоб вимкнути це й відповідати на всі повідомлення: ```json5 @@ -274,7 +274,7 @@ OpenClaw або шлях до локального checkout, доки не бу ## Усунення несправностей -Спочатку виконайте діагностичні команди: +Спочатку запустіть діагностичні команди: ```bash openclaw doctor @@ -282,20 +282,20 @@ openclaw channels status --probe ``` - - - **Перевірте контроль доступу:** Переконайтеся, що ваш ID користувача є в `allowFrom`, або тимчасово видаліть `allowFrom` і встановіть `allowedRoles: ["all"]` для тестування. - - **Перевірте, що бот перебуває в каналі:** Бот має приєднатися до каналу, указаного в `channel`. + + - **Перевірте контроль доступу:** переконайтеся, що ваш ID користувача є в `allowFrom`, або тимчасово видаліть `allowFrom` і задайте `allowedRoles: ["all"]` для тестування. + - **Перевірте, що бот у каналі:** бот має приєднатися до каналу, указаного в `channel`. - - "Failed to connect" або помилки автентифікації: + + "Не вдалося підключитися" або помилки автентифікації: - - Переконайтеся, що `accessToken` є значенням OAuth access token (зазвичай починається з префікса `oauth:`) - - Перевірте, що токен має scopes `chat:read` і `chat:write` - - Якщо використовується оновлення токена, переконайтеся, що задано `clientSecret` і `refreshToken` + - Переконайтеся, що `accessToken` є значенням OAuth-токена доступу (зазвичай починається з префікса `oauth:`) + - Перевірте, що токен має області доступу `chat:read` і `chat:write` + - Якщо використовується оновлення токена, переконайтеся, що `clientSecret` і `refreshToken` задано - + Перевірте журнали на наявність подій оновлення: ``` @@ -303,29 +303,29 @@ openclaw channels status --probe Access token refreshed for user 123456 (expires in 14400s) ``` - Якщо бачите "token refresh disabled (no refresh token)": + Якщо ви бачите "token refresh disabled (no refresh token)": - - Переконайтеся, що надано `clientSecret` - - Переконайтеся, що надано `refreshToken` + - Переконайтеся, що `clientSecret` надано + - Переконайтеся, що `refreshToken` надано -## Config +## Конфігурація -### Config облікового запису +### Конфігурація облікового запису Ім’я користувача бота. - OAuth access token із `chat:read` і `chat:write`. + OAuth-токен доступу з `chat:read` і `chat:write`. Twitch Client ID (з Token Generator або вашого застосунку). - Канал, до якого потрібно приєднатися. + Канал для приєднання. Увімкнути цей обліковий запис. @@ -337,10 +337,10 @@ openclaw channels status --probe Необов’язково: для автоматичного оновлення токена. - Термін дії токена в секундах. + Строк дії токена в секундах. - Часова позначка отримання токена. + Позначка часу отримання токена. Список дозволених ID користувачів. @@ -355,11 +355,11 @@ openclaw channels status --probe ### Параметри провайдера - `channels.twitch.enabled` - Увімкнути/вимкнути запуск каналу -- `channels.twitch.username` - Ім’я користувача бота (спрощена config для одного облікового запису) -- `channels.twitch.accessToken` - OAuth access token (спрощена config для одного облікового запису) -- `channels.twitch.clientId` - Twitch Client ID (спрощена config для одного облікового запису) -- `channels.twitch.channel` - Канал, до якого потрібно приєднатися (спрощена config для одного облікового запису) -- `channels.twitch.accounts.` - Config для кількох облікових записів (усі поля облікового запису вище) +- `channels.twitch.username` - Ім’я користувача бота (спрощена конфігурація одного облікового запису) +- `channels.twitch.accessToken` - OAuth-токен доступу (спрощена конфігурація одного облікового запису) +- `channels.twitch.clientId` - Twitch Client ID (спрощена конфігурація одного облікового запису) +- `channels.twitch.channel` - Канал для приєднання (спрощена конфігурація одного облікового запису) +- `channels.twitch.accounts.` - Конфігурація кількох облікових записів (усі поля облікового запису вище) Повний приклад: @@ -396,11 +396,11 @@ openclaw channels status --probe } ``` -## Дії інструментів +## Дії інструмента Агент може викликати `twitch` з дією: -- `send` - Надіслати повідомлення в канал +- `send` - Надіслати повідомлення до каналу Приклад: @@ -417,22 +417,22 @@ openclaw channels status --probe ## Безпека та експлуатація - **Ставтеся до токенів як до паролів** — ніколи не комітьте токени в git. -- **Використовуйте автоматичне оновлення токенів** для довготривалих ботів. +- **Використовуйте автоматичне оновлення токенів** для ботів, що працюють довго. - **Використовуйте списки дозволених ID користувачів** замість імен користувачів для контролю доступу. -- **Стежте за журналами** щодо подій оновлення токенів і стану з’єднання. -- **Мінімізуйте scopes токенів** — запитуйте лише `chat:read` і `chat:write`. -- **Якщо застрягли**: перезапустіть Gateway після підтвердження, що жоден інший процес не володіє сеансом. +- **Відстежуйте журнали** щодо подій оновлення токенів і стану з’єднання. +- **Мінімізуйте області доступу токенів** — запитуйте лише `chat:read` і `chat:write`. +- **Якщо застрягли**: перезапустіть gateway після підтвердження, що жоден інший процес не володіє сесією. ## Обмеження -- **500 символів** на повідомлення (автоматично розбивається на фрагменти на межах слів). -- Markdown видаляється перед розбиттям на фрагменти. -- Без обмеження частоти (використовуються вбудовані обмеження Twitch). +- **500 символів** на повідомлення (автоматично розбивається на частини за межами слів). +- Markdown видаляється перед розбиттям. +- Без обмеження частоти (використовуються вбудовані обмеження частоти Twitch). ## Пов’язане -- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень +- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Групи](/uk/channels/groups) — поведінка групового чату та фільтрація за згадками -- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing +- [Групи](/uk/channels/groups) — поведінка групових чатів і блокування без згадки +- [Pairing](/uk/channels/pairing) — автентифікація DM і потік сполучення - [Безпека](/uk/gateway/security) — модель доступу та посилення безпеки diff --git a/docs/uk/channels/whatsapp.md b/docs/uk/channels/whatsapp.md index 5c14407d2..11db446e9 100644 --- a/docs/uk/channels/whatsapp.md +++ b/docs/uk/channels/whatsapp.md @@ -1,28 +1,28 @@ --- read_when: - - Робота над поведінкою каналу WhatsApp/web або маршрутизацією вхідних повідомлень -summary: Підтримка каналу WhatsApp, засоби керування доступом, поведінка доставки та операційні процедури + - Робота з поведінкою каналу WhatsApp/вебканалу або маршрутизацією вхідних повідомлень +summary: Підтримка каналу WhatsApp, засоби контролю доступу, поведінка доставки та операції title: WhatsApp x-i18n: - generated_at: "2026-05-02T20:13:37Z" + generated_at: "2026-05-02T21:04:38Z" model: gpt-5.5 provider: openai - source_hash: bb8afa93f0470e0454cf59e19193d8c2f204db63b428a4de579e93f01bf3ee62 + source_hash: 4ce4696b9d055695e340be5d9570316f957118d1925af577783c27443e725056 source_path: channels/whatsapp.md workflow: 16 --- -Статус: готовий до production через WhatsApp Web (Baileys). Gateway керує прив’язаними сеансами. +Стан: готово до production через WhatsApp Web (Baileys). Gateway керує пов'язаними сеансами. ## Встановлення (на вимогу) - Onboarding (`openclaw onboard`) і `openclaw channels add --channel whatsapp` - пропонують установити WhatsApp plugin під час першого вибору. -- `openclaw channels login --channel whatsapp` також пропонує потік установлення, коли - plugin ще відсутній. -- Dev channel + git checkout: типово використовує локальний шлях plugin. -- Stable/Beta: використовує npm-пакет `@openclaw/whatsapp`, коли актуальний пакет - опубліковано. + пропонують встановити плагін WhatsApp під час першого вибору. +- `openclaw channels login --channel whatsapp` також пропонує процес встановлення, коли + плагін ще не наявний. +- Dev-канал + git checkout: типово використовує локальний шлях плагіна. +- Stable/Beta: використовує npm-пакет `@openclaw/whatsapp`; оновлення beta-каналу + віддають перевагу `@openclaw/whatsapp@beta`, коли цей тег доступний. Ручне встановлення залишається доступним: @@ -30,26 +30,25 @@ x-i18n: openclaw plugins install @openclaw/whatsapp ``` -Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий або відсутній, використовуйте -актуальну пакетовану збірку OpenClaw або локальний checkout, доки ланцюг npm-пакетів -не наздожене. +Використовуйте `@openclaw/whatsapp@beta`, коли стежите за beta-каналом OpenClaw і npmjs +показує `beta` попереду `latest`. - - Типова політика DM — pairing для невідомих відправників. + + Типова політика DM — сполучення для невідомих відправників. - - Міжканальна діагностика та інструкції з виправлення. + + Міжканальна діагностика та інструкції з відновлення. - - Повні шаблони й приклади конфігурації каналу. + + Повні шаблони та приклади конфігурації каналів. ## Швидке налаштування - + ```json5 { @@ -66,7 +65,7 @@ openclaw plugins install @openclaw/whatsapp - + ```bash openclaw channels login --channel whatsapp @@ -78,7 +77,7 @@ openclaw channels login --channel whatsapp openclaw channels login --channel whatsapp --account work ``` - Щоб під’єднати наявний/власний каталог автентифікації WhatsApp Web перед входом: + Щоб прикріпити наявний/власний каталог автентифікації WhatsApp Web перед входом: ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth @@ -87,7 +86,7 @@ openclaw channels login --channel whatsapp --account work - + ```bash openclaw gateway @@ -95,31 +94,31 @@ openclaw gateway - + ```bash openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - Запити pairing спливають через 1 годину. Очікувані запити обмежено до 3 на канал. + Запити на сполучення спливають через 1 годину. Очікувані запити обмежені 3 на канал. -OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та потік налаштування оптимізовані для такого налаштування, але налаштування з особистим номером також підтримуються.) +OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого варіанта, але налаштування з особистим номером також підтримуються.) ## Шаблони розгортання - + Це найчистіший операційний режим: - окрема ідентичність WhatsApp для OpenClaw - - чіткіші allowlist DM і межі маршрутизації - - менша ймовірність плутанини із self-chat + - зрозуміліші allowlist DM і межі маршрутизації + - нижча ймовірність плутанини із self-chat Мінімальний шаблон політики: @@ -136,44 +135,44 @@ OpenClaw рекомендує за можливості запускати Whats - - Onboarding підтримує режим особистого номера й записує базову конфігурацію, дружню до self-chat: + + Onboarding підтримує режим особистого номера й записує базовий варіант, дружній до self-chat: - `dmPolicy: "allowlist"` - `allowFrom` містить ваш особистий номер - `selfChatMode: true` - Під час виконання захисти self-chat спираються на прив’язаний власний номер і `allowFrom`. + Під час виконання захисти self-chat базуються на пов'язаному власному номері та `allowFrom`. - + Канал платформи обміну повідомленнями базується на WhatsApp Web (`Baileys`) у поточній архітектурі каналів OpenClaw. - Окремого каналу повідомлень Twilio WhatsApp у вбудованому реєстрі чат-каналів немає. + У вбудованому реєстрі chat-каналів немає окремого каналу повідомлень Twilio WhatsApp. ## Модель виконання -- Gateway володіє WhatsApp socket і циклом повторного підключення. -- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс прив’язаного пристрою не перезапускається тільки через те, що останнім часом ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але протягом вікна watchdog не обробляються повідомлення застосунку; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний тайм-аут повідомлень для першого вікна відновлення. -- Таймінги Baileys socket явно задані в `web.whatsapp.*`: `keepAliveIntervalMs` керує ping WhatsApp Web застосунку, `connectTimeoutMs` керує тайм-аутом початкового handshake, а `defaultQueryTimeoutMs` керує тайм-аутами запитів Baileys. +- Gateway керує сокетом WhatsApp і циклом повторного підключення. +- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс пов'язаного пристрою не перезапускається тільки тому, що останнім часом ніхто не надсилав повідомлення. Довше обмеження тиші застосунку все ще примусово виконує повторне підключення, якщо транспортні фрейми продовжують надходити, але жодні повідомлення застосунку не обробляються протягом вікна watchdog; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний тайм-аут повідомлення для першого вікна відновлення. +- Таймінги сокета Baileys явно задаються в `web.whatsapp.*`: `keepAliveIntervalMs` керує ping WhatsApp Web на рівні застосунку, `connectTimeoutMs` керує тайм-аутом початкового handshake, а `defaultQueryTimeoutMs` керує тайм-аутами запитів Baileys. - Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису. -- Чати статусів і трансляцій ігноруються (`@status`, `@broadcast`). -- Watchdog повторного підключення стежить за активністю транспорту WhatsApp Web, а не лише за обсягом вхідних повідомлень застосунку: тихі сеанси прив’язаних пристроїв залишаються активними, доки транспортні кадри продовжують надходити, але зупинка транспорту примушує повторне підключення задовго до пізнішого шляху віддаленого від’єднання. -- Прямі чати використовують правила сеансів DM (`session.dmScope`; типове `main` згортає DM у головний сеанс агента). +- Чати статусу та трансляцій ігноруються (`@status`, `@broadcast`). +- Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси пов'язаних пристроїв залишаються активними, доки тривають транспортні фрейми, але збій транспорту примусово виконує повторне підключення задовго до пізнішого шляху віддаленого відключення. +- Прямі чати використовують правила DM-сеансів (`session.dmScope`; типове `main` згортає DM до головного сеансу агента). - Групові сеанси ізольовані (`agent::whatsapp:group:`). -- WhatsApp Channels/Newsletters можуть бути явними вихідними цілями зі своїм нативним JID `@newsletter`. Вихідні надсилання до newsletter використовують метадані сеансу каналу (`agent::whatsapp:channel:`), а не семантику сеансів DM. -- Транспорт WhatsApp Web поважає стандартні змінні середовища proxy на хості gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Віддавайте перевагу конфігурації proxy на рівні хоста, а не специфічним для каналу налаштуванням proxy WhatsApp. -- Коли ввімкнено `messages.removeAckAfterReply`, OpenClaw очищає реакцію ack у WhatsApp після доставки видимої відповіді. +- WhatsApp Channels/Newsletters можуть бути явними вихідними цілями зі своїм нативним JID `@newsletter`. Вихідні надсилання до newsletter використовують метадані сеансу каналу (`agent::whatsapp:channel:`), а не семантику DM-сеансу. +- Транспорт WhatsApp Web поважає стандартні змінні середовища proxy на хості gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Віддавайте перевагу конфігурації proxy на рівні хоста замість налаштувань proxy WhatsApp, специфічних для каналу. +- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає ack-реакцію WhatsApp після доставки видимої відповіді. ## Plugin hooks і приватність Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів, ідентифікатори груп, імена відправників і поля кореляції сеансів. З цієї причини -WhatsApp не транслює вхідні payload `message_received` hook до plugins, +WhatsApp не транслює вхідні payload `message_received` hook до плагінів, якщо ви явно не ввімкнете це: ```json5 @@ -188,7 +187,7 @@ WhatsApp не транслює вхідні payload `message_received` hook до } ``` -Можна обмежити ввімкнення одним обліковим записом: +Ви можете обмежити ввімкнення одним обліковим записом: ```json5 { @@ -206,13 +205,13 @@ WhatsApp не транслює вхідні payload `message_received` hook до } ``` -Вмикайте це лише для plugins, яким ви довіряєте отримувати вміст і ідентифікатори -вхідних повідомлень WhatsApp. +Увімкніть це лише для плагінів, яким довіряєте отримувати вміст і +ідентифікатори вхідних повідомлень WhatsApp. ## Контроль доступу та активація - + `channels.whatsapp.dmPolicy` керує доступом до прямих чатів: - `pairing` (типово) @@ -222,54 +221,54 @@ WhatsApp не транслює вхідні payload `message_received` hook до `allowFrom` приймає номери у стилі E.164 (нормалізуються внутрішньо). - `allowFrom` — це список контролю доступу для відправників DM. Він не обмежує явні вихідні надсилання до JID груп WhatsApp або JID каналів `@newsletter`. + `allowFrom` — це список контролю доступу відправників DM. Він не обмежує явні вихідні надсилання до JID груп WhatsApp або JID каналів `@newsletter`. Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над типовими значеннями рівня каналу для цього облікового запису. Деталі поведінки під час виконання: - - pairings зберігаються в allow-store каналу та об’єднуються з налаштованим `allowFrom` - - запланована автоматизація і fallback одержувачів Heartbeat використовують явні цілі доставки або налаштований `allowFrom`; схвалення DM pairing не є неявними одержувачами Cron чи Heartbeat - - якщо allowlist не налаштовано, прив’язаний власний номер дозволено типово - - OpenClaw ніколи автоматично не створює pairing для вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з прив’язаного пристрою) + - сполучення зберігаються в allow-store каналу й об'єднуються з налаштованим `allowFrom` + - запланована автоматизація та fallback отримувачів heartbeat використовують явні цілі доставки або налаштований `allowFrom`; схвалення DM-сполучення не є неявними отримувачами cron чи heartbeat + - якщо allowlist не налаштовано, пов'язаний власний номер дозволено типово + - OpenClaw ніколи автоматично не створює сполучення для вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з пов'язаного пристрою) - + Доступ до груп має два рівні: 1. **Allowlist членства в групах** (`channels.whatsapp.groups`) - - якщо `groups` пропущено, всі групи придатні - - якщо `groups` присутній, він діє як allowlist груп (`"*"` дозволено) + - якщо `groups` пропущено, усі групи придатні + - якщо `groups` наявний, він діє як allowlist груп (`"*"` дозволено) - 2. **Політика відправників групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) + 2. **Політика відправників груп** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) - `open`: allowlist відправників обходиться - `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`) - - `disabled`: блокувати всі вхідні повідомлення груп + - `disabled`: блокувати всі групові вхідні повідомлення Fallback allowlist відправників: - - якщо `groupAllowFrom` не задано, під час виконання використовується fallback до `allowFrom`, коли він доступний - - allowlists відправників оцінюються перед активацією через згадку/відповідь + - якщо `groupAllowFrom` не задано, під час виконання fallback переходить до `allowFrom`, коли доступно + - allowlist відправників оцінюються перед активацією за згадкою/відповіддю - Примітка: якщо блок `channels.whatsapp` взагалі відсутній, fallback політики груп під час виконання — `allowlist` (із warning log), навіть якщо задано `channels.defaults.groupPolicy`. + Примітка: якщо блока `channels.whatsapp` взагалі немає, fallback політики груп під час виконання — `allowlist` (із warning-log), навіть якщо `channels.defaults.groupPolicy` задано. - - Відповіді в групах типово потребують згадки. + + Групові відповіді типово потребують згадки. - Виявлення згадок включає: + Виявлення згадок охоплює: - явні згадки WhatsApp ідентичності бота - налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - - транскрипти voice-note для авторизованих групових повідомлень - - неявне виявлення reply-to-bot (відправник відповіді збігається з ідентичністю бота) + - транскрипти вхідних voice-note для авторизованих групових повідомлень + - неявне виявлення reply-to-bot (відправник відповіді відповідає ідентичності бота) Примітка щодо безпеки: - - quote/reply лише задовольняє gating за згадкою; він **не** надає авторизацію відправнику - - з `groupPolicy: "allowlist"` відправники, яких немає в allowlist, усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача з allowlist + - цитата/відповідь лише задовольняє вимогу згадки; вона **не** надає авторизацію відправнику + - з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо відповідають на повідомлення користувача з allowlist Команда активації на рівні сеансу: @@ -283,19 +282,19 @@ WhatsApp не транслює вхідні payload `message_received` hook до ## Поведінка особистого номера та self-chat -Коли прив’язаний власний номер також присутній у `allowFrom`, активуються захисти self-chat WhatsApp: +Коли пов'язаний власний номер також присутній у `allowFrom`, активуються захисти self-chat WhatsApp: -- пропускати read receipts для turns self-chat -- ігнорувати поведінку автоматичного запуску mention-JID, яка інакше пінгувала б вас -- якщо `messages.responsePrefix` не задано, відповіді self-chat типово мають префікс `[{identity.name}]` або `[openclaw]` +- пропускати read receipts для ходів self-chat +- ігнорувати поведінку auto-trigger mention-JID, яка інакше ping-нула б вас +- якщо `messages.responsePrefix` не задано, відповіді self-chat типово використовують `[{identity.name}]` або `[openclaw]` ## Нормалізація повідомлень і контекст - - Вхідні повідомлення WhatsApp обгортаються у спільний вхідний envelope. + + Вхідні повідомлення WhatsApp обгортаються у спільну вхідну оболонку. - Якщо існує цитована відповідь, контекст додається в такій формі: + Якщо існує процитована відповідь, контекст додається в такій формі: ```text [Replying to id:] @@ -303,16 +302,16 @@ WhatsApp не транслює вхідні payload `message_received` hook до [/Replying] ``` - Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника). - Коли ціль цитованої відповіді — медіа, яке можна завантажити, OpenClaw зберігає його через - звичайне сховище вхідних медіа та показує як `MediaPath`/`MediaType`, щоб - агент міг переглянути згадане зображення, а не бачив лише + Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164). + Коли ціль процитованої відповіді — медіа, яке можна завантажити, OpenClaw зберігає його через + звичайне сховище вхідних медіа й надає як `MediaPath`/`MediaType`, щоб + агент міг оглянути згадане зображення, а не бачити лише ``. - - Вхідні повідомлення лише з медіа нормалізуються з placeholders, такими як: + + Вхідні повідомлення лише з медіа нормалізуються із заповнювачами, такими як: - `` - `` @@ -320,24 +319,24 @@ WhatsApp не транслює вхідні payload `message_received` hook до - `` - `` - Авторизовані групові voice notes транскрибуються перед gating за згадкою, коли - body містить лише ``, тому вимовляння згадки бота у voice note може - запустити відповідь. Якщо транскрипт усе ще не згадує бота, - транскрипт зберігається в очікуваній історії групи замість сирого placeholder. + Авторизовані групові voice notes транскрибуються перед перевіркою згадки, коли + тіло містить лише ``, тож вимовлена згадка бота в voice note може + викликати відповідь. Якщо транскрипт усе ще не згадує бота, транскрипт + зберігається в очікуваній історії групи замість сирого заповнювача. - Тіла локацій використовують стислий текст координат. Мітки/коментарі локацій і деталі контакту/vCard відображаються як fenced недовірені метадані, а не inline текст prompt. + Тіла location використовують стислий текст координат. Мітки/коментарі location і деталі contact/vCard відображаються як fenced untrusted metadata, а не inline prompt text. - - Для груп необроблені повідомлення можуть буферизуватися та вставлятися як контекст, коли бота нарешті запускають. + + Для груп необроблені повідомлення можуть буферизуватися й додаватися як контекст, коли бот нарешті активується. - - типовий ліміт: `50` + - типове обмеження: `50` - конфігурація: `channels.whatsapp.historyLimit` - fallback: `messages.groupChat.historyLimit` - `0` вимикає - Маркери вставлення: + Маркери ін'єкції: - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` @@ -375,56 +374,56 @@ WhatsApp не транслює вхідні payload `message_received` hook до } ``` - Повороти самочату пропускають сповіщення про прочитання, навіть коли їх увімкнено глобально. + Ходи в чаті із самим собою пропускають сповіщення про прочитання, навіть коли їх увімкнено глобально. -## Доставка, поділ на фрагменти та медіа +## Доставка, фрагментація та медіа - + - стандартний ліміт фрагмента: `channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.chunkMode = "length" | "newline"` - - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім переходить до безпечного за довжиною поділу на фрагменти + - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечної за довжиною фрагментації - - підтримує зображення, відео, аудіо (голосову нотатку PTT) і документні payload-и - - аудіомедіа надсилається через Baileys payload `audio` з `ptt: true`, тому клієнти WhatsApp відображають його як голосову нотатку push-to-talk - - payload-и відповідей зберігають `audioAsVoice`; вихід голосової нотатки TTS для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM + - підтримує зображення, відео, аудіо (голосову нотатку PTT) і документні payload + - аудіомедіа надсилається через Baileys `audio` payload з `ptt: true`, тому клієнти WhatsApp відображають його як голосову нотатку push-to-talk + - payload відповіді зберігають `audioAsVoice`; вивід голосової нотатки TTS для WhatsApp залишається на цьому PTT-шляху, навіть коли provider повертає MP3 або WebM - нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими нотатками - - аудіо не у форматі Ogg, зокрема вихід Microsoft Edge TTS MP3/WebM, транскодується через `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT - - `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку й пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує auto-TTS для поточного чату WhatsApp + - аудіо не у форматі Ogg, включно з виводом Microsoft Edge TTS MP3/WebM, перекодовується за допомогою `ffmpeg` у 48 кГц моно Ogg/Opus перед PTT-доставкою + - `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку й пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує авто-TTS для поточного чату WhatsApp - відтворення анімованих GIF підтримується через `gifPlayback: true` під час надсилання відео - - підписи застосовуються до першого медіаелемента під час надсилання payload-ів відповіді з кількома медіа, окрім голосових нотаток PTT: для них спочатку надсилається аудіо, а видимий текст окремо, бо клієнти WhatsApp не відображають підписи голосових нотаток стабільно + - підписи застосовуються до першого медіаелемента під час надсилання payload відповіді з кількома медіа, крім голосових нотаток PTT: для них спочатку надсилається аудіо, а видимий текст окремо, бо клієнти WhatsApp не відображають підписи до голосових нотаток стабільно - джерелом медіа може бути HTTP(S), `file://` або локальні шляхи - - - ліміт збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`) - - ліміт надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`) + + - ліміт збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (стандартно `50`) + - ліміт надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (стандартно `50`) - перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..mediaMaxMb` - - зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб уміститися в ліміти - - у разі помилки надсилання медіа резервна поведінка для першого елемента надсилає текстове попередження замість тихого відкидання відповіді + - зображення автоматично оптимізуються (зміна розміру/перебір якості), щоб укластися в ліміти + - у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість мовчазного відкидання відповіді ## Цитування відповіді -WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим через `channels.whatsapp.replyToMode`. +WhatsApp підтримує нативне цитування відповіді, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте ним за допомогою `channels.whatsapp.replyToMode`. -| Значення | Поведінка | -| ----------- | ------------------------------------------------------------------- | -| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення | -| `"first"` | Цитувати лише перший фрагмент вихідної відповіді | -| `"all"` | Цитувати кожен фрагмент вихідної відповіді | +| Значення | Поведінка | +| ----------- | ---------------------------------------------------------------------- | +| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення | +| `"first"` | Цитувати лише перший фрагмент вихідної відповіді | +| `"all"` | Цитувати кожен фрагмент вихідної відповіді | | `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування | -Типово: `"off"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..replyToMode`. +Стандартне значення — `"off"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..replyToMode`. ```json5 { @@ -438,16 +437,16 @@ WhatsApp підтримує нативне цитування відповіде ## Рівень реакцій -`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції у WhatsApp: +`channels.whatsapp.reactionLevel` керує тим, наскільки широко agent використовує emoji-реакції у WhatsApp: -| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис | -| ------------- | ----------- | ---------------------------- | --------------------------------------------------- | -| `"off"` | Ні | Ні | Жодних реакцій | -| `"ack"` | Так | Ні | Лише Ack-реакції (квитанція перед відповіддю) | -| `"minimal"` | Так | Так (консервативно) | Ack + реакції агента з консервативними вказівками | -| `"extensive"` | Так | Так (заохочується) | Ack + реакції агента із заохочувальними вказівками | +| Рівень | Реакції підтвердження | Реакції, ініційовані agent | Опис | +| ------------ | --------------------- | -------------------------- | -------------------------------------------------- | +| `"off"` | Ні | Ні | Жодних реакцій | +| `"ack"` | Так | Ні | Лише реакції підтвердження (підтвердження перед відповіддю) | +| `"minimal"` | Так | Так (обережно) | Підтвердження + реакції agent з обережними настановами | +| `"extensive"` | Так | Так (заохочується) | Підтвердження + реакції agent із заохочувальними настановами | -Типово: `"minimal"`. +Стандартно: `"minimal"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..reactionLevel`. @@ -463,8 +462,8 @@ WhatsApp підтримує нативне цитування відповіде ## Реакції підтвердження -WhatsApp підтримує негайні Ack-реакції після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`. -Ack-реакції обмежуються `reactionLevel` — їх пригнічено, коли `reactionLevel` дорівнює `"off"`. +WhatsApp підтримує негайні реакції підтвердження при отриманні вхідного повідомлення через `channels.whatsapp.ackReaction`. +Реакції підтвердження залежать від `reactionLevel` — вони пригнічуються, коли `reactionLevel` дорівнює `"off"`. ```json5 { @@ -484,30 +483,30 @@ Ack-реакції обмежуються `reactionLevel` — їх пригні - надсилаються негайно після прийняття вхідного повідомлення (перед відповіддю) - помилки журналюються, але не блокують нормальну доставку відповіді -- груповий режим `mentions` реагує на повороти, спричинені згадкою; активація групи `always` діє як обхід цієї перевірки -- WhatsApp використовує `channels.whatsapp.ackReaction` (застаріле `messages.ackReaction` тут не використовується) +- груповий режим `mentions` реагує на ходи, запущені згадкою; групова активація `always` діє як обхід для цієї перевірки +- WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується) ## Кілька облікових записів і облікові дані - ідентифікатори облікових записів беруться з `channels.whatsapp.accounts` - - стандартний вибір облікового запису: `default`, якщо він присутній, інакше перший налаштований ідентифікатор облікового запису (відсортований) - - ідентифікатори облікових записів нормалізуються внутрішньо для пошуку + - стандартний вибір облікового запису: `default`, якщо він наявний, інакше перший налаштований ідентифікатор облікового запису (відсортовано) + - ідентифікатори облікових записів внутрішньо нормалізуються для пошуку - + - поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp//creds.json` - файл резервної копії: `creds.json.bak` - - застаріла стандартна автентифікація в `~/.openclaw/credentials/` досі розпізнається/мігрується для потоків стандартного облікового запису + - застаріла стандартна автентифікація в `~/.openclaw/credentials/` усе ще розпізнається/мігрується для потоків стандартного облікового запису `openclaw channels logout --channel whatsapp [--account ]` очищає стан автентифікації WhatsApp для цього облікового запису. - Коли Gateway доступний, вихід спочатку зупиняє активний слухач WhatsApp для вибраного облікового запису, щоб пов'язана сесія не продовжувала отримувати повідомлення до наступного перезапуску. `openclaw channels remove --channel whatsapp` також зупиняє активний слухач перед вимкненням або видаленням конфігурації облікового запису. + Коли Gateway доступний, вихід спочатку зупиняє активний слухач WhatsApp для вибраного облікового запису, щоб пов’язана сесія не продовжувала отримувати повідомлення до наступного перезапуску. `openclaw channels remove --channel whatsapp` також зупиняє активний слухач перед вимкненням або видаленням конфігурації облікового запису. У застарілих каталогах автентифікації `oauth.json` зберігається, а файли автентифікації Baileys видаляються. @@ -516,17 +515,17 @@ Ack-реакції обмежуються `reactionLevel` — їх пригні ## Інструменти, дії та записи конфігурації -- Підтримка інструментів агента охоплює дію реакції WhatsApp (`react`). +- Підтримка інструментів agent включає дію реакції WhatsApp (`react`). - Обмежувачі дій: - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- Записи конфігурації, ініційовані каналом, увімкнено типово (вимикається через `channels.whatsapp.configWrites=false`). +- Записи конфігурації, ініційовані каналом, увімкнені стандартно (вимикаються через `channels.whatsapp.configWrites=false`). ## Усунення несправностей - - Симптом: статус каналу повідомляє, що він не пов'язаний. + + Симптом: статус каналу повідомляє, що його не пов’язано. Виправлення: @@ -537,17 +536,17 @@ Ack-реакції обмежуються `reactionLevel` — їх пригні - - Симптом: пов'язаний обліковий запис із повторними від'єднаннями або спробами повторного підключення. + + Симптом: пов’язаний обліковий запис із повторюваними від’єднаннями або спробами повторного підключення. - Тихі облікові записи можуть залишатися підключеними після звичайного тайм-ауту повідомлень; watchdog - перезапускається, коли транспортна активність WhatsApp Web зупиняється, сокет закривається або - активність на рівні застосунку залишається беззвучною довше за довше вікно безпеки. + Тихі облікові записи можуть залишатися підключеними після звичайного тайм-ауту повідомлення; watchdog + перезапускається, коли зупиняється активність транспорту WhatsApp Web, сокет закривається або + активність на рівні застосунку лишається беззвучною довше за подовжене вікно безпеки. Якщо журнали показують повторюване `status=408 Request Time-out Connection was lost`, налаштуйте таймінги сокета Baileys у `web.whatsapp`. Почніть зі скорочення `keepAliveIntervalMs` нижче тайм-ауту простою вашої мережі та збільшення - `connectTimeoutMs` на повільних або нестабільних з'єднаннях: + `connectTimeoutMs` на повільних або нестабільних з’єднаннях: ```json5 { @@ -568,49 +567,49 @@ Ack-реакції обмежуються `reactionLevel` — їх пригні openclaw logs --follow ``` - Якщо `~/.openclaw/logs/whatsapp-health.log` повідомляє `Gateway inactive`, але + Якщо `~/.openclaw/logs/whatsapp-health.log` каже `Gateway inactive`, але `openclaw gateway status` і `openclaw channels status --probe` показують, що gateway і WhatsApp справні, запустіть `openclaw doctor`. У Linux doctor - попереджає про застарілі записи crontab, які досі викликають - `~/.openclaw/bin/ensure-whatsapp.sh`; видаліть ці застарілі записи через - `crontab -e`, бо cron може не мати середовища користувацької шини systemd і - змушувати старий скрипт хибно звітувати про стан gateway. + попереджає про застарілі записи crontab, які все ще викликають + `~/.openclaw/bin/ensure-whatsapp.sh`; видаліть ці застарілі записи за допомогою + `crontab -e`, бо cron може не мати середовища systemd user-bus і + змушувати старий скрипт неправильно повідомляти про стан gateway. - За потреби повторно пов'яжіть через `channels login`. + За потреби повторно пов’яжіть через `channels login`. - - Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або від'єднанням TLS-сокета. + + Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або від’єднанням TLS-сокета. - Вхід у WhatsApp Web використовує стандартне проксі-середовище хоста gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Перевірте, що процес gateway успадковує проксі-змінні середовища і що `NO_PROXY` не відповідає `mmg.whatsapp.net`. + Вхід у WhatsApp Web використовує стандартне проксі-середовище хоста gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Перевірте, що процес gateway успадковує проксі-env і що `NO_PROXY` не збігається з `mmg.whatsapp.net`. Вихідні надсилання швидко завершуються помилкою, коли для цільового облікового запису немає активного слухача gateway. - Переконайтеся, що gateway запущений, а обліковий запис пов'язано. + Переконайтеся, що gateway запущено, а обліковий запис пов’язано. - - Рядки транскрипту записують те, що згенерував агент. Доставка WhatsApp перевіряється окремо: OpenClaw вважає автоматичну відповідь надісланою лише після того, як Baileys повертає ідентифікатор вихідного повідомлення принаймні для одного видимого текстового або медіа-надсилання. + + Рядки transcript записують те, що згенерував agent. Доставка WhatsApp перевіряється окремо: OpenClaw вважає автоматичну відповідь надісланою лише після того, як Baileys поверне ідентифікатор вихідного повідомлення принаймні для одного видимого текстового або медійного надсилання. - Ack-реакції є незалежними квитанціями перед відповіддю. Успішна реакція не доводить, що пізніша текстова або медіа-відповідь була прийнята WhatsApp. + Реакції підтвердження є незалежними підтвердженнями перед відповіддю. Успішна реакція не доводить, що пізнішу текстову або медіавідповідь було прийнято WhatsApp. Перевірте журнали gateway на `auto-reply delivery failed` або `auto-reply was not accepted by WhatsApp provider`. - + Перевіряйте в такому порядку: - `groupPolicy` - `groupAllowFrom` / `allowFrom` - записи allowlist у `groups` - - обмеження згадками (`requireMention` + шаблони згадок) - - дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому залишайте один `groupPolicy` на кожну область + - обмеження за згадками (`requireMention` + шаблони згадок) + - дублікати ключів в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому залишайте один `groupPolicy` для кожної області @@ -619,36 +618,36 @@ Ack-реакції обмежуються `reactionLevel` — їх пригні -## Системні промпти +## Системні prompts -WhatsApp підтримує системні промпти в стилі Telegram для груп і прямих чатів через мапи `groups` і `direct`. +WhatsApp підтримує системні prompts у стилі Telegram для груп і прямих чатів через мапи `groups` і `direct`. -Ієрархія розв'язання для групових повідомлень: +Ієрархія розв’язання для групових повідомлень: -Ефективна мапа `groups` визначається першою: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук промпта виконується на отриманій єдиній мапі: +Ефективна мапа `groups` визначається першою: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується на отриманій єдиній мапі: -1. **Системний промпт конкретної групи** (`groups[""].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний промпт не застосовується. -2. **Wildcard-системний промпт групи** (`groups["*"].systemPrompt`): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. +1. **Системний prompt для конкретної групи** (`groups[""].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується. +2. **Wildcard системний prompt для групи** (`groups["*"].systemPrompt`): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. -Ієрархія розв'язання для прямих повідомлень: +Ієрархія розв’язання для прямих повідомлень: -Ефективна мапа `direct` визначається першою: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук промпта виконується на отриманій єдиній мапі: +Ефективна мапа `direct` визначається першою: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується на отриманій єдиній мапі: -1. **Системний промпт конкретного прямого чату** (`direct[""].systemPrompt`): використовується, коли конкретний запис співрозмовника існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний промпт не застосовується. -2. **Wildcard-системний промпт прямого чату** (`direct["*"].systemPrompt`): використовується, коли конкретний запис співрозмовника повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. +1. **Системний prompt для конкретного direct** (`direct[""].systemPrompt`): використовується, коли конкретний запис peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується. +2. **Wildcard системний prompt для direct** (`direct["*"].systemPrompt`): використовується, коли конкретний запис peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. -`dms` залишається легким контейнером перевизначень історії для окремих DM (`dms..historyLimit`). Перевизначення промптів розміщуються в `direct`. +`dms` лишається полегшеним контейнером перевизначень історії для кожного DM (`dms..historyLimit`). Перевизначення prompt розміщуються в `direct`. -**Відмінність від поведінки Telegram з кількома обліковими записами:** У Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у налаштуванні з кількома обліковими записами — навіть для облікових записів, які не визначають власних `groups`, — щоб бот не отримував групові повідомлення з груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і кореневий `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У налаштуванні WhatsApp з кількома обліковими записами, якщо потрібні окремі для кожного облікового запису групові або прямі підказки, явно визначайте повну мапу в кожному обліковому записі, а не покладайтеся на типові значення кореневого рівня. +**Відмінність від поведінки кількох облікових записів Telegram:** У Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у налаштуванні з кількома обліковими записами — навіть для облікових записів, які не визначають власних `groups`, — щоб запобігти отриманню ботом групових повідомлень із груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і кореневий `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У налаштуванні WhatsApp із кількома обліковими записами, якщо вам потрібні окремі групові або прямі промпти для кожного облікового запису, явно визначте повну мапу під кожним обліковим записом, а не покладайтеся на типові значення кореневого рівня. Важлива поведінка: -- `channels.whatsapp.groups` є і мапою конфігурації для кожної групи, і дозвільним списком груп на рівні чату. У кореневій області або області облікового запису `groups["*"]` означає "усі групи допускаються" для цієї області. -- Додавайте груповий символ узагальнення `systemPrompt` лише тоді, коли вже потрібно, щоб ця область допускала всі групи. Якщо все ще потрібно, щоб придатним був лише фіксований набір ID груп, не використовуйте `groups["*"]` як типову підказку. Натомість повторіть підказку в кожному явно дозволеному записі групи. -- Допуск групи й авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників і далі окремо контролюється `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`. -- `channels.whatsapp.direct` не має такого самого побічного ефекту для приватних повідомлень. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як приватне повідомлення вже допущено правилами `dmPolicy` плюс `allowFrom` або сховища сполучень. +- `channels.whatsapp.groups` є одночасно мапою конфігурації для кожної групи та списком дозволених груп на рівні чату. На кореневому рівні або в межах облікового запису `groups["*"]` означає «усі групи дозволені» для цієї області. +- Додавайте груповий wildcard `systemPrompt` лише тоді, коли ви вже хочете, щоб ця область дозволяла всі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ID груп, не використовуйте `groups["*"]` для типового промпта. Натомість повторіть промпт у кожному явно дозволеному записі групи. +- Допуск групи та авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників усе ще окремо контролюється `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`. +- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як DM уже допущено через `dmPolicy` разом із `allowFrom` або правилами сховища спарювання. Приклад: @@ -690,26 +689,26 @@ WhatsApp підтримує системні промпти в стилі Telegr } ``` -## Вказівники до довідника конфігурації +## Вказівники довідника конфігурації Основний довідник: - [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp) -Поля WhatsApp з високою цінністю сигналу: +Важливі поля WhatsApp: - доступ: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups` -- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel` +- доставлення: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel` - кілька облікових записів: `accounts..enabled`, `accounts..authDir`, перевизначення на рівні облікового запису - операції: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*` -- поведінка сесії: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` -- підказки: `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt` +- поведінка сеансу: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` +- промпти: `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt` ## Пов’язане -- [Сполучення](/uk/channels/pairing) +- [Спарювання](/uk/channels/pairing) - [Групи](/uk/channels/groups) - [Безпека](/uk/gateway/security) - [Маршрутизація каналів](/uk/channels/channel-routing) -- [Маршрутизація між агентами](/uk/concepts/multi-agent) +- [Маршрутизація кількох агентів](/uk/concepts/multi-agent) - [Усунення несправностей](/uk/channels/troubleshooting) diff --git a/docs/uk/channels/zalo.md b/docs/uk/channels/zalo.md index 80e7d8e69..5d3f835af 100644 --- a/docs/uk/channels/zalo.md +++ b/docs/uk/channels/zalo.md @@ -1,41 +1,42 @@ --- read_when: - - Робота над функціями Zalo або Webhook-ами + - Робота над функціями Zalo або Webhook summary: Стан підтримки бота Zalo, можливості та конфігурація title: Zalo x-i18n: - generated_at: "2026-04-29T05:37:51Z" + generated_at: "2026-05-02T21:04:36Z" model: gpt-5.5 provider: openai - source_hash: e79a4a27accc7f460bd3ae9c01e8f5f80e21a285af5d89b94bb9c89244a4438f + source_hash: 65c9bdb0994228a6916e52c35fa6ea8d09b9b686bb9dac1c74cb38b3e6db1e48 source_path: channels/zalo.md workflow: 16 --- -Status: експериментально. DM підтримуються. Розділ [Можливості](#capabilities) нижче відображає поточну поведінку ботів Marketplace. +Status: експериментальний. Особисті повідомлення підтримуються. Розділ [Можливості](#capabilities) нижче відображає поточну поведінку ботів Marketplace. -## Вбудований plugin +## Вбудований Plugin -Zalo постачається як вбудований plugin у поточних випусках OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення. +Zalo постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні пакетовані +збірки не потребують окремого встановлення. -Якщо ви використовуєте старішу збірку або користувацьке встановлення, яке не містить Zalo, встановіть поточний npm-пакет, коли його буде опубліковано: +Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Zalo, встановіть +npm-пакет напряму: - Встановити через CLI: `openclaw plugins install @openclaw/zalo` -- Або з вихідного checkout: `openclaw plugins install ./path/to/local/zalo-plugin` -- Докладно: [Plugins](/uk/tools/plugin) - -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, використовуйте поточну пакетовану збірку OpenClaw або шлях до локального checkout, доки не буде опубліковано новіший npm-пакет. +- Бета-канал: `openclaw plugins install @openclaw/zalo@beta` +- Або з checkout вихідного коду: `openclaw plugins install ./path/to/local/zalo-plugin` +- Докладніше: [Plugins](/uk/tools/plugin) ## Швидке налаштування (для початківців) -1. Переконайтеся, що plugin Zalo доступний. +1. Переконайтеся, що Plugin Zalo доступний. - Поточні пакетовані випуски OpenClaw уже містять його. - - Старіші/користувацькі встановлення можуть додати його вручну командами вище. + - У старіших/власних встановленнях його можна додати вручну командами вище. 2. Задайте токен: - Env: `ZALO_BOT_TOKEN=...` - - Або config: `channels.zalo.accounts.default.botToken: "..."`. + - Або конфігурація: `channels.zalo.accounts.default.botToken: "..."`. 3. Перезапустіть gateway (або завершіть налаштування). -4. Доступ до DM за замовчуванням виконується через pairing; підтвердьте код pairing під час першого контакту. +4. Доступ до особистих повідомлень типово використовує спарювання; підтвердьте код спарювання під час першого контакту. Мінімальна конфігурація: @@ -55,17 +56,17 @@ Zalo постачається як вбудований plugin у поточни } ``` -## Що це +## Що це таке -Zalo — це застосунок для обміну повідомленнями, орієнтований на В’єтнам; його Bot API дає Gateway змогу запускати бота для розмов 1:1. +Zalo — месенджер, орієнтований на В’єтнам; його Bot API дає змогу Gateway запускати бота для розмов 1:1. Це добре підходить для підтримки або сповіщень, коли потрібна детермінована маршрутизація назад у Zalo. -Ця сторінка відображає поточну поведінку OpenClaw для **ботів Zalo Bot Creator / Marketplace**. -**Боти Zalo Official Account (OA)** — це інша продуктова поверхня Zalo, і вона може поводитися інакше. +Ця сторінка відображає поточну поведінку OpenClaw для **Zalo Bot Creator / ботів Marketplace**. +**Боти Zalo Official Account (OA)** — це інша поверхня продукту Zalo, і вони можуть поводитися інакше. - Канал Zalo Bot API, яким володіє Gateway. - Детермінована маршрутизація: відповіді повертаються в Zalo; модель ніколи не вибирає канали. -- DM спільно використовують основну сесію агента. +- Особисті повідомлення використовують основну сесію агента. - Розділ [Можливості](#capabilities) нижче показує поточну підтримку ботів Marketplace. ## Налаштування (швидкий шлях) @@ -74,9 +75,9 @@ Zalo — це застосунок для обміну повідомлення 1. Перейдіть на [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) і ввійдіть. 2. Створіть нового бота й налаштуйте його параметри. -3. Скопіюйте повний токен бота (зазвичай `numeric_id:secret`). Для ботів Marketplace придатний для виконання токен може з’явитися у привітальному повідомленні бота після створення. +3. Скопіюйте повний токен бота (зазвичай `numeric_id:secret`). Для ботів Marketplace придатний для виконання токен може з’явитися у вітальному повідомленні бота після створення. -### 2) Налаштуйте токен (env або config) +### 2) Налаштуйте токен (env або конфігурація) Приклад: @@ -96,107 +97,107 @@ Zalo — це застосунок для обміну повідомлення } ``` -Якщо пізніше ви перейдете на поверхню бота Zalo, де доступні групи, можна явно додати конфігурацію для груп, як-от `groupPolicy` і `groupAllowFrom`. Для поточної поведінки ботів Marketplace див. [Можливості](#capabilities). +Якщо згодом ви перейдете на поверхню бота Zalo, де доступні групи, можна явно додати групову конфігурацію, як-от `groupPolicy` і `groupAllowFrom`. Для поточної поведінки ботів Marketplace див. [Можливості](#capabilities). -Опція env: `ZALO_BOT_TOKEN=...` (працює лише для облікового запису за замовчуванням). +Варіант env: `ZALO_BOT_TOKEN=...` (працює лише для облікового запису за замовчуванням). -Підтримка кількох облікових записів: використовуйте `channels.zalo.accounts` із токенами для кожного облікового запису та необов’язковим `name`. +Підтримка кількох облікових записів: використовуйте `channels.zalo.accounts` з окремими токенами для кожного облікового запису та необов’язковим `name`. -3. Перезапустіть gateway. Zalo запускається, коли токен визначено (env або config). -4. Доступ до DM за замовчуванням використовує pairing. Підтвердьте код, коли з ботом уперше зв’яжуться. +3. Перезапустіть gateway. Zalo запускається, коли токен визначено (env або конфігурація). +4. Доступ до особистих повідомлень типово використовує спарювання. Підтвердьте код під час першого контакту з ботом. ## Як це працює (поведінка) -- Вхідні повідомлення нормалізуються у спільний envelope каналу з placeholder медіа. +- Вхідні повідомлення нормалізуються у спільний конверт каналу із заповнювачами медіа. - Відповіді завжди маршрутизуються назад у той самий чат Zalo. -- За замовчуванням використовується long-polling; режим webhook доступний через `channels.zalo.webhookUrl`. +- Типово використовується довге опитування; режим webhook доступний через `channels.zalo.webhookUrl`. ## Обмеження -- Вихідний текст розбивається на фрагменти по 2000 символів (обмеження Zalo API). -- Завантаження/вивантаження медіа обмежені `channels.zalo.mediaMaxMb` (за замовчуванням 5). -- Streaming за замовчуванням заблоковано, бо обмеження 2000 символів робить streaming менш корисним. +- Вихідний текст розбивається на фрагменти по 2000 символів (ліміт Zalo API). +- Завантаження/вивантаження медіа обмежуються `channels.zalo.mediaMaxMb` (типово 5). +- Streaming типово заблоковано, оскільки ліміт у 2000 символів робить Streaming менш корисним. -## Керування доступом (DM) +## Контроль доступу (особисті повідомлення) -### Доступ до DM +### Доступ до особистих повідомлень -- За замовчуванням: `channels.zalo.dmPolicy = "pairing"`. Невідомі відправники отримують код pairing; повідомлення ігноруються, доки їх не буде підтверджено (коди спливають через 1 годину). -- Підтвердити через: +- За замовчуванням: `channels.zalo.dmPolicy = "pairing"`. Невідомі відправники отримують код спарювання; повідомлення ігноруються, доки доступ не буде підтверджено (коди спливають через 1 годину). +- Підтвердження через: - `openclaw pairing list zalo` - `openclaw pairing approve zalo ` -- Pairing — це типовий обмін токеном. Докладно: [Pairing](/uk/channels/pairing) -- `channels.zalo.allowFrom` приймає числові ідентифікатори користувачів (пошук за username недоступний). +- Спарювання — стандартний обмін токеном. Докладніше: [Спарювання](/uk/channels/pairing) +- `channels.zalo.allowFrom` приймає числові ідентифікатори користувачів (пошук за іменем користувача недоступний). -## Керування доступом (групи) +## Контроль доступу (групи) -Для **ботів Zalo Bot Creator / Marketplace** підтримка груп на практиці була недоступна, бо бота взагалі не можна було додати до групи. +Для **Zalo Bot Creator / ботів Marketplace** підтримка груп на практиці була недоступна, оскільки бота взагалі не можна було додати до групи. -Це означає, що наведені нижче ключі конфігурації, пов’язані з групами, існують у схемі, але не були придатні для використання з ботами Marketplace: +Це означає, що наведені нижче ключі групової конфігурації існують у схемі, але не були придатні для використання з ботами Marketplace: -- `channels.zalo.groupPolicy` керує обробкою вхідних повідомлень у групах: `open | allowlist | disabled`. +- `channels.zalo.groupPolicy` керує обробкою вхідних групових повідомлень: `open | allowlist | disabled`. - `channels.zalo.groupAllowFrom` обмежує, які ідентифікатори відправників можуть запускати бота в групах. -- Якщо `groupAllowFrom` не задано, Zalo повертається до `allowFrom` для перевірок відправників. -- Примітка runtime: якщо `channels.zalo` повністю відсутній, runtime все одно повертається до `groupPolicy="allowlist"` для безпеки. +- Якщо `groupAllowFrom` не задано, Zalo повертається до `allowFrom` для перевірок відправника. +- Примітка щодо виконання: якщо `channels.zalo` повністю відсутній, runtime все одно повертається до `groupPolicy="allowlist"` задля безпеки. -Значення групової політики (коли доступ до груп доступний на вашій поверхні бота): +Значення групової політики (коли груповий доступ доступний на вашій поверхні бота): - `groupPolicy: "disabled"` — блокує всі групові повідомлення. -- `groupPolicy: "open"` — дозволяє будь-якого учасника групи (з gating за згадкою). -- `groupPolicy: "allowlist"` — типовий fail-closed варіант; приймаються лише дозволені відправники. +- `groupPolicy: "open"` — дозволяє будь-якому учаснику групи (з обмеженням через згадку). +- `groupPolicy: "allowlist"` — стандартне fail-closed значення; приймаються лише дозволені відправники. -Якщо ви використовуєте іншу продуктову поверхню бота Zalo і підтвердили робочу поведінку груп, задокументуйте це окремо, а не припускайте, що вона збігається з потоком ботів Marketplace. +Якщо ви використовуєте іншу поверхню продукту бота Zalo і перевірили робочу групову поведінку, задокументуйте це окремо, а не припускайте, що вона збігається з потоком ботів Marketplace. -## Long-polling проти webhook +## Довге опитування проти webhook -- За замовчуванням: long-polling (публічний URL не потрібен). +- За замовчуванням: довге опитування (публічна URL-адреса не потрібна). - Режим webhook: задайте `channels.zalo.webhookUrl` і `channels.zalo.webhookSecret`. - Секрет webhook має містити 8-256 символів. - URL webhook має використовувати HTTPS. - Zalo надсилає події із заголовком `X-Bot-Api-Secret-Token` для перевірки. - - Gateway HTTP обробляє webhook-запити за `channels.zalo.webhookPath` (за замовчуванням шлях URL webhook). - - Запити мають використовувати `Content-Type: application/json` (або типи медіа `+json`). - - Дублікати подій (`event_name + message_id`) ігноруються протягом короткого replay-вікна. - - Burst-трафік обмежується за частотою для кожного шляху/джерела і може повертати HTTP 429. + - Gateway HTTP обробляє запити webhook за `channels.zalo.webhookPath` (типово шлях URL webhook). + - Запити мають використовувати `Content-Type: application/json` (або медіатипи `+json`). + - Дублікати подій (`event_name + message_id`) ігноруються протягом короткого вікна повторного відтворення. + - Піковий трафік обмежується за швидкістю для кожного шляху/джерела й може повертати HTTP 429. -**Примітка:** getUpdates (polling) і webhook взаємовиключні згідно з документацією Zalo API. +**Примітка:** getUpdates (опитування) і webhook взаємовиключні згідно з документацією Zalo API. ## Підтримувані типи повідомлень -Для короткого знімка підтримки див. [Можливості](#capabilities). Примітки нижче додають подробиці там, де поведінка потребує додаткового контексту. +Короткий огляд підтримки див. у [Можливості](#capabilities). Примітки нижче додають подробиці там, де поведінка потребує додаткового контексту. -- **Текстові повідомлення**: Повна підтримка з розбиттям на фрагменти по 2000 символів. -- **Звичайні URL у тексті**: Поводяться як звичайний текстовий ввід. -- **Попередні перегляди посилань / картки rich link**: Див. статус ботів Marketplace у [Можливості](#capabilities); вони не запускали відповідь надійно. -- **Повідомлення із зображеннями**: Див. статус ботів Marketplace у [Можливості](#capabilities); обробка вхідних зображень була ненадійною (індикатор набору без фінальної відповіді). -- **Стікери**: Див. статус ботів Marketplace у [Можливості](#capabilities). -- **Голосові нотатки / аудіофайли / відео / звичайні файлові вкладення**: Див. статус ботів Marketplace у [Можливості](#capabilities). -- **Непідтримувані типи**: Логуються (наприклад, повідомлення від захищених користувачів). +- **Текстові повідомлення**: повна підтримка з розбиттям на фрагменти по 2000 символів. +- **Прості URL-адреси в тексті**: поводяться як звичайний текстовий ввід. +- **Попередній перегляд посилань / насичені картки посилань**: див. статус ботів Marketplace у [Можливості](#capabilities); вони не завжди надійно запускали відповідь. +- **Повідомлення із зображеннями**: див. статус ботів Marketplace у [Можливості](#capabilities); обробка вхідних зображень була ненадійною (індикатор набору без фінальної відповіді). +- **Стікери**: див. статус ботів Marketplace у [Можливості](#capabilities). +- **Голосові нотатки / аудіофайли / відео / загальні файлові вкладення**: див. статус ботів Marketplace у [Можливості](#capabilities). +- **Непідтримувані типи**: записуються в журнал (наприклад, повідомлення від захищених користувачів). ## Можливості -Ця таблиця підсумовує поточну поведінку **ботів Zalo Bot Creator / Marketplace** в OpenClaw. +Ця таблиця підсумовує поточну поведінку **Zalo Bot Creator / ботів Marketplace** в OpenClaw. | Функція | Статус | | --------------------------- | --------------------------------------- | -| Прямі повідомлення | ✅ Підтримується | -| Групи | ❌ Недоступно для ботів Marketplace | +| Прямі повідомлення | ✅ Підтримуються | +| Групи | ❌ Недоступні для ботів Marketplace | | Медіа (вхідні зображення) | ⚠️ Обмежено / перевірте у своєму середовищі | | Медіа (вихідні зображення) | ⚠️ Не перевірялося повторно для ботів Marketplace | -| Звичайні URL у тексті | ✅ Підтримується | -| Попередні перегляди посилань | ⚠️ Ненадійно для ботів Marketplace | -| Реакції | ❌ Не підтримується | +| Прості URL-адреси в тексті | ✅ Підтримуються | +| Попередній перегляд посилань | ⚠️ Ненадійний для ботів Marketplace | +| Реакції | ❌ Не підтримуються | | Стікери | ⚠️ Немає відповіді агента для ботів Marketplace | | Голосові нотатки / аудіо / відео | ⚠️ Немає відповіді агента для ботів Marketplace | | Файлові вкладення | ⚠️ Немає відповіді агента для ботів Marketplace | -| Threads | ❌ Не підтримується | -| Опитування | ❌ Не підтримується | -| Нативні команди | ❌ Не підтримується | -| Streaming | ⚠️ Заблоковано (обмеження 2000 символів) | +| Потоки | ❌ Не підтримуються | +| Опитування | ❌ Не підтримуються | +| Нативні команди | ❌ Не підтримуються | +| Streaming | ⚠️ Заблоковано (ліміт 2000 символів) | ## Цілі доставки (CLI/cron) -- Використовуйте chat id як ціль. +- Використовуйте ідентифікатор чату як ціль. - Приклад: `openclaw message send --channel zalo --target 123456789 --message "hi"`. ## Усунення несправностей @@ -204,56 +205,56 @@ Zalo — це застосунок для обміну повідомлення **Бот не відповідає:** - Перевірте, що токен чинний: `openclaw channels status --probe` -- Переконайтеся, що відправника підтверджено (pairing або allowFrom) +- Переконайтеся, що відправника підтверджено (спарювання або allowFrom) - Перевірте журнали gateway: `openclaw logs --follow` **Webhook не отримує події:** - Переконайтеся, що URL webhook використовує HTTPS - Перевірте, що секретний токен має 8-256 символів -- Підтвердьте, що HTTP-endpoint gateway доступний на налаштованому шляху -- Переконайтеся, що polling getUpdates не запущено (вони взаємовиключні) +- Підтвердьте, що HTTP endpoint gateway доступний за налаштованим шляхом +- Переконайтеся, що опитування getUpdates не запущене (вони взаємовиключні) ## Довідник конфігурації (Zalo) Повна конфігурація: [Конфігурація](/uk/gateway/configuration) -Плоскі ключі верхнього рівня (`channels.zalo.botToken`, `channels.zalo.dmPolicy` і подібні) — це застарілий shorthand для одного облікового запису. Для нових конфігурацій надавайте перевагу `channels.zalo.accounts..*`. Обидві форми все ще задокументовані тут, бо вони існують у схемі. +Плоскі ключі верхнього рівня (`channels.zalo.botToken`, `channels.zalo.dmPolicy` тощо) — це застаріле скорочення для одного облікового запису. Для нових конфігурацій віддавайте перевагу `channels.zalo.accounts..*`. Обидві форми все ще задокументовані тут, бо вони існують у схемі. -Опції provider: +Параметри провайдера: - `channels.zalo.enabled`: увімкнути/вимкнути запуск каналу. - `channels.zalo.botToken`: токен бота з Zalo Bot Platform. -- `channels.zalo.tokenFile`: читати токен зі шляху до звичайного файла. Symlink відхиляються. -- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (за замовчуванням: pairing). -- `channels.zalo.allowFrom`: allowlist для DM (ідентифікатори користувачів). `open` вимагає `"*"`. Wizard попросить числові ідентифікатори. -- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (за замовчуванням: allowlist). Присутній у config; див. [Можливості](#capabilities) і [Керування доступом (групи)](#access-control-groups) щодо поточної поведінки ботів Marketplace. -- `channels.zalo.groupAllowFrom`: allowlist відправників групи (ідентифікатори користувачів). Повертається до `allowFrom`, якщо не задано. -- `channels.zalo.mediaMaxMb`: ліміт вхідних/вихідних медіа (МБ, за замовчуванням 5). +- `channels.zalo.tokenFile`: читати токен зі звичайного шляху до файлу. Символьні посилання відхиляються. +- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (типово: pairing). +- `channels.zalo.allowFrom`: allowlist для особистих повідомлень (ідентифікатори користувачів). `open` потребує `"*"`. Майстер запитає числові ідентифікатори. +- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (типово: allowlist). Присутній у конфігурації; для поточної поведінки ботів Marketplace див. [Можливості](#capabilities) і [Контроль доступу (групи)](#access-control-groups). +- `channels.zalo.groupAllowFrom`: allowlist відправників групи (ідентифікатори користувачів). Якщо не задано, повертається до `allowFrom`. +- `channels.zalo.mediaMaxMb`: ліміт вхідних/вихідних медіа (МБ, типово 5). - `channels.zalo.webhookUrl`: увімкнути режим webhook (потрібен HTTPS). - `channels.zalo.webhookSecret`: секрет webhook (8-256 символів). - `channels.zalo.webhookPath`: шлях webhook на HTTP-сервері gateway. -- `channels.zalo.proxy`: URL proxy для API-запитів. +- `channels.zalo.proxy`: URL проксі для запитів API. -Опції кількох облікових записів: +Параметри кількох облікових записів: -- `channels.zalo.accounts..botToken`: токен для кожного облікового запису. -- `channels.zalo.accounts..tokenFile`: звичайний файл токена для кожного облікового запису. Symlink відхиляються. +- `channels.zalo.accounts..botToken`: токен для окремого облікового запису. +- `channels.zalo.accounts..tokenFile`: звичайний файл токена для окремого облікового запису. Символьні посилання відхиляються. - `channels.zalo.accounts..name`: відображуване ім’я. - `channels.zalo.accounts..enabled`: увімкнути/вимкнути обліковий запис. -- `channels.zalo.accounts..dmPolicy`: політика DM для кожного облікового запису. -- `channels.zalo.accounts..allowFrom`: allowlist для кожного облікового запису. -- `channels.zalo.accounts..groupPolicy`: групова політика для кожного облікового запису. Присутня в config; див. [Можливості](#capabilities) і [Керування доступом (групи)](#access-control-groups) щодо поточної поведінки ботів Marketplace. -- `channels.zalo.accounts..groupAllowFrom`: allowlist відправників групи для кожного облікового запису. -- `channels.zalo.accounts..webhookUrl`: URL webhook для кожного облікового запису. -- `channels.zalo.accounts..webhookSecret`: секрет webhook для кожного облікового запису. -- `channels.zalo.accounts..webhookPath`: шлях webhook для кожного облікового запису. -- `channels.zalo.accounts..proxy`: URL proxy для кожного облікового запису. +- `channels.zalo.accounts..dmPolicy`: політика особистих повідомлень для окремого облікового запису. +- `channels.zalo.accounts..allowFrom`: allowlist для окремого облікового запису. +- `channels.zalo.accounts..groupPolicy`: групова політика для окремого облікового запису. Присутня в конфігурації; для поточної поведінки ботів Marketplace див. [Можливості](#capabilities) і [Контроль доступу (групи)](#access-control-groups). +- `channels.zalo.accounts..groupAllowFrom`: allowlist відправників групи для окремого облікового запису. +- `channels.zalo.accounts..webhookUrl`: URL webhook для окремого облікового запису. +- `channels.zalo.accounts..webhookSecret`: секрет webhook для окремого облікового запису. +- `channels.zalo.accounts..webhookPath`: шлях webhook для окремого облікового запису. +- `channels.zalo.accounts..proxy`: URL проксі для окремого облікового запису. ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing -- [Групи](/uk/channels/groups) — поведінка групових чатів і gating за згадкою +- [Спарювання](/uk/channels/pairing) — автентифікація особистих повідомлень і потік спарювання +- [Групи](/uk/channels/groups) — поведінка групових чатів і обмеження за згадкою - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Безпека](/uk/gateway/security) — модель доступу й посилення захисту diff --git a/docs/uk/channels/zalouser.md b/docs/uk/channels/zalouser.md index 58bc06ad0..624404740 100644 --- a/docs/uk/channels/zalouser.md +++ b/docs/uk/channels/zalouser.md @@ -1,50 +1,47 @@ --- read_when: - Налаштування Zalo Personal для OpenClaw - - Налагодження входу в Zalo Personal або потоку повідомлень + - Налагодження входу або потоку повідомлень Zalo Personal summary: Підтримка особистого облікового запису Zalo через нативний zca-js (вхід за QR-кодом), можливості та конфігурація title: Особистий Zalo x-i18n: - generated_at: "2026-04-29T05:38:05Z" + generated_at: "2026-05-02T21:05:18Z" model: gpt-5.5 provider: openai - source_hash: 581a427f7fa37b0fa204f6b813c767eaa7af1f577baf2ac6ea3a31bf23ca6a49 + source_hash: a8bd665c47705e0213e1a7c05c3242d6ff745346cdee184da4884e5365807b2d source_path: channels/zalouser.md workflow: 16 --- -Статус: експериментально. Ця інтеграція автоматизує **особистий обліковий запис Zalo** через нативний `zca-js` усередині OpenClaw. +Статус: експериментально. Ця інтеграція автоматизує **особистий обліковий запис Zalo** через нативний `zca-js` всередині OpenClaw. Це неофіційна інтеграція, яка може призвести до призупинення або блокування облікового запису. Використовуйте на власний ризик. -## Вбудований plugin +## Вбудований плагін -Zalo Personal постачається як вбудований plugin у поточних випусках OpenClaw, тому звичайні +Zalo Personal постачається як вбудований плагін у поточних випусках OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення. -Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Zalo Personal, -установіть поточний npm-пакет, коли його буде опубліковано: +Якщо ви використовуєте старішу збірку або власне встановлення, яке не містить Zalo Personal, +встановіть npm-пакет напряму: -- Установити через CLI: `openclaw plugins install @openclaw/zalouser` +- Встановлення через CLI: `openclaw plugins install @openclaw/zalouser` +- Бета-канал: `openclaw plugins install @openclaw/zalouser@beta` - Або з checkout вихідного коду: `openclaw plugins install ./path/to/local/zalouser-plugin` -- Докладніше: [Plugins](/uk/tools/plugin) - -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, використовуйте поточну пакетовану -збірку OpenClaw або локальний шлях checkout, доки не буде -опубліковано новіший npm-пакет. +- Докладніше: [Плагіни](/uk/tools/plugin) Зовнішній CLI-бінарник `zca`/`openzca` не потрібен. ## Швидке налаштування (для початківців) -1. Переконайтеся, що plugin Zalo Personal доступний. +1. Переконайтеся, що плагін Zalo Personal доступний. - Поточні пакетовані випуски OpenClaw уже містять його. - - Старіші/власні встановлення можуть додати його вручну за допомогою команд вище. + - У старіших або власних встановленнях його можна додати вручну за допомогою команд вище. 2. Увійдіть (QR, на машині Gateway): - `openclaw channels login --channel zalouser` - - Відскануйте QR-код за допомогою мобільного застосунку Zalo. + - Відскануйте QR-код мобільним застосунком Zalo. 3. Увімкніть канал: ```json5 @@ -59,22 +56,22 @@ Zalo Personal постачається як вбудований plugin у по ``` 4. Перезапустіть Gateway (або завершіть налаштування). -5. Доступ до DM за замовчуванням використовує спарювання; підтвердьте код спарювання під час першого контакту. +5. Для доступу через DM типовим є pairing; підтвердьте код pairing під час першого контакту. ## Що це таке -- Працює повністю в процесі через `zca-js`. +- Працює повністю в межах процесу через `zca-js`. - Використовує нативні слухачі подій для отримання вхідних повідомлень. - Надсилає відповіді напряму через JS API (текст/медіа/посилання). - Призначено для сценаріїв використання “особистого облікового запису”, коли Zalo Bot API недоступний. ## Іменування -ID каналу — `zalouser`, щоб явно вказати, що це автоматизує **особистий обліковий запис користувача Zalo** (неофіційно). Ми залишаємо `zalo` зарезервованим для потенційної майбутньої офіційної інтеграції Zalo API. +Ідентифікатор каналу — `zalouser`, щоб явно показати, що це автоматизує **особистий обліковий запис користувача Zalo** (неофіційно). Ми залишаємо `zalo` зарезервованим для потенційної майбутньої офіційної інтеграції Zalo API. ## Пошук ID (каталог) -Використовуйте CLI каталогу, щоб знаходити співрозмовників/групи та їхні ID: +Використовуйте CLI каталогу, щоб знаходити peers/групи та їхні ID: ```bash openclaw directory self --channel zalouser @@ -85,33 +82,33 @@ openclaw directory groups list --channel zalouser --query "work" ## Обмеження - Вихідний текст розбивається на фрагменти приблизно по 2000 символів (обмеження клієнта Zalo). -- Потокове передавання за замовчуванням заблоковане. +- Streaming заблоковано за замовчуванням. ## Контроль доступу (DM) `channels.zalouser.dmPolicy` підтримує: `pairing | allowlist | open | disabled` (за замовчуванням: `pairing`). -`channels.zalouser.allowFrom` приймає ID користувачів або імена. Під час налаштування імена перетворюються на ID за допомогою внутрішньопроцесного пошуку контактів plugin. +`channels.zalouser.allowFrom` приймає ID або імена користувачів. Під час налаштування імена перетворюються на ID за допомогою внутрішньопроцесного пошуку контактів плагіна. -Підтверджуйте через: +Підтвердження через: - `openclaw pairing list zalouser` - `openclaw pairing approve zalouser ` ## Доступ до груп (необов’язково) -- За замовчуванням: `channels.zalouser.groupPolicy = "open"` (групи дозволені). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити стандартне значення, коли воно не задане. -- Обмежте списком дозволених: +- За замовчуванням: `channels.zalouser.groupPolicy = "open"` (групи дозволено). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, коли його не задано. +- Обмеження до allowlist: - `channels.zalouser.groupPolicy = "allowlist"` - - `channels.zalouser.groups` (ключами мають бути стабільні ID груп; імена перетворюються на ID під час запуску, коли це можливо) + - `channels.zalouser.groups` (ключами мають бути стабільні ID груп; імена за можливості перетворюються на ID під час запуску) - `channels.zalouser.groupAllowFrom` (керує тим, які відправники в дозволених групах можуть запускати бота) - Заблокувати всі групи: `channels.zalouser.groupPolicy = "disabled"`. -- Майстер налаштування може запитувати списки дозволених груп. -- Під час запуску OpenClaw перетворює імена груп/користувачів у списках дозволених на ID і записує відповідність у журнал. -- Зіставлення списку дозволених груп за замовчуванням виконується лише за ID. Нерозв’язані імена ігноруються для авторизації, якщо не ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`. -- `channels.zalouser.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який повторно вмикає змінюване зіставлення за назвою групи. +- Майстер налаштування може запитувати allowlist для груп. +- Під час запуску OpenClaw перетворює імена груп/користувачів в allowlist на ID і записує зіставлення в журнал. +- Зіставлення allowlist груп за замовчуванням виконується лише за ID. Нерозпізнані імена ігноруються для авторизації, якщо не ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`. +- `channels.zalouser.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який знову вмикає зіставлення за змінними іменами груп. - Якщо `groupAllowFrom` не задано, runtime повертається до `allowFrom` для перевірок відправників у групах. -- Перевірки відправників застосовуються як до звичайних групових повідомлень, так і до керівних команд (наприклад `/new`, `/reset`). +- Перевірки відправників застосовуються як до звичайних групових повідомлень, так і до керівних команд (наприклад, `/new`, `/reset`). Приклад: @@ -133,12 +130,12 @@ openclaw directory groups list --channel zalouser --query "work" ### Обмеження групових згадок - `channels.zalouser.groups..requireMention` керує тим, чи потрібна згадка для відповідей у групі. -- Порядок розв’язання: точний ID/назва групи -> нормалізований slug групи -> `*` -> стандартне значення (`true`). -- Це застосовується як до груп зі списку дозволених, так і до відкритого режиму груп. -- Цитування повідомлення бота зараховується як неявна згадка для активації в групі. -- Авторизовані керівні команди (наприклад `/new`) можуть обходити обмеження згадок. -- Коли групове повідомлення пропускається, бо потрібна згадка, OpenClaw зберігає його як очікувану історію групи та включає її до наступного обробленого групового повідомлення. -- Ліміт історії групи за замовчуванням дорівнює `messages.groupChat.historyLimit` (fallback `50`). Ви можете перевизначити його для окремого облікового запису через `channels.zalouser.historyLimit`. +- Порядок розв’язання: точний ID/ім’я групи -> нормалізований slug групи -> `*` -> стандартне значення (`true`). +- Це застосовується як до груп в allowlist, так і до режиму відкритих груп. +- Цитування повідомлення бота вважається неявною згадкою для активації в групі. +- Авторизовані керівні команди (наприклад, `/new`) можуть обходити обмеження згадки. +- Коли групове повідомлення пропускається через вимогу згадки, OpenClaw зберігає його як очікувану історію групи та додає її до наступного обробленого групового повідомлення. +- Ліміт історії групи за замовчуванням дорівнює `messages.groupChat.historyLimit` (резервне значення `50`). Його можна перевизначити для кожного облікового запису через `channels.zalouser.historyLimit`. Приклад: @@ -174,11 +171,11 @@ openclaw directory groups list --channel zalouser --query "work" } ``` -## Набір тексту, реакції та підтвердження доставки +## Введення, реакції та підтвердження доставки -- OpenClaw надсилає подію набору тексту перед відправленням відповіді (best-effort). +- OpenClaw надсилає подію введення перед відправленням відповіді (best-effort). - Дія реакції на повідомлення `react` підтримується для `zalouser` у діях каналу. - - Використовуйте `remove: true`, щоб прибрати певний emoji реакції з повідомлення. + - Використовуйте `remove: true`, щоб прибрати конкретний emoji реакції з повідомлення. - Семантика реакцій: [Реакції](/uk/tools/reactions) - Для вхідних повідомлень, які містять метадані подій, OpenClaw надсилає підтвердження доставлено + переглянуто (best-effort). @@ -189,19 +186,19 @@ openclaw directory groups list --channel zalouser --query "work" - `openclaw channels status --probe` - Повторний вхід: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser` -**Список дозволених/назва групи не розв’язалися:** +**Ім’я в allowlist/групі не розв’язалося:** - Використовуйте числові ID в `allowFrom`/`groupAllowFrom`/`groups` або точні імена друзів/груп. -**Оновлено зі старого налаштування на основі CLI:** +**Оновлення зі старого налаштування на основі CLI:** -- Приберіть будь-які старі припущення щодо зовнішнього процесу `zca`. -- Тепер канал працює повністю в OpenClaw без зовнішніх CLI-бінарників. +- Приберіть будь-які старі припущення про зовнішній процес `zca`. +- Канал тепер повністю працює в OpenClaw без зовнішніх CLI-бінарників. ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Спарювання](/uk/channels/pairing) — автентифікація DM і процес спарювання +- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing - [Групи](/uk/channels/groups) — поведінка групового чату та обмеження згадок - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень - [Безпека](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/cli/plugins.md b/docs/uk/cli/plugins.md index c965f24ef..1005fa66d 100644 --- a/docs/uk/cli/plugins.md +++ b/docs/uk/cli/plugins.md @@ -1,35 +1,35 @@ --- read_when: - - Ви хочете встановити Plugin Gateway або керувати ними чи сумісними пакетами - - Ви хочете діагностувати збої завантаження Plugin + - Ви хочете встановити Plugin-и Gateway або керувати ними чи сумісними пакетами + - Ви хочете налагодити збої завантаження Plugin sidebarTitle: Plugins summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) title: Plugins x-i18n: - generated_at: "2026-05-02T19:23:34Z" + generated_at: "2026-05-02T21:05:42Z" model: gpt-5.5 provider: openai - source_hash: 6fc046a04175c1b22f787920bf5ec28c24d0bb7d62eda4d9517da8f5dbac4c50 + source_hash: 48583cb22363837cf95ebc4de6f688f72921347240ac5cf228c20f9a6c5237fd source_path: cli/plugins.md workflow: 16 --- -Керуйте Plugin для Gateway, пакетами хуків і сумісними бандлами. +Керуйте Plugin для Gateway, пакетами хуків і сумісними bundles. - - Посібник для кінцевих користувачів з установлення, увімкнення та усунення проблем із plugins. + + Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення несправностей plugins. - - Швидкі приклади для встановлення, перегляду списку, оновлення, видалення та публікації. + + Короткі приклади для встановлення, перегляду списку, оновлення, видалення та публікації. - - Модель сумісності бандлів. + + Модель сумісності bundle. - + Поля маніфесту та схема конфігурації. - + Посилення безпеки для встановлення plugins. @@ -62,19 +62,19 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Для розслідування повільного встановлення, інспектування, видалення або оновлення реєстру запустіть -команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує час виконання фаз +Для дослідження повільного встановлення, інспектування, видалення або оновлення реєстру запустіть +команду з `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Трасування записує таймінги фаз у stderr і зберігає JSON-вивід придатним для парсингу. Див. [Налагодження](/uk/help/debugging#plugin-lifecycle-trace). -Вбудовані plugins постачаються з OpenClaw. Деякі ввімкнені за замовчуванням (наприклад вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний plugin); інші потребують `plugins enable`. +Вбудовані plugins постачаються разом з OpenClaw. Деякі увімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний plugin); інші потребують `plugins enable`. -Нативні plugins OpenClaw мають постачати `openclaw.plugin.json` з вбудованою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні бандли натомість використовують власні маніфести бандлів. +Нативні plugins OpenClaw мають постачати `openclaw.plugin.json` з вбудованою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні bundles натомість використовують власні маніфести bundle. -`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід списку/інформації також показує підтип бандла (`codex`, `claude` або `cursor`) і виявлені можливості бандла. +`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info також показує підтип bundle (`codex`, `claude` або `cursor`) і виявлені можливості bundle. -### Установлення +### Встановлення ```bash openclaw plugins search "calendar" # search ClawHub plugins @@ -93,97 +93,97 @@ openclaw plugins install --marketplace https://github.com// -Голі назви пакетів під час перехідного запуску встановлюються з npm за замовчуванням. Використовуйте `clawhub:` для ClawHub. Ставтеся до встановлення plugins як до запуску коду. Надавайте перевагу закріпленим версіям. +Голі імена пакетів під час перехідного запуску за замовчуванням встановлюються з npm. Використовуйте `clawhub:` для ClawHub. Ставтеся до встановлення plugins як до запуску коду. Надавайте перевагу закріпленим версіям. -`plugins search` запитує ClawHub щодо доступних для встановлення пакетів plugins і виводить -готові до встановлення назви пакетів. Він шукає пакети code-plugin і bundle-plugin, +`plugins search` запитує ClawHub щодо доступних для встановлення пакетів plugin і виводить +імена пакетів, готові до встановлення. Пошук охоплює пакети code-plugin і bundle-plugin, а не skills. Використовуйте `openclaw skills search` для Skills ClawHub. ClawHub є основною поверхнею розповсюдження та виявлення для більшості plugins. Npm -залишається підтримуваним резервним варіантом і шляхом прямого встановлення. Під час міграції до -ClawHub OpenClaw усе ще постачає деякі пакети plugins, що належать OpenClaw, `@openclaw/*` -у npm; версії цих пакетів можуть відставати від вбудованого вихідного коду між -циклами випуску plugins. Якщо npm повідомляє, що пакет plugin, який належить OpenClaw, застарів, ця -опублікована версія є старим зовнішнім артефактом; використовуйте plugin, вбудований у -поточний OpenClaw, або локальний checkout, доки не буде опубліковано новіший пакет npm. +залишається підтримуваним резервним варіантом і шляхом прямого встановлення. Пакети plugin +`@openclaw/*`, що належать OpenClaw, знову публікуються в npm; див. поточний список +на [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) або +[інвентар plugins](/uk/plugins/plugin-inventory). Стабільні встановлення використовують `latest`. +Встановлення й оновлення beta-каналу надають перевагу npm dist-tag `beta`, коли цей тег +доступний, а потім повертаються до `latest`. - - Якщо ваш розділ `plugins` підтримується однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записує зміни в цей включений файл і лишає `openclaw.json` без змін. Кореневі включення, масиви включень і включення з одноранговими перевизначеннями завершуються закрито замість вирівнювання. Див. [Включення конфігурації](/uk/gateway/configuration) для підтримуваних форм. + + Якщо ваш розділ `plugins` підтримується однофайловим `$include`, `plugins install/update/enable/disable/uninstall` записують зміни до цього включеного файла й залишають `openclaw.json` без змін. Кореневі includes, масиви include та includes із сусідніми перевизначеннями завершуються закрито, а не розгортаються. Див. [Config includes](/uk/gateway/configuration) щодо підтримуваних форм. - Якщо під час установлення конфігурація недійсна, `plugins install` зазвичай завершується закрито й повідомляє, що спершу треба запустити `openclaw doctor --fix`. Під час запуску Gateway недійсна конфігурація одного plugin ізолюється до цього plugin, щоб інші канали та plugins могли продовжувати роботу; `openclaw doctor --fix` може помістити недійсний запис plugin у карантин. Єдиний задокументований виняток під час установлення — вузький шлях відновлення для вбудованих plugins, які явно погоджуються на `openclaw.install.allowInvalidConfigRecovery`. + Якщо під час встановлення конфігурація недійсна, `plugins install` зазвичай завершується закрито й повідомляє спершу запустити `openclaw doctor --fix`. Під час запуску Gateway недійсна конфігурація одного plugin ізолюється до цього plugin, щоб інші канали та plugins могли продовжити роботу; `openclaw doctor --fix` може помістити недійсний запис plugin у карантин. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення для вбудованих plugins, які явно підключають `openclaw.install.allowInvalidConfigRecovery`. - - `--force` повторно використовує наявну ціль установлення та перезаписує вже встановлений plugin або пакет хуків на місці. Використовуйте його, коли навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакта npm. Для звичайних оновлень уже відстежуваного plugin npm надавайте перевагу `openclaw plugins update `. + + `--force` повторно використовує наявну ціль встановлення та перезаписує вже встановлений plugin або пакет хуків на місці. Використовуйте це, коли ви навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакту npm. Для звичайних оновлень уже відстежуваного npm plugin надавайте перевагу `openclaw plugins update `. - Якщо ви запускаєте `plugins install` для id plugin, який уже встановлено, OpenClaw зупиняється й указує на `plugins update ` для звичайного оновлення або на `plugins install --force`, коли ви справді хочете перезаписати поточну установку з іншого джерела. + Якщо запустити `plugins install` для id plugin, який уже встановлено, OpenClaw зупиниться й спрямує вас до `plugins update ` для звичайного оновлення або до `plugins install --force`, коли ви справді хочете перезаписати поточне встановлення з іншого джерела. - - `--pin` застосовується лише до встановлень npm. Він не підтримується з установленнями `git:`; використовуйте явне посилання git, наприклад `git:github.com/acme/plugin@v1.2.3`, коли хочете закріпити джерело. Він не підтримується з `--marketplace`, оскільки встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm. + + `--pin` застосовується лише до встановлень npm. Він не підтримується з установленнями `git:`; використовуйте явне git-посилання, як-от `git:github.com/acme/plugin@v1.2.3`, коли потрібне закріплене джерело. Він не підтримується з `--marketplace`, оскільки встановлення marketplace зберігають метадані джерела marketplace замість npm spec. - `--dangerously-force-unsafe-install` — це аварійний параметр для хибних спрацьовувань у вбудованому сканері небезпечного коду. Він дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про знахідки `critical`, але **не** обходить блокування політик хуків plugin `before_install` і **не** обходить збої сканування. + `--dangerously-force-unsafe-install` — це аварійна опція для хибних спрацьовувань вбудованого сканера небезпечного коду. Вона дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про знахідки `critical`, але вона **не** обходить блокування політики hook plugin `before_install` і **не** обходить збої сканування. - Цей прапорець CLI застосовується до потоків установлення/оновлення plugin. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. + Цей прапорець CLI застосовується до потоків встановлення/оновлення plugin. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills ClawHub. - Якщо plugin, який ви опублікували в ClawHub, заблоковано скануванням реєстру, скористайтеся кроками для видавця в [ClawHub](/uk/tools/clawhub). + Якщо plugin, який ви опублікували на ClawHub, заблоковано скануванням реєстру, скористайтеся кроками для видавця в [ClawHub](/uk/tools/clawhub). - - `plugins install` також є поверхнею встановлення для пакетів хуків, які надають `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для фільтрованої видимості хуків і ввімкнення окремих хуків, а не для встановлення пакетів. + + `plugins install` також є поверхнею встановлення для пакетів хуків, які відкривають `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для фільтрованої видимості хуків і вмикання окремих хуків, а не для встановлення пакетів. - Специфікації npm є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Встановлення залежностей виконується локально для проєкту з `--ignore-scripts` задля безпеки, навіть якщо ваша оболонка має глобальні налаштування встановлення npm. + Npm specs є **лише реєстровими** (ім'я пакета + необов'язкова **точна версія** або **dist-tag**). Git/URL/file specs і semver-діапазони відхиляються. Встановлення залежностей виконуються локально для проєкту з `--ignore-scripts` заради безпеки, навіть якщо ваша оболонка має глобальні налаштування npm install. - Використовуйте `npm:`, коли хочете явно вказати розв’язання npm. Голі специфікації пакетів також установлюються напряму з npm під час перехідного запуску. + Використовуйте `npm:`, коли хочете явно вказати розв'язання через npm. Голі specs пакетів також установлюються безпосередньо з npm під час перехідного запуску. - Голі специфікації та `@latest` залишаються на стабільній гілці. Якщо npm розв’язує будь-яку з них до prerelease, OpenClaw зупиняється й просить вас явно погодитися за допомогою prerelease-тегу, такого як `@beta`/`@rc`, або точної prerelease-версії, такої як `@1.2.3-beta.4`. + Голі specs і `@latest` залишаються на стабільній гілці. Якщо npm розв'язує будь-що з цього до prerelease, OpenClaw зупиняється й просить явно погодитися через prerelease-тег, як-от `@beta`/`@rc`, або точну prerelease-версію, як-от `@1.2.3-beta.4`. - Якщо гола специфікація встановлення збігається з офіційним id plugin (наприклад `diffs`), OpenClaw встановлює запис каталогу напряму. Щоб установити пакет npm з такою самою назвою, використовуйте явну scoped-специфікацію (наприклад `@scope/diffs`). + Якщо голий install spec збігається з офіційним id plugin (наприклад `diffs`), OpenClaw встановлює запис каталогу напряму. Щоб установити npm-пакет з такою самою назвою, використовуйте явний scoped spec (наприклад `@scope/diffs`). - - Використовуйте `git:` для встановлення напряму з репозиторію git. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні URL клонування `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@` або `#`, щоб перед установленням перейти на гілку, тег або коміт. + + Використовуйте `git:` для встановлення безпосередньо з git-репозиторію. Підтримувані форми включають `git:github.com/owner/repo`, `git:owner/repo`, повні clone URL `https://`, `ssh://`, `git://`, `file://` і `git@host:owner/repo.git`. Додайте `@` або `#`, щоб перед встановленням перейти на гілку, тег або commit. - Установлення з Git клонують у тимчасовий каталог, переходять на запитаний ref, якщо він присутній, а потім використовують звичайний інсталятор каталогу plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення менеджера пакетів і записи встановлення поводяться як установлення npm. Записані встановлення git включають URL/ref джерела плюс розв’язаний коміт, щоб `openclaw plugins update` міг повторно розв’язати джерело пізніше. + Git-встановлення клонують у тимчасовий каталог, переходять на запитаний ref, якщо він наявний, а потім використовують звичайний інсталятор каталогу plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення менеджера пакетів і записи встановлення поводяться як у npm-встановленнях. Записані git-встановлення включають вихідний URL/ref і розв'язаний commit, щоб `openclaw plugins update` міг пізніше повторно розв'язати джерело. - Після встановлення з git використовуйте `openclaw plugins inspect --runtime --json`, щоб перевірити реєстрації часу виконання, як-от методи gateway та команди CLI. Якщо plugin зареєстрував корінь CLI через `api.registerCli`, виконайте цю команду напряму через кореневий CLI OpenClaw, наприклад `openclaw demo-plugin ping`. + Після встановлення з git використовуйте `openclaw plugins inspect --runtime --json`, щоб перевірити runtime-реєстрації, як-от методи gateway і команди CLI. Якщо plugin зареєстрував корінь CLI через `api.registerCli`, виконайте цю команду безпосередньо через кореневий CLI OpenClaw, наприклад `openclaw demo-plugin ping`. - - Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних plugins OpenClaw мають містити дійсний `openclaw.plugin.json` у корені витягнутого plugin; архіви, що містять лише `package.json`, відхиляються до того, як OpenClaw запише записи встановлення. + + Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Архіви нативних plugin OpenClaw мають містити дійсний `openclaw.plugin.json` у корені витягнутого plugin; архіви, які містять лише `package.json`, відхиляються до того, як OpenClaw запише записи встановлення. - Встановлення з marketplace Claude також підтримуються. + Встановлення marketplace Claude також підтримуються. -Встановлення з ClawHub використовують явний локатор `clawhub:`: +Встановлення ClawHub використовують явний locator `clawhub:`: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Голі npm-сумісні специфікації plugins під час перехідного запуску встановлюються з npm за замовчуванням: +Голі npm-безпечні specs plugin під час перехідного запуску за замовчуванням встановлюються з npm: ```bash openclaw plugins install openclaw-codex-app-server ``` -Використовуйте `npm:`, щоб явно вказати розв’язання лише через npm: +Використовуйте `npm:`, щоб явно вказати розв'язання лише через npm: ```bash openclaw plugins install npm:openclaw-codex-app-server openclaw plugins install npm:@scope/plugin-name@1.0.1 ``` -OpenClaw перевіряє оголошену сумісність API plugin / мінімального gateway перед установленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версіонований npm-pack `.tgz`, перевіряє заголовок дайджесту ClawHub і дайджест артефакта, а потім установлює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack усе ще встановлюються через застарілий шлях перевірки архіву пакета. Записані встановлення зберігають свої метадані джерела ClawHub, тип артефакта, npm integrity, npm shasum, назву tarball і факти дайджесту ClawPack для подальших оновлень. -Неверсіоновані встановлення ClawHub зберігають неверсіоновану записану специфікацію, щоб `openclaw plugins update` міг відстежувати новіші випуски ClawHub; явні селектори версії або тегу, такі як `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються закріпленими до цього селектора. +OpenClaw перевіряє заявлену сумісність plugin API / мінімального gateway перед встановленням. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версійний npm-pack `.tgz`, перевіряє digest header ClawHub і digest артефакту, а потім встановлює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack досі встановлюються через застарілий шлях перевірки архіву пакета. Записані встановлення зберігають метадані джерела ClawHub, тип артефакту, npm integrity, npm shasum, назву tarball і факти ClawPack digest для подальших оновлень. +Неверсійовані встановлення ClawHub зберігають неверсійований записаний spec, щоб `openclaw plugins update` міг відстежувати новіші релізи ClawHub; явні селектори версії або тегу, як-от `clawhub:pkg@1.2.3` і `clawhub:pkg@beta`, залишаються закріпленими на цьому селекторі. #### Скорочення marketplace @@ -204,28 +204,28 @@ openclaw plugins install --marketplace ./my-marketplace ``` - - - назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json` + + - назва відомого Claude marketplace з `~/.claude/plugins/known_marketplaces.json` - локальний корінь marketplace або шлях `marketplace.json` - - скорочення репозиторію GitHub, як-от `owner/repo` - - URL репозиторію GitHub, як-от `https://github.com/owner/repo` + - скорочення репозиторію GitHub, наприклад `owner/repo` + - URL репозиторію GitHub, наприклад `https://github.com/owner/repo` - git URL - - Для віддалених marketplace, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає джерела відносних шляхів із цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші не-шляхові джерела плагінів із віддалених маніфестів. + + Для віддалених marketplace, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає джерела відносних шляхів із цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші непутьові джерела плагінів із віддалених маніфестів. Для локальних шляхів і архівів OpenClaw автоматично виявляє: - нативні плагіни OpenClaw (`openclaw.plugin.json`) -- Codex-сумісні пакети (`.codex-plugin/plugin.json`) -- Claude-сумісні пакети (`.claude-plugin/plugin.json` або стандартне компонування компонентів Claude) -- Cursor-сумісні пакети (`.cursor-plugin/plugin.json`) +- сумісні з Codex пакети (`.codex-plugin/plugin.json`) +- сумісні з Claude пакети (`.claude-plugin/plugin.json` або типовий макет компонентів Claude) +- сумісні з Cursor пакети (`.cursor-plugin/plugin.json`) -Сумісні пакети встановлюються у звичайний корінь плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, command-skills Claude, стандартні значення Claude `settings.json`, стандартні значення Claude `.lsp.json` / оголошених у маніфесті `lspServers`, command-skills Cursor і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в diagnostics/info, але ще не підключені до виконання під час runtime. +Сумісні пакети встановлюються у звичайний корінь плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакетів, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / оголошені в маніфесті `lspServers`, command-skills Cursor і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не під’єднані до виконання під час роботи. ### Список @@ -241,41 +241,41 @@ openclaw plugins search --json ``` - Показувати лише увімкнені плагіни. + Показати лише ввімкнені плагіни. - Перемкнутися з табличного подання на рядки деталей для кожного плагіна з метаданими source/origin/version/activation. + Перемкнутися з табличного подання на докладні рядки для кожного плагіна з метаданими джерела/походження/версії/активації. - Машиночитний інвентар, а також діагностика registry і стан встановлення залежностей пакета. + Машинночитний інвентар, а також діагностика реєстру та стан встановлення залежностей пакета. -`plugins list` спершу читає збережений локальний registry плагінів, із резервним варіантом, похідним лише з маніфесту, коли registry відсутній або недійсний. Це корисно для перевірки, чи плагін встановлено, увімкнено та видно для планування холодного запуску, але це не live runtime-перевірка вже запущеного процесу Gateway. Після зміни коду плагіна, стану ввімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або хуків. Для віддалених/container розгортань перевірте, що ви перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку. +`plugins list` спершу читає збережений локальний реєстр плагінів, із резервним варіантом, похідним лише від маніфесту, коли реєстр відсутній або недійсний. Це корисно для перевірки, чи плагін встановлений, увімкнений і видимий для планування холодного запуску, але це не живий runtime-зонд уже запущеного процесу Gateway. Після зміни коду плагіна, увімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або хуків. Для віддалених/контейнерних розгортань перевірте, що перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку. `plugins list --json` включає `dependencyStatus` кожного плагіна з `package.json` -`dependencies` і `optionalDependencies`. OpenClaw перевіряє, чи присутні ці назви пакетів -уздовж звичайного шляху пошуку Node `node_modules` для плагіна; він -не імпортує runtime-код плагіна, не запускає менеджер пакетів і не відновлює відсутні -залежності. +`dependencies` та `optionalDependencies`. OpenClaw перевіряє, чи наявні ці назви +пакетів у звичайному для плагіна шляху пошуку Node `node_modules`; він +не імпортує runtime-код плагіна, не запускає менеджер пакетів і не виправляє +відсутні залежності. `plugins search` — це віддалений пошук у каталозі ClawHub. Він не перевіряє локальний -стан, не змінює config, не встановлює пакети й не завантажує runtime-код плагіна. Результати -пошуку включають назву пакета ClawHub, family, channel, version, summary та -підказку встановлення, як-от `openclaw plugins install clawhub:`. +стан, не змінює конфігурацію, не встановлює пакети й не завантажує runtime-код плагіна. Результати пошуку +містять назву пакета ClawHub, сімейство, канал, версію, підсумок і +підказку для встановлення, наприклад `openclaw plugins install clawhub:`. -Для роботи з вбудованими плагінами всередині упакованого Docker-образу змонтуйте bind-mount вихідний -каталог плагіна поверх відповідного упакованого вихідного шляху, наприклад -`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване накладання source -перед `/app/dist/extensions/synology-chat`; звичайний скопійований вихідний -каталог лишається неактивним, тож звичайні упаковані встановлення й далі використовують скомпільований dist. +Для роботи з bundled plugin усередині запакованого Docker-образу примонтуйте каталог +джерел плагіна поверх відповідного запакованого шляху джерел, наприклад +`/app/extensions/synology-chat`. OpenClaw виявить це змонтоване накладання +джерел перед `/app/dist/extensions/synology-chat`; звичайний скопійований каталог +джерел залишиться неактивним, тож нормальні запаковані встановлення й далі використовуватимуть скомпільований dist. Для налагодження runtime-хуків: -- `openclaw plugins inspect --runtime --json` показує зареєстровані хуки та діагностику з проходу інспекції із завантаженням модуля. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані плагіни. -- `openclaw gateway status --deep --require-rpc` підтверджує досяжний Gateway, підказки service/process, шлях config і справність RPC. -- Невбудовані conversation-хуки (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. +- `openclaw plugins inspect --runtime --json` показує зареєстровані хуки та діагностику з проходу інспекції із завантаженим модулем. Runtime-інспекція ніколи не встановлює залежності; використовуйте `openclaw doctor --fix`, щоб очистити застарілий стан залежностей або встановити відсутні налаштовані завантажувані плагіни. +- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки щодо служби/процесу, шлях конфігурації та стан RPC. +- Небандловані хуки розмов (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. Використовуйте `--link`, щоб уникнути копіювання локального каталогу (додає до `plugins.load.paths`): @@ -284,16 +284,16 @@ openclaw plugins install -l ./my-plugin ``` -`--force` не підтримується з `--link`, оскільки linked-встановлення повторно використовують вихідний шлях замість копіювання поверх керованої цілі встановлення. +`--force` не підтримується з `--link`, оскільки пов’язані встановлення повторно використовують шлях джерела замість копіювання поверх керованої цілі встановлення. -Використовуйте `--pin` для npm-встановлень, щоб зберегти resolved exact spec (`name@version`) у керованому індексі плагінів, зберігаючи стандартну поведінку unpinned. +Використовуйте `--pin` під час npm-встановлень, щоб зберегти розв’язану точну специфікацію (`name@version`) у керованому індексі плагінів, залишаючи типову поведінку незакріпленою. ### Індекс Plugin -Метадані встановлення Plugin — це керований машиною стан, а не користувацький config. Встановлення та оновлення записують його в `plugins/installs.json` під активним каталогом стану OpenClaw. Його верхньорівнева мапа `installRecords` є довговічним джерелом метаданих встановлення, зокрема записів для пошкоджених або відсутніх маніфестів плагінів. Масив `plugins` — це похідний від маніфесту cache холодного registry. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, uninstall, diagnostics і холодним registry плагінів. +Метадані встановлення Plugin — це машинно-керований стан, а не конфігурація користувача. Встановлення та оновлення записують його в `plugins/installs.json` в активному каталозі стану OpenClaw. Його карта верхнього рівня `installRecords` є довготривалим джерелом метаданих встановлення, включно із записами для зламаних або відсутніх маніфестів плагінів. Масив `plugins` — це похідний від маніфестів кеш холодного реєстру. Файл містить попередження не редагувати його та використовується `openclaw plugins update`, видаленням, діагностикою та холодним реєстром плагінів. -Коли OpenClaw бачить у config доставлені застарілі записи `plugins.installs`, він переносить їх в індекс плагінів і видаляє ключ config; якщо будь-який запис не вдається, записи config зберігаються, щоб метадані встановлення не було втрачено. +Коли OpenClaw бачить поставлені застарілі записи `plugins.installs` у конфігурації, він переміщує їх до індексу плагінів і видаляє ключ конфігурації; якщо будь-який із записів не вдається, записи конфігурації зберігаються, щоб метадані встановлення не були втрачені. ### Видалення @@ -303,7 +303,7 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` видаляє записи плагінів із `plugins.entries`, збереженого індексу плагінів, записів allow/deny list плагінів і linked-записів `plugins.load.paths`, коли застосовно. Якщо `--keep-files` не задано, uninstall також видаляє відстежуваний керований каталог встановлення, коли він міститься всередині кореня plugin extensions OpenClaw. Для плагінів active memory слот memory скидається до `memory-core`. +`uninstall` видаляє записи плагіна з `plugins.entries`, збереженого індексу плагінів, записів allow/deny list плагінів і пов’язаних записів `plugins.load.paths`, коли це застосовно. Якщо `--keep-files` не встановлено, uninstall також видаляє відстежуваний керований каталог встановлення, коли він розташований усередині кореня розширень плагінів OpenClaw. Для плагінів Active Memory слот пам’яті скидається до `memory-core`. `--keep-config` підтримується як застарілий псевдонім для `--keep-files`. @@ -322,26 +322,26 @@ openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-ins Оновлення застосовуються до відстежуваних встановлень плагінів у керованому індексі плагінів і відстежуваних встановлень hook-pack у `hooks.internal.installs`. - - Коли ви передаєте plugin id, OpenClaw повторно використовує записаний install spec для цього плагіна. Це означає, що раніше збережені dist-tags, як-от `@beta`, і точні pinned-версії продовжують використовуватися під час подальших запусків `update `. + + Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-tags, такі як `@beta`, і точні закріплені версії й надалі використовуються під час наступних запусків `update `. - Для npm-встановлень ви також можете передати явний npm package spec із dist-tag або точною версією. OpenClaw зіставляє цю назву пакета назад із відстежуваним записом плагіна, оновлює цей встановлений плагін і записує новий npm spec для майбутніх id-based оновлень. + Для npm-встановлень ви також можете передати явну специфікацію npm-пакета з dist-tag або точною версією. OpenClaw зіставляє назву цього пакета з відстежуваним записом плагіна, оновлює цей встановлений плагін і записує нову npm-специфікацію для майбутніх оновлень за id. - Передавання назви npm-пакета без версії або тега також зіставляється назад із відстежуваним записом плагіна. Використовуйте це, коли плагін було pinned до точної версії і ви хочете повернути його до стандартної release line registry. + Передавання назви npm-пакета без версії або тега також зіставляється з відстежуваним записом плагіна. Використовуйте це, коли плагін був закріплений на точній версії, а ви хочете повернути його до типової лінії випусків реєстру. - - `openclaw plugins update` повторно використовує відстежуваний plugin spec, якщо ви не передасте новий spec. `openclaw update` додатково знає активний канал оновлення OpenClaw: на beta-каналі записи npm і ClawHub плагінів default-line спершу пробують `@beta`, а потім повертаються до записаного default/latest spec, якщо beta-релізу плагіна немає. Точні версії та явні теги залишаються pinned до цього selector. + + `openclaw plugins update` повторно використовує відстежувану специфікацію плагіна, якщо ви не передасте нову специфікацію. `openclaw update` додатково знає активний канал оновлень OpenClaw: на beta-каналі записи npm і ClawHub плагінів типової лінії спочатку пробують `@beta`, а потім повертаються до записаної default/latest специфікації, якщо beta-випуску плагіна не існує. Точні версії та явні теги залишаються закріпленими за цим селектором. - - Перед live npm update OpenClaw перевіряє встановлену версію пакета щодо метаданих npm registry. Якщо встановлена версія та записана ідентичність artifact уже відповідають resolved target, оновлення пропускається без завантаження, перевстановлення або переписування `openclaw.json`. + + Перед живим npm-оновленням OpenClaw перевіряє встановлену версію пакета за метаданими npm-реєстру. Якщо встановлена версія та записана ідентичність артефакта вже відповідають розв’язаній цілі, оновлення пропускається без завантаження, перевстановлення або перезапису `openclaw.json`. - Коли збережений integrity hash існує, а hash отриманого artifact змінюється, OpenClaw трактує це як npm artifact drift. Інтерактивна команда `openclaw plugins update` друкує очікуваний і фактичний hashes та просить підтвердження перед продовженням. Неінтерактивні update helpers завершуються fail-closed, якщо caller не надасть явну continuation policy. + Коли існує збережений integrity hash і hash отриманого артефакта змінюється, OpenClaw трактує це як зсув npm-артефакта. Інтерактивна команда `openclaw plugins update` друкує очікуваний і фактичний hashes та просить підтвердження перед продовженням. Неінтерактивні помічники оновлення fail closed, якщо викликач не надає явну політику продовження. - - `--dangerously-force-unsafe-install` також доступний у `plugins update` як break-glass override для хибнопозитивних спрацювань built-in dangerous-code scan під час оновлень плагінів. Він усе одно не обходить policy blocks plugin `before_install` або блокування scan-failure і застосовується лише до оновлень плагінів, а не оновлень hook-pack. + + `--dangerously-force-unsafe-install` також доступний для `plugins update` як аварійне перевизначення хибних спрацьовувань вбудованого сканування небезпечного коду під час оновлень плагінів. Він все одно не обходить блокування політик `before_install` плагіна або блокування через збій сканування, і застосовується лише до оновлень плагінів, а не до оновлень hook-pack. @@ -353,21 +353,21 @@ openclaw plugins inspect --runtime openclaw plugins inspect --json ``` -Inspect показує identity, load status, source, можливості маніфесту, policy flags, diagnostics, install metadata, можливості пакета та будь-яку виявлену підтримку MCP або LSP server без стандартного імпорту runtime плагіна. Додайте `--runtime`, щоб завантажити модуль плагіна й включити зареєстровані хуки, tools, commands, services, gateway methods і HTTP routes. Runtime-інспекція повідомляє про відсутні залежності плагіна напряму; встановлення та відновлення залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`. +Inspect показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політики, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку MCP або LSP-сервера без імпорту runtime плагіна за замовчуванням. Додайте `--runtime`, щоб завантажити модуль плагіна й включити зареєстровані хуки, інструменти, команди, служби, методи Gateway та HTTP-маршрути. Runtime-інспекція повідомляє про відсутні залежності плагіна напряму; встановлення та ремонти залишаються в `openclaw plugins install`, `openclaw plugins update` і `openclaw doctor --fix`. -CLI-команди, власником яких є плагін, встановлюються як кореневі групи команд `openclaw`. Після того як `inspect --runtime` показує команду в `cliCommands`, запускайте її як `openclaw ...`; наприклад, плагін, який реєструє `demo-git`, можна перевірити через `openclaw demo-git ping`. +CLI-команди, що належать плагінам, встановлюються як кореневі групи команд `openclaw`. Після того як `inspect --runtime` покаже команду в `cliCommands`, запускайте її як `openclaw ...`; наприклад, плагін, який реєструє `demo-git`, можна перевірити за допомогою `openclaw demo-git ping`. -Кожен плагін класифікується за тим, що він фактично реєструє під час runtime: +Кожен плагін класифікується за тим, що він фактично реєструє під час роботи: -- **plain-capability** — один тип capability (наприклад, provider-only плагін) -- **hybrid-capability** — кілька типів capability (наприклад, text + speech + images) -- **hook-only** — лише хуки, без capabilities або surfaces -- **non-capability** — tools/commands/services, але без capabilities +- **plain-capability** — один тип можливостей (наприклад, плагін лише провайдера) +- **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення) +- **hook-only** — лише хуки, без можливостей або поверхонь +- **non-capability** — інструменти/команди/служби, але без можливостей -Див. [Форми Plugin](/uk/plugins/architecture#plugin-shapes), щоб дізнатися більше про модель capability. +Див. [Форми Plugin](/uk/plugins/architecture#plugin-shapes), щоб дізнатися більше про модель можливостей. -Прапорець `--json` виводить машиночитний звіт, придатний для scripting і auditing. `inspect --all` відображає таблицю для всього fleet зі стовпцями shape, capability kinds, compatibility notices, bundle capabilities і hook summary. `info` — псевдонім для `inspect`. +Прапорець `--json` виводить машинночитний звіт, придатний для скриптів і аудиту. `inspect --all` відображає таблицю для всього парку з формою, видами можливостей, повідомленнями про сумісність, можливостями пакетів і колонками підсумку хуків. `info` є псевдонімом для `inspect`. ### Doctor @@ -376,11 +376,11 @@ CLI-команди, власником яких є плагін, встанов openclaw plugins doctor ``` -`doctor` повідомляє про помилки завантаження плагінів, діагностику manifest/discovery і compatibility notices. Коли все чисто, він друкує `No plugin issues detected.` +`doctor` повідомляє про помилки завантаження плагінів, діагностику маніфестів/виявлення та повідомлення про сумісність. Коли все чисто, він друкує `No plugin issues detected.` -Для module-shape failures, як-от відсутні експорти `register`/`activate`, повторно запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити стислий export-shape summary у diagnostic output. +Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`, повторно запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити стислий підсумок форми експорту в діагностичний вивід. -### Registry +### Реєстр ```bash openclaw plugins registry @@ -388,12 +388,12 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -Локальний registry плагінів — це збережена холодна read model OpenClaw для identity встановлених плагінів, enablement, source metadata і contribution ownership. Звичайний startup, provider owner lookup, channel setup classification та plugin inventory можуть читати його без імпорту runtime modules плагінів. +Локальний реєстр плагінів — це збережена в OpenClaw холодна модель читання для ідентичності встановлених плагінів, увімкнення, метаданих джерел і володіння внесками. Звичайний запуск, пошук власника провайдера, класифікація налаштування каналів та інвентар плагінів можуть читати його без імпорту runtime-модулів плагінів. -Використовуйте `plugins registry`, щоб перевірити, чи збережений registry присутній, поточний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу плагінів, config policy і manifest/package metadata. Це шлях repair, а не шлях runtime activation. +Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр наявний, актуальний або застарілий. Використовуйте `--refresh`, щоб перебудувати його зі збереженого індексу плагінів, політики конфігурації та метаданих маніфестів/пакетів. Це шлях ремонту, а не шлях runtime-активації. -`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через змінну середовища призначений лише для аварійного відновлення запуску під час розгортання міграції. +`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Віддавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через змінну середовища призначений лише для екстреного відновлення запуску під час розгортання міграції. ### Маркетплейс @@ -403,10 +403,10 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Команда списку маркетплейса приймає локальний шлях до маркетплейса, шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить визначену мітку джерела, а також розібраний маніфест маркетплейса й записи плагінів. +Список маркетплейсу приймає локальний шлях маркетплейсу, шлях до `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. `--json` виводить мітку визначеного джерела разом із розібраним маніфестом маркетплейсу та записами плагінів. ## Пов’язане - [Створення плагінів](/uk/plugins/building-plugins) -- [Довідник CLI](/uk/cli) -- [Спільнотні плагіни](/uk/plugins/community) +- [Довідка CLI](/uk/cli) +- [Плагіни спільноти](/uk/plugins/community) diff --git a/docs/uk/gateway/config-channels.md b/docs/uk/gateway/config-channels.md index 26c493e24..801724c1a 100644 --- a/docs/uk/gateway/config-channels.md +++ b/docs/uk/gateway/config-channels.md @@ -1,56 +1,56 @@ --- read_when: - - Налаштування Plugin каналу (автентифікація, контроль доступу, кілька облікових записів) - - Усунення несправностей із ключами конфігурації для окремих каналів - - Аудит політики DM, політики груп або обмеження згадок + - Налаштування Plugin для каналу (автентифікація, контроль доступу, кілька облікових записів) + - Усунення проблем із ключами конфігурації для окремих каналів + - Аудит політики DM, групової політики або обмеження за згадками summary: 'Конфігурація каналів: контроль доступу, сполучення, ключі для кожного каналу в Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших' title: Конфігурація — канали x-i18n: - generated_at: "2026-05-02T20:49:31Z" + generated_at: "2026-05-02T21:05:46Z" model: gpt-5.5 provider: openai - source_hash: 36284b1aa0a920c32723273fa8807667555a772328fd46f65b7cb2edabc31538 + source_hash: 5231efba32fab480313c05dfd5dcec12e32020a79001c4a72df4c3844966e65e source_path: gateway/config-channels.md workflow: 16 --- -Ключі конфігурації каналів у `channels.*`. Охоплює доступ до DM і груп, -налаштування кількох облікових записів, обмеження за згадкою та ключі окремих каналів для Slack, Discord, -Telegram, WhatsApp, Matrix, iMessage та інших вбудованих Plugin каналів. +Ключі конфігурації для кожного каналу в `channels.*`. Охоплює доступ до DM і груп, +налаштування з кількома обліковими записами, обмеження за згадкою та ключі для кожного каналу для Slack, Discord, +Telegram, WhatsApp, Matrix, iMessage та інших bundled channel plugins. -Для агентів, інструментів, середовища виконання Gateway та інших ключів верхнього рівня див. +Для агентів, інструментів, середовища виконання gateway та інших ключів верхнього рівня див. [Довідник конфігурації](/uk/gateway/configuration-reference). ## Канали -Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). +Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не задано `enabled: false`). ### Доступ до DM і груп Усі канали підтримують політики DM і політики груп: -| Політика DM | Поведінка | +| Політика DM | Поведінка | | ------------------- | --------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | -| `allowlist` | Лише відправники в `allowFrom` (або у сховищі дозволених сполучень) | +| `pairing` (default) | Невідомі відправники отримують одноразовий код спарювання; власник має схвалити | +| `allowlist` | Лише відправники в `allowFrom` (або в сховищі дозволених спарених) | | `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| `disabled` | Ігнорувати всі вхідні DM | -| Політика групи | Поведінка | +| Політика групи | Поведінка | | --------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | +| `allowlist` (default) | Лише групи, що відповідають налаштованому списку дозволених | | `open` | Обійти списки дозволених груп (обмеження за згадкою все ще застосовується) | -| `disabled` | Блокувати всі повідомлення груп/кімнат | +| `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` провайдера не встановлено. -Коди сполучення спливають через 1 годину. Очікувані запити на сполучення DM обмежені **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика групи під час виконання повертається до `allowlist` (закрито за замовчуванням) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` провайдера не задано. +Коди спарювання спливають через 1 годину. Очікувані запити спарювання DM обмежені **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. ### Перевизначення моделі каналу -Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ID каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Зіставлення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, встановленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Зіставлення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, заданого через `/model`). ```json5 { @@ -91,15 +91,15 @@ Telegram, WhatsApp, Matrix, iMessage та інших вбудованих Plugin } ``` -- `channels.defaults.groupPolicy`: резервна політика групи, коли `groupPolicy` на рівні провайдера не встановлено. -- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь цитований/тематичний/історичний контекст), `allowlist` (включати лише контекст від дозволених відправників), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. +- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не задано. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь цитований контекст/контекст треду/історії), `allowlist` (включати лише контекст від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: включати справні статуси каналів у вивід Heartbeat. - `channels.defaults.heartbeat.showAlerts`: включати погіршені/помилкові статуси у вивід Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: відтворювати компактний вивід Heartbeat у стилі індикатора. +- `channels.defaults.heartbeat.useIndicator`: показувати компактний вивід Heartbeat у стилі індикаторів. ### WhatsApp -WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує пов’язаний сеанс. +WhatsApp працює через вебканал gateway (Baileys Web). Він запускається автоматично, коли існує пов’язаний сеанс. ```json5 { @@ -157,9 +157,9 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше перший налаштований ID облікового запису (відсортований). +- Вихідні команди за замовчуванням використовують обліковий запис `default`, якщо він є; інакше перший налаштований ID облікового запису (після сортування). - Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, коли він відповідає налаштованому ID облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису переноситься `openclaw doctor` у `whatsapp/default`. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується `openclaw doctor` у `whatsapp/default`. - Перевизначення для облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -219,12 +219,12 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символічні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервом для типового облікового запису. -- `apiRoot` — це лише корінь Telegram Bot API. Використовуйте `https://api.telegram.org` або ваш самостійно розміщений/проксійований корінь, а не `https://api.telegram.org/bot`; `openclaw doctor --fix` видаляє випадковий кінцевий суфікс `/bot`. +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- `apiRoot` — це лише корінь Telegram Bot API. Використовуйте `https://api.telegram.org` або власний self-hosted/proxy корінь, а не `https://api.telegram.org/bot`; `openclaw doctor --fix` прибирає випадковий кінцевий суфікс `/bot`. - Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, коли він відповідає налаштованому ID облікового запису. -- У налаштуваннях із кількома обліковими записами (2+ ID облікових записів) задайте явний типовий (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, коли він відсутній або недійсний. -- `configWrites: false` блокує ініційовані Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують сталі прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна в [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings). +- У налаштуваннях із кількома обліковими записами (2+ ID облікових записів) задайте явне типове значення (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, коли воно відсутнє або недійсне. +- `configWrites: false` блокує записи конфігурації, ініційовані Telegram (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` із `type: "acp"` налаштовують сталі прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна в [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings). - Попередні перегляди потоків Telegram використовують `sendMessage` + `editMessageText` (працює в прямих і групових чатах). - Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). @@ -331,41 +331,41 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним значенням для облікового запису за замовчуванням. -- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; параметри повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання. -- Необов'язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ідентифікатору облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ідентифікатори відхиляються. -- Slug-и guild мають нижній регістр із пробілами, заміненими на `-`; ключі каналів використовують slug-овану назву (без `#`). Надавайте перевагу ідентифікаторам guild. -- Повідомлення, створені ботами, ігноруються за замовчуванням. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). +- Токен: `channels.discord.token`, із `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; параметри повторних спроб і політик облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- Використовуйте `user:` (DM) або `channel:` (канал гільдії) для цілей доставлення; голі числові ідентифікатори відхиляються. +- Слаги гільдій пишуться малими літерами із заміною пробілів на `-`; ключі каналів використовують ім’я у вигляді слага (без `#`). Надавайте перевагу ідентифікаторам гільдій. +- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). - `channels.discord.guilds..ignoreOtherMentions` (і перевизначення каналів) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here). - `channels.discord.mentionAliases` зіставляє стабільний вихідний текст `@handle` з ідентифікаторами користувачів Discord перед надсиланням, щоб відомих колег можна було згадувати детерміновано, навіть коли тимчасовий кеш каталогу порожній. Перевизначення для окремих облікових записів розміщуються в `channels.discord.accounts..mentionAliases`. -- `maxLinesPerMessage` (за замовчуванням 17) розбиває високі повідомлення, навіть якщо вони мають менше ніж 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією Discord, прив'язаною до потоків: - - `enabled`: перевизначення Discord для функцій сесій, прив'язаних до потоків (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив'язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного скасування фокуса через неактивність у годинах (`0` вимикає) +- `maxLinesPerMessage` (типово 17) розбиває повідомлення з великою кількістю рядків, навіть якщо вони коротші за 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією Discord, прив’язаною до гілок: + - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також прив’язане доставлення/маршрутизація) + - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSessions`: перемикач для `sessions_spawn({ thread: true })` і автоматичного створення/прив'язування потоків ACP thread-spawn (за замовчуванням: `true`) - - `defaultSpawnContext`: нативний контекст під-агента для запусків, прив'язаних до потоків (за замовчуванням `"fork"`) -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив'язки ACP для каналів і потоків (використовуйте ідентифікатор каналу/потоку в `match.peer.id`). Семантика полів спільна в [ACP Agents](/uk/tools/acp-agents#persistent-channel-bindings). -- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2. -- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов'язкові перевизначення auto-join + LLM + TTS. Текстові конфігурації Discord залишають голос вимкненим за замовчуванням; задайте `channels.discord.voice.enabled=true`, щоб увімкнути. -- `channels.discord.voice.model` необов'язково перевизначає модель LLM, яка використовується для відповідей у голосових каналах Discord. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` передаються до параметрів DAVE `@discordjs/voice` (за замовчуванням `true` і `24`). -- `channels.discord.voice.connectTimeoutMs` керує початковим очікуванням Ready `@discordjs/voice` для `/vc join` і спроб auto-join (за замовчуванням `30000`). -- `channels.discord.voice.reconnectGraceMs` керує тим, скільки часу відключена голосова сесія може переходити в сигналізацію перепідключення, перш ніж OpenClaw її знищить (за замовчуванням `15000`). -- OpenClaw додатково намагається відновити приймання голосу, виходячи з голосової сесії та повторно входячи в неї після повторних помилок дешифрування. + - `spawnSessions`: перемикач для `sessions_spawn({ thread: true })` і автоматичного створення/прив’язування гілок під час породження ACP-гілок (типово: `true`) + - `defaultSpawnContext`: власний контекст субагента для породжень, прив’язаних до гілок (типово `"fork"`) +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують сталі прив’язки ACP для каналів і гілок (використовуйте ідентифікатор каналу/гілки в `match.peer.id`). Семантика полів спільна в [Агентах ACP](/uk/tools/acp-agents#persistent-channel-bindings). +- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів компонентів Discord v2. +- `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення автоприєднання + LLM + TTS. Текстові конфігурації Discord типово залишають голос вимкненим; задайте `channels.discord.voice.enabled=true`, щоб увімкнути його. +- `channels.discord.voice.model` необов’язково перевизначає модель LLM, яка використовується для відповідей у голосових каналах Discord. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` передаються до параметрів DAVE `@discordjs/voice` (типово `true` і `24`). +- `channels.discord.voice.connectTimeoutMs` керує початковим очікуванням Ready `@discordjs/voice` для `/vc join` і спроб автоприєднання (типово `30000`). +- `channels.discord.voice.reconnectGraceMs` керує тим, скільки часу від’єднаний голосовий сеанс може переходити до сигналізування повторного підключення, перш ніж OpenClaw знищить його (типово `15000`). +- OpenClaw додатково намагається відновити приймання голосу, залишаючи голосовий сеанс і повторно приєднуючись до нього після повторних збоїв розшифрування. - `channels.discord.streaming` є канонічним ключем режиму потоку. Застарілі значення `streamMode` і булеві значення `streaming` мігруються автоматично. -- `channels.discord.autoPresence` зіставляє доступність середовища виконання з присутністю бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов'язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає зіставлення змінних імен/тегів (режим сумісності на випадок аварійного доступу). -- `channels.discord.execApprovals`: нативна для Discord доставка схвалень exec і авторизація схвалювачів. - - `enabled`: `true`, `false` або `"auto"` (за замовчуванням). В автоматичному режимі схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ідентифікатори користувачів Discord, яким дозволено схвалювати запити exec. Якщо пропущено, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов'язковий allowlist ідентифікаторів агентів. Пропустіть, щоб пересилати схвалення для всіх агентів. - - `sessionFilter`: необов'язкові шаблони ключів сесій (підрядок або регулярний вираз). - - `target`: куди надсилати запити на схвалення. `"dm"` (за замовчуванням) надсилає в DM схвалювачів, `"channel"` надсилає в початковий канал, `"both"` надсилає в обидва місця. Коли target містить `"channel"`, кнопки доступні лише визначеним схвалювачам. - - `cleanupAfterResolve`: коли `true`, видаляє DM зі схваленнями після схвалення, відмови або тайм-ауту. +- `channels.discord.autoPresence` зіставляє доступність середовища виконання з присутністю бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає змінне зіставлення імен/тегів (режим аварійної сумісності). +- `channels.discord.execApprovals`: доставлення схвалень exec і авторизація схвалювачів у рідному форматі Discord. + - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ідентифікатори користувачів Discord, яким дозволено схвалювати запити exec. Якщо пропущено, використовується резервний варіант `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий список дозволених ідентифікаторів агентів. Пропустіть, щоб пересилати схвалення для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або регулярний вираз). + - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в DM схвалювачам, `"channel"` надсилає до початкового каналу, `"both"` надсилає в обидва місця. Коли ціль містить `"channel"`, кнопки можуть використовувати лише визначені схвалювачі. + - `cleanupAfterResolve`: коли `true`, видаляє DM зі схваленнями після схвалення, відхилення або тайм-ауту. -**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, за замовчуванням), `all` (усі повідомлення), `allowlist` (з `guilds..users` для всіх повідомлень). +**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (з `guilds..users` для всіх повідомлень). ### Google Chat @@ -396,11 +396,11 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- JSON облікового запису служби: вбудований (`serviceAccount`) або файловий (`serviceAccountFile`). +- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`). - SecretRef облікового запису служби також підтримується (`serviceAccountRef`). -- Резервні значення env: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Використовуйте `spaces/` або `users/` для цілей доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення змінного email principal (режим сумісності на випадок аварійного доступу). +- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Використовуйте `spaces/` або `users/` для цілей доставлення. +- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає змінне зіставлення принципалів електронної пошти (режим аварійної сумісності). ### Slack @@ -472,44 +472,44 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного значення env облікового запису за замовчуванням). -- **HTTP mode** потребує `botToken` плюс `signingSecret` (на кореневому рівні або для окремого облікового запису). -- `socketMode` передає налаштування транспорту Slack SDK Socket Mode до публічного API Bolt receiver. Використовуйте це лише під час дослідження тайм-аутів ping/pong або застарілої поведінки websocket. +- **Режим сокета** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного середовища типового облікового запису). +- **Режим HTTP** потребує `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). +- `socketMode` передає налаштування транспорту Socket Mode SDK Slack до публічного API приймача Bolt. Використовуйте його лише під час дослідження тайм-аутів ping/pong або поведінки застарілого websocket. - `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті текстові - рядки або об'єкти SecretRef. -- Знімки облікових записів Slack відкривають поля джерела/статусу для окремих облікових даних, як-от - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, в HTTP mode, + рядки або об’єкти SecretRef. +- Знімки облікових записів Slack надають поля джерела/статусу для окремих облікових даних, як-от + `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в режимі HTTP — `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef, але поточний шлях команди/середовища виконання не зміг визначити значення секрету. - `configWrites: false` блокує записи конфігурації, ініційовані Slack. -- Необов'язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, коли він відповідає налаштованому ідентифікатору облікового запису. -- `channels.slack.streaming.mode` є канонічним ключем режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві значення `streaming` і значення `nativeStreaming` мігруються автоматично. -- Використовуйте `user:` (DM) або `channel:` для цілей доставки. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з налаштованим ідентифікатором облікового запису. +- `channels.slack.streaming.mode` є канонічним ключем режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує рідним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві значення `streaming` і значення `nativeStreaming` мігруються автоматично. +- Використовуйте `user:` (DM) або `channel:` для цілей доставлення. -**Режими сповіщень про реакції:** `off`, `own` (за замовчуванням), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). -**Ізоляція сесій потоків:** `thread.historyScope` є окремим для потоку (за замовчуванням) або спільним у межах каналу. `thread.inheritParent` копіює стенограму батьківського каналу до нових потоків. +**Ізоляція сеансів гілок:** `thread.historyScope` застосовується для окремої гілки (типово) або спільно для всього каналу. `thread.inheritParent` копіює транскрипт батьківського каналу до нових гілок. -- Нативний стримінг Slack плюс статус потоку в стилі Slack assistant "is typing..." потребують цільового потоку відповіді. DM верхнього рівня за замовчуванням залишаються поза потоками, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі потоку. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки відповідь виконується, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна для Slack доставка схвалень exec і авторизація схвалювачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Рідне потокове передавання Slack разом зі статусом гілки в стилі асистента Slack "is typing..." потребують цілі гілки для відповіді. DM верхнього рівня типово залишаються поза гілками, тому вони використовують `typingReaction` або звичайне доставлення замість попереднього перегляду в стилі гілки. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки відповідь виконується, а потім видаляє її після завершення. Використовуйте короткий код емодзі Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: доставлення схвалень exec і авторизація схвалювачів у рідному форматі Slack. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | За замовчуванням | Примітки | +| Група дій | Типово | Примітки | | ------------ | ------- | ---------------------- | | reactions | увімкнено | Реагувати + перелічувати реакції | | messages | увімкнено | Читати/надсилати/редагувати/видаляти | -| pins | увімкнено | Закріпити/відкріпити/перелічити | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список користувацьких emoji | +| pins | увімкнено | Закріплювати/відкріплювати/перелічувати | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список власних емодзі | ### Mattermost -Mattermost постачається як bundled plugin у поточних випусках OpenClaw. Старіші або -кастомні збірки можуть установити поточний npm-пакет за допомогою -`openclaw plugins install @openclaw/mattermost`; якщо npm повідомляє, що -пакет, який належить OpenClaw, застарілий, використовуйте bundled plugin або локальний checkout -до публікації новішого npm-пакета. +Mattermost постачається як bundled Plugin у поточних випусках OpenClaw. Старіші або +власні збірки можуть установити поточний пакет npm за допомогою +`openclaw plugins install @openclaw/mattermost`. Перевіряйте +[npmjs.com/package/@openclaw/mattermost](https://www.npmjs.com/package/@openclaw/mattermost) +для поточних dist-tags перед закріпленням версії. ```json5 { @@ -539,18 +539,23 @@ Mattermost постачається як bundled plugin у поточних ви } ``` -Режими чату: `oncall` (відповідати на @-згадку, за замовчуванням), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). +Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера). -Коли нативні команди Mattermost увімкнені: +Коли рідні команди Mattermost увімкнені: - `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. -- `commands.callbackUrl` має вказувати на кінцеву точку Gateway OpenClaw і бути доступним із сервера Mattermost. -- Нативні зворотні виклики slash-команд автентифікуються токенами окремих команд, які повертає Mattermost під час реєстрації slash-команд. Якщо реєстрація завершується невдало або жодні команди не активовано, OpenClaw відхиляє зворотні виклики з повідомленням `Unauthorized: invalid command token.` -- Для приватних/tailnet/внутрішніх хостів зворотних викликів Mattermost може вимагати, щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. Використовуйте значення хоста/домену, а не повні URL-адреси. -- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані Mattermost записи конфігурації. +- `commands.callbackUrl` має резолвитися до endpoint Gateway OpenClaw і бути доступним із сервера Mattermost. +- Нативні slash callback автентифікуються токенами для окремих команд, які повертає + Mattermost під час реєстрації slash command. Якщо реєстрація завершується невдало або жодні + команди не активовано, OpenClaw відхиляє callback з + `Unauthorized: invalid command token.` +- Для приватних/tailnet/внутрішніх хостів callback Mattermost може вимагати, щоб + `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback. + Використовуйте значення хоста/домену, а не повні URL-адреси. +- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: поканальне перевизначення блокування за згадкою (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення gating згадок для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з id налаштованого облікового запису. ### Signal @@ -574,12 +579,12 @@ Mattermost постачається як bundled plugin у поточних ви **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). - `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити ініційовані Signal записи конфігурації. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису. +- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані Signal. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з id налаштованого облікового запису. ### BlueBubbles -BlueBubbles — рекомендований шлях iMessage (підтримується Plugin, налаштовується в `channels.bluebubbles`). +BlueBubbles — рекомендований шлях iMessage (на базі Plugin, налаштовується в `channels.bluebubbles`). ```json5 { @@ -594,14 +599,14 @@ BlueBubbles — рекомендований шлях iMessage (підтриму } ``` -- Основні ключові шляхи, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до сталих сесій ACP. Використовуйте handle BlueBubbles або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Семантика спільних полів: [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings). +- Основні ключові шляхи, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з id налаштованого облікового запису. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до сталих сесій ACP. Використовуйте handle BlueBubbles або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings). - Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Daemon або порт не потрібні. ```json5 { @@ -625,15 +630,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з id налаштованого облікового запису. -- Потрібен Full Disk Access до бази даних Messages. -- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб перелічити чати. +- Потребує Full Disk Access до DB Messages. +- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб перелічити чати. - `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. -- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ relay-хоста вже є в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити ініційовані iMessage записи конфігурації. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до сталих сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Семантика спільних полів: [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings). +- `attachmentRoots` і `remoteAttachmentRoots` обмежують вхідні шляхи вкладень (типово: `/Users/*/Library/Messages/Attachments`). +- SCP використовує сувору перевірку host key, тому переконайтеся, що ключ relay-хоста вже існує в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані iMessage. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до сталих сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [Агенти ACP](/uk/tools/acp-agents#persistent-channel-bindings). @@ -646,7 +651,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix підтримується Plugin і налаштовується в `channels.matrix`. +Matrix працює на базі Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -676,25 +681,25 @@ Matrix підтримується Plugin і налаштовується в `cha } ``` -- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. +- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. - `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver. `proxy` і ця згода на мережу є незалежними елементами керування. -- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у налаштуваннях із кількома обліковими записами. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові DM-подібні запрошення ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: нативна для Matrix доставка схвалень exec і авторизація схвалювачів. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ідентифікатори користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено схвалювати exec-запити. - - `agentFilter`: необов’язковий allowlist ідентифікаторів агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver. `proxy` і ця мережева opt-in опція є незалежними елементами керування. +- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення у стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: Matrix-native доставлення схвалень exec і авторизація approver. + - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли approver можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати exec-запити. + - `agentFilter`: необов’язковий allowlist ID агентів. Пропустіть, щоб пересилати схвалення для всіх агентів. - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`. + - `target`: куди надсилати prompts схвалення. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`. - Перевизначення для окремих облікових записів: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовується за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Проби статусу Matrix і live-пошуки в каталозі використовують ту саму політику проксі, що й runtime-трафік. -- Повну конфігурацію Matrix, правила націлювання та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). +- `channels.matrix.dm.sessionScope` керує тим, як Matrix DM групуються в сесії: `per-user` (типово) спільно використовуються за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Status probes Matrix і live directory lookups використовують ту саму proxy policy, що й runtime-трафік. +- Повну конфігурацію Matrix, правила targeting і приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams підтримується Plugin і налаштовується в `channels.msteams`. +Microsoft Teams працює на базі Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -709,12 +714,12 @@ Microsoft Teams підтримується Plugin і налаштовуєтьс } ``` -- Основні ключові шляхи, описані тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих команд/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Основні ключові шляхи, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC підтримується Plugin і налаштовується в `channels.irc`. +IRC працює на базі Plugin і налаштовується в `channels.irc`. ```json5 { @@ -735,13 +740,13 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -- Основні ключові шляхи, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з ідентифікатором налаштованого облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/блокування за згадкою) задокументовано в [IRC](/uk/channels/irc). +- Основні ключові шляхи, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, коли він збігається з id налаштованого облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/mention gating) задокументовано в [IRC](/uk/channels/irc). ### Кілька облікових записів (усі канали) -Запускайте кілька облікових записів на канал (кожен із власним `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -762,34 +767,34 @@ IRC підтримується Plugin і налаштовується в `channe } ``` -- `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). +- `default` використовується, коли `accountId` пропущено (CLI + routing). - Env-токени застосовуються лише до **типового** облікового запису. - Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або onboarding каналу), залишаючись на конфігурації каналу верхнього рівня з одним обліковим записом, OpenClaw спочатку переносить значення верхнього рівня, що належать до облікового запису, у map облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переміщує їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -- Наявні прив’язки лише до каналу (без `accountId`) і далі відповідають типовому обліковому запису; прив’язки з областю облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису в підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовує `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Якщо ви додаєте не типовий обліковий запис через `openclaw channels add` (або onboarding каналу), усе ще маючи конфігурацію каналу верхнього рівня з одним обліковим записом, OpenClaw спершу просуває account-scoped значення верхнього рівня для одного облікового запису в карту облікових записів каналу, щоб оригінальний обліковий запис продовжив працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні channel-only прив’язки (без `accountId`) продовжують відповідати типовому обліковому запису; account-scoped прив’язки залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи account-scoped значення верхнього рівня для одного облікового запису в просунутий обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -### Інші канали Plugin +### Інші Plugin-канали -Багато каналів Plugin налаштовуються як `channels.` і задокументовані на своїх спеціальних сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато Plugin-каналів налаштовуються як `channels.` і задокументовані на своїх спеціалізованих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Дивіться повний індекс каналів: [Канали](/uk/channels). -### Блокування групового чату за згадкою +### Mention gating у груповому чаті -Групові повідомлення типово **вимагають згадку** (метадані згадки або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібна згадка** (metadata mention або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. -Видимі відповіді контролюються окремо. Групові/канальні кімнати типово мають `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw усе ще обробляє turn, але звичайні фінальні відповіді залишаються приватними, а видимий вивід у кімнату вимагає `message(action=send)`. Задавайте `"automatic"` лише тоді, коли потрібна legacy-поведінка, за якої звичайні відповіді публікуються назад у кімнату. Щоб застосувати таку саму поведінку видимих відповідей лише через інструмент і до прямих чатів, задайте `messages.visibleReplies: "message_tool"`; Codex harness також використовує таку поведінку лише через інструмент як своє типове значення для прямих чатів, коли воно не задане. +Видимі відповіді керуються окремо. Для групових/канальних кімнат типово `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw усе ще обробляє turn, але звичайні фінальні відповіді залишаються приватними, а видимий вивід у кімнату потребує `message(action=send)`. Задавайте `"automatic"` лише тоді, коли потрібна legacy-поведінка, за якої звичайні відповіді публікуються назад у кімнату. Щоб застосувати таку саму поведінку видимих відповідей лише через tool і до прямих чатів, задайте `messages.visibleReplies: "message_tool"`; Codex harness також використовує цю поведінку лише через tool як своє незадане типове значення для прямого чату. -Якщо інструмент повідомлень недоступний за активною політикою інструментів, OpenClaw повертається до автоматичних видимих відповідей замість мовчазного придушення відповіді. `openclaw doctor` попереджає про цю невідповідність. +Якщо message tool недоступний за активною tool policy, OpenClaw повертається до автоматичних видимих відповідей замість того, щоб мовчки пригнічувати відповідь. `openclaw doctor` попереджає про цю невідповідність. -Gateway гаряче перезавантажує конфігурацію `messages` після збереження файлу. Перезапуск потрібен лише тоді, коли відстеження файлів або перезавантаження конфігурації вимкнено в розгортанні. +Gateway гаряче перезавантажує конфігурацію `messages` після збереження файлу. Перезапускайте лише тоді, коли file watching або перезавантаження конфігурації вимкнено в deployment. **Типи згадок:** -- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються. -- Блокування за згадкою застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Metadata mentions**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Text patterns**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються. +- Mention gating застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). ```json5 { @@ -808,9 +813,9 @@ Gateway гаряче перезавантажує конфігурацію `mess `messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначити його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. -`messages.visibleReplies` є глобальним значенням за замовчуванням для вихідного ходу; `messages.groupChat.visibleReplies` перевизначає його для вихідних ходів групи/каналу. Коли `messages.visibleReplies` не задано, harness може надати власне значення за замовчуванням для прямих/вихідних чатів; harness Codex за замовчуванням використовує `message_tool`. Списки дозволених каналів і шлюзування за згадками все одно визначають, чи буде хід оброблено. +`messages.visibleReplies` — це глобальне значення за замовчуванням для вихідного ходу; `messages.groupChat.visibleReplies` перевизначає його для вихідних ходів групи/каналу. Коли `messages.visibleReplies` не задано, harness може надати власне значення за замовчуванням для прямих/вихідних чатів; harness Codex за замовчуванням використовує `message_tool`. Списки дозволених каналів і шлюз згадувань усе ще визначають, чи обробляється хід. -#### Ліміти історії DM +#### Обмеження історії DM ```json5 { @@ -825,13 +830,13 @@ Gateway гаряче перезавантажує конфігурацію `mess } ``` -Порядок визначення: перевизначення для окремого DM → стандартне значення провайдера → без ліміту (зберігається все). +Визначення: перевизначення для окремого DM → значення провайдера за замовчуванням → без обмеження (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим чату із собою -Додайте власний номер до `allowFrom`, щоб увімкнути режим чату із собою (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): +Додайте власний номер до `allowFrom`, щоб увімкнути режим чату із собою (ігнорує нативні @-згадування, відповідає лише на текстові шаблони): ```json5 { @@ -852,7 +857,7 @@ Gateway гаряче перезавантажує конфігурацію `mess } ``` -### Команди (обробка команд у чаті) +### Команди (обробка команд чату) ```json5 { @@ -881,32 +886,32 @@ Gateway гаряче перезавантажує конфігурацію `mess -- Цей блок налаштовує поверхні команд. Поточний вбудований і комплектний каталог команд див. у [командах Slash](/uk/tools/slash-commands). -- Ця сторінка є **довідником ключів конфігурації**, а не повним каталогом команд. Команди, що належать каналам/Plugin, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, пам’ять `/dreaming`, керування телефоном `/phone` і Talk `/voice`, задокументовано на сторінках відповідних каналів/Plugin, а також у [командах Slash](/uk/tools/slash-commands). +- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих і bundled команд див. у [Slash Commands](/uk/tools/slash-commands). +- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналам/Plugin, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, пам’ять `/dreaming`, керування телефоном `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. -- `native: "auto"` вмикає нативні команди для Discord/Telegram, а Slack залишає вимкненим. -- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, а Slack залишає вимкненим. -- Перевизначення для каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначте реєстрацію нативних Skills для каналу за допомогою `channels..commands.nativeSkills`. +- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. +- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. +- Перевизначення для каналу: `channels.discord.commands.native` (булеве значення або `"auto"`). `false` очищає раніше зареєстровані команди. +- Перевизначте нативну реєстрацію Skills для каналу через `channels..commands.nativeSkills`. - `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. - `bash: true` вмикає `! ` для оболонки хоста. Потребує `tools.elevated.enabled` і відправника в `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читає/записує `openclaw.json`). Для клієнтів Gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів-операторів із правом запису. +- `config: true` вмикає `/config` (читає/записує `openclaw.json`). Для клієнтів Gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступна лише для читання команда `/config show` залишається доступною звичайним клієнтам оператора з областю запису. - `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, керованого OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення Plugin, встановлення та керування вмиканням/вимиканням. +- `plugins: true` вмикає `/plugins` для виявлення, встановлення та керування ввімкненням/вимкненням Plugin. - `channels..configWrites` обмежує мутації конфігурації для каналу (за замовчуванням: true). -- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також обмежує записи, спрямовані на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). +- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також обмежує записи, націлені на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). - `restart: false` вимикає `/restart` і дії інструмента перезапуску Gateway. За замовчуванням: `true`. -- `ownerAllowFrom` є явним списком дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. -- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному prompt. Задайте `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених каналів/сполучення та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не задано. -- Карта документації команд: - - вбудований і комплектний каталог: [команди Slash](/uk/tools/slash-commands) - - поверхні команд для окремих каналів: [Канали](/uk/channels) +- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. +- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному prompt. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених каналів/спарювання та `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено. +- Мапа документації команд: + - каталог вбудованих і bundled команд: [Slash Commands](/uk/tools/slash-commands) + - поверхні команд, специфічні для каналів: [Канали](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - - команди сполучення: [Сполучення](/uk/channels/pairing) + - команди спарювання: [Спарювання](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - Dreaming пам’яті: [Dreaming](/uk/concepts/dreaming) + - dreaming пам’яті: [Dreaming](/uk/concepts/dreaming) diff --git a/docs/uk/plugins/voice-call.md b/docs/uk/plugins/voice-call.md index f4a782589..b8094d150 100644 --- a/docs/uk/plugins/voice-call.md +++ b/docs/uk/plugins/voice-call.md @@ -1,45 +1,45 @@ --- read_when: - - Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw + - Ви хочете здійснити вихідний голосовий виклик з OpenClaw - Ви налаштовуєте або розробляєте Plugin голосових викликів - - Вам потрібен голос у реальному часі або потокова транскрипція в телефонії + - Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція в телефонії sidebarTitle: Voice call -summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з опційним голосом у реальному часі та потоковою транскрипцією -title: Plugin голосових викликів +summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією +title: Plugin голосового виклику x-i18n: - generated_at: "2026-05-02T09:29:40Z" + generated_at: "2026-05-02T21:05:49Z" model: gpt-5.5 provider: openai - source_hash: 8f04b14ad1aafcc6036aff2301d9d0210c0cde333051ed89d498c51b4e0c0353 + source_hash: 1cf78847a16cdf6fddc47d045d1cad5acf70f7f220fb868a12ff9d69d6cbde6e source_path: plugins/voice-call.md workflow: 16 --- -Голосові виклики для OpenClaw через plugin. Підтримує вихідні сповіщення, -багатоходові розмови, повнодуплексний голос у реальному часі, потокову -транскрипцію та вхідні виклики з політиками allowlist. +Голосові виклики для OpenClaw через Plugin. Підтримує вихідні сповіщення, +багатоетапні розмови, повнодуплексний голос у реальному часі, потокову +транскрипцію та вхідні виклики з політиками списку дозволених. **Поточні провайдери:** `twilio` (Programmable Voice + Media Streams), `telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput speech), `mock` (розробка/без мережі). -Plugin Voice Call працює **усередині процесу Gateway**. Якщо ви використовуєте -віддалений Gateway, установіть і налаштуйте plugin на машині, де працює +Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте +віддалений Gateway, установіть і налаштуйте Plugin на машині, де працює Gateway, а потім перезапустіть Gateway, щоб завантажити його. ## Швидкий старт - + - + ```bash openclaw plugins install @openclaw/voice-call ``` - + ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin openclaw plugins install "$PLUGIN_SRC" @@ -48,38 +48,37 @@ Gateway, а потім перезапустіть Gateway, щоб заванта - Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий, ця версія пакета - походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку - OpenClaw або шлях до локальної папки, доки не буде опубліковано новіший npm-пакет. + Використовуйте `@openclaw/voice-call@beta`, коли стежите за бета-каналом OpenClaw і + npmjs показує `beta` попереду `latest`. - Після цього перезапустіть Gateway, щоб plugin завантажився. + Після цього перезапустіть 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 @@ -89,21 +88,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта -Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічний URL webhook**. +Для Twilio, Telnyx і Plivo налаштування має визначати **публічну URL-адресу Webhook**. Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість -запуску провайдера, який не зможе отримувати carrier webhooks. +запуску провайдера, який не зможе отримувати Webhook від оператора. ## Конфігурація Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних, -під час запуску Gateway у журнал записується попередження setup-incomplete з відсутніми ключами, і -runtime не запускається. Команди, RPC-виклики та інструменти агента все одно +під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та +пропускає запуск 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 @@ -176,27 +175,27 @@ runtime не запускається. Команди, RPC-виклики та ``` - - - Twilio, Telnyx і Plivo вимагають **публічно доступного** URL webhook. - - `mock` — локальний dev-провайдер (без мережевих викликів). - - 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. + + - Twilio, Telnyx і Plivo всі потребують **публічно доступної** URL-адреси Webhook. + - `mock` — локальний провайдер для розробки (без мережевих викликів). + - 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. - - - `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають дійсний кадр `start`. - - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту. - - `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети до старту для кожної вихідної IP-адреси. - - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікуваних + активних). + + - `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний фрейм `start`. + - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих pre-start сокетів. + - `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані pre-start сокети на одну вихідну IP-адресу. + - `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувані + активні). - - Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі - ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`. - Runtime fallback поки що приймає старі ключі voice-call, але + + Старіші конфігурації з `provider: "log"`, `twilio.from` або застарілими + ключами OpenAI `streaming.*` переписуються командою `openclaw doctor --fix`. + Резервний шлях runtime поки що приймає старі ключі voice-call, але шлях переписування — це `openclaw doctor --fix`, а сумісний shim є тимчасовим. @@ -211,51 +210,51 @@ runtime не запускається. Команди, RPC-виклики та -## Область сесії +## Область сеансу За замовчуванням Voice Call використовує `sessionScope: "per-phone"`, щоб повторні виклики від -того самого абонента зберігали пам’ять розмови. Установіть `sessionScope: "per-call"`, коли -кожен carrier call має починатися зі свіжого контексту, наприклад для рецепції, -бронювання, IVR або bridge-потоків Google Meet, де той самий номер телефону може -представляти різні зустрічі. +того самого абонента зберігали пам’ять розмови. Задайте `sessionScope: "per-call"`, коли +кожен операторський виклик має починатися зі свіжим контекстом, наприклад для рецепції, +бронювання, IVR або потоків мосту Google Meet, де той самий номер телефону може +позначати різні зустрічі. ## Голосові розмови в реальному часі -`realtime` вибирає провайдера повнодуплексного голосу в реальному часі для live call -audio. Це окремо від `streaming`, який лише пересилає аудіо -провайдерам транскрипції в реальному часі. +`realtime` вибирає повнодуплексного голосового провайдера реального часу для live-аудіо +виклику. Це окремо від `streaming`, який лише передає аудіо +провайдерам транскрипції реального часу. `realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один -аудіорежим для кожного виклику. +аудіорежим на виклик. Поточна поведінка 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`), зареєстровані їхніми Plugin провайдерів. - Сира конфігурація, якою володіє провайдер, розміщується в `realtime.providers.`. -- 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` для ізольованих викликів). +- 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-медіа замість того, щоб завершити весь 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` усе одно передаються провайдеру realtime. | +| `safe-read-only` | Надає інструмент consult і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. | +| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати нормальну політику інструментів агента. | +| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` усе одно передаються realtime-провайдеру. | -### Приклади провайдерів realtime +### Приклади realtime-провайдерів - Типові значення: API-ключ із `realtime.providers.google.apiKey`, + Стандартні значення: API-ключ із `realtime.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_GENERATIVE_AI_API_KEY`; модель `gemini-2.5-flash-native-audio-preview-12-2025`; голос `Kore`. @@ -313,25 +312,25 @@ audio. Це окремо від `streaming`, який лише пересила Див. [провайдера Google](/uk/providers/google) і -[провайдера OpenAI](/uk/providers/openai) для специфічних для провайдера опцій голосу realtime. +[провайдера OpenAI](/uk/providers/openai), щоб дізнатися про специфічні для провайдера параметри голосу реального часу. ## Потокова транскрипція -`streaming` вибирає провайдера транскрипції в реальному часі для live call audio. +`streaming` вибирає провайдера транскрипції реального часу для live-аудіо виклику. Поточна поведінка runtime: -- `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. +- `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. -### Приклади постачальників потокового передавання +### Приклади провайдерів потокового передавання - Типові значення: ключ API `streaming.providers.openai.apiKey` або + Значення за замовчуванням: API-ключ `streaming.providers.openai.apiKey` або `OPENAI_API_KEY`; модель `gpt-4o-transcribe`; `silenceDurationMs: 800`; `vadThreshold: 0.5`. @@ -363,7 +362,7 @@ audio. Це окремо від `streaming`, який лише пересила - Типові значення: ключ API `streaming.providers.xai.apiKey` або `XAI_API_KEY`; + Значення за замовчуванням: API-ключ `streaming.providers.xai.apiKey` або `XAI_API_KEY`; кінцева точка `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`; `endpointingMs: 800`; `interimResults: true`. @@ -398,8 +397,8 @@ audio. Це окремо від `streaming`, який лише пересила ## TTS для викликів Voice Call використовує основну конфігурацію `messages.tts` для потокового -мовлення під час викликів. Її можна перевизначити в конфігурації Plugin з -**такою самою формою** — вона глибоко зливається з `messages.tts`. +мовлення під час викликів. Її можна перевизначити в конфігу plugin з +**тією самою формою** — вона глибоко об'єднується з `messages.tts`. ```json5 { @@ -420,18 +419,18 @@ Voice Call використовує основну конфігурацію `mes поточний транспорт 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`) для налагодження. -- Коли втручання Twilio або демонтаж потоку очищає чергу TTS, запити на відтворення в черзі завершуються замість того, щоб залишати абонентів у стані очікування завершення відтворення. +- Застарілі ключі `tts.` у конфігу plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються через `openclaw doctor --fix`; зафіксований конфіг має використовувати `tts.providers.`. +- Core TTS використовується, коли потокове передавання медіа Twilio увімкнено; інакше виклики повертаються до нативних голосів провайдера. +- Якщо медіапотік Twilio уже активний, Voice Call не повертається до TwiML ``. Якщо телефонний TTS у цьому стані недоступний, запит відтворення завершується помилкою замість змішування двох шляхів відтворення. +- Коли телефонний TTS повертається до вторинного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження. +- Коли barge-in Twilio або демонтаж потоку очищає чергу TTS, що очікує, запити відтворення в черзі завершуються, а не залишають абонентів чекати завершення відтворення. ### Приклади TTS - + ```json5 { messages: { @@ -445,7 +444,7 @@ Voice Call використовує основну конфігурацію `mes } ``` - + ```json5 { plugins: { @@ -469,7 +468,7 @@ Voice Call використовує основну конфігурацію `mes } ``` - + ```json5 { plugins: { @@ -495,7 +494,7 @@ Voice Call використовує основну конфігурацію `mes ## Вхідні виклики -Типова вхідна політика — `disabled`. Щоб увімкнути вхідні виклики, задайте: +Вхідна політика за замовчуванням має значення `disabled`. Щоб увімкнути вхідні виклики, задайте: ```json5 { @@ -506,28 +505,33 @@ Voice Call використовує основну конфігурацію `mes ``` -`inboundPolicy: "allowlist"` — це перевірка ідентифікатора абонента з низькою гарантією. Plugin нормалізує надане постачальником значення `From` і порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку постачальником і цілісність корисного навантаження, але **не** доводить володіння номером абонента PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію за caller ID, а не як надійну ідентичність абонента. +`inboundPolicy: "allowlist"` — це перевірка caller-ID із низьким рівнем гарантії. Plugin +нормалізує надане провайдером значення `From` і порівнює його з +`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і +цілісність корисного навантаження, але **не** доводить право власності на номер +PSTN/VoIP абонента. Розглядайте `allowFrom` як фільтрацію caller-ID, а не як надійну +ідентифікацію абонента. -Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`, +Автовідповіді використовують систему агентів. Налаштовуйте їх за допомогою `responseModel`, `responseSystemPrompt` і `responseTimeoutMs`. ### Маршрутизація за номером Використовуйте `numbers`, коли один Voice Call plugin приймає виклики для кількох телефонних номерів і кожен номер має поводитися як окрема лінія. Наприклад, один -номер може використовувати невимушеного персонального помічника, а інший — бізнес- +номер може використовувати невимушеного персонального асистента, а інший — бізнес- персону, іншого агента відповіді та інший голос TTS. -Маршрути вибираються з наданого постачальником набраного номера `To`. Ключі мають бути -номерами E.164. Коли надходить виклик, Voice Call один раз визначає відповідний маршрут, -зберігає зіставлений маршрут у записі виклику та повторно використовує цю ефективну конфігурацію +Маршрути вибираються з набраного номера `To`, наданого провайдером. Ключі мають бути +номерами E.164. Коли виклик надходить, Voice Call один раз визначає відповідний маршрут, +зберігає зіставлений маршрут у записі виклику й повторно використовує цей ефективний конфіг для привітання, класичного шляху автовідповіді, шляху консультації в реальному часі та -відтворення TTS. Якщо жоден маршрут не збігається, використовується глобальна конфігурація Voice Call. -Вихідні виклики не використовують `numbers`; передавайте вихідну ціль, повідомлення та -сеанс явно під час ініціювання виклику. +відтворення TTS. Якщо жоден маршрут не збігається, використовується глобальний конфіг Voice Call. +Вихідні виклики не використовують `numbers`; під час ініціювання виклику передавайте ціль вихідного виклику, повідомлення та +сеанс явно. -Перевизначення маршрутів наразі підтримують: +Перевизначення маршруту наразі підтримують: - `inboundGreeting` - `tts` @@ -536,8 +540,8 @@ Voice Call використовує основну конфігурацію `mes - `responseSystemPrompt` - `responseTimeoutMs` -Значення маршруту `tts` глибоко зливається поверх глобальної конфігурації Voice Call `tts`, тож -зазвичай можна перевизначити лише голос постачальника: +Значення маршруту `tts` глибоко об'єднується поверх глобального конфігу Voice Call `tts`, тож +зазвичай можна перевизначити лише голос провайдера: ```json5 { @@ -563,9 +567,9 @@ Voice Call використовує основну конфігурацію `mes } ``` -### Контракт мовленого виводу +### Контракт усного виводу -Для автовідповідей Voice Call додає строгий контракт мовленого виводу до +Для автовідповідей Voice Call додає суворий контракт усного виводу до системного prompt: ```text @@ -574,41 +578,41 @@ Voice Call використовує основну конфігурацію `mes Voice Call захисно витягує текст мовлення: -- Ігнорує корисні навантаження, позначені як вміст reasoning/помилки. +- Ігнорує корисні навантаження, позначені як вміст reasoning/error. - Розбирає прямий JSON, JSON у fenced-блоці або вбудовані ключі `"spoken"`. -- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаопису. +- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци планування/метаданих. -Це зосереджує мовлене відтворення на тексті для абонента й запобігає -потраплянню тексту планування в аудіо. +Це утримує голосове відтворення зосередженим на тексті для абонента та запобігає +витоку тексту планування в аудіо. ### Поведінка запуску розмови Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного стану відтворення: -- Очищення черги через втручання й автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється. +- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується. - Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби. -- Початкове відтворення для потокового передавання Twilio запускається під час підключення потоку без додаткової затримки. -- Втручання перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не буде відтворено. -- Голосові розмови в реальному часі використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сеанси `` залишаються приєднаними. +- Початкове відтворення для потокового передавання Twilio починається під час підключення потоку без додаткової затримки. +- Barge-in перериває активне відтворення й очищає записи Twilio TTS, що перебувають у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжити роботу, не чекаючи аудіо, яке ніколи не буде відтворено. +- Голосові розмови в реальному часі використовують власний початковий хід потоку реального часу. Voice Call **не** надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тож вихідні сеанси `` залишаються підключеними. -### Пільговий період від'єднання потоку Twilio +### Пільговий період відключення потоку Twilio -Коли медіапотік Twilio від'єднується, Voice Call чекає **2000 мс** перед -автоматичним завершенням виклику: +Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс**, перш ніж +автоматично завершити виклик: - Якщо потік повторно підключається протягом цього вікна, автоматичне завершення скасовується. - Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам. -## Прибирач застарілих викликів +## Очищувач застарілих викликів -Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний -Webhook (наприклад, виклики в режимі сповіщення, що ніколи не завершуються). Типове значення +Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують кінцевий +webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Значення за замовчуванням — `0` (вимкнено). Рекомендовані діапазони: -- **Production:** `120`–`300` секунд для потоків у стилі сповіщення. +- **Продакшн:** `120`–`300` секунд для потоків у стилі сповіщень. - Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд. ```json5 @@ -628,26 +632,26 @@ Webhook (наприклад, виклики в режимі сповіщення ## Безпека Webhook -Коли перед Gateway стоїть проксі або тунель, Plugin -реконструює публічну URL-адресу для перевірки підпису. Ці параметри -керують тим, яким forwarded-заголовкам довіряти: +Коли proxy або tunnel стоїть перед Gateway, plugin +відновлює публічний URL для перевірки підпису. Ці опції +керують тим, яким пересланим заголовкам довіряти: - Список дозволених хостів із forwarding-заголовків. + Allowlist хостів із заголовків пересилання. - Довіряти forwarded-заголовкам без списку дозволених. + Довіряти пересланим заголовкам без allowlist. - Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. + Довіряти пересланим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. -Додатковий захист: +Додаткові захисти: - **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені чинні webhook-запити підтверджуються, але пропускаються для побічних ефектів. -- Ходи розмови Twilio містять токен для кожного ходу в callback-викликах ``, тому застарілі/повторно відтворені callback-виклики мовлення не можуть задовольнити новіший очікуваний хід транскрипту. -- Неавтентифіковані webhook-запити відхиляються до читання тіла, коли відсутні обов'язкові signature-заголовки постачальника. -- Webhook voice-call використовує спільний pre-auth профіль тіла (64 КБ / 5 секунд) плюс ліміт одночасних запитів на IP перед перевіркою підпису. +- Ходи розмови Twilio містять токен для кожного ходу в callback-ах ``, тому застарілі/повторно відтворені callback-и мовлення не можуть задовольнити новіший хід транскрипту, що очікує. +- Неавтентифіковані webhook-запити відхиляються до читання тіла, коли відсутні обов'язкові заголовки підпису провайдера. +- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс обмеження одночасних запитів на IP перед перевіркою підпису. Приклад зі стабільним публічним хостом: @@ -683,15 +687,15 @@ openclaw voicecall latency # summarize turn latency from lo openclaw voicecall expose --mode funnel ``` -Коли Gateway уже запущено, операційні команди `voicecall` делегуються +Коли Gateway уже запущений, операційні команди `voicecall` делегують виконання voice-call runtime, що належить Gateway, щоб CLI не прив'язував другий -webhook-сервер. Якщо Gateway недоступний, команди повертаються до -самостійного CLI runtime. +webhook-сервер. Якщо жоден Gateway недоступний, команди повертаються до +автономного CLI runtime. -`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call. +`latency` читає `calls.jsonl` зі стандартного шляху сховища голосових викликів. Використовуйте `--file `, щоб указати інший журнал, і `--last `, щоб обмежити аналіз останніми N записами (за замовчуванням 200). Вивід містить p50/p90/p99 -для затримки ходу та часу очікування слухання. +для затримки ходу та часу очікування прослуховування. ## Інструмент агента @@ -706,9 +710,9 @@ webhook-сервер. Якщо Gateway недоступний, команди п | `end_call` | `callId` | | `get_status` | `callId` | -Цей репозиторій постачається з відповідним документом Skills за адресою `skills/voice-call/SKILL.md`. +Цей репозиторій постачає відповідний документ навички за шляхом `skills/voice-call/SKILL.md`. -## Gateway RPC +## RPC Gateway | Метод | Аргументи | | -------------------- | ------------------------------------------ | @@ -719,13 +723,13 @@ webhook-сервер. Якщо Gateway недоступний, команди п | `voicecall.end` | `callId` | | `voicecall.status` | `callId` | -`dtmfSequence` чинний лише з `mode: "conversation"`. Виклики в режимі сповіщення +`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики в режимі сповіщення мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні -цифри після з’єднання. +цифри після підключення. ## Усунення несправностей -### Налаштування не проходить через доступність webhook +### Налаштування не проходить перевірку доступності webhook Запустіть налаштування з того самого середовища, у якому працює Gateway: @@ -734,17 +738,17 @@ openclaw voicecall setup openclaw voicecall setup --json ``` -Для `twilio`, `telnyx` і `plivo` стан `webhook-exposure` має бути зеленим. Налаштований -`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 +отримає webhook TwiML. Публічний webhook усе одно потрібен для зворотних викликів статусу, +розмовних викликів, DTMF до підключення, потоків реального часу та керування викликом після +підключення. Використовуйте один шлях публічного доступу: @@ -779,17 +783,17 @@ openclaw voicecall smoke Перевірте вибраного провайдера та обов’язкові поля облікових даних: -- Twilio: `twilio.accountSid`, `twilio.authToken` і `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: @@ -808,32 +812,32 @@ openclaw logs --follow Поширені причини: - `publicUrl` указує на інший шлях, ніж `serve.path`. -- URL тунелю змінилася після запуску Gateway. +- URL тунелю змінився після запуску Gateway. - Проксі пересилає запит, але видаляє або переписує заголовки host/proto. -- Брандмауер або DNS спрямовує публічне ім’я хоста кудись, окрім Gateway. +- Firewall або DNS спрямовує публічне ім’я хоста кудись, окрім Gateway. - Gateway було перезапущено без увімкненого Plugin Voice Call. Коли перед Gateway стоїть зворотний проксі або тунель, задайте `webhookSecurity.allowedHosts` як публічне ім’я хоста або використовуйте `webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте -`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває -під вашим контролем. +`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під +вашим контролем. ### Перевірка підпису не проходить -Підписи провайдера перевіряються за публічною URL-адресою, яку OpenClaw відтворює -з вхідного запиту. Якщо перевірка підписів не проходить: +Підписи провайдера перевіряються щодо публічної URL-адреси, яку OpenClaw відновлює +з вхідного запиту. Якщо підписи не проходять перевірку: -- Переконайтеся, що URL webhook провайдера точно збігається з `publicUrl`, включно зі - схемою, хостом і шляхом. -- Для URL ngrok безплатного рівня оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю. -- Переконайтеся, що проксі зберігає оригінальні заголовки host і proto, або налаштуйте +- Переконайтеся, що URL-адреса webhook провайдера точно збігається з `publicUrl`, зокрема + зі схемою, хостом і шляхом. +- Для URL ngrok безкоштовного рівня оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю. +- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте `webhookSecurity.allowedHosts`. - Не вмикайте `skipSignatureVerification` поза локальним тестуванням. -### Не вдається приєднатися до Google Meet через Twilio +### Підключення Google Meet через Twilio не вдаються -Google Meet використовує цей Plugin для приєднання через телефонний набір Twilio. Спочатку перевірте Voice Call: +Google Meet використовує цей Plugin для підключень через дозвон Twilio. Спочатку перевірте Voice Call: ```bash openclaw voicecall setup @@ -846,43 +850,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. +- Google Meet делегує підключення Twilio до Voice Call. +- Voice Call зберігає DTMF TwiML до підключення. +- Початковий TwiML Twilio споживається й обслуговується до обробки реального часу. +- Voice Call обслуговує TwiML реального часу для виклику Twilio. - Міст реального часу запускається з початковим привітанням у черзі. `openclaw voicecall tail` усе ще показує збережені записи викликів; це корисно для -стану виклику й транскриптів, але не кожен webhook-перехід або перехід реального часу -там з’являється. +стану виклику та транскриптів, але не кожен перехід webhook/реального часу там +відображається. -### Виклик у реальному часі не має мовлення +### У виклику реального часу немає мовлення Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і `streaming.enabled` не можуть одночасно бути true. -Для викликів Twilio у реальному часі також перевірте: +Для викликів Twilio в реальному часі також перевірте: -- Plugin провайдера реального часу завантажено та зареєстровано. +- Plugin провайдера реального часу завантажено й зареєстровано. - `realtime.provider` не задано або він називає зареєстрованого провайдера. - API-ключ провайдера доступний процесу Gateway. -- `openclaw logs --follow` показує, що TwiML реального часу віддано, міст реального часу +- `openclaw logs --follow` показує, що TwiML реального часу обслужено, міст реального часу запущено, а початкове привітання поставлено в чергу. ## Пов’язане - [Режим розмови](/uk/nodes/talk) -- [Синтез мовлення](/uk/tools/tts) +- [Перетворення тексту на мовлення](/uk/tools/tts) - [Голосове пробудження](/uk/nodes/voicewake) diff --git a/docs/uk/plugins/zalouser.md b/docs/uk/plugins/zalouser.md index eefe3a4a1..0f025bac6 100644 --- a/docs/uk/plugins/zalouser.md +++ b/docs/uk/plugins/zalouser.md @@ -2,38 +2,38 @@ read_when: - Вам потрібна підтримка Zalo Personal (неофіційна) в OpenClaw - Ви налаштовуєте або розробляєте Plugin zalouser -summary: 'Zalo Personal Plugin: вхід за QR-кодом + обмін повідомленнями через нативний zca-js (встановлення Plugin + конфігурація каналу + інструмент)' +summary: 'Plugin Zalo Personal: вхід за QR-кодом + обмін повідомленнями через нативний zca-js (встановлення Plugin + конфігурація каналу + інструмент)' title: Особистий Plugin Zalo x-i18n: - generated_at: "2026-04-29T05:40:59Z" + generated_at: "2026-05-02T21:05:50Z" model: gpt-5.5 provider: openai - source_hash: 4cbf56d81d4137706fb03b516f65b20f51a4e40ce301c2eaa7923ddc9ac0787f + source_hash: 0649c95317c09fc8316ec371a357d7d41d8bf801d0d9e500a29de13388421973 source_path: plugins/zalouser.md workflow: 16 --- -# Zalo Personal (plugin) +# Zalo Personal (Plugin) -Підтримка Zalo Personal для OpenClaw через plugin із використанням нативного `zca-js` для автоматизації звичайного облікового запису користувача Zalo. +Підтримка Zalo Personal для OpenClaw через Plugin із використанням нативного `zca-js` для автоматизації звичайного облікового запису користувача Zalo. Неофіційна автоматизація може призвести до призупинення або блокування облікового запису. Використовуйте на власний ризик. -## Назва +## Назви -ID каналу — `zalouser`, щоб явно вказати, що це автоматизує **особистий обліковий запис користувача Zalo** (неофіційно). Ми залишаємо `zalo` зарезервованим для потенційної майбутньої інтеграції з офіційним API Zalo. +Ідентифікатор каналу — `zalouser`, щоб явно показати, що це автоматизує **особистий обліковий запис користувача Zalo** (неофіційно). Ми залишаємо `zalo` зарезервованим для потенційної майбутньої офіційної інтеграції з Zalo API. ## Де це працює -Цей plugin працює **всередині процесу Gateway**. +Цей Plugin працює **всередині процесу Gateway**. -Якщо ви використовуєте віддалений Gateway, установіть і налаштуйте його на **машині, де запущено Gateway**, а потім перезапустіть Gateway. +Якщо ви використовуєте віддалений Gateway, установіть і налаштуйте його на **машині, де працює Gateway**, а потім перезапустіть Gateway. -Зовнішній бінарний файл CLI `zca`/`openzca` не потрібен. +Зовнішній CLI-бінарник `zca`/`openzca` не потрібен. -## Встановлення +## Установлення ### Варіант A: установлення з npm @@ -41,13 +41,12 @@ ID каналу — `zalouser`, щоб явно вказати, що це авт openclaw plugins install @openclaw/zalouser ``` -Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія пакета походить -зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку OpenClaw або -шлях до локальної папки, доки не буде опубліковано новіший пакет npm. +Використовуйте `@openclaw/zalouser@beta`, коли працюєте з бета-каналом OpenClaw і npmjs +показує `beta` попереду `latest`. Після цього перезапустіть Gateway. -### Варіант B: установлення з локальної папки (розробка) +### Варіант B: установлення з локальної теки (розробка) ```bash PLUGIN_SRC=./path/to/local/zalouser-plugin @@ -59,7 +58,7 @@ cd "$PLUGIN_SRC" && pnpm install ## Конфігурація -Конфігурація каналу розміщується в `channels.zalouser` (не в `plugins.entries.*`): +Конфігурація каналу міститься в `channels.zalouser` (не в `plugins.entries.*`): ```json5 { @@ -88,9 +87,9 @@ openclaw directory peers list --channel zalouser --query "name" Дії: `send`, `image`, `link`, `friends`, `groups`, `me`, `status` -Дії повідомлень каналу також підтримують `react` для реакцій на повідомлення. +Дії з повідомленнями каналу також підтримують `react` для реакцій на повідомлення. ## Пов’язане -- [Створення plugins](/uk/plugins/building-plugins) -- [Спільнотні plugins](/uk/plugins/community) +- [Створення Plugin-ів](/uk/plugins/building-plugins) +- [Спільнотні Plugin-и](/uk/plugins/community)