From 6bfd1f98ce39a0d8ca49d02e7e319589a7494a4d Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 12:09:02 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/discord.md | 503 ++++++++++++++++++----------------- docs/uk/channels/telegram.md | 479 ++++++++++++++++----------------- 2 files changed, 492 insertions(+), 490 deletions(-) diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index 4376dda99..2ca82588c 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -4,31 +4,31 @@ read_when: summary: Статус підтримки, можливості та конфігурація бота Discord title: Discord x-i18n: - generated_at: "2026-04-29T05:36:30Z" + generated_at: "2026-04-29T12:05:58Z" model: gpt-5.5 provider: openai - source_hash: f25e1e1ed36d9f6f943cdf155d8cab08f031fcaab67477acf04ea7f18f694ec7 + source_hash: 8ae0b2fc79f266bc830c8c8725cb7a1bb1b33d89566c63a80362c7ecb2c863fb source_path: channels/discord.md workflow: 16 --- -Готово для приватних повідомлень і каналів гільдій через офіційний Discord Gateway. +Готово для особистих повідомлень і каналів гільдій через офіційний Discord gateway. - Приватні повідомлення Discord за замовчуванням використовують режим сполучення. + Особисті повідомлення Discord за замовчуванням використовують режим сполучення. Власна поведінка команд і каталог команд. - Діагностика між каналами та потік відновлення. + Діагностика між каналами та процес відновлення. ## Швидке налаштування -Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і сполучити його з OpenClaw. Рекомендуємо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спочатку створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). +Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і спарувати його з OpenClaw. Радимо додати бота на власний приватний сервер. Якщо у вас його ще немає, [спершу створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). @@ -54,12 +54,12 @@ x-i18n: Попри назву, це створює ваш перший токен — нічого не "скидається". - Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він знадобиться вам невдовзі. + Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він скоро вам знадобиться. - Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з правильними дозволами, щоб додати бота на свій сервер. + Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL запрошення з потрібними дозволами, щоб додати бота на свій сервер. Прокрутіть униз до **OAuth2 URL Generator** і ввімкніть: @@ -69,39 +69,39 @@ x-i18n: Нижче з’явиться розділ **Bot Permissions**. Увімкніть щонайменше: **General Permissions** - - Перегляд каналів + - View Channels **Text Permissions** - - Надсилання повідомлень - - Читання історії повідомлень - - Вбудовування посилань - - Прикріплення файлів - - Додавання реакцій (необов’язково) + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions (необов’язково) - Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в гілках Discord, включно з робочими процесами форумних або медіаканалів, які створюють або продовжують гілку, також увімкніть **Надсилати повідомлення в гілках**. - Скопіюйте згенеровану URL-адресу внизу, вставте її у браузер, виберіть свій сервер і натисніть **Продовжити**, щоб підключити. Тепер ви маєте бачити свого бота на сервері Discord. + Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в тредах Discord, зокрема у сценаріях форумних або медіаканалів, які створюють або продовжують тред, також увімкніть **Send Messages in Threads**. + Скопіюйте згенерований URL внизу, вставте його у браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте бачити свого бота на сервері Discord. - - Повернувшись у застосунок Discord, потрібно увімкнути режим розробника, щоб копіювати внутрішні ID. + + Повернувшись у застосунок Discord, потрібно ввімкнути режим розробника, щоб копіювати внутрішні ID. - 1. Натисніть **Налаштування користувача** (піктограма шестерні поруч із вашим аватаром) → **Додатково** → увімкніть **Режим розробника** - 2. Клацніть правою кнопкою миші **піктограму сервера** на бічній панелі → **Копіювати ID сервера** - 3. Клацніть правою кнопкою миші **власний аватар** → **Копіювати ID користувача** + 1. Натисніть **User Settings** (піктограма шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** + 2. Клацніть правою кнопкою миші **піктограму сервера** на бічній панелі → **Copy Server ID** + 3. Клацніть правою кнопкою миші **власний аватар** → **Copy User ID** - Збережіть свої **ID сервера** та **ID користувача** разом із токеном бота — ви надішлете всі три значення в OpenClaw на наступному кроці. + Збережіть свої **Server ID** і **User ID** поруч із Bot Token — на наступному кроці ви надішлете всі три до OpenClaw. - - Щоб сполучення працювало, Discord має дозволяти вашому боту надсилати вам особисті повідомлення. Клацніть правою кнопкою миші **піктограму сервера** → **Налаштування приватності** → увімкніть **Особисті повідомлення**. + + Щоб сполучення працювало, Discord має дозволити вашому боту надсилати вам особисті повідомлення. Клацніть правою кнопкою миші **піктограму сервера** → **Privacy Settings** → увімкніть **Direct Messages**. - Це дозволяє учасникам сервера (включно з ботами) надсилати вам особисті повідомлення. Залиште це ввімкненим, якщо хочете використовувати особисті повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, можете вимкнути особисті повідомлення після сполучення. + Це дозволяє учасникам сервера (зокрема ботам) надсилати вам особисті повідомлення. Залиште це ввімкненим, якщо хочете використовувати особисті повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, можете вимкнути особисті повідомлення після сполучення. - - Токен вашого бота Discord — це секрет (як пароль). Задайте його на машині, де працює OpenClaw, перш ніж писати своєму агенту. + + Токен вашого бота Discord є секретом (як пароль). Установіть його на машині, де запущено OpenClaw, перш ніж писати агенту. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -111,21 +111,21 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - Якщо OpenClaw уже працює як фоновий сервіс, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й заново запустивши процес `openclaw gateway run`. - Для встановлень як керованого сервісу виконайте `openclaw gateway install` з оболонки, де присутня змінна `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб сервіс міг розв'язати env SecretRef після перезапуску. + Якщо OpenClaw уже працює як фонова служба, перезапустіть його через застосунок OpenClaw для Mac або зупинивши й повторно запустивши процес `openclaw gateway run`. + Для інсталяцій керованої служби запустіть `openclaw gateway install` з оболонки, де наявний `DISCORD_BOT_TOKEN`, або збережіть змінну в `~/.openclaw/.env`, щоб служба могла розв’язати env SecretRef після перезапуску. - + - - Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому це. Якщо Discord — ваш перший канал, натомість скористайтеся вкладкою CLI / конфігурації. + + Поспілкуйтеся зі своїм агентом OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і скажіть йому. Якщо Discord є вашим першим каналом, натомість використайте вкладку CLI / config. - > "Я вже задав токен свого бота Discord у конфігурації. Будь ласка, заверши налаштування Discord з ID користувача `` та ID сервера ``." + > "Я вже встановив токен свого бота Discord у конфігурації. Завершіть налаштування Discord з User ID `` і Server ID ``." - - Якщо ви віддаєте перевагу файловій конфігурації, задайте: + + Якщо ви віддаєте перевагу файловій конфігурації, установіть: ```json5 { @@ -142,27 +142,27 @@ openclaw gateway } ``` - Резервне значення env для стандартного облікового запису: + Резерв env для стандартного облікового запису: ```bash DISCORD_BOT_TOKEN=... ``` - Підтримуються значення `token` у відкритому тексті. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Підтримуються відкриті значення `token`. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). - - Зачекайте, доки Gateway запуститься, потім надішліть приватне повідомлення своєму боту в Discord. Він відповість кодом спарювання. + + Дочекайтеся запуску gateway, а потім надішліть боту особисте повідомлення в Discord. Він відповість кодом сполучення. - - Надішліть код спарювання своєму агенту в наявному каналі: + + Надішліть код сполучення своєму агенту в наявному каналі: - > "Схвали цей код спарювання Discord: ``" + > "Схвали цей код сполучення Discord: ``" @@ -174,32 +174,32 @@ openclaw pairing approve discord - Коди спарювання спливають через 1 годину. + Коди сполучення спливають через 1 годину. - Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через DM. + Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через особисті повідомлення. -Визначення токена враховує обліковий запис. Значення токена в конфігурації мають пріоритет над резервним значенням з env. `DISCORD_BOT_TOKEN` використовується лише для облікового запису за замовчуванням. -Якщо два ввімкнені облікові записи Discord визначаються до одного й того самого токена бота, OpenClaw запускає лише один монітор Gateway для цього токена. Токен із конфігурації має пріоритет над резервним значенням env за замовчуванням; інакше перемагає перший увімкнений обліковий запис, а дубльований обліковий запис повідомляється як вимкнений. -Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` для кожного виклику використовується саме для цього виклику. Це стосується дій надсилання та читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису та налаштування повторних спроб усе одно беруться з вибраного облікового запису в активному знімку runtime. +Розв’язання токена враховує обліковий запис. Значення токена з конфігурації мають пріоритет над резервом env. `DISCORD_BOT_TOKEN` використовується лише для стандартного облікового запису. +Якщо два ввімкнені облікові записи Discord розв’язуються в той самий токен бота, OpenClaw запускає лише один монітор gateway для цього токена. Токен із конфігурації має пріоритет над стандартним резервом env; інакше перемагає перший увімкнений обліковий запис, а дубльований обліковий запис повідомляється як вимкнений. +Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` для кожного виклику використовується саме для цього виклику. Це стосується дій send і read/probe-style (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису та налаштування повторних спроб усе одно беруться з вибраного облікового запису в активному знімку runtime. ## Рекомендовано: налаштуйте робочий простір гільдії -Коли DM запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власний сеанс агента зі своїм контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. +Коли особисті повідомлення запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власний сеанс агента з власним контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. - - Це дає вашому агенту змогу відповідати в будь-якому каналі на вашому сервері, а не лише в DM. + + Це дає вашому агенту змогу відповідати в будь-якому каналі на вашому сервері, а не лише в особистих повідомленнях. - - > "Додай ID мого сервера Discord `` до списку дозволених гільдій" + + > "Додай мій Discord Server ID `` до списку дозволених гільдій" - + ```json5 { @@ -222,16 +222,16 @@ openclaw pairing approve discord - - За замовчуванням ваш агент відповідає в каналах гільдії лише тоді, коли його @згадують. Для приватного сервера вам, імовірно, потрібно, щоб він відповідав на кожне повідомлення. + + За замовчуванням ваш агент відповідає в каналах гільдії лише тоді, коли його @згадали. Для приватного сервера ви, ймовірно, захочете, щоб він відповідав на кожне повідомлення. - У каналах гільдії звичайні фінальні відповіді асистента за замовчуванням залишаються приватними. Видимий вивід Discord потрібно явно надсилати інструментом `message`, тож агент може за замовчуванням мовчки спостерігати й публікувати лише тоді, коли вирішить, що відповідь у каналі корисна. + У каналах гільдії звичайні фінальні відповіді помічника за замовчуванням залишаються приватними. Видимий вивід Discord потрібно надсилати явно інструментом `message`, щоб агент за замовчуванням міг залишатися непомітним і публікувати лише тоді, коли вирішить, що відповідь у каналі корисна. - - > "Дозволь моєму агенту відповідати на цьому сервері без потреби бути @згаданим" + + > "Дозволь моєму агенту відповідати на цьому сервері без необхідності @згадки" - + Установіть `requireMention: false` у конфігурації гільдії: ```json5 @@ -255,45 +255,45 @@ openclaw pairing approve discord - - За замовчуванням довготривала пам'ять (MEMORY.md) завантажується лише в сеансах DM. Канали гільдії не завантажують MEMORY.md автоматично. + + За замовчуванням довготривала пам’ять (MEMORY.md) завантажується лише в сеансах особистих повідомлень. Канали гільдії не завантажують MEMORY.md автоматично. - + > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо тобі потрібен довготривалий контекст із MEMORY.md." - - Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони вставляються в кожен сеанс). Зберігайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам'яті. + + Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони інжектуються для кожного сеансу). Зберігайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам’яті. -Тепер створіть кілька каналів на своєму сервері Discord і почніть спілкуватися. Ваш агент бачить назву каналу, і кожен канал отримує власний ізольований сеанс — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що інше, що пасує вашому робочому процесу. +Тепер створіть кілька каналів на своєму сервері Discord і починайте спілкуватися. Ваш агент бачить назву каналу, і кожен канал отримує власний ізольований сеанс — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що пасує вашому робочому процесу. ## Модель runtime -- Gateway володіє з'єднанням Discord. +- Gateway володіє підключенням Discord. - Маршрутизація відповідей детермінована: вхідні відповіді Discord повертаються до Discord. - Метадані гільдії/каналу Discord додаються до підказки моделі як ненадійний - контекст, а не як видимий користувачу префікс відповіді. Якщо модель копіює цю оболонку - назад, OpenClaw вилучає скопійовані метадані з вихідних відповідей і з - майбутнього контексту повторного відтворення. + контекст, а не як видимий користувачу префікс відповіді. Якщо модель копіює цей конверт + назад, OpenClaw видаляє скопійовані метадані з вихідних відповідей і з + майбутнього контексту відтворення. - За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують головний сеанс агента (`agent:main:main`). - Канали гільдії є ізольованими ключами сеансів (`agent::discord:channel:`). -- Групові DM за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). -- Нативні slash-команди виконуються в ізольованих сеансах команд (`agent::discord:slash:`), водночас усе ще передаючи `CommandTargetSessionKey` до маршрутизованого сеансу розмови. -- Текстова доставка оголошень cron/heartbeat до Discord використовує фінальну - видиму асистенту відповідь один раз. Медіа та структуровані payload компонентів залишаються - багатоповідомними, коли агент випускає кілька придатних для доставки payload. +- Групові особисті повідомлення ігноруються за замовчуванням (`channels.discord.dm.groupEnabled=false`). +- Власні slash-команди виконуються в ізольованих командних сеансах (`agent::discord:slash:`), водночас усе ще несучи `CommandTargetSessionKey` до маршрутизованого сеансу розмови. +- Доставка текстових оголошень cron/heartbeat до Discord використовує остаточну + видиму помічнику відповідь один раз. Медіа та структуровані компонентні payloads залишаються + багатоповідомними, коли агент випускає кілька придатних до доставки payloads. -## Канали форумів +## Форумні канали -Канали форумів і медіаканали Discord приймають лише дописи в тредах. OpenClaw підтримує два способи їх створення: +Форумні та медіаканали Discord приймають лише публікації в тредах. OpenClaw підтримує два способи їх створення: -- Надішліть повідомлення до батьківського форуму (`channel:`), щоб автоматично створити тред. Назва треду використовує перший непорожній рядок вашого повідомлення. -- Використайте `openclaw message thread create`, щоб створити тред напряму. Не передавайте `--message-id` для каналів форумів. +- Надішліть повідомлення батьківському форуму (`channel:`), щоб автоматично створити тред. Назвою треду стане перший непорожній рядок вашого повідомлення. +- Використайте `openclaw message thread create`, щоб створити тред напряму. Не передавайте `--message-id` для форумних каналів. Приклад: надіслати до батьківського форуму, щоб створити тред @@ -302,7 +302,7 @@ openclaw message send --channel discord --target channel: \ --message "Topic title\nBody of the post" ``` -Приклад: явно створити тред форуму +Приклад: явно створити форумний тред ```bash openclaw message thread create --channel discord --target channel: \ @@ -313,7 +313,7 @@ openclaw message thread create --channel discord --target channel: \ ## Інтерактивні компоненти -OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодій маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери Discord components v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та дотримуються наявних налаштувань Discord `replyToMode`. Підтримувані блоки: @@ -321,21 +321,21 @@ OpenClaw підтримує контейнери компонентів Discord - Рядки дій дозволяють до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити використовувати кнопки, елементи вибору та форми кілька разів, доки вони не завершать дію. +За замовчуванням components призначені для одноразового використання. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, меню вибору та форм, доки не завершиться строк їх дії. -Щоб обмежити, хто може натиснути кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, користувачі, які не збігаються, отримують ефемерну відмову. +Щоб обмежити, хто може натискати кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Коли це налаштовано, користувачі, які не відповідають умовам, отримують ефемерну відмову. -Slash-команди `/model` і `/models` відкривають інтерактивний вибірник моделі з розкривними списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибірника є ефемерною, і використовувати її може лише користувач, який її викликав. +Slash-команди `/model` і `/models` відкривають інтерактивний вибір моделі з випадаючими списками провайдера, моделі та сумісного runtime, а також кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь вибору ефемерна, і використовувати її може лише користувач, який її викликав. -Файлові вкладення: +Вкладення файлів: -- Блоки `file` мають указувати на посилання вкладення (`attachment://`) +- Блоки `file` мають указувати на посилання на вкладення (`attachment://`) - Надайте вкладення через `media`/`path`/`filePath` (один файл); для кількох файлів використовуйте `media-gallery` -- Використовуйте `filename`, щоб перевизначити назву завантаження, коли вона має збігатися з посиланням вкладення +- Використовуйте `filename`, щоб перевизначити назву завантаження, коли вона має збігатися з посиланням на вкладення Модальні форми: -- Додайте `components.modal` із до 5 полями +- Додайте `components.modal` з до 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` - OpenClaw автоматично додає кнопку запуску @@ -404,12 +404,13 @@ Slash-команди `/model` і `/models` відкривають інтерак - `open` (потребує, щоб `channels.discord.allowFrom` містив `"*"`; застаріле: `channels.discord.dm.allowFrom`) - `disabled` - Якщо політика DM не є відкритою, невідомі користувачі блокуються (або отримують запит на створення пари в режимі `pairing`). + Якщо політика DM не відкрита, невідомі користувачі блокуються (або отримують запит на pairing у режимі `pairing`). - Пріоритетність кількох облікових записів: + Пріоритет для кількох облікових записів: - `channels.discord.accounts.default.allowFrom` застосовується лише до облікового запису `default`. - - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхній власний `allowFrom` не задано. + - Для одного облікового запису `allowFrom` має пріоритет над застарілим `dm.allowFrom`. + - Іменовані облікові записи успадковують `channels.discord.allowFrom`, коли їхні власні `allowFrom` і застарілий `dm.allowFrom` не задані. - Іменовані облікові записи не успадковують `channels.discord.accounts.default.allowFrom`. Формат цілі DM для доставки: @@ -417,7 +418,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - `user:` - згадка `<@id>` - Голі числові ID неоднозначні та відхиляються, якщо не надано явний тип цілі користувача/каналу. + Голі числові ID зазвичай розпізнаються як ID каналів, коли активне значення каналу за замовчуванням, але ID, перелічені в ефективному DM `allowFrom` облікового запису, обробляються як цілі користувацьких DM для сумісності. @@ -428,16 +429,16 @@ Slash-команди `/model` і `/models` відкривають інтерак - `allowlist` - `disabled` - Безпечна базова конфігурація, коли існує `channels.discord`, це `allowlist`. + Безпечний базовий режим, коли існує `channels.discord`, — це `allowlist`. Поведінка `allowlist`: - - гільдія має збігатися з `channels.discord.guilds` (переважно `id`, slug також приймається) - - необов’язкові списки дозволених відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволені, коли вони збігаються з `users` АБО `roles` - - пряме зіставлення імен/тегів вимкнено за замовчуванням; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності + - гільдія має відповідати `channels.discord.guilds` (бажано `id`, slug також приймається) + - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволяються, коли вони відповідають `users` АБО `roles` + - пряме зіставлення імен/тегів вимкнене за замовчуванням; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності - імена/теги підтримуються для `users`, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи з іменами/тегами - - якщо для гільдії налаштовано `channels`, канали поза списком відхиляються - - якщо гільдія не має блока `channels`, усі канали в цій дозволеній гільдії дозволені + - якщо для гільдії налаштовано `channels`, канали, не зазначені в списку, забороняються + - якщо гільдія не має блоку `channels`, дозволяються всі канали в цій гільдії з allowlist Приклад: @@ -463,12 +464,12 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Якщо ви встановите лише `DISCORD_BOT_TOKEN` і не створите блок `channels.discord`, runtime fallback буде `groupPolicy="allowlist"` (із попередженням у журналах), навіть якщо `channels.defaults.groupPolicy` дорівнює `open`. + Якщо ви лише задаєте `DISCORD_BOT_TOKEN` і не створюєте блок `channels.discord`, fallback runtime — `groupPolicy="allowlist"` (з попередженням у логах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. - Повідомлення гільдій за замовчуванням пропускаються через шлюз згадок. + Повідомлення гільдій за замовчуванням пропускаються через перевірку згадок. Виявлення згадок включає: @@ -477,7 +478,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - неявну поведінку відповіді боту в підтримуваних випадках `requireMention` налаштовується для кожної гільдії/каналу (`channels.discord.guilds...`). - `ignoreOtherMentions` за потреби відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). + `ignoreOtherMentions` необов’язково відкидає повідомлення, які згадують іншого користувача/роль, але не бота (крім @everyone/@here). Групові DM: @@ -487,9 +488,9 @@ Slash-команди `/model` і `/models` відкривають інтерак -### Маршрутизація агента на основі ролей +### Маршрутизація агентів на основі ролей -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і оцінюються після прив’язок peer або parent-peer та перед прив’язками лише гільдії. Якщо прив’язка також задає інші поля match (наприклад `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і обчислюються після прив’язок peer або parent-peer та перед прив’язками лише для гільдії. Якщо прив’язка також задає інші поля зіставлення (наприклад `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. ```json5 { @@ -513,13 +514,13 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` -## Нативні команди та авторизація команд +## Нативні команди та автентифікація команд -- `commands.native` за замовчуванням дорівнює `"auto"` і ввімкнено для Discord. -- Перевизначення для каналу: `channels.discord.commands.native`. +- `commands.native` за замовчуванням має значення `"auto"` і ввімкнено для Discord. +- Перевизначення для окремого каналу: `channels.discord.commands.native`. - `commands.native=false` явно очищає раніше зареєстровані нативні команди Discord. -- Авторизація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. -- Команди все ще можуть бути видимі в UI Discord для користувачів, які не авторизовані; виконання все одно застосовує авторизацію OpenClaw і повертає "not authorized". +- Автентифікація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. +- Команди все ще можуть бути видимі в UI Discord для користувачів, які не авторизовані; виконання все одно застосовує автентифікацію OpenClaw і повертає "not authorized". Див. [Slash-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. @@ -527,7 +528,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - `ephemeral: true` -## Подробиці функцій +## Деталі функцій @@ -536,7 +537,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - `[[reply_to_current]]` - `[[reply_to:]]` - Керується `channels.discord.replyToMode`: + Керується через `channels.discord.replyToMode`: - `off` (за замовчуванням) - `first` @@ -544,20 +545,20 @@ Slash-команди `/model` і `/models` відкривають інтерак - `batched` Примітка: `off` вимикає неявне створення ланцюжків відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. - `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord за хід. - `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли - вхідний хід був дебаунс-пакетом із кількох повідомлень. Це корисно, - коли ви хочете нативні відповіді переважно для неоднозначних сплесків чату, а не для кожного + `first` завжди додає неявне посилання на нативну відповідь до першого вихідного повідомлення Discord у межах ходу. + `batched` додає неявне посилання Discord на нативну відповідь лише тоді, коли + вхідний хід був debounced-пакетом із кількох повідомлень. Це корисно, + коли потрібні нативні відповіді переважно для неоднозначних швидких чатів, а не для кожного ходу з одним повідомленням. - ID повідомлень надаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. + ID повідомлень відображаються в контексті/історії, щоб агенти могли націлюватися на конкретні повідомлення. - - OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` відображається на `partial` у Discord; `streamMode` є застарілим псевдонімом і автоматично мігрується. + + OpenClaw може транслювати чернетки відповідей, надсилаючи тимчасове повідомлення й редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` зіставляється з `partial` у Discord; `streamMode` є застарілим псевдонімом і автоматично мігрується. - За замовчуванням залишається `off`, оскільки редагування попереднього перегляду Discord швидко впираються в ліміти частоти, коли кілька ботів або gateways спільно використовують обліковий запис. + За замовчуванням лишається `off`, бо редагування попереднього перегляду Discord швидко впираються в rate limits, коли кілька ботів або Gateway спільно використовують один обліковий запис. ```json5 { @@ -575,11 +576,11 @@ Slash-команди `/model` і `/models` відкривають інтерак ``` - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` видає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). - - Медіа, помилки та фінальні повідомлення з явною відповіддю скасовують очікувані редагування попереднього перегляду. - - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи повторно використовують оновлення інструментів/прогресу повідомлення попереднього перегляду. + - `block` надсилає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені `textChunkLimit`). + - Media, помилка та фінальні відповіді з явним посиланням скасовують очікувані редагування попереднього перегляду. + - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. - Потоковий попередній перегляд підтримує лише текст; медіавідповіді повертаються до звичайної доставки. Коли потокове передавання `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потоковий попередній перегляд підтримує лише текст; відповіді з media повертаються до звичайної доставки. Коли потоковий режим `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної трансляції. @@ -590,7 +591,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - fallback: `messages.groupChat.historyLimit` - `0` вимикає - Елементи керування історією DM: + Керування історією DM: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` @@ -598,24 +599,24 @@ Slash-команди `/model` і `/models` відкривають інтерак Поведінка потоків: - Потоки Discord маршрутизуються як сеанси каналів і успадковують конфігурацію батьківського каналу, якщо її не перевизначено. - - Сеанси потоків успадковують вибір `/model` на рівні сеансу батьківського каналу як fallback лише для моделі; локальні для потоку вибори `/model` все одно мають пріоритет, а історія transcript батьківського каналу не копіюється, якщо не ввімкнено успадкування transcript. - - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових автоматичних потоків початкове заповнення з батьківського transcript. Перевизначення для облікового запису розташовані в `channels.discord.accounts..thread.inheritParent`. - - Реакції інструмента повідомлень можуть розв’язувати DM-цілі `user:`. + - Сеанси потоків успадковують вибір `/model` на рівні сеансу батьківського каналу як fallback лише для моделі; локальні для потоку вибори `/model` усе одно мають пріоритет, а історія transcript батьківського каналу не копіюється, якщо не ввімкнено успадкування transcript. + - `channels.discord.thread.inheritParent` (за замовчуванням `false`) вмикає для нових auto-threads початкове заповнення з батьківського transcript. Перевизначення для окремого облікового запису розташовані в `channels.discord.accounts..thread.inheritParent`. + - Реакції інструмента повідомлень можуть розпізнавати цілі DM `user:`. - `guilds..channels..requireMention: false` зберігається під час fallback активації на етапі відповіді. - Теми каналів вставляються як **ненадійний** контекст. Allowlists обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. + Теми каналів вставляються як **недовірений** контекст. Allowlists обмежують, хто може запускати агента, але не є повною межею редагування додаткового контексту. - - Discord може прив’язати потік до цілі сеансу, щоб наступні повідомлення в цьому потоці продовжували маршрутизуватися до того самого сеансу (включно із сеансами субагентів). + + Discord може прив’язати потік до цілі сеансу, щоб подальші повідомлення в цьому потоці продовжували маршрутизуватися до того самого сеансу (включно із сеансами підагентів). Команди: - - `/focus ` прив’язати поточний/новий потік до цілі субагента/сеансу - - `/unfocus` видалити прив’язку поточного потоку + - `/focus ` прив’язати поточний/новий потік до цілі підагента/сеансу + - `/unfocus` вилучити прив’язку поточного потоку - `/agents` показати активні запуски та стан прив’язки - - `/session idle ` переглянути/оновити автоматичне скасування фокуса через неактивність для сфокусованих прив’язок + - `/session idle ` переглянути/оновити автоматичне зняття фокуса через неактивність для сфокусованих прив’язок - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив’язок Конфігурація: @@ -644,18 +645,18 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - `session.threadBindings.*` задає глобальні значення за замовчуванням. + - `session.threadBindings.*` задає глобальні типові значення. - `channels.discord.threadBindings.*` перевизначає поведінку Discord. - - `spawnSubagentSessions` має бути true, щоб автоматично створювати/прив’язувати потоки для `sessions_spawn({ thread: true })`. - - `spawnAcpSessions` має бути true, щоб автоматично створювати/прив’язувати потоки для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). - - Якщо прив’язки потоків вимкнено для облікового запису, `/focus` і пов’язані операції прив’язки потоків недоступні. + - `spawnSubagentSessions` має бути true, щоб автоматично створювати/прив'язувати гілки для `sessions_spawn({ thread: true })`. + - `spawnAcpSessions` має бути true, щоб автоматично створювати/прив'язувати гілки для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). + - Якщо прив'язки гілок вимкнено для облікового запису, `/focus` і пов'язані операції прив'язки гілок недоступні. Див. [Субагенти](/uk/tools/subagents), [Агенти ACP](/uk/tools/acp-agents) і [Довідник конфігурації](/uk/gateway/configuration-reference). - - Для стабільних робочих просторів ACP, які завжди ввімкнені, налаштуйте типізовані прив’язки ACP верхнього рівня, що спрямовані на розмови Discord. + + Для стабільних "always-on" робочих просторів ACP налаштуйте типізовані прив'язки ACP верхнього рівня, націлені на розмови Discord. Шлях конфігурації: @@ -711,11 +712,11 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - `/acp spawn codex --bind here` прив’язує поточний канал або потік на місці й зберігає майбутні повідомлення в тій самій сесії ACP. Повідомлення потоку успадковують прив’язку батьківського каналу. - - У прив’язаному каналі або потоці `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив’язки потоків можуть перевизначати визначення цілі, доки активні. - - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив’язати дочірній потік через `--thread auto|here`. + - `/acp spawn codex --bind here` прив'язує поточний канал або гілку на місці та зберігає майбутні повідомлення в тій самій сесії ACP. Повідомлення гілки успадковують прив'язку батьківського каналу. + - У прив'язаному каналі або гілці `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив'язки гілок можуть перевизначати розв'язання цілі, доки активні. + - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив'язати дочірню гілку через `--thread auto|here`. - Див. [Агенти ACP](/uk/tools/acp-agents), щоб дізнатися більше про поведінку прив’язок. + Див. [Агенти ACP](/uk/tools/acp-agents), щоб дізнатися подробиці поведінки прив'язок. @@ -723,18 +724,18 @@ Slash-команди `/model` і `/models` відкривають інтерак Режим сповіщень про реакції для кожної гільдії: - `off` - - `own` (за замовчуванням) + - `own` (типово) - `all` - `allowlist` (використовує `guilds..users`) - Події реакцій перетворюються на системні події та прикріплюються до маршрутизованої сесії Discord. + Події реакцій перетворюються на системні події та приєднуються до маршрутизованої сесії Discord. `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. - Порядок визначення: + Порядок розв'язання: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` @@ -749,9 +750,9 @@ Slash-команди `/model` і `/models` відкривають інтерак - Записи конфігурації, ініційовані каналом, увімкнено за замовчуванням. + Записи конфігурації, ініційовані каналом, увімкнені типово. - Це впливає на потоки `/config set|unset` (коли функції команд увімкнено). + Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). Вимкнення: @@ -768,7 +769,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - Маршрутизуйте WebSocket-трафік Discord gateway і стартові REST-запити (ID застосунку + визначення списку дозволених) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. + Маршрутизуйте WebSocket-трафік Discord gateway і стартові REST-запити (ID застосунку + розв'язання списку дозволів) через HTTP(S)-проксі з `channels.discord.proxy`. ```json5 { @@ -799,7 +800,7 @@ Slash-команди `/model` і `/models` відкривають інтерак - Увімкніть визначення PluralKit, щоб зіставляти проксійовані повідомлення з ідентичністю учасника системи: + Увімкніть розв'язання PluralKit, щоб зіставляти проксійовані повідомлення з ідентичністю учасника системи: ```json5 { @@ -816,9 +817,9 @@ Slash-команди `/model` і `/models` відкривають інтерак Примітки: - - списки дозволених можуть використовувати `pk:` - - відображувані імена учасників зіставляються за name/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` - - пошуки використовують ID оригінального повідомлення й обмежені часовим вікном + - списки дозволів можуть використовувати `pk:` + - показувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` + - пошуки використовують ID оригінального повідомлення та обмежені часовим вікном - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо `allowBots=true` не встановлено @@ -826,7 +827,7 @@ Slash-команди `/model` і `/models` відкривають інтерак Оновлення присутності застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте автоматичну присутність. - Приклад лише зі статусом: + Приклад лише статусу: ```json5 { @@ -838,7 +839,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Приклад активності (користувацький статус є типом активності за замовчуванням): + Приклад активності (користувацький статус є типовим типом активності): ```json5 { @@ -851,7 +852,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Приклад трансляції: + Приклад Streaming: ```json5 { @@ -868,13 +869,13 @@ Slash-команди `/model` і `/models` відкривають інтерак Мапа типів активності: - 0: Грає - - 1: Транслює (потребує `activityUrl`) + - 1: Streaming (потребує `activityUrl`) - 2: Слухає - 3: Дивиться - - 4: Користувацька (використовує текст активності як стан статусу; емодзі необов’язковий) + - 4: Користувацький (використовує текст активності як стан статусу; емодзі необов'язковий) - 5: Змагається - Приклад автоматичної присутності (сигнал справності середовища виконання): + Приклад автоматичної присутності (сигнал працездатності середовища виконання): ```json5 { @@ -891,7 +892,7 @@ Slash-команди `/model` і `/models` відкривають інтерак } ``` - Автоматична присутність зіставляє доступність середовища виконання зі статусом Discord: справний => online, погіршений або невідомий => idle, вичерпаний або недоступний => dnd. Необов’язкові перевизначення тексту: + Автоматична присутність зіставляє доступність середовища виконання зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов'язкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -899,42 +900,42 @@ Slash-команди `/model` і `/models` відкривають інтерак - - Discord підтримує обробку підтверджень кнопками в DM і може додатково публікувати запити підтвердження в початковому каналі. + + Discord підтримує обробку схвалень на основі кнопок у приватних повідомленнях і може необов'язково публікувати запити на схвалення у вихідному каналі. Шлях конфігурації: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов’язково; за можливості використовує резервно `commands.ownerAllowFrom`) - - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) + - `channels.discord.execApprovals.approvers` (необов'язково; за можливості використовує резервний `commands.ownerAllowFrom`) + - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord автоматично вмикає нативні підтвердження виконання, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного затверджувача: або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не виводить затверджувачів виконання з `allowFrom` каналу, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт підтверджень. + Discord автоматично вмикає нативні схвалення exec, коли `enabled` не задано або має значення `"auto"` і можна розв'язати принаймні одного схвалювача, або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не виводить схвалювачів exec з канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для приватних повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт схвалень. - Для чутливих групових команд лише для власника, таких як `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити підтвердження та фінальні результати приватно. Спершу він пробує Discord DM, коли власник, що викликає команду, має маршрут власника Discord; якщо він недоступний, OpenClaw використовує резервно перший доступний маршрут власника з `commands.ownerAllowFrom`, наприклад Telegram. + Для чутливих групових команд лише для власника, як-от `/diagnostics` і `/export-trajectory`, OpenClaw надсилає запити на схвалення та кінцеві результати приватно. Спершу він пробує приватне повідомлення Discord, коли власник, що викликав команду, має маршрут власника Discord; якщо це недоступно, він використовує резервний перший доступний маршрут власника з `commands.ownerAllowFrom`, наприклад Telegram. - Коли `target` має значення `channel` або `both`, запит підтвердження видно в каналі. Кнопками можуть користуватися лише визначені затверджувачі; інші користувачі отримують ефемерну відмову. Запити підтвердження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw використовує резервну доставку в DM. + Коли `target` має значення `channel` або `both`, запит на схвалення видимий у каналі. Лише розв'язані схвалювачі можуть користуватися кнопками; інші користувачі отримують ефемерну відмову. Запити на схвалення містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw використовує резервну доставку через приватне повідомлення. - Discord також відтворює спільні кнопки підтвердження, які використовують інші чат-канали. Нативний адаптер Discord переважно додає маршрутизацію DM для затверджувачів і розсилання в канали. - Коли ці кнопки наявні, вони є основним UX підтвердження; OpenClaw - має додавати ручну команду `/approve` лише тоді, коли результат інструмента каже, - що підтвердження в чаті недоступні або ручне підтвердження є єдиним шляхом. - Якщо нативне середовище виконання підтверджень Discord не активне, OpenClaw зберігає - видимим локальний детермінований запит `/approve `. Якщо + Discord також відображає спільні кнопки схвалення, які використовують інші чат-канали. Нативний адаптер Discord здебільшого додає маршрутизацію приватних повідомлень схвалювачам і розсилання в канали. + Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw + має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, + що чат-схвалення недоступні або ручне схвалення є єдиним шляхом. + Якщо нативне середовище виконання схвалень Discord не активне, OpenClaw зберігає + локальний детермінований запит `/approve ` видимим. Якщо середовище виконання активне, але нативну картку неможливо доставити до жодної цілі, - OpenClaw надсилає резервне сповіщення в той самий чат із точною командою `/approve` - з очікуваного підтвердження. + OpenClaw надсилає резервне сповіщення в той самий чат з точною командою `/approve` + з очікуваного схвалення. - Автентифікація Gateway і визначення підтверджень дотримуються спільного контракту клієнта Gateway (`plugin:` IDs визначаються через `plugin.approval.resolve`; інші IDs — через `exec.approval.resolve`). Термін дії підтверджень за замовчуванням спливає через 30 хвилин. + Автентифікація Gateway і розв'язання схвалень дотримуються спільного контракту клієнта Gateway (`plugin:` ID розв'язуються через `plugin.approval.resolve`; інші ID через `exec.approval.resolve`). Типово схвалення спливають через 30 хвилин. - Див. [Підтвердження виконання](/uk/tools/exec-approvals). + Див. [Схвалення exec](/uk/tools/exec-approvals). -## Інструменти та правила доступу до дій +## Інструменти та шлюзи дій -Дії повідомлень Discord охоплюють обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. +Дії з повідомленнями Discord включають обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. Основні приклади: @@ -943,26 +944,26 @@ Slash-команди `/model` і `/models` відкривають інтерак - модерація: `timeout`, `kick`, `ban` - присутність: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файла), щоб задати зображення обкладинки запланованої події. +Дія `event-create` приймає необов'язковий параметр `image` (URL або шлях до локального файлу), щоб установити зображення обкладинки запланованої події. -Правила доступу до дій розміщені в `channels.discord.actions.*`. +Шлюзи дій розташовані в `channels.discord.actions.*`. -Поведінка правил доступу за замовчуванням: +Типова поведінка шлюзів: -| Група дій | За замовчуванням | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | -| roles | вимкнено | -| moderation | вимкнено | -| presence | вимкнено | +| Група дій | Типово | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | +| roles | вимкнено | +| moderation | вимкнено | +| presence | вимкнено | ## UI Components v2 -OpenClaw використовує Discord components v2 для підтверджень виконання та маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для користувацького UI (розширено; потребує створення payload компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. +OpenClaw використовує Discord components v2 для схвалень exec і маркерів між контекстами. Дії з повідомленнями Discord також можуть приймати `components` для користувацького UI (розширене використання; потребує створення payload компонента через інструмент discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендовані. - `channels.discord.ui.components.accentColor` задає акцентний колір, який використовують контейнери компонентів Discord (hex). -- Для окремого облікового запису задайте через `channels.discord.accounts..ui.components.accentColor`. -- `embeds` ігноруються, коли наявні components v2. +- Задайте для окремого облікового запису через `channels.discord.accounts..ui.components.accentColor`. +- `embeds` ігноруються, коли присутні components v2. Приклад: @@ -982,20 +983,20 @@ OpenClaw використовує Discord components v2 для підтверд ## Голос -Discord має дві окремі голосові поверхні: голосові канали реального часу (безперервні розмови) і вкладення голосових повідомлень (формат попереднього перегляду хвилі). Gateway підтримує обидві. +Discord має дві окремі голосові поверхні: realtime **голосові канали** (безперервні розмови) і **вкладення голосових повідомлень** (формат попереднього перегляду хвилі). Gateway підтримує обидві. ### Голосові канали Контрольний список налаштування: 1. Увімкніть Message Content Intent у Discord Developer Portal. -2. Увімкніть Server Members Intent, коли використовуються списки дозволених для ролей/користувачів. +2. Увімкніть Server Members Intent, коли використовуються списки дозволів ролей/користувачів. 3. Запросіть бота з областями `bot` і `applications.commands`. 4. Надайте Connect, Speak, Send Messages і Read Message History у цільовому голосовому каналі. 5. Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). 6. Налаштуйте `channels.discord.voice`. -Використовуйте `/vc join|leave|status`, щоб керувати сесіями. Команда використовує агента облікового запису за замовчуванням і дотримується тих самих правил списку дозволених і групової політики, що й інші команди Discord. +Використовуйте `/vc join|leave|status`, щоб керувати сесіями. Команда використовує типового агента облікового запису та дотримується тих самих правил списків дозволів і групової політики, що й інші команди Discord. ```bash /vc join channel: @@ -1033,33 +1034,33 @@ Discord має дві окремі голосові поверхні: голос Примітки: - `voice.tts` перевизначає `messages.tts` лише для голосового відтворення. -- `voice.model` перевизначає LLM, що використовується лише для відповідей у голосовому каналі Discord. Залиште його незаданим, щоб успадкувати модель маршрутизованого агента. +- `voice.model` перевизначає LLM, що використовується лише для відповідей у голосовому каналі Discord. Не задавайте його, щоб успадкувати маршрутизовану модель агента. - STT використовує `tools.media.audio`; `voice.model` не впливає на транскрибування. -- Ходи голосового транскрипта визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). -- Голос увімкнено за замовчуванням; установіть `channels.discord.voice.enabled=false`, щоб вимкнути голосове середовище виконання та Gateway intent `GuildVoiceStates`. -- `channels.discord.intents.voiceStates` може явно перевизначити підписку на intent голосового стану. Залиште його незаданим, щоб intent слідував за `voice.enabled`. -- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються до параметрів підключення `@discordjs/voice`. -- Значення за замовчуванням `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. -- OpenClaw також відстежує помилки розшифрування приймання та автоматично відновлюється, виходячи з голосового каналу й повторно приєднуючись до нього після повторюваних помилок у короткому вікні. -- Якщо після оновлення журнали приймання неодноразово показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована гілка `@discordjs/voice` містить upstream-виправлення padding з PR discord.js #11449, який закрив issue discord.js #11419. +- Ходи голосової стенограми визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). +- Голос увімкнено за замовчуванням; установіть `channels.discord.voice.enabled=false`, щоб вимкнути голосове середовище виконання та намір Gateway `GuildVoiceStates`. +- `channels.discord.intents.voiceStates` може явно перевизначити підписку на намір стану голосу. Не задавайте його, щоб намір відповідав `voice.enabled`. +- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються напряму до параметрів приєднання `@discordjs/voice`. +- Значення за замовчуванням `@discordjs/voice`: `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. +- OpenClaw також відстежує збої розшифрування під час отримання та автоматично відновлюється, залишаючи голосовий канал і повторно приєднуючись до нього після повторних збоїв у короткому проміжку часу. +- Якщо після оновлення журнали отримання неодноразово показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, зберіть звіт про залежності та журнали. Вбудована лінія `@discordjs/voice` містить виправлення доповнення з upstream із PR discord.js #11449, який закрив issue discord.js #11419. Конвеєр голосового каналу: -- Захоплення PCM з Discord перетворюється на тимчасовий WAV-файл. +- Захоплення PCM із Discord перетворюється на тимчасовий файл WAV. - `tools.media.audio` обробляє STT, наприклад `openai/gpt-4o-mini-transcribe`. -- Транскрипт надсилається через звичайний вхідний потік і маршрутизацію Discord. +- Стенограма надсилається через звичайний вхідний потік Discord і маршрутизацію. - `voice.model`, якщо задано, перевизначає лише LLM відповіді для цього ходу голосового каналу. -- `voice.tts` об’єднується поверх `messages.tts`; отримане аудіо відтворюється у приєднаному каналі. +- `voice.tts` об’єднується поверх `messages.tts`; отримане аудіо відтворюється в каналі, до якого виконано приєднання. -Облікові дані визначаються окремо для кожного компонента: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. +Облікові дані визначаються для кожного компонента окремо: автентифікація маршруту LLM для `voice.model`, автентифікація STT для `tools.media.audio` і автентифікація TTS для `messages.tts`/`voice.tts`. ### Голосові повідомлення Голосові повідомлення Discord показують попередній перегляд хвильової форми та потребують аудіо OGG/Opus. OpenClaw генерує хвильову форму автоматично, але потребує `ffmpeg` і `ffprobe` на хості Gateway для перевірки та перетворення. -- Надайте **локальний шлях до файлу** (URL відхиляються). +- Надайте **шлях до локального файлу** (URL-адреси відхиляються). - Не додавайте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). -- Приймається будь-який формат аудіо; OpenClaw перетворює його на OGG/Opus за потреби. +- Приймається будь-який аудіоформат; OpenClaw за потреби перетворює його на OGG/Opus. ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1071,16 +1072,16 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a - увімкніть Message Content Intent - - увімкніть Server Members Intent, коли ви залежите від визначення користувача/учасника - - перезапустіть Gateway після зміни intents + - увімкніть Server Members Intent, коли ви залежите від розпізнавання користувача/учасника + - перезапустіть gateway після зміни намірів - перевірте `groupPolicy` - - перевірте allowlist гільдії в `channels.discord.guilds` - - якщо існує мапа `channels` гільдії, дозволені лише перелічені канали + - перевірте список дозволених guild у `channels.discord.guilds` + - якщо існує мапа `channels` для guild, дозволені лише перелічені канали - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1096,9 +1097,9 @@ openclaw logs --follow Поширені причини: - - `groupPolicy="allowlist"` без відповідного allowlist гільдії/каналу - - `requireMention` налаштовано не в тому місці (має бути в `channels.discord.guilds` або записі каналу) - - відправника заблоковано allowlist `users` гільдії/каналу + - `groupPolicy="allowlist"` без відповідного списку дозволених guild/каналів + - `requireMention` налаштовано в неправильному місці (має бути в `channels.discord.guilds` або записі каналу) + - відправника заблоковано списком дозволених `users` guild/каналу @@ -1109,13 +1110,13 @@ openclaw logs --follow - `Slow listener detected ...` - `stuck session: sessionKey=agent:...:discord:... state=processing ...` - Регулятори черги Carbon gateway: + Параметри черги Carbon gateway: - один обліковий запис: `channels.discord.eventQueue.listenerTimeout` - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` - це керує лише роботою слухача Carbon gateway, а не тривалістю ходу агента - Discord не застосовує власний тайм-аут каналу до поставлених у чергу ходів агента. Слухачі повідомлень негайно передають керування далі, а поставлені в чергу запуски Discord зберігають порядок у межах сесії, доки життєвий цикл сесії/інструмента/середовища виконання не завершиться або не перерве роботу. + Discord не застосовує тайм-аут, що належить каналу, до поставлених у чергу ходів агента. Слухачі повідомлень передають їх негайно, а поставлені в чергу запуски Discord зберігають порядок у межах сеансу, доки життєвий цикл сеансу/інструмента/середовища виконання не завершить або не перерве роботу. ```json5 { @@ -1135,59 +1136,59 @@ openclaw logs --follow - - OpenClaw отримує метадані Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартного URL Gateway Discord і обмежуються за частотою в журналах. + + OpenClaw отримує метадані Discord `/gateway/bot` перед підключенням. Тимчасові збої повертаються до стандартної URL-адреси gateway Discord і обмежуються за частотою в журналах. - Регулятори тайм-ауту метаданих: + Параметри тайм-ауту метаданих: - один обліковий запис: `channels.discord.gatewayInfoTimeoutMs` - кілька облікових записів: `channels.discord.accounts..gatewayInfoTimeoutMs` - - резервне env-значення, коли config не задано: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` - - за замовчуванням: `30000` (30 секунд), максимум: `120000` + - запасний варіант env, коли конфігурацію не задано: `OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS` + - стандартне значення: `30000` (30 секунд), максимум: `120000` - - Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. + + Перевірки дозволів `channels status --probe` працюють лише для числових ідентифікаторів каналів. - Якщо ви використовуєте slug-ключі, зіставлення під час виконання все ще може працювати, але probe не може повністю перевірити дозволи. + Якщо ви використовуєте ключі-slug, зіставлення під час виконання все одно може працювати, але probe не може повністю перевірити дозволи. - + - DM вимкнено: `channels.discord.dm.enabled=false` - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) - - очікується схвалення сполучення в режимі `pairing` + - очікування схвалення сполучення в режимі `pairing` - + За замовчуванням повідомлення, створені ботами, ігноруються. - Якщо ви встановлюєте `channels.discord.allowBots=true`, використовуйте строгі правила згадок і allowlist, щоб уникнути зациклення. + Якщо ви задаєте `channels.discord.allowBots=true`, використовуйте строгі правила згадок і allowlist, щоб уникнути циклічної поведінки. Надавайте перевагу `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. - + - - підтримуйте OpenClaw в актуальному стані (`openclaw update`), щоб була присутня логіка відновлення приймання голосу Discord - - підтвердьте `channels.discord.voice.daveEncryption=true` (за замовчуванням) - - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (upstream-значення за замовчуванням) і налаштовуйте лише за потреби - - стежте за журналами на наявність: + - підтримуйте OpenClaw актуальним (`openclaw update`), щоб була наявна логіка відновлення прийому голосу Discord + - підтвердьте `channels.discord.voice.daveEncryption=true` (стандартно) + - почніть із `channels.discord.voice.decryptionFailureTolerance=24` (стандартне значення upstream) і налаштовуйте лише за потреби + - стежте в журналах за: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - якщо помилки продовжуються після автоматичного повторного приєднання, зберіть журнали та порівняйте з upstream-історією приймання DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) + - якщо збої тривають після автоматичного повторного приєднання, зберіть журнали та порівняйте їх з upstream-історією прийому DAVE у [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) і [discord.js #11449](https://github.com/discordjs/discord.js/pull/11449) -## Довідник конфігурації +## Довідник із конфігурації -Основний довідник: [Довідник конфігурації - Discord](/uk/gateway/config-channels#discord). +Основний довідник: [Довідник із конфігурації - Discord](/uk/gateway/config-channels#discord). - + - запуск/автентифікація: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` @@ -1196,8 +1197,8 @@ openclaw logs --follow - метадані Gateway: `gatewayInfoTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- потокове передавання: `streaming` (застарілий alias: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- медіа/повтор: `mediaMaxMb` (обмежує вихідні завантаження Discord, за замовчуванням `100MB`), `retry` +- потокове передавання: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- медіа/повтор: `mediaMaxMb` (обмежує вихідні завантаження Discord, стандартно `100MB`), `retry` - дії: `actions.*` - присутність: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` @@ -1205,31 +1206,31 @@ openclaw logs --follow -## Безпека та експлуатація +## Безпека й експлуатація -- Розглядайте токени ботів як секрети (`DISCORD_BOT_TOKEN` бажано в керованих середовищах). -- Надавайте Discord дозволи за принципом найменших привілеїв. -- Якщо deploy/state команд застарілий, перезапустіть Gateway і повторно перевірте за допомогою `openclaw channels status --probe`. +- Вважайте токени ботів секретами (у контрольованих середовищах бажано `DISCORD_BOT_TOKEN`). +- Надавайте мінімально необхідні дозволи Discord. +- Якщо розгортання/стан команд застаріли, перезапустіть gateway і повторно перевірте за допомогою `openclaw channels status --probe`. ## Пов’язане - - Сполучіть користувача Discord із Gateway. + + Зіставте користувача Discord із gateway. - + Груповий чат і поведінка allowlist. - + Маршрутизуйте вхідні повідомлення до агентів. - + Модель загроз і посилення захисту. - - Зіставляйте гільдії та канали з агентами. + + Зіставляйте guilds і канали з агентами. - - Поведінка нативних команд. + + Нативна поведінка команд. diff --git a/docs/uk/channels/telegram.md b/docs/uk/channels/telegram.md index 03cd04fa4..766f6c13d 100644 --- a/docs/uk/channels/telegram.md +++ b/docs/uk/channels/telegram.md @@ -1,27 +1,27 @@ --- read_when: - Робота над функціями Telegram або Webhook -summary: Стан підтримки бота Telegram, можливості та конфігурація +summary: Стан підтримки Telegram-бота, можливості та конфігурація title: Telegram x-i18n: - generated_at: "2026-04-29T11:47:40Z" + generated_at: "2026-04-29T12:06:06Z" model: gpt-5.5 provider: openai - source_hash: 8bae9845e95669fe21d75694d81172bfb4fc6329b67ef232e7fe4cbf67b87958 + source_hash: 8db902132bd9b93deda2f951353dadc6ea2d4d76a59919cf1fb90f7e75615556 source_path: channels/telegram.md workflow: 16 --- -Готово до production-використання для ботів у DM і групах через grammY. Режим довгого опитування є стандартним; режим Webhook є необов'язковим. +Готове до продакшну для особистих повідомлень бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий. - - Стандартна політика DM для Telegram — сполучення. + + Політика особистих повідомлень за замовчуванням для Telegram — створення пари. - - Міжканальна діагностика та сценарії відновлення. + + Міжканальна діагностика та інструкції з відновлення. - + Повні шаблони й приклади конфігурації каналів. @@ -29,14 +29,14 @@ x-i18n: ## Швидке налаштування - - Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`). + + Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я точно `@BotFather`). - Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен. + Запустіть `/newbot`, дотримуйтесь підказок і збережіть токен. - + ```json5 { @@ -51,12 +51,12 @@ x-i18n: } ``` - Резервне значення з env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис). - Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть Gateway. + Резервний варіант через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням). + Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації/змінних середовища, а потім запустіть gateway. - + ```bash openclaw gateway @@ -64,82 +64,82 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Коди сполучення спливають через 1 годину. + Коди створення пари спливають через 1 годину. - - Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу. + + Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до своєї моделі доступу. -Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису. +Порядок визначення токена враховує обліковий запис. На практиці значення з конфігурації мають пріоритет над резервною змінною середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням. ## Налаштування на боці Telegram - - Боти Telegram стандартно використовують **Privacy Mode**, який обмежує, які повідомлення груп вони отримують. + + Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують. - Якщо бот має бачити всі повідомлення групи, зробіть одне з такого: + Якщо бот має бачити всі групові повідомлення, або: - вимкніть режим приватності через `/setprivacy`, або - зробіть бота адміністратором групи. - Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну. + Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну. - - Статус адміністратора контролюється в налаштуваннях групи Telegram. + + Статус адміністратора керується в налаштуваннях групи Telegram. - Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі. + Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі. - + - - `/setjoingroups`, щоб дозволити/заборонити додавання до груп + - `/setjoingroups` для дозволу/заборони додавання до груп - `/setprivacy` для поведінки видимості в групах -## Контроль доступу й активація +## Контроль доступу та активація - + `channels.telegram.dmPolicy` керує доступом до особистих повідомлень: - - `pairing` (стандартно) + - `pairing` (за замовчуванням) - `allowlist` (потрібен принаймні один ID відправника в `allowFrom`) - `open` (потрібно, щоб `allowFrom` містив `"*"`) - `disabled` - `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім'я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. + `dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів. - `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються. - У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` трактується як межа безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після об'єднання все ще не містить явний wildcard. - `dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації. - Налаштування запитує лише числові ID користувачів. - Якщо ви оновилися і ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв'язати (best-effort; потребує токена бота Telegram). - Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). + `channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються. + У конфігураціях із кількома обліковими записами обмежувальний `channels.telegram.allowFrom` верхнього рівня розглядається як межа безпеки: записи `allowFrom: ["*"]` на рівні облікового запису не роблять цей обліковий запис публічним, якщо ефективний список дозволів облікового запису після об’єднання все ще не містить явного шаблону `*`. + `dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі особисті повідомлення та відхиляється перевіркою конфігурації. + Під час налаштування запитуються лише числові ID користувачів. + Якщо ви оновилися і ваша конфігурація містить записи списку дозволів `@username`, запустіть `openclaw doctor --fix`, щоб розв’язати їх (найкраща спроба; потрібен токен бота Telegram). + Якщо раніше ви покладалися на файли списку дозволів зі сховища створення пари, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у сценаріях зі списком дозволів (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID). - Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення). + Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх підтверджень створення пари). - Типова плутанина: схвалення сполучення DM не означає "цей відправник авторизований усюди". - Сполучення надає доступ до DM. Якщо власник команд ще не існує, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора. - Авторизація відправника в групі все ще походить із явних allowlist у конфігурації. - Якщо ви хочете "я авторизований один раз, і працюють і DM, і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. + Типова плутанина: схвалення створення пари для особистих повідомлень не означає «цей відправник авторизований всюди». + Створення пари надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене створення пари також задає `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення виконання мали явний обліковий запис оператора. + Авторизація відправника в групі все ще походить із явних списків дозволів у конфігурації. + Якщо вам потрібно «я авторизований один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:`. ### Як знайти свій ID користувача Telegram Безпечніше (без стороннього бота): - 1. Напишіть своєму боту в DM. - 2. Виконайте `openclaw logs --follow`. + 1. Напишіть своєму боту в особисті повідомлення. + 2. Запустіть `openclaw logs --follow`. 3. Прочитайте `from.id`. Офіційний метод Bot API: @@ -152,31 +152,31 @@ curl "https://api.telegram.org/bot/getUpdates" - + Два елементи керування застосовуються разом: 1. **Які групи дозволені** (`channels.telegram.groups`) - немає конфігурації `groups`: - з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи - з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`) - - `groups` налаштовано: працює як allowlist (явні ID або `"*"`) + - `groups` налаштовано: діє як список дозволів (явні ID або `"*"`) - 2. **Яким відправникам дозволено писати в групах** (`channels.telegram.groupPolicy`) + 2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (за замовчуванням) - `disabled` `groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`. Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються). - Не додавайте ID чатів груп Telegram або супергруп у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`. + Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`. Нечислові записи ігноруються для авторизації відправника. - Межа безпеки (`2026.2.25+`): автентифікація відправника в групі **не** успадковує схвалення зі сховища спарювання DM. - Спарювання лишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. - Якщо `groupAllowFrom` не задано, Telegram повертається до конфігурації `allowFrom`, а не до сховища спарювання. + Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища створення пари для особистих повідомлень. + Створення пари залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи/теми. + Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища створення пари. Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`. - Примітка щодо середовища виконання: якщо `channels.telegram` повністю відсутній, середовище виконання за замовчуванням відмовляє безпечно з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. + Примітка щодо виконання: якщо `channels.telegram` повністю відсутній, середовище виконання за замовчуванням закриває доступ через `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно. - Приклад: дозволити будь-якому учаснику в одній конкретній групі: + Приклад: дозволити будь-якого учасника в одній конкретній групі: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Приклад: дозволити лише конкретним користувачам в одній конкретній групі: + Приклад: дозволити лише конкретних користувачів в одній конкретній групі: ```json5 { @@ -211,17 +211,17 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram. + Типова помилка: `groupAllowFrom` не є списком дозволених груп Telegram. - - Додавайте від’ємні ID чатів груп Telegram або супергруп, як-от `-1001234567890`, у `channels.telegram.groups`. - - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди в дозволеній групі можуть запускати бота. - - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом. + - Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`. + - Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота. + - Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг розмовляти з ботом. - + Відповіді в групах за замовчуванням потребують згадки. Згадка може надходити з: @@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Перемикачі команд на рівні сеансу: + Перемикачі команд на рівні сесії: - `/activation always` - `/activation mention` - Вони оновлюють лише стан сеансу. Для збереження використовуйте конфігурацію. + Вони оновлюють лише стан сесії. Для збереження використовуйте конфігурацію. Приклад сталої конфігурації: @@ -252,31 +252,31 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Отримання ID групового чату: + Як отримати ID групового чату: - - перешліть повідомлення з групи до `@userinfobot` / `@getidsbot` - - або прочитайте `chat.id` з `openclaw logs --follow` - - або перевірте `getUpdates` Bot API + - переслати групове повідомлення до `@userinfobot` / `@getidsbot` + - або прочитати `chat.id` з `openclaw logs --follow` + - або переглянути `getUpdates` Bot API -## Поведінка середовища виконання +## Поведінка під час виконання -- Telegram належить процесу Gateway. -- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали). +- Telegram належить процесу gateway. +- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповіді назад у Telegram (модель не вибирає канали). - Вхідні повідомлення нормалізуються в спільну оболонку каналу з метаданими відповіді та заповнювачами медіа. -- Групові сеанси ізольовані за ID групи. Теми форуму додають `:topic:`, щоб ізолювати теми. -- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сеансів, що враховують тред, і зберігає ID треду для відповідей. -- Long polling використовує grammY runner із послідовністю для кожного чату/треду. Загальна конкурентність приймача runner використовує `agents.defaults.maxConcurrent`. -- Long polling захищено всередині кожного процесу Gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший Gateway OpenClaw, скрипт або зовнішній poller, імовірно, використовує той самий токен. -- Перезапуски watchdog для long-polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку polling під час тривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. -- Telegram Bot API не підтримує read-receipt (`sendReadReceipts` не застосовується). +- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:`, щоб теми були ізольовані. +- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують потік, і зберігає ID потоку для відповідей. +- Довге опитування використовує grammY runner із послідовністю за чатом/потоком. Загальна паралельність приймача runner використовує `agents.defaults.maxConcurrent`. +- Довге опитування захищене всередині кожного процесу gateway, щоб лише один активний опитувач міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній опитувач використовує той самий токен. +- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеного сигналу активності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів. +- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується). ## Довідник функцій - + OpenClaw може транслювати часткові відповіді в реальному часі: - прямі чати: повідомлення попереднього перегляду + `editMessageText` @@ -284,12 +284,12 @@ curl "https://api.telegram.org/bot/getUpdates" Вимога: - - `channels.telegram.streaming` є `off | partial | block | progress` (за замовчуванням: `partial`) - - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням) - - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активна трансляція попереднього перегляду) - - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб перенести їх до `channels.telegram.streaming.mode` + - `channels.telegram.streaming` — `off | partial | block | progress` (за замовчуванням: `partial`) + - `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним найменуванням) + - `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли потоковий попередній перегляд активний) + - застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; запустіть `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode` - Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Працюємо...", що показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлень планування або зведень патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і новіше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: + Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюю...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніше. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте: ```json { @@ -306,16 +306,16 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення "Працюємо...". Запити на схвалення, медіа-вміст і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки стану прогресу інструментів. + Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення «Працюю...». Запити на схвалення, медіанавантаження та помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише залишити редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів. - Для відповідей лише з текстом: + Для відповідей лише текстом: - - короткі попередні перегляди DM/групи/теми: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці - - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу в Telegram відображала час завершення, а не час створення попереднього перегляду + - короткі попередні перегляди DM/групи/теми: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці + - попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тому видима позначка часу Telegram відображає час завершення, а не час створення попереднього перегляду - Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. + Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду. - Стримінг попереднього перегляду відокремлений від стримінгу блоків. Коли стримінг блоків явно ввімкнено для Telegram, OpenClaw пропускає стрим попереднього перегляду, щоб уникнути подвійного стримінгу. + Потокове передавання попереднього перегляду відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`. @@ -326,21 +326,21 @@ curl "https://api.telegram.org/bot/getUpdates" - + Вихідний текст використовує Telegram `parse_mode: "HTML"`. - - Текст у стилі Markdown рендериться в безпечний для Telegram HTML. - - Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram. - - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст. + - Текст у стилі Markdown відтворюється як безпечний для Telegram HTML. + - Сирий HTML моделі екранується, щоб зменшити збої розбору Telegram. + - Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст. - Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`. + Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені за допомогою `channels.telegram.linkPreview: false`. Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`. - Нативні значення команд за замовчуванням: + Типові значення нативних команд: - `commands.native: "auto"` вмикає нативні команди для Telegram @@ -361,47 +361,47 @@ curl "https://api.telegram.org/bot/getUpdates" Правила: - - назви нормалізуються (видаляється початковий `/`, переводяться в нижній регістр) - - чинний шаблон: `a-z`, `0-9`, `_`, довжина `1..32` + - назви нормалізуються (прибирається початковий `/`, нижній регістр) + - допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32` - користувацькі команди не можуть перевизначати нативні команди - - конфлікти/дублікати пропускаються й записуються в журнал + - конфлікти/дублікати пропускаються та записуються в журнал Примітки: - користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично - - команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram + - команди Plugin/skill можуть усе ще працювати під час введення, навіть якщо їх не показано в меню Telegram - Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо це налаштовано. + Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди або команди Plugin можуть усе ще реєструватися, якщо це налаштовано. - Поширені помилки налаштування: + Поширені збої налаштування: - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнюється після скорочення; зменште кількість plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`. - - Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було задано як повний endpoint `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot`. - - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як помилка очищення webhook. + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`. + - збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` прибирає випадковий кінцевий `/bot`. + - `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тому це не повідомляється як збій очищення Webhook. - `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано. - ### Команди сполучення пристрою (plugin `device-pair`) + ### Команди сполучення пристрою (Plugin `device-pair`) - Коли plugin `device-pair` встановлено: + Коли встановлено Plugin `device-pair`: 1. `/pair` генерує код налаштування 2. вставте код у застосунок iOS - 3. `/pair pending` показує список запитів, що очікують (включно з роллю/областями) + 3. `/pair pending` показує список запитів, що очікують (включно з роллю/областями доступу) 4. схваліть запит: - `/pair approve ` для явного схвалення - `/pair approve`, коли є лише один запит, що очікує - `/pair approve latest` для найновішого - Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей bootstrap мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, усе ще потребують областей під власним префіксом ролі. + Код налаштування містить короткочасний токен початкового завантаження. Вбудована передача початкового завантаження зберігає токен основного вузла в `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області доступу початкового завантаження мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролям, що не є операторами, усе ще потрібні області доступу з їхнім власним префіксом ролі. - Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області/публічний ключ), попередній запит, що очікував, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. + Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням. Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios). - Налаштуйте область inline-клавіатури: + Налаштуйте область дії вбудованої клавіатури: ```json5 { @@ -433,7 +433,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Області: + Області дії: - `off` - `dm` @@ -441,7 +441,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (за замовчуванням) - Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`. + Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`. Приклад дії повідомлення: @@ -475,9 +475,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`) - Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Елементи керування доступом: + Засоби керування доступом: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` @@ -485,16 +485,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.sticker` (за замовчуванням: вимкнено) Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`. - Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання. + Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціальне повторне розв’язання SecretRef для кожного надсилання. - Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions) + Семантика видалення реакції: [/tools/reactions](/uk/tools/reactions) - - Telegram підтримує явні теги ланцюжків відповідей у згенерованому виводі: + + Telegram підтримує явні теги потоків відповідей у згенерованому виводі: - - `[[reply_to_current]]` відповідає на повідомлення, що спричинило дію + - `[[reply_to_current]]` відповідає на повідомлення-тригер - `[[reply_to:]]` відповідає на конкретний ID повідомлення Telegram `channels.telegram.replyToMode` керує обробкою: @@ -503,17 +503,17 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Коли ланцюжки відповідей увімкнені й доступний оригінальний текст або підпис Telegram, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються від початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. + Коли потоки відповідей увімкнено й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату. - Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. + Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються. - - Супергрупи форуму: + + Форумні супергрупи: - - ключі сесій теми додають `:topic:` - - відповіді та індикатор набору спрямовуються в ланцюжок теми + - ключі сеансів теми додають `:topic:` + - відповіді та індикатор набору спрямовуються в потік теми - шлях конфігурації теми: `channels.telegram.groups..topics.` @@ -522,10 +522,10 @@ curl "https://api.telegram.org/bot/getUpdates" - надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`) - дії набору тексту все ще включають `message_thread_id` - Успадкування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` діє лише для теми й не успадковується з типових налаштувань групи. + Наслідування теми: записи теми успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` належить лише темі й не успадковується з типових значень групи. - **Маршрутизація агента для окремої теми**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад: + **Маршрутизація агента за темою**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сеанс. Приклад: ```json5 { @@ -545,26 +545,26 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Кожна тема після цього має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3` + Кожна тема після цього має власний ключ сеансу: `agent:zu:telegram:group:-1001234567890:topic:3` - **Постійне прив’язування теми ACP**: теми форуму можуть закріплювати сесії ACP harness через типізовані прив’язування ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"`, а також ID з кваліфікатором теми на кшталт `-1001234567890:topic:42`). Наразі область обмежена темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). + **Постійне прив’язування теми ACP**: теми форуму можуть закріплювати сеанси обв’язки ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"`, а також ID з уточненням теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents). - **Створення ACP, прив’язане до ланцюжка, з чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`. + **Прив’язаний до потоку запуск ACP із чату**: `/acp spawn --thread here|auto` прив’язує поточну тему до нового сеансу ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`. - Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сесій з урахуванням ланцюжків. + Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сеансів з урахуванням потоку. ### Аудіоповідомлення - Telegram розрізняє голосові нотатки й аудіофайли. + Telegram розрізняє голосові нотатки та аудіофайли. - за замовчуванням: поведінка аудіофайлу - - тег `[[audio_as_voice]]` у відповіді агента, щоб примусово надіслати голосову нотатку - - транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований, - ненадійний текст; виявлення згадок усе ще використовує сирий - транскрипт, тому голосові повідомлення, обмежені згадками, продовжують працювати. + - тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку + - розшифрування вхідних голосових нотаток оформлюються в контексті агента як згенерований машиною, + недовірений текст; виявлення згадки все ще використовує сире + розшифрування, тому голосові повідомлення з вимогою згадки продовжують працювати. Приклад дії повідомлення: @@ -580,7 +580,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Відеоповідомлення - Telegram розрізняє відеофайли й відеонотатки. + Telegram розрізняє відеофайли та відеонотатки. Приклад дії повідомлення: @@ -600,7 +600,7 @@ curl "https://api.telegram.org/bot/getUpdates" Обробка вхідних стікерів: - - статичний WEBP: завантажується й обробляється (заповнювач ``) + - статичний WEBP: завантажується та обробляється (заповнювач ``) - анімований TGS: пропускається - відео WEBM: пропускається @@ -616,7 +616,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision. + Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору. Увімкнути дії зі стікерами: @@ -657,7 +657,7 @@ curl "https://api.telegram.org/bot/getUpdates" - Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень). + Реакції Telegram надходять як оновлення `message_reaction` (окремо від навантажень повідомлень). Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт: @@ -665,44 +665,44 @@ curl "https://api.telegram.org/bot/getUpdates" Конфігурація: - - `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`) - - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`) Примітки: - - `own` означає лише реакції користувача на повідомлення, надіслані ботом (за найкращих зусиль через кеш надісланих повідомлень). - - Події реакцій усе ще дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. - - Telegram не надає ідентифікатори гілок в оновленнях реакцій. - - нефорумні групи спрямовуються до сеансу групового чату - - форумні групи спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми + - `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень). + - Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються. + - Telegram не надає ID гілок в оновленнях реакцій. + - групи нефорумного типу скеровуються до сеансу групового чату + - форумні групи скеровуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми `allowed_updates` для polling/webhook автоматично включає `message_reaction`. - `ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення. + `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. - Порядок визначення: + Порядок вирішення: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Telegram очікує emoji Unicode (наприклад, "👀"). + - Telegram очікує unicode-емодзі (наприклад, "👀"). - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - Записи конфігурації каналу ввімкнені типово (`configWrites !== false`). + Записи конфігурації каналу ввімкнені за замовчуванням (`configWrites !== false`). - Записи, спричинені Telegram, включають: + Записи, ініційовані Telegram, включають: - - події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` + - події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups` - `/config set` і `/config unset` (потребує ввімкнення команд) Вимкнення: @@ -719,29 +719,29 @@ curl "https://api.telegram.org/bot/getUpdates" - - Типово використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`). + + За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`). - Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. + Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`. - Режим Webhook перевіряє захисти запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram. - Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/кожної теми, що використовуються long polling, тому повільні ходи агента не затримують ACK доставки Telegram. + Режим webhook перевіряє захисні умови запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram. + Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes для кожного чату/теми, що й long polling, тому повільні ходи агента не затримують ACK доставки Telegram. - - - Типове значення `channels.telegram.textChunkLimit` — 4000. - - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною. - - `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram. - - `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). - - `channels.telegram.pollingStallThresholdMs` типово дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зупинку polling. - - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає. - - додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий. - - allowlist-и Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. + + - `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000. + - `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною. + - `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram. + - `channels.telegram.timeoutSeconds` перевизначає timeout клієнта Telegram API (якщо не задано, застосовується значення за замовчуванням grammY). + - `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зупинку polling. + - історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає. + - додатковий контекст reply/quote/forward наразі передається як отримано. + - allowlists Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту. - Керування історією DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для помилок Telegram до підключення, але не повторює неоднозначні мережеві конверти після надсилання, які можуть дублювати видимі повідомлення. + - Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної вхідної відповіді також використовує обмежений безпечний повтор надсилання для збоїв Telegram до підключення, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення. Ціль надсилання CLI може бути числовим ID чату або іменем користувача: @@ -765,50 +765,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` для форумних тем (або використовуйте ціль `:topic:`) + - `--thread-id` для форумних тем (або використайте ціль `:topic:`) Надсилання Telegram також підтримує: - - `--presentation` з блоками `buttons` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє - - `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, коли бот може закріплювати повідомлення в цьому чаті - - `--force-document` для надсилання вихідних зображень і GIF як документів замість стиснених фото або завантажень анімованих медіа + - `--presentation` з блоками `buttons` для inline keyboards, коли це дозволяє `channels.telegram.capabilities.inlineButtons` + - `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті + - `--force-document` для надсилання вихідних зображень і GIF як документів замість стиснених фото або завантажень animated-media Обмеження дій: - `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями - - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими + - `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим - - Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram. + + Telegram підтримує підтвердження exec у DM затверджувачів і може необов’язково публікувати prompts у початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram. Шлях конфігурації: - - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача) - - `channels.telegram.execApprovals.approvers` (відступає до числових ID власників з `commands.ownerAllowFrom`) - - `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both` + - `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача) + - `channels.telegram.execApprovals.approvers` (відступає до числових ID власників із `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене спарювання DM початково налаштовує `commands.ownerAllowFrom`, коли власника команд ще немає, тож налаштування з одним власником усе ще працює без дублювання ID у `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може розмовляти з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось затверджувачем exec. Перше схвалене створення пари DM ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тому налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`. - Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення і подальшого повідомлення. Схвалення exec типово спливають через 30 хвилин. + Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли prompt потрапляє у форумну тему, OpenClaw зберігає тему для prompt затвердження та подальшого повідомлення. Підтвердження exec за замовчуванням спливають через 30 хвилин. - Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення plugin; інші спочатку визначаються через схвалення exec. + Inline-кнопки затвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID затвердження з префіксом `plugin:` вирішуються через затвердження plugin; інші спершу вирішуються через підтвердження exec. - Див. [Схвалення exec](/uk/tools/exec-approvals). + Див. [Підтвердження exec](/uk/tools/exec-approvals). ## Керування відповідями про помилки -Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити його. Цією поведінкою керують два ключі конфігурації: +Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або приховати його. Цю поведінку контролюють два ключі конфігурації: -| Ключ | Значення | Типово | Опис | -| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | +| Ключ | Значення | За замовчуванням | Опис | +| ----------------------------------- | ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю приховує відповіді про помилки. | +| `channels.telegram.errorCooldownMs` | число (мс) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. | Підтримуються перевизначення для кожного облікового запису, групи й теми (те саме успадкування, що й для інших ключів конфігурації Telegram). @@ -835,49 +835,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість. - BotFather: `/setprivacy` -> Disable - - потім видаліть і знову додайте бота до групи + - потім видаліть і повторно додайте бота до групи - `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки. - `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство. - швидкий тест сеансу: `/activation always`. - + - - коли існує `channels.telegram.groups`, група має бути вказана (або містити `"*"`) + - коли існує `channels.telegram.groups`, групу потрібно вказати (або включити `"*"`) - перевірте членство бота в групі - перегляньте журнали: `openclaw logs --follow` для причин пропуску - + - - авторизуйте ідентичність відправника (спарювання та/або числовий `allowFrom`) - - авторизація команд усе ще застосовується, навіть коли політика групи — `open` - - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню - - `setMyCommands failed` з мережевими/ fetch-помилками зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org` + - авторизуйте свою ідентичність відправника (створення пари та/або числовий `allowFrom`) + - авторизація команд усе одно застосовується, навіть коли політика групи `open` + - `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість plugin/skill/custom команд або вимкніть native menus + - `setMyCommands failed` з мережевими/fetch помилками зазвичай указує на проблеми доступності DNS/HTTPS до `api.telegram.org` - + - - `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота. - - Знову скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису. - - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відклало б ту саму помилку неправильного токена до пізніших викликів API. - - Якщо `deleteWebhook` завершується з тимчасовою мережевою помилкою під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо очищення вже виконано. + - `getMe returned 401` є помилкою автентифікації Telegram для налаштованого bot token. + - Скопіюйте повторно або згенеруйте заново bot token у BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням. + - `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий token до наступних викликів API. + - Якщо `deleteWebhook` зазнає збою через тимчасову мережеву помилку під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо очищення вже виконано. - - Node 22+ і користувацький fetch/проксі можуть спричиняти негайну поведінку переривання, якщо типи AbortSignal не збігаються. - - Деякі хости спершу визначають `api.telegram.org` як IPv6; зламаний вихід IPv6 може спричиняти переривчасті збої Telegram API. - - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки. - - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за типових налаштувань. - - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли тривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми проксі, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`. - - Telegram також враховує env проксі процесу для транспорту Bot API, включно з `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхніми варіантами в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. - - Якщо керований проксі OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартного env проксі немає, Telegram також використовує цей URL для транспорту Bot API. - - На VPS-хостах із нестабільним прямим виходом/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`: + - Node 22+ і власний fetch/proxy можуть спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються. + - Деякі hosts спершу вирішують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API. + - Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки. + - Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної liveness long-poll за замовчуванням. + - `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений обліковий запис polling не завершив `getUpdates` після startup grace або коли його остання успішна активність polling transport застаріла. + - Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш host усе одно повідомляє про хибні перезапуски через зупинку polling. Постійні зупинки зазвичай указують на проблеми proxy, DNS, IPv6 або TLS egress між host і `api.telegram.org`. + - Telegram також враховує process proxy env для транспорту Bot API, включно з `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхніми варіантами в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`. + - Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для service environment і стандартного proxy env немає, Telegram також використовує цей URL для транспорту Bot API. + - На VPS hosts з нестабільним прямим egress/TLS скеровуйте виклики Telegram API через `channels.telegram.proxy`: ```yaml channels: @@ -885,8 +886,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ типово використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. - - Якщо ваш хост — WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства: + - Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`. + - Якщо ваш хост — WSL2 або він явно краще працює з поведінкою лише IPv4, примусово задайте вибір family: ```yaml channels: @@ -895,10 +896,10 @@ channels: autoSelectFamily: false ``` - - Відповіді діапазону тестування за RFC 2544 (`198.18.0.0/15`) уже дозволені + - Відповіді з benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або прозорий проксі переписує `api.telegram.org` на якусь іншу - приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете + приватну/внутрішню/спеціального використання адресу під час завантажень медіа, можна увімкнути обхід лише для Telegram: ```yaml @@ -908,17 +909,17 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - Те саме вибіркове ввімкнення доступне для кожного облікового запису за адресою + - Такий самий opt-in доступний для кожного облікового запису за адресою `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - Якщо ваш проксі резолвить хости медіа Telegram у `198.18.x.x`, спочатку залиште - небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон - тестування RFC 2544 за замовчуванням. + небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон + RFC 2544 за замовчуванням. `channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram - від SSRF. Використовуйте це лише в довірених середовищах проксі, керованих оператором, - як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони - синтезують приватні або спеціального призначення відповіді поза діапазоном тестування + від SSRF. Використовуйте це лише для довірених, контрольованих оператором проксі-середовищ, + таких як fake-IP routing у Clash, Mihomo або Surge, коли вони + синтезують приватні або спеціального використання відповіді поза benchmark-діапазоном RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет. @@ -926,7 +927,7 @@ channels: - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Перевірте відповіді DNS: + - Перевірте DNS-відповіді: ```bash dig +short api.telegram.org A @@ -936,24 +937,24 @@ dig +short api.telegram.org AAAA -Додаткова допомога: [Усунення проблем із каналами](/uk/channels/troubleshooting). +Додаткова допомога: [Усунення несправностей каналів](/uk/channels/troubleshooting). ## Довідник конфігурації Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram). - + - запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються) -- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`) -- схвалення виконання: `execApprovals`, `accounts.*.execApprovals` +- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`) +- підтвердження exec: `execApprovals`, `accounts.*.execApprovals` - команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands` -- потоки обговорень/відповіді: `replyToMode` -- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` +- потоки/відповіді: `replyToMode` +- streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming` - форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` - власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot`) -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - реакції: `reactionNotifications`, `reactionLevel` - помилки: `errorPolicy`, `errorCooldownMs` @@ -962,28 +963,28 @@ dig +short api.telegram.org AAAA -Пріоритетність кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. +Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити стандартну маршрутизацію. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає про це. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`. ## Пов’язане - - Сполучіть користувача Telegram із Gateway. + + Зв’яжіть користувача Telegram із gateway. - - Поведінка списку дозволених груп і тем. + + Поведінка allowlist для груп і тем. - + Маршрутизуйте вхідні повідомлення до агентів. - - Модель загроз і посилення захисту. + + Модель загроз і зміцнення захисту. - - Зіставляйте групи й теми з агентами. + + Зіставте групи й теми з агентами. - - Міжканальна діагностика. + + Діагностика між каналами.