chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
56833b9ae9
commit
349b828bb8
@ -4,15 +4,15 @@ read_when:
|
||||
summary: Підтримка каналу WhatsApp, керування доступом, поведінка доставки та операції
|
||||
title: WhatsApp
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T03:02:53Z"
|
||||
generated_at: "2026-04-26T04:44:00Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 120033548f60a39619952e908bd4925dc7da5f8baaa4406ed455aa46010fbb2e
|
||||
source_hash: 300a8c7ff5768a8da869a4052c01639e7763550adceb40dabc908be44602f352
|
||||
source_path: channels/whatsapp.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Статус: готово до production через WhatsApp Web (Baileys). Gateway керує пов’язаними сесіями.
|
||||
Статус: готовий до production через WhatsApp Web (Baileys). Gateway керує прив’язаними сеансами.
|
||||
|
||||
## Встановлення (за потреби)
|
||||
|
||||
@ -20,7 +20,7 @@ x-i18n:
|
||||
буде запропоновано встановити Plugin WhatsApp, коли ви вперше його виберете.
|
||||
- `openclaw channels login --channel whatsapp` також пропонує процес встановлення, якщо
|
||||
Plugin ще не встановлено.
|
||||
- Канал dev + checkout з git: за замовчуванням використовується локальний шлях Plugin.
|
||||
- Канал dev + git checkout: за замовчуванням використовується локальний шлях Plugin.
|
||||
- Stable/Beta: за замовчуванням використовується npm-пакет `@openclaw/whatsapp`.
|
||||
|
||||
Ручне встановлення також доступне:
|
||||
@ -31,10 +31,10 @@ openclaw plugins install @openclaw/whatsapp
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Політика DM за замовчуванням для невідомих відправників — сполучення.
|
||||
Стандартна політика DM — сполучення для невідомих відправників.
|
||||
</Card>
|
||||
<Card title="Усунення проблем каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
<Card title="Усунення несправностей каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Діагностика між каналами та сценарії відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналу.
|
||||
@ -61,7 +61,7 @@ openclaw plugins install @openclaw/whatsapp
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Під’єднайте WhatsApp (QR)">
|
||||
<Step title="Прив’яжіть WhatsApp (QR)">
|
||||
|
||||
```bash
|
||||
openclaw channels login --channel whatsapp
|
||||
@ -73,7 +73,7 @@ openclaw channels login --channel whatsapp
|
||||
openclaw channels login --channel whatsapp --account work
|
||||
```
|
||||
|
||||
Щоб під’єднати наявний/власний каталог автентифікації WhatsApp Web перед входом:
|
||||
Щоб підключити наявний/власний каталог автентифікації WhatsApp Web перед входом:
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
|
||||
@ -97,24 +97,24 @@ openclaw pairing list whatsapp
|
||||
openclaw pairing approve whatsapp <CODE>
|
||||
```
|
||||
|
||||
Термін дії запитів на сполучення спливає через 1 годину. Кількість очікуваних запитів обмежена до 3 на канал.
|
||||
Термін дії запитів на сполучення спливає через 1 годину. Кількість запитів у стані очікування обмежена 3 на канал.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
OpenClaw рекомендує, коли це можливо, запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого варіанта, але сценарії з особистим номером також підтримуються.)
|
||||
OpenClaw рекомендує, коли це можливо, запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого сценарію, але конфігурації з особистим номером також підтримуються.)
|
||||
</Note>
|
||||
|
||||
## Шаблони розгортання
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Окремий номер (рекомендовано)">
|
||||
<Accordion title="Виділений номер (рекомендовано)">
|
||||
Це найчистіший операційний режим:
|
||||
|
||||
- окрема ідентичність WhatsApp для OpenClaw
|
||||
- чіткіші allowlist для DM і межі маршрутизації
|
||||
- нижча ймовірність плутанини із самочатом
|
||||
- чіткіші списки дозволів DM і межі маршрутизації
|
||||
- менша ймовірність плутанини із самочатом
|
||||
|
||||
Мінімальний шаблон політики:
|
||||
|
||||
@ -132,39 +132,40 @@ OpenClaw рекомендує, коли це можливо, запускати
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Резервний варіант з особистим номером">
|
||||
Онбординг підтримує режим особистого номера та записує базову конфігурацію, дружню до самочату:
|
||||
Онбординг підтримує режим особистого номера та записує базову конфігурацію, зручну для самочату:
|
||||
|
||||
- `dmPolicy: "allowlist"`
|
||||
- `allowFrom` містить ваш особистий номер
|
||||
- `selfChatMode: true`
|
||||
|
||||
Під час роботи захист самочату спирається на прив’язаний власний номер і `allowFrom`.
|
||||
Під час виконання захисти самочату спираються на прив’язаний власний номер і `allowFrom`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження каналу лише WhatsApp Web">
|
||||
Канал платформи обміну повідомленнями в поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`).
|
||||
<Accordion title="Обсяг каналу лише для WhatsApp Web">
|
||||
Канал платформи повідомлень у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`).
|
||||
|
||||
Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі chat-channel немає.
|
||||
Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі чат-каналів немає.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Модель виконання
|
||||
|
||||
- Gateway керує сокетом WhatsApp і циклом повторного підключення.
|
||||
- Для вихідного надсилання потрібен активний слухач WhatsApp для цільового облікового запису.
|
||||
- Gateway керує сокетом WhatsApp і циклом перепідключення.
|
||||
- Для вихідних відправлень потрібен активний слухач WhatsApp для цільового облікового запису.
|
||||
- Чати статусів і розсилок ігноруються (`@status`, `@broadcast`).
|
||||
- Прямі чати використовують правила DM-сесій (`session.dmScope`; значення за замовчуванням `main` зводить DM до основної сесії агента).
|
||||
- Групові сесії ізольовані (`agent:<agentId>:whatsapp:group:<jid>`).
|
||||
- Транспорт WhatsApp Web враховує стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації проксі на рівні хоста, а не специфічним для каналу налаштуванням проксі WhatsApp.
|
||||
- Прямі чати використовують правила сеансів DM (`session.dmScope`; значення `main` за замовчуванням зводить DM до основного сеансу агента).
|
||||
- Групові сеанси ізольовані (`agent:<agentId>:whatsapp:group:<jid>`).
|
||||
- Транспорт WhatsApp Web підтримує стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Віддавайте перевагу проксі, налаштованому на рівні хоста, а не специфічним налаштуванням проксі WhatsApp для каналу.
|
||||
- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає реакцію підтвердження WhatsApp після доставки видимої відповіді.
|
||||
|
||||
## Хуки Plugin і конфіденційність
|
||||
## Хуки Plugin і приватність
|
||||
|
||||
Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів,
|
||||
ідентифікатори груп, імена відправників і поля кореляції сесій. З цієї причини
|
||||
WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
без вашої явної згоди:
|
||||
ідентифікатори груп, імена відправників і поля кореляції сеансів. З цієї причини
|
||||
WhatsApp не транслює корисне навантаження вхідного хука `message_received` Plugin
|
||||
, якщо ви явно не ввімкнете це:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -178,7 +179,7 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
}
|
||||
```
|
||||
|
||||
Ви можете обмежити цю згоду одним обліковим записом:
|
||||
Ви можете обмежити це ввімкнення одним обліковим записом:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -196,8 +197,8 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
}
|
||||
```
|
||||
|
||||
Вмикайте це лише для тих Plugin, яким ви довіряєте отримання вхідного вмісту
|
||||
повідомлень WhatsApp та ідентифікаторів.
|
||||
Вмикайте це лише для тих Plugin, яким ви довіряєте отримання вхідного вмісту повідомлень WhatsApp
|
||||
та ідентифікаторів.
|
||||
|
||||
## Керування доступом і активація
|
||||
|
||||
@ -212,57 +213,57 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
|
||||
`allowFrom` приймає номери у стилі E.164 (внутрішньо нормалізуються).
|
||||
|
||||
Багатооблікове перевизначення: `channels.whatsapp.accounts.<id>.dmPolicy` (і `allowFrom`) мають пріоритет над значеннями за замовчуванням на рівні каналу для цього облікового запису.
|
||||
Перевизначення для кількох облікових записів: `channels.whatsapp.accounts.<id>.dmPolicy` (і `allowFrom`) мають пріоритет над значеннями канального рівня за замовчуванням для цього облікового запису.
|
||||
|
||||
Деталі поведінки під час виконання:
|
||||
Подробиці поведінки під час виконання:
|
||||
|
||||
- сполучення зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom`
|
||||
- якщо allowlist не налаштовано, прив’язаний власний номер дозволяється за замовчуванням
|
||||
- OpenClaw ніколи не виконує автоматичне сполучення для вихідних `fromMe` DM (повідомлень, які ви надсилаєте собі з прив’язаного пристрою)
|
||||
- сполучення зберігаються в канальному сховищі дозволів і об’єднуються з налаштованим `allowFrom`
|
||||
- якщо список дозволів не налаштовано, прив’язаний власний номер дозволяється за замовчуванням
|
||||
- OpenClaw ніколи не виконує автоматичне сполучення вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з прив’язаного пристрою)
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Групова політика + allowlist">
|
||||
<Tab title="Групова політика + списки дозволів">
|
||||
Доступ до груп має два рівні:
|
||||
|
||||
1. **Allowlist членства в групі** (`channels.whatsapp.groups`)
|
||||
- якщо `groups` не вказано, допустимими є всі групи
|
||||
- якщо `groups` присутній, він працює як allowlist груп (`"*"` дозволено)
|
||||
1. **Список дозволів членства в групі** (`channels.whatsapp.groups`)
|
||||
- якщо `groups` пропущено, усі групи є допустимими
|
||||
- якщо `groups` присутній, він діє як список дозволів груп (`"*"` дозволено)
|
||||
|
||||
2. **Політика відправників групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
|
||||
- `open`: allowlist відправників обходиться
|
||||
- `open`: список дозволів відправників обходиться
|
||||
- `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`)
|
||||
- `disabled`: блокувати всі вхідні групові повідомлення
|
||||
|
||||
Резервне значення allowlist відправників:
|
||||
Резервна поведінка списку дозволів відправників:
|
||||
|
||||
- якщо `groupAllowFrom` не задано, під час виконання використовується `allowFrom`, якщо він доступний
|
||||
- allowlist відправників оцінюються до активації за згадкою/відповіддю
|
||||
- списки дозволів відправників оцінюються до активації за згадкою/відповіддю
|
||||
|
||||
Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика під час виконання — `allowlist` (із попередженням у журналі), навіть якщо встановлено `channels.defaults.groupPolicy`.
|
||||
Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика під час виконання — `allowlist` (із попереджувальним записом у журналі), навіть якщо задано `channels.defaults.groupPolicy`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Згадки + /activation">
|
||||
За замовчуванням для групових відповідей потрібна згадка.
|
||||
Групові відповіді за замовчуванням потребують згадки.
|
||||
|
||||
Визначення згадок включає:
|
||||
|
||||
- явні згадки ідентичності бота у WhatsApp
|
||||
- налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервне значення `messages.groupChat.mentionPatterns`)
|
||||
- неявне визначення відповіді боту (відправник відповіді збігається з ідентичністю бота)
|
||||
- явні згадки бот-ідентичності в WhatsApp
|
||||
- налаштовані шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`)
|
||||
- неявне виявлення відповіді боту (відправник відповіді збігається з ідентичністю бота)
|
||||
|
||||
Примітка щодо безпеки:
|
||||
|
||||
- цитата/відповідь лише задовольняє перевірку згадки; вона **не** надає авторизацію відправнику
|
||||
- з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача з allowlist
|
||||
- цитування/відповідь лише задовольняє вимогу згадки; це **не** надає авторизацію відправнику
|
||||
- за `groupPolicy: "allowlist"` відправники, яких немає у списку дозволів, усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача зі списку дозволів
|
||||
|
||||
Команда активації на рівні сесії:
|
||||
Команда активації на рівні сеансу:
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
`activation` оновлює стан сесії (а не глобальну конфігурацію). Вона обмежена власником.
|
||||
`activation` оновлює стан сеансу (а не глобальну конфігурацію). Вона обмежена власником.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -271,15 +272,15 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
|
||||
Коли прив’язаний власний номер також присутній у `allowFrom`, активуються запобіжники самочату WhatsApp:
|
||||
|
||||
- пропускати read receipts для ходів самочату
|
||||
- ігнорувати поведінку автоматичного тригера mention-JID, яка інакше сповіщала б вас самих
|
||||
- якщо `messages.responsePrefix` не задано, відповіді самочату за замовчуванням мають формат `[{identity.name}]` або `[openclaw]`
|
||||
- пропускати сповіщення про прочитання для ходів самочату
|
||||
- ігнорувати поведінку автозапуску mention-JID, яка інакше пінгувала б вас самих
|
||||
- якщо `messages.responsePrefix` не задано, відповіді самочату за замовчуванням мають вигляд `[{identity.name}]` або `[openclaw]`
|
||||
|
||||
## Нормалізація повідомлень і контекст
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вхідний envelope + контекст відповіді">
|
||||
Вхідні повідомлення WhatsApp загортаються у спільний вхідний envelope.
|
||||
<Accordion title="Вхідний конверт + контекст відповіді">
|
||||
Вхідні повідомлення WhatsApp обгортаються у спільний вхідний конверт.
|
||||
|
||||
Якщо існує цитована відповідь, контекст додається в такому вигляді:
|
||||
|
||||
@ -289,12 +290,12 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
[/Replying]
|
||||
```
|
||||
|
||||
Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
|
||||
Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Заповнювачі медіа та витягування location/contact">
|
||||
Вхідні повідомлення лише з медіа нормалізуються за допомогою таких заповнювачів:
|
||||
Вхідні повідомлення лише з медіа нормалізуються із заповнювачами, наприклад:
|
||||
|
||||
- `<media:image>`
|
||||
- `<media:video>`
|
||||
@ -302,12 +303,12 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
- `<media:document>`
|
||||
- `<media:sticker>`
|
||||
|
||||
Тіла location використовують стислий текст координат. Мітки/коментарі location і дані contact/vCard відображаються як fenced недовірені метадані, а не як вбудований текст prompt.
|
||||
Вміст location використовує стислий текст координат. Мітки/коментарі location та дані contact/vCard відображаються як огороджені ненадійні метадані, а не як вбудований текст prompt.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ін’єкція історії очікування групи">
|
||||
Для груп необроблені повідомлення можуть буферизуватися та ін’єктуватися як контекст, коли бот нарешті спрацьовує.
|
||||
Для груп необроблені повідомлення можуть буферизуватися та ін’єктуватися як контекст, коли бота нарешті буде активовано.
|
||||
|
||||
- ліміт за замовчуванням: `50`
|
||||
- конфігурація: `channels.whatsapp.historyLimit`
|
||||
@ -316,13 +317,13 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
|
||||
Маркери ін’єкції:
|
||||
|
||||
- `[Повідомлення чату з вашої останньої відповіді — для контексту]`
|
||||
- `[Поточне повідомлення — дайте відповідь на нього]`
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Read receipts">
|
||||
Read receipts увімкнено за замовчуванням для прийнятих вхідних повідомлень WhatsApp.
|
||||
<Accordion title="Сповіщення про прочитання">
|
||||
Сповіщення про прочитання увімкнено за замовчуванням для прийнятих вхідних повідомлень WhatsApp.
|
||||
|
||||
Вимкнути глобально:
|
||||
|
||||
@ -352,53 +353,53 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin
|
||||
}
|
||||
```
|
||||
|
||||
Для ходів самочату read receipts пропускаються навіть коли вони глобально увімкнені.
|
||||
Для ходів самочату сповіщення про прочитання пропускаються, навіть коли вони глобально ввімкнені.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Доставка, розбиття на частини та медіа
|
||||
## Доставка, поділ на частини та медіа
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Розбиття тексту на частини">
|
||||
<Accordion title="Поділ тексту на частини">
|
||||
- ліміт частини за замовчуванням: `channels.whatsapp.textChunkLimit = 4000`
|
||||
- `channels.whatsapp.chunkMode = "length" | "newline"`
|
||||
- режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного розбиття за довжиною
|
||||
- режим `newline` віддає перевагу межам абзаців (порожнім рядкам), а потім переходить до безпечного за довжиною поділу на частини
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка вихідних медіа">
|
||||
- підтримуються payload зображень, відео, аудіо (голосове повідомлення PTT) і документів
|
||||
- аудіомедіа надсилається через payload `audio` Baileys з `ptt: true`, тому клієнти WhatsApp відображають його як голосове повідомлення push-to-talk
|
||||
- payload відповідей зберігають `audioAsVoice`; вихід голосових повідомлень TTS для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM
|
||||
- рідне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими повідомленнями
|
||||
- аудіо не у форматі Ogg, включно з виходом TTS MP3/WebM від Microsoft Edge, транскодується за допомогою `ffmpeg` у 48 кГц моно Ogg/Opus перед доставкою PTT
|
||||
- `/tts latest` надсилає останню відповідь асистента як одне голосове повідомлення й пригнічує повторне надсилання для тієї самої відповіді; `/tts chat on|off|default` керує автоматичним TTS для поточного чату WhatsApp
|
||||
- підтримується відтворення анімованих GIF через `gifPlayback: true` під час надсилання відео
|
||||
- captions застосовуються до першого елемента медіа під час надсилання payload відповіді з кількома медіа, за винятком того, що голосові повідомлення PTT надсилають аудіо спочатку, а видимий текст окремо, оскільки клієнти WhatsApp не завжди коректно відображають captions голосових повідомлень
|
||||
- джерелом медіа можуть бути HTTP(S), `file://` або локальні шляхи
|
||||
- підтримуються корисні навантаження image, video, audio (PTT voice-note) і document
|
||||
- аудіомедіа надсилаються через корисне навантаження Baileys `audio` з `ptt: true`, тож клієнти WhatsApp відображають їх як голосову нотатку push-to-talk
|
||||
- корисні навантаження відповіді зберігають `audioAsVoice`; вихід TTS voice-note для WhatsApp лишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM
|
||||
- нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з voice-note
|
||||
- аудіо не у форматі Ogg, включно з виходом Microsoft Edge TTS у форматах MP3/WebM, транскодується за допомогою `ffmpeg` у 48 кГц моно Ogg/Opus перед доставкою PTT
|
||||
- `/tts latest` надсилає останню відповідь асистента як одну voice-note і пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує авто-TTS для поточного чату WhatsApp
|
||||
- анімоване відтворення GIF підтримується через `gifPlayback: true` під час надсилання video
|
||||
- підписи застосовуються до першого медіаелемента під час надсилання корисних навантажень відповіді з кількома медіа, за винятком PTT voice-note, де аудіо надсилається першим, а видимий текст окремо, тому що клієнти WhatsApp не відображають підписи voice-note послідовно
|
||||
- джерелом медіа може бути HTTP(S), `file://` або локальні шляхи
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження розміру медіа та резервна поведінка">
|
||||
- обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`)
|
||||
- обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`)
|
||||
- перевизначення для облікових записів використовують `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (підбір розміру/якості), щоб відповідати обмеженням
|
||||
- якщо надсилання медіа не вдається, резервний механізм для першого елемента надсилає текстове попередження замість тихого пропуску відповіді
|
||||
- перевизначення для облікового запису використовують `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб вкладатися в обмеження
|
||||
- у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість того, щоб мовчки відкинути відповідь
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Цитування відповідей
|
||||
|
||||
WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді візуально цитують вхідне повідомлення. Керуйте цим за допомогою `channels.whatsapp.replyToMode`.
|
||||
WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Це керується через `channels.whatsapp.replyToMode`.
|
||||
|
||||
| Значення | Поведінка |
|
||||
| ----------- | --------------------------------------------------------------------- |
|
||||
| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення |
|
||||
| `"first"` | Цитувати лише перший фрагмент вихідної відповіді |
|
||||
| `"all"` | Цитувати кожен фрагмент вихідної відповіді |
|
||||
| `"batched"` | Цитувати відкладені пакетні відповіді, залишаючи негайні без цитування |
|
||||
| `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування |
|
||||
|
||||
Значення за замовчуванням — `"off"`. Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts.<id>.replyToMode`.
|
||||
За замовчуванням — `"off"`. Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts.<id>.replyToMode`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -412,14 +413,14 @@ WhatsApp підтримує нативне цитування відповіде
|
||||
|
||||
## Рівень реакцій
|
||||
|
||||
`channels.whatsapp.reactionLevel` визначає, наскільки широко агент використовує emoji-реакції у WhatsApp:
|
||||
`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції у WhatsApp:
|
||||
|
||||
| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис |
|
||||
| ------------ | ----------- | ---------------------------- | ------------------------------------------------- |
|
||||
| `"off"` | Ні | Ні | Жодних реакцій |
|
||||
| `"ack"` | Так | Ні | Лише ack-реакції (підтвердження до відповіді) |
|
||||
| `"minimal"` | Так | Так (обережно) | Ack + реакції агента з консервативними вказівками |
|
||||
| `"extensive"`| Так | Так (заохочується) | Ack + реакції агента із заохочувальними вказівками |
|
||||
| Рівень | Реакції підтвердження | Реакції, ініційовані агентом | Опис |
|
||||
| ------------ | --------------------- | ---------------------------- | ------------------------------------------------ |
|
||||
| `"off"` | Ні | Ні | Жодних реакцій |
|
||||
| `"ack"` | Так | Ні | Лише реакції підтвердження (підтвердження до відповіді) |
|
||||
| `"minimal"` | Так | Так (обережно) | Підтвердження + реакції агента з обережними настановами |
|
||||
| `"extensive"`| Так | Так (заохочується) | Підтвердження + реакції агента із заохочувальними настановами |
|
||||
|
||||
За замовчуванням: `"minimal"`.
|
||||
|
||||
@ -437,8 +438,8 @@ WhatsApp підтримує нативне цитування відповіде
|
||||
|
||||
## Реакції підтвердження
|
||||
|
||||
WhatsApp підтримує негайні ack-реакції після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
|
||||
Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`.
|
||||
WhatsApp підтримує негайні реакції підтвердження після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
|
||||
Реакції підтвердження обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -457,8 +458,8 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- надсилаються негайно після прийняття вхідного повідомлення (до відповіді)
|
||||
- збої журналюються, але не блокують звичайну доставку відповіді
|
||||
- груповий режим `mentions` реагує на ходи, активовані згадкою; групова активація `always` обходить цю перевірку
|
||||
- збої записуються в журнал, але не блокують звичайну доставку відповіді
|
||||
- у груповому режимі `mentions` реакція ставиться на ходах, активованих згадкою; групова активація `always` діє як обхід цієї перевірки
|
||||
- WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується)
|
||||
|
||||
## Кілька облікових записів і облікові дані
|
||||
@ -470,10 +471,10 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
- ідентифікатори облікових записів внутрішньо нормалізуються для пошуку
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Шляхи до облікових даних і сумісність зі застарілими варіантами">
|
||||
<Accordion title="Шляхи облікових даних і сумісність зі застарілими версіями">
|
||||
- поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- резервний файл: `creds.json.bak`
|
||||
- застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` усе ще розпізнається/мігрується для потоків з обліковим записом за замовчуванням
|
||||
- застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` усе ще розпізнається/мігрується для сценаріїв з обліковим записом за замовчуванням
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка виходу">
|
||||
@ -484,19 +485,19 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Інструменти, дії та запис конфігурації
|
||||
## Інструменти, дії та записи конфігурації
|
||||
|
||||
- Підтримка інструментів агента включає дію реакції WhatsApp (`react`).
|
||||
- Обмеження дій:
|
||||
- `channels.whatsapp.actions.reactions`
|
||||
- `channels.whatsapp.actions.polls`
|
||||
- Запис конфігурації, ініційований каналом, увімкнено за замовчуванням (вимикається через `channels.whatsapp.configWrites=false`).
|
||||
- Записи конфігурації, ініційовані каналом, увімкнені за замовчуванням (вимикаються через `channels.whatsapp.configWrites=false`).
|
||||
|
||||
## Усунення проблем
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Не під’єднано (потрібен QR)">
|
||||
Симптом: статус каналу повідомляє, що під’єднання немає.
|
||||
<Accordion title="Не прив’язано (потрібен QR)">
|
||||
Симптом: статус каналу показує, що прив’язку не виконано.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -507,8 +508,8 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Під’єднано, але відключено / цикл повторного підключення">
|
||||
Симптом: під’єднаний обліковий запис із повторними відключеннями або спробами повторного підключення.
|
||||
<Accordion title="Прив’язано, але від’єднано / цикл перепідключення">
|
||||
Симптом: прив’язаний обліковий запис із повторними від’єднаннями або спробами перепідключення.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -517,30 +518,30 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
За потреби повторно під’єднайте через `channels login`.
|
||||
За потреби виконайте повторну прив’язку через `channels login`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Немає активного слухача під час надсилання">
|
||||
Вихідне надсилання швидко завершується помилкою, якщо для цільового облікового запису немає активного слухача Gateway.
|
||||
Вихідні надсилання швидко завершуються помилкою, якщо для цільового облікового запису немає активного слухача Gateway.
|
||||
|
||||
Переконайтеся, що Gateway запущено і обліковий запис під’єднано.
|
||||
Переконайтеся, що Gateway запущено і обліковий запис прив’язано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Групові повідомлення несподівано ігноруються">
|
||||
<Accordion title="Групові повідомлення неочікувано ігноруються">
|
||||
Перевіряйте в такому порядку:
|
||||
|
||||
- `groupPolicy`
|
||||
- `groupAllowFrom` / `allowFrom`
|
||||
- записи allowlist у `groups`
|
||||
- обмеження згадками (`requireMention` + шаблони згадок)
|
||||
- дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` на кожну область
|
||||
- записи списку дозволів `groups`
|
||||
- обмеження за згадкою (`requireMention` + шаблони згадок)
|
||||
- дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` для кожної області
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Попередження про runtime Bun">
|
||||
Runtime Gateway для WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи Gateway WhatsApp/Telegram.
|
||||
<Accordion title="Попередження runtime Bun">
|
||||
Runtime Gateway для WhatsApp має використовувати Node. Bun позначається як несумісний для стабільної роботи Gateway WhatsApp/Telegram.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -550,28 +551,28 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
|
||||
Ієрархія визначення для групових повідомлень:
|
||||
|
||||
Спочатку визначається ефективна мапа `groups`: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Пошук prompt потім виконується за єдиною отриманою мапою:
|
||||
Ефективна мапа `groups` визначається спочатку: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується по отриманій єдиній мапі:
|
||||
|
||||
1. **Системний prompt для конкретної групи** (`groups["<groupId>"].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** у ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
1. **Системний prompt для конкретної групи** (`groups["<groupId>"].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** в ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для груп** (`groups["*"].systemPrompt`): використовується, коли запис конкретної групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
|
||||
Ієрархія визначення для прямих повідомлень:
|
||||
|
||||
Спочатку визначається ефективна мапа `direct`: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Пошук prompt потім виконується за єдиною отриманою мапою:
|
||||
Ефективна мапа `direct` визначається спочатку: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується по отриманій єдиній мапі:
|
||||
|
||||
1. **Системний prompt для конкретного direct-чату** (`direct["<peerId>"].systemPrompt`): використовується, коли запис конкретного peer існує в мапі **і** у ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для direct-чатів** (`direct["*"].systemPrompt`): використовується, коли запис конкретного peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
1. **Системний prompt для конкретного прямого чату** (`direct["<peerId>"].systemPrompt`): використовується, коли запис конкретного peer існує в мапі **і** в ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для прямих чатів** (`direct["*"].systemPrompt`): використовується, коли запис конкретного peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
|
||||
Примітка: `dms` залишається полегшеним контейнером перевизначення історії для окремих DM (`dms.<id>.historyLimit`); перевизначення prompt містяться у `direct`.
|
||||
Примітка: `dms` залишається легковаговим контейнером перевизначення історії для окремих DM (`dms.<id>.historyLimit`); перевизначення prompt розміщуються в `direct`.
|
||||
|
||||
**Відмінність від поведінки Telegram з кількома обліковими записами:** У Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, які не визначають власний `groups` — щоб бот не отримував групові повідомлення для груп, до яких він не належить. У WhatsApp цей запобіжник не застосовується: кореневі `groups` і `direct` завжди успадковуються обліковими записами, які не мають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні prompt для груп або direct-чатів на рівні окремого облікового запису, явно визначайте повну мапу під кожним обліковим записом, а не покладайтеся на значення за замовчуванням на кореневому рівні.
|
||||
**Відмінність від поведінки Telegram з кількома обліковими записами:** У Telegram коренева `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, які не визначають власну `groups`, — щоб бот не отримував групові повідомлення для груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від того, скільки облікових записів налаштовано. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні prompt для груп або прямих чатів на рівні окремого облікового запису, явно визначайте повну мапу під кожним обліковим записом, а не покладайтеся на кореневі значення за замовчуванням.
|
||||
|
||||
Важлива поведінка:
|
||||
|
||||
- `channels.whatsapp.groups` — це і мапа конфігурації окремих груп, і allowlist груп на рівні чату. На кореневому рівні або на рівні облікового запису `groups["*"]` означає «усі групи допущені» для цієї області.
|
||||
- Додавайте wildcard `systemPrompt` для груп лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб допустимим був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` як значення prompt за замовчуванням. Натомість повторіть prompt у кожному явно дозволеному записі групи.
|
||||
- Допуск груп і авторизація відправників — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників і далі окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
|
||||
- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає конфігурацію direct-чату за замовчуванням після того, як DM уже допущено через `dmPolicy` разом із `allowFrom` або правилами pairing-store.
|
||||
- `channels.whatsapp.groups` — це і мапа конфігурації для окремих груп, і список дозволів груп на рівні чату. На кореневому рівні або на рівні облікового запису `groups["*"]` означає «для цієї області дозволені всі групи».
|
||||
- Додавайте wildcard `systemPrompt` для груп лише тоді, коли ви вже хочете, щоб ця область дозволяла всі групи. Якщо ви все ще хочете, щоб допустимим був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` як значення prompt за замовчуванням. Натомість повторіть prompt у кожному явно дозволеному записі групи.
|
||||
- Допуск груп і авторизація відправників — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але саме по собі не авторизує кожного відправника в цих групах. Доступ відправників усе ще окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
|
||||
- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає конфігурацію прямого чату за замовчуванням після того, як DM уже було допущено через `dmPolicy` разом із правилами `allowFrom` або сховища pairing.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -580,31 +581,31 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: {
|
||||
// Use only if all groups should be admitted at the root scope.
|
||||
// Applies to all accounts that do not define their own groups map.
|
||||
"*": { systemPrompt: "Default prompt for all groups." },
|
||||
// Використовуйте лише якщо на кореневому рівні мають бути дозволені всі групи.
|
||||
// Застосовується до всіх облікових записів, які не визначають власну мапу groups.
|
||||
"*": { systemPrompt: "Стандартний prompt для всіх груп." },
|
||||
},
|
||||
direct: {
|
||||
// Applies to all accounts that do not define their own direct map.
|
||||
"*": { systemPrompt: "Default prompt for all direct chats." },
|
||||
// Застосовується до всіх облікових записів, які не визначають власну мапу direct.
|
||||
"*": { systemPrompt: "Стандартний prompt для всіх прямих чатів." },
|
||||
},
|
||||
accounts: {
|
||||
work: {
|
||||
groups: {
|
||||
// This account defines its own groups, so root groups are fully
|
||||
// replaced. To keep a wildcard, define "*" explicitly here too.
|
||||
// Цей обліковий запис визначає власну groups, тому коренева groups
|
||||
// повністю замінюється. Щоб зберегти wildcard, явно визначте тут і "*".
|
||||
"120363406415684625@g.us": {
|
||||
requireMention: false,
|
||||
systemPrompt: "Focus on project management.",
|
||||
systemPrompt: "Зосередьтеся на управлінні проєктами.",
|
||||
},
|
||||
// Use only if all groups should be admitted in this account.
|
||||
"*": { systemPrompt: "Default prompt for work groups." },
|
||||
// Використовуйте лише якщо в цьому обліковому записі мають бути дозволені всі групи.
|
||||
"*": { systemPrompt: "Стандартний prompt для робочих груп." },
|
||||
},
|
||||
direct: {
|
||||
// This account defines its own direct map, so root direct entries are
|
||||
// fully replaced. To keep a wildcard, define "*" explicitly here too.
|
||||
"+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
|
||||
"*": { systemPrompt: "Default prompt for work direct chats." },
|
||||
// Цей обліковий запис визначає власну direct, тому кореневі записи direct
|
||||
// повністю замінюються. Щоб зберегти wildcard, явно визначте тут і "*".
|
||||
"+15551234567": { systemPrompt: "Prompt для конкретного робочого прямого чату." },
|
||||
"*": { systemPrompt: "Стандартний prompt для робочих прямих чатів." },
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -619,13 +620,13 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
|
||||
- [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp)
|
||||
|
||||
Важливі поля WhatsApp:
|
||||
Ключові поля WhatsApp:
|
||||
|
||||
- доступ: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
|
||||
- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`
|
||||
- кілька облікових записів: `accounts.<id>.enabled`, `accounts.<id>.authDir`, перевизначення на рівні облікового запису
|
||||
- операції: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`
|
||||
- поведінка сесій: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
|
||||
- поведінка сеансу: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
|
||||
- prompt: `groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
|
||||
|
||||
## Пов’язане
|
||||
@ -635,4 +636,4 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
- [Безпека](/uk/gateway/security)
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing)
|
||||
- [Маршрутизація кількох агентів](/uk/concepts/multi-agent)
|
||||
- [Усунення проблем](/uk/channels/troubleshooting)
|
||||
- [Усунення несправностей](/uk/channels/troubleshooting)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry
|
||||
- Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда
|
||||
- Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення
|
||||
- Ви хочете надсилати дані про використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry
|
||||
- Ви налаштовуєте трасування, метрики або логи для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда
|
||||
- Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати панелі моніторингу чи сповіщення
|
||||
summary: Експортуйте діагностику OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP)
|
||||
title: Експорт OpenTelemetry
|
||||
title: експорт OpenTelemetry
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T01:42:41Z"
|
||||
generated_at: "2026-04-26T04:44:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d670d7188d9c075b97743eae82e0aa999ac458a51c978a755e847e0b1648fa44
|
||||
source_hash: 2f2389c4efc2984d27e571152ce3cfea2ffeddc99084695f1c6ab6c97e6b7f7b
|
||||
source_path: gateway/opentelemetry.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel`,
|
||||
використовуючи **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP,
|
||||
працює без змін у коді. Для локальних файлових журналів і способів їх читання див.
|
||||
[Журналювання](/uk/logging).
|
||||
OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel`
|
||||
з використанням **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP,
|
||||
працює без змін у коді. Для локальних файлових логів і способів їх читання див.
|
||||
[Логування](/uk/logging).
|
||||
|
||||
## Як це працює разом
|
||||
|
||||
- **Події діагностики** — це структуровані внутрішньопроцесні записи, які створюються
|
||||
Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг
|
||||
Gateway і вбудованими Plugin для запусків моделей, потоку повідомлень, сесій, черг
|
||||
та exec.
|
||||
- **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як
|
||||
OpenTelemetry **метрики**, **трасування** і **журнали** через OTLP/HTTP.
|
||||
- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і сам plugin,
|
||||
тому внутрішньопроцесні накладні витрати за замовчуванням залишаються майже нульовими.
|
||||
OpenTelemetry **метрики**, **трасування** і **логи** через OTLP/HTTP.
|
||||
- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і Plugin,
|
||||
тож внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -56,7 +56,7 @@ OpenClaw експортує діагностику через вбудовани
|
||||
}
|
||||
```
|
||||
|
||||
Ви також можете ввімкнути plugin з CLI:
|
||||
Ви також можете ввімкнути Plugin з CLI:
|
||||
|
||||
```bash
|
||||
openclaw plugins enable diagnostics-otel
|
||||
@ -68,16 +68,16 @@ openclaw plugins enable diagnostics-otel
|
||||
|
||||
## Експортовані сигнали
|
||||
|
||||
| Сигнал | Що до нього входить |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черг, стану сесій, exec і тиску на пам’ять. |
|
||||
| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. |
|
||||
| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. |
|
||||
| Сигнал | Що він містить |
|
||||
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запусків, потоку повідомлень, смуг черги, стану сесій, exec і тиску пам’яті. |
|
||||
| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. |
|
||||
| **Логи** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. |
|
||||
|
||||
Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три за замовчуванням увімкнені,
|
||||
коли `diagnostics.otel.enabled` має значення true.
|
||||
|
||||
## Довідник конфігурації
|
||||
## Довідник з конфігурації
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -112,54 +112,54 @@ openclaw plugins enable diagnostics-otel
|
||||
|
||||
### Змінні середовища
|
||||
|
||||
| Variable | Призначення |
|
||||
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Змінна | Призначення |
|
||||
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. |
|
||||
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для окремих сигналів, які використовуються, коли відповідний ключ конфігурації `diagnostics.otel.*Endpoint` не задано. Конфігурація для конкретного сигналу має пріоритет над змінною середовища для конкретного сигналу, яка має пріоритет над спільною кінцевою точкою. |
|
||||
| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Встановіть значення `gen_ai_latest_experimental`, щоб надсилати останній експериментальний атрибут GenAI span (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені, низькокардинальні семантичні атрибути незалежно від цього. |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Встановіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. |
|
||||
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення endpoint для конкретного сигналу, що використовується, коли відповідний ключ конфігурації `diagnostics.otel.*Endpoint` не задано. Конфігурація конкретного сигналу має пріоритет над env конкретного сигналу, а той — над спільним endpoint. |
|
||||
| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. |
|
||||
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає протокол передачі даних (сьогодні враховується лише `http/protobuf`). |
|
||||
| `OTEL_SEMCONV_STABILITY_OPT_IN` | Встановіть `gen_ai_latest_experimental`, щоб виводити останній експериментальний атрибут GenAI span (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. |
|
||||
| `OPENCLAW_OTEL_PRELOADED` | Встановіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді Plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. |
|
||||
|
||||
## Конфіденційність і захоплення вмісту
|
||||
|
||||
Необроблений вміст моделей/інструментів **не** експортується за замовчуванням. Спани містять обмежені
|
||||
ідентифікатори (channel, provider, model, категорія помилки, лише хешовані request id)
|
||||
і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані інструментів або
|
||||
ключі сесій.
|
||||
Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Спани містять
|
||||
обмежені ідентифікатори (канал, провайдер, модель, категорія помилки, лише хешовані id запитів)
|
||||
і ніколи не включають текст запиту, текст відповіді, вхідні дані інструментів, вихідні дані інструментів
|
||||
або ключі сесії.
|
||||
|
||||
Встановлюйте `diagnostics.otel.captureContent.*` у `true` лише тоді, коли ваш колектор і
|
||||
політика зберігання схвалені для тексту промптів, відповідей, інструментів або system prompt.
|
||||
Кожен підключ окремо вмикається за принципом opt-in:
|
||||
політика зберігання схвалені для тексту запитів, відповідей, інструментів або
|
||||
системних запитів. Кожен підключ окремо вимагає явного ввімкнення:
|
||||
|
||||
- `inputMessages` — вміст запитів користувача.
|
||||
- `outputMessages` — вміст відповідей моделі.
|
||||
- `toolInputs` — корисні навантаження аргументів інструментів.
|
||||
- `toolOutputs` — корисні навантаження результатів інструментів.
|
||||
- `systemPrompt` — зібраний system/developer prompt.
|
||||
- `inputMessages` — вміст запиту користувача.
|
||||
- `outputMessages` — вміст відповіді моделі.
|
||||
- `toolInputs` — payload аргументів інструменту.
|
||||
- `toolOutputs` — payload результатів інструменту.
|
||||
- `systemPrompt` — зібраний системний/розробницький запит.
|
||||
|
||||
Коли ввімкнено будь-який підключ, спани моделей та інструментів отримують обмежені, редаговані
|
||||
Коли ввімкнено будь-який підключ, спани моделі та інструментів отримують обмежені, відредаговані
|
||||
атрибути `openclaw.content.*` лише для цього класу.
|
||||
|
||||
## Семплювання та скидання
|
||||
|
||||
- **Трасування:** `diagnostics.otel.sampleRate` (лише для root span, `0.0` відкидає все,
|
||||
- **Трасування:** `diagnostics.otel.sampleRate` (лише для root-span, `0.0` відкидає все,
|
||||
`1.0` зберігає все).
|
||||
- **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`).
|
||||
- **Журнали:** OTLP-журнали враховують `logging.level` (рівень файлового журналу). Редагування
|
||||
консолі **не** застосовується до OTLP-журналів. Для інсталяцій із великим обсягом
|
||||
краще використовувати семплювання/фільтрацію на колекторі OTLP, а не локальне семплювання.
|
||||
- **Логи:** OTLP-логи враховують `logging.level` (рівень файлового логу). Редагування
|
||||
для консолі **не** застосовується до OTLP-логів. Для інсталяцій із великим обсягом даних слід
|
||||
надавати перевагу семплюванню/фільтрації колектора OTLP замість локального семплювання.
|
||||
|
||||
## Експортовані метрики
|
||||
|
||||
### Використання моделі
|
||||
|
||||
- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`)
|
||||
- `openclaw.cost.usd` (лічильник, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.run.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.context.tokens` (гістограма, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
- `gen_ai.client.token.usage` (гістограма, метрика GenAI semantic conventions, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
|
||||
- `gen_ai.client.operation.duration` (гістограма, секунди, метрика GenAI semantic conventions, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язково `error.type`)
|
||||
- `gen_ai.client.token.usage` (гістограма, метрика семантичних конвенцій GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`)
|
||||
- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних конвенцій GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`)
|
||||
|
||||
### Потік повідомлень
|
||||
|
||||
@ -200,14 +200,14 @@ openclaw plugins enable diagnostics-otel
|
||||
- `openclaw.model.usage`
|
||||
- `openclaw.channel`, `openclaw.provider`, `openclaw.model`
|
||||
- `openclaw.tokens.*` (input/output/cache_read/cache_write/total)
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші GenAI semantic conventions
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, коли ввімкнено найновіші семантичні конвенції GenAI
|
||||
- `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*`
|
||||
- `openclaw.run`
|
||||
- `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory`
|
||||
- `openclaw.model.call`
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші GenAI semantic conventions
|
||||
- `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, коли ввімкнено найновіші семантичні конвенції GenAI
|
||||
- `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`
|
||||
- `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA від upstream request id провайдера; сирі id не експортуються)
|
||||
- `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для id запиту до висхідного провайдера; сирі id не експортуються)
|
||||
- `openclaw.tool.execution`
|
||||
- `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*`
|
||||
- `openclaw.exec`
|
||||
@ -223,26 +223,26 @@ openclaw plugins enable diagnostics-otel
|
||||
- `openclaw.session.stuck`
|
||||
- `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth`
|
||||
- `openclaw.context.assembled`
|
||||
- `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту prompt, history, response або ключів сесії)
|
||||
- `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту запиту, історії, відповіді чи ключа сесії)
|
||||
- `openclaw.tool.loop`
|
||||
- `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, params або виводу інструмента)
|
||||
- `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструменту)
|
||||
- `openclaw.memory.pressure`
|
||||
- `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes`
|
||||
|
||||
Коли захоплення вмісту явно ввімкнено, спани моделей та інструментів також можуть
|
||||
містити обмежені, редаговані атрибути `openclaw.content.*` для конкретних
|
||||
класів вмісту, які ви явно ввімкнули.
|
||||
Коли захоплення вмісту явно ввімкнено, спани моделі та інструментів також можуть
|
||||
містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних
|
||||
класів вмісту, які ви ввімкнули.
|
||||
|
||||
## Каталог подій діагностики
|
||||
|
||||
Події нижче лежать в основі метрик і спанів, наведених вище. Plugins також можуть
|
||||
підписуватися на них напряму без експорту OTLP.
|
||||
Наведені нижче події лежать в основі наведених вище метрик і спанів. Plugin також можуть підписуватися
|
||||
на них безпосередньо без експорту OTLP.
|
||||
|
||||
**Використання моделі**
|
||||
|
||||
- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/channel,
|
||||
id сесій. `usage` — це облік провайдера/ходу для вартості та телеметрії;
|
||||
`context.used` — це поточний знімок prompt/context і він може бути меншим за
|
||||
- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал,
|
||||
id сесій. `usage` — це облік провайдера/ходу для вартості й телеметрії;
|
||||
`context.used` — це поточний знімок запиту/контексту, і він може бути меншим за
|
||||
`usage.total` провайдера, коли залучено кешований ввід або виклики циклу інструментів.
|
||||
|
||||
**Потік повідомлень**
|
||||
@ -261,13 +261,13 @@ openclaw plugins enable diagnostics-otel
|
||||
**Exec**
|
||||
|
||||
- `exec.process.completed` — підсумковий результат, тривалість, ціль, режим, код
|
||||
виходу та тип збою. Текст команди й робочі каталоги не
|
||||
завершення та тип помилки. Текст команди й робочі каталоги не
|
||||
включаються.
|
||||
|
||||
## Без експортера
|
||||
|
||||
Ви можете зберегти події діагностики доступними для plugins або користувацьких приймачів
|
||||
без запуску `diagnostics-otel`:
|
||||
Ви можете залишити події діагностики доступними для Plugin або власних приймачів без
|
||||
запуску `diagnostics-otel`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -276,7 +276,7 @@ openclaw plugins enable diagnostics-otel
|
||||
```
|
||||
|
||||
Для цільового виводу налагодження без підвищення `logging.level` використовуйте
|
||||
прапорці діагностики. Прапорці нечутливі до регістру та підтримують wildcard-и (наприклад, `telegram.*` або
|
||||
прапори діагностики. Прапори нечутливі до регістру й підтримують шаблони (наприклад, `telegram.*` або
|
||||
`*`):
|
||||
|
||||
```json5
|
||||
@ -291,9 +291,9 @@ openclaw plugins enable diagnostics-otel
|
||||
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
|
||||
```
|
||||
|
||||
Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і все ще
|
||||
редагується `logging.redactSensitive`. Повний посібник:
|
||||
[Прапорці діагностики](/uk/diagnostics/flags).
|
||||
Вивід прапорів надходить до стандартного файлу журналу (`logging.file`) і все ще
|
||||
редагується через `logging.redactSensitive`. Повний посібник:
|
||||
[Прапори діагностики](/uk/diagnostics/flags).
|
||||
|
||||
## Вимкнення
|
||||
|
||||
@ -306,10 +306,10 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway
|
||||
Ви також можете не додавати `diagnostics-otel` до `plugins.allow` або виконати
|
||||
`openclaw plugins disable diagnostics-otel`.
|
||||
|
||||
## Пов’язані матеріали
|
||||
## Пов’язане
|
||||
|
||||
- [Журналювання](/uk/logging) — файлові журнали, консольний вивід, tailing через CLI та вкладка Logs у Control UI
|
||||
- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
|
||||
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналювання налагодження
|
||||
- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент пакета підтримки для операторів (окремо від експорту OTEL)
|
||||
- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`
|
||||
- [Логування](/uk/logging) — файлові логи, консольний вивід, tailing у CLI та вкладка Logs у Control UI
|
||||
- [Внутрішня структура логування Gateway](/uk/gateway/logging) — стилі WS-логів, префікси підсистем і захоплення консолі
|
||||
- [Прапори діагностики](/uk/diagnostics/flags) — прапори цільових налагоджувальних логів
|
||||
- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент для створення пакетів підтримки операторів (окремо від експорту OTEL)
|
||||
- [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user