chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
dfbb0529cc
commit
519d861a1e
@ -2,29 +2,29 @@
|
||||
read_when:
|
||||
- Ви хочете підключити бота Feishu/Lark
|
||||
- Ви налаштовуєте канал Feishu
|
||||
summary: Огляд бота Feishu, функції та конфігурація
|
||||
summary: Огляд, можливості та конфігурація бота Feishu
|
||||
title: Feishu
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T22:37:52Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T05:57:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 54db77a6bb05d862fe8eb5dfc97d04e4252b20e2b0ccbf204eb49d9d7256b026
|
||||
source_hash: 37de7cbb12821f119ca1a06fcdb8e80a07752e1cbfc462344d24750fbf13147a
|
||||
source_path: channels/feishu.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Feishu / Lark
|
||||
|
||||
Feishu/Lark — це універсальна платформа для співпраці, де команди спілкуються в чаті, діляться документами, керують календарями та разом виконують роботу.
|
||||
Feishu/Lark — це універсальна платформа для спільної роботи, де команди спілкуються, діляться документами, керують календарями та працюють разом.
|
||||
|
||||
**Статус:** готово до використання у продакшені для особистих повідомлень боту та групових чатів. Режим WebSocket використовується за замовчуванням; режим webhook є необов’язковим.
|
||||
**Статус:** готово до production для приватних повідомлень ботам і групових чатів. WebSocket є типовим режимом; режим Webhook необов’язковий.
|
||||
|
||||
---
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Note>
|
||||
Потрібен OpenClaw 2026.4.25 або новіший. Щоб перевірити, виконайте `openclaw --version`. Щоб оновити, виконайте `openclaw update`.
|
||||
Потрібен OpenClaw 2026.4.25 або новіший. Виконайте `openclaw --version`, щоб перевірити. Оновіться за допомогою `openclaw update`.
|
||||
</Note>
|
||||
|
||||
<Steps>
|
||||
@ -32,10 +32,10 @@ Feishu/Lark — це універсальна платформа для спів
|
||||
```bash
|
||||
openclaw channels login --channel feishu
|
||||
```
|
||||
Відскануйте QR-код у мобільному застосунку Feishu/Lark, щоб автоматично створити бота Feishu/Lark.
|
||||
Проскануйте QR-код мобільним застосунком Feishu/Lark, щоб автоматично створити бота Feishu/Lark.
|
||||
</Step>
|
||||
|
||||
<Step title="Після завершення налаштування перезапустіть Gateway, щоб застосувати зміни">
|
||||
<Step title="Після завершення налаштування перезапустіть gateway, щоб застосувати зміни">
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
@ -44,18 +44,18 @@ Feishu/Lark — це універсальна платформа для спів
|
||||
|
||||
---
|
||||
|
||||
## Керування доступом
|
||||
## Контроль доступу
|
||||
|
||||
### Особисті повідомлення
|
||||
### Приватні повідомлення
|
||||
|
||||
Налаштуйте `dmPolicy`, щоб керувати тим, хто може писати боту в особисті повідомлення:
|
||||
Налаштуйте `dmPolicy`, щоб керувати тим, хто може надсилати приватні повідомлення боту:
|
||||
|
||||
- `"pairing"` — невідомі користувачі отримують код прив’язки; схваліть його через CLI
|
||||
- `"pairing"` — невідомі користувачі отримують код сполучення; підтвердіть через CLI
|
||||
- `"allowlist"` — спілкуватися можуть лише користувачі, перелічені в `allowFrom` (типово: лише власник бота)
|
||||
- `"open"` — дозволити всіх користувачів
|
||||
- `"disabled"` — вимкнути всі особисті повідомлення
|
||||
- `"open"` — дозволити публічні приватні повідомлення лише коли `allowFrom` містить `"*"`; з обмежувальними записами спілкуватися можуть лише відповідні користувачі
|
||||
- `"disabled"` — вимкнути всі приватні повідомлення
|
||||
|
||||
**Схвалити запит на прив’язку:**
|
||||
**Підтвердити запит на сполучення:**
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@ -66,26 +66,26 @@ openclaw pairing approve feishu <CODE>
|
||||
|
||||
**Політика груп** (`channels.feishu.groupPolicy`):
|
||||
|
||||
| Значення | Поведінка |
|
||||
| ------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `"open"` | Відповідати на всі повідомлення в групах |
|
||||
| `"allowlist"` | Відповідати лише в групах із `groupAllowFrom` або явно налаштованих у `groups.<chat_id>` |
|
||||
| `"disabled"` | Вимкнути всі повідомлення в групах; явні записи `groups.<chat_id>` не перевизначають це |
|
||||
| Значення | Поведінка |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `"open"` | Відповідати на всі повідомлення в групах |
|
||||
| `"allowlist"` | Відповідати лише групам у `groupAllowFrom` або явно налаштованим у `groups.<chat_id>` |
|
||||
| `"disabled"` | Вимкнути всі групові повідомлення; явні записи `groups.<chat_id>` не перевизначають це |
|
||||
|
||||
Типове значення: `allowlist`
|
||||
Типово: `allowlist`
|
||||
|
||||
**Вимога згадки** (`channels.feishu.requireMention`):
|
||||
|
||||
- `true` — вимагати @mention (типово)
|
||||
- `false` — відповідати без @mention
|
||||
- `true` — вимагати @згадку (типово)
|
||||
- `false` — відповідати без @згадки
|
||||
- Перевизначення для окремої групи: `channels.feishu.groups.<chat_id>.requireMention`
|
||||
- Згадки лише для розсилки `@all` і `@_all` не вважаються згадками бота. Повідомлення, яке містить і `@all`, і пряму згадку бота, усе одно вважається згадкою бота.
|
||||
- Трансляційні лише `@all` і `@_all` не вважаються згадками бота. Повідомлення, яке згадує і `@all`, і бота напряму, усе одно зараховується як згадка бота.
|
||||
|
||||
---
|
||||
|
||||
## Приклади конфігурації груп
|
||||
|
||||
### Дозволити всі групи, без обов’язкової @mention
|
||||
### Дозволити всі групи, без вимоги @згадки
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -97,7 +97,7 @@ openclaw pairing approve feishu <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
### Дозволити всі групи, але все одно вимагати @mention
|
||||
### Дозволити всі групи, але все ще вимагати @згадку
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -117,14 +117,14 @@ openclaw pairing approve feishu <CODE>
|
||||
channels: {
|
||||
feishu: {
|
||||
groupPolicy: "allowlist",
|
||||
// Ідентифікатори груп мають вигляд: oc_xxx
|
||||
// Group IDs look like: oc_xxx
|
||||
groupAllowFrom: ["oc_xxx", "oc_yyy"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
У режимі `allowlist` ви також можете дозволити групу, додавши явний запис `groups.<chat_id>`. Явні записи не перевизначають `groupPolicy: "disabled"`. Шаблонні значення за замовчуванням у `groups.*` налаштовують відповідні групи, але самі по собі не надають групам доступ.
|
||||
У режимі `allowlist` ви також можете допустити групу, додавши явний запис `groups.<chat_id>`. Явні записи не перевизначають `groupPolicy: "disabled"`. Типові значення з wildcard у `groups.*` налаштовують відповідні групи, але самі по собі не допускають групи.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -141,7 +141,7 @@ openclaw pairing approve feishu <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
### Обмежити відправників усередині групи
|
||||
### Обмежити відправників у групі
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -151,7 +151,7 @@ openclaw pairing approve feishu <CODE>
|
||||
groupAllowFrom: ["oc_xxx"],
|
||||
groups: {
|
||||
oc_xxx: {
|
||||
// open_id користувачів мають вигляд: ou_xxx
|
||||
// User open_ids look like: ou_xxx
|
||||
allowFrom: ["ou_user1", "ou_user2"],
|
||||
},
|
||||
},
|
||||
@ -164,23 +164,23 @@ openclaw pairing approve feishu <CODE>
|
||||
|
||||
<a id="get-groupuser-ids"></a>
|
||||
|
||||
## Отримання ідентифікаторів груп/користувачів
|
||||
## Отримати ідентифікатори груп/користувачів
|
||||
|
||||
### Ідентифікатори груп (`chat_id`, формат: `oc_xxx`)
|
||||
|
||||
Відкрийте групу у Feishu/Lark, натисніть значок меню у верхньому правому куті та перейдіть до **Налаштувань**. Ідентифікатор групи (`chat_id`) вказано на сторінці налаштувань.
|
||||
Відкрийте групу у Feishu/Lark, натисніть іконку меню у верхньому правому куті та перейдіть до **Налаштувань**. Ідентифікатор групи (`chat_id`) зазначено на сторінці налаштувань.
|
||||
|
||||
|
||||
|
||||
|
||||
### Ідентифікатори користувачів (`open_id`, формат: `ou_xxx`)
|
||||
|
||||
Запустіть Gateway, надішліть боту особисте повідомлення, а потім перевірте журнали:
|
||||
Запустіть gateway, надішліть приватне повідомлення боту, потім перевірте журнали:
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Знайдіть `open_id` у виведенні журналів. Ви також можете перевірити незавершені запити на прив’язку:
|
||||
Шукайте `open_id` у виводі журналу. Також можна перевірити запити на сполучення, що очікують:
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@ -190,14 +190,14 @@ openclaw pairing list feishu
|
||||
|
||||
## Поширені команди
|
||||
|
||||
| Команда | Опис |
|
||||
| --------- | ----------------------------- |
|
||||
| `/status` | Показати стан бота |
|
||||
| `/reset` | Скинути поточну сесію |
|
||||
| `/model` | Показати або змінити AI-модель |
|
||||
| Команда | Опис |
|
||||
| --------- | ---------------------------- |
|
||||
| `/status` | Показати статус бота |
|
||||
| `/reset` | Скинути поточний сеанс |
|
||||
| `/model` | Показати або змінити модель ШІ |
|
||||
|
||||
<Note>
|
||||
Feishu/Lark не підтримує вбудовані меню slash-команд, тому надсилайте їх як звичайні текстові повідомлення.
|
||||
Feishu/Lark не підтримує нативні меню slash-команд, тому надсилайте їх як звичайні текстові повідомлення.
|
||||
</Note>
|
||||
|
||||
---
|
||||
@ -207,24 +207,24 @@ Feishu/Lark не підтримує вбудовані меню slash-коман
|
||||
### Бот не відповідає в групових чатах
|
||||
|
||||
1. Переконайтеся, що бота додано до групи
|
||||
2. Переконайтеся, що ви згадали бота через @mention (це потрібно за замовчуванням)
|
||||
3. Переконайтеся, що `groupPolicy` не має значення `"disabled"`
|
||||
2. Переконайтеся, що ви @згадали бота (це потрібно типово)
|
||||
3. Перевірте, що `groupPolicy` не є `"disabled"`
|
||||
4. Перевірте журнали: `openclaw logs --follow`
|
||||
|
||||
### Бот не отримує повідомлення
|
||||
|
||||
1. Переконайтеся, що бота опубліковано та схвалено в Feishu Open Platform / Lark Developer
|
||||
1. Переконайтеся, що бота опубліковано й схвалено у Feishu Open Platform / Lark Developer
|
||||
2. Переконайтеся, що підписка на події містить `im.message.receive_v1`
|
||||
3. Переконайтеся, що вибрано **persistent connection** (WebSocket)
|
||||
3. Переконайтеся, що вибрано **постійне підключення** (WebSocket)
|
||||
4. Переконайтеся, що надано всі потрібні області дозволів
|
||||
5. Переконайтеся, що Gateway запущено: `openclaw gateway status`
|
||||
5. Переконайтеся, що gateway працює: `openclaw gateway status`
|
||||
6. Перевірте журнали: `openclaw logs --follow`
|
||||
|
||||
### Витік App Secret
|
||||
### App Secret витік
|
||||
|
||||
1. Скиньте App Secret у Feishu Open Platform / Lark Developer
|
||||
2. Оновіть значення у своїй конфігурації
|
||||
3. Перезапустіть Gateway: `openclaw gateway restart`
|
||||
3. Перезапустіть gateway: `openclaw gateway restart`
|
||||
|
||||
---
|
||||
|
||||
@ -241,7 +241,7 @@ Feishu/Lark не підтримує вбудовані меню slash-коман
|
||||
main: {
|
||||
appId: "cli_xxx",
|
||||
appSecret: "xxx",
|
||||
name: "Основний бот",
|
||||
name: "Primary bot",
|
||||
tts: {
|
||||
providers: {
|
||||
openai: { voice: "shimmer" },
|
||||
@ -251,7 +251,7 @@ Feishu/Lark не підтримує вбудовані меню slash-коман
|
||||
backup: {
|
||||
appId: "cli_yyy",
|
||||
appSecret: "yyy",
|
||||
name: "Резервний бот",
|
||||
name: "Backup bot",
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
@ -260,40 +260,40 @@ Feishu/Lark не підтримує вбудовані меню slash-коман
|
||||
}
|
||||
```
|
||||
|
||||
`defaultAccount` визначає, який обліковий запис використовується, коли вихідні API не вказують `accountId`.
|
||||
`accounts.<id>.tts` використовує ту саму структуру, що й `messages.tts`, і виконує глибоке злиття поверх
|
||||
глобальної конфігурації TTS, тож у багатоботних конфігураціях Feishu можна
|
||||
зберігати спільні облікові дані провайдерів глобально, перевизначаючи лише voice, model, persona або auto mode
|
||||
`defaultAccount` керує тим, який обліковий запис використовується, коли вихідні API не вказують `accountId`.
|
||||
`accounts.<id>.tts` використовує ту саму форму, що й `messages.tts`, і виконує глибоке злиття поверх
|
||||
глобальної конфігурації TTS, тому налаштування Feishu з кількома ботами можуть зберігати спільні облікові дані
|
||||
провайдера глобально, перевизначаючи лише голос, модель, персону або автоматичний режим
|
||||
для кожного облікового запису.
|
||||
|
||||
### Обмеження повідомлень
|
||||
|
||||
- `textChunkLimit` — розмір фрагмента вихідного тексту (типово: `2000` символів)
|
||||
- `mediaMaxMb` — обмеження на вивантаження/завантаження медіа (типово: `30` МБ)
|
||||
- `mediaMaxMb` — ліміт завантаження/вивантаження медіа (типово: `30` МБ)
|
||||
|
||||
### Потокова передача
|
||||
### Потокове передавання
|
||||
|
||||
Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Якщо ввімкнено, бот оновлює картку в реальному часі під час генерування тексту.
|
||||
Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Коли це ввімкнено, бот оновлює картку в реальному часі під час генерування тексту.
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
streaming: true, // увімкнути потоковий вивід у картках (типово: true)
|
||||
blockStreaming: true, // увімкнути потокову передачу на рівні блоків (типово: true)
|
||||
streaming: true, // enable streaming card output (default: true)
|
||||
blockStreaming: true, // enable block-level streaming (default: true)
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Установіть `streaming: false`, щоб надсилати повну відповідь одним повідомленням.
|
||||
Установіть `streaming: false`, щоб надіслати повну відповідь одним повідомленням.
|
||||
|
||||
### Оптимізація квот
|
||||
### Оптимізація квоти
|
||||
|
||||
Зменште кількість викликів API Feishu/Lark за допомогою двох необов’язкових прапорців:
|
||||
|
||||
- `typingIndicator` (типово `true`): установіть `false`, щоб пропускати виклики реакції друку
|
||||
- `resolveSenderNames` (типово `true`): установіть `false`, щоб пропускати пошук профілів відправників
|
||||
- `typingIndicator` (типово `true`): установіть `false`, щоб пропустити виклики реакції набору тексту
|
||||
- `resolveSenderNames` (типово `true`): установіть `false`, щоб пропустити пошуки профілів відправників
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -306,11 +306,11 @@ Feishu/Lark підтримує потокові відповіді через і
|
||||
}
|
||||
```
|
||||
|
||||
### Сесії ACP
|
||||
### Сеанси ACP
|
||||
|
||||
Feishu/Lark підтримує ACP для особистих повідомлень і повідомлень у потоках груп. ACP у Feishu/Lark керується текстовими командами — вбудованих меню slash-команд немає, тому використовуйте повідомлення `/acp ...` безпосередньо в розмові.
|
||||
Feishu/Lark підтримує ACP для приватних повідомлень і повідомлень у групових тредах. ACP у Feishu/Lark керується текстовими командами — нативних меню slash-команд немає, тому використовуйте повідомлення `/acp ...` безпосередньо в розмові.
|
||||
|
||||
#### Постійна прив’язка ACP
|
||||
#### Постійне прив’язування ACP
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -356,17 +356,17 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
|
||||
#### Запуск ACP із чату
|
||||
|
||||
У особистому повідомленні Feishu/Lark або в потоці:
|
||||
У приватному повідомленні або треді Feishu/Lark:
|
||||
|
||||
```text
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
`--thread here` працює для особистих повідомлень і повідомлень у потоках Feishu/Lark. Подальші повідомлення в прив’язаній розмові спрямовуються безпосередньо до цієї сесії ACP.
|
||||
`--thread here` працює для приватних повідомлень і повідомлень у тредах Feishu/Lark. Подальші повідомлення у прив’язаній розмові спрямовуються безпосередньо до цього сеансу ACP.
|
||||
|
||||
### Маршрутизація між кількома агентами
|
||||
### Маршрутизація кількох агентів
|
||||
|
||||
Використовуйте `bindings`, щоб спрямовувати особисті повідомлення або групи Feishu/Lark до різних агентів.
|
||||
Використовуйте `bindings`, щоб спрямовувати приватні повідомлення або групи Feishu/Lark до різних агентів.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -399,10 +399,10 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
Поля маршрутизації:
|
||||
|
||||
- `match.channel`: `"feishu"`
|
||||
- `match.peer.kind`: `"direct"` (особисте повідомлення) або `"group"` (груповий чат)
|
||||
- `match.peer.kind`: `"direct"` (приватне повідомлення) або `"group"` (груповий чат)
|
||||
- `match.peer.id`: Open ID користувача (`ou_xxx`) або ідентифікатор групи (`oc_xxx`)
|
||||
|
||||
Див. [Отримання ідентифікаторів груп/користувачів](#get-groupuser-ids), щоб дізнатися, як їх знайти.
|
||||
Див. [Отримати ідентифікатори груп/користувачів](#get-groupuser-ids), щоб отримати поради щодо пошуку.
|
||||
|
||||
---
|
||||
|
||||
@ -410,34 +410,34 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
|
||||
Повна конфігурація: [Конфігурація Gateway](/uk/gateway/configuration)
|
||||
|
||||
| Налаштування | Опис | Типове значення |
|
||||
| ------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------- |
|
||||
| `channels.feishu.enabled` | Увімкнути/вимкнути канал | `true` |
|
||||
| `channels.feishu.domain` | Домен API (`feishu` або `lark`) | `feishu` |
|
||||
| `channels.feishu.connectionMode` | Транспорт подій (`websocket` або `webhook`) | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | Типовий обліковий запис для вихідної маршрутизації | `default` |
|
||||
| `channels.feishu.verificationToken` | Потрібен для режиму webhook | — |
|
||||
| `channels.feishu.encryptKey` | Потрібен для режиму webhook | — |
|
||||
| `channels.feishu.webhookPath` | Шлях маршруту webhook | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | Хост прив’язки webhook | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | Порт прив’язки webhook | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | App ID | — |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
|
||||
| `channels.feishu.accounts.<id>.domain` | Перевизначення домену для окремого облікового запису | `feishu` |
|
||||
| `channels.feishu.accounts.<id>.tts` | Перевизначення TTS для окремого облікового запису | `messages.tts` |
|
||||
| `channels.feishu.dmPolicy` | Політика особистих повідомлень | `allowlist` |
|
||||
| `channels.feishu.allowFrom` | Список дозволених для особистих повідомлень (`open_id`) | [BotOwnerId] |
|
||||
| `channels.feishu.groupPolicy` | Політика груп | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | Список дозволених груп | — |
|
||||
| `channels.feishu.requireMention` | Вимагати @mention у групах | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Перевизначення @mention для окремої групи; явні ID також дозволяють групу в режимі allowlist | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | Увімкнути/вимкнути конкретну групу | `true` |
|
||||
| `channels.feishu.textChunkLimit` | Розмір фрагмента повідомлення | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | Обмеження розміру медіа | `30` |
|
||||
| `channels.feishu.streaming` | Потоковий вивід у картках | `true` |
|
||||
| `channels.feishu.blockStreaming` | Потокова передача на рівні блоків | `true` |
|
||||
| `channels.feishu.typingIndicator` | Надсилати реакції набору тексту | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | Визначати відображувані імена відправників | `true` |
|
||||
| Налаштування | Опис | Типово |
|
||||
| ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------- |
|
||||
| `channels.feishu.enabled` | Увімкнути/вимкнути канал | `true` |
|
||||
| `channels.feishu.domain` | Домен API (`feishu` або `lark`) | `feishu` |
|
||||
| `channels.feishu.connectionMode` | Транспорт подій (`websocket` або `webhook`) | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | Обліковий запис за замовчуванням для вихідної маршрутизації | `default` |
|
||||
| `channels.feishu.verificationToken` | Потрібно для режиму webhook | — |
|
||||
| `channels.feishu.encryptKey` | Потрібно для режиму webhook | — |
|
||||
| `channels.feishu.webhookPath` | Шлях маршруту webhook | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | Хост прив’язки webhook | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | Порт прив’язки webhook | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | ID застосунку | — |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | Секрет застосунку | — |
|
||||
| `channels.feishu.accounts.<id>.domain` | Перевизначення домену для окремого облікового запису | `feishu` |
|
||||
| `channels.feishu.accounts.<id>.tts` | Перевизначення TTS для окремого облікового запису | `messages.tts` |
|
||||
| `channels.feishu.dmPolicy` | Політика DM | `allowlist` |
|
||||
| `channels.feishu.allowFrom` | Список дозволених DM (список open_id) | [BotOwnerId] |
|
||||
| `channels.feishu.groupPolicy` | Політика груп | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | Список дозволених груп | — |
|
||||
| `channels.feishu.requireMention` | Вимагати @mention у групах | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Перевизначення @mention для окремої групи; явні ID також допускають групу в режимі allowlist | успадковано |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | Увімкнути/вимкнути конкретну групу | `true` |
|
||||
| `channels.feishu.textChunkLimit` | Розмір фрагмента повідомлення | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | Обмеження розміру медіа | `30` |
|
||||
| `channels.feishu.streaming` | Потокове виведення карток | `true` |
|
||||
| `channels.feishu.blockStreaming` | Потокове передавання на рівні блоків | `true` |
|
||||
| `channels.feishu.typingIndicator` | Надсилати реакції набору тексту | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | Визначати відображувані імена відправників | `true` |
|
||||
|
||||
---
|
||||
|
||||
@ -453,13 +453,14 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
- ✅ Відео/медіа
|
||||
- ✅ Стікери
|
||||
|
||||
Вхідні аудіоповідомлення Feishu/Lark нормалізуються як заповнювачі медіа замість
|
||||
необробленого JSON `file_key`. Якщо налаштовано `tools.media.audio`, OpenClaw
|
||||
завантажує ресурс голосового повідомлення та виконує спільну транскрипцію аудіо перед
|
||||
ходом агента, щоб агент отримав транскрибований мовний текст. Якщо Feishu вже містить
|
||||
текст транскрипції безпосередньо в аудіокорисному навантаженні, цей текст використовується без
|
||||
додаткового виклику ASR. Без провайдера транскрипції аудіо агент усе одно отримує
|
||||
заповнювач `<media:audio>` разом зі збереженим вкладенням, а не необроблене корисне навантаження ресурсу Feishu.
|
||||
Вхідні аудіоповідомлення Feishu/Lark нормалізуються як медіаплейсхолдери, а не
|
||||
як необроблений JSON `file_key`. Коли налаштовано `tools.media.audio`, OpenClaw
|
||||
завантажує ресурс голосової нотатки й запускає спільну транскрипцію аудіо перед
|
||||
ходом агента, тож агент отримує текстову розшифровку мовлення. Якщо Feishu містить
|
||||
текст транскрипції безпосередньо в аудіо payload, цей текст використовується без
|
||||
ще одного виклику ASR. Без провайдера транскрипції аудіо агент усе одно отримує
|
||||
плейсхолдер `<media:audio>` разом зі збереженим вкладенням, а не необроблений
|
||||
payload ресурсу Feishu.
|
||||
|
||||
### Надсилання
|
||||
|
||||
@ -468,34 +469,35 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
- ✅ Файли
|
||||
- ✅ Аудіо
|
||||
- ✅ Відео/медіа
|
||||
- ✅ Інтерактивні картки (включно з потоковими оновленнями)
|
||||
- ⚠️ Форматований текст (форматування у стилі post; не підтримує всі можливості авторингу Feishu/Lark)
|
||||
- ✅ Інтерактивні картки (зокрема потокові оновлення)
|
||||
- ⚠️ Форматований текст (форматування у стилі post; не підтримує повні можливості авторингу Feishu/Lark)
|
||||
|
||||
Нативні аудіобульбашки Feishu/Lark використовують тип повідомлення Feishu `audio` і потребують
|
||||
вивантаження медіа у форматі Ogg/Opus (`file_type: "opus"`). Наявні медіафайли `.opus` і `.ogg`
|
||||
надсилаються напряму як нативне аудіо. MP3/WAV/M4A та інші ймовірні аудіоформати
|
||||
транскодуються в 48kHz Ogg/Opus за допомогою `ffmpeg` лише тоді, коли відповідь запитує
|
||||
голосову доставку (`audioAsVoice` / інструмент повідомлень `asVoice`, включно з голосовими
|
||||
відповідями TTS). Звичайні вкладення MP3 залишаються звичайними файлами. Якщо `ffmpeg` відсутній або
|
||||
конвертація завершується помилкою, OpenClaw переходить до вкладення файлу та записує причину в журнал.
|
||||
медіа для завантаження Ogg/Opus (`file_type: "opus"`). Наявні медіа `.opus` і `.ogg`
|
||||
надсилаються безпосередньо як нативне аудіо. MP3/WAV/M4A та інші ймовірні аудіоформати
|
||||
перекодовуються у 48kHz Ogg/Opus через `ffmpeg` лише тоді, коли відповідь запитує
|
||||
доставку голосом (`audioAsVoice` / інструмент повідомлень `asVoice`, зокрема відповіді
|
||||
TTS у вигляді голосових нотаток). Звичайні вкладення MP3 залишаються звичайними файлами. Якщо `ffmpeg` відсутній або
|
||||
конвертація не вдається, OpenClaw повертається до вкладення файлу й записує причину в журнал.
|
||||
|
||||
### Потоки та відповіді
|
||||
|
||||
- ✅ Вбудовані відповіді
|
||||
- ✅ Відповіді в потоках
|
||||
- ✅ Відповіді з медіа зберігають прив’язку до потоку при відповіді на повідомлення в потоці
|
||||
- ✅ Відповіді з медіа залишаються прив’язаними до потоку під час відповіді на повідомлення в потоці
|
||||
|
||||
Для `groupSessionScope: "group_topic"` і `"group_topic_sender"` нативні
|
||||
тематичні групи Feishu/Lark використовують `thread_id` події (`omt_*`) як канонічний ключ сесії теми.
|
||||
Звичайні відповіді в групі, які OpenClaw перетворює на потоки, і далі використовують ID кореневого
|
||||
повідомлення відповіді (`om_*`), щоб перший хід і наступний хід залишалися в одній сесії.
|
||||
тематичні групи Feishu/Lark використовують подію `thread_id` (`omt_*`) як канонічний
|
||||
ключ тематичної сесії. Звичайні групові відповіді, які OpenClaw перетворює на потоки, і далі
|
||||
використовують ID кореневого повідомлення відповіді (`om_*`), щоб перший хід і наступний хід
|
||||
залишалися в тій самій сесії.
|
||||
|
||||
---
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд каналів](/uk/channels) — усі підтримувані канали
|
||||
- [Прив’язка](/uk/channels/pairing) — автентифікація особистих повідомлень і процес прив’язки
|
||||
- [Групи](/uk/channels/groups) — поведінка групових чатів і керування через згадки
|
||||
- [Сполучення](/uk/channels/pairing) — автентифікація DM і процес сполучення
|
||||
- [Групи](/uk/channels/groups) — поведінка групового чату й обмеження за згадками
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
|
||||
- [Безпека](/uk/gateway/security) — модель доступу та захист системи
|
||||
- [Безпека](/uk/gateway/security) — модель доступу й посилення захисту
|
||||
|
||||
@ -1,51 +1,56 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування контролю доступу до особистих повідомлень
|
||||
- Сполучення нового iOS/Android Node
|
||||
- Перегляд стану безпеки OpenClaw
|
||||
summary: 'Огляд сполучення: схваліть, хто може надсилати вам приватні повідомлення + які вузли можуть приєднуватися'
|
||||
- Сполучення нового вузла iOS/Android
|
||||
- Огляд стану безпеки OpenClaw
|
||||
summary: 'Огляд спарювання: схваліть, хто може надсилати вам приватні повідомлення + які вузли можуть приєднуватися'
|
||||
title: Сполучення
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T22:44:27Z"
|
||||
generated_at: "2026-04-29T05:57:19Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 123d1dccfab0a2ed8a415934eb508e373c4fe85e3d07adb5eb8aa9f3cf8a3fc9
|
||||
source_hash: cfdcaf831aedb122ea85200518b8dc1c6f42eff365444dee6c4b740050b1ce26
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
«Спарювання» — це явний крок підтвердження доступу в OpenClaw.
|
||||
«Сполучення» — це явний крок підтвердження доступу в OpenClaw.
|
||||
Воно використовується у двох місцях:
|
||||
|
||||
1. **Спарювання DM** (кому дозволено спілкуватися з ботом)
|
||||
2. **Спарювання Node** (яким пристроям/Node дозволено приєднуватися до мережі Gateway)
|
||||
1. **Сполучення DM** (кому дозволено спілкуватися з ботом)
|
||||
2. **Сполучення Node** (яким пристроям/вузлам дозволено приєднуватися до мережі Gateway)
|
||||
|
||||
Контекст безпеки: [Безпека](/uk/gateway/security)
|
||||
|
||||
## 1) Спарювання DM (вхідний доступ до чату)
|
||||
## 1) Сполучення DM (вхідний доступ до чату)
|
||||
|
||||
Коли канал налаштовано з політикою DM `pairing`, невідомі відправники отримують короткий код, а їхнє повідомлення **не обробляється**, доки ви його не підтвердите.
|
||||
Коли канал налаштовано з політикою DM `pairing`, невідомі відправники отримують короткий код, а їхнє повідомлення **не обробляється**, доки ви не схвалите доступ.
|
||||
|
||||
Типові політики DM задокументовано тут: [Безпека](/uk/gateway/security)
|
||||
|
||||
Коди спарювання:
|
||||
`dmPolicy: "open"` є публічною лише тоді, коли ефективний список дозволених DM містить `"*"`.
|
||||
Налаштування й перевірка вимагають цей wildcard для публічно відкритих конфігурацій. Якщо наявний
|
||||
стан містить `open` з конкретними записами `allowFrom`, runtime все одно допускає
|
||||
лише цих відправників, а схвалення в pairing-store не розширюють доступ `open`.
|
||||
|
||||
Коди сполучення:
|
||||
|
||||
- 8 символів, великі літери, без неоднозначних символів (`0O1I`).
|
||||
- **Спливають через 1 годину**. Бот надсилає повідомлення про спарювання лише тоді, коли створюється новий запит (приблизно раз на годину для кожного відправника).
|
||||
- Очікувані запити на спарювання DM типово обмежені **3 на канал**; додаткові запити ігноруються, доки один не спливе або не буде схвалений.
|
||||
- **Завершують дію через 1 годину**. Бот надсилає повідомлення про сполучення лише коли створюється новий запит (приблизно раз на годину для кожного відправника).
|
||||
- Очікувані запити на сполучення DM типово обмежено **3 на канал**; додаткові запити ігноруються, доки один із них не завершить дію або не буде схвалений.
|
||||
|
||||
### Схвалити відправника
|
||||
### Схвалення відправника
|
||||
|
||||
```bash
|
||||
openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Якщо власника команд ще не налаштовано, схвалення коду спарювання DM також ініціалізує
|
||||
Якщо власника команд ще не налаштовано, схвалення коду сполучення DM також початково заповнює
|
||||
`commands.ownerAllowFrom` схваленим відправником, наприклад `telegram:123456789`.
|
||||
Це дає початковим налаштуванням явного власника для привілейованих команд і запитів
|
||||
на схвалення exec. Після появи власника наступні схвалення спарювання надають лише
|
||||
доступ до DM; вони не додають більше власників.
|
||||
підтвердження exec. Після появи власника подальші схвалення сполучення надають лише
|
||||
доступ до DM; вони не додають нових власників.
|
||||
|
||||
Підтримувані канали: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
|
||||
|
||||
@ -54,60 +59,60 @@ openclaw pairing approve telegram <CODE>
|
||||
Зберігається в `~/.openclaw/credentials/`:
|
||||
|
||||
- Очікувані запити: `<channel>-pairing.json`
|
||||
- Схвалене сховище allowlist:
|
||||
- Типовий акаунт: `<channel>-allowFrom.json`
|
||||
- Нетиповий акаунт: `<channel>-<accountId>-allowFrom.json`
|
||||
- Сховище схваленого списку дозволених:
|
||||
- Типовий обліковий запис: `<channel>-allowFrom.json`
|
||||
- Нетиповий обліковий запис: `<channel>-<accountId>-allowFrom.json`
|
||||
|
||||
Поведінка області акаунта:
|
||||
Поведінка області дії облікового запису:
|
||||
|
||||
- Нетипові акаунти читають/записують лише свій файл allowlist з областю.
|
||||
- Типовий акаунт використовує каналовий файл allowlist без області.
|
||||
- Нетипові облікові записи читають/записують лише свій scoped файл списку дозволених.
|
||||
- Типовий обліковий запис використовує channel-scoped unscoped файл списку дозволених.
|
||||
|
||||
Вважайте ці дані чутливими (вони контролюють доступ до вашого асистента).
|
||||
Ставтеся до них як до чутливих даних (вони керують доступом до вашого асистента).
|
||||
|
||||
<Note>
|
||||
Сховище allowlist для спарювання призначене для доступу до DM. Авторизація груп окрема.
|
||||
Схвалення коду спарювання DM не дозволяє автоматично цьому відправнику запускати групові
|
||||
команди або керувати ботом у групах. Початкова ініціалізація першого власника є окремим станом
|
||||
конфігурації в `commands.ownerAllowFrom`, а доставка в групові чати й надалі підпорядковується
|
||||
груповим allowlist каналу (наприклад `groupAllowFrom`, `groups` або перевизначенням для окремої групи
|
||||
чи окремої теми залежно від каналу).
|
||||
Сховище списку дозволених для сполучення призначене для доступу до DM. Авторизація груп є окремою.
|
||||
Схвалення коду сполучення DM не дозволяє цьому відправнику автоматично виконувати групові
|
||||
команди або керувати ботом у групах. Початкове налаштування першого власника є окремим станом конфігурації
|
||||
в `commands.ownerAllowFrom`, а доставка групових чатів і надалі дотримується
|
||||
списків дозволених груп каналу (наприклад `groupAllowFrom`, `groups` або перевизначень для окремих груп
|
||||
чи окремих тем залежно від каналу).
|
||||
</Note>
|
||||
|
||||
## 2) Спарювання пристрою Node (iOS/Android/macOS/headless Node)
|
||||
## 2) Сполучення пристрою Node (iOS/Android/macOS/headless вузли)
|
||||
|
||||
Node підключаються до Gateway як **пристрої** з `role: node`. Gateway
|
||||
створює запит на спарювання пристрою, який потрібно схвалити.
|
||||
Вузли підключаються до Gateway як **пристрої** з `role: node`. Gateway
|
||||
створює запит на сполучення пристрою, який потрібно схвалити.
|
||||
|
||||
### Спарювання через Telegram (рекомендовано для iOS)
|
||||
### Сполучення через Telegram (рекомендовано для iOS)
|
||||
|
||||
Якщо ви використовуєте Plugin `device-pair`, можна виконати перше спарювання пристрою повністю з Telegram:
|
||||
Якщо ви використовуєте Plugin `device-pair`, перше сполучення пристрою можна повністю виконати з Telegram:
|
||||
|
||||
1. У Telegram напишіть своєму боту: `/pair`
|
||||
2. Бот відповість двома повідомленнями: повідомленням з інструкціями та окремим повідомленням із **кодом налаштування** (його легко скопіювати/вставити в Telegram).
|
||||
3. На телефоні відкрийте застосунок OpenClaw для iOS → Settings → Gateway.
|
||||
1. У Telegram напишіть вашому боту: `/pair`
|
||||
2. Бот відповідає двома повідомленнями: повідомленням з інструкцією та окремим повідомленням із **кодом налаштування** (його легко скопіювати/вставити в Telegram).
|
||||
3. На телефоні відкрийте застосунок OpenClaw iOS → Settings → Gateway.
|
||||
4. Вставте код налаштування та підключіться.
|
||||
5. Поверніться в Telegram: `/pair pending` (перегляньте ID запитів, роль і області), потім схваліть.
|
||||
5. Поверніться в Telegram: `/pair pending` (перегляньте ідентифікатори запитів, роль і області дії), потім схваліть.
|
||||
|
||||
Код налаштування — це base64-кодоване JSON-навантаження, яке містить:
|
||||
Код налаштування — це JSON-пакет, закодований у base64, який містить:
|
||||
|
||||
- `url`: URL WebSocket для Gateway (`ws://...` або `wss://...`)
|
||||
- `bootstrapToken`: короткоживучий bootstrap-токен для одного пристрою, що використовується для початкового handshake спарювання
|
||||
- `url`: WebSocket URL Gateway (`ws://...` або `wss://...`)
|
||||
- `bootstrapToken`: короткочасний bootstrap-токен для одного пристрою, який використовується для початкового handshake сполучення
|
||||
|
||||
Цей bootstrap-токен містить вбудований bootstrap-профіль спарювання:
|
||||
Цей bootstrap-токен несе вбудований bootstrap-профіль сполучення:
|
||||
|
||||
- основний переданий токен `node` залишається з `scopes: []`
|
||||
- будь-який переданий токен `operator` залишається обмеженим bootstrap allowlist:
|
||||
- будь-який переданий токен `operator` залишається обмеженим bootstrap-списком дозволених:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- перевірки bootstrap-областей мають префікс ролі, а не один плоский пул областей:
|
||||
записи області operator задовольняють лише запити operator, а ролі не-operator
|
||||
усе одно мають запитувати області під власним префіксом ролі
|
||||
- подальша ротація/відкликання токенів залишається обмеженою як схваленим
|
||||
контрактом ролі пристрою, так і областями operator сесії викликача
|
||||
- перевірки bootstrap-областей мають префікс ролі, а не один плаский пул областей:
|
||||
записи області operator задовольняють лише запити operator, а не-operator ролі
|
||||
все одно мають запитувати області під власним префіксом ролі
|
||||
- подальша ротація/відкликання токена залишається обмеженою як схваленим
|
||||
рольовим контрактом пристрою, так і operator-областями сесії викликача
|
||||
|
||||
Ставтеся до коду налаштування як до пароля, поки він чинний.
|
||||
Ставтеся до коду налаштування як до пароля, доки він чинний.
|
||||
|
||||
### Схвалити пристрій Node
|
||||
### Схвалення пристрою Node
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
@ -115,17 +120,17 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
Якщо той самий пристрій повторює спробу з іншими даними автентифікації (наприклад з іншими
|
||||
роллю/областями/публічним ключем), попередній очікуваний запит замінюється, і створюється новий
|
||||
Якщо той самий пристрій повторює спробу з іншими деталями автентифікації (наприклад іншими
|
||||
роллю/областями/публічним ключем), попередній очікуваний запит замінюється і створюється новий
|
||||
`requestId`.
|
||||
|
||||
<Note>
|
||||
Уже спарений пристрій не отримує ширший доступ непомітно. Якщо він перепідключається і просить більше областей або ширшу роль, OpenClaw залишає наявне схвалення без змін і створює новий очікуваний запит на підвищення доступу. Використовуйте `openclaw devices list`, щоб порівняти поточний схвалений доступ із новим запитаним доступом перед схваленням.
|
||||
Уже сполучений пристрій не отримує ширший доступ непомітно. Якщо він повторно підключається і просить більше областей або ширшу роль, OpenClaw залишає наявне схвалення без змін і створює новий очікуваний запит на підвищення доступу. Використовуйте `openclaw devices list`, щоб порівняти поточний схвалений доступ із новим запитаним доступом перед схваленням.
|
||||
</Note>
|
||||
|
||||
### Необов’язкове автоматичне схвалення Node за довіреним CIDR
|
||||
|
||||
Спарювання пристроїв типово залишається ручним. Для суворо контрольованих мереж Node
|
||||
Сполучення пристроїв типово залишається ручним. Для суворо контрольованих мереж Node
|
||||
можна ввімкнути автоматичне схвалення першого підключення Node з явними CIDR або точними IP:
|
||||
|
||||
```json5
|
||||
@ -140,24 +145,24 @@ openclaw devices reject <requestId>
|
||||
}
|
||||
```
|
||||
|
||||
Це застосовується лише до нових запитів спарювання `role: node` без запитаних
|
||||
областей. Клієнти operator, browser, Control UI і WebChat усе одно потребують ручного
|
||||
схвалення. Зміни ролі, області, metadata та публічного ключа також потребують ручного
|
||||
Це застосовується лише до нових запитів на сполучення `role: node` без запитаних
|
||||
областей. Клієнти Operator, браузера, Control UI та WebChat усе одно потребують ручного
|
||||
схвалення. Зміни ролі, області, метаданих і публічного ключа також потребують ручного
|
||||
схвалення.
|
||||
|
||||
### Сховище стану спарювання Node
|
||||
### Зберігання стану сполучення Node
|
||||
|
||||
Зберігається в `~/.openclaw/devices/`:
|
||||
|
||||
- `pending.json` (короткоживучий; очікувані запити спливають)
|
||||
- `paired.json` (спарені пристрої + токени)
|
||||
- `pending.json` (короткочасний; очікувані запити завершують дію)
|
||||
- `paired.json` (сполучені пристрої + токени)
|
||||
|
||||
### Примітки
|
||||
|
||||
- Застарілий API `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) є
|
||||
окремим сховищем спарювання, яким володіє Gateway. WS Node усе одно потребують спарювання пристрою.
|
||||
- Запис спарювання є довговічним джерелом істини для схвалених ролей. Активні
|
||||
токени пристрою залишаються обмеженими цим набором схвалених ролей; випадковий запис токена
|
||||
окремим сховищем сполучення, власником якого є Gateway. WS-вузли все одно потребують сполучення пристрою.
|
||||
- Запис сполучення є довговічним джерелом істини для схвалених ролей. Активні
|
||||
токени пристроїв залишаються обмеженими цим схваленим набором ролей; випадковий запис токена
|
||||
поза схваленими ролями не створює нового доступу.
|
||||
|
||||
## Пов’язані документи
|
||||
|
||||
@ -5,24 +5,24 @@ read_when:
|
||||
summary: Налаштування Webhook Synology Chat і конфігурація OpenClaw
|
||||
title: Synology Chat
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:44:53Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-29T05:57:06Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5135e9aa1fd86437a635378dfbbde321bbd2e5f6fef7a3cc740ea54ebf4b76d5
|
||||
source_hash: c3d6d7a56bd15d29de38c6ae29ae496b491c2e75df5e0a0a15410b0fbdc55a00
|
||||
source_path: channels/synology-chat.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Стан: вбудований Plugin каналу приватних повідомлень, що використовує Webhook-и Synology Chat.
|
||||
Plugin приймає вхідні повідомлення з вихідних Webhook-ів Synology Chat і надсилає відповіді
|
||||
через вхідний Webhook Synology Chat.
|
||||
Стан: вбудований Plugin каналу прямих повідомлень, що використовує webhooks Synology Chat.
|
||||
Plugin приймає вхідні повідомлення від вихідних webhooks Synology Chat і надсилає відповіді
|
||||
через вхідний webhook Synology Chat.
|
||||
|
||||
## Вбудований Plugin
|
||||
|
||||
Synology Chat постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайні
|
||||
пакетовані збірки не потребують окремого встановлення.
|
||||
Synology Chat постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні
|
||||
пакетні збірки не потребують окремого встановлення.
|
||||
|
||||
Якщо у вас старіша збірка або кастомне встановлення без Synology Chat,
|
||||
Якщо ви використовуєте старішу збірку або кастомне встановлення, яке виключає Synology Chat,
|
||||
встановіть його вручну:
|
||||
|
||||
Встановлення з локального checkout:
|
||||
@ -31,36 +31,36 @@ Synology Chat постачається як вбудований Plugin у по
|
||||
openclaw plugins install ./path/to/local/synology-chat-plugin
|
||||
```
|
||||
|
||||
Докладніше: [Plugin-и](/uk/tools/plugin)
|
||||
Докладніше: [Plugins](/uk/tools/plugin)
|
||||
|
||||
## Швидке налаштування
|
||||
|
||||
1. Переконайтеся, що Plugin Synology Chat доступний.
|
||||
- У поточних пакетованих релізах OpenClaw він уже вбудований.
|
||||
- У старіших/кастомних встановленнях його можна додати вручну з source checkout командою вище.
|
||||
- Поточні пакетні випуски OpenClaw вже включають його.
|
||||
- Старіші/кастомні встановлення можуть додати його вручну з checkout вихідного коду за допомогою команди вище.
|
||||
- `openclaw onboard` тепер показує Synology Chat у тому самому списку налаштування каналів, що й `openclaw channels add`.
|
||||
- Неінтерактивне налаштування: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
2. В інтеграціях Synology Chat:
|
||||
- Створіть вхідний Webhook і скопіюйте його URL.
|
||||
- Створіть вихідний Webhook зі своїм секретним токеном.
|
||||
3. Спрямуйте URL вихідного Webhook до вашого Gateway OpenClaw:
|
||||
- `https://gateway-host/webhook/synology` типово.
|
||||
- Створіть вхідний webhook і скопіюйте його URL.
|
||||
- Створіть вихідний webhook із вашим секретним токеном.
|
||||
3. Спрямуйте URL вихідного webhook до вашого OpenClaw gateway:
|
||||
- `https://gateway-host/webhook/synology` за замовчуванням.
|
||||
- Або ваш кастомний `channels.synology-chat.webhookPath`.
|
||||
4. Завершіть налаштування в OpenClaw.
|
||||
- Покроково: `openclaw onboard`
|
||||
- Інтерактивно: `openclaw onboard`
|
||||
- Напряму: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
|
||||
5. Перезапустіть Gateway і надішліть DM боту Synology Chat.
|
||||
5. Перезапустіть gateway і надішліть DM боту Synology Chat.
|
||||
|
||||
Деталі автентифікації Webhook:
|
||||
Деталі автентифікації webhook:
|
||||
|
||||
- OpenClaw приймає токен вихідного Webhook спочатку з `body.token`, потім
|
||||
з `?token=...`, а потім із заголовків.
|
||||
- Прийняті форми заголовків:
|
||||
- OpenClaw приймає токен вихідного webhook з `body.token`, потім
|
||||
`?token=...`, потім із заголовків.
|
||||
- Прийнятні форми заголовків:
|
||||
- `x-synology-token`
|
||||
- `x-webhook-token`
|
||||
- `x-openclaw-token`
|
||||
- `Authorization: Bearer <token>`
|
||||
- Порожні або відсутні токени закривають доступ за замовчуванням.
|
||||
- Порожні або відсутні токени закривають доступ.
|
||||
|
||||
Мінімальна конфігурація:
|
||||
|
||||
@ -83,7 +83,7 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
|
||||
|
||||
## Змінні середовища
|
||||
|
||||
Для типового акаунта можна використовувати env-змінні:
|
||||
Для типового облікового запису можна використовувати змінні середовища:
|
||||
|
||||
- `SYNOLOGY_CHAT_TOKEN`
|
||||
- `SYNOLOGY_CHAT_INCOMING_URL`
|
||||
@ -92,25 +92,25 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
|
||||
- `SYNOLOGY_RATE_LIMIT`
|
||||
- `OPENCLAW_BOT_NAME`
|
||||
|
||||
Значення конфігурації мають пріоритет над env-змінними.
|
||||
Значення конфігурації перевизначають змінні середовища.
|
||||
|
||||
`SYNOLOGY_CHAT_INCOMING_URL` не можна задавати з workspace `.env`; див. [Файли workspace `.env`](/uk/gateway/security).
|
||||
`SYNOLOGY_CHAT_INCOMING_URL` не можна встановити з workspace `.env`; див. [Файли workspace `.env`](/uk/gateway/security).
|
||||
|
||||
## Політика DM і керування доступом
|
||||
## Політика DM і контроль доступу
|
||||
|
||||
- `dmPolicy: "allowlist"` — рекомендоване типове значення.
|
||||
- `allowedUserIds` приймає список (або рядок, розділений комами) Synology user ID.
|
||||
- У режимі `allowlist` порожній список `allowedUserIds` вважається неправильною конфігурацією, і маршрут Webhook не буде запущено (використовуйте `dmPolicy: "open"` для дозволу всім).
|
||||
- `dmPolicy: "open"` дозволяє будь-якого відправника.
|
||||
- `dmPolicy: "allowlist"` є рекомендованим типовим значенням.
|
||||
- `allowedUserIds` приймає список (або рядок, розділений комами) ідентифікаторів користувачів Synology.
|
||||
- У режимі `allowlist` порожній список `allowedUserIds` вважається помилковою конфігурацією, і маршрут webhook не запуститься (використовуйте `dmPolicy: "open"` з `allowedUserIds: ["*"]` для дозволу всім).
|
||||
- `dmPolicy: "open"` дозволяє публічні DM лише коли `allowedUserIds` містить `"*"`; з обмежувальними записами спілкуватися можуть лише відповідні користувачі.
|
||||
- `dmPolicy: "disabled"` блокує DM.
|
||||
- Прив’язка отримувача відповіді типово залишається на стабільному числовому `user_id`. `channels.synology-chat.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який знову вмикає пошук за змінними username/nickname для доставки відповідей.
|
||||
- Схвалення pairing працює з:
|
||||
- Прив’язка одержувача відповіді за замовчуванням лишається на стабільному числовому `user_id`. `channels.synology-chat.dangerouslyAllowNameMatching: true` — це режим сумісності на крайній випадок, який повторно вмикає пошук за змінюваним username/nickname для доставки відповідей.
|
||||
- Схвалення сполучення працюють із:
|
||||
- `openclaw pairing list synology-chat`
|
||||
- `openclaw pairing approve synology-chat <CODE>`
|
||||
|
||||
## Вихідна доставка
|
||||
|
||||
Використовуйте числові Synology Chat user ID як цілі.
|
||||
Використовуйте числові ідентифікатори користувачів Synology Chat як цілі.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -120,19 +120,19 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te
|
||||
```
|
||||
|
||||
Надсилання медіа підтримується через доставку файлів за URL.
|
||||
URL вихідних файлів мають використовувати `http` або `https`, а приватні чи іншим чином заблоковані мережеві цілі відхиляються до того, як OpenClaw передасть URL до Webhook NAS.
|
||||
Вихідні URL файлів мають використовувати `http` або `https`, а приватні або інакше заблоковані мережеві цілі відхиляються до того, як OpenClaw передасть URL до webhook NAS.
|
||||
|
||||
## Кілька акаунтів
|
||||
## Кілька облікових записів
|
||||
|
||||
Підтримується кілька акаунтів Synology Chat у `channels.synology-chat.accounts`.
|
||||
Кожен акаунт може перевизначати токен, вхідний URL, шлях Webhook, політику DM і ліміти.
|
||||
Сесії приватних повідомлень ізольовані для кожного акаунта та користувача, тому той самий числовий `user_id`
|
||||
на двох різних акаунтах Synology не ділить спільний стан транскрипту.
|
||||
Надайте кожному ввімкненому акаунту окремий `webhookPath`. OpenClaw тепер відхиляє дубльовані точні шляхи
|
||||
і відмовляється запускати іменовані акаунти, які лише успадковують спільний шлях Webhook у конфігураціях із кількома акаунтами.
|
||||
Якщо вам навмисно потрібне застаріле успадкування для іменованого акаунта, задайте
|
||||
`dangerouslyAllowInheritedWebhookPath: true` для цього акаунта або в `channels.synology-chat`,
|
||||
але дубльовані точні шляхи все одно відхиляються із закриттям доступу за замовчуванням. Надавайте перевагу явним шляхам для кожного акаунта.
|
||||
Кілька облікових записів Synology Chat підтримуються в `channels.synology-chat.accounts`.
|
||||
Кожен обліковий запис може перевизначати токен, вхідний URL, шлях webhook, політику DM і ліміти.
|
||||
Сесії прямих повідомлень ізольовані за обліковим записом і користувачем, тому той самий числовий `user_id`
|
||||
у двох різних облікових записах Synology не спільно використовує стан transcript.
|
||||
Надайте кожному ввімкненому обліковому запису окремий `webhookPath`. OpenClaw тепер відхиляє дублікати точних шляхів
|
||||
і відмовляється запускати іменовані облікові записи, які лише успадковують спільний шлях webhook у налаштуваннях із кількома обліковими записами.
|
||||
Якщо вам навмисно потрібне застаріле успадкування для іменованого облікового запису, встановіть
|
||||
`dangerouslyAllowInheritedWebhookPath: true` для цього облікового запису або в `channels.synology-chat`,
|
||||
але дублікати точних шляхів усе одно відхиляються із закриттям доступу. Надавайте перевагу явним шляхам для кожного облікового запису.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -157,37 +157,37 @@ URL вихідних файлів мають використовувати `htt
|
||||
}
|
||||
```
|
||||
|
||||
## Примітки щодо безпеки
|
||||
## Нотатки щодо безпеки
|
||||
|
||||
- Тримайте `token` у секреті та змінюйте його, якщо він витік.
|
||||
- Залишайте `allowInsecureSsl: false`, якщо тільки ви явно не довіряєте самопідписаному локальному сертифікату NAS.
|
||||
- Вхідні запити Webhook перевіряються за токеном і обмежуються за частотою для кожного відправника.
|
||||
- Перевірки некоректного токена використовують порівняння секретів за сталий час і закривають доступ за замовчуванням.
|
||||
- Зберігайте `token` у секреті та ротуйте його в разі витоку.
|
||||
- Залишайте `allowInsecureSsl: false`, якщо ви явно не довіряєте самопідписаному локальному сертифікату NAS.
|
||||
- Вхідні запити webhook перевіряються за токеном і обмежуються за частотою для кожного відправника.
|
||||
- Перевірки недійсного токена використовують порівняння секретів зі сталим часом виконання та закривають доступ.
|
||||
- Для production надавайте перевагу `dmPolicy: "allowlist"`.
|
||||
- Тримайте `dangerouslyAllowNameMatching` вимкненим, якщо тільки вам явно не потрібна застаріла доставка відповідей за username.
|
||||
- Тримайте `dangerouslyAllowInheritedWebhookPath` вимкненим, якщо тільки ви явно не приймаєте ризик маршрутизації зі спільним шляхом у конфігурації з кількома акаунтами.
|
||||
- Тримайте `dangerouslyAllowNameMatching` вимкненим, якщо вам явно не потрібна застаріла доставка відповідей на основі username.
|
||||
- Тримайте `dangerouslyAllowInheritedWebhookPath` вимкненим, якщо ви явно не приймаєте ризик маршрутизації через спільний шлях у налаштуванні з кількома обліковими записами.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
- `Missing required fields (token, user_id, text)`:
|
||||
- у payload вихідного Webhook відсутнє одне з обов’язкових полів
|
||||
- якщо Synology надсилає токен у заголовках, переконайтеся, що gateway/проксі зберігає ці заголовки
|
||||
- у payload вихідного webhook бракує одного з обов’язкових полів
|
||||
- якщо Synology надсилає токен у заголовках, переконайтеся, що gateway/proxy зберігає ці заголовки
|
||||
- `Invalid token`:
|
||||
- секрет вихідного Webhook не збігається з `channels.synology-chat.token`
|
||||
- запит потрапляє не в той акаунт/шлях Webhook
|
||||
- reverse proxy прибрав заголовок токена до того, як запит дійшов до OpenClaw
|
||||
- секрет вихідного webhook не відповідає `channels.synology-chat.token`
|
||||
- запит потрапляє в неправильний обліковий запис/шлях webhook
|
||||
- reverse proxy видалив заголовок токена до того, як запит досяг OpenClaw
|
||||
- `Rate limit exceeded`:
|
||||
- забагато спроб із некоректним токеном з одного джерела можуть тимчасово заблокувати це джерело
|
||||
- для автентифікованих відправників також діє окремий ліміт частоти повідомлень для кожного користувача
|
||||
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`:
|
||||
- увімкнено `dmPolicy="allowlist"`, але жодного користувача не налаштовано
|
||||
- забагато спроб із недійсним токеном з одного джерела можуть тимчасово заблокувати це джерело
|
||||
- автентифіковані відправники також мають окремий ліміт повідомлень для кожного користувача
|
||||
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].`:
|
||||
- `dmPolicy="allowlist"` увімкнено, але користувачів не налаштовано
|
||||
- `User not authorized`:
|
||||
- числовий `user_id` відправника відсутній у `allowedUserIds`
|
||||
- числовий `user_id` відправника не входить до `allowedUserIds`
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд каналів](/uk/channels) — усі підтримувані канали
|
||||
- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing
|
||||
- [Групи](/uk/channels/groups) — поведінка групового чату та шлюзування за згадками
|
||||
- [Сполучення](/uk/channels/pairing) — автентифікація DM і потік сполучення
|
||||
- [Групи](/uk/channels/groups) — поведінка групового чату та gating згадок
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
|
||||
- [Безпека](/uk/gateway/security) — модель доступу та зміцнення безпеки
|
||||
- [Безпека](/uk/gateway/security) — модель доступу та посилення безпеки
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Стан підтримки Telegram-бота, можливості та конфігурація
|
||||
summary: Статус підтримки, можливості та налаштування бота Telegram
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T23:41:24Z"
|
||||
generated_at: "2026-04-29T05:56:58Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: aecd9edba56d0689a5823536a92171fa6e0c3ef56656f4699bb1e5793e248751
|
||||
source_hash: 0bf75d82f21658a1ca547b2e4ab229f7b6e47537a2379bf52bd7a18f0677664b
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Готово до production для DM ботів і груп через grammY. Long polling є режимом за замовчуванням; режим webhook необов’язковий.
|
||||
Готово для production для DM ботів і груп через grammY. Long polling є режимом за замовчуванням; режим Webhook є необов’язковим.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Створення пари" icon="link" href="/uk/channels/pairing">
|
||||
Типова політика DM для Telegram — створення пари.
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Політика DM за замовчуванням для Telegram — сполучення.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальні діагностика та сценарії відновлення.
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -30,7 +30,7 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і поспілкуйтеся з **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
|
||||
|
||||
@ -51,12 +51,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації/env, потім запустіть gateway.
|
||||
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть Gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть gateway і схваліть перший DM">
|
||||
<Step title="Запустіть Gateway і схваліть перший DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,38 +64,38 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Коди створення пари спливають через 1 годину.
|
||||
Коди сполучення спливають через 1 годину.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте бота до групи">
|
||||
Додайте бота до своєї групи, потім задайте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення конфігурації мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує облікові записи. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
</Note>
|
||||
|
||||
## Налаштування на стороні Telegram
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує, які повідомлення груп вони отримують.
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
|
||||
Якщо бот має бачити всі повідомлення групи, або:
|
||||
Якщо бот має бачити всі повідомлення групи, виконайте одне з такого:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожну групу, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дозволи групи">
|
||||
Статус адміністратора керується в налаштуваннях групи Telegram.
|
||||
|
||||
Адміністративні боти отримують усі повідомлення групи, що корисно для постійної поведінки в групі.
|
||||
Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -107,37 +107,38 @@ openclaw pairing approve telegram <CODE>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Контроль доступу та активація
|
||||
## Контроль доступу й активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
`channels.telegram.dmPolicy` керує доступом до особистих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `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:` приймаються та нормалізуються.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації.
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються й нормалізуються.
|
||||
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після злиття все ще не містить явний wildcard.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією config.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist виду `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища створення пари, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
Якщо ви оновилися й ваша config містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потребує токена бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (а не залежала від попередніх схвалень створення пари).
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу залишалася сталою в config (замість залежності від попередніх схвалень сполучення).
|
||||
|
||||
Поширене непорозуміння: схвалення створення пари для DM не означає «цей відправник авторизований усюди».
|
||||
Створення пари надає доступ до DM. Якщо власника команд ще немає, перше схвалене створення пари також задає `commands.ownerAllowFrom`, щоб команди лише для власника й схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправників у групах усе ще береться з явних allowlist у конфігурації.
|
||||
Поширена плутанина: схвалення сполучення DM не означає «цей відправник авторизований усюди».
|
||||
Сполучення надає доступ до DM. Якщо власник команд ще не існує, перше схвалене сполучення також встановлює `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
|
||||
Авторизація відправника в групі все ще походить з явних allowlist у config.
|
||||
Якщо ви хочете «я авторизований один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніше (без стороннього бота):
|
||||
|
||||
1. Надішліть DM своєму боту.
|
||||
1. Напишіть DM своєму боту.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
@ -155,27 +156,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Два елементи керування застосовуються разом:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає конфігурації `groups`:
|
||||
- немає config `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні 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`.
|
||||
Нечислові записи ігноруються для авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища створення пари DM.
|
||||
Створення пари лишається лише для DM. Для груп задайте `groupAllowFrom` або per-group/per-topic `allowFrom`.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища створення пари.
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень DM.
|
||||
Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до config `allowFrom`, а не до сховища сполучень.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed із `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
Приклад: дозволити будь-якому учаснику в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -192,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи:
|
||||
Приклад: дозволити лише конкретних користувачів в одній конкретній групі:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -212,9 +213,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram.
|
||||
|
||||
- Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом.
|
||||
- Розміщуйте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Розміщуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом.
|
||||
|
||||
</Warning>
|
||||
|
||||
@ -230,14 +231,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Перемикачі команд на рівні сесії:
|
||||
Перемикачі команд рівня сесії:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте конфігурацію.
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте config.
|
||||
|
||||
Приклад сталої конфігурації:
|
||||
Приклад сталої config:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -253,42 +254,42 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Як отримати ID групового чату:
|
||||
|
||||
- перешліть повідомлення групи до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перегляньте Bot API `getUpdates`
|
||||
- переслати повідомлення групи до `@userinfobot` / `@getidsbot`
|
||||
- або прочитати `chat.id` з `openclaw logs --follow`
|
||||
- або переглянути Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Поведінка runtime
|
||||
|
||||
- Telegram належить процесу gateway.
|
||||
- Telegram належить процесу Gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний envelope каналу з метаданими відповіді та placeholders для медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми лишалися ізольованими.
|
||||
- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає ID thread для відповідей.
|
||||
- Long polling використовує grammY runner із послідовністю per-chat/per-thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищений всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, ймовірно, інший gateway OpenClaw, script або зовнішній poller використовує той самий токен.
|
||||
- Перезапуски watchdog для long-polling за замовчуванням запускаються після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення per-account.
|
||||
- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується).
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholder для медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми залишалися ізольованими.
|
||||
- DM повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із thread-aware ключами сесій і зберігає ID thread для відповідей.
|
||||
- Long polling використовує grammY runner з послідовністю на рівні чату/thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищений усередині кожного процесу Gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший OpenClaw Gateway, script або зовнішній poller, імовірно, використовує той самий токен.
|
||||
- Перезапуски watchdog для long-polling за замовчуванням запускаються після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення на рівні облікового запису.
|
||||
- Telegram Bot API не підтримує read-receipt (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
OpenClaw може stream часткові відповіді в реальному часі:
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` дорівнює `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` відображається в `partial` у Telegram (сумісність із міжканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли preview streaming активний)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
- `channels.telegram.streaming` є `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли preview streaming активний)
|
||||
- застарілі значення `channels.telegram.streamMode` і boolean `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення плану або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і новіших. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Оновлення попереднього перегляду tool-progress — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб залишити відредагований попередній перегляд для тексту відповіді, але приховати рядки tool-progress, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -305,41 +306,41 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише коли хочете доставку тільки фінальної відповіді: редагування попереднього перегляду Telegram вимкнені, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремих повідомлень «Працюємо...». Запити на схвалення, media payloads і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховуючи рядки статусу прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише коли хочете доставку тільки фінального повідомлення: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу пригнічуються замість надсилання окремими повідомленнями "Working...". Запити на схвалення, media payloads і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете залишити лише редагування попереднього перегляду відповіді, приховавши рядки статусу tool-progress.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
|
||||
- короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима часова мітка Telegram відображає час завершення, а не час створення попереднього перегляду
|
||||
- короткі попередні перегляди в DM/групі/топіку: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тому видима позначка часу в Telegram відображає час завершення, а не час створення попереднього перегляду
|
||||
|
||||
Для складних відповідей (наприклад медіа-payload) OpenClaw повертається до звичайної остаточної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, медіанавантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
|
||||
Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
Потокове передавання попереднього перегляду відокремлене від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
|
||||
|
||||
Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
|
||||
|
||||
Потік міркувань лише для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерування
|
||||
- остаточна відповідь надсилається без тексту міркувань
|
||||
- `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерації
|
||||
- фінальна відповідь надсилається без тексту міркувань
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний варіант HTML">
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Markdown-подібний текст рендериться у безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Текст, подібний до Markdown, рендериться в безпечний для Telegram HTML.
|
||||
- Сирий HTML від моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередні перегляди посилань увімкнено за замовчуванням; їх можна вимкнути через `channels.telegram.linkPreview: false`.
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
Реєстрація меню команд Telegram обробляється під час запуску за допомогою `setMyCommands`.
|
||||
|
||||
Стандартні параметри нативних команд:
|
||||
Типові значення нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
@ -360,40 +361,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- імена нормалізуються (прибирається початковий `/`, переводяться в нижній регістр)
|
||||
- імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й логуються
|
||||
- конфлікти/дублікати пропускаються й записуються в журнал
|
||||
|
||||
Примітки:
|
||||
|
||||
- користувацькі команди є лише пунктами меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
- користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди або команди Plugin можуть усе ще реєструватися, якщо налаштовані.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо це налаштовано.
|
||||
|
||||
Типові збої налаштування:
|
||||
Поширені помилки налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще перевищило ліміт після обрізання; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Збій `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
|
||||
- `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тому це не повідомляється як збій очищення Webhook.
|
||||
- `setMyCommands failed` з мережевими помилками або помилками fetch зазвичай означає, що вихідні DNS/HTTPS до `api.telegram.org` заблоковані.
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, тоді як прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
|
||||
- `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 <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один очікуваний запит
|
||||
- `/pair approve`, коли є лише один запит, що очікує
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування переносить короткоживучий bootstrap-токен. Вбудована bootstrap-передача залишає основний токен Node на `scopes: []`; будь-який переданий токен оператора лишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap-областей дії мають префікс ролі, тому цей список дозволеного оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області дії під власним префіксом ролі.
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей доступу bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролі, що не є операторськими, усе ще потребують областей доступу під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад роль/області дії/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, роль/області доступу/публічний ключ), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
@ -442,7 +443,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
|
||||
|
||||
Приклад дії з повідомленням:
|
||||
Приклад дії повідомлення:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -465,36 +466,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дії з повідомленнями Telegram для агентів і автоматизації">
|
||||
<Accordion title="Дії повідомлень Telegram для агентів і автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, optional `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Параметри обмеження:
|
||||
Елементи керування доступом:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнено за замовчуванням, і вони не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного розв’язання SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги потоків відповідей">
|
||||
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги гілкування відповідей">
|
||||
Telegram підтримує явні теги гілкування відповідей у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, яке запустило обробку
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що запустило обробку
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ідентифікатор повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
|
||||
@ -502,29 +503,29 @@ curl "https://api.telegram.org/bot<bot_token>/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_*]]` усе ще враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму та поведінка гілок">
|
||||
<Accordion title="Топіки форуму та поведінка гілок">
|
||||
Форумні супергрупи:
|
||||
|
||||
- ключі сеансів тем додають `:topic:<threadId>`
|
||||
- відповіді й індикатор набору спрямовуються в гілку теми
|
||||
- шлях конфігурації теми:
|
||||
- ключі сесій топіків додають `:topic:<threadId>`
|
||||
- відповіді й індикатор набору спрямовуються в гілку топіка
|
||||
- шлях конфігурації топіка:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
Особливий випадок загального топіка (`threadId=1`):
|
||||
|
||||
- під час надсилання повідомлень опускається `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору все одно включають `message_thread_id`
|
||||
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору тексту все ще включають `message_thread_id`
|
||||
|
||||
Наслідування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` застосовується лише на рівні теми й не успадковується зі стандартних параметрів групи.
|
||||
Успадкування топіків: записи топіків успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` застосовується лише до топіка й не успадковується з типових значень групи.
|
||||
|
||||
**Маршрутизація агентів за темами**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сеанс. Приклад:
|
||||
**Маршрутизація агентів для кожного топіка**: кожен топік може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації топіка. Це дає кожному топіку власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -544,28 +545,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Після цього кожна тема має власний ключ сеансу: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Тоді кожен топік має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійне прив’язування тем ACP**: Теми форуму можуть закріплювати сеанси обв’язки ACP через типізовані прив’язування ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форумів у групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
**Постійна прив’язка ACP-топіка**: форумні топіки можуть закріплювати сесії стенда ACP через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором топіка, як-от `-1001234567890:topic:42`). Наразі область дії обмежена форумними топіками в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
|
||||
**Запуск ACP із чату, прив’язаний до гілки**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нового сеансу ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
**Прив’язаний до гілки запуск ACP із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточний топік до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в топіку. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сеансів, обізнані про гілки.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням гілок.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Аудіо, відео та стікери">
|
||||
### Аудіоповідомлення
|
||||
|
||||
Telegram розрізняє голосові повідомлення та аудіофайли.
|
||||
Telegram розрізняє голосові нотатки та аудіофайли.
|
||||
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення
|
||||
- транскрипти вхідних голосових повідомлень оформлюються в контексті агента як машинно згенерований,
|
||||
недовірений текст; виявлення згадок усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення, обмежені згадками, продовжують працювати.
|
||||
- тег `[[audio_as_voice]]` у відповіді агента для примусового надсилання як голосової нотатки
|
||||
- транскрипти вхідних голосових нотаток оформлюються як машинно згенерований,
|
||||
ненадійний текст у контексті агента; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тому voice-повідомлення з доступом через згадку продовжують працювати.
|
||||
|
||||
Приклад дії з повідомленням:
|
||||
Приклад дії повідомлення:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -581,7 +582,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Telegram розрізняє відеофайли та відеонотатки.
|
||||
|
||||
Приклад дії з повідомленням:
|
||||
Приклад дії повідомлення:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -599,9 +600,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Обробка вхідних стікерів:
|
||||
|
||||
- статичні WEBP: завантажуються й обробляються (placeholder `<media:sticker>`)
|
||||
- анімовані TGS: пропускаються
|
||||
- відео WEBM: пропускаються
|
||||
- статичний WEBP: завантажується й обробляється (заповнювач `<media:sticker>`)
|
||||
- анімований TGS: пропускається
|
||||
- відео WEBM: пропускається
|
||||
|
||||
Поля контексту стікера:
|
||||
|
||||
@ -615,9 +616,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів візуального аналізу.
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision.
|
||||
|
||||
Увімкніть дії зі стікерами:
|
||||
Увімкнути дії зі стікерами:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -656,7 +657,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень).
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від навантажень повідомлень).
|
||||
|
||||
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
@ -669,17 +670,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (наскільки можливо через кеш надісланих повідомлень).
|
||||
- `own` означає лише реакції користувача на повідомлення, надіслані ботом (у міру можливостей через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно дотримуються контролів доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори тредів в оновленнях реакцій.
|
||||
- групи без форуму спрямовуються до сесії групового чату
|
||||
- форумні групи спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- Telegram не надає ідентифікатори потоків в оновленнях реакцій.
|
||||
- групи без форуму спрямовуються до сеансу групового чату
|
||||
- форумні групи спрямовуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включає `message_reaction`.
|
||||
`allowed_updates` для polling/webhook автоматично містить `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підтверджувальні реакції">
|
||||
<Accordion title="Реакції підтвердження">
|
||||
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
@ -697,12 +698,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Записи конфігурації з подій і команд Telegram">
|
||||
Записи конфігурації каналу ввімкнені за замовчуванням (`configWrites !== false`).
|
||||
Записи конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`).
|
||||
|
||||
Записи, ініційовані Telegram, включають:
|
||||
|
||||
- події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потребує ввімкнення команд)
|
||||
- події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потребує ввімкнення команди)
|
||||
|
||||
Вимкнення:
|
||||
|
||||
@ -721,26 +722,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Long polling проти webhook">
|
||||
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes для кожного чату/теми, що й long polling, тому повільні ходи агента не затримують delivery ACK Telegram.
|
||||
Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло, перш ніж повернути `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/теми, що використовуються long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження, повторні спроби та цілі CLI">
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `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` вимикає.
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий.
|
||||
- allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зупинку polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає.
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається як отримано.
|
||||
- allowlist Telegram переважно обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Елементи керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Конфігурація `channels.telegram.retry` застосовується до helper-ів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API.
|
||||
- конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ідентифікатором чату або іменем користувача:
|
||||
|
||||
@ -769,8 +770,8 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
Надсилання Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа
|
||||
|
||||
Обмеження дій:
|
||||
|
||||
@ -780,36 +781,36 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підтвердження exec у Telegram">
|
||||
Telegram підтримує підтвердження exec у DM затверджувачів і може необов’язково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ідентифікаторами користувачів Telegram.
|
||||
Telegram підтримує підтвердження exec у DM підтверджувачів і може за бажанням публікувати запити у вихідному чаті або темі. Підтверджувачі мають бути числовими ідентифікаторами користувачів Telegram.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (резервно використовує числові ідентифікатори власників з `commands.ownerAllowFrom`)
|
||||
- `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`, коли власника команд ще немає, тому налаштування з одним власником усе одно працює без дублювання ідентифікаторів у `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може спілкуватися з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось підтверджувачем exec. Перше схвалене DM-сполучення ініціалізує `commands.ownerAllowFrom`, коли власника команд ще немає, тому налаштування з одним власником і далі працює без дублювання ID у `execApprovals.approvers`.
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту підтвердження та подальшої відповіді. Термін дії підтверджень exec за замовчуванням спливає через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту підтвердження та подальшої відповіді. Підтвердження exec типово спливають через 30 хвилин.
|
||||
|
||||
Inline-кнопки підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Ідентифікатори підтверджень із префіксом `plugin:` визначаються через підтвердження Plugin; інші спершу визначаються через підтвердження exec.
|
||||
Кнопки вбудованого підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` обробляються через підтвердження plugin; інші спершу обробляються через підтвердження exec.
|
||||
|
||||
Див. [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Керування відповідями на помилки
|
||||
## Керування відповідями про помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації:
|
||||
Коли агент стикається з помилкою доставки або провайдера, 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` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилок під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для облікового запису, групи та теми (таке саме успадкування, як і для інших ключів конфігурації Telegram).
|
||||
Підтримуються перевизначення для окремих облікових записів, груп і тем (з таким самим успадкуванням, як в інших ключів конфігурації Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -832,48 +833,48 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
<AccordionGroup>
|
||||
<Accordion title="Бот не відповідає на групові повідомлення без згадки">
|
||||
|
||||
- Якщо `requireMention=false`, режим privacy Telegram має дозволяти повну видимість.
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і повторно додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ідентифікатори груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- швидкий тест сесії: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот узагалі не бачить групові повідомлення">
|
||||
|
||||
- коли існує `channels.telegram.groups`, групу має бути вказано (або включено `"*"`)
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте логи: `openclaw logs --follow` для причин пропуску
|
||||
- перегляньте журнали: `openclaw logs --follow` щодо причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або зовсім не працюють">
|
||||
|
||||
- авторизуйте свою ідентичність відправника (pairing та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість команд Plugin/Skills/custom або вимкніть native menu
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
- авторизуйте ідентичність свого відправника (сполучення та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи має значення `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню забагато записів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` із помилками network/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований токен">
|
||||
|
||||
- `getMe returned 401` — це помилка автентифікації Telegram для налаштованого токена бота.
|
||||
- Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є помилкою автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий токен до пізніших викликів API.
|
||||
- `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота.
|
||||
- Заново скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
|
||||
- `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий токен до пізніших викликів API.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
<Accordion title="Нестабільність опитування або мережі">
|
||||
|
||||
- Node 22+ + custom fetch/proxy може спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу визначають `api.telegram.org` як IPv6; зламаний IPv6 egress може спричиняти періодичні збої Telegram API.
|
||||
- Якщо логи містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки.
|
||||
- Якщо логи містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки liveness long-poll за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим egress/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ + користувацький fetch/proxy може спричинити негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу перетворюють `api.telegram.org` на IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої API Telegram.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування й перебудовує транспорт Telegram після 120 секунд без завершеного long-poll liveness за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через polling-stall. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики API Telegram через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -881,8 +882,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост — WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір family:
|
||||
- Node 22+ типово використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост є WSL2 або явно працює краще з поведінкою лише IPv4, примусово задайте вибір family:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -891,11 +892,11 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді діапазону benchmark RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
- Відповіді з benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
прозорий proxy переписує `api.telegram.org` на іншу
|
||||
приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете явно
|
||||
ввімкнути обхід лише для Telegram:
|
||||
transparent proxy переписує `api.telegram.org` на іншу
|
||||
приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете
|
||||
увімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -904,19 +905,19 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Такий самий opt-in доступний для кожного облікового запису за шляхом
|
||||
- Таке саме явне ввімкнення доступне для кожного облікового запису за адресою
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy визначає медіахости Telegram як `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон
|
||||
benchmark RFC 2544 за замовчуванням.
|
||||
- Якщо ваш proxy перетворює хости медіа Telegram на `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон
|
||||
RFC 2544 за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист
|
||||
медіа Telegram від SSRF. Використовуйте його лише для довірених проксі-середовищ,
|
||||
контрольованих оператором, як-от Clash, Mihomo або fake-IP маршрутизація Surge,
|
||||
коли вони синтезують приватні або спеціального призначення відповіді поза
|
||||
діапазоном бенчмарків RFC 2544. Залишайте його вимкненим для звичайного
|
||||
доступу Telegram через публічний інтернет.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram
|
||||
від SSRF. Використовуйте це лише в довірених проксі-середовищах під контролем
|
||||
оператора, як-от Clash, Mihomo або маршрутизація fake-IP Surge, коли вони
|
||||
синтезують приватні або спеціального використання відповіді поза діапазоном
|
||||
тестування RFC 2544. Для звичайного публічного доступу Telegram через інтернет
|
||||
залишайте це вимкненим.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення середовища (тимчасові):
|
||||
@ -939,18 +940,18 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Важливі поля Telegram">
|
||||
<Accordion title="Високосигнальні поля Telegram">
|
||||
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символьні посилання відхиляються)
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`)
|
||||
- схвалення exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- підтвердження виконання: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- потоки/відповіді: `replyToMode`
|
||||
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставлення: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- власний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot<TOKEN>`)
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
- помилки: `errorPolicy`, `errorCooldownMs`
|
||||
@ -959,23 +960,23 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, установіть `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
Пріоритет кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає про це. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Сполучіть користувача Telegram із Gateway.
|
||||
Сполучіть користувача Telegram із gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка списку дозволених груп і тем.
|
||||
</Card>
|
||||
<Card title="Маршрутизація каналів" icon="route" href="/uk/channels/channel-routing">
|
||||
Маршрутизуйте вхідні повідомлення агентам.
|
||||
Маршрутизуйте вхідні повідомлення до агентів.
|
||||
</Card>
|
||||
<Card title="Безпека" icon="shield" href="/uk/gateway/security">
|
||||
Модель загроз і зміцнення захисту.
|
||||
Модель загроз і посилення захисту.
|
||||
</Card>
|
||||
<Card title="Маршрутизація кількох агентів" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставляйте групи й теми з агентами.
|
||||
|
||||
545
docs/uk/ci.md
545
docs/uk/ci.md
File diff suppressed because one or more lines are too long
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Локальний запуск pnpm openclaw qa matrix
|
||||
- Запуск pnpm openclaw qa matrix локально
|
||||
- Додавання або вибір QA-сценаріїв Matrix
|
||||
- Тріаж збоїв Matrix QA, тайм-аутів або завислого очищення
|
||||
summary: 'Довідник для супровідників щодо живої QA-доріжки Matrix на базі Docker: CLI, профілі, змінні середовища, сценарії та вихідні артефакти.'
|
||||
title: QA Matrix
|
||||
summary: 'Довідник для супровідників щодо live-лінії QA Matrix на базі Docker: CLI, профілі, змінні середовища, сценарії та вихідні артефакти.'
|
||||
title: Матричне QA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:09:51Z"
|
||||
generated_at: "2026-04-29T05:57:16Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6282e8a65fb5af46a67f8240d5a9ce095e614b6cc68621745ffe79cf88a5131f
|
||||
source_hash: 6ab862474e2abe45a1dcd66f025e3a3dd52a3417b0c1f42a26cd7944dd4053f5
|
||||
source_path: concepts/qa-matrix.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Лейн Matrix QA запускає вбудований `@openclaw/matrix` plugin проти одноразового homeserver Tuwunel у Docker, з тимчасовими обліковими записами driver, SUT і observer, а також підготовленими кімнатами. Це покриття Matrix із реальним live-транспортом.
|
||||
Лінія QA Matrix запускає вбудований Plugin `@openclaw/matrix` із одноразовим homeserver Tuwunel у Docker, з тимчасовими обліковими записами driver, SUT і observer та попередньо заповненими кімнатами. Це живе покриття Matrix із реальним транспортом.
|
||||
|
||||
Це інструментарій лише для мейнтейнерів. Пакетовані релізи OpenClaw навмисно не містять `qa-lab`, тому `openclaw qa` доступний лише з checkout вихідного коду. Checkout вихідного коду завантажує вбудований runner напряму — крок встановлення plugin не потрібен.
|
||||
Це інструменти лише для супровідників. Пакетовані релізи OpenClaw навмисно не містять `qa-lab`, тому `openclaw qa` доступний лише з checkout вихідного коду. Checkout вихідного коду завантажує вбудований засіб запуску напряму — крок встановлення Plugin не потрібен.
|
||||
|
||||
Ширший контекст QA framework див. в [огляді QA](/uk/concepts/qa-e2e-automation).
|
||||
Ширший контекст фреймворку QA див. в [огляді QA](/uk/concepts/qa-e2e-automation).
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -26,16 +26,16 @@ x-i18n:
|
||||
pnpm openclaw qa matrix --profile fast --fail-fast
|
||||
```
|
||||
|
||||
Звичайний `pnpm openclaw qa matrix` запускає `--profile all` і не зупиняється після першої помилки. Використовуйте `--profile fast --fail-fast` для release gate; розділяйте каталог на шарди за допомогою `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli`, коли запускаєте повний inventory паралельно.
|
||||
Звичайний `pnpm openclaw qa matrix` запускає `--profile all` і не зупиняється після першої помилки. Використовуйте `--profile fast --fail-fast` для релізного gate; розбийте каталог на шарди за допомогою `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli`, коли запускаєте весь інвентар паралельно.
|
||||
|
||||
## Що робить лейн
|
||||
## Що робить лінія
|
||||
|
||||
1. Створює одноразовий homeserver Tuwunel у Docker (стандартний образ `ghcr.io/matrix-construct/tuwunel:v1.5.1`, ім’я сервера `matrix-qa.test`, порт `28008`).
|
||||
2. Реєструє трьох тимчасових користувачів — `driver` (надсилає вхідний трафік), `sut` (обліковий запис OpenClaw Matrix, що тестується), `observer` (перехоплення трафіку третьої сторони).
|
||||
3. Готує кімнати, потрібні вибраним сценаріям (основну, для threading, media, restart, secondary, allowlist, E2EE, verification DM тощо).
|
||||
4. Запускає дочірній OpenClaw gateway зі справжнім Matrix plugin, обмеженим обліковим записом SUT; `qa-channel` не завантажується в дочірньому процесі.
|
||||
5. Виконує сценарії послідовно, спостерігаючи події через Matrix clients driver/observer.
|
||||
6. Зупиняє homeserver, записує artifacts зі звітом і підсумком, потім завершує роботу.
|
||||
1. Готує одноразовий homeserver Tuwunel у Docker (образ за замовчуванням `ghcr.io/matrix-construct/tuwunel:v1.5.1`, ім’я сервера `matrix-qa.test`, порт `28008`).
|
||||
2. Реєструє трьох тимчасових користувачів — `driver` (надсилає вхідний трафік), `sut` (обліковий запис OpenClaw Matrix, що тестується), `observer` (захоплення стороннього трафіку).
|
||||
3. Заповнює кімнати, потрібні для вибраних сценаріїв (main, threading, media, restart, secondary, allowlist, E2EE, verification DM тощо).
|
||||
4. Запускає дочірній Gateway OpenClaw зі справжнім Matrix Plugin, обмеженим обліковим записом SUT; `qa-channel` у дочірньому процесі не завантажується.
|
||||
5. Виконує сценарії послідовно, спостерігаючи події через Matrix-клієнти driver/observer.
|
||||
6. Зупиняє homeserver, записує артефакти звіту й підсумку, потім завершує роботу.
|
||||
|
||||
## CLI
|
||||
|
||||
@ -45,101 +45,102 @@ pnpm openclaw qa matrix [options]
|
||||
|
||||
### Поширені прапорці
|
||||
|
||||
| Прапорець | Стандартно | Опис |
|
||||
| --------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--profile <profile>` | `all` | Профіль сценаріїв. Див. [Профілі](#profiles). |
|
||||
| `--fail-fast` | off | Зупинитися після першої невдалої перевірки або сценарію. |
|
||||
| `--scenario <id>` | — | Запустити лише цей сценарій. Можна повторювати. Див. [Сценарії](#scenarios). |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | Куди записуються звіти, підсумок, спостережені події та output log. Відносні шляхи обчислюються відносно `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального робочого каталогу. |
|
||||
| `--sut-account <id>` | `sut` | Ідентифікатор облікового запису Matrix у конфігурації QA gateway. |
|
||||
| Прапорець | За замовчуванням | Опис |
|
||||
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `--profile <profile>` | `all` | Профіль сценаріїв. Див. [Профілі](#profiles). |
|
||||
| `--fail-fast` | вимкнено | Зупинитися після першої невдалої перевірки або сценарію. |
|
||||
| `--scenario <id>` | — | Запустити лише цей сценарій. Можна повторювати. Див. [Сценарії](#scenarios). |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | Куди записуються звіти, підсумок, спостережені події та журнал виводу. Відносні шляхи визначаються відносно `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального робочого каталогу. |
|
||||
| `--sut-account <id>` | `sut` | Ідентифікатор облікового запису Matrix у конфігурації QA Gateway. |
|
||||
|
||||
### Прапорці провайдера
|
||||
|
||||
Лейн використовує справжній транспорт Matrix, але model provider можна налаштувати:
|
||||
Лінія використовує справжній транспорт Matrix, але провайдера моделі можна налаштувати:
|
||||
|
||||
| Прапорець | Стандартно | Опис |
|
||||
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` для deterministic mock dispatch або `live-frontier` для live frontier providers. Legacy alias `live-openai` досі працює. |
|
||||
| `--model <ref>` | provider default | Основний ref `provider/model`. |
|
||||
| `--alt-model <ref>` | provider default | Альтернативний ref `provider/model`, коли сценарії перемикаються посеред виконання. |
|
||||
| `--fast` | off | Увімкнути fast mode провайдера, де це підтримується. |
|
||||
| Прапорець | За замовчуванням | Опис |
|
||||
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` для детермінованої mock-диспетчеризації або `live-frontier` для живих передових провайдерів. Застарілий alias `live-openai` досі працює. |
|
||||
| `--model <ref>` | стандарт провайдера | Основне посилання `provider/model`. |
|
||||
| `--alt-model <ref>` | стандарт провайдера | Альтернативне посилання `provider/model`, коли сценарії перемикаються посеред виконання. |
|
||||
| `--fast` | вимкнено | Увімкнути швидкий режим провайдера, де він підтримується. |
|
||||
|
||||
Matrix QA не приймає `--credential-source` або `--credential-role`. Лейн створює одноразових користувачів локально; спільного credential pool для lease немає.
|
||||
Matrix QA не приймає `--credential-source` або `--credential-role`. Лінія локально створює одноразових користувачів; немає спільного пулу облікових даних, з якого можна брати lease.
|
||||
|
||||
## Профілі
|
||||
|
||||
Вибраний профіль визначає, які сценарії запускатимуться.
|
||||
Вибраний профіль визначає, які сценарії виконуються.
|
||||
|
||||
| Профіль | Для чого використовувати |
|
||||
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `all` (default) | Повний каталог. Повільний, але вичерпний. |
|
||||
| `fast` | Підмножина для release gate, яка перевіряє live transport contract: canary, mention gating, allowlist block, reply shape, restart resume, thread follow-up, thread isolation, reaction observation і delivery metadata для exec approval. |
|
||||
| `transport` | Сценарії transport-level threading, DM, room, autojoin, mention/allowlist, approval і reaction. |
|
||||
| `media` | Покриття вкладень image, audio, video, PDF, EPUB. |
|
||||
| `e2ee-smoke` | Мінімальне покриття E2EE — базова зашифрована відповідь, thread follow-up, успішний bootstrap. |
|
||||
| `e2ee-deep` | Вичерпні сценарії E2EE для state-loss, backup, key і recovery. |
|
||||
| `e2ee-cli` | CLI-сценарії `openclaw matrix encryption setup` і `verify *`, керовані через QA harness. |
|
||||
| Профіль | Для чого використовувати |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `all` (default) | Повний каталог. Повільний, але вичерпний. |
|
||||
| `fast` | Підмножина для релізного gate, що перевіряє контракт живого транспорту: canary, mention gating, allowlist block, reply shape, restart resume, thread follow-up, thread isolation, reaction observation і доставку метаданих exec approval. |
|
||||
| `transport` | Сценарії потоків, DM, кімнат, autojoin, mention/allowlist, approval і реакцій на рівні транспорту. |
|
||||
| `media` | Покриття вкладень із зображеннями, аудіо, відео, PDF, EPUB. |
|
||||
| `e2ee-smoke` | Мінімальне покриття E2EE — базова зашифрована відповідь, thread follow-up, успішний bootstrap. |
|
||||
| `e2ee-deep` | Вичерпні сценарії E2EE для втрати стану, backup, ключів і відновлення. |
|
||||
| `e2ee-cli` | Сценарії CLI `openclaw matrix encryption setup` і `verify *`, що виконуються через QA harness. |
|
||||
|
||||
Точне зіставлення міститься в `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`.
|
||||
|
||||
## Сценарії
|
||||
|
||||
Повний список ідентифікаторів сценаріїв — це union `MatrixQaScenarioId` у `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15`. Категорії охоплюють:
|
||||
Повний список ідентифікаторів сценаріїв — це union `MatrixQaScenarioId` у `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15`. Категорії включають:
|
||||
|
||||
- threading — `matrix-thread-*`, `matrix-subagent-thread-spawn`
|
||||
- top-level / DM / room — `matrix-top-level-reply-shape`, `matrix-room-*`, `matrix-dm-*`
|
||||
- streaming і tool progress — `matrix-room-partial-streaming-preview`, `matrix-room-quiet-streaming-preview`, `matrix-room-tool-progress-*`, `matrix-room-block-streaming`
|
||||
- media — `matrix-media-type-coverage`, `matrix-room-image-understanding-attachment`, `matrix-attachment-only-ignored`, `matrix-unsupported-media-safe`
|
||||
- routing — `matrix-room-autojoin-invite`, `matrix-secondary-room-*`
|
||||
- reactions — `matrix-reaction-*`
|
||||
- approvals — `matrix-approval-*` (exec/plugin metadata, chunked fallback, deny reactions, threads і routing `target: "both"`)
|
||||
- потоки — `matrix-thread-*`, `matrix-subagent-thread-spawn`
|
||||
- верхній рівень / DM / кімната — `matrix-top-level-reply-shape`, `matrix-room-*`, `matrix-dm-*`
|
||||
- streaming і прогрес інструментів — `matrix-room-partial-streaming-preview`, `matrix-room-quiet-streaming-preview`, `matrix-room-tool-progress-*`, `matrix-room-block-streaming`
|
||||
- медіа — `matrix-media-type-coverage`, `matrix-room-image-understanding-attachment`, `matrix-attachment-only-ignored`, `matrix-unsupported-media-safe`
|
||||
- маршрутизація — `matrix-room-autojoin-invite`, `matrix-secondary-room-*`
|
||||
- реакції — `matrix-reaction-*`
|
||||
- approvals — `matrix-approval-*` (метадані exec/Plugin, chunked fallback, реакції deny, потоки та маршрутизація `target: "both"`)
|
||||
- restart і replay — `matrix-restart-*`, `matrix-stale-sync-replay-dedupe`, `matrix-room-membership-loss`, `matrix-homeserver-restart-resume`, `matrix-initial-catchup-then-incremental`
|
||||
- mention gating, bot-to-bot і allowlists — `matrix-mention-*`, `matrix-allowbots-*`, `matrix-allowlist-*`, `matrix-multi-actor-ordering`, `matrix-inbound-edit-*`, `matrix-mxid-prefixed-command-block`, `matrix-observer-allowlist-override`
|
||||
- E2EE — `matrix-e2ee-*` (basic reply, thread follow-up, bootstrap, recovery key lifecycle, state-loss variants, server backup behavior, device hygiene, SAS / QR / DM verification, restart, artifact redaction)
|
||||
- E2EE CLI — `matrix-e2ee-cli-*` (encryption setup, idempotent setup, bootstrap failure, recovery-key lifecycle, multi-account, gateway-reply round-trip, self-verification)
|
||||
- E2EE — `matrix-e2ee-*` (базова відповідь, thread follow-up, bootstrap, життєвий цикл recovery key, варіанти втрати стану, поведінка server backup, гігієна пристроїв, перевірка SAS / QR / DM, restart, редагування артефактів)
|
||||
- E2EE CLI — `matrix-e2ee-cli-*` (налаштування шифрування, ідемпотентне налаштування, помилка bootstrap, життєвий цикл recovery-key, кілька облікових записів, round-trip gateway-reply, self-verification)
|
||||
|
||||
Передайте `--scenario <id>` (можна повторювати), щоб запустити вручну вибраний набір; поєднуйте з `--profile all`, щоб ігнорувати profile gating.
|
||||
Передайте `--scenario <id>` (можна повторювати), щоб запустити вручну вибраний набір; поєднуйте з `--profile all`, щоб ігнорувати фільтрацію профілю.
|
||||
|
||||
## Змінні середовища
|
||||
|
||||
| Змінна | Стандартно | Ефект |
|
||||
| Змінна | Типове значення | Ефект |
|
||||
| --------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000` (30 хв) | Жорстка верхня межа для всього запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | Quiet window для негативних no-reply assertions. Обмежується до `≤` timeout запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Обмеження для Docker teardown. Failure surfaces містять recovery-команду `docker compose ... down --remove-orphans`. |
|
||||
| `OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS` | `45000` | Межа для початкової canary-відповіді. Release CI збільшує її на спільних раннерах, щоб повільний перший хід gateway не завершувався помилкою до початку покриття сценаріїв. |
|
||||
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | Тихе вікно для негативних тверджень про відсутність відповіді. Обмежується до `≤` таймауту запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Межа для демонтажу Docker. Поверхні помилок містять команду відновлення `docker compose ... down --remove-orphans`. |
|
||||
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | Перевизначає образ homeserver під час перевірки з іншою версією Tuwunel. |
|
||||
| `OPENCLAW_QA_MATRIX_PROGRESS` | on | `0` вимикає progress lines `[matrix-qa] ...` у stderr. `1` примусово вмикає їх. |
|
||||
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | redacted | `1` зберігає message body і `formatted_body` у `matrix-qa-observed-events.json`. Типово дані редагуються, щоб CI artifacts залишалися безпечними. |
|
||||
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | off | `1` пропускає deterministic `process.exit` після запису artifacts. Типово вихід примусовий, бо native crypto handles matrix-js-sdk можуть утримувати event loop живим після завершення artifacts. |
|
||||
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | unset | Коли встановлено зовнішнім launcher (наприклад, `scripts/run-node.mjs`), Matrix QA повторно використовує цей шлях log замість запуску власного tee. |
|
||||
| `OPENCLAW_QA_MATRIX_PROGRESS` | увімкнено | `0` вимикає рядки прогресу `[matrix-qa] ...` у stderr. `1` примусово вмикає їх. |
|
||||
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | відредаговано | `1` зберігає тіло повідомлення та `formatted_body` у `matrix-qa-observed-events.json`. Типово редагує їх, щоб CI-артефакти залишалися безпечними. |
|
||||
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | вимкнено | `1` пропускає детермінований `process.exit` після запису артефакту. Типово вихід примусовий, бо нативні crypto-дескриптори matrix-js-sdk можуть тримати цикл подій активним після завершення артефакту. |
|
||||
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | не задано | Коли задано зовнішнім запускачем (наприклад, `scripts/run-node.mjs`), Matrix QA повторно використовує цей шлях журналу замість запуску власного tee. |
|
||||
|
||||
## Output artifacts
|
||||
## Вихідні артефакти
|
||||
|
||||
Записуються до `--output-dir`:
|
||||
|
||||
- `matrix-qa-report.md` — звіт протоколу у Markdown (що пройшло, не пройшло, було пропущено і чому).
|
||||
- `matrix-qa-summary.json` — структурований підсумок, придатний для парсингу в CI та панелей моніторингу.
|
||||
- `matrix-qa-observed-events.json` — спостережені події Matrix від клієнтів драйвера й спостерігача. Тіла редагуються, якщо не встановлено `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`; метадані затвердження узагальнюються з вибраними безпечними полями та скороченим попереднім переглядом команди.
|
||||
- `matrix-qa-output.log` — об’єднані stdout/stderr із запуску. Якщо встановлено `OPENCLAW_RUN_NODE_OUTPUT_LOG`, натомість повторно використовується журнал зовнішнього запускача.
|
||||
- `matrix-qa-report.md` — протокольний звіт Markdown (що пройшло, не пройшло, було пропущено і чому).
|
||||
- `matrix-qa-summary.json` — структурований підсумок, придатний для парсингу CI та панелей моніторингу.
|
||||
- `matrix-qa-observed-events.json` — спостережені події Matrix від клієнтів драйвера й observer. Тіла редагуються, якщо не задано `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`; метадані схвалення підсумовуються з вибраними безпечними полями та скороченим попереднім переглядом команди.
|
||||
- `matrix-qa-output.log` — об’єднані stdout/stderr із запуску. Якщо задано `OPENCLAW_RUN_NODE_OUTPUT_LOG`, натомість повторно використовується журнал зовнішнього запускника.
|
||||
|
||||
Типовий каталог виводу — `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`, тому послідовні запуски не перезаписують один одного.
|
||||
Типова директорія виводу — `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`, тому послідовні запуски не перезаписують один одного.
|
||||
|
||||
## Поради з тріажу
|
||||
|
||||
- **Запуск зависає ближче до кінця:** нативні криптографічні дескриптори `matrix-js-sdk` можуть пережити harness. Типова поведінка примусово виконує чистий `process.exit` після запису артефактів; якщо ви скасували `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`, очікуйте, що процес залишатиметься активним.
|
||||
- **Помилка очищення:** знайдіть надруковану команду відновлення (виклик `docker compose ... down --remove-orphans`) і запустіть її вручну, щоб звільнити порт homeserver.
|
||||
- **Нестабільні вікна негативних тверджень у CI:** зменште `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` (типово 8 с), коли CI швидкий; збільште його на повільних спільних runner-ах.
|
||||
- **Потрібні відредаговані тіла для звіту про ваду:** перезапустіть із `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` і додайте `matrix-qa-observed-events.json`. Вважайте отриманий артефакт чутливим.
|
||||
- **Запуск зависає ближче до кінця:** нативні crypto-дескриптори `matrix-js-sdk` можуть пережити harness. Типово після запису артефакту примусово виконується чистий `process.exit`; якщо ви прибрали `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`, очікуйте, що процес затримається.
|
||||
- **Помилка очищення:** знайдіть надруковану команду відновлення (виклик `docker compose ... down --remove-orphans`) і виконайте її вручну, щоб звільнити порт homeserver.
|
||||
- **Нестабільні вікна негативних тверджень у CI:** зменште `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` (типово 8 с), коли CI швидкий; збільште його на повільних спільних раннерах.
|
||||
- **Потрібні відредаговані тіла для звіту про помилку:** повторіть запуск із `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` і додайте `matrix-qa-observed-events.json`. Вважайте отриманий артефакт чутливим.
|
||||
- **Інша версія Tuwunel:** спрямуйте `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` на версію, що тестується. Lane перевіряє лише закріплений типовий образ.
|
||||
|
||||
## Контракт live-транспорту
|
||||
## Контракт живого транспорту
|
||||
|
||||
Matrix — один із трьох lane live-транспорту (Matrix, Telegram, Discord), які спільно використовують єдиний контрольний список контракту, визначений у [огляді QA → Покриття live-транспорту](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` залишається широким синтетичним набором і навмисно не є частиною цієї матриці.
|
||||
Matrix — один із трьох live transport lanes (Matrix, Telegram, Discord), що спільно використовують єдиний контрольний список контракту, визначений у [огляді QA → покриття живого транспорту](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` залишається широким синтетичним набором і навмисно не є частиною цієї матриці.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд QA](/uk/concepts/qa-e2e-automation) — загальний стек QA та контракт live-транспорту
|
||||
- [Канал QA](/uk/channels/qa-channel) — синтетичний адаптер каналу для сценаріїв, підтримуваних репозиторієм
|
||||
- [Огляд QA](/uk/concepts/qa-e2e-automation) — загальний стек QA і контракт живого транспорту
|
||||
- [QA Channel](/uk/channels/qa-channel) — синтетичний адаптер каналу для сценаріїв, підтримуваних репозиторієм
|
||||
- [Тестування](/uk/help/testing) — запуск тестів і додавання покриття QA
|
||||
- [Matrix](/uk/channels/matrix) — плагін каналу, що тестується
|
||||
- [Matrix](/uk/channels/matrix) — Plugin каналу, що тестується
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user