chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
33098a7d58
commit
fdba301d2f
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над можливостями Telegram або Webhook
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Статус підтримки бота Telegram, можливості та конфігурація
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T07:28:35Z"
|
||||
generated_at: "2026-04-25T08:43:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 8401457440f52a1c8342d650d8dedb363639bc1cda0c1bbe7150d2b243c09087
|
||||
source_hash: 258cf292a6ba70fc05c509af7c4f70a58b95579ec61ec958e789c84ecbb59681
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Через grammY готово до продакшну для DM бота та груп. Long polling — режим за замовчуванням; режим Webhook — необов’язковий.
|
||||
Готово до продакшену для DM бота та груп через grammY. Режим довгого опитування є режимом за замовчуванням; режим 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 title="Усунення проблем каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
@ -52,11 +52,11 @@ x-i18n:
|
||||
```
|
||||
|
||||
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть Gateway.
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть Gateway і схваліть перший DM">
|
||||
<Step title="Запустіть gateway і підтвердьте перший DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,35 +64,35 @@ 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>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним варіантом через env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням із env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим конфіденційності та видимість у групах">
|
||||
За замовчуванням Telegram-боти працюють у **Privacy Mode**, який обмежує, які повідомлення з груп вони отримують.
|
||||
<Accordion title="Режим конфіденційності та видимість груп">
|
||||
Для ботів Telegram за замовчуванням увімкнено **Privacy Mode**, який обмежує, які повідомлення групи вони отримують.
|
||||
|
||||
Якщо бот має бачити всі повідомлення в групі, виконайте одну з дій:
|
||||
Якщо бот має бачити всі повідомлення групи, виконайте одне з таких:
|
||||
|
||||
- вимкніть режим конфіденційності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму конфіденційності видаліть і знову додайте бота в кожну групу, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму конфіденційності видаліть бота й додайте його знову в кожну групу, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дозволи в групі">
|
||||
<Accordion title="Дозволи групи">
|
||||
Статус адміністратора керується в налаштуваннях групи Telegram.
|
||||
|
||||
Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі.
|
||||
@ -102,59 +102,59 @@ openclaw pairing approve telegram <CODE>
|
||||
<Accordion title="Корисні перемикачі BotFather">
|
||||
|
||||
- `/setjoingroups`, щоб дозволити/заборонити додавання до груп
|
||||
- `/setprivacy` для поведінки видимості в групах
|
||||
- `/setprivacy` для керування видимістю в групах
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Контроль доступу та активація
|
||||
## Керування доступом і активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потрібен щонайменше один ID відправника в `allowFrom`)
|
||||
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється перевіркою config.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваш config містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (best-effort; потрібен токен бота Telegram).
|
||||
Якщо ви раніше покладалися на файли allowlist у pairing-store, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` для сценаріїв allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією config.
|
||||
Під час налаштування запитуються лише числові 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`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень підключення).
|
||||
Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID у `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх підтверджень сполучення).
|
||||
|
||||
Поширена плутанина: схвалення підключення для DM не означає, що «цей відправник авторизований усюди».
|
||||
Підключення надає доступ лише до DM. Авторизація відправника в групах усе ще визначається явними allowlist у config.
|
||||
Типова плутанина: підтвердження сполучення в DM не означає, що «цей відправник авторизований усюди».
|
||||
Сполучення надає доступ лише до DM. Авторизація відправників у групах, як і раніше, походить лише з явних allowlist у config.
|
||||
Якщо ви хочете, щоб «я був авторизований один раз і працювали і DM, і команди в групі», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніший спосіб (без стороннього бота):
|
||||
|
||||
1. Надішліть DM вашому боту.
|
||||
1. Напишіть своєму боту в DM.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
Офіційний спосіб через Bot API:
|
||||
Офіційний метод через Bot API:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
Сторонній спосіб (менш приватний): `@userinfobot` або `@getidsbot`.
|
||||
Сторонній метод (менш приватний): `@userinfobot` або `@getidsbot`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп і allowlist">
|
||||
Разом застосовуються два елементи керування:
|
||||
Разом застосовуються два механізми керування:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає config `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`)
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи до `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
|
||||
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
|
||||
@ -162,15 +162,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не вказано, Telegram використовує `allowFrom` як резервний варіант.
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує резервне значення з `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються).
|
||||
Не вказуйте ID груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групах **не** успадковує схвалення з pairing-store для DM.
|
||||
Підключення залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` для конкретної групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram використовує config `allowFrom`, а не pairing store.
|
||||
Практичний шаблон для ботів з одним власником: встановіть свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` не заданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка про runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює в fail-closed режимі з `groupPolicy="allowlist"`, якщо явно не задано `channels.defaults.groupPolicy`.
|
||||
Не додавайте ID чатів Telegram group або supergroup до `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує підтвердження зі сховища сполучень для DM.
|
||||
Сполучення залишається лише для DM. Для груп налаштуйте `groupAllowFrom` або `allowFrom` для конкретної групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з `allowFrom` у config, а не зі сховища сполучень.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom`, і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює в режимі fail-closed з `groupPolicy="allowlist"`, якщо лише явно не задано `channels.defaults.groupPolicy`.
|
||||
|
||||
Приклад: дозволити будь-якому учаснику в одній конкретній групі:
|
||||
|
||||
@ -207,22 +207,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram.
|
||||
Типова помилка: `groupAllowFrom` — це не allowlist груп Telegram.
|
||||
|
||||
- Додавайте від’ємні ID груп або супергруп Telegram, наприклад `-1001234567890`, до `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, наприклад `8734062810`, до `groupAllowFrom`, якщо хочете обмежити, які люди всередині дозволеної групи можуть активувати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише якщо хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
- Додавайте від’ємні ID чатів Telegram group або supergroup, наприклад `-1001234567890`, до `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, наприклад `8734062810`, до `groupAllowFrom`, якщо хочете обмежити, які люди всередині дозволеної групи можуть звертатися до бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Поведінка згадки">
|
||||
За замовчуванням відповіді в групах вимагають згадки.
|
||||
<Tab title="Поведінка згадування">
|
||||
Відповіді в групах за замовчуванням вимагають згадування.
|
||||
|
||||
Згадка може надходити з:
|
||||
Згадування може надходити з:
|
||||
|
||||
- нативної згадки `@botusername`, або
|
||||
- шаблонів згадки в:
|
||||
- нативного згадування `@botusername`, або
|
||||
- шаблонів згадування в:
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
@ -231,7 +231,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для постійного збереження використовуйте config.
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте config.
|
||||
|
||||
Приклад постійної конфігурації:
|
||||
|
||||
@ -258,32 +258,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
## Поведінка runtime
|
||||
|
||||
- Telegram належить процесу Gateway.
|
||||
- Маршрутизація детермінована: вхідні відповіді Telegram повертаються в Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються до спільного конверта каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб зберігати ізоляцію тем.
|
||||
- DM-повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесії, що враховують тред, і зберігає ID треду для відповідей.
|
||||
- Long polling використовує grammY runner із послідовністю на рівні чату/треду. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Перезапуски watchdog для long polling спрацьовують за замовчуванням після 120 секунд без завершеної живучості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще є хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і може бути від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються у спільний конверт каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Для тем форуму додається `:topic:<threadId>`, щоб теми були ізольовані.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, чутливими до потоків, і зберігає ID потоку для відповідей.
|
||||
- Довге опитування використовує runner grammY із послідовністю для кожного чату/потоку. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене в межах кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller.
|
||||
- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання опитування під час довготривалої роботи. Значення задається в мілісекундах і допускається в діапазоні від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник можливостей
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
<Accordion title="Попередній перегляд живого потоку (редагування повідомлень)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: попереднє повідомлення + `editMessageText`
|
||||
- групи/теми: попереднє повідомлення + `editMessageText`
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` дорівнює `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` у Telegram відповідає `partial` (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний preview streaming)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` автоматично зіставляються
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` відображається в `partial` у Telegram (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи повторно використовуються оновлення інструментів/прогресу в тому самому редагованому повідомленні попереднього перегляду (за замовчуванням: `true`, коли активне потокове попереднє відображення)
|
||||
- застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` відображаються автоматично
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюю...», які показуються під час роботи інструментів, наприклад під час виконання команд, читання файлів, оновлень плану або підсумків патчів. У Telegram вони ввімкнені за замовчуванням, щоб відповідати випущеній поведінці OpenClaw починаючи з `v2026.4.22`. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, встановіть:
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюю...», які показуються під час виконання інструментів, наприклад виконання команд, читання файлів, оновлення плану або підсумків патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw починаючи з `v2026.4.22`. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -300,52 +301,52 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки стану прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки стану прогресу інструментів.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
|
||||
- DM: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- DM: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- group/topic: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці (без другого повідомлення)
|
||||
|
||||
Для складних відповідей (наприклад, із медіавмістом) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, з медіа-навантаженням) OpenClaw переходить до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
|
||||
Preview streaming відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає preview stream, щоб уникнути подвійного потокового передавання.
|
||||
Потокове попереднє відображення відокремлене від потокової передачі блоками. Коли для Telegram явно ввімкнено потокову передачу блоками, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі.
|
||||
|
||||
Якщо нативний транспорт чернеток недоступний або відхиляється, OpenClaw автоматично переходить на `sendMessage` + `editMessageText`.
|
||||
Якщо нативний транспорт чернеток недоступний або відхиляється, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
|
||||
|
||||
Потік міркувань лише для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає міркування в live preview під час генерації
|
||||
- `/reasoning stream` надсилає міркування в живий попередній перегляд під час генерації
|
||||
- фінальна відповідь надсилається без тексту міркувань
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний перехід до HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
<Accordion title="Форматування та резервний варіант HTML">
|
||||
Для вихідного тексту використовується Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередній перегляд посилань увімкнено за замовчуванням; його можна вимкнути через `channels.telegram.linkPreview: false`.
|
||||
Попередній перегляд посилань увімкнено за замовчуванням і його можна вимкнути за допомогою `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`.
|
||||
|
||||
Типові значення нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
Додайте власні записи до меню команд:
|
||||
Додайте користувацькі записи меню команд:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegram: {
|
||||
customCommands: [
|
||||
{ command: "backup", description: "Резервна копія Git" },
|
||||
{ command: "backup", description: "Резервне копіювання Git" },
|
||||
{ command: "generate", description: "Створити зображення" },
|
||||
],
|
||||
},
|
||||
@ -355,40 +356,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- імена нормалізуються (забирається початковий `/`, перетворення в нижній регістр)
|
||||
- імена нормалізуються (видаляється початковий `/`, перетворюються на нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- власні команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються й записуються в журнал
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються та журналюються
|
||||
|
||||
Примітки:
|
||||
|
||||
- власні команди — це лише записи меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills усе ще можуть працювати при ручному введенні, навіть якщо вони не показані в меню Telegram
|
||||
- користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills усе одно можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнені, вбудовані команди видаляються. Власні команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано.
|
||||
|
||||
Поширені збої налаштування:
|
||||
Поширені збої під час налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/власних команд або вимкніть `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідні DNS/HTTPS-запити до `api.telegram.org` заблоковані.
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS до `api.telegram.org` заблоковані.
|
||||
|
||||
### Команди підключення пристрою (Plugin `device-pair`)
|
||||
### Команди сполучення пристрою (`device-pair` Plugin)
|
||||
|
||||
Коли встановлено Plugin `device-pair`:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список очікуваних запитів (включно з роллю/scopes)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один запит в очікуванні
|
||||
3. `/pair pending` показує список запитів, що очікують на розгляд (зокрема роль/scopes)
|
||||
4. підтвердьте запит:
|
||||
- `/pair approve <requestId>` для явного підтвердження
|
||||
- `/pair approve`, коли є лише один запит, що очікує на розгляд
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен primary Node на `scopes: []`; будь-який переданий operator-токен залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тому цей operator allowlist задовольняє лише operator-запити; ролям, що не є operator, усе ще потрібні scopes під власним префіксом ролі.
|
||||
Код налаштування містить короткостроковий bootstrap-токен. Вбудований bootstrap-handoff зберігає токен primary node з `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, як і раніше потребують scopes під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими даними auth (наприклад, role/scopes/public key), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`.
|
||||
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/scopes/публічний ключ), попередній запит, що очікує на розгляд, замінюється, а новий запит використовує інший `requestId`. Перед підтвердженням знову виконайте `/pair pending`.
|
||||
|
||||
Докладніше: [Підключення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -433,7 +434,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (за замовчуванням)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
|
||||
Застаріле `capabilities: ["inlineButtons"]` відображається в `inlineButtons: "all"`.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -458,33 +459,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дії з повідомленнями Telegram для агентів і автоматизації">
|
||||
<Accordion title="Дії повідомлень Telegram для агентів і автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Керування обмеженнями:
|
||||
Керувальні перемикачі:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час runtime використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторного визначення `SecretRef` для кожного надсилання.
|
||||
Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання в runtime використовує активний знімок config/secrets (startup/reload), тому шляхи дій не виконують ad hoc повторне визначення SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги тредів відповідей">
|
||||
Telegram підтримує явні теги тредів відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги потоків відповідей">
|
||||
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення-тригер
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
@ -495,27 +496,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Примітка: `off` вимикає неявні треди відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
Примітка: `off` вимикає неявне впорядкування відповідей у потоці. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму та поведінка тредів">
|
||||
Супергрупи-форуми:
|
||||
<Accordion title="Теми форуму та поведінка потоків">
|
||||
Супергрупи форуму:
|
||||
|
||||
- ключі сесій тем додають `:topic:<threadId>`
|
||||
- відповіді та введення тексту спрямовуються в тред теми
|
||||
- ключі сесій тем доповнюються `:topic:<threadId>`
|
||||
- відповіді та індикатор набору тексту націлюються на потік теми
|
||||
- шлях config теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`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` існує лише на рівні теми й не успадковується від значень групи за замовчуванням.
|
||||
`agentId` належить лише темі й не успадковується від значень групи за замовчуванням.
|
||||
|
||||
**Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через `agentId` у config теми. Це надає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад:
|
||||
**Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через налаштування `agentId` у config теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -524,9 +525,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
topics: {
|
||||
"1": { agentId: "main" }, // Загальна тема → main agent
|
||||
"3": { agentId: "zu" }, // Тема розробки → zu agent
|
||||
"5": { agentId: "coder" } // Код-рев’ю → coder agent
|
||||
"1": { agentId: "main" }, // Загальна тема → агент main
|
||||
"3": { agentId: "zu" }, // Тема розробки → агент zu
|
||||
"5": { agentId: "coder" } // Рецензія коду → агент coder
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -537,21 +538,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Тоді кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійне прив’язування тем ACP**: Теми форуму можуть закріплювати сесії ACP harness через типізовані ACP bindings верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з указанням теми, наприклад `-1001234567890:topic:42`). Наразі область дії обмежена темами форуму в групах/супергрупах. Див. [ACP Agents](/uk/tools/acp-agents).
|
||||
**Постійна прив’язка тем ACP**: Теми форуму можуть закріплювати сесії harness ACP через bindings ACP верхнього рівня з типізацією (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором теми на кшталт `-1001234567890:topic:42`). Наразі область дії обмежена темами форуму в groups/supergroups. Див. [ACP Agents](/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]]` у відповіді агента примусово надсилає як голосове повідомлення
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -567,7 +568,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Відеоповідомлення
|
||||
|
||||
Telegram розрізняє відеофайли та відеоногатки.
|
||||
Telegram розрізняє відеофайли та відеонотатки.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -603,9 +604,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити повторні виклики vision.
|
||||
|
||||
Увімкнення дій зі стікерами:
|
||||
Увімкніть дії для стікерів:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -646,9 +647,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень).
|
||||
|
||||
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
- `Додано реакцію Telegram: 👍 від Alice (@alice) на повідомлення 42`
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
Config:
|
||||
|
||||
@ -658,34 +659,34 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе ще дотримуються елементів контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID тредів в оновленнях реакцій.
|
||||
- Події реакцій усе одно дотримуються керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID потоку в оновленнях реакцій.
|
||||
- нефорумні групи маршрутизуються до сесії групового чату
|
||||
- форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної вихідної теми
|
||||
- групи форуму маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включають `message_reaction`.
|
||||
`allowed_updates` для polling/Webhook автоматично включають `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Реакції підтвердження">
|
||||
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
<Accordion title="Реакції-підтвердження">
|
||||
`ackReaction` надсилає емодзі-підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- резервний варіант — емодзі identity агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
- резервний варіант емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує Unicode-емодзі (наприклад "👀").
|
||||
- Telegram очікує емодзі unicode (наприклад, "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Запис config із подій і команд Telegram">
|
||||
Записи config каналу ввімкнені за замовчуванням (`configWrites !== false`).
|
||||
<Accordion title="Записи config із подій і команд Telegram">
|
||||
Запис конфігурації каналу увімкнено за замовчуванням (`configWrites !== false`).
|
||||
|
||||
Записи, ініційовані Telegram, включають:
|
||||
|
||||
@ -706,31 +707,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling проти webhook">
|
||||
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Довге опитування чи Webhook">
|
||||
За замовчуванням використовується довге опитування. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково `webhookPath`, `webhookHost`, `webhookPort` (типові значення: `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або свідомо встановіть `webhookHost: "0.0.0.0"`.
|
||||
Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного вхідного трафіку або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим Webhook перевіряє захист запитів, секретний токен Telegram і JSON body перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі bot lanes на рівні чату/теми, які використовуються в long polling, тож повільні ходи агента не затримують ACK доставки Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі бот-черги для кожного чату/теми, що й у режимі довгого опитування, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ліміти, повторні спроби та цілі CLI">
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується значення grammY за замовчуванням).
|
||||
- Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте в діапазоні від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає її.
|
||||
- Додатковий контекст reply/quote/forward наразі передається як отримано.
|
||||
- allowlist Telegram насамперед обмежують те, хто може активувати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Елементи керування історією DM:
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в діапазоні від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання опитування.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає її.
|
||||
- додатковий контекст reply/quote/forward наразі передається як отримано.
|
||||
- allowlist Telegram насамперед визначають, хто може запускати агента, а не є повноцінною межею редагування додаткового контексту.
|
||||
- засоби керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- Config `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API.
|
||||
- config `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ID чату або ім’ям користувача:
|
||||
Ціллю надсилання CLI може бути числовий ID чату або ім’я користувача:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -754,48 +755,48 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-public`
|
||||
- `--thread-id` для тем форуму (або використовуйте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
Надсилання в Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи, а не як стиснені фото чи анімовані медіазавантаження
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, коли бот може закріплювати повідомлення в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стислих фото або анімованих медіазавантажень
|
||||
|
||||
Обмеження дій:
|
||||
Керувальні перемикачі дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема опитування
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання увімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Погодження exec у Telegram">
|
||||
Telegram підтримує погодження exec у DM користувачів, що погоджують, і за потреби може публікувати запити у вихідному чаті або темі. Користувачі, що погоджують, мають бути задані числовими ID користувачів Telegram.
|
||||
<Accordion title="Підтвердження exec у Telegram">
|
||||
Telegram підтримує підтвердження exec у DM схвалювачів і може за потреби публікувати запити у вихідному чаті або темі. Схвалювачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях config:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного користувача, що погоджує)
|
||||
- `channels.telegram.execApprovals.approvers` (резервний варіант — числові ID власника з `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача)
|
||||
- `channels.telegram.execApprovals.approvers` (використовує резервне значення числових ID власників із `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту погодження й подальшої взаємодії. Типово погодження exec спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на схвалення та подальших дій. За замовчуванням термін дії підтверджень exec спливає через 30 хвилин.
|
||||
|
||||
Вбудовані кнопки погодження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID погодження з префіксом `plugin:` визначаються через погодження Plugin; інші спочатку визначаються через погодження exec.
|
||||
Вбудовані кнопки схвалення також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалення з префіксом `plugin:` визначаються через схвалення Plugin; інші спочатку визначаються через схвалення exec.
|
||||
|
||||
Див. [Погодження exec](/uk/tools/exec-approvals).
|
||||
Див. [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Елементи керування відповідями про помилки
|
||||
## Керування відповідями на помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі config:
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приглушити її. Цю поведінку контролюють два ключі config:
|
||||
|
||||
| Ключ | Значення | За замовчуванням | Опис |
|
||||
| ----------------------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю пригнічує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в тому самому чаті. Запобігає спаму помилками під час збоїв. |
|
||||
| Key | Values | Default | Description |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає в чат дружнє повідомлення про помилку. `silent` повністю приглушує відповіді з помилками. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в тому самому чаті. Запобігає спаму помилками під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для окремих облікових записів, груп і тем (та сама схема успадкування, що й для інших ключів config Telegram).
|
||||
Підтримуються перевизначення для окремого облікового запису, групи та теми (те саме успадкування, що й для інших ключів config Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -805,7 +806,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
errorCooldownMs: 120000,
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
errorPolicy: "silent", // приховати помилки в цій групі
|
||||
errorPolicy: "silent", // приглушити помилки в цій групі
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -816,42 +817,42 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## Усунення проблем
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Бот не відповідає на повідомлення в групі без згадки">
|
||||
<Accordion title="Бот не відповідає на повідомлення групи без згадування">
|
||||
|
||||
- Якщо `requireMention=false`, режим конфіденційності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і знову додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; для wildcard `"*"` перевірка членства неможлива.
|
||||
- потім видаліть бота з групи й додайте знову
|
||||
- `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадування.
|
||||
- `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="Команди працюють частково або взагалі не працюють">
|
||||
<Accordion title="Команди працюють частково або зовсім не працюють">
|
||||
|
||||
- авторизуйте свою ідентичність відправника (підключення та/або числовий `allowFrom`)
|
||||
- авторизація команд усе ще застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню містить занадто багато записів; зменште кількість команд Plugin/Skills/власних команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми досяжності DNS/HTTPS до `api.telegram.org`
|
||||
- авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`)
|
||||
- авторизація команд застосовується навіть тоді, коли політика групи має значення `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню містить забагато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає проблеми з доступністю DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
<Accordion title="Нестабільність опитування або мережі">
|
||||
|
||||
- Node 22+ + власний fetch/proxy можуть спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- На деяких хостах `api.telegram.org` спочатку визначається в IPv6; несправний вихід через IPv6 може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює спроби для них як для відновлюваних мережевих помилок.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної живучості long-poll за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ + користувацький fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- На деяких хостах `api.telegram.org` спочатку визначається в IPv6; несправний вихідний IPv6-трафік може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює їх як відновлювані мережеві помилки.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності довгого опитування за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` є здоровими, але ваш хост усе ще повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або вихідного TLS між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим виходом/TLS направляйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -859,7 +860,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- У Node 22+ типовими є `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства:
|
||||
|
||||
```yaml
|
||||
@ -869,10 +870,10 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді з діапазону RFC 2544 benchmark (`198.18.0.0/15`) уже дозволені
|
||||
- Відповіді з діапазону еталонного тестування RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
за замовчуванням для завантажень медіа Telegram. Якщо довірений fake-IP або
|
||||
transparent proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/special-use адресу під час завантаження медіа, ви можете
|
||||
прозорий proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете
|
||||
увімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
@ -882,25 +883,25 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Те саме явне ввімкнення доступне для окремого облікового запису в
|
||||
- Той самий opt-in доступний для окремого облікового запису в
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy визначає хости медіа Telegram у `198.18.x.x`, спочатку залиште
|
||||
- Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спочатку залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяють
|
||||
діапазон RFC 2544 benchmark.
|
||||
діапазон еталонного тестування RFC 2544.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захисти SSRF
|
||||
для медіа Telegram. Використовуйте його лише в довірених proxy-середовищах під контролем оператора,
|
||||
таких як Clash, Mihomo або Surge fake-IP routing, коли вони
|
||||
синтезують приватні або special-use відповіді поза діапазоном RFC 2544 benchmark.
|
||||
Для звичайного публічного доступу до Telegram через інтернет залишайте це вимкненим.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист
|
||||
Telegram media SSRF. Використовуйте його лише в довірених середовищах proxy,
|
||||
які контролює оператор, як-от Clash, Mihomo або fake-IP-маршрутизація Surge, коли вони
|
||||
синтезують приватні або спеціального призначення відповіді поза діапазоном
|
||||
еталонного тестування RFC 2544. Для звичайного публічного доступу до Telegram через інтернет залишайте його вимкненим.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення через середовище (тимчасові):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- Перевірте DNS-відповіді:
|
||||
- Перевірте відповіді DNS:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -910,51 +911,51 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Додаткова допомога: [Усунення проблем із каналом](/uk/channels/troubleshooting).
|
||||
Більше допомоги: [Усунення проблем каналів](/uk/channels/troubleshooting).
|
||||
|
||||
## Довідник з конфігурації
|
||||
## Довідник конфігурації
|
||||
|
||||
Основний довідник: [Довідник з конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Ключові поля Telegram">
|
||||
<Accordion title="Ключові поля Telegram із високим сигналом">
|
||||
|
||||
- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symlink відхиляються)
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
|
||||
- погодження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
|
||||
- підтвердження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команди/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- треди/відповіді: `replyToMode`
|
||||
- потокове передавання: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- потоки/відповіді: `replyToMode`
|
||||
- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
- помилки: `errorPolicy`, `errorCooldownMs`
|
||||
- запис/історія: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- записи/історія: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Пріоритетність для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw використовує перший нормалізований ID облікового запису, а `openclaw doctor` показує попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
Пріоритетність кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw використовує резервний варіант із першим нормалізованим ID облікового запису, і `openclaw doctor` видає попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Пов’язані матеріали
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Підключення" icon="link" href="/uk/channels/pairing">
|
||||
Підключіть користувача Telegram до gateway.
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Зіставте користувача Telegram із gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка allowlist для груп і тем.
|
||||
</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">
|
||||
Зіставлення груп і тем з агентами.
|
||||
Зіставляйте групи й теми з агентами.
|
||||
</Card>
|
||||
<Card title="Усунення проблем" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика.
|
||||
|
||||
@ -5,62 +5,62 @@ read_when:
|
||||
summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем
|
||||
title: Довідник конфігурації
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T07:53:43Z"
|
||||
generated_at: "2026-04-25T08:43:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fd4ebfce263df22d2daa8e0a01e8ab7f590f86b424c534a85d39a25cee98e053
|
||||
source_hash: debcc9f7151314c02484a3b801bb0e2270b982e9d59567506a032762696aff1c
|
||||
source_path: gateway/configuration-reference.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
|
||||
Довідник конфігурації ядра для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration).
|
||||
|
||||
Охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний глибший довідник. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD розміщено на окремих сторінках, а не тут.
|
||||
Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і плагінам, а також глибокі параметри пам’яті/QMD винесені на окремі сторінки, а не наведені тут.
|
||||
|
||||
Джерело істини в коді:
|
||||
|
||||
- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із об’єднаними метаданими bundled/plugin/channel, коли вони доступні
|
||||
- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізованого перегляду
|
||||
- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації відносно поточної поверхні схеми
|
||||
- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із доданими метаданими bundled/plugin/channel, коли вони доступні
|
||||
- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації
|
||||
- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc щодо поточної поверхні схеми
|
||||
|
||||
Окремі глибокі довідники:
|
||||
Окремі докладні довідники:
|
||||
|
||||
- [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming`
|
||||
- [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming`
|
||||
- [Slash commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд
|
||||
- сторінки відповідних каналів/Plugin для специфічних для каналу поверхонь команд
|
||||
- сторінки власника каналу/плагіна для специфічних поверхонь команд каналів
|
||||
|
||||
Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано.
|
||||
Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано.
|
||||
|
||||
---
|
||||
|
||||
## Канали
|
||||
|
||||
Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див.
|
||||
Ключі конфігурації окремих каналів перенесено на окрему сторінку — див.
|
||||
[Configuration — channels](/uk/gateway/config-channels) для `channels.*`,
|
||||
зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших
|
||||
bundled каналів (автентифікація, контроль доступу, кілька облікових записів, gating згадок).
|
||||
bundled каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками).
|
||||
|
||||
## Типові налаштування агента, мультиагентність, сесії та повідомлення
|
||||
## Значення агентів за замовчуванням, мультиагентність, сесії та повідомлення
|
||||
|
||||
Перенесено на окрему сторінку — див.
|
||||
[Configuration — agents](/uk/gateway/config-agents) для:
|
||||
|
||||
- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox)
|
||||
- `agents.defaults.*` (робочий простір, модель, thinking, Heartbeat, пам’ять, медіа, Skills, sandbox)
|
||||
- `multiAgent.*` (маршрутизація та прив’язки мультиагентності)
|
||||
- `session.*` (життєвий цикл сесії, compaction, pruning)
|
||||
- `session.*` (життєвий цикл сесії, Compaction, очищення)
|
||||
- `messages.*` (доставка повідомлень, TTS, рендеринг markdown)
|
||||
- `talk.*` (режим Talk)
|
||||
- `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`)
|
||||
|
||||
## Інструменти та власні провайдери
|
||||
## Інструменти та користувацькі провайдери
|
||||
|
||||
Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних
|
||||
провайдерів / base-URL перенесено на окрему сторінку — див.
|
||||
Політика інструментів, експериментальні перемикачі, конфігурація інструментів на основі провайдерів, а також налаштування користувацьких
|
||||
провайдерів / base-URL перенесені на окрему сторінку — див.
|
||||
[Configuration — tools and custom providers](/uk/gateway/config-tools).
|
||||
|
||||
## MCP
|
||||
|
||||
Визначення MCP-серверів, керованих OpenClaw, розміщуються в `mcp.servers` і
|
||||
Визначення MCP-серверів, якими керує OpenClaw, розташовані в `mcp.servers` і
|
||||
використовуються вбудованим Pi та іншими адаптерами середовища виконання. Команди `openclaw mcp list`,
|
||||
`show`, `set` і `unset` керують цим блоком без підключення до
|
||||
цільового сервера під час редагування конфігурації.
|
||||
@ -87,14 +87,14 @@ bundled каналів (автентифікація, контроль дост
|
||||
}
|
||||
```
|
||||
|
||||
- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які
|
||||
- `mcp.servers`: іменовані визначення stdio- або віддалених MCP-серверів для середовищ виконання, які
|
||||
надають налаштовані MCP-інструменти.
|
||||
- `mcp.sessionIdleTtlMs`: idle TTL для bundled MCP runtime, прив’язаних до сесії.
|
||||
Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є резервним механізмом для
|
||||
довготривалих сесій і майбутніх викликачів.
|
||||
- Зміни в `mcp.*` застосовуються на льоту через знищення кешованих session MCP runtime.
|
||||
Наступне виявлення/використання інструмента створює їх заново з нової конфігурації, тож видалені
|
||||
записи `mcp.servers` прибираються негайно, а не чекають idle TTL.
|
||||
- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP runtime, прив’язаних до сесії.
|
||||
Одноразові вбудовані запуски запитують очищення наприкінці виконання; цей TTL є
|
||||
страховим механізмом для довготривалих сесій і майбутніх викликів.
|
||||
- Зміни в `mcp.*` застосовуються на льоту через звільнення кешованих MCP runtime сесії.
|
||||
Наступне виявлення/використання інструменту відтворює їх із нової конфігурації, тому видалені
|
||||
записи `mcp.servers` прибираються негайно, а не чекають TTL простою.
|
||||
|
||||
Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і
|
||||
[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки середовища виконання.
|
||||
@ -124,18 +124,18 @@ bundled каналів (автентифікація, контроль дост
|
||||
}
|
||||
```
|
||||
|
||||
- `allowBundled`: необов’язковий список дозволу лише для bundled Skills (керовані/робочі Skills не зачіпаються).
|
||||
- `load.extraDirs`: додаткові спільні кореневі каталоги Skills (найнижчий пріоритет).
|
||||
- `install.preferBrew`: якщо `true`, надає перевагу інсталяторам Homebrew, коли `brew`
|
||||
доступний, перш ніж переходити до інших типів інсталяторів.
|
||||
- `install.nodeManager`: пріоритет node-інсталятора для специфікацій `metadata.openclaw.install`
|
||||
- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/workspace skills не зачіпаються).
|
||||
- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет).
|
||||
- `install.preferBrew`: коли `true`, віддає перевагу інсталяторам Homebrew, якщо `brew`
|
||||
доступний, перед переходом до інших типів інсталяторів.
|
||||
- `install.nodeManager`: пріоритет інсталятора Node для специфікацій `metadata.openclaw.install`
|
||||
(`npm` | `pnpm` | `yarn` | `bun`).
|
||||
- `entries.<skillKey>.enabled: false` вимикає Skill, навіть якщо він bundled/встановлений.
|
||||
- `entries.<skillKey>.apiKey`: зручне поле для Skills, які оголошують основну env-змінну (рядок у відкритому тексті або об’єкт SecretRef).
|
||||
- `entries.<skillKey>.enabled: false` вимикає skill, навіть якщо він bundled/встановлений.
|
||||
- `entries.<skillKey>.apiKey`: зручне поле для skills, що оголошують основну змінну середовища (рядок відкритого тексту або об’єкт SecretRef).
|
||||
|
||||
---
|
||||
|
||||
## Plugin
|
||||
## Плагіни
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -160,42 +160,42 @@ bundled каналів (автентифікація, контроль дост
|
||||
```
|
||||
|
||||
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, а також `plugins.load.paths`.
|
||||
- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, зокрема пакети Claude стандартного макета без manifest.
|
||||
- **Зміни конфігурації потребують перезапуску gateway.**
|
||||
- `allow`: необов’язковий список дозволу (завантажуються лише перелічені Plugin). `deny` має пріоритет.
|
||||
- `plugins.entries.<id>.apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує).
|
||||
- `plugins.entries.<id>.env`: карта env-змінних у межах Plugin.
|
||||
- `plugins.entries.<id>.hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють промпт, зі старого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hook Plugin і підтримуваних каталогів hook, наданих пакетами.
|
||||
- `plugins.entries.<id>.hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих hook, як-от `llm_input`, `llm_output` і `agent_end`.
|
||||
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряє цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових subagent.
|
||||
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише якщо навмисно хочете дозволити будь-яку модель.
|
||||
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного Plugin OpenClaw, якщо вона доступна).
|
||||
- Налаштування облікових записів/runtime для channel Plugin розміщуються в `channels.<id>` і мають описуватися метаданими `channelConfigs` у manifest відповідного Plugin, а не центральним реєстром параметрів OpenClaw.
|
||||
- Виявлення приймає нативні плагіни OpenClaw, а також сумісні набори Codex і Claude, зокрема набори Claude стандартного макета без маніфесту.
|
||||
- **Зміни конфігурації вимагають перезапуску Gateway.**
|
||||
- `allow`: необов’язковий список дозволу (завантажуються лише перелічені плагіни). `deny` має пріоритет.
|
||||
- `plugins.entries.<id>.apiKey`: зручне поле API-ключа на рівні плагіна (коли підтримується плагіном).
|
||||
- `plugins.entries.<id>.env`: мапа змінних середовища в області плагіна.
|
||||
- `plugins.entries.<id>.hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, зі застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks плагіна та підтримуваних каталогів hooks, які надаються bundle.
|
||||
- `plugins.entries.<id>.hooks.allowConversationAccess`: коли `true`, довірені небандловані плагіни можуть читати необроблений вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output` і `agent_end`.
|
||||
- `plugins.entries.<id>.subagent.allowModelOverride`: явна довіра цьому плагіну запитувати перевизначення `provider` і `model` для кожного запуску фонових підзапусків subagent.
|
||||
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель.
|
||||
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений плагіном (перевіряється схемою нативного плагіна OpenClaw, якщо доступна).
|
||||
- Налаштування облікових записів/середовища виконання для плагінів каналів розміщуються в `channels.<id>` і мають описуватися метаданими `channelConfigs` у маніфесті плагіна-власника, а не центральним реєстром параметрів OpenClaw.
|
||||
- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl.
|
||||
- `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Використовує як резервне значення `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`.
|
||||
- `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`).
|
||||
- `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`).
|
||||
- `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні).
|
||||
- `timeoutSeconds`: тайм-аут запиту на скрапінг у секундах (типово: `60`).
|
||||
- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok).
|
||||
- `enabled`: увімкнути провайдера X Search.
|
||||
- `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує як запасний варіант `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`.
|
||||
- `baseUrl`: базова URL-адреса API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`).
|
||||
- `onlyMainContent`: витягувати лише основний вміст сторінок (за замовчуванням: `true`).
|
||||
- `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні).
|
||||
- `timeoutSeconds`: тайм-аут запиту scrape у секундах (за замовчуванням: `60`).
|
||||
- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (пошук у вебі Grok).
|
||||
- `enabled`: увімкнути провайдер X Search.
|
||||
- `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`).
|
||||
- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів.
|
||||
- `enabled`: головний перемикач dreaming (типово `false`).
|
||||
- `frequency`: Cron-розклад для кожного повного циклу dreaming (типово `"0 3 * * *"`).
|
||||
- політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації).
|
||||
- Повна конфігурація пам’яті розміщена в [Memory configuration reference](/uk/reference/memory-config):
|
||||
- `plugins.entries.memory-core.config.dreaming`: налаштування Dreaming для пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів.
|
||||
- `enabled`: головний перемикач Dreaming (за замовчуванням `false`).
|
||||
- `frequency`: частота Cron для кожного повного циклу Dreaming (за замовчуванням `"0 3 * * *"`).
|
||||
- політика фаз і пороги є деталями реалізації (не призначені для користувацьких ключів конфігурації).
|
||||
- Повна конфігурація пам’яті наведена в [Memory configuration reference](/uk/reference/memory-config):
|
||||
- `agents.defaults.memorySearch.*`
|
||||
- `memory.backend`
|
||||
- `memory.citations`
|
||||
- `memory.qmd.*`
|
||||
- `plugins.entries.memory-core.config.dreaming`
|
||||
- Увімкнені Plugin-пакети Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw.
|
||||
- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті.
|
||||
- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типове значення — `"legacy"`, доки ви не встановите й не виберете інший рушій.
|
||||
- `plugins.installs`: метадані встановлення, керовані CLI та використовувані `openclaw plugins update`.
|
||||
- Містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
|
||||
- Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручного редагування.
|
||||
- Увімкнені bundle-плагіни Claude також можуть надавати вбудовані стандартні значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як необроблені патчі конфігурації OpenClaw.
|
||||
- `plugins.slots.memory`: вибрати id активного плагіна пам’яті або `"none"`, щоб вимкнути плагіни пам’яті.
|
||||
- `plugins.slots.contextEngine`: вибрати id активного плагіна механізму контексту; за замовчуванням `"legacy"`, якщо ви не встановите та не виберете інший механізм.
|
||||
- `plugins.installs`: метадані встановлення, якими керує CLI і які використовуються `openclaw plugins update`.
|
||||
- Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
|
||||
- Розглядайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI замість ручного редагування.
|
||||
|
||||
Див. [Plugins](/uk/tools/plugin).
|
||||
|
||||
@ -251,31 +251,31 @@ bundled каналів (автентифікація, контроль дост
|
||||
- `tabCleanup` очищає відстежувані вкладки основного агента після простою або коли
|
||||
сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб
|
||||
вимкнути ці окремі режими очищення.
|
||||
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тож навігація браузера типово залишається суворою.
|
||||
- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі.
|
||||
- У суворому режимі віддалені кінцеві точки профілю CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення.
|
||||
- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім.
|
||||
- У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
|
||||
- Віддалені профілі працюють лише в режимі під’єднання (start/stop/reset вимкнені).
|
||||
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням залишається строгою.
|
||||
- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли свідомо довіряєте навігації браузера в приватній мережі.
|
||||
- У строгому режимі віддалені кінцеві точки профілю CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок досяжності/виявлення.
|
||||
- `ssrfPolicy.allowPrivateNetwork` і надалі підтримується як застарілий псевдонім.
|
||||
- У строгому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
|
||||
- Віддалені профілі працюють лише в режимі attach-only (запуск/зупинка/скидання вимкнені).
|
||||
- `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`.
|
||||
Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S),
|
||||
коли ваш провайдер надає прямий URL DevTools WebSocket.
|
||||
- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть під’єднуватися
|
||||
на вибраному хості або через під’єднаний вузол браузера.
|
||||
- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний
|
||||
Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S),
|
||||
коли ваш провайдер надає пряму URL-адресу DevTools WebSocket.
|
||||
- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на
|
||||
вибраному хості або через підключений browser node.
|
||||
- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний
|
||||
профіль браузера на базі Chromium, наприклад Brave або Edge.
|
||||
- Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP:
|
||||
дії на основі snapshot/ref замість націлювання за CSS-селекторами, hook завантаження
|
||||
одного файлу, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без
|
||||
`responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій.
|
||||
- Для профілів `existing-session` зберігаються поточні обмеження маршруту Chrome MCP:
|
||||
дії на основі snapshot/ref замість націлювання за CSS-селекторами, hooks
|
||||
для завантаження одного файлу, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без
|
||||
`responsebody`, експорту PDF, перехоплення завантажень або пакетних дій.
|
||||
- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно
|
||||
задавайте `cdpUrl` лише для віддаленого CDP.
|
||||
- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний
|
||||
`browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у
|
||||
Chrome, а інший — у Brave.
|
||||
- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
Chrome, а інший у Brave.
|
||||
- Порядок автовиявлення: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- `browser.executablePath` приймає `~` для домашнього каталогу вашої ОС.
|
||||
- Служба керування: лише local loopback (порт визначається з `gateway.port`, типово `18791`).
|
||||
- Служба керування: лише local loopback (порт визначається з `gateway.port`, за замовчуванням `18791`).
|
||||
- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад,
|
||||
`--disable-gpu`, розмір вікна або прапорці налагодження).
|
||||
|
||||
@ -295,8 +295,8 @@ bundled каналів (автентифікація, контроль дост
|
||||
}
|
||||
```
|
||||
|
||||
- `seamColor`: акцентний колір для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо).
|
||||
- `assistant`: перевизначення ідентичності для Control UI. Використовує ідентичність активного агента як запасний варіант.
|
||||
- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо).
|
||||
- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента.
|
||||
|
||||
---
|
||||
|
||||
@ -373,67 +373,67 @@ bundled каналів (автентифікація, контроль дост
|
||||
|
||||
<Accordion title="Докладно про поля Gateway">
|
||||
|
||||
- `mode`: `local` (запустити gateway) або `remote` (під’єднатися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`.
|
||||
- `mode`: `local` (запуск gateway) або `remote` (підключення до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`.
|
||||
- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
|
||||
- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`.
|
||||
- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
|
||||
- **Примітка щодо Docker**: типовий bind `loopback` слухає на `127.0.0.1` усередині контейнера. Із bridge-мережею Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недоступний. Використовуйте `--network host` або задайте `bind: "lan"` (чи `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах.
|
||||
- **Auth**: типово обов’язкова. Bind не на loopback потребують auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (зокрема через SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск і процеси встановлення/відновлення сервісу завершуються помилкою, коли налаштовано обидва значення, а режим не задано.
|
||||
- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках onboarding.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з урахуванням ідентичності та довіряє заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють auth trusted-proxy.
|
||||
- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth за заголовками Tailscale; натомість вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокенний потік передбачає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`.
|
||||
- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожної IP-адреси клієнта і для кожної області auth окремо (shared-secret і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`.
|
||||
- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні хибні спроби від того самого клієнта можуть спровокувати обмеження вже на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності.
|
||||
- `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо свідомо хочете, щоб трафік localhost теж підлягав rate limit (для тестових налаштувань або суворих proxy-розгортань).
|
||||
- Спроби WS auth із походження браузера завжди обмежуються, і виняток для loopback вимкнено (додатковий рівень захисту від brute force localhost із браузера).
|
||||
- На loopback ці блокування для браузерних походжень ізолюються за нормалізованим значенням `Origin`,
|
||||
тож повторні невдачі з одного походження localhost не блокують автоматично
|
||||
інше походження.
|
||||
- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, потребує auth).
|
||||
- `controlUi.allowedOrigins`: явний список дозволених browser-origin для WebSocket-підключень до Gateway. Обов’язковий, коли очікуються браузерні клієнти з не-loopback походжень.
|
||||
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервну логіку походження через заголовок Host для розгортань, що навмисно покладаються на політику походження Host-header.
|
||||
- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`.
|
||||
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення через
|
||||
змінну середовища процесу, яке дозволяє незашифрований `ws://` до довірених IP
|
||||
приватної мережі; типово незашифрований трафік і далі дозволено лише для loopback. Еквівалента в
|
||||
`openclaw.json` немає, а конфігурація приватної мережі браузера, така як
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів
|
||||
WebSocket Gateway.
|
||||
- `gateway.remote.token` / `.password`: це поля облікових даних віддаленого клієнта. Вони самі собою не налаштовують auth gateway.
|
||||
- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього APNs relay, який використовується офіційними/TestFlight збірками iOS після того, як вони публікують реєстрації relay-backed у gateway. Цей URL має збігатися з URL relay, скомпільованим у збірку iOS.
|
||||
- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типове значення: `10000`.
|
||||
- Реєстрації relay-backed делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає до gateway дозвіл на надсилання в межах цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback HTTP URL relay. У production URL relay мають залишатися на HTTPS.
|
||||
- `gateway.channelHealthCheckMinutes`: інтервал монітора стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора стану. Типове значення: `5`.
|
||||
- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`.
|
||||
- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис протягом ковзної години. Типове значення: `10`.
|
||||
- `channels.<provider>.healthMonitor.enabled`: вимкнення на рівні каналу для перезапусків монітора стану за збереження глобального монітора увімкненим.
|
||||
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу.
|
||||
- `bind`: `auto`, `loopback` (за замовчуванням), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`.
|
||||
- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
|
||||
- **Примітка щодо Docker**: bind `loopback` за замовчуванням слухає `127.0.0.1` усередині контейнера. З мережею Docker bridge (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недосяжний. Використовуйте `--network host` або задайте `bind: "lan"` (або `bind: "custom"` із `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах.
|
||||
- **Автентифікація**: обов’язкова за замовчуванням. Bind не через loopback вимагають автентифікації gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу за замовчуванням генерує token.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Під час запуску та у потоках встановлення/відновлення служби виникає помилка, якщо задано обидва, а mode не вказано.
|
||||
- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках онбордингу.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: делегує автентифікацію reverse proxy з урахуванням ідентичності та довіряє заголовкам ідентичності з `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють вимоги trusted-proxy auth.
|
||||
- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю автентифікацію через заголовки Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей безтокенний потік передбачає, що хост gateway є довіреним. За замовчуванням `true`, коли `tailscale.mode = "serve"`.
|
||||
- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожної IP-адреси клієнта та для кожної області автентифікації (спільний секрет і токен пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`.
|
||||
- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні хибні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві пройшли як звичайні розбіжності.
|
||||
- `gateway.auth.rateLimit.exemptLoopback` за замовчуванням має значення `true`; задайте `false`, якщо свідомо хочете, щоб трафік localhost також підлягав rate limit (для тестових налаштувань або суворих розгортань proxy).
|
||||
- Спроби WS-автентифікації з джерелом browser завжди обмежуються з вимкненим винятком для loopback (додатковий захист від brute force localhost через браузер).
|
||||
- На loopback ці блокування з джерелом browser ізольовані для кожного нормалізованого значення `Origin`,
|
||||
тому повторні невдачі з одного localhost origin не блокують автоматично
|
||||
інший origin.
|
||||
- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потрібна автентифікація).
|
||||
- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти з origin не через loopback.
|
||||
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для розгортань, що свідомо покладаються на політику origin за заголовком Host.
|
||||
- `remote.transport`: `ssh` (за замовчуванням) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`.
|
||||
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення в змінних
|
||||
середовища клієнтського процесу, яке дозволяє незашифрований `ws://` до довірених IP-адрес
|
||||
приватної мережі; за замовчуванням незашифрований трафік і надалі обмежено лише loopback. Еквівалента в `openclaw.json`
|
||||
немає, а конфігурація приватної мережі браузера, така як
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнти
|
||||
Gateway WebSocket.
|
||||
- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію gateway.
|
||||
- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у gateway. Ця URL-адреса має збігатися з URL relay, скомпільованою у збірку iOS.
|
||||
- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. За замовчуванням `10000`.
|
||||
- Реєстрації з підтримкою relay делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає до gateway дозвіл на надсилання в межах цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення в env для наведеної вище конфігурації relay.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний виняток для URL relay через HTTP на loopback. URL relay у продакшні мають залишатися на HTTPS.
|
||||
- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health monitor. За замовчуванням: `5`.
|
||||
- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`.
|
||||
- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health monitor на канал/обліковий запис у ковзному часовому вікні однієї години. За замовчуванням: `10`.
|
||||
- `channels.<provider>.healthMonitor.enabled`: вимкнення перезапусків health monitor для окремого каналу зі збереженням увімкненого глобального монітора.
|
||||
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: перевизначення на рівні окремого облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням рівня каналу.
|
||||
- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано.
|
||||
- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається розв’язати, розв’язання завершується в режимі fail-closed (без маскування резервним віддаленим шляхом).
|
||||
- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки пересланого клієнта. Вказуйте лише proxy, які ви контролюєте. Записи loopback і далі є дійсними для налаштувань proxy на тому ж хості / локального виявлення (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типове значення `false` для поведінки fail-closed.
|
||||
- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого pairing пристрою Node без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення ролі, області доступу, метаданих або відкритого ключа.
|
||||
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування списків дозволу/заборони для оголошених команд Node після pairing та обчислення списку дозволу.
|
||||
- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон).
|
||||
- `gateway.tools.allow`: вилучає назви інструментів із типового списку заборон HTTP.
|
||||
- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і їх не вдалося розв’язати, розв’язання завершується за принципом fail closed (без маскування резервним віддаленим шляхом).
|
||||
- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки forwarded-client. Указуйте лише proxy, якими ви керуєте. Записи loopback залишаються дійсними для налаштувань proxy/local-detection на тому ж хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. За замовчуванням `false` для поведінки fail closed.
|
||||
- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволу CIDR/IP для автоматичного схвалення першого pairing пристрою node без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично pairing для operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, областей доступу, метаданих або відкритого ключа.
|
||||
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд node після pairing і перевірки списку дозволу.
|
||||
- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює список заборон за замовчуванням).
|
||||
- `gateway.tools.allow`: прибирає назви інструментів зі списку HTTP-заборон за замовчуванням.
|
||||
|
||||
</Accordion>
|
||||
|
||||
### OpenAI-сумісні кінцеві точки
|
||||
### Сумісні з OpenAI кінцеві точки
|
||||
|
||||
- Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
|
||||
- Chat Completions: за замовчуванням вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
|
||||
- Responses API: `gateway.http.endpoints.responses.enabled`.
|
||||
- Посилене захист URL-входів Responses:
|
||||
- Посилене захищення URL-входів Responses:
|
||||
- `gateway.http.endpoints.responses.maxUrlParts`
|
||||
- `gateway.http.endpoints.responses.files.urlAllowlist`
|
||||
- `gateway.http.endpoints.responses.images.urlAllowlist`
|
||||
Порожні списки дозволу трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false`
|
||||
і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання за URL.
|
||||
та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL.
|
||||
- Необов’язковий заголовок посиленого захисту відповіді:
|
||||
- `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-походжень, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
|
||||
- `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, якими ви керуєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
|
||||
|
||||
### Ізоляція кількох екземплярів
|
||||
|
||||
@ -465,11 +465,11 @@ openclaw gateway --port 19001
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`).
|
||||
- `autoGenerate`: автоматично генерує локальну самопідписану пару сертифікат/ключ, якщо явні файли не налаштовано; лише для local/dev.
|
||||
- `certPath`: шлях у файловій системі до файлу TLS-сертифіката.
|
||||
- `keyPath`: шлях у файловій системі до файлу приватного TLS-ключа; обмежте дозволи доступу.
|
||||
- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або власних ланцюжків довіри.
|
||||
- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`).
|
||||
- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для local/dev.
|
||||
- `certPath`: шлях файлової системи до файлу TLS-сертифіката.
|
||||
- `keyPath`: шлях файлової системи до файлу приватного TLS-ключа; обмежуйте дозволи доступу.
|
||||
- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або користувацьких ланцюжків довіри.
|
||||
|
||||
### `gateway.reload`
|
||||
|
||||
@ -479,19 +479,19 @@ openclaw gateway --port 19001
|
||||
reload: {
|
||||
mode: "hybrid", // off | restart | hot | hybrid
|
||||
debounceMs: 500,
|
||||
deferralTimeoutMs: 300000,
|
||||
deferralTimeoutMs: 0,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `mode`: керує тим, як зміни конфігурації застосовуються під час виконання.
|
||||
- `"off"`: ігнорувати зміни наживо; зміни потребують явного перезапуску.
|
||||
- `"restart"`: завжди перезапускати процес gateway при зміні конфігурації.
|
||||
- `mode`: визначає, як зміни конфігурації застосовуються під час виконання.
|
||||
- `"off"`: ігнорувати зміни наживо; зміни вимагають явного перезапуску.
|
||||
- `"restart"`: завжди перезапускати процес gateway після зміни конфігурації.
|
||||
- `"hot"`: застосовувати зміни в процесі без перезапуску.
|
||||
- `"hybrid"` (типово): спочатку пробувати hot reload; за потреби повертатися до перезапуску.
|
||||
- `"hybrid"` (за замовчуванням): спочатку намагатися виконати hot reload; за потреби переходити до перезапуску.
|
||||
- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
|
||||
- `deferralTimeoutMs`: максимальний час очікування в мс для операцій у процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин).
|
||||
- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення операцій у процесі перед примусовим перезапуском. Не вказуйте його або задайте `0`, щоб чекати необмежено довго й періодично журналювати попередження про те, що ще є незавершені операції.
|
||||
|
||||
---
|
||||
|
||||
@ -528,39 +528,39 @@ openclaw gateway --port 19001
|
||||
}
|
||||
```
|
||||
|
||||
Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
Токени hook у рядку запиту відхиляються.
|
||||
Автентифікація: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
Hook-токени в query string відхиляються.
|
||||
|
||||
Примітки щодо валідації та безпеки:
|
||||
|
||||
- `hooks.enabled=true` потребує непорожнього `hooks.token`.
|
||||
- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється.
|
||||
- `hooks.enabled=true` вимагає непорожній `hooks.token`.
|
||||
- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється.
|
||||
- `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`.
|
||||
- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`).
|
||||
- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping цього opt-in не потребують.
|
||||
- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього явного дозволу.
|
||||
|
||||
**Кінцеві точки:**
|
||||
|
||||
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
|
||||
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
|
||||
- `sessionKey` з тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`).
|
||||
- `sessionKey` з тіла запиту приймається лише коли `hooks.allowRequestSessionKey=true` (за замовчуванням: `false`).
|
||||
- `POST /hooks/<name>` → розв’язується через `hooks.mappings`
|
||||
- Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`.
|
||||
- Значення `sessionKey` у mapping, згенеровані через шаблони, вважаються наданими ззовні й також вимагають `hooks.allowRequestSessionKey=true`.
|
||||
|
||||
<Accordion title="Докладно про mapping">
|
||||
|
||||
- `match.path` зіставляється з підшляхом після `/hooks` (наприклад, `/hooks/gmail` → `gmail`).
|
||||
- `match.source` зіставляється з полем payload для загальних шляхів.
|
||||
- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload.
|
||||
- `transform` може вказувати на JS/TS-модуль, який повертає дію hook.
|
||||
- `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються).
|
||||
- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового.
|
||||
- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не задано = дозволити всі, `[]` = заборонити всі).
|
||||
- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків агента з hook без явного `sessionKey`.
|
||||
- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і session key mapping, керованим шаблоном, задавати `sessionKey` (типово: `false`).
|
||||
- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`).
|
||||
- `match.source` зіставляє поле в тілі запиту для загальних шляхів.
|
||||
- Шаблони на кшталт `{{messages[0].subject}}` читають значення з тіла запиту.
|
||||
- `transform` може вказувати на модуль JS/TS, що повертає дію hook.
|
||||
- `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються).
|
||||
- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до стандартного.
|
||||
- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не вказано = дозволити все, `[]` = заборонити все).
|
||||
- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`.
|
||||
- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії mapping на основі шаблонів задавати `sessionKey` (за замовчуванням: `false`).
|
||||
- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`.
|
||||
- `deliver: true` надсилає фінальну відповідь у канал; типове значення `channel` — `last`.
|
||||
- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей).
|
||||
- `deliver: true` надсилає фінальну відповідь у канал; `channel` за замовчуванням має значення `last`.
|
||||
- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -568,7 +568,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
- Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`.
|
||||
- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`.
|
||||
- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого значення.
|
||||
- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного значення за замовчуванням.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -591,7 +591,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути.
|
||||
- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути це.
|
||||
- Не запускайте окремий `gog gmail watch serve` паралельно з Gateway.
|
||||
|
||||
---
|
||||
@ -608,18 +608,18 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Обслуговує редаговані агентом HTML/CSS/JS та A2UI через HTTP на порту Gateway:
|
||||
- Обслуговує HTML/CSS/JS і A2UI, які агент може редагувати, через HTTP на порту Gateway:
|
||||
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
|
||||
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
|
||||
- Лише локально: зберігайте `gateway.bind: "loopback"` (типово).
|
||||
- Bind не на loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
|
||||
- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення вузла Gateway рекламує URL можливостей у межах вузла для доступу до canvas/A2UI.
|
||||
- URL можливостей прив’язані до активної WS-сесії вузла і швидко спливають. Резервний варіант на основі IP не використовується.
|
||||
- Впроваджує клієнт live-reload у HTML, що обслуговується.
|
||||
- Лише локально: зберігайте `gateway.bind: "loopback"` (за замовчуванням).
|
||||
- Для bind не через loopback: маршрути canvas вимагають автентифікації Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
|
||||
- Node WebView зазвичай не надсилають заголовки автентифікації; після pairing і підключення node Gateway рекламує URL-адреси можливостей у межах node для доступу до canvas/A2UI.
|
||||
- URL-адреси можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується.
|
||||
- Вбудовує клієнт live reload у HTML, що обслуговується.
|
||||
- Автоматично створює стартовий `index.html`, якщо каталог порожній.
|
||||
- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`.
|
||||
- Зміни потребують перезапуску gateway.
|
||||
- Вимкніть live reload для великих каталогів або при помилках `EMFILE`.
|
||||
- Зміни вимагають перезапуску gateway.
|
||||
- Вимикайте live reload для великих каталогів або при помилках `EMFILE`.
|
||||
|
||||
---
|
||||
|
||||
@ -637,9 +637,9 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів.
|
||||
- `minimal` (за замовчуванням): не включає `cliPath` + `sshPort` у TXT-записи.
|
||||
- `full`: включає `cliPath` + `sshPort`.
|
||||
- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`.
|
||||
- Ім’я хоста за замовчуванням — `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`.
|
||||
|
||||
### Wide-area (DNS-SD)
|
||||
|
||||
@ -651,7 +651,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
Записує унікаст-зону DNS-SD до `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS.
|
||||
Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS.
|
||||
|
||||
Налаштування: `openclaw dns setup --apply`.
|
||||
|
||||
@ -659,7 +659,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
## Середовище
|
||||
|
||||
### `env` (вбудовані env-змінні)
|
||||
### `env` (вбудовані змінні середовища)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -676,14 +676,14 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній ключ.
|
||||
- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні).
|
||||
- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої оболонки входу.
|
||||
- Вбудовані змінні середовища застосовуються лише якщо в середовищі процесу відсутній цей ключ.
|
||||
- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні).
|
||||
- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell.
|
||||
- Повний порядок пріоритету див. у [Environment](/uk/help/environment).
|
||||
|
||||
### Підстановка env-змінних
|
||||
### Підстановка змінних середовища
|
||||
|
||||
Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`:
|
||||
Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -695,18 +695,18 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
|
||||
- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації.
|
||||
- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`.
|
||||
- Екрануйте через `$${VAR}` для буквального `${VAR}`.
|
||||
- Працює з `$include`.
|
||||
|
||||
---
|
||||
|
||||
## Секрети
|
||||
|
||||
Посилання на секрети є додатковими: значення у відкритому тексті й далі працюють.
|
||||
Посилання на секрети є адитивними: значення відкритим текстом і надалі працюють.
|
||||
|
||||
### `SecretRef`
|
||||
|
||||
Використовуйте один формат об’єкта:
|
||||
Використовуйте одну форму об’єкта:
|
||||
|
||||
```json5
|
||||
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
|
||||
@ -715,16 +715,16 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
Валідація:
|
||||
|
||||
- шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$`
|
||||
- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
|
||||
- `source: "file"` id: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
|
||||
- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
|
||||
- id для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад, `a/../b` відхиляється)
|
||||
- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
|
||||
- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
|
||||
- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
|
||||
- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад, `a/../b` відхиляється)
|
||||
|
||||
### Підтримувана поверхня облікових даних
|
||||
|
||||
- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface)
|
||||
- `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`.
|
||||
- Посилання в `auth-profiles.json` включено до runtime-розв’язання та покриття аудиту.
|
||||
- Посилання в `auth-profiles.json` включені до розв’язання під час виконання та охоплення аудиту.
|
||||
|
||||
### Конфігурація провайдерів секретів
|
||||
|
||||
@ -756,18 +756,18 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`).
|
||||
- Шляхи провайдерів file і exec завершуються в режимі fail-closed, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які не можна перевірити.
|
||||
- Провайдер `exec` потребує абсолютного шляху `command` і використовує payload протоколу через stdin/stdout.
|
||||
- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою розв’язаного цільового шляху.
|
||||
- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`).
|
||||
- Шляхи провайдерів file та exec завершуються за принципом fail closed, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити.
|
||||
- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout.
|
||||
- За замовчуванням шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки з перевіркою розв’язаного цільового шляху.
|
||||
- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху.
|
||||
- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`.
|
||||
- Посилання на секрети розв’язуються під час активації в snapshot у пам’яті, після чого шляхи запитів читають лише цей snapshot.
|
||||
- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.
|
||||
- Дочірнє середовище `exec` за замовчуванням мінімальне; явно передавайте потрібні змінні через `passEnv`.
|
||||
- Посилання на секрети розв’язуються під час активації у знімок у пам’яті, а потім шляхи запитів читають лише цей знімок.
|
||||
- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.
|
||||
|
||||
---
|
||||
|
||||
## Сховище auth
|
||||
## Сховище автентифікації
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -787,11 +787,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
- Профілі для кожного агента зберігаються в `<agentDir>/auth-profiles.json`.
|
||||
- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних.
|
||||
- Профілі режиму OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef.
|
||||
- Статичні runtime-облікові дані надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищуються після виявлення.
|
||||
- Застарілі імпорти OAuth надходять із `~/.openclaw/credentials/oauth.json`.
|
||||
- Профілі режиму OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані профілю автентифікації на основі SecretRef.
|
||||
- Статичні облікові дані runtime надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються після виявлення.
|
||||
- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`.
|
||||
- Див. [OAuth](/uk/concepts/oauth).
|
||||
- Runtime-поведінка секретів та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets).
|
||||
- Поведінка runtime для секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets).
|
||||
|
||||
### `auth.cooldowns`
|
||||
|
||||
@ -813,24 +813,24 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг може
|
||||
і далі потрапляти сюди навіть у відповідях `401`/`403`, але зіставлення
|
||||
тексту, специфічні для провайдера, залишаються в межах відповідного провайдера
|
||||
(наприклад OpenRouter `Key limit exceeded`). Повторювані HTTP `402` повідомлення про usage-window або
|
||||
ліміт витрат organization/workspace залишаються в гілці `rate_limit`
|
||||
натомість.
|
||||
- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу для кожного провайдера.
|
||||
- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff білінгу (типово: `24`).
|
||||
- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (типово: `10`).
|
||||
- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`).
|
||||
- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`).
|
||||
- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Форми зайнятості провайдера, такі як `ModelNotReadyException`, потрапляють сюди.
|
||||
- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`).
|
||||
- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок rate limit перед перемиканням на резервну модель (типово: `1`). Цей кошик rate limit включає текстові форми провайдерів, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
|
||||
- `billingBackoffHours`: базова затримка повторної спроби в годинах, коли профіль завершується через справжні
|
||||
помилки білінгу/недостатнього кредиту (за замовчуванням: `5`). Явний текст про білінг
|
||||
усе ще може потрапляти сюди навіть у відповідях `401`/`403`, але текстові
|
||||
зіставлення, специфічні для провайдера, залишаються в межах провайдера, якому вони належать (наприклад, OpenRouter
|
||||
`Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage window або
|
||||
ліміт витрат organization/workspace натомість залишаються в шляху `rate_limit`.
|
||||
- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин затримки білінгу для окремих провайдерів.
|
||||
- `billingMaxHours`: максимальна межа в годинах для експоненційного зростання затримки білінгу (за замовчуванням: `24`).
|
||||
- `authPermanentBackoffMinutes`: базова затримка в хвилинах для високодостовірних збоїв `auth_permanent` (за замовчуванням: `10`).
|
||||
- `authPermanentMaxMinutes`: максимальна межа в хвилинах для зростання затримки `auth_permanent` (за замовчуванням: `60`).
|
||||
- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників затримок (за замовчуванням: `24`).
|
||||
- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед переходом до резервної моделі (за замовчуванням: `1`). Сюди потрапляють форми зайнятості провайдера, такі як `ModelNotReadyException`.
|
||||
- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`).
|
||||
- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate limit перед переходом до резервної моделі (за замовчуванням: `1`). Цей кошик rate limit включає тексти у формі провайдера, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
|
||||
|
||||
---
|
||||
|
||||
## Логування
|
||||
## Журналювання
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -845,10 +845,10 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
|
||||
- Установіть `logging.file` для стабільного шляху.
|
||||
- `consoleLevel` підвищується до `debug` із `--verbose`.
|
||||
- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів.
|
||||
- Файл журналу за замовчуванням: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
|
||||
- Задайте `logging.file` для стабільного шляху.
|
||||
- `consoleLevel` підвищується до `debug` з `--verbose`.
|
||||
- `maxFileBytes`: максимальний розмір файлу журналу в байтах, після якого запис пригнічується (додатне ціле число; за замовчуванням: `524288000` = 500 MB). Для продакшн-розгортань використовуйте зовнішню ротацію журналів.
|
||||
|
||||
---
|
||||
|
||||
@ -893,22 +893,22 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: головний перемикач для виводу інструментування (типово: `true`).
|
||||
- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує wildcard, як-от `"telegram.*"` або `"*"`).
|
||||
- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, доки сесія залишається у стані обробки.
|
||||
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`).
|
||||
- `enabled`: головний перемикач для виводу інструментування (за замовчуванням: `true`).
|
||||
- `flags`: масив рядків-прапорців, що вмикають цільовий вивід логів (підтримуються шаблони з wildcard, як-от `"telegram.*"` або `"*"`).
|
||||
- `stuckSessionWarnMs`: поріг віку в мс для виводу попереджень про завислі сесії, поки сесія залишається у стані обробки.
|
||||
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (за замовчуванням: `false`).
|
||||
- `otel.endpoint`: URL колектора для експорту OTel.
|
||||
- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`.
|
||||
- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel.
|
||||
- `otel.serviceName`: назва сервісу для атрибутів ресурсу.
|
||||
- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт trace, metrics або log.
|
||||
- `otel.sampleRate`: частота семплування trace `0`–`1`.
|
||||
- `otel.protocol`: `"http/protobuf"` (за замовчуванням) або `"grpc"`.
|
||||
- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються разом із запитами експорту OTel.
|
||||
- `otel.serviceName`: назва служби для атрибутів ресурсу.
|
||||
- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт trace, metrics або logs.
|
||||
- `otel.sampleRate`: частота вибірки trace `0`–`1`.
|
||||
- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс.
|
||||
- `otel.captureContent`: opt-in захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, окрім system; форма об’єкта дозволяє явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`.
|
||||
- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, зберігаючи активними слухачі діагностики.
|
||||
- `cacheTrace.enabled`: журналювати snapshot cache trace для вбудованих запусків (типово: `false`).
|
||||
- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
|
||||
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі типово: `true`).
|
||||
- `otel.captureContent`: явний дозвіл на захоплення необробленого вмісту для атрибутів span OTEL. За замовчуванням вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім системного; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`.
|
||||
- `OPENCLAW_OTEL_PRELOADED=1`: прапорець середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить плагіну, зберігаючи активними діагностичні слухачі.
|
||||
- `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (за замовчуванням: `false`).
|
||||
- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (за замовчуванням: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
|
||||
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі за замовчуванням: `true`).
|
||||
|
||||
---
|
||||
|
||||
@ -930,12 +930,12 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`.
|
||||
- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`).
|
||||
- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`).
|
||||
- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням для каналу stable (типово: `6`; макс.: `168`).
|
||||
- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable у годинах (типово: `12`; макс.: `168`).
|
||||
- `auto.betaCheckIntervalHours`: як часто виконуються перевірки для каналу beta, у годинах (типово: `1`; макс.: `24`).
|
||||
- `channel`: канал релізу для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`.
|
||||
- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (за замовчуванням: `true`).
|
||||
- `auto.enabled`: увімкнути фонове автооновлення для пакетних установлень (за замовчуванням: `false`).
|
||||
- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для каналу stable (за замовчуванням: `6`; макс.: `168`).
|
||||
- `auto.stableJitterHours`: додаткове вікно розподілу розгортання каналу stable в годинах (за замовчуванням: `12`; макс.: `168`).
|
||||
- `auto.betaCheckIntervalHours`: як часто виконуються перевірки каналу beta, у годинах (за замовчуванням: `1`; макс.: `24`).
|
||||
|
||||
---
|
||||
|
||||
@ -968,22 +968,22 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: глобальний feature gate ACP (типово: `false`).
|
||||
- `dispatch.enabled`: незалежний gate для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання.
|
||||
- `backend`: id типового backend runtime ACP (має збігатися із зареєстрованим runtime Plugin ACP).
|
||||
- `enabled`: глобальний feature gate для ACP (за замовчуванням: `false`).
|
||||
- `dispatch.enabled`: незалежний gate для dispatch ходів ACP-сесії (за замовчуванням: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося.
|
||||
- `backend`: id backend середовища виконання ACP за замовчуванням (має відповідати зареєстрованому runtime plugin ACP).
|
||||
- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль.
|
||||
- `allowedAgents`: список дозволу id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень.
|
||||
- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP.
|
||||
- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту.
|
||||
- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блока.
|
||||
- `stream.repeatSuppression`: пригнічує повторювані рядки статусу/інструментів на кожному ході (типово: `true`).
|
||||
- `stream.deliveryMode`: `"live"` інкрементально транслює; `"final_only"` буферизує до термінальних подій ходу.
|
||||
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`).
|
||||
- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, проєктованих на один хід ACP.
|
||||
- `allowedAgents`: список дозволу id агентів, дозволених для ACP runtime sessions; порожнє значення означає відсутність додаткових обмежень.
|
||||
- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій.
|
||||
- `stream.coalesceIdleMs`: вікно скидання простою в мс для потокового тексту.
|
||||
- `stream.maxChunkChars`: максимальний розмір блоку перед розбиттям проєкції потокового блока.
|
||||
- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів на хід (за замовчуванням: `true`).
|
||||
- `stream.deliveryMode`: `"live"` передає поступово; `"final_only"` буферизує до термінальних подій ходу.
|
||||
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (за замовчуванням: `"paragraph"`).
|
||||
- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, проєктованих на один ACP-хід.
|
||||
- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP.
|
||||
- `stream.tagVisibility`: запис назв тегів у булеві перевизначення видимості для потокових подій.
|
||||
- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до можливого очищення.
|
||||
- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP.
|
||||
- `stream.tagVisibility`: запис імен тегів у булеві перевизначення видимості для потокових подій.
|
||||
- `runtime.ttlMinutes`: TTL простою в хвилинах для ACP session workers до можливого очищення.
|
||||
- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища виконання ACP.
|
||||
|
||||
---
|
||||
|
||||
@ -999,17 +999,17 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `cli.banner.taglineMode` керує стилем підрядка банера:
|
||||
- `"random"` (типово): ротаційні кумедні/сезонні підрядки.
|
||||
- `"default"`: фіксований нейтральний підрядок (`Усі ваші чати — в одному OpenClaw.`).
|
||||
- `"off"`: без тексту підрядка (назва/версія банера все одно показуються).
|
||||
- Щоб приховати весь банер (а не лише підрядки), задайте env `OPENCLAW_HIDE_BANNER=1`.
|
||||
- `cli.banner.taglineMode` керує стилем слогана банера:
|
||||
- `"random"` (за замовчуванням): ротаційні кумедні/сезонні слогани.
|
||||
- `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`).
|
||||
- `"off"`: без тексту слогана (заголовок/версія банера все одно показуються).
|
||||
- Щоб приховати весь банер (не лише слогани), задайте env `OPENCLAW_HIDE_BANNER=1`.
|
||||
|
||||
---
|
||||
|
||||
## Wizard
|
||||
|
||||
Метадані, які записуються керованими CLI потоками налаштування (`onboard`, `configure`, `doctor`):
|
||||
Метадані, які записуються керованими потоками налаштування CLI (`onboard`, `configure`, `doctor`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1027,13 +1027,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
## Ідентичність
|
||||
|
||||
Див. поля ідентичності `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults).
|
||||
Див. поля ідентичності `agents.list` у [Agent defaults](/uk/gateway/config-agents#agent-defaults).
|
||||
|
||||
---
|
||||
|
||||
## Bridge (застарілий, видалений)
|
||||
## Bridge (застаріле, вилучено)
|
||||
|
||||
Поточні збірки більше не включають TCP bridge. Nodes під’єднуються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
|
||||
Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
|
||||
|
||||
<Accordion title="Застаріла конфігурація bridge (історична довідка)">
|
||||
|
||||
@ -1073,11 +1073,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: як довго зберігати завершені ізольовані сесії запуску Cron перед видаленням із `sessions.json`. Також керує очищенням архівованих видалених transcript Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути.
|
||||
- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/<jobId>.jsonl`) перед обрізанням. Типово: `2_000_000` байтів.
|
||||
- `runLog.keepLines`: кількість найновіших рядків, що зберігаються при спрацьовуванні обрізання журналу запуску. Типово: `2000`.
|
||||
- `webhookToken`: bearer token, який використовується для POST-доставки Webhook Cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається.
|
||||
- `webhook`: застарілий резервний URL Webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`.
|
||||
- `sessionRetention`: як довго зберігати завершені ізольовані сесії виконання cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. За замовчуванням: `24h`; задайте `false`, щоб вимкнути.
|
||||
- `runLog.maxBytes`: максимальний розмір файлу журналу одного запуску (`cron/runs/<jobId>.jsonl`) перед очищенням. За замовчуванням: `2_000_000` байт.
|
||||
- `runLog.keepLines`: кількість найновіших рядків, що зберігаються під час очищення журналу запуску. За замовчуванням: `2000`.
|
||||
- `webhookToken`: bearer token, що використовується для доставлення cron Webhook POST (`delivery.mode = "webhook"`); якщо не вказано, заголовок автентифікації не надсилається.
|
||||
- `webhook`: застаріла резервна URL-адреса Webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`.
|
||||
|
||||
### `cron.retry`
|
||||
|
||||
@ -1093,11 +1093,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`).
|
||||
- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів).
|
||||
- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не задавайте, щоб повторювати всі тимчасові типи.
|
||||
- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (за замовчуванням: `3`; діапазон: `0`–`10`).
|
||||
- `backoffMs`: масив затримок повторних спроб у мс для кожної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів).
|
||||
- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати для всіх тимчасових типів.
|
||||
|
||||
Застосовується лише до одноразових завдань Cron. Періодичні завдання використовують окрему обробку збоїв.
|
||||
Застосовується лише до одноразових cron-завдань. Періодичні завдання використовують окрему обробку збоїв.
|
||||
|
||||
### `cron.failureAlert`
|
||||
|
||||
@ -1115,11 +1115,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`).
|
||||
- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`).
|
||||
- `enabled`: увімкнути сповіщення про збої для cron-завдань (за замовчуванням: `false`).
|
||||
- `after`: кількість послідовних збоїв перед спрацьовуванням сповіщення (додатне ціле число, мін.: `1`).
|
||||
- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число).
|
||||
- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook.
|
||||
- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщень.
|
||||
- `mode`: режим доставлення — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook.
|
||||
- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставлення сповіщень.
|
||||
|
||||
### `cron.failureDestination`
|
||||
|
||||
@ -1136,51 +1136,51 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Типове місце призначення для сповіщень про збої Cron для всіх завдань.
|
||||
- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо цільових даних.
|
||||
- `channel`: перевизначення каналу для доставки через announce. `"last"` повторно використовує останній відомий канал доставки.
|
||||
- `to`: явна ціль announce або URL Webhook. Обов’язкове для режиму webhook.
|
||||
- `accountId`: необов’язкове перевизначення облікового запису для доставки.
|
||||
- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення.
|
||||
- Коли не задано ні глобальне, ні на рівні завдання місце призначення для збоїв, завдання, які вже доставляють через `announce`, при збої повертаються до цієї основної цілі announce.
|
||||
- Стандартний пункт призначення для сповіщень про збої cron для всіх завдань.
|
||||
- `mode`: `"announce"` або `"webhook"`; за замовчуванням `"announce"`, коли є достатньо даних цілі.
|
||||
- `channel`: перевизначення каналу для доставлення announce. `"last"` повторно використовує останній відомий канал доставлення.
|
||||
- `to`: явна ціль announce або URL-адреса Webhook. Обов’язкове для режиму webhook.
|
||||
- `accountId`: необов’язкове перевизначення облікового запису для доставлення.
|
||||
- `delivery.failureDestination` на рівні завдання перевизначає це глобальне значення за замовчуванням.
|
||||
- Коли не задано ні глобальний, ні окремий пункт призначення для збою, завдання, які вже доставляють через `announce`, у разі збою використовують як резервний варіант цю основну ціль announce.
|
||||
- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`.
|
||||
|
||||
Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [background tasks](/uk/automation/tasks).
|
||||
Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks).
|
||||
|
||||
---
|
||||
|
||||
## Змінні шаблону моделі медіа
|
||||
## Змінні шаблонів медіамоделі
|
||||
|
||||
Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`:
|
||||
Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`:
|
||||
|
||||
| Variable | Опис |
|
||||
| ------------------ | ------------------------------------------------------- |
|
||||
| `{{Body}}` | Повний текст вхідного повідомлення |
|
||||
| `{{RawBody}}` | Сирий текст повідомлення (без обгорток історії/відправника) |
|
||||
| `{{BodyStripped}}` | Текст повідомлення без згадок групи |
|
||||
| `{{From}}` | Ідентифікатор відправника |
|
||||
| `{{To}}` | Ідентифікатор призначення |
|
||||
| `{{MessageSid}}` | Ідентифікатор повідомлення каналу |
|
||||
| `{{SessionId}}` | UUID поточної сесії |
|
||||
| `{{IsNewSession}}` | `"true"`, коли створено нову сесію |
|
||||
| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
|
||||
| `{{MediaPath}}` | Локальний шлях до медіа |
|
||||
| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
|
||||
| `{{Transcript}}` | Транскрипт аудіо |
|
||||
| `{{Prompt}}` | Розв’язаний медіапромпт для записів CLI |
|
||||
| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI |
|
||||
| `{{ChatType}}` | `"direct"` або `"group"` |
|
||||
| `{{GroupSubject}}` | Назва групи (за можливості) |
|
||||
| `{{GroupMembers}}` | Попередній перегляд учасників групи (за можливості) |
|
||||
| `{{SenderName}}` | Відображуване ім’я відправника (за можливості) |
|
||||
| `{{SenderE164}}` | Номер телефону відправника (за можливості) |
|
||||
| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) |
|
||||
| Змінна | Опис |
|
||||
| ----------------- | --------------------------------------------------- |
|
||||
| `{{Body}}` | Повний текст вхідного повідомлення |
|
||||
| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) |
|
||||
| `{{BodyStripped}}` | Текст без згадок у групі |
|
||||
| `{{From}}` | Ідентифікатор відправника |
|
||||
| `{{To}}` | Ідентифікатор отримувача |
|
||||
| `{{MessageSid}}` | ID повідомлення каналу |
|
||||
| `{{SessionId}}` | UUID поточної сесії |
|
||||
| `{{IsNewSession}}` | `"true"`, коли створено нову сесію |
|
||||
| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
|
||||
| `{{MediaPath}}` | Локальний шлях до медіа |
|
||||
| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
|
||||
| `{{Transcript}}` | Транскрипт аудіо |
|
||||
| `{{Prompt}}` | Розв’язаний media prompt для записів CLI |
|
||||
| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI |
|
||||
| `{{ChatType}}` | `"direct"` або `"group"` |
|
||||
| `{{GroupSubject}}` | Назва групи (best effort) |
|
||||
| `{{GroupMembers}}` | Попередній список учасників групи (best effort) |
|
||||
| `{{SenderName}}` | Відображуване ім’я відправника (best effort) |
|
||||
| `{{SenderE164}}` | Номер телефону відправника (best effort) |
|
||||
| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) |
|
||||
|
||||
---
|
||||
|
||||
## Include конфігурації (`$include`)
|
||||
## Включення конфігурації (`$include`)
|
||||
|
||||
Розділіть конфігурацію на кілька файлів:
|
||||
Розділяйте конфігурацію на кілька файлів:
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
@ -1196,13 +1196,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
**Поведінка злиття:**
|
||||
|
||||
- Один файл: замінює об’єкт-контейнер.
|
||||
- Масив файлів: глибоко зливається в заданому порядку (пізніші перевизначають попередні).
|
||||
- Сусідні ключі: зливаються після include (перевизначають включені значення).
|
||||
- Вкладені include: до 10 рівнів глибини.
|
||||
- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми й форми `../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в цих межах.
|
||||
- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підтриманий include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін.
|
||||
- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів, керованих OpenClaw; такі записи завершуються в режимі fail-closed замість сплощення конфігурації.
|
||||
- Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних include.
|
||||
- Масив файлів: виконується глибоке злиття за порядком (пізніші перевизначають попередні).
|
||||
- Сусідні ключі: зливаються після включень (перевизначають включені значення).
|
||||
- Вкладені включення: до 10 рівнів глибини.
|
||||
- Шляхи: розв’язуються відносно файла, який включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в межах цієї границі.
|
||||
- Записи, якими керує OpenClaw, що змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін.
|
||||
- Кореневі включення, масиви включень і включення з перевизначеннями сусідніх ключів доступні лише для читання для записів, якими керує OpenClaw; такі записи завершуються за принципом fail closed замість сплощення конфігурації.
|
||||
- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних включень.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user