openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 04:50:34 +00:00
parent aa27364593
commit bfedbe14ae
13 changed files with 1668 additions and 1535 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
docs/uk/automation/cron-jobs.md
View File

@ -4,18 +4,18 @@ read_when:
- Підключення зовнішніх тригерів (Webhook, Gmail) до OpenClaw
- Вибір між Heartbeat і Cron для запланованих завдань
sidebarTitle: Scheduled tasks
summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway
summary: Заплановані завдання, Webhook і тригери Gmail PubSub для планувальника Gateway
title: Заплановані завдання
x-i18n:
generated_at: "2026-04-29T15:58:21Z"
generated_at: "2026-05-02T04:47:26Z"
model: gpt-5.5
provider: openai
source_hash: 021e623bdea786178e0948e9905360c897c26d31fdf866e9af8cfc9538968d60
source_hash: cdda94c3c31e4530e0944cd8f5667a7eb567fcff8e602d6a86d5699d078e9b48
source_path: automation/cron-jobs.md
workflow: 16
---
Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента у потрібний час і може доставляти результат назад у канал чату або кінцеву точку webhook.
Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може доставляти результат назад у канал чату або кінцеву точку Webhook.
## Швидкий старт
@ -44,43 +44,43 @@ Cron — це вбудований планувальник Gateway. Він зб
</Step>
</Steps>
## Як працює cron
## Як працює Cron
- Cron працює **всередині процесу Gateway** (не всередині моделі).
- Cron виконується **всередині процесу Gateway** (не всередині моделі).
- Визначення завдань зберігаються в `~/.openclaw/cron/jobs.json`, тому перезапуски не втрачають розклади.
- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json` і додайте `jobs-state.json` до gitignore.
- Після розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть вважати завдання новими, бо поля runtime тепер містяться в `jobs-state.json`.
- Коли `jobs.json` редагується під час роботи або зупинки Gateway, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного runtime-слота й очищує застарілі значення `nextRunAtMs`. Суто форматування або переписування лише порядку ключів зберігають очікуваний слот.
- Усі виконання cron створюють записи [фонового завдання](/uk/automation/tasks).
- Під час запуску Gateway прострочені ізольовані завдання agent-turn переплановуються за межі вікна підключення каналу, а не відтворюються негайно, тому запуск Discord/Telegram і налаштування нативних команд залишаються чуйними після перезапусків.
- Одноразові завдання (`--at`) за замовчуванням автоматично видаляються після успішного виконання.
- Ізольовані запуски cron за можливості закривають відстежувані вкладки/процеси браузера для свого сеансу `cron:<jobId>` після завершення запуску, щоб від'єднана автоматизація браузера не залишала осиротілих процесів.
- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат є лише проміжним оновленням стану (`on it`, `pulling everything together` і подібні підказки), а жоден дочірній запуск субагента вже не відповідає за фінальну відповідь, OpenClaw один раз повторно запитує фактичний результат перед доставкою.
- Ізольовані запуски cron спершу віддають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім переходять до відомих маркерів фінального підсумку/виводу, таких як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не повідомлялася як успішний запуск.
- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть коли payload відповіді не створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій, а не очищують завдання як успішне.
- Коли ізольоване завдання agent-turn досягає `timeoutSeconds`, cron перериває базовий запуск агента й дає йому коротке вікно для очищення. Якщо запуск не завершує спорожнення, очищення, яким володіє Gateway, примусово очищує володіння сеансом цього запуску до того, як cron запише тайм-аут, щоб робота з черги чату не залишалася за застарілим сеансом обробки.
- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення Cron у git, відстежуйте `jobs.json` і додайте `jobs-state.json` до gitignore.
- Після розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть вважати завдання новими, бо поля стану виконання тепер містяться в `jobs-state.json`.
- Коли `jobs.json` редагують, поки Gateway працює або зупинений, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного runtime-слота й очищає застарілі значення `nextRunAtMs`. Суто форматувальні зміни або переписування лише порядку ключів зберігають очікуваний слот.
- Усі виконання Cron створюють записи [фонового завдання](/uk/automation/tasks).
- Під час запуску Gateway прострочені ізольовані завдання ходу агента переплановуються за межі вікна підключення каналів замість негайного повторного відтворення, тому запуск Discord/Telegram і налаштування нативних команд залишаються чуйними після перезапусків.
- Одноразові завдання (`--at`) типово автоматично видаляються після успішного виконання.
- Ізольовані запуски Cron у режимі найкращої спроби закривають відстежувані вкладки браузера/процеси для їхньої сесії `cron:<jobId>` після завершення запуску, щоб від’єднана браузерна автоматизація не залишала осиротілих процесів.
- Ізольовані запуски Cron також захищають від застарілих відповідей-підтверджень. Якщо перший результат є лише проміжним оновленням статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw один раз повторно запитує фактичний результат перед доставкою.
- Ізольовані запуски Cron спершу віддають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім повертаються до відомих маркерів фінального підсумку/виводу, як-от `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не звітувалася як успішний запуск.
- Ізольовані запуски Cron також трактують помилки агента на рівні запуску як помилки завдання, навіть коли не створено payload відповіді, тому помилки моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій замість очищення завдання як успішного.
- Коли ізольоване завдання ходу агента досягає `timeoutSeconds`, Cron перериває базовий запуск агента й дає йому коротке вікно для очищення. Якщо запуск не завершує спорожнення, очищення, яким володіє Gateway, примусово очищає володіння сесією цього запуску перед тим, як Cron записує тайм-аут, щоб робота чату в черзі не залишалася за застарілою сесією обробки.
<a id="maintenance"></a>
<Note>
Узгодження завдань для cron спершу належить runtime, а потім спирається на довготривалу історію: активне завдання cron залишається live, доки runtime cron ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірнього сеансу ще існує. Щойно runtime перестає володіти завданням і 5-хвилинне пільгове вікно спливає, обслуговування перевіряє збережені журнали запусків і стан завдання для відповідного запуску `cron:<jobId>:<startedAt>`. Якщо ця довготривала історія показує термінальний результат, журнал завдань фіналізується з нього; інакше обслуговування, яким володіє Gateway, може позначити завдання як `lost`. Офлайн-аудит CLI може відновлюватися з довготривалої історії, але він не трактує власний порожній in-process набір активних завдань як доказ того, що запуск cron, яким володіє Gateway, зник.
Узгодження завдань для Cron спочатку належить runtime, а вже потім спирається на довговічну історію: активне завдання Cron залишається живим, поки runtime Cron усе ще відстежує це завдання як запущене, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і 5-хвилинне пільгове вікно спливає, перевірки обслуговування переглядають збережені журнали запусків і стан завдання для відповідного запуску `cron:<jobId>:<startedAt>`. Якщо ця довговічна історія показує термінальний результат, журнал завдань фіналізується з нього; інакше обслуговування, яким володіє Gateway, може позначити завдання як `lost`. Офлайн-аудит CLI може відновитися з довговічної історії, але він не трактує власну порожню множину активних завдань у процесі як доказ того, що запуск Cron, яким володіє Gateway, зник.
</Note>
## Типи розкладів
| Тип | Прапорець CLI | Опис |
| Вид | Прапорець CLI | Опис |
| ------- | ------------- | ------------------------------------------------------- |
| `at` | `--at` | Одноразова позначка часу (ISO 8601 або відносна, як-от `20m`) |
| `every` | `--every` | Фіксований інтервал |
| `cron` | `--cron` | 5-польовий або 6-польовий вираз cron з необов'язковим `--tz` |
| `at` | `--at` | Одноразова часова мітка (ISO 8601 або відносна, як `20m`) |
| `every` | `--every` | Фіксований інтервал |
| `cron` | `--cron` | 5-польовий або 6-польовий вираз Cron з необов’язковим `--tz` |
Позначки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом.
Часові мітки без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом.
Повторювані вирази на початку години автоматично розподіляються з розкидом до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна.
Повторювані вирази на початку години автоматично розносяться до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна.
### День місяця й день тижня використовують логіку OR
Вирази cron розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли поля дня місяця й дня тижня обидва не є шаблонами, croner збігається, коли збігається **будь-яке** з полів, а не обидва. Це стандартна поведінка Vixie cron.
Вирази Cron розбираються [croner](https://github.com/Hexagon/croner). Коли поля дня місяця й дня тижня обидва не є wildcard, croner спрацьовує, коли збігається **будь-яке** з полів, а не обидва. Це стандартна поведінка Vixie cron.
```
# Intended: "9 AM on the 15th, only if it's a Monday"
@ -88,34 +88,34 @@ Cron — це вбудований планувальник Gateway. Він зб
0 9 15 * 1
```
Це спрацьовує приблизно 5-6 разів на місяць замість 0-1 разу на місяць. OpenClaw тут використовує стандартну поведінку OR від Croner. Щоб вимагати виконання обох умов, використовуйте модифікатор дня тижня `+` від Croner (`0 9 15 * +1`) або плануйте за одним полем і перевіряйте інше у prompt чи команді завдання.
Це спрацьовує приблизно 5–6 разів на місяць замість 0–1 разу на місяць. OpenClaw тут використовує типову поведінку OR від Croner. Щоб вимагати обидві умови, використовуйте модифікатор дня тижня `+` від Croner (`0 9 15 * +1`) або плануйте за одним полем і перевіряйте інше в prompt чи команді вашого завдання.
## Стилі виконання
| Стиль | Значення `--session` | Виконується в | Найкраще для |
| --------------- | -------------------- | ------------------------- | ------------------------------- |
| Основний сеанс | `main` | Наступний heartbeat turn | Нагадування, системні події |
| Ізольований | `isolated` | Виділений `cron:<jobId>` | Звіти, фонові службові роботи |
| Поточний сеанс | `current` | Прив'язаний під час створення | Періодична робота з урахуванням контексту |
| Власний сеанс | `session:custom-id` | Постійний іменований сеанс | Робочі процеси, що спираються на історію |
| Стиль | Значення `--session` | Де виконується | Найкраще для |
| --------------- | -------------------- | ---------------------- | ------------------------------- |
| Основна сесія | `main` | Наступний хід Heartbeat | Нагадування, системні події |
| Ізольовано | `isolated` | Окремий `cron:<jobId>` | Звіти, фонові рутинні завдання |
| Поточна сесія | `current` | Прив’язується під час створення | Повторювана робота з урахуванням контексту |
| Власна сесія | `session:custom-id` | Постійна іменована сесія | Робочі процеси, що будуються на історії |
<AccordionGroup>
<Accordion title="Основний сеанс, ізольований і власний">
Завдання **основного сеансу** ставлять системну подію в чергу й за потреби пробуджують heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують свіжість щоденного/idle-скидання для цільового сеансу. **Ізольовані** завдання виконують виділений agent turn зі свіжим сеансом. **Власні сеанси** (`session:xxx`) зберігають контекст між запусками, уможливлюючи робочі процеси на кшталт щоденних стендапів, що спираються на попередні підсумки.
<Accordion title="Основна сесія, ізольована чи власна">
Завдання **основної сесії** ставлять у чергу системну подію й необов’язково пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують свіжість щоденного/простою скидання для цільової сесії. **Ізольовані** завдання виконують окремий хід агента зі свіжою сесією. **Власні сесії** (`session:xxx`) зберігають контекст між запусками, уможливлюючи робочі процеси на кшталт щоденних стендапів, що спираються на попередні підсумки.
</Accordion>
<Accordion title="Що означає «свіжий сеанс» для ізольованих завдань">
Для ізольованих завдань «свіжий сеанс» означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явні вибрані користувачем перевизначення моделі/автентифікації, але не успадковує навколишній контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання або черги, підвищення, origin чи прив'язку ACP runtime. Використовуйте `current` або `session:<id>`, коли повторюване завдання має навмисно спиратися на той самий контекст розмови.
<Accordion title="Що означає «свіжа сесія» для ізольованих завдань">
Для ізольованих завдань «свіжа сесія» означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні вподобання, як-от налаштування thinking/fast/verbose, мітки та явні вибрані користувачем перевизначення моделі/auth, але не успадковує навколишній контекст розмови зі старішого рядка Cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищення прав, походження або runtime-прив’язку ACP. Використовуйте `current` або `session:<id>`, коли повторюване завдання має навмисно будуватися на тому самому контексті розмови.
</Accordion>
<Accordion title="Очищення runtime">
Для ізольованих завдань демонтаж runtime тепер включає best-effort очищення браузера для цього сеансу cron. Помилки очищення ігноруються, щоб фактичний результат cron все одно мав пріоритет.
Для ізольованих завдань демонтаж runtime тепер включає best-effort очищення браузера для цієї сесії Cron. Помилки очищення ігноруються, щоб фактичний результат Cron усе одно мав пріоритет.
Ізольовані запуски cron також утилізують будь-які bundled MCP runtime instances, створені для завдання, через спільний шлях runtime-cleanup. Це відповідає тому, як демонтуються MCP-клієнти основного сеансу й власного сеансу, тому ізольовані завдання cron не залишають stdio дочірні процеси або довгоживучі MCP-з'єднання між запусками.
Ізольовані запуски Cron також утилізують будь-які bundled MCP runtime instances, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як клієнти MCP основної сесії та власної сесії демонтуються, тому ізольовані завдання Cron не протікають stdio child processes або довгоживучими MCP-з’єднаннями між запусками.
</Accordion>
<Accordion title="Субагент і доставка Discord">
Коли ізольовані запуски cron оркеструють субагентів, доставка також віддає перевагу фінальному виводу нащадка над застарілим проміжним текстом батьківського запуску. Якщо нащадки ще виконуються, OpenClaw пригнічує це часткове оновлення батьківського запуску замість того, щоб оголошувати його.
<Accordion title="Доставка субагента та Discord">
Коли ізольовані запуски Cron оркеструють субагентів, доставка також віддає перевагу фінальному виводу нащадка над застарілим проміжним текстом батьківського запуску. Якщо нащадки усе ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість його оголошення.
Для текстових цілей оголошення Discord OpenClaw надсилає канонічний фінальний текст асистента один раз замість повторного відтворення і streamed/intermediate текстових payload, і фінальної відповіді. Медіа та структуровані payload Discord все ще доставляються як окремі payload, щоб вкладення й компоненти не губилися.
Для text-only цілей оголошення Discord OpenClaw надсилає канонічний фінальний текст асистента один раз замість повторного відтворення і streamed/intermediate text payloads, і фінальної відповіді. Медіа та структуровані Discord payloads усе ще доставляються як окремі payloads, щоб вкладення й компоненти не губилися.
</Accordion>
</AccordionGroup>
@ -123,7 +123,7 @@ Cron — це вбудований планувальник Gateway. Він зб
### Параметри payload для ізольованих завдань
<ParamField path="--message" type="string" required>
Текст prompt (обов'язковий для ізольованого).
Текст prompt (обов’язковий для ізольованих).
</ParamField>
<ParamField path="--model" type="string">
Перевизначення моделі; використовує вибрану дозволену модель для завдання.
@ -132,55 +132,57 @@ Cron — це вбудований планувальник Gateway. Він зб
Перевизначення рівня thinking.
</ParamField>
<ParamField path="--light-context" type="boolean">
Пропустити ін'єкцію bootstrap-файла робочої області.
Пропустити ін’єкцію bootstrap-файлів робочого простору.
</ParamField>
<ParamField path="--tools" type="string">
Обмежити, які інструменти може використовувати завдання, наприклад `--tools exec,read`.
</ParamField>
`--model` використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення `/model` сеансу чату: налаштовані ланцюжки fallback все ще застосовуються, коли основна модель завдання зазнає збою. Якщо запитана модель не дозволена або не може бути визначена, cron завершує запуск із явною помилкою валідації замість тихого fallback до вибору моделі агента/за замовчуванням для завдання.
`--model` використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення `/model` для чат-сесії: налаштовані ланцюги fallback усе ще застосовуються, коли основна модель завдання зазнає збою. Якщо запитана модель не дозволена або її неможливо розв’язати, Cron завершує запуск із явною помилкою валідації замість тихого fallback до вибору моделі агента/типової моделі завдання.
Завдання Cron також можуть містити `fallbacks` на рівні payload. Коли він присутній, цей список замінює налаштований ланцюжок fallback для завдання. Використовуйте `fallbacks: []` у payload/API завдання, коли потрібен строгий запуск cron, який пробує лише вибрану модель. Якщо завдання має `--model`, але не має fallback ні в payload, ні в конфігурації, OpenClaw передає явне порожнє перевизначення fallback, щоб основна модель агента не додавалася як прихована додаткова ціль повторної спроби.
Завдання Cron також можуть мати `fallbacks` на рівні payload. Коли він присутній, цей список замінює налаштований ланцюг fallback для завдання. Використовуйте `fallbacks: []` у payload/API завдання, коли потрібен строгий запуск Cron, який пробує лише вибрану модель. Якщо завдання має `--model`, але не має ані payload fallback, ані налаштованих fallback, OpenClaw передає явне порожнє перевизначення fallback, щоб основна модель агента не додавалася як прихована додаткова ціль повторної спроби.
Пріоритет вибору моделі для ізольованих завдань:
1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене)
1. Перевизначення моделі Gmail hook (коли запуск прийшов із Gmail і це перевизначення дозволене)
2. `model` у payload конкретного завдання
3. Збережене вибране користувачем перевизначення моделі сеансу cron
4. Вибір моделі агента/за замовчуванням
3. Збережене перевизначення моделі сесії Cron, вибране користувачем
4. Вибір моделі агента/типової моделі
Fast mode також наслідує resolved live selection. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron використовує це за замовчуванням. Збережене перевизначення `fastMode` сеансу все одно має пріоритет над конфігурацією в будь-якому напрямку.
Fast mode також дотримується розв’язаного live-вибору. Якщо конфіг вибраної моделі має `params.fastMode`, ізольований Cron типово використовує його. Збережене перевизначення `fastMode` сесії все ще має пріоритет над конфігом в обох напрямках.
Якщо ізольований запуск потрапляє на live model-switch handoff, cron повторює спробу з перемкненим провайдером/моделлю і зберігає цей live selection для активного запуску перед повторною спробою. Коли перемикання також містить новий auth profile, cron також зберігає це перевизначення auth profile для активного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб перемикання cron переривається замість нескінченного циклу.
Якщо ізольований запуск потрапляє на live model-switch handoff, Cron повторює спробу з перемкненим провайдером/моделлю й зберігає цей live-вибір для активного запуску перед повторною спробою. Коли перемикання також переносить новий auth profile, Cron зберігає і це перевизначення auth profile для активного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторні спроби перемикання Cron переривається замість нескінченного циклу.
Перед тим як ізольований запуск cron входить у runner агента, OpenClaw перевіряє доступні локальні кінцеві точки провайдерів для налаштованих провайдерів `api: "ollama"` і `api: "openai-completions"`, чий `baseUrl` є loopback, private-network або `.local`. Якщо ця кінцева точка не працює, запуск записується як `skipped` із чіткою помилкою провайдера/моделі замість початку виклику моделі. Результат кінцевої точки кешується на 5 хвилин, тому багато прострочених завдань, що використовують той самий непрацюючий локальний сервер Ollama, vLLM, SGLang або LM Studio, ділять одну невелику перевірку замість створення шторму запитів. Пропущені provider-preflight запуски не збільшують backoff помилок виконання; увімкніть `failureAlert.includeSkipped`, якщо хочете повторювані сповіщення про пропуск.
Перш ніж ізольований запуск Cron увійде до runner агента, OpenClaw перевіряє досяжні локальні кінцеві точки провайдера для налаштованих провайдерів `api: "ollama"` і `api: "openai-completions"`, чиї `baseUrl` є loopback, приватною мережею або `.local`. Якщо ця кінцева точка недоступна, запуск записується як `skipped` з чіткою помилкою провайдера/моделі замість запуску model call. Результат кінцевої точки кешується на 5 хвилин, тому багато належних до виконання завдань, що використовують той самий мертвий локальний сервер Ollama, vLLM, SGLang або LM Studio, спільно використовують одну невелику перевірку замість створення шторму запитів. Пропущені provider-preflight запуски не збільшують execution-error backoff; увімкніть `failureAlert.includeSkipped`, коли хочете повторювані сповіщення про пропуск.
## Доставка й вивід
## Доставка та вивід
| Режим | Що відбувається |
| ---------- | ------------------------------------------------------------------ |
| `announce` | Fallback-доставляє фінальний текст до цілі, якщо агент не надіслав |
| `webhook` | POST payload події завершення на URL |
| `none` | Немає fallback-доставки runner |
| Режим | Що відбувається |
| ---------- | ----------------------------------------------------------------- |
| `announce` | Fallback-доставка фінального тексту до цілі, якщо агент не надіслав |
| `webhook` | POST payload завершеної події на URL |
| `none` | Немає fallback-доставки runner |
Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`; прямі виклики RPC/config також можуть передавати `delivery.threadId` як рядок або число. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:<id>`, `user:<id>`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ID кімнати або форму `room:!room:server` з Matrix.
Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форумів Telegram використовуйте `-1001234567890:topic:123`; прямі RPC/config-викликачі також можуть передавати `delivery.threadId` як рядок або число. Цілі Slack/Discord/Mattermost мають використовувати явні префікси (`channel:<id>`, `user:<id>`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ідентифікатор кімнати або форму `room:!room:server` з Matrix.
Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` керують лише тим, що runner робить із фінальною відповіддю після ходу агента.
Коли доставка оголошення використовує `channel: "last"` або пропускає `channel`, ціль із префіксом провайдера, як-от `telegram:123`, може вибрати канал до того, як cron повернеться до історії сесії або одного налаштованого каналу. Лише префікси, оголошені завантаженим plugin, є селекторами провайдера. Якщо `delivery.channel` задано явно, префікс цілі має називати того самого провайдера; наприклад, `channel: "whatsapp"` із `to: "telegram:123"` відхиляється замість того, щоб дозволити WhatsApp інтерпретувати ідентифікатор Telegram як номер телефону. Префікси типу цілі та сервісу, як-от `channel:<id>`, `user:<id>`, `imessage:<handle>` і `sms:<number>`, залишаються синтаксисом цілей, що належить каналу, а не селекторами провайдера.
Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену поточну ціль доставки для резервного маршруту оголошення. Внутрішні ключі сесій можуть бути в нижньому регістрі; цілі доставки провайдера не реконструюються з цих ключів, коли доступний поточний контекст чату.
Для ізольованих завдань доставка в чат є спільною. Якщо доступний маршрут чату, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. Інакше `announce`, `webhook` і `none` керують лише тим, що runner робить із фінальною відповіддю після ходу агента.
Сповіщення про збої використовують окремий шлях призначення:
Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену живу ціль доставки для резервного маршруту оголошення. Внутрішні ключі сесій можуть бути в нижньому регістрі; цілі доставки провайдера не відновлюються з цих ключів, коли доступний поточний контекст чату.
- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про збої.
Сповіщення про помилки використовують окремий шлях призначення:
- `cron.failureDestination` задає глобальне типове призначення для сповіщень про помилки.
- `job.delivery.failureDestination` перевизначає його для окремого завдання.
- Якщо жодне з них не задано, а завдання вже доставляє через `announce`, сповіщення про збої тепер повертаються до цієї основної цілі оголошення.
- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`.
- `failureAlert.includeSkipped: true` вмикає для завдання або глобальної політики сповіщень cron повторні сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому вони не впливають на backoff помилок виконання.
- Якщо жодне з них не задано, а завдання вже доставляє через `announce`, сповіщення про помилки тепер повертаються до цієї основної цілі оголошення.
- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`.
- `failureAlert.includeSkipped: true` вмикає для завдання або глобальної політики cron-сповіщень повторювані сповіщення про пропущені запуски. Пропущені запуски мають окремий лічильник послідовних пропусків, тому не впливають на backoff помилок виконання.
## Приклади CLI
<Tabs>
<Tab title="One-shot reminder">
<Tab title="Одноразове нагадування">
```bash
openclaw cron add \
--name "Calendar check" \
@ -190,7 +192,7 @@ Fast mode також наслідує resolved live selection. Якщо конф
--wake now
```
</Tab>
<Tab title="Recurring isolated job">
<Tab title="Повторюване ізольоване завдання">
```bash
openclaw cron add \
--name "Morning brief" \
@ -203,7 +205,7 @@ Fast mode також наслідує resolved live selection. Якщо конф
--to "channel:C1234567890"
```
</Tab>
<Tab title="Model and thinking override">
<Tab title="Перевизначення моделі та мислення">
```bash
openclaw cron add \
--name "Deep analysis" \
@ -218,9 +220,9 @@ Fast mode також наслідує resolved live selection. Якщо конф
</Tab>
</Tabs>
## Webhooks
## Webhook-и
Gateway може відкривати HTTP Webhook-ендпоїнти для зовнішніх тригерів. Увімкніть у config:
Gateway може відкривати HTTP Webhook-кінцеві точки для зовнішніх тригерів. Увімкніть у config:
```json5
{
@ -243,7 +245,7 @@ Gateway може відкривати HTTP Webhook-ендпоїнти для з
<AccordionGroup>
<Accordion title="POST /hooks/wake">
Додайте системну подію до черги для основної сесії:
Додати системну подію в чергу для основної сесії:
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
@ -261,7 +263,7 @@ Gateway може відкривати HTTP Webhook-ендпоїнти для з
</Accordion>
<Accordion title="POST /hooks/agent">
Запустіть ізольований хід агента:
Запустити ізольований хід агента:
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
@ -273,29 +275,29 @@ Gateway може відкривати HTTP Webhook-ендпоїнти для з
Поля: `message` (обов’язкове), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `fallbacks`, `thinking`, `timeoutSeconds`.
</Accordion>
<Accordion title="Mapped hooks (POST /hooks/<name>)">
Власні назви hook розв’язуються через `hooks.mappings` у config. Mappings можуть перетворювати довільні payloads на дії `wake` або `agent` за допомогою шаблонів чи перетворень коду.
<Accordion title="Зіставлені hooks (POST /hooks/<name>)">
Власні назви hook визначаються через `hooks.mappings` у config. Зіставлення можуть перетворювати довільні payload-и на дії `wake` або `agent` за допомогою шаблонів або перетворень коду.
</Accordion>
</AccordionGroup>
<Warning>
Тримайте hook-ендпоїнти за local loopback, tailnet або довіреним reverse proxy.
Тримайте кінцеві точки hook за loopback, tailnet або довіреним reverse proxy.
- Використовуйте виділений токен hook; не перевикористовуйте токени автентифікації Gateway.
- Тримайте `hooks.path` на виділеному підшляху; `/` відхиляється.
- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway.
- Тримайте `hooks.path` на окремому підшляху; `/` відхиляється.
- Задайте `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`.
- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити допустимі форми ключів сесій.
- Payloads hook за замовчуванням обгортаються межами безпеки.
- Тримайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем.
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесій.
- Payload-и hook за замовчуванням обгортаються межами безпеки.
</Warning>
## Інтеграція Gmail PubSub
Під’єднайте тригери вхідної скриньки Gmail до OpenClaw через Google PubSub.
Під’єднайте тригери вхідних Gmail до OpenClaw через Google PubSub.
<Note>
**Передумови:** CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічного HTTPS-ендпоїнта.
**Передумови:** `gcloud` CLI, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічної HTTPS-кінцевої точки.
</Note>
### Налаштування майстром (рекомендовано)
@ -304,17 +306,17 @@ Gateway може відкривати HTTP Webhook-ендпоїнти для з
openclaw webhooks gmail setup --account openclaw@gmail.com
```
Це записує config `hooks.gmail`, вмикає preset Gmail і використовує Tailscale Funnel для push-ендпоїнта.
Це записує config `hooks.gmail`, вмикає пресет Gmail і використовує Tailscale Funnel для push-кінцевої точки.
### Автозапуск Gateway
Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway запускає `gog gmail watch serve` під час завантаження та автоматично поновлює watch. Задайте `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися.
Коли `hooks.enabled=true` і `hooks.gmail.account` задано, Gateway запускає `gog gmail watch serve` під час старту й автоматично поновлює watch. Задайте `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися.
### Ручне одноразове налаштування
<Steps>
<Step title="Select the GCP project">
Виберіть проєкт GCP, якому належить клієнт OAuth, що використовується `gog`:
<Step title="Виберіть проєкт GCP">
Виберіть проєкт GCP, якому належить OAuth-клієнт, що використовується `gog`:
```bash
gcloud auth login
@ -323,7 +325,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com
```
</Step>
<Step title="Create topic and grant Gmail push access">
<Step title="Створіть topic і надайте Gmail push-доступ">
```bash
gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
@ -331,7 +333,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com
--role=roles/pubsub.publisher
```
</Step>
<Step title="Start the watch">
<Step title="Запустіть watch">
```bash
gog gmail watch start \
--account openclaw@gmail.com \
@ -387,11 +389,11 @@ openclaw cron edit <jobId> --clear-agent
Примітка щодо перевизначення моделі:
- `openclaw cron add|edit --model ...` змінює вибрану модель завдання.
- Якщо модель дозволена, точний provider/model доходить до ізольованого запуску агента.
- Якщо вона не дозволена або не може бути розв’язана, cron завершує запуск з явною помилкою валідації.
- Налаштовані fallback chains усе ще застосовуються, бо cron `--model` є основним значенням завдання, а не перевизначенням сесії `/model`.
- Payload `fallbacks` замінює налаштовані fallbacks для цього завдання; `fallbacks: []` вимикає fallback і робить запуск строгим.
- Звичайний `--model` без явного або налаштованого списку fallback не переходить до основної моделі агента як мовчазна додаткова ціль повторної спроби.
- Якщо модель дозволена, цей точний provider/model доходить до ізольованого запуску агента.
- Якщо вона не дозволена або не може бути визначена, cron завершує запуск із явною помилкою валідації.
- Налаштовані ланцюжки fallback усе ще застосовуються, бо cron `--model` є основною моделлю завдання, а не перевизначенням сесії `/model`.
- Payload `fallbacks` замінює налаштовані fallback для цього завдання; `fallbacks: []` вимикає fallback і робить запуск строгим.
- Простий `--model` без явного або налаштованого списку fallback не переходить до основної моделі агента як мовчазна додаткова ціль повтору.
</Note>
@ -415,29 +417,29 @@ openclaw cron edit <jobId> --clear-agent
}
```
`maxConcurrentRuns` обмежує як диспетчеризацію запланованих cron, так і виконання ізольованого ходу агента. Ізольовані ходи cron-агента внутрішньо використовують виділену смугу виконання черги `cron-nested`, тому збільшення цього значення дає змогу незалежним cron-запускам LLM просуватися паралельно, а не лише запускати їхні зовнішні cron-обгортки. Спільна не-cron смуга `nested` цим налаштуванням не розширюється.
`maxConcurrentRuns` обмежує і заплановану dispatch cron, і виконання ізольованих ходів агента. Ізольовані cron-ходи агента внутрішньо використовують виділену lane виконання `cron-nested` черги, тому збільшення цього значення дає змогу незалежним LLM-запускам cron просуватися паралельно, а не лише запускати їхні зовнішні cron-обгортки. Спільна не-cron lane `nested` не розширюється цим параметром.
Sidecar стану runtime виводиться з `cron.store`: сховище `.json`, як-от `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а шлях сховища без суфікса `.json` додає `-state.json`.
Стан runtime sidecar виводиться з `cron.store`: store `.json`, як-от `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, тоді як шлях store без суфікса `.json` додає `-state.json`.
Якщо ви вручну редагуєте `jobs.json`, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для pending slots, active markers, метаданих останнього запуску та ідентичності розкладу, яка повідомляє scheduler, коли зовнішньо відредаговане завдання потребує нового `nextRunAtMs`.
Якщо ви вручну редагуєте `jobs.json`, не додавайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для pending slots, active markers, метаданих останнього запуску й ідентичності розкладу, яка повідомляє scheduler, коли зовні відредагованому завданню потрібен свіжий `nextRunAtMs`.
Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`.
<AccordionGroup>
<Accordion title="Retry behavior">
**Повторна спроба одноразового завдання**: тимчасові помилки (ліміт частоти, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикають негайно.
<Accordion title="Поведінка повторів">
**Одноразовий повтор**: тимчасові помилки (rate limit, overload, network, server error) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикаються негайно.
**Повторна спроба повторюваного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску.
**Повтор для регулярних завдань**: експоненційний backoff (від 30 с до 60 хв) між повторами. Backoff скидається після наступного успішного запуску.
</Accordion>
<Accordion title="Maintenance">
`cron.sessionRetention` (за замовчуванням `24h`) очищує записи ізольованих run-session. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищують файли run-log.
<Accordion title="Обслуговування">
`cron.sessionRetention` (типово `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли run-log.
</Accordion>
</AccordionGroup>
## Усунення несправностей
### Сходи команд
### Драбина команд
```bash
openclaw status
@ -451,30 +453,30 @@ openclaw doctor
```
<AccordionGroup>
<Accordion title="Cron not firing">
<Accordion title="Cron не спрацьовує">
- Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`.
- Переконайтеся, що Gateway працює безперервно.
- Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом host.
- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run <jobId> --due`, і час завдання ще не настав.
- Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста.
- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено командою `openclaw cron run <jobId> --due`, і час завдання ще не настав.
</Accordion>
<Accordion title="Cron fired but no delivery">
- Режим доставки `none` означає, що резервне надсилання runner не очікується. Агент усе ще може надсилати напряму через інструмент `message`, коли доступний маршрут чату.
- Відсутня/недійсна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено.
- Для Matrix скопійовані або legacy завдання з ідентифікаторами кімнат `delivery.to` у нижньому регістрі можуть завершуватися помилкою, бо ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання до точного значення `!room:server` або `room:!room:server` з Matrix.
<Accordion title="Cron спрацював, але доставки немає">
- Режим доставки `none` означає, що резервне надсилання через runner не очікується. Агент усе ще може надсилати напряму за допомогою інструмента `message`, коли доступний маршрут чату.
- Відсутня або недійсна ціль доставки (`channel`/`to`) означає, що вихідне надсилання було пропущено.
- Для Matrix скопійовані або застарілі завдання з ідентифікаторами кімнат `delivery.to` у нижньому регістрі можуть завершуватися помилкою, бо ідентифікатори кімнат Matrix чутливі до регістру. Відредагуйте завдання до точного значення `!room:server` або `room:!room:server` з Matrix.
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставку заблоковано обліковими даними.
- Якщо ізольований запуск повертає лише мовчазний токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також пригнічує резервний шлях зведення в черзі, тому в чат нічого не публікується.
- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряму вихідну доставку, а також резервний шлях підсумку в черзі, тож назад у чат нічого не публікується.
- Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` з попереднім чатом або явний канал/ціль).
</Accordion>
<Accordion title="Здається, Cron або heartbeat заважає перенесенню /new-style">
- Свіжість щоденного та неактивного скидання не базується на `updatedAt`; див. [Керування сеансами](/uk/concepts/session#session-lifecycle).
- Пробудження Cron, запуски heartbeat, сповіщення exec і службові оновлення gateway можуть оновлювати рядок сеансу для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`.
- Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сеансу transcript JSONL, якщо файл досі доступний. Застарілі неактивні рядки без `lastInteractionAt` використовують цей відновлений час початку як базовий рівень неактивності.
<Accordion title="Cron або Heartbeat, здається, перешкоджає переходу /new-style">
- Свіжість щоденного та неактивного скидання не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle).
- Пробудження Cron, запуски Heartbeat, сповіщення exec і службовий облік Gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`.
- Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії transcript JSONL, коли файл досі доступний. Застарілі неактивні рядки без `lastInteractionAt` використовують цей відновлений час початку як свою базову точку неактивності.
</Accordion>
<Accordion title="Підводні камені часових поясів">
- Cron без `--tz` використовує часовий пояс хоста gateway.
- Cron без `--tz` використовує часовий пояс хоста Gateway.
- Розклади `at` без часового поясу трактуються як UTC.
- Heartbeat `activeHours` використовує налаштоване визначення часового поясу.
@ -483,7 +485,7 @@ openclaw doctor
## Пов’язане
- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації стисло
- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron
- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основного сеансу
- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації стисло
- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань Cron
- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії
- [Часовий пояс](/uk/concepts/timezone) — налаштування часового поясу

111
docs/uk/channels/channel-routing.md
View File

@ -1,93 +1,93 @@
---
read_when:
- Зміна маршрутизації каналів або поведінки вхідних повідомлень
summary: Правила маршрутизації за каналами (WhatsApp, Telegram, Discord, Slack) і спільний контекст
- Зміна маршрутизації каналів або поведінки вхідної скриньки
summary: Правила маршрутизації для кожного каналу (WhatsApp, Telegram, Discord, Slack) і спільний контекст
title: Маршрутизація каналів
x-i18n:
generated_at: "2026-04-27T20:14:58Z"
model: gpt-5.4
generated_at: "2026-05-02T04:47:10Z"
model: gpt-5.5
provider: openai
source_hash: c43347048fcfd137cc3a0b2cfdc4cf36426fdcf9645f2d1a05ce9cf49688cf0d
source_hash: 9a752696e70d2c13d3ab1c9cedd41442e0d8aee6d78b3a069b53dd2b262174da
source_path: channels/channel-routing.md
workflow: 15
workflow: 16
---
# Канали й маршрутизація
# Канали та маршрутизація
OpenClaw маршрутизує відповіді **назад у той канал, звідки надійшло повідомлення**. Модель не вибирає канал; маршрутизація є детермінованою та керується конфігурацією хоста.
OpenClaw маршрутизує відповіді **назад у канал, звідки надійшло повідомлення**. Модель не вибирає канал; маршрутизація детермінована й керується конфігурацією хоста.
## Ключові терміни
- **Канал**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, а також канали Plugin. `webchat` — це внутрішній канал інтерфейсу WebChat і не є налаштовуваним вихідним каналом.
- **AccountId**: екземпляр облікового запису в межах каналу (де підтримується).
- Необов’язковий типовий обліковий запис каналу: `channels.<channel>.defaultAccount` визначає, який обліковий запис використовується, коли вихідний шлях не вказує `accountId`.
- У конфігураціях із кількома обліковими записами встановіть явний типовий обліковий запис (`defaultAccount` або `accounts.default`), коли налаштовано два чи більше облікових записи. Без цього резервна маршрутизація може вибрати перший нормалізований ідентифікатор облікового запису.
- **AgentId**: ізольований робочий простір + сховище сесій («brain»).
- **SessionKey**: ключ сегмента, який використовується для збереження контексту та керування конкурентністю.
- **Канал**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, а також Plugin-канали. `webchat` — це внутрішній канал інтерфейсу WebChat і не є настроюваним вихідним каналом.
- **AccountId**: екземпляр облікового запису для кожного каналу (коли підтримується).
- Необов’язковий типовий обліковий запис каналу: `channels.<channel>.defaultAccount` вибирає обліковий запис, який використовується, коли вихідний шлях не вказує `accountId`.
- У конфігураціях із кількома обліковими записами задайте явний типовий обліковий запис (`defaultAccount` або `accounts.default`), коли налаштовано два чи більше облікових записів. Без цього резервна маршрутизація може вибрати перший нормалізований ідентифікатор облікового запису.
- **AgentId**: ізольований робочий простір + сховище сеансів («мозок»).
- **SessionKey**: ключ кошика, що використовується для збереження контексту й керування конкурентністю.
## Форми ключа сесії (приклади)
## Префікси вихідних цілей
Прямі повідомлення типово згортаються до **основної** сесії агента:
Явні вихідні цілі можуть містити префікс постачальника, наприклад `telegram:123` або `tg:123`. Ядро розглядає цей префікс як підказку для вибору каналу лише тоді, коли вибраний канал — `last` або інакше не визначений, і лише коли завантажений Plugin оголошує цей префікс. Якщо викликач уже вибрав явний канал, префікс постачальника має відповідати цьому каналу; міжканальні комбінації, як-от доставлення WhatsApp до `telegram:123`, завершуються помилкою ще до специфічної для Plugin нормалізації цілі.
Префікси типу цілі та сервісу, як-от `channel:<id>`, `user:<id>`, `room:<id>`, `thread:<id>`, `imessage:<handle>` і `sms:<number>`, залишаються всередині граматики вибраного каналу. Вони самі по собі не вибирають постачальника.
## Форми ключів сеансів (приклади)
Особисті повідомлення типово згортаються в **основний** сеанс агента:
- `agent:<agentId>:<mainKey>` (типово: `agent:main:main`)
Навіть коли історія розмов у прямих повідомленнях спільна з основною сесією, політика sandbox і tool використовує похідний ключ середовища виконання для прямого чату на рівні облікового запису для зовнішніх DM, щоб повідомлення, що походять із каналів, не трактувалися як локальні запуски основної сесії.
Навіть коли історія розмов з особистих повідомлень спільна з основним сеансом, пісочниця й політика інструментів використовують похідний ключ середовища виконання особистого чату для кожного облікового запису для зовнішніх особистих повідомлень, щоб повідомлення, що походять із каналів, не оброблялися як локальні запуски основного сеансу.
Групи й канали залишаються ізольованими в межах каналу:
Групи й канали залишаються ізольованими для кожного каналу:
- Групи: `agent:<agentId>:<channel>:group:<id>`
- Канали/кімнати: `agent:<agentId>:<channel>:channel:<id>`
Потоки:
Гілки:
- Потоки Slack/Discord додають `:thread:<threadId>` до базового ключа.
- Теми форумів Telegram вбудовують `:topic:<topicId>` у ключ групи.
- Гілки Slack/Discord додають `:thread:<threadId>` до базового ключа.
- Теми форуму Telegram вбудовують `:topic:<topicId>` у ключ групи.
Приклади:
- `agent:main:telegram:group:-1001234567890:topic:42`
- `agent:main:discord:channel:123456:thread:987654`
## Закріплення маршруту основних DM
## Закріплення маршруту основних особистих повідомлень
Коли `session.dmScope` має значення `main`, прямі повідомлення можуть спільно використовувати одну основну сесію.
Щоб `lastRoute` цієї сесії не перезаписувався DM від не-власника,
OpenClaw визначає закріпленого власника з `allowFrom`, якщо виконуються всі такі умови:
Коли `session.dmScope` має значення `main`, особисті повідомлення можуть спільно використовувати один основний сеанс. Щоб запобігти перезапису `lastRoute` сеансу особистими повідомленнями не від власника, OpenClaw виводить закріпленого власника з `allowFrom`, коли виконуються всі ці умови:
- `allowFrom` містить рівно один не-шаблонний запис.
- `allowFrom` має рівно один запис без символу-узагальнення.
- Запис можна нормалізувати до конкретного ідентифікатора відправника для цього каналу.
- Відправник вхідного DM не збігається з цим закріпленим власником.
- Відправник вхідного особистого повідомлення не відповідає цьому закріпленому власнику.
У разі такої невідповідності OpenClaw усе одно записує метадані вхідної сесії, але
пропускає оновлення `lastRoute` основної сесії.
У такому випадку невідповідності OpenClaw все одно записує метадані вхідного сеансу, але пропускає оновлення `lastRoute` основного сеансу.
## Захищений запис вхідних даних
## Захищене записування вхідних повідомлень
Плагіни каналів можуть позначати запис вхідної сесії як `createIfMissing: false`,
коли захищений шлях не повинен створювати нову сесію OpenClaw. У цьому режимі
OpenClaw може оновлювати метадані та `lastRoute` для наявної сесії, але
не створює запис сесії лише для маршруту тільки тому, що було виявлено повідомлення.
Channel-плагіни можуть позначати запис вхідного сеансу як `createIfMissing: false`, коли захищений шлях не має створювати новий сеанс OpenClaw. У цьому режимі OpenClaw може оновлювати метадані й `lastRoute` для наявного сеансу, але не створює запис сеансу лише для маршруту просто тому, що було помічено повідомлення.
## Правила маршрутизації (як вибирається агент)
Маршрутизація вибирає **одного агента** для кожного вхідного повідомлення:
1. **Точний збіг peer** (`bindings` з `peer.kind` + `peer.id`).
2. **Збіг батьківського peer** (успадкування потоку).
3. **Збіг guild + ролей** (Discord) через `guildId` + `roles`.
4. **Збіг guild** (Discord) через `guildId`.
5. **Збіг team** (Slack) через `teamId`.
6. **Збіг облікового запису** (`accountId` у каналі).
7. **Збіг каналу** (будь-який обліковий запис у цьому каналі, `accountId: "*"`).
8. **Типовий агент** (`agents.list[].default`, інакше перший запис у списку, резервний варіант — `main`).
1. **Точний збіг співрозмовника** (`bindings` з `peer.kind` + `peer.id`).
2. **Збіг батьківського співрозмовника** (успадкування гілки).
3. **Збіг гільдії + ролей** (Discord) через `guildId` + `roles`.
4. **Збіг гільдії** (Discord) через `guildId`.
5. **Збіг команди** (Slack) через `teamId`.
6. **Збіг облікового запису** (`accountId` на каналі).
7. **Збіг каналу** (будь-який обліковий запис на цьому каналі, `accountId: "*"`).
8. **Типовий агент** (`agents.list[].default`, інакше перший запис списку, резервно `main`).
Коли binding містить кілька полів збігу (`peer`, `guildId`, `teamId`, `roles`), **усі надані поля мають збігатися**, щоб цей binding застосовувався.
Коли прив’язка містить кілька полів зіставлення (`peer`, `guildId`, `teamId`, `roles`), **усі надані поля мають збігатися**, щоб ця прив’язка застосувалася.
Зіставлений агент визначає, який робочий простір і яке сховище сесій використовуються.
Зіставлений агент визначає, який робочий простір і сховище сеансів використовуються.
## Групи трансляції (запуск кількох агентів)
Групи трансляції дають змогу запускати **кілька агентів** для одного й того самого peer **коли OpenClaw зазвичай відповідає** (наприклад, у групах WhatsApp після згадки/активаційного шлюзу).
Групи трансляції дають змогу запускати **кілька агентів** для одного співрозмовника **коли OpenClaw зазвичай відповідав би** (наприклад: у групах WhatsApp після перевірки згадки/активації).
Конфігурація:
@ -106,14 +106,14 @@ OpenClaw може оновлювати метадані та `lastRoute` для
## Огляд конфігурації
- `agents.list`: іменовані визначення агентів (робочий простір, модель тощо).
- `bindings`: зіставляє вхідні канали/облікові записи/peer з агентами.
- `bindings`: зіставлення вхідних каналів/облікових записів/співрозмовників з агентами.
Приклад:
```json5
{
agents: {
list: [{ id: "support", name: "Підтримка", workspace: "~/.openclaw/workspace-support" }],
list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
},
bindings: [
{ match: { channel: "slack", teamId: "T123" }, agentId: "support" },
@ -122,25 +122,20 @@ OpenClaw може оновлювати метадані та `lastRoute` для
}
```
## Зберігання сесій
## Сховище сеансів
Сховища сесій розміщуються в каталозі стану (типово `~/.openclaw`):
Сховища сеансів розташовані в каталозі стану (типово `~/.openclaw`):
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- JSONL-стенограми розміщуються поруч зі сховищем
- JSONL-транскрипти розташовані поруч зі сховищем
Ви можете перевизначити шлях до сховища через `session.store` і шаблонізацію `{agentId}`.
Виявлення сесій Gateway і ACP також сканує дискові сховища агентів у типовому
корені `agents/` і в коренях `session.store` із шаблонами. Виявлені
сховища мають залишатися всередині цього визначеного кореня агента й використовувати звичайний файл
`sessions.json`. Символічні посилання та шляхи поза коренем ігноруються.
Виявлення сеансів Gateway і ACP також сканує дискові сховища агентів під типовим коренем `agents/` і під коренями шаблонізованого `session.store`. Виявлені сховища мають залишатися всередині цього розв’язаного кореня агента й використовувати звичайний файл `sessions.json`. Символічні посилання та шляхи поза коренем ігноруються.
## Поведінка WebChat
WebChat підключається до **вибраного агента** і типово використовує основну
сесію агента. Завдяки цьому WebChat дає змогу бачити міжканальний контекст для цього
агента в одному місці.
WebChat приєднується до **вибраного агента** й типово використовує основний сеанс агента. Через це WebChat дає змогу бачити міжканальний контекст для цього агента в одному місці.
## Контекст відповіді
@ -149,7 +144,7 @@ WebChat підключається до **вибраного агента** і
- `ReplyToId`, `ReplyToBody` і `ReplyToSender`, коли доступні.
- Цитований контекст додається до `Body` як блок `[Replying to ...]`.
Це узгоджено в усіх каналах.
Це узгоджено між каналами.
## Пов’язане

451
docs/uk/channels/slack.md
View File

@ -1,43 +1,43 @@
---
read_when:
- Налаштування Slack або налагодження сокетного/HTTP-режиму Slack
summary: Налаштування Slack і поведінка під час виконання (Socket Mode + URL-адреси HTTP-запитів)
- Налаштування Slack або налагодження режиму сокета/HTTP у Slack
summary: Налаштування Slack і поведінка під час виконання (Режим Socket + URL-адреси HTTP-запитів)
title: Slack
x-i18n:
generated_at: "2026-05-02T04:01:21Z"
generated_at: "2026-05-02T04:47:14Z"
model: gpt-5.5
provider: openai
source_hash: 1a676acabdb4dce83f813f991692624e1f5b2dff739e68b5c5bd7b064dd82d03
source_hash: 60e06b138e1579156ccd07bb6db1a25009be970d072ba500b61810c5b78fd01d
source_path: channels/slack.md
workflow: 16
---
Готовий до production-використання для DM і каналів через інтеграції Slack app. Режим за замовчуванням — Socket Mode; HTTP Request URLs також підтримуються.
Готово до продакшну для прямих повідомлень і каналів через інтеграції застосунку Slack. Режим за замовчуванням — сокетний режим; URL-адреси HTTP-запитів також підтримуються.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/uk/channels/pairing">
DM у Slack за замовчуванням використовують режим створення пари.
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
Особисті повідомлення Slack за замовчуванням використовують режим сполучення.
</Card>
<Card title="Slash commands" icon="terminal" href="/uk/tools/slash-commands">
<Card title="Слеш-команди" icon="terminal" href="/uk/tools/slash-commands">
Нативна поведінка команд і каталог команд.
</Card>
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
Міжканальна діагностика та інструкції з виправлення.
<Card title="Усунення проблем із каналами" icon="wrench" href="/uk/channels/troubleshooting">
Міжканальна діагностика та сценарії відновлення.
</Card>
</CardGroup>
## Швидке налаштування
<Tabs>
<Tab title="Socket Mode (за замовчуванням)">
<Tab title="Сокетний режим (за замовчуванням)">
<Steps>
<Step title="Створіть новий Slack app">
У налаштуваннях Slack app натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**:
<Step title="Створіть новий застосунок Slack">
У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**:
- виберіть **from a manifest** і виберіть workspace для свого app
- вставте [приклад manifest](#manifest-and-scope-checklist) нижче й продовжте створення
- виберіть **from a manifest** і виберіть робочий простір для свого застосунку
- вставте [приклад маніфеста](#manifest-and-scope-checklist) нижче й продовжте створення
- згенеруйте **App-Level Token** (`xapp-...`) з `connections:write`
- установіть app і скопіюйте показаний **Bot Token** (`xoxb-...`)
- установіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`)
</Step>
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5
```
Резервний варіант через env (лише обліковий запис за замовчуванням):
Резервний варіант через змінні середовища (лише обліковий запис за замовчуванням):
```bash
SLACK_APP_TOKEN=xapp-...
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
</Step>
<Step title="Запустіть gateway">
<Step title="Запустіть Gateway">
```bash
openclaw gateway
@ -84,15 +84,15 @@ openclaw gateway
</Tab>
<Tab title="HTTP Request URLs">
<Tab title="URL-адреси HTTP-запитів">
<Steps>
<Step title="Створіть новий Slack app">
У налаштуваннях Slack app натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**:
<Step title="Створіть новий застосунок Slack">
У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**:
- виберіть **from a manifest** і виберіть workspace для свого app
- вставте [приклад manifest](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням
- виберіть **from a manifest** і виберіть робочий простір для свого застосунку
- вставте [приклад маніфеста](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням
- збережіть **Signing Secret** для перевірки запитів
- установіть app і скопіюйте показаний **Bot Token** (`xoxb-...`)
- установіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`)
</Step>
@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5
```
<Note>
Використовуйте унікальні webhook-шляхи для HTTP із кількома обліковими записами
Використовуйте унікальні шляхи Webhook для HTTP з кількома обліковими записами
Надайте кожному обліковому запису окремий `webhookPath` (за замовчуванням `/slack/events`), щоб реєстрації не конфліктували.
Надайте кожному обліковому запису окремий `webhookPath` (типово `/slack/events`), щоб реєстрації не конфліктували.
</Note>
</Step>
<Step title="Запустіть gateway">
<Step title="Запустіть Gateway">
```bash
openclaw gateway
@ -140,9 +140,9 @@ openclaw gateway
</Tab>
</Tabs>
## Налаштування транспорту Socket Mode
## Налаштування транспорту сокетного режиму
OpenClaw за замовчуванням установлює для клієнта Slack SDK час очікування pong 15 секунд у Socket Mode. Перевизначайте транспортні налаштування лише тоді, коли потрібне налаштування під конкретний workspace або хост:
OpenClaw за замовчуванням задає тайм-аут очікування pong для клієнта Slack SDK на 15 секунд у сокетному режимі. Перевизначайте налаштування транспорту лише тоді, коли потрібне налаштування під конкретний робочий простір або хост:
```json5
{
@ -159,13 +159,13 @@ OpenClaw за замовчуванням установлює для клієн
}
```
Використовуйте це лише для workspace у Socket Mode, які фіксують у журналах таймаути pong/server-ping для websocket Slack або працюють на хостах із відомим виснаженням event loop. `clientPingTimeout` — це очікування pong після того, як SDK надсилає клієнтський ping; `serverPingTimeout` — очікування ping від сервера Slack. Повідомлення й події app залишаються станом застосунку, а не сигналами активності транспорту.
Використовуйте це лише для робочих просторів у сокетному режимі, де фіксуються тайм-аути Slack websocket pong/server-ping, або для хостів із відомим голодуванням циклу подій. `clientPingTimeout` — це очікування pong після того, як SDK надсилає клієнтський ping; `serverPingTimeout` — це очікування ping від сервера Slack. Повідомлення й події застосунку залишаються станом застосунку, а не сигналами працездатності транспорту.
## Контрольний список manifest і scopes
## Контрольний список маніфеста й областей доступу
Базовий manifest Slack app однаковий для Socket Mode і HTTP Request URLs. Відрізняється лише блок `settings` (і `url` slash-команди).
Базовий маніфест застосунку Slack однаковий для сокетного режиму та URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` слеш-команди).
Базовий manifest (Socket Mode за замовчуванням):
Базовий маніфест (сокетний режим за замовчуванням):
```json
{
@ -240,7 +240,7 @@ OpenClaw за замовчуванням установлює для клієн
}
```
Для режиму **HTTP Request URLs** замініть `settings` на HTTP-варіант і додайте `url` до кожної slash-команди. Потрібна публічна URL-адреса:
Для **режиму URL-адрес HTTP-запитів** замініть `settings` на HTTP-варіант і додайте `url` до кожної слеш-команди. Потрібна публічна URL-адреса:
```json
{
@ -270,24 +270,24 @@ OpenClaw за замовчуванням установлює для клієн
}
```
### Додаткові налаштування manifest
### Додаткові налаштування маніфеста
Увімкніть інші функції, що розширюють наведені вище типові значення.
Увімкніть різні функції, які розширюють наведені вище типові параметри.
Типовий manifest вмикає вкладку **Home** у Slack App Home і підписується на `app_home_opened`. Коли учасник workspace відкриває вкладку Home, OpenClaw публікує безпечне типове подання Home через `views.publish`; payload розмови або приватна конфігурація не додаються. Вкладка **Messages** лишається ввімкненою для DM у Slack.
Типовий маніфест вмикає вкладку **Головна** на сторінці застосунку Slack і підписується на `app_home_opened`. Коли учасник робочого простору відкриває вкладку «Головна», OpenClaw публікує безпечне типове подання головної сторінки через `views.publish`; жодне навантаження розмови або приватна конфігурація не включаються. Вкладка **Повідомлення** залишається ввімкненою для особистих повідомлень Slack.
<AccordionGroup>
<Accordion title="Необов’язкові нативні slash-команди">
<Accordion title="Необов’язкові нативні слеш-команди">
Кілька [нативних slash-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з певними нюансами:
З певними нюансами можна використовувати кілька [нативних слеш-команд](#commands-and-slash-behavior) замість однієї налаштованої команди:
- Використовуйте `/agentstatus` замість `/status`, оскільки команда `/status` зарезервована.
- Одночасно можна зробити доступними не більше ніж 25 slash-команд.
- Використовуйте `/agentstatus` замість `/status`, тому що команда `/status` зарезервована.
- Одночасно можна зробити доступними не більше 25 слеш-команд.
Замініть наявний розділ `features.slash_commands` підмножиною [доступних команд](/uk/tools/slash-commands#command-list):
<Tabs>
<Tab title="Socket Mode (за замовчуванням)">
<Tab title="Сокетний режим (за замовчуванням)">
```json
"slash_commands": [
@ -403,8 +403,8 @@ OpenClaw за замовчуванням установлює для клієн
```
</Tab>
<Tab title="HTTP Request URLs">
Використовуйте той самий список `slash_commands`, що й для Socket Mode вище, і додайте `"url": "https://gateway-host.example.com/slack/events"` до кожного запису. Приклад:
<Tab title="URL-адреси HTTP-запитів">
Використовуйте той самий список `slash_commands`, що й для сокетного режиму вище, і додайте `"url": "https://gateway-host.example.com/slack/events"` до кожного запису. Приклад:
```json
"slash_commands": [
@ -427,14 +427,14 @@ OpenClaw за замовчуванням установлює для клієн
</Tabs>
</Accordion>
<Accordion title="Необов’язкові scopes авторства (операції запису)">
Додайте bot scope `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (користувацьке ім’я та іконку), а не типову ідентичність Slack app.
<Accordion title="Необов’язкові області доступу авторства (операції запису)">
Додайте область доступу бота `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували активну ідентичність агента (власне ім’я користувача та піктограму) замість типової ідентичності застосунку Slack.
Якщо ви використовуєте emoji-іконку, Slack очікує синтаксис `:emoji_name:`.
Якщо ви використовуєте піктограму-емодзі, Slack очікує синтаксис `:emoji_name:`.
</Accordion>
<Accordion title="Необов’язкові області доступу користувацького токена (операції читання)">
Якщо ви налаштовуєте `channels.slack.userToken`, типовими областями доступу для читання є:
<Accordion title="Необов’язкові області дії токена користувача (операції читання)">
Якщо ви налаштовуєте `channels.slack.userToken`, типовими областями дії для читання є:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -442,7 +442,7 @@ OpenClaw за замовчуванням установлює для клієн
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (якщо ви покладаєтеся на читання через пошук Slack)
- `search:read` (якщо ви залежите від читання через пошук Slack)
</Accordion>
</AccordionGroup>
@ -450,26 +450,26 @@ OpenClaw за замовчуванням установлює для клієн
## Модель токенів
- `botToken` + `appToken` потрібні для Socket Mode.
- Режим HTTP потребує `botToken` + `signingSecret`.
- Для режиму HTTP потрібні `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті
рядки або об’єкти SecretRef.
- Токени конфігурації мають пріоритет над резервними значеннями зі змінних середовища.
- Токени конфігурації перевизначають резервні значення env.
- Резервні значення env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовуються лише до облікового запису за замовчуванням.
- `userToken` (`xoxp-...`) налаштовується лише в конфігурації (без резервного значення env) і за замовчуванням працює лише для читання (`userTokenReadOnly: true`).
- `userToken` (`xoxp-...`) задається лише в конфігурації (без резервного значення env) і за замовчуванням має поведінку лише для читання (`userTokenReadOnly: true`).
Поведінка знімка стану:
- Інспекція облікового запису Slack відстежує поля `*Source` і `*Status`
для кожних облікових даних (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Стан може бути `available`, `configured_unavailable` або `missing`.
- Стан — `available`, `configured_unavailable` або `missing`.
- `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef
або інше неінлайн-джерело секретів, але поточна команда чи шлях виконання
не змогли отримати фактичне значення.
або інше не-вбудоване джерело секрету, але поточна команда/шлях виконання
не зміг отримати фактичне значення.
- У режимі HTTP включається `signingSecretStatus`; у Socket Mode
потрібна пара — `botTokenStatus` + `appTokenStatus`.
<Tip>
Для дій і читання каталогу користувацький токен може мати пріоритет, якщо його налаштовано. Для запису перевага залишається за bot token; записи через користувацький токен дозволені лише коли `userTokenReadOnly: false` і bot token недоступний.
Для дій/читання каталогу може надаватися перевага токену користувача, якщо його налаштовано. Для записів перевага лишається за токеном бота; записи через токен користувача дозволені лише коли `userTokenReadOnly: false` і токен бота недоступний.
</Tip>
## Дії та шлюзи
@ -479,20 +479,20 @@ OpenClaw за замовчуванням установлює для клієн
Доступні групи дій у поточному інструментарії Slack:
| Група | За замовчуванням |
| ---------- | ------- |
| messages | увімкнено |
| reactions | увімкнено |
| pins | увімкнено |
| memberInfo | увімкнено |
| emojiList | увімкнено |
| ---------- | ---------------- |
| messages | увімкнено |
| reactions | увімкнено |
| pins | увімкнено |
| memberInfo | увімкнено |
| emojiList | увімкнено |
Поточні дії повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ID файлів Slack, показані у вхідних плейсхолдерах файлів, і повертає прев’ю зображень для зображень або метадані локального файлу для інших типів файлів.
Поточні дії повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ID файлів Slack, показані у вхідних заповнювачах файлів, і повертає попередні перегляди зображень для зображень або метадані локального файлу для інших типів файлів.
## Контроль доступу та маршрутизація
<Tabs>
<Tab title="Політика DM">
`channels.slack.dmPolicy` керує доступом до DM. `channels.slack.allowFrom` є канонічним allowlist для DM.
`channels.slack.dmPolicy` керує доступом до DM. `channels.slack.allowFrom` є канонічним списком дозволених DM.
- `pairing` (за замовчуванням)
- `allowlist`
@ -505,7 +505,7 @@ OpenClaw за замовчуванням установлює для клієн
- `channels.slack.allowFrom`
- `dm.allowFrom` (застаріле)
- `dm.groupEnabled` (групові DM за замовчуванням false)
- `dm.groupChannels` (необов’язковий allowlist MPIM)
- `dm.groupChannels` (необов’язковий список дозволених MPIM)
Пріоритет для кількох облікових записів:
@ -513,9 +513,9 @@ OpenClaw за замовчуванням установлює для клієн
- Іменовані облікові записи успадковують `channels.slack.allowFrom`, коли їхній власний `allowFrom` не задано.
- Іменовані облікові записи не успадковують `channels.slack.accounts.default.allowFrom`.
Застарілі `channels.slack.dm.policy` і `channels.slack.dm.allowFrom` усе ще читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли це можливо без зміни доступу.
Застарілі `channels.slack.dm.policy` і `channels.slack.dm.allowFrom` усе ще читаються для сумісності. `openclaw doctor --fix` мігрує їх до `dmPolicy` і `allowFrom`, коли може зробити це без зміни доступу.
Спарювання в DM використовує `openclaw pairing approve slack <code>`.
Сполучення в DM використовує `openclaw pairing approve slack <code>`.
</Tab>
@ -526,20 +526,20 @@ OpenClaw за замовчуванням установлює для клієн
- `allowlist`
- `disabled`
Allowlist каналів розташований у `channels.slack.channels` і **має використовувати стабільні ID каналів Slack** (наприклад `C12345678`) як ключі конфігурації.
Список дозволених каналів міститься в `channels.slack.channels` і **має використовувати стабільні ID каналів Slack** (наприклад `C12345678`) як ключі конфігурації.
Примітка щодо runtime: якщо `channels.slack` повністю відсутній (налаштування лише через env), runtime повертається до `groupPolicy="allowlist"` і записує попередження в журнал (навіть якщо задано `channels.defaults.groupPolicy`).
Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), runtime повертається до `groupPolicy="allowlist"` і записує попередження (навіть якщо `channels.defaults.groupPolicy` задано).
Розпізнавання імен/ID:
- записи allowlist каналів і записи allowlist DM розпізнаються під час запуску, коли доступ токена це дозволяє
- нерозпізнані записи з іменами каналів зберігаються як налаштовані, але за замовчуванням ігноруються для маршрутизації
- вхідна авторизація та маршрутизація каналів за замовчуванням спершу використовують ID; прямий збіг за username/slug потребує `channels.slack.dangerouslyAllowNameMatching: true`
- записи списку дозволених каналів і записи списку дозволених DM розпізнаються під час запуску, коли доступ токена це дозволяє
- нерозпізнані записи імен каналів зберігаються як налаштовані, але за замовчуванням ігноруються для маршрутизації
- вхідна авторизація та маршрутизація каналів за замовчуванням спершу використовують ID; пряме зіставлення імені користувача/slug потребує `channels.slack.dangerouslyAllowNameMatching: true`
<Warning>
Ключі на основі імен (`#channel-name` або `channel-name`) **не** збігаються під `groupPolicy: "allowlist"`. Пошук каналу за замовчуванням спершу використовує ID, тому ключ на основі імені ніколи не маршрутизуватиметься успішно, а всі повідомлення в цьому каналі буде тихо заблоковано. Це відрізняється від `groupPolicy: "open"`, де ключ каналу не потрібен для маршрутизації, і ключ на основі імені здається робочим.
Ключі на основі імен (`#channel-name` або `channel-name`) **не** зіставляються під `groupPolicy: "allowlist"`. Пошук каналу за замовчуванням спершу використовує ID, тому ключ на основі імені ніколи не буде успішно маршрутизований, а всі повідомлення в цьому каналі буде мовчки заблоковано. Це відрізняється від `groupPolicy: "open"`, де ключ каналу не потрібен для маршрутизації, і ключ на основі імені здається робочим.
Завжди використовуйте ID каналу Slack як ключ. Щоб знайти його: клацніть канал у Slack правою кнопкою → **Copy link** — ID (`C...`) з’являється в кінці URL.
Завжди використовуйте ID каналу Slack як ключ. Щоб знайти його: клацніть канал у Slack правою кнопкою → **Copy link** — ID (`C...`) з’явиться в кінці URL.
Правильно:
@ -556,7 +556,7 @@ OpenClaw за замовчуванням установлює для клієн
}
```
Неправильно (тихо блокується під `groupPolicy: "allowlist"`):
Неправильно (мовчки блокується під `groupPolicy: "allowlist"`):
```json5
{
@ -574,47 +574,48 @@ OpenClaw за замовчуванням установлює для клієн
</Tab>
<Tab title="Згадки та користувачі каналу">
Повідомлення каналів за замовчуванням пропускаються через фільтр згадок.
<Tab title="Згадки та користувачі каналів">
Повідомлення каналів за замовчуванням обмежені згадками.
Джерела згадок:
- явна згадка застосунку (`<@botId>`)
- згадка групи користувачів Slack (`<!subteam^S...>`), коли користувач бота є учасником цієї групи користувачів; потребує `usergroups:read`
- regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`)
- неявна поведінка гілки відповіді боту (вимкнено, коли `thread.requireExplicitMention` має значення `true`)
- згадка групи користувачів Slack (`<!subteam^S...>`), коли користувач-бот є членом цієї групи користувачів; потребує `usergroups:read`
- шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервне `messages.groupChat.mentionPatterns`)
- неявна поведінка відповіді в гілці боту (вимкнено, коли `thread.requireExplicitMention` дорівнює `true`)
Керування на рівні каналу (`channels.slack.channels.<id>`; імена лише через розв’язання під час запуску або `dangerouslyAllowNameMatching`):
Поканальні елементи керування (`channels.slack.channels.<id>`; імена лише через розпізнавання під час запуску або `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
- `users` (список дозволених)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- формат ключів `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або wildcard `"*"`
- формат ключів `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або символ-джокер `"*"`
(застарілі ключі без префікса досі зіставляються лише з `id:`)
`allowBots` є консервативним для каналів і приватних каналів: повідомлення кімнати, створені ботом, приймаються лише тоді, коли бот-відправник явно вказаний у allowlist `users` цієї кімнати, або коли принаймні один явний ID власника Slack із `channels.slack.allowFrom` зараз є учасником кімнати. Wildcard і записи власника за відображуваним іменем не задовольняють умову присутності власника. Присутність власника використовує Slack `conversations.members`; переконайтеся, що застосунок має відповідну область читання для типу кімнати (`channels:read` для публічних каналів, `groups:read` для приватних каналів). Якщо пошук учасників не вдається, OpenClaw відкидає повідомлення кімнати, створене ботом.
`allowBots` є консервативним для каналів і приватних каналів: повідомлення кімнати, створені ботом, приймаються лише коли бот-відправник явно зазначений у списку дозволених `users` цієї кімнати або коли принаймні один явний ID власника Slack із `channels.slack.allowFrom` наразі є учасником кімнати. Символи-джокери та записи власників за відображуваними іменами не задовольняють наявність власника. Наявність власника використовує Slack `conversations.members`; переконайтеся, що застосунок має відповідну область дії читання для типу кімнати (`channels:read` для публічних каналів, `groups:read` для приватних каналів). Якщо пошук учасників не вдається, OpenClaw відкидає повідомлення кімнати, створене ботом.
</Tab>
</Tabs>
## Гілки, сеанси й теги відповіді
## Гілки, сеанси та теги відповіді
- DM маршрутизуються як `direct`; канали як `channel`; MPIM як `group`.
- З типовим `session.dmScope=main` DM Slack згортаються в основний сеанс агента.
- Прив’язки маршрутів Slack приймають сирі ID співрозмовників, а також цільові форми Slack, як-от `channel:C12345678`, `user:U12345678` і `<@U12345678>`.
- Із типовим `session.dmScope=main` DM Slack згортаються в основний сеанс агента.
- Сеанси каналів: `agent:<agentId>:slack:channel:<channelId>`.
- Відповіді в гілках можуть створювати суфікси сеансів гілок (`:thread:<threadTs>`), коли це застосовно.
- Типове значення `channels.slack.thread.historyScope` — `thread`; типове значення `thread.inheritParent` — `false`.
- `channels.slack.thread.initialHistoryLimit` керує тим, скільки наявних повідомлень гілки отримується під час запуску нового сеансу гілки (типово `20`; установіть `0`, щоб вимкнути).
- `channels.slack.thread.requireExplicitMention` (типово `false`): коли `true`, пригнічує неявні згадки в гілках, щоб бот відповідав лише на явні згадки `@bot` усередині гілок, навіть якщо бот уже брав участь у гілці. Без цього відповіді в гілці, де брав участь бот, обходять фільтр `requireMention`.
- Значення `channels.slack.thread.historyScope` за замовчуванням — `thread`; значення `thread.inheritParent` за замовчуванням — `false`.
- `channels.slack.thread.initialHistoryLimit` керує тим, скільки наявних повідомлень гілки отримується під час запуску нового сеансу гілки (за замовчуванням `20`; задайте `0`, щоб вимкнути).
- `channels.slack.thread.requireExplicitMention` (за замовчуванням `false`): коли `true`, пригнічує неявні згадки в гілках, тож бот відповідає лише на явні згадки `@bot` у гілках, навіть якщо бот уже брав участь у гілці. Без цього відповіді в гілці за участю бота обходять обмеження `requireMention`.
Керування гілками відповідей:
Елементи керування гілками відповідей:
- `channels.slack.replyToMode`: `off|first|all|batched` (типово `off`)
- `channels.slack.replyToModeByChatType`: окремо для `direct|group|channel`
- застарілий резервний варіант для прямих чатів: `channels.slack.dm.replyToMode`
- `channels.slack.replyToMode`: `off|first|all|batched` (за замовчуванням `off`)
- `channels.slack.replyToModeByChatType`: для кожного `direct|group|channel`
- застаріле резервне значення для прямих чатів: `channels.slack.dm.replyToMode`
Підтримуються ручні теги відповіді:
@ -622,45 +623,45 @@ OpenClaw за замовчуванням установлює для клієн
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` вимикає **всі** гілки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все одно враховуються в режимі `"off"`. Гілки Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими в рядку.
`replyToMode="off"` вимикає **всі** гілки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"`. Гілки Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими безпосередньо в потоці.
</Note>
## Реакції підтвердження
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення.
Порядок розв’язання:
Порядок розпізнавання:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
Примітки:
- Slack очікує короткі коди (наприклад, `"eyes"`).
- Slack очікує shortcodes (наприклад `"eyes"`).
- Використовуйте `""`, щоб вимкнути реакцію для облікового запису Slack або глобально.
## Потокове передавання тексту
`channels.slack.streaming` керує поведінкою live preview:
`channels.slack.streaming` керує поведінкою живого попереднього перегляду:
- `off`: вимкнути потокове передавання live preview.
- `partial` (типово): замінювати текст preview найновішим частковим виводом.
- `block`: додавати фрагментовані оновлення preview.
- `progress`: показувати текст статусу перебігу під час генерації, а потім надіслати фінальний текст.
- `streaming.preview.toolProgress`: коли draft preview активний, спрямовувати оновлення інструментів/перебігу в те саме редаговане повідомлення preview (типово: `true`). Установіть `false`, щоб зберігати окремі повідомлення інструментів/перебігу.
- `off`: вимкнути потокове передавання живого попереднього перегляду.
- `partial` (за замовчуванням): замінювати текст попереднього перегляду найновішим частковим виводом.
- `block`: додавати фрагментовані оновлення попереднього перегляду.
- `progress`: показувати текст стану прогресу під час генерації, а потім надсилати фінальний текст.
- `streaming.preview.toolProgress`: коли чорновий попередній перегляд активний, маршрутизувати оновлення інструментів/прогресу до того самого редагованого повідомлення попереднього перегляду (за замовчуванням: `true`). Задайте `false`, щоб зберігати окремі повідомлення інструментів/прогресу.
`channels.slack.streaming.nativeTransport` керує нативним потоковим передаванням тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`).
`channels.slack.streaming.nativeTransport` керує нативним потоковим передаванням тексту Slack, коли `channels.slack.streaming.mode` дорівнює `partial` (за замовчуванням: `true`).
- Для появи нативного потокового передавання тексту й статусу гілки помічника Slack має бути доступна гілка відповіді. Вибір гілки все одно відповідає `replyToMode`.
- Корені каналів і групових чатів усе ще можуть використовувати звичайний draft preview, коли нативне потокове передавання недоступне.
- DM Slack верхнього рівня за замовчуванням залишаються поза гілкою, тому вони не показують preview у стилі гілки; використовуйте відповіді в гілках або `typingReaction`, якщо хочете мати там видимий перебіг.
- Медіа й нетекстові payloads повертаються до звичайної доставки.
- Фінальні медіа/помилки скасовують очікувані редагування preview; придатні фінальні текстові/блокові результати скидаються лише тоді, коли можуть редагувати preview на місці.
- Якщо потокове передавання завершується помилкою посеред відповіді, OpenClaw повертається до звичайної доставки для решти payloads.
- Для появи нативного потокового передавання тексту та стану гілки асистента Slack має бути доступна гілка відповіді. Вибір гілки все одно дотримується `replyToMode`.
- Корені каналів і групових чатів усе ще можуть використовувати звичайний чорновий попередній перегляд, коли нативне потокове передавання недоступне.
- DM Slack верхнього рівня за замовчуванням залишаються поза гілками, тому вони не показують попередній перегляд у стилі гілки; використовуйте відповіді в гілках або `typingReaction`, якщо хочете бачити прогрес там.
- Медіа та нетекстові payloads повертаються до звичайної доставки.
- Фінали медіа/помилок скасовують очікувані редагування попереднього перегляду; придатні фінали тексту/блоків скидаються лише тоді, коли можуть редагувати попередній перегляд на місці.
- Якщо потокове передавання зазнає невдачі посеред відповіді, OpenClaw повертається до звичайної доставки для решти payloads.
Використовуйте draft preview замість нативного потокового передавання тексту Slack:
Використовуйте чорновий попередній перегляд замість нативного потокового передавання тексту Slack:
```json5
{
@ -683,52 +684,52 @@ OpenClaw за замовчуванням установлює для клієн
## Резервна реакція набору тексту
`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення запуску. Це найкорисніше поза відповідями в гілках, які використовують типовий індикатор статусу "is typing...".
`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення запуску. Це найкорисніше поза відповідями в гілках, які використовують стандартний індикатор стану "is typing...".
Порядок розв’язання:
Порядок розпізнавання:
- `channels.slack.accounts.<accountId>.typingReaction`
- `channels.slack.typingReaction`
Примітки:
- Slack очікує короткі коди (наприклад, `"hourglass_flowing_sand"`).
- Реакція виконується за принципом best-effort, а очищення автоматично пробується після завершення відповіді або шляху помилки.
- Slack очікує shortcodes (наприклад `"hourglass_flowing_sand"`).
- Реакція виконується за найкращої спроби, а очищення автоматично виконується після завершення відповіді або шляху помилки.
## Медіа, фрагментація й доставка
## Медіа, фрагментація та доставка
<AccordionGroup>
<Accordion title="Вхідні вкладення">
Файлові вкладення Slack завантажуються з приватних URL, розміщених Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, коли отримання успішне й обмеження розміру це дозволяють. Заповнювачі файлів містять Slack `fileId`, щоб агенти могли отримати оригінальний файл за допомогою `download-file`.
Файлові вкладення Slack завантажуються з приватних URL, розміщених у Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, коли отримання успішне й обмеження розміру це дозволяють. Заповнювачі файлів містять Slack `fileId`, щоб агенти могли отримати початковий файл за допомогою `download-file`.
Завантаження використовують обмежені тайм-аути простою й загального часу. Якщо отримання файлу Slack зависає або завершується помилкою, OpenClaw продовжує обробляти повідомлення й повертається до заповнювача файлу.
Завантаження використовують обмежені тайм-аути бездіяльності та загального часу. Якщо отримання файлу Slack зависає або завершується помилкою, OpenClaw продовжує обробляти повідомлення й повертається до заповнювача файлу.
Обмеження вхідного розміру під час виконання за замовчуванням становить `20MB`, якщо його не перевизначено через `channels.slack.mediaMaxMb`.
Обмеження розміру вхідних даних під час виконання типово становить `20MB`, якщо його не перевизначено через `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="Вихідний текст і файли">
- текстові фрагменти використовують `channels.slack.textChunkLimit` (за замовчуванням 4000)
- фрагменти тексту використовують `channels.slack.textChunkLimit` (типово 4000)
- `channels.slack.chunkMode="newline"` вмикає поділ із пріоритетом абзаців
- надсилання файлів використовує API завантаження Slack і може містити відповіді в тредах (`thread_ts`)
- обмеження вихідних медіа використовує `channels.slack.mediaMaxMb`, якщо налаштовано; інакше надсилання в канал використовує типові значення за MIME-типом із медіаконвеєра
- надсилання файлів використовує API завантаження Slack і може містити відповіді в треді (`thread_ts`)
- обмеження вихідних медіа відповідає `channels.slack.mediaMaxMb`, коли налаштовано; інакше надсилання каналом використовує типові значення за MIME-типом із медіаконвеєра
</Accordion>
<Accordion title="Цілі доставки">
Бажані явні цілі:
- `user:<id>` для DM
- `user:<id>` для особистих повідомлень
- `channel:<id>` для каналів
Текстові або лише блочні Slack DM можуть публікуватися напряму в ідентифікатори користувачів; завантаження файлів і надсилання в тредах спочатку відкривають DM через API розмов Slack, тому що ці шляхи потребують конкретного ідентифікатора розмови.
Особисті повідомлення Slack лише з текстом/блоками можуть публікуватися безпосередньо за ідентифікаторами користувачів; завантаження файлів і надсилання в тредах спершу відкривають особисте повідомлення через API розмов Slack, тому що ці шляхи потребують конкретного ідентифікатора розмови.
</Accordion>
</AccordionGroup>
## Команди та поведінка slash
## Команди та поведінка slash-команд
Slash-команди відображаються у Slack як одна налаштована команда або кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові значення команд:
Slash-команди з’являються в Slack як одна налаштована команда або кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команд:
- `enabled: false`
- `name: "openclaw"`
@ -747,22 +748,22 @@ Slash-команди відображаються у Slack як одна нал
/help
```
Меню аргументів нативних команд використовують адаптивну стратегію рендерингу, яка показує модальне вікно підтвердження перед надсиланням вибраного значення параметра:
Меню нативних аргументів використовують адаптивну стратегію відтворення, яка показує модальне вікно підтвердження перед надсиланням вибраного значення опції:
- до 5 варіантів: блоки кнопок
- 6-100 варіантів: статичне меню вибору
- понад 100 варіантів: зовнішній вибір з асинхронним фільтруванням варіантів, коли доступні обробники параметрів інтерактивності
- перевищені ліміти Slack: закодовані значення параметрів повертаються до кнопок
- до 5 опцій: блоки кнопок
- 6-100 опцій: статичне меню вибору
- понад 100 опцій: зовнішній вибір з асинхронною фільтрацією опцій, коли доступні обробники параметрів інтерактивності
- перевищені обмеження Slack: закодовані значення опцій повертаються до кнопок
```txt
/think
```
Slash-сеанси використовують ізольовані ключі на кшталт `agent:<agentId>:slack:slash:<userId>` і все одно спрямовують виконання команд до цільового сеансу розмови за допомогою `CommandTargetSessionKey`.
Slash-сеанси використовують ізольовані ключі, як-от `agent:<agentId>:slack:slash:<userId>`, і все одно спрямовують виконання команд до цільового сеансу розмови за допомогою `CommandTargetSessionKey`.
## Інтерактивні відповіді
Slack може рендерити створені агентом інтерактивні елементи керування відповідями, але ця функція за замовчуванням вимкнена.
Slack може відображати створені агентом елементи керування інтерактивними відповідями, але ця функція типово вимкнена.
Увімкніть її глобально:
@ -796,44 +797,44 @@ Slack може рендерити створені агентом інтерак
}
```
Коли ввімкнено, агенти можуть надсилати директиви відповідей лише для Slack:
Коли ввімкнено, агенти можуть видавати директиви відповідей лише для Slack:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
Ці директиви компілюються в Slack Block Kit і спрямовують кліки або вибори назад через наявний шлях подій взаємодії Slack.
Ці директиви компілюються в Slack Block Kit і спрямовують натискання або вибори назад через наявний шлях подій взаємодії Slack.
Примітки:
- Це UI, специфічний для Slack. Інші канали не перетворюють директиви Slack Block Kit на власні системи кнопок.
- Значення інтерактивних callback є непрозорими токенами, згенерованими OpenClaw, а не сирими значеннями, створеними агентом.
- Якщо згенеровані інтерактивні блоки перевищили б ліміти Slack Block Kit, OpenClaw натомість повертається до початкової текстової відповіді, щоб не надсилати недійсне payload блоків.
- Це інтерфейс, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок.
- Значення інтерактивних callback — це згенеровані OpenClaw непрозорі токени, а не необроблені значення, створені агентом.
- Якщо згенеровані інтерактивні блоки перевищили б обмеження Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання недійсного навантаження блоків.
## Exec-схвалення у Slack
## Підтвердження exec у Slack
Slack може працювати як нативний клієнт схвалень з інтерактивними кнопками та взаємодіями, замість повернення до Web UI або термінала.
Slack може діяти як нативний клієнт підтвердження з інтерактивними кнопками та взаємодіями, замість повернення до вебінтерфейсу або термінала.
- Exec-схвалення використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналів.
- Схвалення Plugin усе ще можуть вирішуватися через ту саму нативну поверхню кнопок Slack, коли запит уже надходить у Slack і тип ідентифікатора схвалення є `plugin:`.
- Авторизація схвалювача все ще застосовується: лише користувачі, ідентифіковані як схвалювачі, можуть схвалювати або відхиляти запити через Slack.
- Підтвердження exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації особистих повідомлень/каналів.
- Підтвердження Plugin усе ще можуть вирішуватися через ту саму нативну кнопкову поверхню Slack, коли запит уже потрапляє в Slack, а тип ідентифікатора підтвердження — `plugin:`.
- Авторизація затверджувача все ще застосовується: лише користувачі, ідентифіковані як затверджувачі, можуть схвалювати або відхиляти запити через Slack.
Це використовує ту саму спільну поверхню кнопок схвалення, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити схвалення рендеряться як кнопки Block Kit безпосередньо в розмові.
Коли ці кнопки присутні, вони є основним UX схвалення; OpenClaw
має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що схвалення
через чат недоступні або ручне схвалення є єдиним шляхом.
Це використовує ту саму спільну поверхню кнопок підтвердження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити підтвердження відображаються як кнопки Block Kit безпосередньо в розмові.
Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw
має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що
підтвердження в чаті недоступні або ручне підтвердження є єдиним шляхом.
Шлях конфігурації:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (необов’язково; за можливості повертається до `commands.ownerAllowFrom`)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`)
- `agentFilter`, `sessionFilter`
Slack автоматично вмикає нативні Exec-схвалення, коли `enabled` не задано або має значення `"auto"` і визначено принаймні одного
схвалювача. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт схвалень.
Установіть `enabled: true`, щоб примусово ввімкнути нативні схвалення, коли схвалювачів визначено.
Slack автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"` і принаймні один
затверджувач визначається. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт підтвердження.
Установіть `enabled: true`, щоб примусово ввімкнути нативні підтвердження, коли затверджувачі визначаються.
Типова поведінка без явної конфігурації Exec-схвалень Slack:
Типова поведінка без явної конфігурації підтвердження exec у Slack:
```json5
{
@ -843,8 +844,8 @@ Slack автоматично вмикає нативні Exec-схвалення
}
```
Явна нативна конфігурація Slack потрібна лише тоді, коли ви хочете перевизначити схвалювачів, додати фільтри або
увімкнути доставку в початковий чат:
Явна нативна конфігурація Slack потрібна лише тоді, коли потрібно перевизначити затверджувачів, додати фільтри або
увімкнути доставку до початкового чату:
```json5
{
@ -860,25 +861,25 @@ Slack автоматично вмикає нативні Exec-схвалення
}
```
Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити Exec-схвалення також мають
Спільне переспрямування `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити підтвердження exec також мають
маршрутизуватися до інших чатів або явних позасмугових цілей. Спільне переспрямування `approvals.plugin` також
окреме; нативні кнопки Slack усе ще можуть вирішувати схвалення Plugin, коли ці запити вже надходять
окреме; нативні кнопки Slack усе ще можуть вирішувати підтвердження Plugin, коли ці запити вже потрапляють
у Slack.
`/approve` у тому самому чаті також працює в каналах Slack і DM, які вже підтримують команди. Див. [Exec-схвалення](/uk/tools/exec-approvals) для повної моделі переспрямування схвалень.
Same-chat `/approve` також працює в каналах Slack і особистих повідомленнях, які вже підтримують команди. Див. [Підтвердження exec](/uk/tools/exec-approvals) для повної моделі переспрямування підтверджень.
## Події та операційна поведінка
- Редагування/видалення повідомлень зіставляються із системними подіями.
- Трансляції тредів (відповіді в тредах "Also send to channel") обробляються як звичайні повідомлення користувача.
- Трансляції тредів (відповіді в треді «Also send to channel») обробляються як звичайні повідомлення користувача.
- Події додавання/видалення реакцій зіставляються із системними подіями.
- Події приєднання/виходу учасника, створення/перейменування каналу та додавання/видалення закріплення зіставляються із системними подіями.
- `channel_id_changed` може мігрувати ключі конфігурації каналів, коли ввімкнено `configWrites`.
- Метадані теми/призначення каналу вважаються ненадійним контекстом і можуть бути впроваджені в контекст маршрутизації.
- Початкове повідомлення треду та початкове наповнення контексту історії треду фільтруються за налаштованими allowlist відправників, коли це застосовно.
- Дії блоків і модальні взаємодії генерують структуровані системні події `Slack interaction: ...` із насиченими полями payload:
- дії блоків: вибрані значення, мітки, значення picker і метадані `workflow_*`
- події modal `view_submission` і `view_closed` з маршрутизованими метаданими каналу та введеннями форми
- Події приєднання/виходу учасників, створення/перейменування каналів і додавання/видалення закріплень зіставляються із системними подіями.
- `channel_id_changed` може мігрувати ключі конфігурації каналу, коли `configWrites` увімкнено.
- Метадані теми/призначення каналу розглядаються як ненадійний контекст і можуть бути впроваджені в контекст маршрутизації.
- Ініціатор треду та початкове засівання контексту історії треду фільтруються за налаштованими списками дозволених відправників, коли це застосовно.
- Дії блоків і модальні взаємодії створюють структуровані системні події `Slack interaction: ...` з багатими полями навантаження:
- дії блоків: вибрані значення, мітки, значення вибирачів і метадані `workflow_*`
- події модального `view_submission` і `view_closed` з маршрутизованими метаданими каналу та вхідними даними форми
## Довідник конфігурації
@ -887,12 +888,12 @@ Slack автоматично вмикає нативні Exec-схвалення
<Accordion title="Високосигнальні поля Slack">
- режим/автентифікація: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- доступ до DM: `dm.enabled`, `dmPolicy`, `allowFrom` (застарілі: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- перемикач сумісності: `dangerouslyAllowNameMatching` (break-glass; тримайте вимкненим, якщо не потрібно)
- доступ до каналів: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- доступ до особистих повідомлень: `dm.enabled`, `dmPolicy`, `allowFrom` (застаріле: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний режим; тримайте вимкненим, якщо не потрібно)
- доступ до каналу: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- треди/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
- ops/функції: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
- операції/функції: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
</Accordion>
@ -900,12 +901,12 @@ Slack автоматично вмикає нативні Exec-схвалення
<AccordionGroup>
<Accordion title="Немає відповідей у каналах">
Перевірте по порядку:
Перевірте, у такому порядку:
- `groupPolicy`
- allowlist каналів (`channels.slack.channels`) — **ключі мають бути ідентифікаторами каналів** (`C12345678`), а не назвами (`#channel-name`). Ключі на основі назв непомітно не спрацьовують із `groupPolicy: "allowlist"`, тому що маршрутизація каналів за замовчуванням насамперед використовує ID. Щоб знайти ID: клацніть канал у Slack правою кнопкою → **Copy link** — значення `C...` наприкінці URL є ідентифікатором каналу.
- список дозволених каналів (`channels.slack.channels`) — **ключі мають бути ідентифікаторами каналів** (`C12345678`), а не назвами (`#channel-name`). Ключі на основі назв тихо не спрацьовують із `groupPolicy: "allowlist"`, тому що маршрутизація каналів типово насамперед використовує ідентифікатори. Щоб знайти ідентифікатор: клацніть правою кнопкою канал у Slack → **Copy link** — значення `C...` в кінці URL є ідентифікатором каналу.
- `requireMention`
- allowlist `users` для окремого каналу
- поканальний список дозволених `users`
Корисні команди:
@ -917,13 +918,13 @@ openclaw doctor
</Accordion>
<Accordion title="Повідомлення DM ігноруються">
<Accordion title="Особисті повідомлення ігноруються">
Перевірте:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (або застарілий `channels.slack.dm.policy`)
- схвалення спарювання / записи allowlist
- події Slack Assistant DM: докладні журнали зі згадкою `drop message_changed`
- `channels.slack.dmPolicy` (або застаріле `channels.slack.dm.policy`)
- підтвердження спарювання / записи списку дозволених
- події особистих повідомлень Slack Assistant: докладні журнали зі згадкою `drop message_changed`
зазвичай означають, що Slack надіслав відредаговану подію треду Assistant без
відновлюваного людського відправника в метаданих повідомлення
@ -934,124 +935,124 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket mode не підключається">
Перевірте токени bot + app і ввімкнення Socket Mode у налаштуваннях застосунку Slack.
Перевірте токени бота й застосунку та ввімкнення Socket Mode у налаштуваннях застосунку Slack.
Якщо `openclaw channels status --probe --json` показує `botTokenStatus` або
`appTokenStatus: "configured_unavailable"`, обліковий запис Slack
налаштовано, але поточне середовище виконання не змогло визначити значення,
що підтримується SecretRef.
підтримане SecretRef.
</Accordion>
<Accordion title="HTTP-режим не отримує події">
Перевірте:
- секрет підписування
- шлях webhook
- URL запитів Slack (Events + Interactivity + Slash Commands)
- унікальний `webhookPath` для кожного HTTP-облікового запису
- signing secret
- шлях Webhook
- URL запитів Slack (події + інтерактивність + Slash Commands)
- унікальний `webhookPath` для кожного облікового запису HTTP
Якщо `signingSecretStatus: "configured_unavailable"` з’являється у знімках
облікового запису, HTTP-обліковий запис налаштовано, але поточне середовище виконання не змогло
визначити секрет підписування, що підтримується SecretRef.
облікових записів, HTTP-обліковий запис налаштовано, але поточне середовище виконання не змогло
визначити signing secret, підтриманий SecretRef.
</Accordion>
<Accordion title="Нативні/slash-команди не спрацьовують">
<Accordion title="Нативні/slash-команди не запускаються">
Перевірте, що саме ви мали на увазі:
- режим нативних команд (`channels.slack.commands.native: true`) з відповідними slash-командами, зареєстрованими у Slack
- режим нативних команд (`channels.slack.commands.native: true`) з відповідними slash-командами, зареєстрованими в Slack
- або режим однієї slash-команди (`channels.slack.slashCommand.enabled: true`)
Також перевірте `commands.useAccessGroups` і allowlist каналів/користувачів.
Також перевірте `commands.useAccessGroups` і списки дозволених каналів/користувачів.
</Accordion>
</AccordionGroup>
## Довідник vision для вкладень
## Довідник бачення вкладень
Slack може додавати завантажені медіа до ходу агента, коли завантаження файлів Slack успішні й обмеження розміру це дозволяють. Файли зображень можуть передаватися через шлях розуміння медіа або безпосередньо до моделі відповіді з підтримкою vision; інші файли зберігаються як контекст файлів для завантаження, а не розглядаються як вхідні зображення.
Slack може прикріплювати завантажені медіа до ходу агента, коли завантаження файлів Slack успішне й обмеження розміру це дозволяють. Файли зображень можуть передаватися через шлях розуміння медіа або безпосередньо до моделі відповіді з підтримкою бачення; інші файли зберігаються як завантажуваний файловий контекст, а не розглядаються як вхідні зображення.
### Підтримувані типи медіа
| Тип медіа | Джерело | Поточна поведінка | Примітки |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Зображення JPEG / PNG / GIF / WebP | URL файлу Slack | Завантажуються й додаються до ходу для обробки з підтримкою зорових можливостей | Ліміт на файл: `channels.slack.mediaMaxMb` (типово 20 MB) |
| Файли PDF | URL файлу Slack | Завантажуються й надаються як файловий контекст для інструментів, як-от `download-file` або `pdf` | Вхідні повідомлення Slack не перетворюють PDF на вхідні дані image-vision автоматично |
| Інші файли | URL файлу Slack | Завантажуються, коли це можливо, і надаються як файловий контекст | Двійкові файли не розглядаються як вхідні зображення |
| Відповіді в гілках | Файли початкового повідомлення гілки | Файли кореневого повідомлення можуть бути підвантажені як контекст, коли відповідь не має власних медіа | Початкові повідомлення лише з файлами використовують заповнювач вкладення |
| Повідомлення з кількома зображеннями | Кілька файлів Slack | Кожен файл оцінюється незалежно | Обробка Slack обмежена вісьмома файлами на повідомлення |
| Тип медіа | Джерело | Поточна поведінка | Примітки |
| ------------------------------ | -------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Зображення JPEG / PNG / GIF / WebP | URL файлу Slack | Завантажуються й додаються до ходу для обробки з підтримкою бачення | Ліміт на файл: `channels.slack.mediaMaxMb` (типово 20 МБ) |
| Файли PDF | URL файлу Slack | Завантажуються й надаються як файловий контекст для інструментів, як-от `download-file` або `pdf` | Вхідний Slack автоматично не перетворює PDF на вхідні дані для зорового аналізу |
| Інші файли | URL файлу Slack | Завантажуються, коли це можливо, і надаються як файловий контекст | Двійкові файли не обробляються як вхідні зображення |
| Відповіді в гілках | Файли початкового повідомлення гілки | Файли кореневого повідомлення можуть бути підтягнуті як контекст, коли відповідь не має безпосередніх медіа | Початкові повідомлення лише з файлами використовують заповнювач вкладення |
| Повідомлення з кількома зображеннями | Кілька файлів Slack | Кожен файл оцінюється незалежно | Обробка Slack обмежена вісьмома файлами на повідомлення |
### Вхідний конвеєр
Коли надходить повідомлення Slack із файловими вкладеннями:
1. OpenClaw завантажує файл із приватного URL Slack за допомогою токена бота (`xoxb-...`).
2. У разі успіху файл записується до сховища медіа.
1. OpenClaw завантажує файл із приватної URL-адреси Slack за допомогою токена бота (`xoxb-...`).
2. Після успішного завантаження файл записується до сховища медіа.
3. Шляхи завантажених медіа та типи вмісту додаються до вхідного контексту.
4. Шляхи моделі/інструмента з підтримкою зображень можуть використовувати вкладення зображень із цього контексту.
5. Файли, що не є зображеннями, залишаються доступними як файлові метадані або медіапосилання для інструментів, які можуть їх обробляти.
4. Шляхи моделей/інструментів із підтримкою зображень можуть використовувати вкладення зображень із цього контексту.
5. Файли, що не є зображеннями, залишаються доступними як метадані файлів або посилання на медіа для інструментів, які можуть їх обробляти.
### Успадкування вкладень кореня гілки
Коли повідомлення надходить у гілці (має батьківський `thread_ts`):
- Якщо сама відповідь не має прямих медіа, а включене кореневе повідомлення має файли, Slack може підвантажити кореневі файли як контекст початку гілки.
- Прямі вкладення відповіді мають пріоритет над вкладеннями кореневого повідомлення.
- Кореневе повідомлення, яке має лише файли й не має тексту, представляється заповнювачем вкладення, щоб резервний шлях усе одно міг включити його файли.
- Якщо сама відповідь не має безпосередніх медіа, а включене кореневе повідомлення має файли, Slack може підтягнути кореневі файли як контекст початкового повідомлення гілки.
- Безпосередні вкладення відповіді мають пріоритет над вкладеннями кореневого повідомлення.
- Кореневе повідомлення, яке має лише файли й не має тексту, представлено заповнювачем вкладення, щоб резервний шлях усе одно міг включити його файли.
### Обробка кількох вкладень
Коли одне повідомлення Slack містить кілька файлових вкладень:
- Кожне вкладення обробляється незалежно через медіаконвеєр.
- Кожне вкладення обробляється незалежно через медійний конвеєр.
- Посилання на завантажені медіа агрегуються в контекст повідомлення.
- Порядок обробки відповідає порядку файлів Slack у корисному навантаженні події.
- Помилка завантаження одного вкладення не блокує інші.
### Обмеження розміру, завантаження та моделі
- **Ліміт розміру**: типово 20 MB на файл. Налаштовується через `channels.slack.mediaMaxMb`.
- **Помилки завантаження**: файли, які Slack не може надати, прострочені URL, недоступні файли, завеликі файли та HTML-відповіді автентифікації/входу Slack пропускаються замість того, щоб повідомлятися як непідтримувані формати.
- **Модель зорового аналізу**: аналіз зображень використовує активну модель відповіді, коли вона підтримує зоровий аналіз, або модель зображень, налаштовану в `agents.defaults.imageModel`.
- **Ліміт розміру**: типово 20 МБ на файл. Налаштовується через `channels.slack.mediaMaxMb`.
- **Помилки завантаження**: файли, які Slack не може віддати, протерміновані URL-адреси, недоступні файли, завеликі файли та HTML-відповіді Slack для автентифікації/входу пропускаються, а не повідомляються як непідтримувані формати.
- **Модель бачення**: аналіз зображень використовує активну модель відповіді, якщо вона підтримує бачення, або модель зображень, налаштовану в `agents.defaults.imageModel`.
### Відомі обмеження
| Сценарій | Поточна поведінка | Обхідний шлях |
| ------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Прострочений URL файлу Slack | Файл пропускається; помилка не показується | Повторно завантажте файл у Slack |
| Модель зорового аналізу не налаштована | Вкладення зображень зберігаються як медіапосилання, але не аналізуються як зображення | Налаштуйте `agents.defaults.imageModel` або використайте модель відповіді з підтримкою зорового аналізу |
| Дуже великі зображення (> 20 MB типово) | Пропускаються відповідно до ліміту розміру | Збільште `channels.slack.mediaMaxMb`, якщо Slack дозволяє |
| Переслані/поширені вкладення | Текст і розміщені в Slack медіа зображень/файлів обробляються за принципом best-effort | Поділіться ними напряму в гілці OpenClaw |
| PDF-вкладення | Зберігаються як файловий/медіаконтекст, але автоматично не спрямовуються через зоровий аналіз зображень | Використовуйте `download-file` для файлових метаданих або інструмент `pdf` для аналізу PDF |
| Сценарій | Поточна поведінка | Обхідний шлях |
| ------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Протермінована URL-адреса файлу Slack | Файл пропускається; помилка не показується | Повторно завантажте файл у Slack |
| Модель бачення не налаштована | Вкладення зображень зберігаються як посилання на медіа, але не аналізуються як зображення | Налаштуйте `agents.defaults.imageModel` або використайте модель відповіді з підтримкою бачення |
| Дуже великі зображення (> 20 МБ типово) | Пропускаються відповідно до ліміту розміру | Збільште `channels.slack.mediaMaxMb`, якщо Slack дозволяє |
| Переслані/спільні вкладення | Текст і розміщені в Slack медіа зображень/файлів обробляються за принципом найкращої спроби | Поділіться ними безпосередньо в гілці OpenClaw |
| Вкладення PDF | Зберігаються як файловий/медійний контекст, але автоматично не спрямовуються через зоровий аналіз зображень | Використовуйте `download-file` для метаданих файлу або інструмент `pdf` для аналізу PDF |
### Пов’язана документація
- [Конвеєр розуміння медіа](/uk/nodes/media-understanding)
- [Інструмент PDF](/uk/tools/pdf)
- Епік: [#51349](https://github.com/openclaw/openclaw/issues/51349) — увімкнення зорового аналізу вкладень Slack
- Епік: [#51349](https://github.com/openclaw/openclaw/issues/51349) — увімкнення бачення для вкладень Slack
- Регресійні тести: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- Жива перевірка: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## Пов’язане
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/uk/channels/pairing">
Зв’яжіть користувача Slack із Gateway.
<Card title="З’єднання" icon="link" href="/uk/channels/pairing">
З’єднайте користувача Slack із Gateway.
</Card>
<Card title="Groups" icon="users" href="/uk/channels/groups">
Поведінка каналу та групових DM.
<Card title="Групи" icon="users" href="/uk/channels/groups">
Поведінка каналів і групових DM.
</Card>
<Card title="Channel routing" icon="route" href="/uk/channels/channel-routing">
<Card title="Маршрутизація каналу" icon="route" href="/uk/channels/channel-routing">
Спрямовуйте вхідні повідомлення до агентів.
</Card>
<Card title="Security" icon="shield" href="/uk/gateway/security">
<Card title="Безпека" icon="shield" href="/uk/gateway/security">
Модель загроз і посилення захисту.
</Card>
<Card title="Configuration" icon="sliders" href="/uk/gateway/configuration">
<Card title="Конфігурація" icon="sliders" href="/uk/gateway/configuration">
Структура конфігурації та пріоритетність.
</Card>
<Card title="Slash commands" icon="terminal" href="/uk/tools/slash-commands">
<Card title="Slash-команди" icon="terminal" href="/uk/tools/slash-commands">
Каталог команд і поведінка.
</Card>
</CardGroup>

101
docs/uk/channels/synology-chat.md
View File

@ -5,24 +5,24 @@ read_when:
summary: Налаштування Webhook Synology Chat і конфігурація OpenClaw
title: Synology Chat
x-i18n:
generated_at: "2026-04-29T05:57:06Z"
generated_at: "2026-05-02T04:47:18Z"
model: gpt-5.5
provider: openai
source_hash: c3d6d7a56bd15d29de38c6ae29ae496b491c2e75df5e0a0a15410b0fbdc55a00
source_hash: 1f1946425fa6e7a071b03d212854476dc2c0af98097f38da93d3711e5a5c7e96
source_path: channels/synology-chat.md
workflow: 16
---
Стан: вбудований Plugin каналу прямих повідомлень, що використовує webhooks Synology Chat.
Plugin приймає вхідні повідомлення від вихідних webhooks Synology Chat і надсилає відповіді
через вхідний webhook Synology Chat.
Стан: bundled Plugin для каналу прямих повідомлень із використанням Synology Chat webhooks.
Plugin приймає вхідні повідомлення від Synology Chat outgoing webhooks і надсилає відповіді
через Synology Chat incoming webhook.
## Вбудований Plugin
## Bundled plugin
Synology Chat постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні
Synology Chat постачається як bundled Plugin у поточних випусках OpenClaw, тому звичайні
пакетні збірки не потребують окремого встановлення.
Якщо ви використовуєте старішу збірку або кастомне встановлення, яке виключає Synology Chat,
Якщо ви використовуєте старішу збірку або власне встановлення, яке не містить Synology Chat,
встановіть його вручну:
Встановлення з локального checkout:
@ -36,31 +36,31 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
## Швидке налаштування
1. Переконайтеся, що Plugin Synology Chat доступний.
- Поточні пакетні випуски OpenClaw вже включають його.
- Старіші/кастомні встановлення можуть додати його вручну з checkout вихідного коду за допомогою команди вище.
- Поточні пакетні випуски OpenClaw вже містять його.
- У старіших/власних встановленнях його можна додати вручну з source checkout за допомогою наведеної вище команди.
- `openclaw onboard` тепер показує Synology Chat у тому самому списку налаштування каналів, що й `openclaw channels add`.
- Неінтерактивне налаштування: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. В інтеграціях Synology Chat:
- Створіть вхідний webhook і скопіюйте його URL.
- Створіть вихідний webhook із вашим секретним токеном.
3. Спрямуйте URL вихідного webhook до вашого OpenClaw gateway:
- Створіть incoming webhook і скопіюйте його URL.
- Створіть outgoing webhook із вашим секретним токеном.
3. Спрямуйте URL outgoing webhook на ваш OpenClaw gateway:
- `https://gateway-host/webhook/synology` за замовчуванням.
- Або ваш кастомний `channels.synology-chat.webhookPath`.
- Або ваш власний `channels.synology-chat.webhookPath`.
4. Завершіть налаштування в OpenClaw.
- Інтерактивно: `openclaw onboard`
- З майстром: `openclaw onboard`
- Напряму: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
5. Перезапустіть gateway і надішліть DM боту Synology Chat.
Деталі автентифікації webhook:
Подробиці автентифікації webhook:
- OpenClaw приймає токен вихідного webhook з `body.token`, потім
- OpenClaw приймає токен outgoing webhook з `body.token`, потім
`?token=...`, потім із заголовків.
- Прийнятні форми заголовків:
- Прийняті форми заголовків:
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- Порожні або відсутні токени закривають доступ.
- Порожні або відсутні токени завершуються закритою відмовою.
Мінімальна конфігурація:
@ -83,32 +83,32 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
## Змінні середовища
Для типового облікового запису можна використовувати змінні середовища:
Для облікового запису за замовчуванням можна використовувати змінні середовища:
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
- `SYNOLOGY_NAS_HOST`
- `SYNOLOGY_ALLOWED_USER_IDS` (через кому)
- `SYNOLOGY_ALLOWED_USER_IDS` (розділені комами)
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
Значення конфігурації перевизначають змінні середовища.
`SYNOLOGY_CHAT_INCOMING_URL` не можна встановити з workspace `.env`; див. [Файли workspace `.env`](/uk/gateway/security).
`SYNOLOGY_CHAT_INCOMING_URL` не можна встановити з workspace `.env`; див. [Workspace `.env` files](/uk/gateway/security).
## Політика DM і контроль доступу
- `dmPolicy: "allowlist"` є рекомендованим типовим значенням.
- `dmPolicy: "allowlist"` є рекомендованим значенням за замовчуванням.
- `allowedUserIds` приймає список (або рядок, розділений комами) ідентифікаторів користувачів Synology.
- У режимі `allowlist` порожній список `allowedUserIds` вважається помилковою конфігурацією, і маршрут webhook не запуститься (використовуйте `dmPolicy: "open"` з `allowedUserIds: ["*"]` для дозволу всім).
- `dmPolicy: "open"` дозволяє публічні DM лише коли `allowedUserIds` містить `"*"`; з обмежувальними записами спілкуватися можуть лише відповідні користувачі.
- `dmPolicy: "disabled"` блокує DM.
- Прив’язка одержувача відповіді за замовчуванням лишається на стабільному числовому `user_id`. `channels.synology-chat.dangerouslyAllowNameMatching: true` — це режим сумісності на крайній випадок, який повторно вмикає пошук за змінюваним username/nickname для доставки відповідей.
- Схвалення сполучення працюють із:
- Прив’язка отримувача відповіді за замовчуванням залишається на стабільному числовому `user_id`. `channels.synology-chat.dangerouslyAllowNameMatching: true` — це режим сумісності на випадок аварійного відновлення, який знову вмикає пошук за змінним іменем користувача/нікнеймом для доставлення відповідей.
- Схвалення pairing працюють із:
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
## Вихідна доставка
## Вихідне доставлення
Використовуйте числові ідентифікатори користувачів Synology Chat як цілі.
@ -117,22 +117,23 @@ openclaw plugins install ./path/to/local/synology-chat-plugin
```bash
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
openclaw message send --channel synology-chat --target synology:123456 --text "Short prefix"
```
Надсилання медіа підтримується через доставку файлів за URL.
Вихідні URL файлів мають використовувати `http` або `https`, а приватні або інакше заблоковані мережеві цілі відхиляються до того, як OpenClaw передасть URL до webhook NAS.
Надсилання медіа підтримується через доставлення файлів на основі URL.
Вихідні URL файлів мають використовувати `http` або `https`, а приватні чи інакше заблоковані мережеві цілі відхиляються до того, як OpenClaw переспрямує URL до NAS webhook.
## Кілька облікових записів
Кілька облікових записів Synology Chat підтримуються в `channels.synology-chat.accounts`.
Кожен обліковий запис може перевизначати токен, вхідний URL, шлях webhook, політику DM і ліміти.
Сесії прямих повідомлень ізольовані за обліковим записом і користувачем, тому той самий числовий `user_id`
у двох різних облікових записах Synology не спільно використовує стан transcript.
Надайте кожному ввімкненому обліковому запису окремий `webhookPath`. OpenClaw тепер відхиляє дублікати точних шляхів
і відмовляється запускати іменовані облікові записи, які лише успадковують спільний шлях webhook у налаштуваннях із кількома обліковими записами.
Кожен обліковий запис може перевизначати токен, incoming URL, шлях webhook, політику DM і ліміти.
Сеанси прямих повідомлень ізольовані за обліковим записом і користувачем, тому той самий числовий `user_id`
у двох різних облікових записах Synology не має спільного стану transcript.
Надайте кожному ввімкненому обліковому запису окремий `webhookPath`. OpenClaw тепер відхиляє точні дублікати шляхів
і відмовляється запускати іменовані облікові записи, які лише успадковують спільний шлях webhook у конфігураціях із кількома обліковими записами.
Якщо вам навмисно потрібне застаріле успадкування для іменованого облікового запису, встановіть
`dangerouslyAllowInheritedWebhookPath: true` для цього облікового запису або в `channels.synology-chat`,
але дублікати точних шляхів усе одно відхиляються із закриттям доступу. Надавайте перевагу явним шляхам для кожного облікового запису.
але точні дублікати шляхів усе одно відхиляються закритою відмовою. Надавайте перевагу явним шляхам для кожного облікового запису.
```json5
{
@ -157,37 +158,37 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te
}
```
## Нотатки щодо безпеки
## Примітки з безпеки
- Зберігайте `token` у секреті та ротуйте його в разі витоку.
- Тримайте `token` у секреті та ротируйте його в разі витоку.
- Залишайте `allowInsecureSsl: false`, якщо ви явно не довіряєте самопідписаному локальному сертифікату NAS.
- Вхідні запити webhook перевіряються за токеном і обмежуються за частотою для кожного відправника.
- Перевірки недійсного токена використовують порівняння секретів зі сталим часом виконання та закривають доступ.
- Для production надавайте перевагу `dmPolicy: "allowlist"`.
- Тримайте `dangerouslyAllowNameMatching` вимкненим, якщо вам явно не потрібна застаріла доставка відповідей на основі username.
- Тримайте `dangerouslyAllowInheritedWebhookPath` вимкненим, якщо ви явно не приймаєте ризик маршрутизації через спільний шлях у налаштуванні з кількома обліковими записами.
- Перевірки недійсних токенів використовують порівняння секретів зі сталим часом і завершуються закритою відмовою.
- Надавайте перевагу `dmPolicy: "allowlist"` для production.
- Тримайте `dangerouslyAllowNameMatching` вимкненим, якщо вам явно не потрібне застаріле доставлення відповідей на основі імен користувачів.
- Тримайте `dangerouslyAllowInheritedWebhookPath` вимкненим, якщо ви явно не приймаєте ризик маршрутизації через спільний шлях у конфігурації з кількома обліковими записами.
## Усунення несправностей
- `Missing required fields (token, user_id, text)`:
- у payload вихідного webhook бракує одного з обов’язкових полів
- у payload outgoing webhook відсутнє одне з обов’язкових полів
- якщо Synology надсилає токен у заголовках, переконайтеся, що gateway/proxy зберігає ці заголовки
- `Invalid token`:
- секрет вихідного webhook не відповідає `channels.synology-chat.token`
- запит потрапляє в неправильний обліковий запис/шлях webhook
- reverse proxy видалив заголовок токена до того, як запит досяг OpenClaw
- секрет outgoing webhook не збігається з `channels.synology-chat.token`
- запит потрапляє до неправильного облікового запису/шляху webhook
- reverse proxy видалив заголовок токена до того, як запит дістався OpenClaw
- `Rate limit exceeded`:
- забагато спроб із недійсним токеном з одного джерела можуть тимчасово заблокувати це джерело
- автентифіковані відправники також мають окремий ліміт повідомлень для кожного користувача
- автентифіковані відправники також мають окремий ліміт повідомлень на користувача
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open with allowedUserIds=["*"].`:
- `dmPolicy="allowlist"` увімкнено, але користувачів не налаштовано
- `User not authorized`:
- числовий `user_id` відправника не входить до `allowedUserIds`
- числовий `user_id` відправника відсутній у `allowedUserIds`
## Пов’язане
- [Огляд каналів](/uk/channels) — усі підтримувані канали
- [Сполучення](/uk/channels/pairing) — автентифікація DM і потік сполучення
- [Групи](/uk/channels/groups) — поведінка групового чату та gating згадок
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та посилення безпеки
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
- [Групи](/uk/channels/groups) — поведінка групових чатів і обмеження за згадками
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту

452
docs/uk/channels/telegram.md
View File

@ -1,28 +1,28 @@
---
read_when:
- Робота з функціями Telegram або Webhook
summary: Стан підтримки, можливості та налаштування бота Telegram
- Робота над функціями Telegram або Webhook
summary: Стан підтримки, можливості та конфігурація бота Telegram
title: Telegram
x-i18n:
generated_at: "2026-04-30T15:20:22Z"
generated_at: "2026-05-02T04:47:11Z"
model: gpt-5.5
provider: openai
source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd
source_hash: e6ef6fc51d18f4bde9219b75b69da204e18a227b40c4c916eae701494c099de3
source_path: channels/telegram.md
workflow: 16
---
Готово до production для DM ботів і груп через grammY. Довге опитування є стандартним режимом; режим Webhook необов’язковий.
Готово до продакшну для особистих повідомлень бота й груп через grammY. Режим довгого опитування є типовим; режим Webhook необов’язковий.
<CardGroup cols={3}>
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
Типова політика DM для Telegram — сполучення.
Типова політика особистих повідомлень для 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">
Повні шаблони та приклади конфігурації каналів.
Повні шаблони й приклади конфігурації каналів.
</Card>
</CardGroup>
@ -30,13 +30,13 @@ x-i18n:
<Steps>
<Step title="Створіть токен бота в BotFather">
Відкрийте Telegram і напишіть **@BotFather** (переконайтеся, що handle точно `@BotFather`).
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я користувача точно `@BotFather`).
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
</Step>
<Step title="Налаштуйте токен і політику DM">
<Step title="Налаштуйте токен і політику особистих повідомлень">
```json5
{
@ -51,12 +51,12 @@ x-i18n:
}
```
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише стандартний обліковий запис).
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, потім запустіть gateway.
Резервний env: `TELEGRAM_BOT_TOKEN=...` (лише типовий обліковий запис).
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації/env, потім запустіть Gateway.
</Step>
<Step title="Запустіть gateway і схваліть перший DM">
<Step title="Запустіть Gateway і схваліть перше особисте повідомлення">
```bash
openclaw gateway
@ -74,71 +74,71 @@ openclaw pairing approve telegram <CODE>
</Steps>
<Note>
Порядок визначення токена враховує обліковий запис. На практиці значення з конфігурації мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до стандартного облікового запису.
Порядок визначення токена враховує обліковий запис. На практиці значення конфігурації мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до типового облікового запису.
</Note>
## Налаштування на боці Telegram
<AccordionGroup>
<Accordion title="Режим приватності та видимість у групах">
Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує, які групові повідомлення вони отримують.
Боти Telegram типово використовують **режим приватності**, який обмежує, які групові повідомлення вони отримують.
Якщо бот має бачити всі групові повідомлення, зробіть одне з такого:
Якщо бот має бачити всі групові повідомлення, або:
- вимкніть режим приватності через `/setprivacy`, або
- зробіть бота адміністратором групи.
Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну.
Після перемикання режиму приватності видаліть і знову додайте бота в кожній групі, щоб Telegram застосував зміну.
</Accordion>
<Accordion title="Дозволи групи">
Статус адміністратора керується в налаштуваннях групи Telegram.
Боти-адміністратори отримують усі групові повідомлення, що корисно для постійної поведінки в групі.
Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі.
</Accordion>
<Accordion title="Корисні перемикачі BotFather">
- `/setjoingroups` для дозволу/заборони додавання до груп
- `/setjoingroups`, щоб дозволити/заборонити додавання до груп
- `/setprivacy` для поведінки видимості в групах
</Accordion>
</AccordionGroup>
## Контроль доступу та активація
## Контроль доступу й активація
<Tabs>
<Tab title="Політика DM">
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
<Tab title="Політика особистих повідомлень">
`channels.telegram.dmPolicy` керує доступом через особисті повідомлення:
- `pairing` (за замовчуванням)
- `allowlist` (потребує принаймні одного ID відправника в `allowFrom`)
- `open` (потребує, щоб `allowFrom` містив `"*"`)
- `pairing` (типово)
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
- `disabled`
`dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` з числовими ID користувачів.
`dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із суворо обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний allowlist облікового запису після об’єднання все ще не містить явний wildcard.
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється перевіркою конфігурації.
У конфігураціях із кількома обліковими записами обмежувальний верхньорівневий `channels.telegram.allowFrom` розглядається як межа безпеки: записи рівня облікового запису `allowFrom: ["*"]` не роблять цей обліковий запис публічним, якщо ефективний список дозволених облікового запису після об’єднання все ще не містить явного wildcard.
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі особисті повідомлення й відхиляється перевіркою конфігурації.
Налаштування запитує лише числові ID користувачів.
Якщо ви оновилися і ваша конфігурація містить записи allowlist `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потребує токен бота Telegram).
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
Якщо ви оновилися й ваша конфігурація містить записи списку дозволених `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен бота Telegram).
Якщо раніше ви покладалися на файли списку дозволених зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках списку дозволених (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу надійно зберігалася в конфігурації (замість залежності від попередніх схвалень сполучення).
Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була стійкою в конфігурації (а не залежала від попередніх схвалень сполучення).
Поширена плутанина: схвалення сполучення DM не означає "цей відправник авторизований всюди".
Сполучення надає доступ до DM. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
Авторизація відправників у групах усе ще надходить із явних allowlist у конфігурації.
Якщо ви хочете "я авторизований один раз, і працюють і DM, і групові команди", додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
Поширена плутанина: схвалення сполучення в особистих повідомленнях не означає «цей відправник авторизований всюди».
Сполучення надає доступ до особистих повідомлень. Якщо власника команд ще немає, перше схвалене сполучення також задає `commands.ownerAllowFrom`, щоб команди лише для власника та схвалення exec мали явний обліковий запис оператора.
Авторизація відправника в групі все одно походить із явних списків дозволених у конфігурації.
Якщо ви хочете «я авторизований один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`; для команд лише для власника переконайтеся, що `commands.ownerAllowFrom` містить `telegram:<your user id>`.
### Як знайти свій ID користувача Telegram
Безпечніше (без стороннього бота):
1. Напишіть своєму боту в DM.
1. Напишіть своєму боту в особисті повідомлення.
2. Виконайте `openclaw logs --follow`.
3. Прочитайте `from.id`.
@ -152,29 +152,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Tab>
<Tab title="Політика груп і allowlist">
<Tab title="Політика груп і списки дозволених">
Два елементи керування застосовуються разом:
1. **Які групи дозволені** (`channels.telegram.groups`)
- немає конфігурації `groups`:
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
- `groups` налаштовано: діє як allowlist (явні ID або `"*"`)
- з `groupPolicy: "allowlist"` (типово): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
- `groups` налаштовано: діє як список дозволених (явні ID або `"*"`)
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
- `open`
- `allowlist` (за замовчуванням)
- `allowlist` (типово)
- `disabled`
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram використовує резервний `allowFrom`.
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`.
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються).
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Від’ємні ID чатів належать до `channels.telegram.groups`.
Нечислові записи ігноруються для авторизації відправників.
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища сполучень DM.
Сполучення лишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` для конкретної групи/теми.
Якщо `groupAllowFrom` не задано, Telegram використовує резервний config `allowFrom`, а не сховище сполучень.
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`.
Нечислові записи ігноруються для авторизації відправника.
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень особистих повідомлень.
Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми.
Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища сполучень.
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed до `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime типово закривається безпечно з `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
Приклад: дозволити будь-якого учасника в одній конкретній групі:
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи:
Приклад: дозволити лише конкретних користувачів в одній конкретній групі:
```json5
{
@ -211,18 +211,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
<Warning>
Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram.
Поширена помилка: `groupAllowFrom` — це не список дозволених груп Telegram.
- Додавайте від’ємні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
- Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг говорити з ботом.
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
</Warning>
</Tab>
<Tab title="Поведінка згадок">
Групові відповіді за замовчуванням потребують згадки.
Відповіді в групах типово потребують згадки.
Згадка може надходити з:
@ -231,14 +231,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
Перемикачі команд на рівні сесії:
Перемикачі команд рівня сесії:
- `/activation always`
- `/activation mention`
Вони оновлюють лише стан сесії. Використовуйте конфігурацію для постійності.
Вони оновлюють лише стан сесії. Використовуйте конфігурацію для збереження.
Приклад постійної конфігурації:
Приклад сталої конфігурації:
```json5
{
@ -256,22 +256,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- перешліть групове повідомлення до `@userinfobot` / `@getidsbot`
- або прочитайте `chat.id` з `openclaw logs --follow`
- або перевірте Bot API `getUpdates`
- або перегляньте Bot API `getUpdates`
</Tab>
</Tabs>
## Поведінка runtime
- Telegram належить процесу gateway.
- Telegram належить процесу Gateway.
- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали).
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та placeholders для медіа.
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб ізолювати теми.
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає ID thread для відповідей.
- Довге опитування використовує grammY runner із послідовністю на рівні чату/thread. Загальна concurrency sink у runner використовує `agents.defaults.maxConcurrent`.
- Довге опитування захищене всередині кожного процесу gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший OpenClaw gateway, script або зовнішній poller використовує той самий токен.
- Перезапуски watchdog для довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення задається в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для кожного облікового запису.
- Telegram Bot API не підтримує read receipts (`sendReadReceipts` не застосовується).
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб теми залишалися ізольованими.
- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують потік, і зберігає ID потоку для відповідей.
- Довге опитування використовує runner grammY із послідовністю на рівні чату/потоку. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
- Довге опитування захищене всередині кожного процесу Gateway, щоб лише один активний poller міг використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, інший Gateway OpenClaw, скрипт або зовнішній poller, імовірно, використовує той самий токен.
- Перезапуски watchdog для довгого опитування типово спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через polling-stall під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення на рівні облікового запису.
- Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується).
## Довідник функцій
@ -284,12 +284,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Вимога:
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
- `channels.telegram.streaming` має значення `off | partial | block | progress` (типово: `partial`)
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням)
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли streaming попереднього перегляду активний)
- застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (типово: `true`, коли потоковий попередній перегляд активний)
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Працюю...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніших версій. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Working...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки патчів. Telegram залишає їх увімкненими типово, щоб відповідати випущеній поведінці OpenClaw з `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
```json
{
@ -306,16 +306,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення "Працюю...". Запити на схвалення, медіа payloads і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
Використовуйте `streaming.mode: "off"` лише тоді, коли потрібна доставка тільки фінальної відповіді: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу приглушуються замість надсилання як окремі повідомлення «Working...». Запити схвалення, медіа-навантаження й помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши статусні рядки прогресу інструментів.
Для відповідей лише з текстом:
- короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
- попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима позначка часу Telegram відображала час завершення, а не час створення попереднього перегляду
- короткі попередні перегляди в особистих повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
- попередні перегляди старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім прибирає попередній перегляд, щоб видима часова позначка Telegram відображала час завершення, а не час створення попереднього перегляду
Для складних відповідей (наприклад, медіа-навантажень) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
Для складних відповідей (наприклад, медіа-вмісту) OpenClaw повертається до звичайної фінальної доставки, а потім прибирає повідомлення попереднього перегляду.
Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
Потокове передавання попереднього перегляду відокремлене від потокового передавання блоків. Коли потокове передавання блоків явно ввімкнено для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання.
Потік міркувань лише для Telegram:
@ -324,25 +324,25 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Formatting and HTML fallback">
<Accordion title="Форматування та резервний варіант HTML">
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору Telegram.
- Текст у стилі Markdown відтворюється як безпечний для Telegram HTML.
- Сирий HTML від моделі екранується, щоб зменшити кількість помилок розбору Telegram.
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
Попередні перегляди посилань увімкнено за замовчуванням, їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`.
</Accordion>
<Accordion title="Native commands and custom commands">
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
<Accordion title="Вбудовані команди та користувацькі команди">
Реєстрація меню команд Telegram обробляється під час запуску за допомогою `setMyCommands`.
Типові значення власних команд:
Типові значення вбудованих команд:
- `commands.native: "auto"` вмикає власні команди для Telegram
- `commands.native: "auto"` вмикає вбудовані команди для Telegram
Додайте власні записи меню команд:
Додайте користувацькі записи меню команд:
```json5
{
@ -359,47 +359,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Правила:
- імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
- імена нормалізуються (видаляється початковий `/`, нижній регістр)
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
- власні команди не можуть перевизначати вбудовані команди
- конфлікти/дублікати пропускаються й записуються в журнал
- користувацькі команди не можуть перевизначати вбудовані команди
- конфлікти/дублікати пропускаються та записуються в журнал
Примітки:
- власні команди є лише записами меню; вони не реалізують поведінку автоматично
- команди plugin/skill можуть і далі працювати під час введення, навіть якщо їх не показано в меню Telegram
- користувацькі команди є лише записами меню; вони не реалізують поведінку автоматично
- команди plugin/skill усе ще можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
Якщо власні команди вимкнено, вбудовані видаляються. Користувацькі команди або команди Plugin можуть і далі реєструватися, якщо це налаштовано.
Якщо вбудовані команди вимкнено, вбудовані елементи видаляються. Користувацькі/plugin-команди все ще можуть реєструватися, якщо це налаштовано.
Поширені помилки налаштування:
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнилося після обрізання; зменште кількість команд Plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`.
- помилки `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, можуть означати, що `channels.telegram.apiRoot` було встановлено як повну кінцеву точку `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд plugin/skill/користувацьких команд або вимкніть `channels.telegram.commands.native`.
- Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди Bot API через curl працюють, може означати, що `channels.telegram.apiRoot` було встановлено на повну кінцеву точку `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
- `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до опитування, тому це не повідомляється як помилка очищення Webhook.
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано.
- `setMyCommands failed` з мережевими/fetch-помилками зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано.
### Команди сполучення пристрою (Plugin `device-pair`)
Коли Plugin `device-pair` встановлено:
Коли встановлено Plugin `device-pair`:
1. `/pair` генерує код налаштування
2. вставте код у застосунок iOS
3. `/pair pending` перелічує запити, що очікують (включно з роллю/областями)
4. схваліть запит:
- `/pair approve <requestId>` для явного схвалення
- `/pair approve`, коли є лише один запит, що очікує
3. `/pair pending` перелічує запити в очікуванні (включно з роллю/областями дії)
4. затвердьте запит:
- `/pair approve <requestId>` для явного затвердження
- `/pair approve`, коли є лише один запит в очікуванні
- `/pair approve latest` для найновішого
Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного Node на `scopes: []`; будь-який переданий токен оператора лишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки області bootstrap мають префікс ролі, тому цей список дозволів оператора задовольняє лише запити оператора; ролі, що не є операторськими, усе ще потребують областей під власним префіксом ролі.
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролі неоператорів усе ще потребують областей дії під власним префіксом ролі.
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області/публічний ключ), попередній запит, що очікував, замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роллю/областями дії/публічним ключем), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед затвердженням.
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
</Accordion>
<Accordion title="Inline buttons">
Налаштуйте область inline-клавіатури:
<Accordion title="Вбудовані кнопки">
Налаштуйте область дії вбудованої клавіатури:
```json5
{
@ -431,7 +431,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Області:
Області дії:
- `off`
- `dm`
@ -439,7 +439,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `all`
- `allowlist` (за замовчуванням)
Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`.
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
Приклад дії повідомлення:
@ -464,36 +464,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Telegram message actions for agents and automation">
<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`).
Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
Елементи керування обмеженнями:
Елементи керування доступом:
- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
Надсилання під час виконання використовує активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
Примітка: `edit` і `topic-create` наразі ввімкнено за замовчуванням, і вони не мають окремих перемикачів `channels.telegram.actions.*`.
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
</Accordion>
<Accordion title="Reply threading tags">
Telegram підтримує явні теги гілкування відповідей у згенерованому виводі:
<Accordion title="Теги потоків відповідей">
Telegram підтримує явні теги потоків відповідей у згенерованому виводі:
- `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск
- `[[reply_to:<id>]]` відповідає на певний ID повідомлення Telegram
- `[[reply_to_current]]` відповідає на повідомлення, яке спричинило запуск
- `[[reply_to:<id>]]` відповідає на конкретний ідентифікатор повідомлення Telegram
`channels.telegram.replyToMode` керує обробкою:
@ -501,29 +501,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
Коли гілкування відповідей увімкнено й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає вбудований фрагмент цитати Telegram. Telegram обмежує власний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
Коли потоки відповідей увімкнено й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
Примітка: `off` вимикає неявне гілкування відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються.
Примітка: `off` вимикає неявні потоки відповідей. Явні теги `[[reply_to_*]]` усе ще враховуються.
</Accordion>
<Accordion title="Forum topics and thread behavior">
Форумні супергрупи:
<Accordion title="Теми форуму та поведінка потоків">
Супергрупи форуму:
- ключі сесій тем додають `:topic:<threadId>`
- відповіді та індикатор набору тексту спрямовуються в гілку теми
- ключі сесій теми додають `:topic:<threadId>`
- відповіді та індикатор набору спрямовуються до потоку теми
- шлях конфігурації теми:
`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` є лише для теми й не успадковується з типових значень групи.
Успадкування теми: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` стосується лише теми й не успадковується з типових значень групи.
**Маршрутизація агента за темою**: кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
**Маршрутизація агентів за темами**: кожна тема може спрямовуватися до іншого агента через налаштування `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
```json5
{
@ -545,23 +545,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
**Постійне прив’язування тем ACP**: форумні теми можуть закріплювати сесії ACP harness через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та кваліфікованим за темою id на кшталт `-1001234567890:topic:42`). Наразі обмежено форумними темами в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
**Постійне прив’язування теми ACP**: теми форуму можуть закріплювати сесії обв’язки ACP через типізовані прив’язування ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із кваліфікатором теми, як-от `-1001234567890:topic:42`). Наразі обмежено темами форуму в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
**Прив’язаний до гілки запуск ACP з чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження запуску в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`.
**Створення ACP, прив’язане до потоку, з чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потребує `channels.telegram.threadBindings.spawnAcpSessions=true`.
Контекст шаблону відкриває `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням гілок.
Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати в особистих повідомленнях із `message_thread_id` зберігають маршрутизацію особистих повідомлень, але використовують ключі сесій з урахуванням потоку.
</Accordion>
<Accordion title="Audio, video, and stickers">
<Accordion title="Аудіо, відео та стікери">
### Аудіоповідомлення
Telegram розрізняє голосові нотатки та аудіофайли.
- за замовчуванням: поведінка аудіофайла
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосову нотатку
- транскрипти вхідних голосових нотаток оформлюються як машинно згенерований,
ненадійний текст у контексті агента; виявлення згадок усе ще використовує сирий
- за замовчуванням: поведінка аудіофайлу
- тег `[[audio_as_voice]]` у відповіді агента, щоб примусово надіслати голосову нотатку
- вхідні транскрипти голосових нотаток оформлюються як згенерований машиною,
недовірений текст у контексті агента; виявлення згадок усе ще використовує сирий
транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати.
Приклад дії повідомлення:
@ -614,7 +614,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `~/.openclaw/telegram/sticker-cache.json`
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики зору.
Увімкніть дії зі стікерами:
@ -654,8 +654,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Reaction notifications">
Реакції Telegram надходять як оновлення `message_reaction` (окремо від навантажень повідомлень).
<Accordion title="Сповіщення про реакції">
Реакції Telegram надходять як оновлення `message_reaction` (окремо від вмісту повідомлень).
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
@ -668,39 +668,39 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Примітки:
- `own` означає лише реакції користувача на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращих зусиль через кеш надісланих повідомлень).
- Події реакцій усе одно поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
- Telegram не надає ідентифікатори тем у оновленнях реакцій.
- нефорумні групи маршрутизуються до сесії групового чату
- форумні групи маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
- групи без форуму маршрутизуються до сеансу групового чату
- групи з форумом маршрутизуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми
`allowed_updates` для polling/Webhook автоматично включає `message_reaction`.
`allowed_updates` для polling/webhook автоматично містить `message_reaction`.
</Accordion>
<Accordion title="Реакції підтвердження">
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
<Accordion title="Підтверджувальні реакції">
`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення.
Порядок визначення:
- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- резервний емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
Примітки:
- Telegram очікує емодзі Unicode (наприклад "👀").
- Telegram очікує unicode emoji (наприклад "👀").
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
</Accordion>
<Accordion title="Записи конфігурації з подій і команд Telegram">
Записи конфігурації каналу ввімкнені за замовчуванням (`configWrites !== false`).
Записи конфігурації каналу ввімкнено за замовчуванням (`configWrites !== false`).
Записи, ініційовані Telegram, включають:
- події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
- події міграції груп (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
- `/config set` і `/config unset` (потребує ввімкнення команд)
Вимкнення:
@ -717,38 +717,38 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Довге опитування проти Webhook">
За замовчуванням використовується довге опитування. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (типові значення `/telegram-webhook`, `127.0.0.1`, `8787`).
<Accordion title="Long polling проти webhook">
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте зворотний проксі перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
Режим Webhook перевіряє захист запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram.
Потім OpenClaw обробляє оновлення асинхронно через ті самі доріжки бота для кожного чату/теми, що й довге опитування, тому повільні ходи агента не затримують ACK доставки Telegram.
Режим webhook перевіряє запобіжники запиту, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram.
Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/теми, що й long polling, тому повільні ходи агента не затримують ACK доставки Telegram.
</Accordion>
<Accordion title="Ліміти, повторні спроби та цілі CLI">
- Типове значення `channels.telegram.textChunkLimit` — 4000.
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
- `channels.telegram.mediaMaxMb` (типово 100) обмежує розмір вхідних і вихідних медіа Telegram.
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY). Клієнти ботів із довгим опитуванням обмежують налаштовані значення нижче 45-секундного захисту запиту `getUpdates`, щоб бездіяльні опитування не переривалися до завершення 30-секундного вікна опитування.
- Типове значення `channels.telegram.pollingStallThresholdMs` — `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання опитування.
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (типово 50); `0` вимикає.
- додатковий контекст відповіді/цитати/пересилання наразі передається як отримано.
- списки дозволених Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
<Accordion title="Обмеження, повторні спроби та цілі CLI">
- `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000.
- `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
- `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram.
- `channels.telegram.timeoutSeconds` перевизначає таймаут клієнта Telegram API (якщо не задано, застосовується стандартне значення grammY). Клієнти ботів long-polling затискають налаштовані значення нижче 45-секундного запобіжника запиту `getUpdates`, щоб idle polls не переривалися до завершення 30-секундного вікна polling.
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зупинку polling.
- Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає.
- Додатковий контекст відповіді/цитати/пересилання наразі передається як отримано.
- Списки дозволених Telegram насамперед контролюють, хто може запускати агента, а не є повною межею редагування додаткового контексту.
- Керування історією DM:
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- Конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/інструменти/дії) для відновлюваних помилок вихідного API. Доставка остаточної вхідної відповіді також використовує обмежену безпечну повторну спробу надсилання для збоїв Telegram перед підключенням, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення.
- Конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних вихідних помилок API. Доставка фінальної відповіді для вхідних повідомлень також використовує обмежену безпечну повторну спробу надсилання для помилок Telegram до з’єднання, але не повторює неоднозначні мережеві оболонки після надсилання, які можуть дублювати видимі повідомлення.
Ціль надсилання CLI може бути числовим ідентифікатором чату або іменем користувача:
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
```
Опитування Telegram використовують `openclaw message poll` і підтримують форумні теми:
Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму:
```bash
openclaw message poll --channel telegram --target 123456789 \
@ -763,52 +763,52 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` для форумних тем (або використовуйте ціль `:topic:`)
- `--thread-id` для тем форуму (або використовуйте ціль `:topic:`)
Надсилання Telegram також підтримує:
- `--presentation` з блоками `buttons` для вбудованих клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, коли бот може закріплювати в цьому чаті
- `--force-document` для надсилання вихідних зображень і GIF як документів замість стиснених фото або завантажень анімованих медіа
- `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
- `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media
Обмеження дій:
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
</Accordion>
<Accordion title="Схвалення exec у Telegram">
Telegram підтримує схвалення exec у DM схвалювачів і може необов’язково публікувати запити в початковому чаті або темі. Схвалювачі мають бути числовими ідентифікаторами користувачів Telegram.
<Accordion title="Exec approvals у Telegram">
Telegram підтримує exec approvals у DM затверджувачів і може необов’язково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.
Шлях конфігурації:
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного схвалювача)
- `channels.telegram.execApprovals.approvers` (повертається до числових ідентифікаторів власників із `commands.ownerAllowFrom`)
- `channels.telegram.execApprovals.target`: `dm` (типово) | `channel` | `both`
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача)
- `channels.telegram.execApprovals.approvers` (відступає до числових ID власників із `commands.ownerAllowFrom`)
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
- `agentFilter`, `sessionFilter`
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` керують тим, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось схвалювачем exec. Перше схвалене з’єднання DM завантажує `commands.ownerAllowFrom`, коли власника команд ще не існує, тому налаштування з одним власником усе одно працює без дублювання ідентифікаторів у `execApprovals.approvers`.
`channels.telegram.allowFrom`, `groupAllowFrom` і `defaultTo` контролюють, хто може говорити з ботом і куди він надсилає звичайні відповіді. Вони не роблять когось exec approver. Перше схвалене сполучення DM завантажує `commands.ownerAllowFrom`, коли власника команд ще не існує, тому налаштування з одним власником усе одно працює без дублювання ID у `execApprovals.approvers`.
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє у форумну тему, OpenClaw зберігає тему для запиту схвалення та подальшого повідомлення. Термін дії схвалень exec за замовчуванням спливає через 30 хвилин.
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише у довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на схвалення й подальшого повідомлення. Exec approvals за замовчуванням спливають через 30 хвилин.
Вбудовані кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). Ідентифікатори схвалення з префіксом `plugin:` визначаються через схвалення Plugin; інші спершу визначаються через схвалення exec.
Inline-кнопки схвалення також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID схвалень із префіксом `plugin:` визначаються через схвалення plugin; інші спершу визначаються через exec approvals.
Див. [Схвалення exec](/uk/tools/exec-approvals).
Див. [Exec approvals](/uk/tools/exec-approvals).
</Accordion>
</AccordionGroup>
## Керування відповідями про помилки
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або приховати її. Цю поведінку контролюють два ключі конфігурації:
Коли агент стикається з помилкою доставки або provider, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації:
| Ключ | Значення | Типово | Опис |
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю приховує відповіді про помилки. |
| `channels.telegram.errorCooldownMs` | число (мс) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. |
| Ключ | Значення | За замовчуванням | Опис |
| ----------------------------------- | ----------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. |
| `channels.telegram.errorCooldownMs` | число (мс) | `60000` | Мінімальний час між відповідями про помилки до того самого чату. Запобігає спаму помилками під час збоїв. |
Підтримуються перевизначення для облікового запису, групи й теми (таке саме успадкування, як і для інших ключів конфігурації Telegram).
Підтримуються перевизначення для кожного облікового запису, групи й теми (таке саме успадкування, як і для інших ключів конфігурації Telegram).
```json5
{
@ -835,14 +835,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
- BotFather: `/setprivacy` -> Disable
- потім видаліть і повторно додайте бота до групи
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
- `openclaw channels status --probe` може перевіряти явні числові ідентифікатори груп; wildcard `"*"` не можна перевірити на членство.
- швидкий тест сесії: `/activation always`.
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
- швидкий тест сеансу: `/activation always`.
</Accordion>
<Accordion title="Бот взагалі не бачить групові повідомлення">
<Accordion title="Бот узагалі не бачить групові повідомлення">
- коли існує `channels.telegram.groups`, група має бути перелічена (або містити `"*"`)
- коли існує `channels.telegram.groups`, група має бути в списку (або має міститися `"*"`)
- перевірте членство бота в групі
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
@ -850,34 +850,34 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
<Accordion title="Команди працюють частково або не працюють зовсім">
- авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`)
- авторизуйте ідентичність відправника (сполучення та/або числовий `allowFrom`)
- авторизація команд усе одно застосовується, навіть коли політика групи — `open`
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню
- стартові виклики `deleteMyCommands` / `setMyCommands` обмежені та повторюються один раз через транспортний fallback Telegram у разі тайм-ауту запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org`
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/custom або вимкніть нативні меню
- стартові виклики `deleteMyCommands` / `setMyCommands` обмежені й повторюються один раз через резервний транспорт Telegram у разі таймауту запиту. Постійні помилки мережі/fetch зазвичай вказують на проблеми доступності DNS/HTTPS до `api.telegram.org`
</Accordion>
<Accordion title="Запуск повідомляє про неавторизований токен">
<Accordion title="Під час запуску повідомляється про неавторизований токен">
- `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота.
- Повторно скопіюйте або згенеруйте токен бота в BotFather, а потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для типового облікового запису.
- `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "Webhook не існує" лише відклало б той самий збій через неправильний токен до пізніших викликів API.
- Якщо `deleteWebhook` завершується помилкою через тимчасову мережеву помилку під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL Webhook, polling продовжується, бо очищення вже задоволене.
- Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням.
- `deleteWebhook 401 Unauthorized` під час запуску також є збоєм автентифікації; трактування цього як "webhook не існує" лише відклало б той самий збій через поганий токен до пізніших викликів API.
- Якщо `deleteWebhook` завершується з тимчасовою мережевою помилкою під час запуску polling, OpenClaw перевіряє `getWebhookInfo`; коли Telegram повідомляє порожній URL webhook, polling продовжується, бо очищення вже задоволене.
</Accordion>
<Accordion title="Нестабільність polling або мережі">
- Node 22+ + користувацький fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
- Деякі хости спершу розв’язують `api.telegram.org` в IPv6; несправний IPv6 egress може спричиняти періодичні збої Telegram API.
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки.
- Якщо сокети Telegram повторно створюються з коротким фіксованим інтервалом, перевірте, чи не встановлено мале значення `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче за запобіжник запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll.
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням.
- `openclaw channels status --probe` і `openclaw doctor` попереджають, коли запущений акаунт polling не завершив `getUpdates` після початкового пільгового періоду, коли запущений акаунт webhook не завершив `setWebhook` після початкового пільгового періоду або коли остання успішна активність транспорту polling застаріла.
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зупинку polling. Постійні зупинки зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
- Node 22+ + кастомний fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
- Деякі хости спочатку розв’язують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API.
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці запити як відновлювані мережеві помилки.
- Якщо сокети Telegram перестворюються з коротким фіксованим інтервалом, перевірте, чи не занизьке значення `channels.telegram.timeoutSeconds`; клієнти ботів із long-polling обмежують налаштовані значення нижче захисного ліміту запиту `getUpdates`, але старіші випуски могли переривати кожне опитування, коли це значення було нижчим за тайм-аут long-poll.
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеного long-poll підтвердження життєздатності за замовчуванням.
- `openclaw channels status --probe` і `openclaw doctor` попереджають, коли активний обліковий запис з опитуванням не завершив `getUpdates` після початкового пільгового періоду, коли активний обліковий запис Webhook не завершив `setWebhook` після початкового пільгового періоду, або коли остання успішна активність транспорту опитування застаріла.
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або виходом TLS між хостом і `api.telegram.org`.
- Telegram також враховує змінні середовища proxy процесу для транспорту Bot API, зокрема `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` та їхні варіанти в нижньому регістрі. `NO_PROXY` / `no_proxy` усе ще можуть обходити `api.telegram.org`.
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища і стандартні змінні середовища proxy відсутні, Telegram також використовує цю URL-адресу для транспорту Bot API.
- На VPS-хостах із нестабільним прямим egress/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
- Якщо керований proxy OpenClaw налаштовано через `OPENCLAW_PROXY_URL` для сервісного середовища й немає стандартної змінної середовища proxy, Telegram також використовує цю URL-адресу для транспорту Bot API.
- На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
```yaml
channels:
@ -885,8 +885,8 @@ channels:
proxy: socks5://<user>:<password>@proxy-host:1080
```
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (окрім WSL2) і `dnsResultOrder=ipv4first`.
- Якщо ваш хост — WSL2 або явно краще працює в режимі лише IPv4, примусово задайте вибір сімейства:
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2). Порядок результатів DNS Telegram враховує `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, потім `channels.telegram.network.dnsResultOrder`, потім стандарт процесу, як-от `NODE_OPTIONS=--dns-result-order=ipv4first`; якщо нічого не застосовується, Node 22+ повертається до `ipv4first`.
- Якщо ваш хост є WSL2 або явно краще працює з поведінкою лише IPv4, примусово задайте вибір сімейства:
```yaml
channels:
@ -895,11 +895,11 @@ channels:
autoSelectFamily: false
```
- Відповіді з benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені
- Відповіді діапазону для бенчмарків RFC 2544 (`198.18.0.0/15`) уже дозволені
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
прозорий proxy переписує `api.telegram.org` на іншу
прозорий proxy переписує `api.telegram.org` на якусь іншу
приватну/внутрішню/спеціального використання адресу під час завантажень медіа, ви можете
увімкнути обхід лише для Telegram:
ввімкнути обхід лише для Telegram:
```yaml
channels:
@ -908,18 +908,18 @@ channels:
dangerouslyAllowPrivateNetwork: true
```
- Та сама opt-in опція доступна для кожного акаунта за адресою
- Така сама опція доступна для кожного облікового запису за адресою
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
- Якщо ваш proxy розв’язує хости медіа Telegram у `198.18.x.x`, спершу залиште
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяють benchmark-діапазон RFC 2544
за замовчуванням.
- Якщо ваш proxy розв’язує медіахости Telegram у `198.18.x.x`, спершу залиште
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє діапазон
бенчмарків RFC 2544 за замовчуванням.
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram
медіа від SSRF. Використовуйте це лише для довірених, контрольованих оператором середовищ proxy,
як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони
синтезують приватні або спеціального використання відповіді поза benchmark-діапазоном RFC 2544.
Залишайте вимкненим для звичайного публічного інтернет-доступу Telegram.
media від SSRF. Використовуйте це лише для довірених, керованих оператором proxy
середовищ, як-от маршрутизація fake-IP у Clash, Mihomo або Surge, коли вони
синтезують приватні відповіді або відповіді спеціального використання поза діапазоном
бенчмарків RFC 2544. Залишайте це вимкненим для звичайного публічного доступу Telegram через інтернет.
</Warning>
- Перевизначення середовища (тимчасові):
@ -942,40 +942,40 @@ dig +short api.telegram.org AAAA
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
<Accordion title="Найінформативніші поля Telegram">
<Accordion title="Високосигнальні поля Telegram">
- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symlinks відхиляються)
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневі `bindings[]` (`type: "acp"`)
- схвалення exec: `execApprovals`, `accounts.*.execApprovals`
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, top-level `bindings[]` (`type: "acp"`)
- підтвердження exec: `execApprovals`, `accounts.*.execApprovals`
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
- потоки/відповіді: `replyToMode`
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
- streaming: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot<TOKEN>`)
- кастомний корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot<TOKEN>`)
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- реакції: `reactionNotifications`, `reactionLevel`
- reactions: `reactionNotifications`, `reactionLevel`
- помилки: `errorPolicy`, `errorCooldownMs`
- записи/історія: `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.
Сполучіть користувача 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">
Модель загроз і посилення захисту.
@ -984,6 +984,6 @@ dig +short api.telegram.org AAAA
Зіставляйте групи й теми з агентами.
</Card>
<Card title="Усунення несправностей" icon="wrench" href="/uk/channels/troubleshooting">
Міжканальна діагностика.
Діагностика між каналами.
</Card>
</CardGroup>

390
docs/uk/ci.md
View File

@ -1,93 +1,93 @@
---
read_when:
- Вам потрібно з'ясувати, чому завдання CI запустилося або не запустилося.
- Ви налагоджуєте невдалу перевірку GitHub Actions
- Потрібно з’ясувати, чому завдання CI запустилося або не запустилося
- Ви налагоджуєте перевірку GitHub Actions, яка не проходить
- Ви координуєте запуск або повторний запуск валідації релізу
- Ви змінюєте диспетчеризацію ClawSweeper або пересилання активності GitHub
summary: Граф завдань CI, контрольні перевірки за областю, релізні набори та локальні еквіваленти команд
title: CI-конвеєр
summary: Граф завдань CI, контрольні перевірки за областю, парасолькові релізні процеси та локальні еквіваленти команд
title: Конвеєр CI
x-i18n:
generated_at: "2026-05-02T01:24:16Z"
generated_at: "2026-05-02T04:47:35Z"
model: gpt-5.5
provider: openai
source_hash: d7312e6367d24a5f61546fa84c3a281124d463821332ae11ac7bbbbab83cb8d4
source_hash: a2da3014e67b8d2d4bb4c1c9d4c6134eed29309bb176544864df568809ae3ac7
source_path: ci.md
workflow: 16
---
OpenClaw CI запускається під час кожного push до `main` і для кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі lanes, коли змінено лише непов’язані області. Ручні запуски `workflow_dispatch` навмисно обходять smart scoping і розгортають повний граф для release candidates і широкої валідації. Android lanes залишаються opt-in через `include_android`. Покриття Plugin лише для release міститься в окремому workflow [`Plugin Prerelease`](#plugin-prerelease) і запускається лише з [`Full Release Validation`](#full-release-validation) або явного ручного dispatch.
OpenClaw CI виконується під час кожного push до `main` і кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі lanes, коли змінено лише непов’язані області. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області та розгортають повний граф для реліз-кандидатів і широкої валідації. Android lanes залишаються опціональними через `include_android`. Покриття plugin лише для релізів живе в окремому workflow [`Plugin Prerelease`](#plugin-prerelease) і запускається тільки з [`Full Release Validation`](#full-release-validation) або явного ручного dispatch.
## Огляд pipeline
| Завдання | Призначення | Коли запускається |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Виявляє зміни лише в docs, змінені scopes, змінені extensions і будує CI manifest | Завжди для non-draft pushes і PRs |
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft pushes і PRs |
| `security-dependency-audit` | Production lockfile audit без залежностей щодо npm advisories | Завжди для non-draft pushes і PRs |
| `security-fast` | Обов’язковий aggregate для fast security jobs | Завжди для non-draft pushes і PRs |
| `check-dependencies` | Production Knip dependency-only pass плюс guard allowlist невикористаних файлів | Node-relevant changes |
| `build-artifacts` | Будує `dist/`, Control UI, built-artifact checks і reusable downstream artifacts | Node-relevant changes |
| `checks-fast-core` | Fast Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Node-relevant changes |
| `checks-fast-contracts-channels` | Sharded channel contract checks зі стабільним aggregate check result | Node-relevant changes |
| `checks-node-core-test` | Core Node test shards, крім channel, bundled, contract і extension lanes | Node-relevant changes |
| `check` | Sharded main local gate equivalent: prod types, lint, guards, test types і strict smoke | Node-relevant changes |
| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Node-relevant changes |
| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Node-relevant changes |
| `checks` | Verifier для built-artifact channel tests | Node-relevant changes |
| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Manual CI dispatch for releases |
| `check-docs` | Docs formatting, lint і broken-link checks | Docs changed |
| `skills-python` | Ruff + pytest для Python-backed skills | Python-skill-relevant changes |
| `checks-windows` | Windows-specific process/path tests плюс shared runtime import specifier regressions | Windows-relevant changes |
| `macos-node` | macOS TypeScript test lane з використанням shared built artifacts | macOS-relevant changes |
| `macos-swift` | Swift lint, build і tests для macOS app | macOS-relevant changes |
| `android` | Android unit tests для обох flavors плюс одна збірка debug APK | Android-relevant changes |
| `test-performance-agent` | Щоденна оптимізація Codex slow-test після trusted activity | Main CI success або manual dispatch |
| Завдання | Призначення | Коли запускається |
| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- |
| `preflight` | Виявляє зміни лише в документації, змінені області, змінені extensions і будує CI manifest | Завжди для non-draft push і PR |
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR |
| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди для non-draft push і PR |
| `security-fast` | Обов’язковий aggregate для швидких security-завдань | Завжди для non-draft push і PR |
| `check-dependencies` | Production Knip dependency-only pass і guard allowlist невикористаних файлів | Зміни, релевантні до Node |
| `build-artifacts` | Збирання `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні до Node |
| `checks-fast-core` | Швидкі Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні до Node |
| `checks-fast-contracts-channels` | Sharded channel contract checks зі стабільним aggregate check result | Зміни, релевантні до Node |
| `checks-node-core-test` | Core Node test shards, крім channel, bundled, contract і extension lanes | Зміни, релевантні до Node |
| `check` | Sharded еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні до Node |
| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Зміни, релевантні до Node |
| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Зміни, релевантні до Node |
| `checks` | Verifier для built-artifact channel tests | Зміни, релевантні до Node |
| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Ручний CI dispatch для релізів |
| `check-docs` | Форматування документації, lint і перевірки broken-link | Змінено документацію |
| `skills-python` | Ruff + pytest для Skills на Python | Зміни, релевантні до Python-skill |
| `checks-windows` | Windows-specific process/path tests і shared runtime import specifier regressions | Зміни, релевантні до Windows |
| `macos-node` | macOS TypeScript test lane з використанням shared built artifacts | Зміни, релевантні до macOS |
| `macos-swift` | Swift lint, build і tests для macOS app | Зміни, релевантні до macOS |
| `android` | Android unit tests для обох flavors і одне debug APK build | Зміни, релевантні до Android |
| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх main CI або manual dispatch |
## Порядок fail-fast
1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються з помилкою, не чекаючи на важчі artifact і platform matrix jobs.
3. `build-artifacts` перекривається з fast Linux lanes, щоб downstream consumers могли стартувати, щойно shared build буде готовий.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи важчих artifact і platform matrix jobs.
3. `build-artifacts` перекривається зі швидкими Linux lanes, щоб downstream consumers могли стартувати, щойно shared build готовий.
4. Важчі platform і runtime lanes розгортаються після цього: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
GitHub може позначати замінені jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні shard failures, але не стають у чергу після того, як увесь workflow уже був замінений. Автоматичний CI concurrency key версіонований (`CI-v7-*`), тож GitHub-side zombie у старій queue group не може безкінечно блокувати новіші main runs. Manual full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs.
GitHub може позначати витіснені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або `main` ref. Вважайте це CI-шумом, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні shard failures, але не стають у чергу після того, як увесь workflow уже витіснено. Automatic CI concurrency key версіонований (`CI-v7-*`), тому GitHub-side zombie у старій queue group не може безстроково блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs.
## Scope і routing
## Область і маршрутизація
Логіка scope міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає changed-scope detection і змушує preflight manifest поводитися так, ніби змінилась кожна scoped area.
Логіка області живе в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає changed-scope detection і змушує preflight manifest поводитися так, ніби змінилася кожна scoped area.
- **Зміни CI workflow** валідують Node CI graph плюс workflow linting, але самі по собі не примушують запускати Windows, Android або macOS native builds; ці platform lanes залишаються scoped до platform source changes.
- **CI routing-only edits, selected cheap core-test fixture edits і narrow plugin contract helper/test-routing edits** використовують fast Node-only manifest path: `preflight`, security і одне завдання `checks-fast-core`. Цей шлях пропускає build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task перевіряє безпосередньо.
- **Windows Node checks** scoped до Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю lane; непов’язані source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes.
- **Редагування CI workflow** валідують Node CI graph і workflow linting, але самі по собі не примушують Windows, Android або macOS native builds; ці platform lanes залишаються scoped до змін platform source.
- **CI routing-only edits, вибрані cheap core-test fixture edits і вузькі plugin contract helper/test-routing edits** використовують fast Node-only manifest path: `preflight`, security і одну задачу `checks-fast-core`. Цей path пропускає build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task вправляє напряму.
- **Windows Node checks** scoped до Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, що виконують цю lane; непов’язані source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes.
Найповільніші Node test families розділені або збалансовані, щоб кожне завдання залишалося невеликим без надмірного резервування runners: channel contracts запускаються як три weighted shards, small core unit lanes об’єднані в пари, auto-reply запускається як чотири balanced workers (із розбиттям reply subtree на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Broad browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries із використанням CI shard name, щоб `.artifacts/vitest-shard-timings.json` міг відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої small independent guards паралельно в одному job. Gateway watch, channel tests і core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані.
Найповільніші сімейства Node tests розділені або збалансовані, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, small core unit lanes об’єднані в пари, auto-reply запускається як чотири balanced workers (із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Broad browser, QA, media і miscellaneous plugin tests використовують власні dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries з використанням CI shard name, тому `.artifacts/vitest-shard-timings.json` може відрізнити whole config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі independent guards конкурентно всередині одного job. Gateway watch, channel tests і core support-boundary shard запускаються конкурентно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані.
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює flavor з BuildConfig flags для SMS/call-log, уникаючи дублювання debug APK packaging job на кожному Android-relevant push.
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює flavor із SMS/call-log BuildConfig flags, уникаючи дублюючого debug APK packaging job під час кожного Android-relevant push.
Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, pinned до найновішої версії Knip, із вимкненим pnpm minimum release age для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings Knip із `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий неперевірений unused file або залишає stale allowlist entry, водночас зберігаючи навмисні dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може розв’язати статично.
Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, закріплений на останній версії Knip, з вимкненим pnpm minimum release age для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings від Knip із `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий непереглянутий unused file або залишає застарілий allowlist entry, водночас зберігаючи навмисні dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично розв’язати.
## Пересилання активності ClawSweeper
`.github/workflows/clawsweeper-dispatch.yml` є target-side bridge з активності репозиторію OpenClaw до ClawSweeper. Він не виконує checkout і не запускає ненадійний pull request code. Workflow створює GitHub App token з `CLAWSWEEPER_APP_PRIVATE_KEY`, а потім надсилає compact `repository_dispatch` payloads до `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` є target-side bridge від активності репозиторію OpenClaw до ClawSweeper. Він не checkout і не виконує недовірений код pull request. Workflow створює GitHub App token з `CLAWSWEEPER_APP_PRIVATE_KEY`, а потім dispatch компактні `repository_dispatch` payloads до `openclaw/clawsweeper`.
Workflow має чотири lanes:
- `clawsweeper_item` для точних issue і pull request review requests;
- `clawsweeper_comment` для явних команд ClawSweeper у issue comments;
- `clawsweeper_commit_review` для commit-level review requests на `main` pushes;
- `github_activity` для загальної GitHub activity, яку ClawSweeper agent може перевіряти.
- `clawsweeper_item` для точних запитів review issue і pull request;
- `clawsweeper_comment` для явних команд ClawSweeper у коментарях issue;
- `clawsweeper_commit_review` для запитів commit-level review на push до `main`;
- `github_activity` для загальної активності GitHub, яку агент ClawSweeper може inspect.
Lane `github_activity` пересилає лише normalized metadata: event type, action, actor, repository, item number, URL, title, state і short excerpts для comments або reviews, коли вони присутні. Він навмисно не пересилає повне webhook body. Receiving workflow в `openclaw/clawsweeper` — `.github/workflows/github-activity.yml`, який публікує normalized event до OpenClaw Gateway hook для ClawSweeper agent.
Lane `github_activity` пересилає лише normalized metadata: event type, action, actor, repository, item number, URL, title, state і short excerpts для comments або reviews, коли вони є. Він навмисно уникає пересилання повного webhook body. Receiving workflow у `openclaw/clawsweeper` — `.github/workflows/github-activity.yml`, який публікує normalized event до OpenClaw Gateway hook для агента ClawSweeper.
General activity — це observation, а не delivery-by-default. ClawSweeper agent отримує Discord target у своєму prompt і має публікувати в `#clawsweeper` лише коли подія є несподіваною, actionable, risky або operationally useful. Routine opens, edits, bot churn, duplicate webhook noise і normal review traffic мають завершуватися `NO_REPLY`.
Загальна активність — це observation, а не delivery-by-default. Агент ClawSweeper отримує Discord target у своєму prompt і має публікувати в `#clawsweeper` тільки тоді, коли подія є несподіваною, actionable, risky або operationally useful. Routine opens, edits, bot churn, duplicate webhook noise і normal review traffic мають приводити до `NO_REPLY`.
Сприймайте GitHub titles, comments, bodies, review text, branch names і commit messages як ненадійні дані в усьому цьому path. Це input для summarization і triage, а не instructions для workflow або agent runtime.
Ставтеся до GitHub titles, comments, bodies, review text, branch names і commit messages як до недовірених даних у всьому цьому path. Це input для summarization і triage, а не instructions для workflow або agent runtime.
## Manual dispatches
Manual CI dispatches запускають той самий job graph, що й normal CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android лише з `include_android=true`; full release umbrella вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише коли `Full Release Validation` dispatches окремий workflow `Plugin Prerelease` із увімкненим release-validation gate.
Manual CI dispatches запускають той самий job graph, що й normal CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android тільки з `include_android=true`; full release umbrella вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише тоді, коли `Full Release Validation` dispatch окремий workflow `Plugin Prerelease` з увімкненим release-validation gate.
Manual runs використовують унікальну concurrency group, щоб release-candidate full suite не скасовувався іншим push або PR run на тому самому ref. Опціональний input `target_ref` дає trusted caller змогу запускати цей graph для branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref.
Manual runs використовують унікальну concurrency group, щоб release-candidate full suite не було скасовано іншим push або PR run на тому самому ref. Необов’язковий input `target_ref` дає довіреному caller змогу запустити цей graph проти branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -97,15 +97,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Ранери
| Ранер | Завдання |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколів/контрактів/вбудованого, шардовані перевірки контрактів каналів, шарди `check`, крім lint, шарди та агрегати `check-additional`, агрегатні верифікатори тестів Node, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує Ubuntu, розміщений у GitHub, щоб матриця Blacksmith могла ставати в чергу раніше |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші шарди extension, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів вбудованих Plugin, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, щоб 8 vCPU коштували більше, ніж заощаджували); Docker-збірки install-smoke (час у черзі для 32-vCPU коштував більше, ніж заощаджував) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
| Ранер | Завдання |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/вбудованих компонентів, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані перевіряльники тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; передперевірка install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла раніше ставати в чергу |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші шарди розширень, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів вбудованих Plugin, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, щоб 8 vCPU коштували більше, ніж заощаджували); Docker-збірки install-smoke (час очікування в черзі 32-vCPU коштував більше, ніж заощаджував) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
## Локальні відповідники
@ -133,39 +133,55 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
```
## Повна валідація релізу
## Повна перевірка релізу
`Full Release Validation` — це ручний парасольковий workflow для "запустити все перед релізом". Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для релізного підтвердження Plugin/package/static/Docker і запускає `OpenClaw Release Checks` для install smoke, package acceptance, release-path наборів Docker, live/E2E, OpenWebUI, паритету QA Lab, Matrix і каналів Telegram. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти артефакта `release-package-under-test` із release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити той самий пакетний канал Telegram проти опублікованого npm-пакета.
`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` з цією ціллю, запускає `Plugin Prerelease` для релізного підтвердження Plugin/пакета/статики/Docker і запускає `OpenClaw Release Checks` для install smoke, приймання пакета, наборів Docker release-path, live/E2E, OpenWebUI, паритету QA Lab, Matrix і Telegram lane. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти артефакту `release-package-under-test` із release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити ту саму Telegram package lane проти опублікованого npm-пакета.
Див. [Повну валідацію релізу](/uk/reference/full-release-validation) для
Див. [Повну перевірку релізу](/uk/reference/full-release-validation) для
матриці етапів, точних назв завдань workflow, відмінностей профілів, артефактів і
цільових ідентифікаторів повторного запуску.
дескрипторів цільових повторних запусків.
`release_profile` керує шириною live/provider, що передається в release checks. Ручні release workflows за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли ви навмисно хочете широку консультативну матрицю provider/media.
Для підтвердження закріпленого коміту на гілці, що швидко змінюється, використовуйте помічник замість
`gh workflow run ... --ref main -f ref=<sha>`:
- `minimum` зберігає найшвидші критичні для релізу канали OpenAI/core.
```bash
pnpm ci:full-release --sha <full-sha>
```
Refs для dispatch workflow GitHub мають бути гілками або тегами, а не сирими SHA комітів.
Помічник пушить тимчасову гілку `release-ci/<sha>-...` на цільовому SHA,
запускає `Full Release Validation` із цього закріпленого ref, перевіряє, що кожен дочірній
workflow `headSha` збігається з ціллю, і видаляє тимчасову гілку, коли
запуск завершується. Парасольковий перевіряльник також падає, якщо будь-який дочірній workflow працював на
іншому SHA.
`release_profile` керує шириною live/provider, що передається в release checks. Ручні
release workflows типово використовують `stable`; застосовуйте `full` лише коли ви
свідомо хочете широку advisory provider/media матрицю.
- `minimum` зберігає найшвидші критичні для релізу OpenAI/core lane.
- `stable` додає стабільний набір provider/backend.
- `full` запускає широку консультативну матрицю provider/media.
- `full` запускає широку advisory provider/media матрицю.
Парасолька записує ідентифікатори запущених дочірніх виконань, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх виконань і додає таблиці найповільніших завдань для кожного дочірнього виконання. Якщо дочірній workflow перезапущено і він став зеленим, повторно запустіть лише батьківське завдання verifier, щоб оновити результат парасольки та підсумок таймінгів.
Парасолька записує id запущених дочірніх run, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх run і додає таблиці найповільніших завдань для кожного дочірнього run. Якщо дочірній workflow перезапущено й він став зеленим, перезапустіть лише батьківське завдання verifier, щоб оновити результат парасольки та підсумок таймінгів.
Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для кандидата релізу, `ci` лише для звичайного повного дочірнього CI, `plugin-prerelease` лише для дочірнього prerelease Plugin, `release-checks` для кожного дочірнього release або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` у парасольці. Це утримує повторний запуск невдалого release box у межах після цільового виправлення.
Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для release candidate, `ci` лише для звичайного дочірнього full CI, `plugin-prerelease` лише для дочірнього plugin prerelease, `release-checks` для кожного release child або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` у парасольці. Це утримує повторний запуск збійного release box у межах після цільового виправлення.
`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і до live/E2E Docker workflow release-path, і до шарда package acceptance. Це зберігає байти пакета узгодженими між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях.
`OpenClaw Release Checks` використовує довірений workflow ref, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і в live/E2E release-path Docker workflow, і в package acceptance shard. Це зберігає байти пакета узгодженими між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях.
Дублікати запусків `Full Release Validation` для `ref=main` і `rerun_group=all`
замінюють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow, який
він уже запустив, коли батьківський запуск скасовано, тому новіша валідація main
не стоїть позаду застарілого двогодинного запуску release-check. Валідація release branch/tag
і цільові групи повторного запуску зберігають `cancel-in-progress: false`.
він уже запустив, коли батьківський скасовано, тож новіша main validation
не стоїть за застарілим двогодинним release-check run. Перевірки release branch/tag
і цільові rerun groups зберігають `cancel-in-progress: false`.
## Live та E2E шарди
Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного завдання:
Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs`, а не як одне послідовне завдання:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- provider-filtered завдання `native-live-src-gateway-profiles`
- provider-filtered `native-live-src-gateway-profiles` jobs
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -173,61 +189,61 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- розділені медіа-шарди audio/video і provider-filtered шарди music
- розділені медіашарди audio/video і provider-filtered шарди music
Це зберігає те саме файлове покриття, водночас спрощуючи повторний запуск і діагностику повільних збоїв live provider. Агрегатні назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків.
Це зберігає те саме покриття файлів, водночас спрощуючи повторний запуск і діагностику повільних збоїв live provider. Агреговані назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків.
Нативні live media шарди запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; медіа-завдання лише перевіряють бінарні файли перед налаштуванням. Тримайте Docker-backed live suites на звичайних раннерах Blacksmith — container jobs є неправильним місцем для запуску вкладених Docker-тестів.
Нативні live media shards працюють у `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; медіазавдання лише перевіряють бінарні файли перед налаштуванням. Тримайте Docker-backed live suites на звичайних Blacksmith runners — container jobs не підходять для запуску вкладених Docker tests.
Docker-backed шарди live model/backend використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:<sha>` для кожного вибраного коміту. Live release workflow збирає й пушить цей образ один раз, після чого Docker live model, provider-sharded gateway, CLI backend, ACP bind і шарди Codex harness запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway Docker шарди мають явні обмеження `timeout` на рівні скрипта нижче за timeout завдання workflow, щоб завислий контейнер або шлях очищення швидко падав, а не споживав увесь бюджет release-check. Якщо ці шарди незалежно перебудовують повну ціль source Docker, release run неправильно налаштований і марнуватиме wall clock на дубльовані збірки образів.
Docker-backed live model/backend shards використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:<sha>` для кожного вибраного коміту. Live release workflow збирає й пушить цей образ один раз, потім Docker live model, provider-sharded gateway, CLI backend, ACP bind і Codex harness shards запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway Docker shards мають явні script-level обмеження `timeout`, нижчі за timeout завдання workflow, щоб завислий контейнер або шлях очищення швидко падав, а не споживав увесь бюджет release-check. Якщо ці шарди незалежно перебудовують повну source Docker target, release run неправильно налаштований і марнуватиме wall clock на дубльовані збірки образів.
## Package Acceptance
## Приймання пакета
Використовуйте `Package Acceptance`, коли питання таке: "чи працює цей інстальований пакет OpenClaw як продукт?" Це відрізняється від звичайного CI: звичайний CI валідує дерево джерел, тоді як package acceptance валідує один tarball через той самий Docker E2E harness, який користувачі використовують після встановлення або оновлення.
Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальовний пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі запускають після встановлення або оновлення.
### Завдання
1. `resolve_package` виконує checkout `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і виводить джерело, ref workflow, ref пакета, версію, SHA-256 і профіль у підсумку кроку GitHub.
2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи package-digest і запускає вибрані Docker-доріжки для цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow один раз готує пакет і спільні образи, а потім розподіляє ці доріжки як паралельні цільові Docker-завдання з унікальними артефактами.
3. `package_telegram` необов’язково викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance визначив пакет; окремий dispatch Telegram усе ще може встановити опубліковану npm-специфікацію.
4. `summary` завершує workflow помилкою, якщо визначення пакета, Docker acceptance або необов’язкова доріжка Telegram завершилися невдало.
1. `resolve_package` робить checkout `workflow_ref`, визначає один кандидат пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і друкує джерело, workflow ref, package ref, версію, SHA-256 і профіль у підсумку кроку GitHub.
2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Багаторазовий workflow завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи package-digest і запускає вибрані Docker lanes для цього пакета замість пакування workflow checkout. Коли профіль вибирає кілька цільових `docker_lanes`, багаторазовий workflow готує пакет і спільні образи один раз, а потім розгортає ці lanes як паралельні цільові Docker-завдання з унікальними артефактами.
3. `package_telegram` опційно викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance визначив його; автономний Telegram dispatch усе ще може встановити опублікований npm spec.
4. `summary` позначає workflow як невдалий, якщо визначення пакета, Docker acceptance або опційний Telegram lane завершилися невдало.
### Джерела кандидатів
- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для acceptance опублікованих beta/stable.
- `source=ref` пакує довірену гілку `package_ref`, тег або повний SHA commit. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний commit досяжний з історії гілок репозиторію або релізного тегу, встановлює залежності у detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`.
- `source=url` завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим.
- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його варто надати для артефактів, поширених назовні.
- `source=ref` пакує довірену гілку `package_ref`, тег або повний commit SHA. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний commit досяжний з історії гілок репозиторію або release tag, встановлює залежності в detached worktree і пакує його через `scripts/package-openclaw-for-docker.mjs`.
- `source=url` завантажує HTTPS `.tgz`; `package_sha256` обов’язковий.
- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` опційний, але його слід надавати для зовнішньо поширених артефактів.
Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/тестового harness, який запускає тест. `package_ref` — це початковий commit, який пакується, коли `source=ref`. Це дає змогу поточному тестовому harness перевіряти старіші довірені початкові commit без запуску старої логіки workflow.
Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/harness, який запускає тест. `package_ref` — це вихідний commit, який пакується, коли `source=ref`. Це дає поточному тестовому harness змогу перевіряти старі довірені commits вихідного коду без запуску старої workflow-логіки.
### Профілі suite
### Профілі набору
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
- `product` — `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — повні фрагменти release-path Docker з OpenWebUI
- `full` — повні Docker chunks шляху релізу з OpenWebUI
- `custom` — точні `docker_lanes`; обов’язково, коли `suite_profile=custom`
Профіль `package` використовує offline-покриття Plugin, щоб перевірка опублікованого пакета не залежала від живої доступності ClawHub. Необов’язкова доріжка Telegram повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації зберігається для окремих dispatch.
Профіль `package` використовує offline-покриття plugin, щоб перевірка опублікованого пакета не залежала від live-доступності ClawHub. Опційний Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованого npm spec збережено для автономних dispatches.
Спеціальну політику тестування оновлень і Plugin, зокрема локальні команди,
Docker-доріжки, inputs Package Acceptance, типові значення релізу та triage збоїв,
див. у [Тестування оновлень і Plugin](/uk/help/testing-updates-plugins).
Для спеціальної політики тестування оновлень і plugin, зокрема локальних команд,
Docker lanes, входів Package Acceptance, release defaults і triage збоїв,
див. [Тестування оновлень і plugin](/uk/help/testing-updates-plugins).
Release checks викликають Package Acceptance з `source=artifact`, підготовленим артефактом релізного пакета, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Це зберігає перевірки міграції пакета, оновлення, очищення застарілих залежностей Plugin, offline Plugin, plugin-update і Telegram на одному визначеному tarball пакета. Cross-OS release checks і надалі покривають специфічні для ОС onboarding, інсталятор і поведінку платформи; product-валидацію пакета/оновлення слід починати з Package Acceptance. Docker-доріжка `published-upgrade-survivor` перевіряє один базовий опублікований пакет за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опублікований baseline, типово `openclaw@latest`; команди повторного запуску невдалих доріжок зберігають цей baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розгорнути доріжку в deduped матрицю історії: останні шість stable-релізів, `2026.4.23` і останній stable-реліз до `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розгорнути ті самі baselines у fixtures, сформовані за issues, для конфігурації Feishu, збережених bootstrap/persona файлів, шляхів логів із tilde і застарілих коренів залежностей Plugin. Окремий workflow `Update Migration` використовує Docker-доріжку `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання полягає у вичерпному очищенні опублікованих оновлень, а не у звичайній ширині Full Release CI. Локальні агреговані запуски можуть передавати точні специфікації пакетів через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, залишати одну доріжку з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або задавати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для матриці сценаріїв. Опублікована доріжка налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після запуску Gateway. Windows-доріжки packaged і installer fresh також перевіряють, що встановлений пакет може імпортувати browser-control override із сирого абсолютного Windows-шляху. Cross-OS smoke агентного turn OpenAI типово використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли задано, інакше `openai/gpt-5.5`, тож install і gateway proof залишаються на бажаній тестовій моделі GPT-5.
Release checks викликають Package Acceptance з `source=artifact`, підготовленим артефактом release package, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Це тримає перевірки міграції пакета, оновлення, очищення застарілих залежностей plugin, offline plugin, plugin-update і Telegram на одному визначеному package tarball. Cross-OS release checks усе ще покривають OS-специфічний onboarding, installer і поведінку платформи; product validation для package/update має починатися з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє один baseline опублікованого пакета за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опублікований baseline, за замовчуванням `openclaw@latest`; команди повторного запуску failed-lane зберігають цей baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розширити lane до дедуплікованої матриці історії: останні шість stable-релізів, `2026.4.23` і останній stable-реліз перед `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі baselines на issue-shaped fixtures для конфігурації Feishu, збережених файлів bootstrap/persona, шляхів журналів із тильдою та застарілих коренів legacy-залежностей plugin. Окремий workflow `Update Migration` використовує Docker lane `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання полягає у вичерпному очищенні опублікованого оновлення, а не у звичайній ширині Full Release CI. Локальні aggregate-запуски можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, зберігати один lane через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або встановлювати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для scenario matrix. Опублікований lane налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також RPC status після старту Gateway. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override із сирого абсолютного Windows path. OpenAI cross-OS agent-turn smoke за замовчуванням використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли його встановлено, інакше `openai/gpt-5.5`, щоб докази встановлення й gateway залишалися на бажаній тестовій моделі GPT-5.
### Вікна legacy-сумісності
Package Acceptance має обмежені вікна legacy-сумісності для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності:
Package Acceptance має обмежені вікна legacy-сумісності для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати compatibility path:
- відомі приватні QA-записи в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball;
- `doctor-switch` може пропустити підвипадок збереження `gateway install --wrapper`, коли пакет не надає цей прапорець;
- `update-channel-switch` може видаляти відсутні `pnpm.patchedDependencies` з підробленого git fixture, отриманого з tarball, і може логувати відсутній збережений `update.channel`;
- plugin smoke можуть читати legacy-розташування install-record або приймати відсутнє збереження marketplace install-record;
- `plugin-update` може дозволити міграцію метаданих конфігурації, водночас усе ще вимагаючи, щоб install record і поведінка без повторного встановлення залишалися незмінними.
- відомі private QA записи в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball;
- `doctor-switch` може пропускати subcase persistence `gateway install --wrapper`, коли пакет не експонує цей flag;
- `update-channel-switch` може обрізати відсутні `pnpm.patchedDependencies` із fake git fixture, похідного від tarball, і може логувати відсутній persisted `update.channel`;
- plugin smokes можуть читати legacy install-record locations або приймати відсутність marketplace install-record persistence;
- `plugin-update` може дозволяти міграцію config metadata, водночас вимагаючи, щоб install record і поведінка no-reinstall залишалися незмінними.
Опублікований пакет `2026.4.26` також може попереджати про файли штампа метаданих локальної збірки, які вже були випущені. Пізніші пакети мають задовольняти сучасні контракти; ті самі умови спричиняють помилку, а не попередження чи пропуск.
Опублікований пакет `2026.4.26` також може попереджати про файли local build metadata stamp, які вже були відвантажені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови завершуються помилкою замість попередження або пропуску.
### Приклади
@ -270,111 +286,111 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Під час debug невдалого запуску package acceptance починайте з підсумку `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, логи доріжок, timings фаз і команди повторного запуску. Віддавайте перевагу повторному запуску невдалого профілю пакета або точних Docker-доріжок замість повторного запуску повної release validation.
Під час debugging невдалого запуску package acceptance починайте з підсумку `resolve_package`, щоб підтвердити джерело пакета, версію і SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, lane logs, phase timings і rerun commands. Віддавайте перевагу повторному запуску невдалого package profile або точних Docker lanes замість повторного запуску повної release validation.
## Install smoke
Окремий workflow `Install Smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`.
Окремий workflow `Install Smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke coverage на `run_fast_install_smoke` і `run_full_install_smoke`.
- **Швидкий шлях** запускається для pull requests, що торкаються Docker/package surfaces, змін пакетів/маніфестів bundled Plugin або core plugin/channel/gateway/Plugin SDK surfaces, які перевіряють Docker smoke jobs. Зміни лише вихідного коду bundled Plugin, лише тестові правки та правки лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke видалення agents shared-workspace, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений bundled-plugin Docker profile під сукупним timeout команди 240 секунд (Docker run кожного сценарію обмежено окремо).
- **Повний шлях** зберігає QR package install і Docker/update покриття інсталятора для нічних scheduled runs, ручних dispatch, workflow-call release checks і pull requests, які справді торкаються installer/package/Docker surfaces. У full mode install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і швидкий bundled-plugin Docker E2E як окремі jobs, щоб installer work не чекав за root image smokes.
- **Fast path** запускається для pull requests, які торкаються Docker/package surfaces, змін package/manifest для bundled plugin або core plugin/channel/gateway/Plugin SDK surfaces, які перевіряють Docker smoke jobs. Source-only зміни bundled plugin, test-only edits і docs-only edits не резервують Docker workers. Fast path один раз збирає root Dockerfile image, перевіряє CLI, запускає agents delete shared-workspace CLI smoke, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений bundled-plugin Docker profile під 240-секундним aggregate command timeout (Docker run кожного scenario обмежений окремо).
- **Full path** зберігає QR package install і installer Docker/update coverage для нічних scheduled runs, manual dispatches, workflow-call release checks і pull requests, які справді торкаються installer/package/Docker surfaces. У full mode install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і fast bundled-plugin Docker E2E як окремі завдання, щоб installer work не чекав за root image smokes.
Push у `main` (зокрема merge commits) не примушують повний шлях; коли логіка changed-scope вимагала б повне покриття для push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної валідації.
Пуші в `main` (зокрема merge commits) не примушують full path; коли changed-scope logic вимагала б full coverage на push, workflow зберігає fast Docker smoke і залишає full install smoke для нічної або release validation.
Повільний Bun global install image-provider smoke окремо керується `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з workflow release checks, а ручні dispatch `Install Smoke` можуть увімкнути його, але pull requests і push у `main` — ні. QR і installer Docker tests зберігають власні Dockerfiles, зосереджені на install.
Повільний Bun global install image-provider smoke окремо обмежений через `run_bun_global_install_smoke`. Він запускається за нічним schedule і з release checks workflow, а manual `Install Smoke` dispatches можуть opt into it, але pull requests і пуші в `main` — ні. QR і installer Docker tests зберігають власні install-focused Dockerfiles.
## Локальний Docker E2E
`pnpm test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`:
`pnpm test:docker:all` попередньо збирає один спільний live-test image, пакує OpenClaw один раз як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`:
- bare Node/Git runner для доріжок installer/update/plugin-dependency;
- функціональний образ, який встановлює той самий tarball у `/app` для звичайних functionality lanes.
- bare Node/Git runner для installer/update/plugin-dependency lanes;
- functional image, який встановлює той самий tarball у `/app` для звичайних functionality lanes.
Визначення Docker-доріжок розташовані в `scripts/lib/docker-e2e-scenarios.mjs`, логіка planner — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний plan. Scheduler вибирає образ для кожної доріжки за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає доріжки з `OPENCLAW_SKIP_DOCKER_BUILD=1`.
Визначення Docker lane розміщені в `scripts/lib/docker-e2e-scenarios.mjs`, planner logic — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний plan. Scheduler вибирає image для кожного lane через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Налаштування
| Змінна | Типове значення | Призначення |
| ------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних lane. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів tail-пулу, чутливого до провайдерів. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження паралельних live lane, щоб провайдери не застосовували throttling. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження паралельних lane встановлення npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження паралельних multi-service lane. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами lane, щоб уникнути хвиль створення в daemon Docker; задайте `0`, щоб вимкнути затримку. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут на lane (120 хвилин); вибрані live/tail lane використовують жорсткіші обмеження. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не задано | `1` друкує план планувальника без запуску lane. |
| `OPENCLAW_DOCKER_ALL_LANES` | не задано | Розділений комами точний список lane; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу lane. |
| Змінна | Типово | Призначення |
| -------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних ліній. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів хвостового пулу, чутливого до провайдерів. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження одночасних live-ліній, щоб провайдери не застосовували throttling. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження одночасних ліній встановлення npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження одночасних багатосервісних ліній. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами ліній, щоб уникати сплесків створення в демонові Docker; задайте `0`, щоб вимкнути затримку. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут для кожної лінії (120 хвилин); вибрані live/хвостові лінії використовують жорсткіші обмеження. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` виводить план планувальника без запуску ліній. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Розділений комами точний список ліній; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. |
Lane, важча за свій ефективний ліміт, усе ще може стартувати з порожнього пулу, а потім працює сама, доки не звільнить ємність. Локальний агрегат виконує попередні перевірки Docker, видаляє застарілі OpenClaw E2E контейнери, виводить статус активних lane, зберігає тривалості lane для впорядкування від найдовших до найкоротших і типово припиняє планувати нові pooled lane після першого збою.
Лінія, важча за своє ефективне обмеження, усе ще може стартувати з порожнього пулу, а потім виконується самостійно, доки не звільнить місткість. Локальний агрегатор виконує попередні перевірки Docker, видаляє застарілі E2E-контейнери OpenClaw, виводить статус активних ліній, зберігає часові показники ліній для впорядкування від найдовших до найкоротших і за замовчуванням припиняє планувати нові pooled-лінії після першої помилки.
### Багаторазовий live/E2E workflow
Багаторазовий live/E2E workflow запитує `scripts/test-docker-all.mjs --plan-json`, які package, image kind, live image, lane і покриття облікових даних потрібні. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує package artifact поточного запуску, або завантажує package artifact з `package_artifact_run_id`; перевіряє inventory tarball; збирає й публікує package-digest-tagged bare/functional GHCR Docker E2E images через Docker layer cache Blacksmith, коли план потребує lane з установленим package; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest images замість повторної збірки. Завантаження Docker images повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий registry/cache stream швидко повторився, а не спожив більшу частину критичного шляху CI.
Багаторазовий live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, який пакет, тип образу, live-образ, лінія та покриття облікових даних потрібні. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає та публікує позначені digest пакета bare/functional образи GHCR Docker E2E через Docker layer cache Blacksmith, коли план потребує ліній із встановленим пакетом; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest образи замість повторного збирання. Завантаження Docker-образів повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий потік registry/cache швидко повторювався, а не споживав більшість критичного шляху CI.
### Фрагменти release-path
Покриття Release Docker запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому image kind і виконував кілька lane через той самий weighted scheduler:
Покриття Release Docker запускає менші розбиті на фрагменти jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен фрагмент завантажував лише потрібний йому тип образу та виконував кілька ліній через той самий зважений планувальник:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
Поточні release Docker chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` і від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегатними псевдонімами Plugin/runtime. Псевдонім lane `install-e2e` залишається агрегатним псевдонімом ручного повторного запуску для обох lane встановлювача провайдера.
Поточні фрагменти Release Docker: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, а також від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегатними aliases для plugin/runtime. Alias лінії `install-e2e` залишається агрегатним manual rerun alias для обох ліній інсталяторів провайдерів.
OpenWebUI входить до `plugins-runtime-services`, коли повне покриття release-path його запитує, і зберігає окремий chunk `openwebui` лише для dispatches, призначених тільки для OpenWebUI. Lane оновлення bundled-channel повторюють спробу один раз у разі тимчасових мережевих збоїв npm.
OpenWebUI включається до `plugins-runtime-services`, коли повне покриття release-path його запитує, і зберігає окремий фрагмент `openwebui` лише для OpenWebUI-only dispatches. Лінії оновлення bundled-channel повторюють спробу один раз у разі тимчасових мережевих помилок npm.
Кожен chunk завантажує `.artifacts/docker-tests/` з журналами lane, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями повільних lane і командами повторного запуску для кожної lane. Input workflow `docker_lanes` запускає вибрані lane проти підготовлених images замість chunk jobs, що обмежує налагодження невдалої lane одним цільовим Docker job і готує, завантажує або повторно використовує package artifact для цього запуску; якщо вибрана lane є live Docker lane, цільовий job збирає live-test image локально для цього повторного запуску. Згенеровані для кожної lane команди повторного запуску GitHub містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених images, коли ці значення існують, тож невдала lane може повторно використати точні package і images з невдалого запуску.
Кожен фрагмент завантажує `.artifacts/docker-tests/` із логами ліній, часовими показниками, `summary.json`, `failures.json`, часовими показниками фаз, JSON плану планувальника, таблицями повільних ліній і командами повторного запуску для кожної лінії. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених образів замість jobs фрагментів, що обмежує налагодження невдалої лінії одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана лінія є live Docker-лінією, цільовий job локально збирає live-test образ для цього повторного запуску. Згенеровані для кожної лінії команди GitHub rerun включають `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб невдала лінія могла повторно використати точний пакет і образи з невдалого запуску.
```bash
pnpm test:docker:rerun <run-id> # завантажити Docker artifacts і надрукувати об’єднані/по-lane цільові команди повторного запуску
pnpm test:docker:timings <summary> # підсумки повільних lane і критичного шляху фаз
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
Запланований live/E2E workflow щодня запускає повний release-path Docker suite.
Запланований live/E2E workflow щодня запускає повний набір Docker release-path.
## Plugin Prerelease
## Передреліз Plugin
`Plugin Prerelease` є дорожчим покриттям product/package, тому це окремий workflow, який запускається `Full Release Validation` або явно оператором. Звичайні pull requests, push до `main` і окремі ручні CI dispatches не вмикають цей suite. Він балансує тести bundled Plugin між вісьмома extension workers; ці extension shard jobs запускають до двох груп конфігурації Plugin одночасно з одним Vitest worker на групу та більшим heap Node, щоб batches Plugin з важкими imports не створювали додаткових CI jobs. Release-only Docker prerelease path групує цільові Docker lane невеликими групами, щоб не резервувати десятки runners для jobs тривалістю від однієї до трьох хвилин.
`Plugin Prerelease` є дорожчим покриттям product/package, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, push-и в `main` і самостійні manual CI dispatches тримають цей набір вимкненим. Він балансує тести bundled plugin між вісьмома extension workers; ці extension shard jobs запускають до двох груп конфігурації plugin одночасно з одним Vitest worker на групу та більшим Node heap, щоб import-heavy партії plugin не створювали додаткових CI jobs. Release-only Docker prerelease path групує цільові Docker-лінії в невеликі групи, щоб не резервувати десятки runners для jobs тривалістю від однієї до трьох хвилин.
## QA Lab
QA Lab має окремі CI lane поза основним smart-scoped workflow.
QA Lab має окремі CI-лінії поза основним smart-scoped workflow.
- Workflow `Parity gate` запускається для відповідних змін PR і manual dispatch; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs.
- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і за manual dispatch; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні jobs. Live jobs використовують environment `qa-live-shared`, а Telegram/Discord використовують Convex leases.
- Workflow `Parity gate` запускається для відповідних змін PR і manual dispatch; він збирає приватний QA runtime і порівнює agentic packs mock GPT-5.5 та Opus 4.6.
- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch; він розгалужує mock parity gate, live Matrix-лінію, а також live Telegram і Discord лінії як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases.
Release checks запускають Matrix і Telegram live transport lanes з deterministic mock provider і mock-qualified models (`mock-openai/gpt-5.5` та `mock-openai/gpt-5.5-alt`), щоб контракт channel був ізольований від затримки live model і звичайного startup provider Plugin. Live transport Gateway вимикає memory search, оскільки QA parity окремо покриває поведінку memory; connectivity провайдера покривають окремі suites live model, native provider і Docker provider.
Release checks запускають live transport-лінії Matrix і Telegram з детермінованим mock provider і mock-qualified models (`mock-openai/gpt-5.5` та `mock-openai/gpt-5.5-alt`), щоб contract каналу був ізольований від затримки live model і звичайного запуску provider-plugin. Live transport gateway вимикає пошук пам’яті, бо QA parity окремо покриває поведінку пам’яті; підключення провайдерів покривається окремими наборами live model, native provider і Docker provider.
Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише коли checked-out CLI це підтримує. Типове значення CLI і input manual workflow залишаються `all`; manual dispatch `matrix_profile=all` завжди розбиває повне покриття Matrix на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`.
Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли checked-out CLI це підтримує. Типове значення CLI та input manual workflow залишаються `all`; manual dispatch `matrix_profile=all` завжди розбиває повне покриття Matrix на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`.
`OpenClaw Release Checks` також запускає критичні для релізу lane QA Lab перед затвердженням релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва artifacts у невеликий report job для фінального parity comparison.
`OpenClaw Release Checks` також запускає release-critical лінії QA Lab перед схваленням release; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва артефакти в невеликий report job для фінального порівняння parity.
Не ставте шлях landing PR за `Parity gate`, якщо зміна фактично не зачіпає QA runtime, model-pack parity або поверхню, якою володіє parity workflow. Для звичайних виправлень channel, config, docs або unit-test розглядайте це як необов’язковий сигнал і спирайтеся на scoped CI/check evidence.
Не ставте шлях landing PR за `Parity gate`, якщо зміна фактично не зачіпає QA runtime, model-pack parity або поверхню, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit-тестів вважайте це optional signal і дотримуйтеся scoped CI/check evidence.
## CodeQL
Workflow `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним sweep repository. Щоденні, manual і non-draft pull request guard runs сканують код Actions workflow плюс найризикованіші поверхні JavaScript/TypeScript за допомогою high-confidence security queries, відфільтрованих до high/critical `security-severity`.
Workflow `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним sweep репозиторію. Daily, manual і non-draft pull request guard runs сканують Actions workflow code плюс JavaScript/TypeScript поверхні з найвищим ризиком за допомогою high-confidence security queries, відфільтрованих до high/critical `security-severity`.
Pull request guard залишається легким: він запускається лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і виконує ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL не входять до типових PR defaults.
Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL не входять до PR defaults.
### Категорії безпеки
| Категорія | Поверхня |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, Cron і baseline Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації core channel плюс runtime channel Plugin, Gateway, Plugin SDK, secrets, audit touchpoints |
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і поверхні SSRF policy Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers, process execution helpers, outbound delivery і gates виконання tools агентом |
| `/codeql-security-high/plugin-trust-boundary` | Plugin install, loader, manifest, registry, package-manager install, source-loading і trust surfaces package contract Plugin SDK |
| Категорія | Поверхня |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і gateway baseline |
| `/codeql-security-high/channel-runtime-boundary` | Core channel implementation contracts плюс channel plugin runtime, gateway, Plugin SDK, secrets, audit touchpoints |
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і поверхні SSRF policy Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers, process execution helpers, outbound delivery і agent tool-execution gates |
| `/codeql-security-high/plugin-trust-boundary` | Plugin install, loader, manifest, registry, package-manager install, source-loading і trust surfaces package contract Plugin SDK |
### Платформоспецифічні security shards
### Platform-specific security shards
- `CodeQL Android Critical Security` — scheduled Android security shard. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує під `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — weekly/manual macOS security shard. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує результати dependency build із завантаженого SARIF і завантажує під `/codeql-critical-security/macos`. Залишається поза daily defaults, бо macOS build домінує runtime навіть коли чистий.
- `CodeQL macOS Critical Security` — weekly/manual macOS security shard. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує результати dependency build із завантаженого SARIF і завантажує під `/codeql-critical-security/macos`. Тримається поза daily defaults, бо macOS build домінує за часом виконання навіть у чистому стані.
### Категорії Critical Quality
`CodeQL Critical Quality` є відповідним non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries по вузьких high-value surfaces на меншому Blacksmith Linux runner. Його pull request guard навмисно менший за scheduled profile: non-draft PRs запускають лише відповідні shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для змін у коді agent command/model/tool execution і reply dispatch, config schema/migration/IO code, auth/secrets/sandbox/security code, core channel і bundled channel Plugin runtime, Gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, Plugin loader, Plugin SDK/package-contract або Plugin SDK reply runtime. Зміни CodeQL config і quality workflow запускають усі дванадцять PR quality shards.
`CodeQL Critical Quality` є відповідним non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries над вузькими high-value surfaces на меншому Blacksmith Linux runner. Його pull request guard навмисно менший за scheduled profile: non-draft PRs запускають лише відповідні shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для agent command/model/tool execution і reply dispatch code, config schema/migration/IO code, auth/secrets/sandbox/security code, core channel і bundled channel plugin runtime, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, plugin loader, Plugin SDK/package-contract або змін Plugin SDK reply runtime. Зміни CodeQL config і quality workflow запускають усі дванадцять PR quality shards.
Manual dispatch приймає:
@ -382,40 +398,40 @@ Manual dispatch приймає:
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Вузькі profiles є hooks для навчання/ітерації, щоб запускати один quality shard ізольовано.
Вузькі profiles є teaching/iteration hooks для запуску одного quality shard в ізоляції.
| Категорія | Поверхня |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки автентифікації, секретів, пісочниці, Cron і Gateway |
| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти серверних методів |
| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та вбудованого Plugin каналів |
| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація та черги автовідповідей, а також runtime-контракти керівного рівня ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP і мости інструментів, допоміжні засоби нагляду за процесами та контракти вихідної доставки |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам’яті, фасади runtime пам’яті, псевдоніми SDK пам’яті Plugin, зв’язувальний код активації runtime пам’яті та команди doctor пам’яті |
| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня реалізація черги відповідей, черги доставки сеансів, допоміжні засоби прив’язування/доставки вихідних сеансів, поверхні діагностичних подій/пакетів журналів і контракти CLI doctor сеансів |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Вхідна диспетчеризація відповідей Plugin SDK, допоміжні засоби payload/розбиття на фрагменти/runtime для відповідей, параметри відповідей каналів, черги доставки та допоміжні засоби прив’язування сеансів/потоків |
| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація та виявлення провайдерів, реєстрація runtime провайдерів, стандартні параметри/каталоги провайдерів і реєстри web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap керівного UI, локальне збереження, керівні потоки Gateway і runtime-контракти керівного рівня завдань |
| `/codeql-critical-quality/web-media-runtime-boundary` | Runtime-контракти основного web fetch/search, media IO, розуміння медіа, генерації зображень і генерації медіа |
| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та точок входу Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Опубліковане вихідне дерево Plugin SDK на боці пакета та допоміжні засоби контрактів пакетів plugin |
| Категорія | Поверхня |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Auth, secrets, sandbox, Cron і код межі безпеки Gateway |
| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти методів сервера |
| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та bundled channel plugin |
| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація й черги автоматичних відповідей, а також runtime-контракти control plane ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP і мости інструментів, допоміжні засоби нагляду за процесами та контракти вихідної доставки |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам’яті, runtime-фасади пам’яті, псевдоніми Plugin SDK для пам’яті, зв’язувальний код активації runtime пам’яті та команди doctor для пам’яті |
| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сеансів, допоміжні засоби прив’язування/доставки вихідних сеансів, поверхні діагностичних подій/пакетів журналів і контракти CLI doctor для сеансів |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Диспетчеризація вхідних відповідей Plugin SDK, допоміжні засоби payload/chunking/runtime для відповідей, параметри відповідей каналів, черги доставки та допоміжні засоби прив’язування сеансів/тредів |
| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація й виявлення провайдерів, реєстрація runtime провайдерів, стандартні налаштування/каталоги провайдерів і реєстри web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Завантаження Control UI, локальне збереження, потоки керування Gateway і runtime-контракти control plane завдань |
| `/codeql-critical-quality/web-media-runtime-boundary` | Контракти runtime для основних web fetch/search, media IO, розуміння медіа, генерації зображень і генерації медіа |
| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та entrypoint Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований пакетний код Plugin SDK і допоміжні засоби контрактів пакетів plugin |
Якість залишається окремою від безпеки, щоб висновки щодо якості можна було планувати, вимірювати, вимикати або розширювати без розмивання сигналу безпеки. Розширення CodeQL для Swift, Python і вбудованих plugin слід додавати назад як обмежену або шардовану подальшу роботу лише після того, як вузькі профілі матимуть стабільний runtime і сигнал.
Якість залишається окремою від безпеки, щоб знахідки якості можна було планувати, вимірювати, вимикати або розширювати без розмивання сигналу безпеки. Розширення CodeQL для Swift, Python і bundled-plugin слід повертати як scoped або sharded подальшу роботу лише після того, як вузькі профілі матимуть стабільний runtime і сигнал.
## Робочі процеси супроводу
### Docs Agent
Робочий процес `Docs Agent` — це подієво-керована смуга супроводу Codex для підтримання наявної документації в узгодженості з нещодавно заландженими змінами. Він не має чистого розкладу: успішний CI-запуск після push не-бота в `main` може його запустити, а ручний dispatch може запустити його напряму. Виклики через workflow-run пропускаються, коли `main` уже пішов далі або коли інший непропущений запуск Docs Agent було створено протягом останньої години. Коли він запускається, він переглядає діапазон комітів від попереднього непропущеного source SHA Docs Agent до поточного `main`, тож один погодинний запуск може покрити всі зміни main, накопичені з часу останнього проходу документації.
Робочий процес `Docs Agent` — це подієво-керована лінія супроводу Codex для підтримання наявної документації узгодженою з нещодавно внесеними змінами. Він не має чистого розкладу: успішний CI-запуск push не від бота на `main` може його запустити, а ручний запуск може виконати його напряму. Виклики через workflow-run пропускаються, коли `main` уже просунувся далі або коли інший непропущений запуск Docs Agent було створено протягом останньої години. Коли він виконується, він переглядає діапазон комітів від попереднього непропущеного source SHA Docs Agent до поточного `main`, тому один щогодинний запуск може охопити всі зміни main, накопичені з часу останнього проходу документації.
### Test Performance Agent
Робочий процес `Test Performance Agent` — це подієво-керована смуга супроводу Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск після push не-бота в `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже виконувався або виконується цього UTC-дня. Ручний dispatch обходить цей добовий бар’єр активності. Смуга будує згрупований звіт продуктивності Vitest для повного набору, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт повного набору й відхиляє зміни, що зменшують базову кількість прохідних тестів. Якщо базова лінія має failing tests, Codex може виправляти лише очевидні failures, а звіт повного набору після агента має пройти перед будь-яким комітом. Коли `main` просувається до того, як bot push потрапляє в репозиторій, смуга rebase-ить перевірений patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати таку саму безпечну позицію drop-sudo, як docs agent.
Робочий процес `Test Performance Agent` — це подієво-керована лінія супроводу Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск push не від бота на `main` може його запустити, але він пропускається, якщо інший workflow-run виклик уже виконувався або виконується цього UTC-дня. Ручний запуск обходить цей денний gate активності. Лінія будує згрупований звіт продуктивності Vitest для повного набору тестів, дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт повного набору й відхиляє зміни, що зменшують базову кількість успішних тестів. Якщо в baseline є тести з помилками, Codex може виправляти лише очевидні збої, а післяагентський звіт повного набору має пройти перед будь-яким комітом. Коли `main` просувається вперед до того, як bot push буде внесено, лінія перебазовує перевірений patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну позицію drop-sudo, що й docs agent.
### Дублікати PR після merge
Робочий процес `Duplicate PRs After Merge` — це ручний maintainer workflow для очищення дублікатів після land. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що landed PR змержено і що кожен дублікат має або спільне referenced issue, або перетин змінених hunks.
Робочий процес `Duplicate PRs After Merge` — це ручний робочий процес супровідників для очищення дублікатів після land. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що landed PR змарджено і що кожен duplicate має або спільну referenced issue, або hunks змін, що перетинаються.
```bash
gh workflow run duplicate-after-merge.yml \
@ -428,25 +444,25 @@ gh workflow run duplicate-after-merge.yml \
Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широкий scope CI-платформи:
- зміни core production запускають typecheck core prod і core test, а також core lint/guards;
- зміни лише core test запускають тільки typecheck core test і core lint;
- зміни extension production запускають typecheck extension prod і extension test, а також extension lint;
- зміни лише extension test запускають typecheck extension test і extension lint;
- зміни core production запускають core prod і core test typecheck плюс core lint/guards;
- зміни лише core test запускають лише core test typecheck плюс core lint;
- зміни extension production запускають extension prod і extension test typecheck плюс extension lint;
- зміни лише extension test запускають extension test typecheck плюс extension lint;
- зміни публічного Plugin SDK або plugin-contract розширюються до extension typecheck, бо extensions залежать від цих core contracts (Vitest extension sweeps залишаються явною тестовою роботою);
- version bumps лише release metadata запускають цільові version/config/root-dependency checks;
- невідомі зміни root/config безпечно падають до всіх check lanes.
- version bumps лише release metadata запускають цільові перевірки version/config/root-dependency;
- невідомі зміни root/config безпечно переходять у всі check lanes.
Локальний changed-test routing міститься в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі зміни тестів запускають самі себе, зміни source віддають перевагу явним мапінгам, потім sibling tests і import-graph dependents. Конфігурація shared group-room delivery є одним з явних мапінгів: зміни до group visible-reply config, source reply delivery mode або системного prompt message-tool маршрутизуються через core reply tests плюс регресії доставки Discord і Slack, щоб зміна shared default впала ще до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна настільки harness-wide, що дешевий mapped set не є надійним proxy.
Локальний changed-test routing міститься в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі зміни тестів запускають самі себе, зміни source віддають перевагу явним mappings, потім sibling tests і import-graph dependents. Shared group-room delivery config — один із явних mappings: зміни до group visible-reply config, source reply delivery mode або system prompt message-tool проходять через core reply tests плюс регресії доставки Discord і Slack, щоб зміна shared default падала ще до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна достатньо harness-wide, що дешевий mapped set не є надійним proxy.
## Валідація Testbox
Запускайте Testbox із кореня репозиторію і для широкого proof віддавайте перевагу свіжій warmed box. Перед витрачанням повільного gate на box, яку було повторно використано, термін якої сплив або яка щойно повідомила про неочікувано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box.
Запускайте Testbox із кореня репозиторію та віддавайте перевагу свіжому warmed box для широкого proof. Перед тим як витрачати повільний gate на box, який повторно використовували, у якого сплив строк дії або який щойно повідомив про неочікувано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box.
Sanity check швидко падає, коли зникли обов’язкові root files на кшталт `pnpm-lock.yaml` або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що стан remote sync не є надійною копією PR; зупиніть цю box і прогрійте свіжу замість налагодження product test failure. Для навмисних PR із великими видаленнями встановіть `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run.
Sanity check швидко падає, коли потрібні root files, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цей box і прогрійте новий замість debug product test failure. Для навмисних PR із великими deletions задайте `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run.
`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі sync понад п’ять хвилин без post-sync output. Установіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих локальних diffs.
`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі sync понад п’ять хвилин без post-sync output. Задайте `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих локальних diffs.
Crabbox — це другий, repo-owned шлях remote-box для Linux proof, коли Blacksmith недоступний або коли бажаніша owned cloud capacity. Прогрійте box, hydrate її через project workflow, потім запускайте команди через Crabbox CLI:
Crabbox — це repo-owned другий шлях remote-box для Linux proof, коли Blacksmith недоступний або коли власна cloud capacity є кращою. Прогрійте box, hydrate його через project workflow, потім запускайте команди через Crabbox CLI:
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
@ -455,7 +471,7 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm crabbox:stop -- <cbx_id>
```
`.crabbox.yaml` визначає provider, sync і стандартні параметри GitHub Actions hydration. Вона виключає локальний `.git`, щоб hydrated Actions checkout зберігав власні remote Git metadata замість sync maintainer-local remotes і object stores, а також виключає локальні runtime/build artifacts, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` визначає checkout, налаштування Node/pnpm, fetch `origin/main` і non-secret environment handoff, який пізніші команди `crabbox run --id <cbx_id>` підвантажують як source.
`.crabbox.yaml` володіє defaults для provider, sync і GitHub Actions hydration. Він виключає локальний `.git`, щоб hydrated Actions checkout зберігав власні remote Git metadata замість синхронізації maintainer-local remotes і object stores, а також виключає локальні runtime/build artifacts, які ніколи не мають передаватися. `.github/workflows/crabbox-hydrate.yml` володіє checkout, налаштуванням Node/pnpm, fetch `origin/main` і передачею non-secret environment, яку пізніші команди `crabbox run --id <cbx_id>` source.
## Пов’язане

114
docs/uk/cli/cron.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Вам потрібні заплановані завдання та пробудження
- Ви налагоджуєте виконання Cron і журнали
- Ви налагоджуєте виконання Cron і аналізуєте журнали
summary: Довідник CLI для `openclaw cron` (планування та запуск фонових завдань)
title: Cron
x-i18n:
generated_at: "2026-04-30T08:43:38Z"
generated_at: "2026-05-02T04:47:21Z"
model: gpt-5.5
provider: openai
source_hash: 03d79e0e2c71f673c900b84eb2beeab705662c1d016e1d0567323c8da73060bb
source_hash: 298ac3fc868462eb301febbc1aa5296d8087cad7fdc466870487081444c5856f
source_path: cli/cron.md
workflow: 16
---
@ -18,7 +18,7 @@ x-i18n:
Керуйте завданнями Cron для планувальника Gateway.
<Tip>
Запустіть `openclaw cron --help`, щоб переглянути всю поверхню команд. Див. [завдання Cron](/uk/automation/cron-jobs) для концептуального посібника.
Запустіть `openclaw cron --help`, щоб переглянути повну поверхню команд. Див. [завдання Cron](/uk/automation/cron-jobs) для концептуального посібника.
</Tip>
## Сесії
@ -34,73 +34,73 @@ x-i18n:
</Accordion>
<Accordion title="Семантика ізольованої сесії">
Ізольовані запуски скидають навколишній контекст розмови. Маршрутизація каналів і груп, політика надсилання/черги, підвищення, походження та прив’язка ACP runtime скидаються для нового запуску. Безпечні налаштування й явні вибрані користувачем перевизначення моделі або автентифікації можуть переноситися між запусками.
Ізольовані запуски скидають навколишній контекст розмови. Маршрутизація каналів і груп, політика надсилання/черги, підвищення прав, походження та прив’язка середовища виконання ACP скидаються для нового запуску. Безпечні налаштування та явно вибрана користувачем модель або перевизначення автентифікації можуть переноситися між запусками.
</Accordion>
</AccordionGroup>
## Доставка
`openclaw cron list` і `openclaw cron show <job-id>` попередньо показують обчислений маршрут доставки. Для `channel: "last"` попередній перегляд показує, чи маршрут обчислено з основної або поточної сесії, або чи він завершиться закритою помилкою.
`openclaw cron list` і `openclaw cron show <job-id>` показують попередній перегляд розв’язаного маршруту доставки. Для `channel: "last"` попередній перегляд показує, чи маршрут розв’язано з основної або поточної сесії, або чи він завершиться закритою відмовою.
Цілі з префіксом провайдера можуть усунути неоднозначність нерозв’язаних каналів оголошень. Наприклад, `to: "telegram:123"` вибирає Telegram, коли `delivery.channel` пропущено або має значення `last`. Лише префікси, оголошені завантаженим Plugin, є селекторами провайдера. Якщо `delivery.channel` задано явно, префікс має відповідати цьому каналу; `channel: "whatsapp"` з `to: "telegram:123"` відхиляється. Сервісні префікси, як-от `imessage:` і `sms:`, залишаються синтаксисом цілі, що належить каналу.
<Note>
Ізольовані завдання `cron add` за замовчуванням використовують доставку `--announce`. Використовуйте `--no-deliver`, щоб залишити вивід внутрішнім. `--deliver` залишається застарілим псевдонімом для `--announce`.
Ізольовані завдання `cron add` за замовчуванням використовують доставку `--announce`. Використовуйте `--no-deliver`, щоб залишити вивід внутрішнім. `--deliver` лишається застарілим псевдонімом для `--announce`.
</Note>
### Власність доставки
Доставка ізольованого чату Cron спільно належить агенту та runner:
Доставка чату ізольованого Cron спільно керується агентом і виконувачем:
- Агент може надсилати напряму за допомогою інструмента `message`, коли доступний маршрут чату.
- `announce` резервно доставляє фінальну відповідь лише тоді, коли агент не надіслав її напряму до обчисленої цілі.
- `announce` виконує резервну доставку фінальної відповіді лише тоді, коли агент не надіслав напряму до розв’язаної цілі.
- `webhook` надсилає завершене корисне навантаження на URL.
- `none` вимикає резервну доставку runner.
- `none` вимикає резервну доставку виконувачем.
`--announce` — це резервна доставка runner для фінальної відповіді. `--no-deliver` вимикає цю резервну доставку, але не прибирає інструмент `message` агента, коли доступний маршрут чату.
`--announce` — це резервна доставка виконувачем для фінальної відповіді. `--no-deliver` вимикає цей резервний шлях, але не прибирає інструмент `message` агента, коли доступний маршрут чату.
Нагадування, створені з активного чату, зберігають живу ціль доставки чату для резервної доставки announce. Внутрішні ключі сесій можуть бути в нижньому регістрі; не використовуйте їх як джерело істини для чутливих до регістру ідентифікаторів провайдерів, таких як ідентифікатори кімнат Matrix.
Нагадування, створені з активного чату, зберігають поточну ціль доставки чату для резервної доставки оголошення. Внутрішні ключі сесій можуть бути в нижньому регістрі; не використовуйте їх як джерело істини для чутливих до регістру ідентифікаторів провайдерів, таких як ідентифікатори кімнат Matrix.
### Доставка помилок
### Доставка збоїв
Сповіщення про помилки обчислюються в такому порядку:
Сповіщення про збій розв’язуються в такому порядку:
1. `delivery.failureDestination` у завданні.
2. Глобальний `cron.failureDestination`.
3. Основна ціль announce завдання (коли явну ціль для помилок не задано).
3. Основна ціль оголошення завдання (коли явну ціль для збоїв не задано).
<Note>
Завдання основної сесії можуть використовувати `delivery.failureDestination` лише тоді, коли основний режим доставки — `webhook`. Ізольовані завдання приймають його в усіх режимах.
</Note>
Примітка: ізольовані запуски Cron трактують помилки агента на рівні запуску як помилки завдання навіть тоді, коли
корисне навантаження відповіді не створено, тож помилки моделі/провайдера все одно збільшують лічильники
помилок і запускають сповіщення про помилки.
Примітка: ізольовані запуски Cron трактують помилки агента на рівні запуску як помилки завдання навіть тоді, коли корисне навантаження відповіді не створено, тож збої моделі/провайдера все одно збільшують лічильники помилок і запускають сповіщення про збій.
## Планування
### Одноразові завдання
`--at <datetime>` планує одноразовий запуск. Datetime без зміщення трактуються як UTC, якщо ви також не передали `--tz <iana>`, який інтерпретує локальний час у заданому часовому поясі.
`--at <datetime>` планує одноразовий запуск. Дати й час без зміщення трактуються як UTC, якщо ви також не передаєте `--tz <iana>`, що інтерпретує локальний час у заданому часовому поясі.
<Note>
Одноразові завдання за замовчуванням видаляються після успішного виконання. Використовуйте `--keep-after-run`, щоб зберегти їх.
Одноразові завдання за замовчуванням видаляються після успіху. Використовуйте `--keep-after-run`, щоб зберегти їх.
</Note>
### Повторювані завдання
Повторювані завдання використовують експоненційну затримку повтору після послідовних помилок: 30s, 1m, 5m, 15m, 60m. Розклад повертається до нормального після наступного успішного запуску.
Повторювані завдання використовують експоненційний відступ повторних спроб після послідовних помилок: 30с, 1хв, 5хв, 15хв, 60хв. Розклад повертається до норми після наступного успішного запуску.
Пропущені запуски відстежуються окремо від помилок виконання. Вони не впливають на затримку повтору, але `openclaw cron edit <job-id> --failure-alert-include-skipped` може ввімкнути для сповіщень про помилки повторювані сповіщення про пропущені запуски.
Пропущені запуски відстежуються окремо від помилок виконання. Вони не впливають на відступ повторних спроб, але `openclaw cron edit <job-id> --failure-alert-include-skipped` може включити повторні сповіщення про пропущені запуски до сповіщень про збій.
Для ізольованих завдань, які націлені на локально налаштованого провайдера моделі, Cron виконує легку попередню перевірку провайдера перед початком ходу агента. Провайдери local loopback, приватної мережі та `.local` `api: "ollama"` перевіряються на `/api/tags`; локальні OpenAI-сумісні провайдери, такі як vLLM, SGLang і LM Studio, перевіряються на `/models`. Якщо endpoint недоступний, запуск записується як `skipped` і повторюється за пізнішим розкладом; відповідні недоступні endpoint кешуються на 5 хвилин, щоб уникнути масового навантаження багатьох завдань на той самий локальний сервер.
Для ізольованих завдань, які націлені на локально налаштованого провайдера моделей, Cron виконує легку попередню перевірку провайдера перед початком ходу агента. Провайдери local loopback, приватної мережі та `.local` з `api: "ollama"` перевіряються на `/api/tags`; локальні OpenAI-сумісні провайдери, як-от vLLM, SGLang і LM Studio, перевіряються на `/models`. Якщо кінцева точка недоступна, запуск записується як `skipped` і повторюється за пізнішим розкладом; відповідні недоступні кінцеві точки кешуються на 5 хвилин, щоб багато завдань не перевантажували той самий локальний сервер.
Примітка: визначення завдань Cron зберігаються в `jobs.json`, тоді як очікуваний runtime-стан зберігається в `jobs-state.json`. Якщо `jobs.json` редагується зовні, Gateway перезавантажує змінені розклади й очищає застарілі очікувані слоти; перезаписи лише форматування не очищають очікуваний слот.
Примітка: визначення завдань Cron зберігаються в `jobs.json`, тоді як очікуваний стан середовища виконання зберігається в `jobs-state.json`. Якщо `jobs.json` редагується зовні, Gateway перезавантажує змінені розклади та очищає застарілі очікувані слоти; переписування лише форматування не очищає очікуваний слот.
### Ручні запуски
`openclaw cron run` повертається щойно ручний запуск поставлено в чергу. Успішні відповіді містять `{ ok: true, enqueued: true, runId }`. Використовуйте `openclaw cron runs --id <job-id>`, щоб відстежити кінцевий результат.
`openclaw cron run` повертається одразу після додавання ручного запуску до черги. Успішні відповіді містять `{ ok: true, enqueued: true, runId }`. Використовуйте `openclaw cron runs --id <job-id>`, щоб відстежити остаточний результат.
<Note>
`openclaw cron run <job-id>` за замовчуванням примусово запускає завдання. Використовуйте `--due`, щоб зберегти старішу поведінку "запускати лише якщо настав час".
`openclaw cron run <job-id>` за замовчуванням виконує примусовий запуск. Використовуйте `--due`, щоб зберегти старішу поведінку «запускати лише якщо настав час».
</Note>
## Моделі
@ -108,48 +108,48 @@ x-i18n:
`cron add|edit --model <ref>` вибирає дозволену модель для завдання.
<Warning>
Якщо модель не дозволена або її не можна обчислити, Cron завершує запуск з явною помилкою валідації замість повернення до агента завдання або вибору моделі за замовчуванням.
Якщо модель не дозволена або її неможливо розв’язати, Cron завершує запуск явною помилкою валідації замість повернення до агента завдання або вибору моделі за замовчуванням.
</Warning>
Cron `--model` — це **основний параметр завдання**, а не перевизначення `/model` сесії чату. Це означає:
Cron `--model` є **основним параметром завдання**, а не перевизначенням `/model` чат-сесії. Це означає:
- Налаштовані резервні моделі все одно застосовуються, коли вибрана модель завдання завершується помилкою.
- Корисне навантаження `fallbacks` для окремого завдання замінює налаштований список резервних моделей, коли воно присутнє.
- Порожній список резервних моделей для окремого завдання (`fallbacks: []` у корисному навантаженні/API завдання) робить запуск Cron строгим.
- Коли завдання має `--model`, але список резервних моделей не налаштовано, OpenClaw передає явне порожнє перевизначення резервних моделей, щоб основна модель агента не додавалася як прихована ціль повтору.
- Налаштовані резервні моделі все одно застосовуються, коли вибрана модель завдання зазнає збою.
- `fallbacks` у корисному навантаженні завдання замінює налаштований список резервних моделей, коли він присутній.
- Порожній список резервних моделей для завдання (`fallbacks: []` у корисному навантаженні/API завдання) робить запуск Cron строгим.
- Коли завдання має `--model`, але список резервних моделей не налаштовано, OpenClaw передає явне порожнє перевизначення резервних моделей, щоб основна модель агента не додавалася як прихована ціль повторної спроби.
### Пріоритет моделей ізольованого Cron
### Пріоритет моделі ізольованого Cron
Ізольований Cron обчислює активну модель у такому порядку:
Ізольований Cron розв’язує активну модель у такому порядку:
1. Перевизначення Gmail-hook.
2. `--model` для окремого завдання.
3. Збережене перевизначення моделі cron-сесії (коли користувач вибрав його).
2. `--model` для завдання.
3. Збережене перевизначення моделі Cron-сесії (коли користувач вибрав його).
4. Вибір моделі агента або моделі за замовчуванням.
### Швидкий режим
Швидкий режим ізольованого Cron дотримується обчисленого вибору живої моделі. Налаштування моделі `params.fastMode` застосовується за замовчуванням, але збережене перевизначення сесії `fastMode` все одно має пріоритет над конфігурацією.
Швидкий режим ізольованого Cron дотримується розв’язаного вибору поточної моделі. Конфігурація моделі `params.fastMode` застосовується за замовчуванням, але збережене перевизначення сесії `fastMode` все одно має пріоритет над конфігурацією.
### Повтори перемикання живої моделі
### Повторні спроби перемикання поточної моделі
Якщо ізольований запуск викидає `LiveSessionModelSwitchError`, Cron зберігає перемкненого провайдера й модель (а також перевизначення перемкненого профілю автентифікації, коли воно присутнє) для активного запуску перед повтором. Зовнішній цикл повторів обмежений двома повторами перемикання після початкової спроби, після чого переривається замість нескінченного циклу.
Якщо ізольований запуск викидає `LiveSessionModelSwitchError`, Cron зберігає перемкненого провайдера та модель (і перевизначення перемкненого профілю автентифікації, коли воно присутнє) для активного запуску перед повторною спробою. Зовнішній цикл повторних спроб обмежено двома повторними спробами перемикання після початкової спроби, після чого він переривається замість нескінченного циклу.
## Вивід запуску та відмови
### Придушення застарілих підтверджень
Ходи ізольованого Cron придушують застарілі відповіді, що містять лише підтвердження. Якщо перший результат — це лише проміжне оновлення статусу, і жоден дочірній запуск субагента не відповідає за кінцеву відповідь, Cron один раз повторно запитує справжній результат перед доставкою.
Ходи ізольованого Cron придушують застарілі відповіді, що містять лише підтвердження. Якщо перший результат є лише проміжним оновленням стану й жоден запуск нащадкового субагента не відповідає за остаточну відповідь, Cron один раз повторно запитує справжній результат перед доставкою.
### Придушення тихого токена
### Придушення мовчазного токена
Якщо ізольований запуск Cron повертає лише тихий токен (`NO_REPLY` або `no_reply`), Cron придушує як пряму вихідну доставку, так і резервний шлях поставленого в чергу підсумку, тож нічого не надсилається назад у чат.
Якщо ізольований запуск Cron повертає лише мовчазний токен (`NO_REPLY` або `no_reply`), Cron придушує і пряму вихідну доставку, і резервний шлях підсумку в черзі, тож у чат нічого не публікується.
### Структуровані відмови
Ізольовані запуски Cron надають перевагу структурованим метаданим відмови виконання з вбудованого запуску, а потім повертаються до відомих маркерів відмови у фінальному виводі, таких як `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` і фрази відмови прив’язки схвалення.
Ізольовані запуски Cron віддають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім повертаються до відомих маркерів відмови у фінальному виводі, таких як `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` і фрази відмови через прив’язку схвалення.
`cron list` та історія запусків показують причину відмови замість того, щоб повідомляти про заблоковану команду як `ok`.
`cron list` та історія запусків показують причину відмови замість повідомлення про заблоковану команду як `ok`.
## Зберігання
@ -161,42 +161,42 @@ Cron `--model` — це **основний параметр завдання**,
## Міграція старіших завдань
<Note>
Якщо у вас є завдання Cron з часів до поточного формату доставки й сховища, запустіть `openclaw doctor --fix`. Doctor нормалізує застарілі поля Cron (`jobId`, `schedule.cron`, поля доставки верхнього рівня, зокрема застаріле `threadId`, псевдоніми доставки `provider` у корисному навантаженні) і мігрує прості резервні завдання Webhook `notify: true` до явної доставки Webhook, коли налаштовано `cron.webhook`.
Якщо у вас є завдання Cron зі старішого формату доставки та сховища, запустіть `openclaw doctor --fix`. Doctor нормалізує застарілі поля Cron (`jobId`, `schedule.cron`, поля доставки верхнього рівня, включно із застарілим `threadId`, псевдоніми доставки `provider` у корисному навантаженні) і мігрує прості резервні завдання Webhook `notify: true` до явної доставки Webhook, коли `cron.webhook` налаштовано.
</Note>
## Типові редагування
## Поширені редагування
Оновіть налаштування доставки без зміни повідомлення:
Оновити налаштування доставки без зміни повідомлення:
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
```
Вимкніть доставку для ізольованого завдання:
Вимкнути доставку для ізольованого завдання:
```bash
openclaw cron edit <job-id> --no-deliver
```
Увімкніть легкий bootstrap-контекст для ізольованого завдання:
Увімкнути легкий контекст початкового завантаження для ізольованого завдання:
```bash
openclaw cron edit <job-id> --light-context
```
Оголосіть у конкретний канал:
Оголосити в конкретний канал:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
Оголосіть у тему форуму Telegram:
Оголосити в тему форуму Telegram:
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
```
Створіть ізольоване завдання з легким bootstrap-контекстом:
Створити ізольоване завдання з легким контекстом початкового завантаження:
```bash
openclaw cron add \
@ -208,9 +208,9 @@ openclaw cron add \
--no-deliver
```
`--light-context` застосовується лише до ізольованих завдань ходу агента. Для запусків Cron легкий режим залишає bootstrap-контекст порожнім замість ін’єкції повного набору bootstrap робочого простору.
`--light-context` застосовується лише до ізольованих завдань ходу агента. Для запусків Cron легкий режим залишає контекст початкового завантаження порожнім замість впровадження повного набору початкового завантаження робочого простору.
## Типові команди адміністратора
## Поширені адміністративні команди
Ручний запуск і перевірка:
@ -222,9 +222,9 @@ openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50
```
Записи `cron runs` містять діагностику доставки з цільовою Cron-ціллю, обчисленою ціллю, надсиланнями через інструмент message, використанням резервної доставки та станом доставки.
Записи `cron runs` містять діагностику доставки з передбаченою ціллю Cron, розв’язаною ціллю, надсиланнями інструмента повідомлень, використанням резервної доставки та станом доставки.
Перенацілювання агента й сесії:
Перенацілення агента та сесії:
```bash
openclaw cron edit <job-id> --agent ops
@ -233,7 +233,7 @@ openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
```
`openclaw cron add` попереджає, коли `--agent` пропущено для завдань ходу агента, і повертається до агента за замовчуванням (`main`). Передайте `--agent <id>` під час створення, щоб закріпити конкретного агента.
`openclaw cron add` попереджає, коли `--agent` пропущено в завданнях ходу агента, і повертається до агента за замовчуванням (`main`). Передайте `--agent <id>` під час створення, щоб закріпити конкретного агента.
Налаштування доставки:

173
docs/uk/providers/google.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Ви хочете використовувати моделі Google Gemini з OpenClaw
- Вам потрібен ключ API або потік автентифікації OAuth
summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук)
- Потрібен API-ключ або потік автентифікації OAuth
summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіаконтенту, TTS, вебпошук)
title: Google (Gemini)
x-i18n:
generated_at: "2026-05-02T02:49:08Z"
generated_at: "2026-05-02T04:47:18Z"
model: gpt-5.5
provider: openai
source_hash: 17d7694408dd02ea87d71530a544ad45e0284a973803f76313338a5065b3f7d5
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
source_path: providers/google.md
workflow: 16
---
@ -17,11 +17,11 @@ Plugin Google надає доступ до моделей Gemini через Goog
генерацію зображень, розуміння медіа (зображення/аудіо/відео), перетворення тексту на мовлення та вебпошук через
Gemini Grounding.
- Провайдер: `google`
- Постачальник: `google`
- Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY`
- API: Google Gemini API
- Опція середовища виконання: `agents.defaults.agentRuntime.id: "google-gemini-cli"`
повторно використовує OAuth Gemini CLI, водночас зберігаючи посилання на моделі канонічними як `google/*`.
повторно використовує OAuth Gemini CLI, зберігаючи посилання на моделі канонічними як `google/*`.
## Початок роботи
@ -32,7 +32,7 @@ Gemini Grounding.
**Найкраще для:** стандартного доступу до Gemini API через Google AI Studio.
<Steps>
<Step title="Запустіть онбординг">
<Step title="Запустіть первинне налаштування">
```bash
openclaw onboard --auth-choice gemini-api-key
```
@ -65,7 +65,7 @@ Gemini Grounding.
</Steps>
<Tip>
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яку вже налаштовано.
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` підтримуються обидві. Використовуйте ту, яку вже налаштовано.
</Tip>
</Tab>
@ -74,13 +74,13 @@ Gemini Grounding.
**Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого ключа API.
<Warning>
Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
повідомляють про обмеження облікових записів під час використання OAuth у такий спосіб. Використовуйте на власний ризик.
Постачальник `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
повідомляють про обмеження облікових записів під час використання OAuth таким способом. Використовуйте на власний ризик.
</Warning>
<Steps>
<Step title="Установіть Gemini CLI">
Локальна команда `gemini` має бути доступна в `PATH`.
Локальна команда `gemini` має бути доступною в `PATH`.
```bash
# Homebrew
@ -90,8 +90,8 @@ Gemini Grounding.
npm install -g @google/gemini-cli
```
OpenClaw підтримує встановлення через Homebrew і глобальні встановлення npm, включно з
поширеними структурами Windows/npm.
OpenClaw підтримує як інсталяції Homebrew, так і глобальні інсталяції npm, зокрема
поширені компонування Windows/npm.
</Step>
<Step title="Увійдіть через OAuth">
```bash
@ -109,7 +109,7 @@ Gemini Grounding.
- Середовище виконання: `google-gemini-cli`
- Псевдонім: `gemini-cli`
Ідентифікатор моделі Gemini API для Gemini 3.1 Pro — `gemini-3.1-pro-preview`. OpenClaw приймає коротший `google/gemini-3.1-pro` як зручний псевдонім і нормалізує його перед викликами провайдера.
Ідентифікатор моделі Gemini 3.1 Pro у Gemini API — `gemini-3.1-pro-preview`. OpenClaw приймає коротший `google/gemini-3.1-pro` як зручний псевдонім і нормалізує його перед викликами постачальника.
**Змінні середовища:**
@ -119,17 +119,17 @@ Gemini Grounding.
(Або варіанти `GEMINI_CLI_*`.)
<Note>
Якщо запити Gemini CLI OAuth не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або
Якщо запити OAuth Gemini CLI після входу завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або
`GOOGLE_CLOUD_PROJECT_ID` на хості Gateway і повторіть спробу.
</Note>
<Note>
Якщо вхід не вдається до запуску браузерного потоку, переконайтеся, що локальну команду `gemini`
установлено і вона є в `PATH`.
Якщо вхід завершується помилкою до запуску потоку браузера, переконайтеся, що локальна команда `gemini`
установлена й доступна в `PATH`.
</Note>
Посилання на моделі `google-gemini-cli/*` є застарілими псевдонімами сумісності. Нові
конфігурації мають використовувати посилання на моделі `google/*` плюс середовище виконання `google-gemini-cli`,
конфігурації мають використовувати посилання на моделі `google/*` разом із середовищем виконання `google-gemini-cli`,
коли потрібне локальне виконання Gemini CLI.
</Tab>
@ -142,7 +142,7 @@ Gemini Grounding.
| Завершення чату | Так |
| Генерація зображень | Так |
| Генерація музики | Так |
| Перетворення тексту на мовлення | Так |
| Перетворення тексту на мовлення | Так |
| Голос у реальному часі | Так (Google Live API) |
| Розуміння зображень | Так |
| Транскрипція аудіо | Так |
@ -153,8 +153,9 @@ Gemini Grounding.
## Вебпошук
Вбудований провайдер вебпошуку `gemini` використовує заземлення Gemini Google Search.
Налаштуйте його в `plugins.entries.google.config.webSearch`:
Вбудований постачальник вебпошуку `gemini` використовує Gemini Google Search grounding.
Налаштуйте спеціальний ключ пошуку в `plugins.entries.google.config.webSearch`
або дозвольте повторно використовувати `models.providers.google.apiKey` після `GEMINI_API_KEY`:
```json5
{
@ -163,8 +164,8 @@ Gemini Grounding.
google: {
config: {
webSearch: {
apiKey: "AIza...", // optional if GEMINI_API_KEY is set
baseUrl: "https://generativelanguage.googleapis.com/v1beta",
apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set
baseUrl: "https://generativelanguage.googleapis.com/v1beta", // falls back to models.providers.google.baseUrl
model: "gemini-2.5-flash",
},
},
@ -174,17 +175,19 @@ Gemini Grounding.
}
```
`webSearch.baseUrl` є необов'язковим і призначений для операторських проксі або сумісних
кінцевих точок Gemini API. Див. [Пошук Gemini](/uk/tools/gemini-search) щодо
поведінки інструмента, специфічної для провайдера.
Пріоритет облікових даних такий: спеціальний `webSearch.apiKey`, потім `GEMINI_API_KEY`,
потім `models.providers.google.apiKey`. `webSearch.baseUrl` необов’язковий і
існує для операторських проксі або сумісних кінцевих точок Gemini API; якщо його пропущено,
вебпошук Gemini повторно використовує `models.providers.google.baseUrl`. Див.
[пошук Gemini](/uk/tools/gemini-search), щоб дізнатися про поведінку інструмента, специфічну для постачальника.
<Tip>
Моделі Gemini 3 використовують `thinkingLevel`, а не `thinkingBudget`. OpenClaw зіставляє
керування міркуваннями для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` з
`thinkingLevel`, щоб запуски за замовчуванням/із низькою затримкою не надсилали вимкнені
керування міркуваннями для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` із
`thinkingLevel`, щоб запуски за замовчуванням або з низькою затримкою не надсилали вимкнені
значення `thinkingBudget`.
`/think adaptive` зберігає динамічну семантику мислення Google замість вибору
`/think adaptive` зберігає семантику динамічного мислення Google замість вибору
фіксованого рівня OpenClaw. Gemini 3 і Gemini 3.1 пропускають фіксований `thinkingLevel`, щоб
Google міг вибрати рівень; Gemini 2.5 надсилає динамічний sentinel Google
`thinkingBudget: -1`.
@ -197,7 +200,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
## Генерація зображень
Вбудований провайдер генерації зображень `google` за замовчуванням використовує
Вбудований постачальник генерації зображень `google` за замовчуванням використовує
`google/gemini-3.1-flash-image-preview`.
- Також підтримує `google/gemini-3-pro-image-preview`
@ -205,7 +208,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
- Режим редагування: увімкнено, до 5 вхідних зображень
- Керування геометрією: `size`, `aspectRatio` і `resolution`
Щоб використовувати Google як провайдера зображень за замовчуванням:
Щоб використовувати Google як постачальника зображень за замовчуванням:
```json5
{
@ -220,7 +223,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
```
<Note>
Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки перемикання після збою.
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
</Note>
## Генерація відео
@ -233,7 +236,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
- Підтримує `aspectRatio`, `resolution` і `audio`
- Поточне обмеження тривалості: **від 4 до 8 секунд**
Щоб використовувати Google як провайдера відео за замовчуванням:
Щоб використовувати Google як постачальника відео за замовчуванням:
```json5
{
@ -248,7 +251,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
```
<Note>
Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки перемикання після збою.
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
</Note>
## Генерація музики
@ -258,12 +261,12 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
- Модель музики за замовчуванням: `google/lyria-3-clip-preview`
- Також підтримує `google/lyria-3-pro-preview`
- Керування промптом: `lyrics` і `instrumental`
- Формат виводу: `mp3` за замовчуванням, плюс `wav` на `google/lyria-3-pro-preview`
- Вхідні референси: до 10 зображень
- Запуски з підтримкою сесії від'єднуються через спільний потік завдання/статусу, включно з `action: "status"`
- Керування підказкою: `lyrics` і `instrumental`
- Формат виводу: `mp3` за замовчуванням, а також `wav` у `google/lyria-3-pro-preview`
- Вхідні посилання: до 10 зображень
- Запуски з підтримкою сеансів від’єднуються через спільний потік завдання/статусу, зокрема `action: "status"`
Щоб використовувати Google як провайдера музики за замовчуванням:
Щоб використовувати Google як постачальника музики за замовчуванням:
```json5
{
@ -278,12 +281,12 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
```
<Note>
Див. [Генерація музики](/uk/tools/music-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки перемикання після збою.
Див. [Генерація музики](/uk/tools/music-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover.
</Note>
## Перетворення тексту на мовлення
Вбудований мовленнєвий провайдер `google` використовує шлях Gemini API TTS із
Вбудований постачальник мовлення `google` використовує шлях TTS Gemini API з
`gemini-3.1-flash-tts-preview`.
- Голос за замовчуванням: `Kore`
@ -291,7 +294,7 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
- Вивід: WAV для звичайних вкладень TTS, Opus для цілей голосових нотаток, PCM для Talk/телефонії
- Вивід голосової нотатки: Google PCM обгортається як WAV і транскодується в Opus 48 кГц за допомогою `ffmpeg`
Щоб використовувати Google як провайдера TTS за замовчуванням:
Щоб використовувати Google як постачальника TTS за замовчуванням:
```json5
{
@ -311,13 +314,13 @@ Google міг вибрати рівень; Gemini 2.5 надсилає дина
}
```
Gemini API TTS використовує промпти природною мовою для керування стилем. Установіть
`audioProfile`, щоб додавати багаторазовий стильовий промпт перед озвучуваним текстом. Установіть
`speakerName`, коли текст промпта посилається на названого мовця.
TTS Gemini API використовує підказки природною мовою для керування стилем. Установіть
`audioProfile`, щоб додати багаторазову стильову підказку перед озвучуваним текстом. Установіть
`speakerName`, коли текст підказки посилається на названого мовця.
Gemini API TTS також приймає виразні аудіотеги в квадратних дужках у тексті,
наприклад `[whispers]` або `[laughs]`. Щоб теги не відображалися у видимій відповіді чату,
але надсилалися до TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
TTS Gemini API також приймає виразні аудіотеги у квадратних дужках у тексті,
наприклад `[whispers]` або `[laughs]`. Щоб теги не з’являлися у видимій відповіді чату,
але надсилалися в TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
```text
Here is the clean reply text.
@ -326,29 +329,29 @@ Here is the clean reply text.
```
<Note>
Ключ API Google Cloud Console, обмежений Gemini API, є чинним для цього
провайдера. Це не окремий шлях Cloud Text-to-Speech API.
Ключ API Google Cloud Console, обмежений Gemini API, чинний для цього
постачальника. Це не окремий шлях Cloud Text-to-Speech API.
</Note>
## Голос у реальному часі
Вбудований Plugin `google` реєструє провайдера голосу в реальному часі на базі
Gemini Live API для бекенд-аудіомостів, як-от Voice Call і Google Meet.
Вбудований Plugin `google` реєструє постачальника голосу в реальному часі на основі
Gemini Live API для серверних аудіомостів, як-от Voice Call і Google Meet.
| Налаштування | Шлях конфігурації | За замовчуванням |
| Параметр | Шлях конфігурації | Типове значення |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| Голос | `...google.voice` | `Kore` |
| Температура | `...google.temperature` | (не задано) |
| Чутливість початку VAD | `...google.startSensitivity` | (не задано) |
| Чутливість завершення VAD | `...google.endSensitivity` | (не задано) |
| Чутливість початку VAD | `...google.startSensitivity` | (не задано) |
| Чутливість завершення VAD | `...google.endSensitivity` | (не задано) |
| Тривалість тиші | `...google.silenceDurationMs` | (не задано) |
| Обробка активності | `...google.activityHandling` | За замовчуванням Google, `start-of-activity-interrupts` |
| Покриття репліки | `...google.turnCoverage` | За замовчуванням Google, `only-activity` |
| Обробка активності | `...google.activityHandling` | Типове значення Google, `start-of-activity-interrupts` |
| Охоплення ходу | `...google.turnCoverage` | Типове значення Google, `only-activity` |
| Вимкнути автоматичний VAD | `...google.automaticActivityDetectionDisabled` | `false` |
| Ключ API | `...google.apiKey` | Повертається до `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
| Ключ API | `...google.apiKey` | Резервно використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
Приклад конфігурації реального часу Voice Call:
Приклад конфігурації Voice Call у реальному часі:
```json5
{
@ -377,39 +380,39 @@ Gemini Live API для бекенд-аудіомостів, як-от Voice Call
```
<Note>
Google Live API використовує двонапрямний звук і виклик функцій через WebSocket.
OpenClaw адаптує звук телефонії/моста Meet до потоку Gemini PCM Live API і
зберігає виклики інструментів у спільному контракті голосу реального часу. Залиште `temperature`
незаданим, якщо вам не потрібні зміни семплювання; OpenClaw пропускає непозитивні значення,
оскільки Google Live може повертати транскрипти без звуку для `temperature: 0`.
Google Live API використовує двонапрямний аудіопотік і виклики функцій через WebSocket.
OpenClaw адаптує аудіо мосту телефонії/Meet до потоку PCM Live API Gemini та
зберігає виклики інструментів у спільному контракті голосу в реальному часі. Залиште `temperature`
незаданим, якщо вам не потрібні зміни семплінгу; OpenClaw пропускає недодатні значення,
оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`.
Транскрипцію Gemini API увімкнено без `languageCodes`; поточний Google
SDK відхиляє підказки кодів мов на цьому шляху API.
</Note>
<Note>
Control UI Talk підтримує браузерні сеанси Google Live з обмеженими одноразовими
токенами. Постачальники голосу реального часу, що працюють лише на бекенді, також можуть працювати через загальний
токенами. Backend-only постачальники голосу в реальному часі також можуть працювати через загальний
транспорт ретрансляції Gateway, який зберігає облікові дані постачальника на Gateway.
</Note>
Для live-перевірки супровідником виконайте
Для live-перевірки супровідником запустіть
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`.
Гілка Google випускає токен Live API тієї самої обмеженої форми, яку використовує Control
UI Talk, відкриває браузерну кінцеву точку WebSocket, надсилає початкове корисне навантаження налаштування
і чекає на `setupComplete`.
та очікує `setupComplete`.
## Розширена конфігурація
<AccordionGroup>
<Accordion title="Пряме повторне використання кешу Gemini">
<Accordion title="Direct Gemini cache reuse">
Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw
передає налаштований дескриптор `cachedContent` до запитів Gemini.
- Налаштуйте параметри для окремої моделі або глобально за допомогою
`cachedContent` або застарілого `cached_content`
- Якщо присутні обидва, пріоритет має `cachedContent`
- Налаштовуйте параметри для окремої моделі або глобально за допомогою
`cachedContent` чи застарілого `cached_content`
- Якщо наявні обидва, перевагу має `cachedContent`
- Приклад значення: `cachedContents/prebuilt-context`
- Використання потрапляння в кеш Gemini нормалізується в OpenClaw `cacheRead` з
- Використання cache-hit Gemini нормалізується в OpenClaw `cacheRead` з
upstream `cachedContentTokenCount`
```json5
@ -430,19 +433,19 @@ UI Talk, відкриває браузерну кінцеву точку WebSock
</Accordion>
<Accordion title="Нотатки щодо використання JSON у Gemini CLI">
<Accordion title="Gemini CLI JSON usage notes">
Під час використання OAuth-постачальника `google-gemini-cli` OpenClaw нормалізує
JSON-вивід CLI так:
- Текст відповіді надходить із поля CLI JSON `response`.
- Використання повертається до `stats`, коли CLI залишає `usage` порожнім.
- Текст відповіді береться з поля CLI JSON `response`.
- Використання резервно береться зі `stats`, коли CLI залишає `usage` порожнім.
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з
- Якщо `stats.input` відсутнє, OpenClaw виводить вхідні токени з
`stats.input_tokens - stats.cached`.
</Accordion>
<Accordion title="Налаштування середовища й демона">
<Accordion title="Environment and daemon setup">
Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `GEMINI_API_KEY`
доступний цьому процесу (наприклад, у `~/.openclaw/.env` або через
`env.shellEnv`).
@ -452,16 +455,16 @@ UI Talk, відкриває браузерну кінцеву точку WebSock
## Пов’язане
<CardGroup cols={2}>
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
Вибір постачальників, посилань на моделі й поведінки відмовостійкого перемикання.
<Card title="Model selection" href="/uk/concepts/model-providers" icon="layers">
Вибір постачальників, посилань на моделі та поведінки відмовостійкого перемикання.
</Card>
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
Спільні параметри інструменту зображень і вибір постачальника.
<Card title="Image generation" href="/uk/tools/image-generation" icon="image">
Спільні параметри інструмента зображень і вибір постачальника.
</Card>
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
Спільні параметри інструменту відео й вибір постачальника.
<Card title="Video generation" href="/uk/tools/video-generation" icon="video">
Спільні параметри інструмента відео та вибір постачальника.
</Card>
<Card title="Генерація музики" href="/uk/tools/music-generation" icon="music">
Спільні параметри інструменту музики й вибір постачальника.
<Card title="Music generation" href="/uk/tools/music-generation" icon="music">
Спільні параметри інструмента музики та вибір постачальника.
</Card>
</CardGroup>

198
docs/uk/providers/minimax.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Ви хочете використовувати моделі MiniMax в OpenClaw
- Вам потрібні моделі MiniMax в OpenClaw
- Вам потрібні інструкції з налаштування MiniMax
summary: Використання моделей MiniMax в OpenClaw
title: MiniMax
x-i18n:
generated_at: "2026-04-28T11:23:10Z"
generated_at: "2026-05-02T04:47:50Z"
model: gpt-5.5
provider: openai
source_hash: 0ef833258692c78f40a160131c2a0d36f84889e5d5196ddadb648485ba8cb04a
source_hash: 3becdbd14243ce0817d630e6af70559a9b2c9f66860d3f588fef0a118034d2f9
source_path: providers/minimax.md
workflow: 16
---
@ -20,7 +20,7 @@ MiniMax also provides:
- Bundled speech synthesis via T2A v2
- Bundled image understanding via `MiniMax-VL-01`
- Bundled music generation via `music-2.6`
- Bundled `web_search` through the MiniMax Coding Plan search API
- Bundled `web_search` through the MiniMax Token Plan search API
Provider split:
@ -201,14 +201,14 @@ Use the interactive config wizard to set MiniMax without editing JSON:
| Варіант автентифікації | Опис |
| --- | --- |
| `minimax-global-oauth` | Міжнародний OAuth (тариф Coding Plan) |
| `minimax-cn-oauth` | Китайський OAuth (тариф Coding Plan) |
| `minimax-global-api` | Міжнародний ключ API |
| `minimax-cn-api` | Китайський ключ API |
| `minimax-global-oauth` | Міжнародний OAuth (Coding Plan) |
| `minimax-cn-oauth` | Китайський OAuth (Coding Plan) |
| `minimax-global-api` | Міжнародний API key |
| `minimax-cn-api` | Китайський API key |
</Step>
<Step title="Виберіть модель за замовчуванням">
Виберіть модель за замовчуванням, коли з’явиться запит.
<Step title="Виберіть стандартну модель">
Виберіть стандартну модель, коли з’явиться запит.
</Step>
</Steps>
@ -218,13 +218,13 @@ Use the interactive config wizard to set MiniMax without editing JSON:
Plugin MiniMax реєструє модель `image-01` для інструмента `image_generate`. Вона підтримує:
- **Генерацію зображень із тексту** з керуванням співвідношенням сторін
- **Редагування зображення за зображенням** (референс об’єкта) з керуванням співвідношенням сторін
- **Генерацію тексту в зображення** з керуванням співвідношенням сторін
- **Редагування зображення в зображення** (референс суб’єкта) з керуванням співвідношенням сторін
- До **9 вихідних зображень** на запит
- До **1 референсного зображення** на запит редагування
- Підтримувані співвідношення сторін: `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`
Щоб використовувати MiniMax для генерації зображень, задайте його як постачальника генерації зображень:
Щоб використовувати MiniMax для генерації зображень, установіть його як провайдера генерації зображень:
```json5
{
@ -236,55 +236,55 @@ Plugin MiniMax реєструє модель `image-01` для інструме
}
```
Plugin використовує той самий `MINIMAX_API_KEY` або OAuth-автентифікацію, що й текстові моделі. Додаткова конфігурація не потрібна, якщо MiniMax уже налаштовано.
Plugin використовує той самий `MINIMAX_API_KEY` або автентифікацію OAuth, що й текстові моделі. Якщо MiniMax уже налаштовано, додаткова конфігурація не потрібна.
І `minimax`, і `minimax-portal` реєструють `image_generate` з тією самою
моделлю `image-01`. Налаштування з ключем API використовують `MINIMAX_API_KEY`; налаштування OAuth можуть використовувати
моделлю `image-01`. Налаштування з API-key використовують `MINIMAX_API_KEY`; налаштування OAuth можуть натомість використовувати
вбудований шлях автентифікації `minimax-portal`.
Генерація зображень завжди використовує спеціалізований кінцевий пункт MiniMax для зображень
Генерація зображень завжди використовує спеціальний endpoint зображень MiniMax
(`/v1/image_generation`) та ігнорує `models.providers.minimax.baseUrl`,
оскільки це поле налаштовує базову URL-адресу чату/Anthropic-сумісного API. Задайте
оскільки це поле налаштовує базовий URL для чату/Anthropic-сумісності. Установіть
`MINIMAX_API_HOST=https://api.minimaxi.com`, щоб спрямувати генерацію зображень
через CN-кінцевий пункт; глобальний кінцевий пункт за замовчуванням —
через CN endpoint; стандартний глобальний endpoint —
`https://api.minimax.io`.
Коли онбординг або налаштування ключа API записує явні записи `models.providers.minimax`,
Коли онбординг або налаштування API-key записує явні записи `models.providers.minimax`,
OpenClaw матеріалізує `MiniMax-M2.7` і
`MiniMax-M2.7-highspeed` як текстові чат-моделі. Розуміння зображень
окремо надається через медіапостачальника `MiniMax-VL-01`, що належить Plugin.
доступне окремо через належний Plugin медіапровайдер `MiniMax-VL-01`.
<Note>
Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору постачальника та поведінки відмовостійкості.
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover.
</Note>
### Синтез мовлення
Вбудований Plugin `minimax` реєструє MiniMax T2A v2 як постачальника мовлення для
Вбудований Plugin `minimax` реєструє MiniMax T2A v2 як провайдера мовлення для
`messages.tts`.
- Модель TTS за замовчуванням: `speech-2.8-hd`
- Голос за замовчуванням: `English_expressive_narrator`
- Стандартна модель TTS: `speech-2.8-hd`
- Стандартний голос: `English_expressive_narrator`
- Підтримувані вбудовані ідентифікатори моделей включають `speech-2.8-hd`, `speech-2.8-turbo`,
`speech-2.6-hd`, `speech-2.6-turbo`, `speech-02-hd`,
`speech-02-turbo`, `speech-01-hd` і `speech-01-turbo`.
- Розв’язання автентифікації відбувається в такому порядку: `messages.tts.providers.minimax.apiKey`, потім
профілі OAuth/токен-автентифікації `minimax-portal`, потім ключі середовища
профілі автентифікації OAuth/token `minimax-portal`, потім ключі середовища
Token Plan (`MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`,
`MINIMAX_CODING_API_KEY`), потім `MINIMAX_API_KEY`.
- Якщо хост TTS не налаштовано, OpenClaw повторно використовує налаштований
OAuth-хост `minimax-portal` і прибирає Anthropic-сумісні суфікси шляху,
OAuth-хост `minimax-portal` і вилучає Anthropic-сумісні суфікси шляхів,
як-от `/anthropic`.
- Звичайні аудіовкладення залишаються MP3.
- Цілі голосових нотаток, як-от Feishu і Telegram, перекодовуються з MiniMax
MP3 у Opus 48 кГц за допомогою `ffmpeg`, оскільки файловий API Feishu/Lark приймає лише
`file_type: "opus"` для нативних аудіоповідомлень.
- Цілі для голосових нотаток, як-от Feishu і Telegram, транскодуються з MiniMax
MP3 у 48kHz Opus за допомогою `ffmpeg`, оскільки файловий API Feishu/Lark приймає
лише `file_type: "opus"` для нативних аудіоповідомлень.
- MiniMax T2A приймає дробові `speed` і `vol`, але `pitch` надсилається як
ціле число; OpenClaw обрізає дробові значення `pitch` перед API-запитом.
| Налаштування | Змінна середовища | За замовчуванням | Опис |
| Налаштування | Змінна середовища | Стандартне значення | Опис |
| ---------------------------------------- | ---------------------- | ----------------------------- | -------------------------------- |
| `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | Хост API MiniMax T2A. |
| `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | Хост MiniMax T2A API. |
| `messages.tts.providers.minimax.model` | `MINIMAX_TTS_MODEL` | `speech-2.8-hd` | Ідентифікатор моделі TTS. |
| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | Ідентифікатор голосу для мовленнєвого виводу. |
| `messages.tts.providers.minimax.speed` | | `1.0` | Швидкість відтворення, `0.5..2.0`. |
@ -296,14 +296,14 @@ OpenClaw матеріалізує `MiniMax-M2.7` і
Вбудований Plugin MiniMax реєструє генерацію музики через спільний
інструмент `music_generate` як для `minimax`, так і для `minimax-portal`.
- Музична модель за замовчуванням: `minimax/music-2.6`
- Стандартна музична модель: `minimax/music-2.6`
- Музична модель OAuth: `minimax-portal/music-2.6`
- Також підтримує `minimax/music-2.5` і `minimax/music-2.0`
- Керування запитом: `lyrics`, `instrumental`, `durationSeconds`
- Елементи керування промптом: `lyrics`, `instrumental`, `durationSeconds`
- Формат виводу: `mp3`
- Запуски з підтримкою сеансу від’єднуються через спільний потік завдань/статусу, зокрема `action: "status"`
- Запуски з підтримкою сесій від’єднуються через спільний потік завдань/статусу, включно з `action: "status"`
Щоб використовувати MiniMax як постачальника музики за замовчуванням:
Щоб використовувати MiniMax як стандартного музичного провайдера:
```json5
{
@ -318,7 +318,7 @@ OpenClaw матеріалізує `MiniMax-M2.7` і
```
<Note>
Див. [Генерація музики](/uk/tools/music-generation) щодо спільних параметрів інструмента, вибору постачальника та поведінки відмовостійкості.
Див. [Генерація музики](/uk/tools/music-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку failover.
</Note>
### Генерація відео
@ -326,12 +326,12 @@ OpenClaw матеріалізує `MiniMax-M2.7` і
Вбудований Plugin MiniMax реєструє генерацію відео через спільний
інструмент `video_generate` як для `minimax`, так і для `minimax-portal`.
- Відеомодель за замовчуванням: `minimax/MiniMax-Hailuo-2.3`
- Стандартна відеомодель: `minimax/MiniMax-Hailuo-2.3`
- Відеомодель OAuth: `minimax-portal/MiniMax-Hailuo-2.3`
- Режими: потоки текст-у-відео та з референсом одного зображення
- Режими: потоки тексту у відео та референсу одного зображення
- Підтримує `aspectRatio` і `resolution`
Щоб використовувати MiniMax як постачальника відео за замовчуванням:
Щоб використовувати MiniMax як стандартного відеопровайдера:
```json5
{
@ -346,7 +346,7 @@ OpenClaw матеріалізує `MiniMax-M2.7` і
```
<Note>
Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору провайдера та поведінки резервного перемикання.
Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору постачальника та поведінки резервного перемикання.
</Note>
### Розуміння зображень
@ -354,60 +354,60 @@ OpenClaw матеріалізує `MiniMax-M2.7` і
Plugin MiniMax реєструє розуміння зображень окремо від текстового
каталогу:
| ID провайдера | Стандартна модель зображень |
| ---------------- | --------------------------- |
| `minimax` | `MiniMax-VL-01` |
| `minimax-portal` | `MiniMax-VL-01` |
| Ідентифікатор постачальника | Типова модель зображень |
| --------------------------- | ----------------------- |
| `minimax` | `MiniMax-VL-01` |
| `minimax-portal` | `MiniMax-VL-01` |
Саме тому автоматична маршрутизація медіа може використовувати розуміння
зображень MiniMax, навіть коли вбудований каталог текстового провайдера все ще
показує лише текстові chat refs M2.7.
зображень MiniMax навіть тоді, коли вбудований каталог текстового постачальника
все ще показує лише текстові посилання чату M2.7.
### Вебпошук
Plugin MiniMax також реєструє `web_search` через пошуковий API MiniMax Coding Plan.
Plugin MiniMax також реєструє `web_search` через пошуковий API MiniMax Token Plan.
- ID провайдера: `minimax`
- Структуровані результати: заголовки, URL-адреси, фрагменти, пов’язані запити
- Ідентифікатор постачальника: `minimax`
- Структуровані результати: заголовки, URL, фрагменти, пов’язані запити
- Бажана змінна середовища: `MINIMAX_CODE_PLAN_KEY`
- Прийнятий псевдонім env: `MINIMAX_CODING_API_KEY`
- Резервна сумісність: `MINIMAX_API_KEY`, коли він уже вказує на токен coding-plan
- Повторне використання регіону: `plugins.entries.minimax.config.webSearch.region`, потім `MINIMAX_API_HOST`, потім базові URL провайдера MiniMax
- Пошук залишається на ID провайдера `minimax`; налаштування OAuth CN/global усе ще може опосередковано спрямовувати регіон через `models.providers.minimax-portal.baseUrl`
- Прийняті псевдоніми змінних середовища: `MINIMAX_CODING_API_KEY`, `MINIMAX_OAUTH_TOKEN`
- Резервна сумісність: `MINIMAX_API_KEY`, коли вона вже вказує на облікові дані token-plan
- Повторне використання регіону: `plugins.entries.minimax.config.webSearch.region`, потім `MINIMAX_API_HOST`, потім базові URL постачальника MiniMax
- Пошук залишається на ідентифікаторі постачальника `minimax`; налаштування OAuth CN/global може опосередковано скеровувати регіон через `models.providers.minimax-portal.baseUrl` і може надавати bearer-автентифікацію через `MINIMAX_OAUTH_TOKEN`
Конфігурація міститься в `plugins.entries.minimax.config.webSearch.*`.
Конфігурація розташована в `plugins.entries.minimax.config.webSearch.*`.
<Note>
Див. [Пошук MiniMax](/uk/tools/minimax-search) для повної конфігурації та використання вебпошуку.
Див. [Пошук MiniMax](/uk/tools/minimax-search) щодо повної конфігурації та використання вебпошуку.
</Note>
## Розширена конфігурація
<AccordionGroup>
<Accordion title="Configuration options">
| Опція | Опис |
<Accordion title="Параметри конфігурації">
| Параметр | Опис |
| --- | --- |
| `models.providers.minimax.baseUrl` | Надавайте перевагу `https://api.minimax.io/anthropic` (сумісний з Anthropic); `https://api.minimax.io/v1` необов’язковий для payload, сумісних з OpenAI |
| `models.providers.minimax.api` | Надавайте перевагу `anthropic-messages`; `openai-completions` необов’язковий для payload, сумісних з OpenAI |
| `models.providers.minimax.baseUrl` | Бажано `https://api.minimax.io/anthropic` (сумісний з Anthropic); `https://api.minimax.io/v1` необов’язковий для payload, сумісних з OpenAI |
| `models.providers.minimax.api` | Бажано `anthropic-messages`; `openai-completions` необов’язковий для payload, сумісних з OpenAI |
| `models.providers.minimax.apiKey` | API-ключ MiniMax (`MINIMAX_API_KEY`) |
| `models.providers.minimax.models` | Визначає `id`, `name`, `reasoning`, `contextWindow`, `maxTokens`, `cost` |
| `agents.defaults.models` | Псевдоніми моделей, які ви хочете додати до allowlist |
| `models.mode` | Залиште `merge`, якщо хочете додати MiniMax поряд із вбудованими моделями |
| `models.mode` | Залиште `merge`, якщо хочете додати MiniMax поруч із вбудованими моделями |
</Accordion>
<Accordion title="Thinking defaults">
Для `api: "anthropic-messages"` OpenClaw додає `thinking: { type: "disabled" }`, якщо thinking ще не встановлено явно в params/config.
<Accordion title="Типові налаштування мислення">
Для `api: "anthropic-messages"` OpenClaw додає `thinking: { type: "disabled" }`, якщо мислення вже не задано явно в параметрах/конфігурації.
Це запобігає тому, щоб streaming endpoint MiniMax випускав `reasoning_content` у delta chunks стилю OpenAI, що могло б розкрити внутрішні міркування у видимому виводі.
Це не дає streaming endpoint MiniMax випускати `reasoning_content` у delta-частинах у стилі OpenAI, що призвело б до витоку внутрішніх міркувань у видимий вивід.
</Accordion>
<Accordion title="Fast mode">
`/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed` у stream path, сумісному з Anthropic.
<Accordion title="Швидкий режим">
`/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed` на шляху потоку, сумісному з Anthropic.
</Accordion>
<Accordion title="Fallback example">
**Найкраще для:** зберігайте вашу найсильнішу модель останнього покоління як primary, а в разі збою перемикайтеся на MiniMax M2.7. Приклад нижче використовує Opus як конкретну primary; замініть її на бажану primary-модель останнього покоління.
<Accordion title="Приклад резервного перемикання">
**Найкраще для:** збереження вашої найсильнішої моделі останнього покоління як основної з резервним перемиканням на MiniMax M2.7. У прикладі нижче Opus використано як конкретну основну модель; замініть її на бажану основну модель останнього покоління.
```json5
{
@ -429,52 +429,52 @@ Plugin MiniMax також реєструє `web_search` через пошуко
</Accordion>
<Accordion title="Coding Plan usage details">
- API використання Coding Plan: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (потребує ключа coding plan).
- OpenClaw нормалізує використання coding-plan MiniMax до того самого відображення `% left`, яке використовують інші провайдери. Сирі поля MiniMax `usage_percent` / `usagePercent` є залишком квоти, а не спожитою квотою, тому OpenClaw інвертує їх. Поля на основі лічильників мають пріоритет, коли вони присутні.
- Коли API повертає `model_remains`, OpenClaw надає перевагу запису chat-моделі, за потреби виводить мітку вікна з `start_time` / `end_time` і додає назву вибраної моделі до мітки плану, щоб вікна coding-plan було легше розрізняти.
- Знімки використання розглядають `minimax`, `minimax-cn` і `minimax-portal` як одну й ту саму поверхню квоти MiniMax і надають перевагу збереженому OAuth MiniMax перед резервним переходом до env vars ключа Coding Plan.
<Accordion title="Деталі використання Coding Plan">
- API використання Coding Plan: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (потрібен ключ coding plan).
- OpenClaw нормалізує використання coding-plan MiniMax до такого самого відображення `% left`, яке використовують інші постачальники. Необроблені поля MiniMax `usage_percent` / `usagePercent` означають залишок квоти, а не використану квоту, тому OpenClaw інвертує їх. Поля на основі кількості мають пріоритет, коли вони наявні.
- Коли API повертає `model_remains`, OpenClaw віддає перевагу запису моделі чату, за потреби виводить мітку вікна зі `start_time` / `end_time` і включає назву вибраної моделі в мітку плану, щоб вікна coding-plan було легше розрізняти.
- Знімки використання розглядають `minimax`, `minimax-cn` і `minimax-portal` як одну й ту саму поверхню квоти MiniMax і віддають перевагу збереженому OAuth MiniMax перед резервним використанням змінних середовища ключа Coding Plan.
</Accordion>
</AccordionGroup>
## Примітки
- Model refs відповідають шляху автентифікації:
- Посилання на моделі відповідають шляху автентифікації:
- Налаштування API-ключа: `minimax/<model>`
- Налаштування OAuth: `minimax-portal/<model>`
- Стандартна chat-модель: `MiniMax-M2.7`
- Альтернативна chat-модель: `MiniMax-M2.7-highspeed`
- Onboarding і пряме налаштування API-ключа записують визначення текстових моделей для обох варіантів M2.7
- Розуміння зображень використовує медіапровайдера `MiniMax-VL-01`, яким володіє Plugin
- Оновіть значення цін у `models.json`, якщо вам потрібне точне відстеження витрат
- Використовуйте `openclaw models list`, щоб підтвердити поточний ID провайдера, потім перемкніться за допомогою `openclaw models set minimax/MiniMax-M2.7` або `openclaw models set minimax-portal/MiniMax-M2.7`
- Типова модель чату: `MiniMax-M2.7`
- Альтернативна модель чату: `MiniMax-M2.7-highspeed`
- Онбординг і пряме налаштування API-ключа записують визначення моделей лише для тексту для обох варіантів M2.7
- Розуміння зображень використовує належного Plugin медіапостачальника `MiniMax-VL-01`
- Оновіть значення цін у `models.json`, якщо вам потрібне точне відстеження вартості
- Використовуйте `openclaw models list`, щоб підтвердити поточний ідентифікатор постачальника, а потім перемкніться за допомогою `openclaw models set minimax/MiniMax-M2.7` або `openclaw models set minimax-portal/MiniMax-M2.7`
<Tip>
Реферальне посилання для MiniMax Coding Plan (знижка 10%): [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
</Tip>
<Note>
Див. [Провайдери моделей](/uk/concepts/model-providers) щодо правил провайдерів.
Див. [Постачальники моделей](/uk/concepts/model-providers) щодо правил постачальників.
</Note>
## Усунення несправностей
<AccordionGroup>
<Accordion title='"Unknown model: minimax/MiniMax-M2.7"'>
Зазвичай це означає, що **провайдер MiniMax не налаштовано** (немає відповідного запису провайдера й не знайдено профілю автентифікації MiniMax або env-ключа). Виправлення для цього виявлення є у **2026.1.12**. Виправте так:
Зазвичай це означає, що **постачальника MiniMax не налаштовано** (немає відповідного запису постачальника й не знайдено профіль автентифікації/ключ середовища MiniMax). Виправлення для цього виявлення є у **2026.1.12**. Виправте так:
- Оновіться до **2026.1.12** (або запустіть із source `main`), потім перезапустіть gateway.
- Запустіть `openclaw configure` і виберіть опцію автентифікації **MiniMax**, або
- Додайте відповідний блок `models.providers.minimax` чи `models.providers.minimax-portal` вручну, або
- Установіть `MINIMAX_API_KEY`, `MINIMAX_OAUTH_TOKEN` або профіль автентифікації MiniMax, щоб можна було інжектувати відповідного провайдера.
- Оновіться до **2026.1.12** (або запустіть із вихідного коду `main`), потім перезапустіть gateway.
- Запустіть `openclaw configure` і виберіть варіант автентифікації **MiniMax**, або
- Додайте відповідний блок `models.providers.minimax` або `models.providers.minimax-portal` вручну, або
- Задайте `MINIMAX_API_KEY`, `MINIMAX_OAUTH_TOKEN` або профіль автентифікації MiniMax, щоб можна було вставити відповідного постачальника.
Переконайтеся, що ID моделі **чутливий до регістру**:
Переконайтеся, що ідентифікатор моделі **чутливий до регістру**:
- Шлях API-ключа: `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed`
- Шлях OAuth: `minimax-portal/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7-highspeed`
Потім перевірте повторно за допомогою:
Потім перевірте ще раз за допомогою:
```bash
openclaw models list
@ -484,28 +484,28 @@ Plugin MiniMax також реєструє `web_search` через пошуко
</AccordionGroup>
<Note>
Більше довідки: [Усунення несправностей](/uk/help/troubleshooting) і [FAQ](/uk/help/faq).
Додаткова допомога: [Усунення несправностей](/uk/help/troubleshooting) і [FAQ](/uk/help/faq).
</Note>
## Пов’язане
<CardGroup cols={2}>
<Card title="Model selection" href="/uk/concepts/model-providers" icon="layers">
Вибір провайдерів, model refs і поведінка резервного перемикання.
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
Вибір постачальників, посилань на моделі та поведінки резервного перемикання.
</Card>
<Card title="Image generation" href="/uk/tools/image-generation" icon="image">
Спільні параметри інструмента зображень і вибір провайдера.
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
Спільні параметри інструмента зображень і вибір постачальника.
</Card>
<Card title="Music generation" href="/uk/tools/music-generation" icon="music">
Спільні параметри музичного інструмента й вибір провайдера.
<Card title="Генерація музики" href="/uk/tools/music-generation" icon="music">
Спільні параметри інструмента музики та вибір постачальника.
</Card>
<Card title="Video generation" href="/uk/tools/video-generation" icon="video">
Спільні параметри відеоінструмента й вибір провайдера.
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
Спільні параметри інструмента відео та вибір постачальника.
</Card>
<Card title="MiniMax Search" href="/uk/tools/minimax-search" icon="magnifying-glass">
Конфігурація вебпошуку через MiniMax Coding Plan.
<Card title="Пошук MiniMax" href="/uk/tools/minimax-search" icon="magnifying-glass">
Конфігурація вебпошуку через MiniMax Token Plan.
</Card>
<Card title="Troubleshooting" href="/uk/help/troubleshooting" icon="wrench">
<Card title="Усунення несправностей" href="/uk/help/troubleshooting" icon="wrench">
Загальне усунення несправностей і FAQ.
</Card>
</CardGroup>

602
docs/uk/reference/RELEASING.md
View File

@ -1,248 +1,260 @@
---
read_when:
- Пошук визначень публічних каналів випуску
- Запуск перевірки випуску або приймання пакета
- Шукаєте правила іменування версій і ритм випусків
summary: Канали випуску, контрольний список оператора, середовища перевірки, найменування версій і періодичність
- Пошук визначень публічних каналів релізів
- Запуск валідації релізу або приймального тестування пакета
- Шукаєте інформацію про іменування версій і періодичність випусків
summary: Релізні канали, контрольний список оператора, середовища валідації, іменування версій і періодичність
title: Політика випусків
x-i18n:
generated_at: "2026-05-01T23:38:40Z"
generated_at: "2026-05-02T04:48:11Z"
model: gpt-5.5
provider: openai
source_hash: e915840070324f7614c993d20490f0bf4c9b266c57ce74eddfc461e019d3dc07
source_hash: 3ce380a8277e7c8764359e4ded86d1042dcb250691ac62fbee28651f20aa0580
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw має три публічні канали випусків:
OpenClaw має три публічні канали релізів:
- стабільний: теговані випуски, які типово публікуються в npm `beta`, або в npm `latest`, коли це явно запитано
- бета: передвипускні теги, які публікуються в npm `beta`
- стабільний: релізи з тегами, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, коли це явно запитано
- бета: передрелізні теги, які публікуються в npm `beta`
- розробницький: рухома вершина `main`
## Назви версій
- Версія стабільного випуску: `YYYY.M.D`
- Версія стабільного релізу: `YYYY.M.D`
- Git-тег: `vYYYY.M.D`
- Версія стабільного коригувального випуску: `YYYY.M.D-N`
- Версія стабільного коригувального релізу: `YYYY.M.D-N`
- Git-тег: `vYYYY.M.D-N`
- Версія бета-передвипуску: `YYYY.M.D-beta.N`
- Версія бета-передрелізу: `YYYY.M.D-beta.N`
- Git-тег: `vYYYY.M.D-beta.N`
- Не доповнюйте місяць або день нулями
- `latest` означає поточний просунутий стабільний npm-випуск
- Не додавайте початковий нуль до місяця або дня
- `latest` означає поточний просунутий стабільний npm-реліз
- `beta` означає поточну ціль встановлення бета-версії
- Стабільні та стабільні коригувальні випуски типово публікуються в npm `beta`; оператори випуску можуть явно націлитися на `latest` або просунути перевірену бета-збірку пізніше
- Кожен стабільний випуск OpenClaw постачає npm-пакет і застосунок macOS разом;
бета-випуски зазвичай спершу перевіряють і публікують шлях npm/package, а
збирання/підпис/нотаризацію застосунку mac залишають для стабільних випусків, якщо це явно не запитано
- Стабільні та стабільні коригувальні релізи за замовчуванням публікуються в npm `beta`; оператори релізу можуть явно націлитися на `latest` або пізніше просунути перевірену бета-збірку
- Кожен стабільний реліз OpenClaw постачається разом із npm-пакетом і застосунком macOS;
бета-релізи зазвичай спершу перевіряють і публікують шлях npm/пакета, а
збірку/підпис/нотаризацію застосунку Mac резервують для стабільного релізу, якщо це не запитано явно
## Періодичність випусків
## Частота релізів
- Випуски рухаються спершу через бета-канал
- Стабільний випуск іде лише після перевірки останньої бета-версії
- Супровідники зазвичай створюють випуски з гілки `release/YYYY.M.D`, створеної
з поточного `main`, щоб перевірка випуску та виправлення не блокували нову
- Релізи рухаються спершу через бета-канал
- Стабільний реліз виходить лише після перевірки останньої бета-версії
- Мейнтейнери зазвичай готують релізи з гілки `release/YYYY.M.D`, створеної
з поточного `main`, щоб валідація релізу та виправлення не блокували нову
розробку в `main`
- Якщо бета-тег уже надіслано або опубліковано й він потребує виправлення, супровідники створюють
наступний тег `-beta.N` замість видалення або повторного створення старого бета-тега
- Детальна процедура випуску, погодження, облікові дані та нотатки з відновлення
доступні лише супровідникам
- Якщо бета-тег уже надіслано або опубліковано і він потребує виправлення, мейнтейнери створюють
наступний тег `-beta.N` замість видалення чи повторного створення старого бета-тега
- Детальна процедура релізу, затвердження, облікові дані та нотатки з відновлення
доступні лише мейнтейнерам
## Контрольний список оператора випуску
## Контрольний список оператора релізу
Цей контрольний список показує публічну форму процесу випуску. Приватні облікові дані,
підписування, нотаризація, відновлення dist-tag і деталі аварійного відкотування залишаються в
посібнику з випуску лише для супровідників.
Цей контрольний список описує публічну форму релізного процесу. Приватні облікові дані,
підписування, нотаризація, відновлення dist-tag і деталі аварійного відкату залишаються в
релізному runbook лише для мейнтейнерів.
1. Почніть із поточного `main`: отримайте останні зміни, підтвердьте, що цільовий коміт надіслано,
і підтвердьте, що поточний CI `main` достатньо зелений, щоб створювати від нього гілку.
1. Почніть із поточного `main`: підтягніть останні зміни, підтвердьте, що цільовий коміт надіслано,
і підтвердьте, що поточний CI для `main` достатньо зелений, щоб відгалужуватися від нього.
2. Перепишіть верхній розділ `CHANGELOG.md` з реальної історії комітів за допомогою
`/changelog`, зберігайте записи орієнтованими на користувача, закомітьте його, надішліть його та виконайте rebase/pull
`/changelog`, залиште записи орієнтованими на користувачів, закомітьте його, надішліть і виконайте rebase/pull
ще раз перед створенням гілки.
3. Перегляньте записи сумісності випуску в
3. Перегляньте записи сумісності релізу в
`src/plugins/compat/registry.ts` і
`src/commands/doctor/shared/deprecation-compat.ts`. Видаляйте прострочену
сумісність лише тоді, коли шлях оновлення залишається покритим, або зафіксуйте, чому її
сумісність лише тоді, коли шлях оновлення лишається покритим, або зафіксуйте, чому її
навмисно збережено.
4. Створіть `release/YYYY.M.D` з поточного `main`; не виконуйте звичайну роботу над випуском
4. Створіть `release/YYYY.M.D` з поточного `main`; не виконуйте звичайну релізну роботу
безпосередньо в `main`.
5. Підвищте версію в кожному потрібному місці для запланованого тега, потім запустіть
локальну детерміновану попередню перевірку:
5. Збільште версію в кожному потрібному місці для запланованого тега, а потім запустіть
локальний детермінований preflight:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build` і `pnpm release:check`.
6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. До створення тега
для перевіркової попередньої перевірки дозволено повний 40-символьний SHA гілки випуску.
6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. До появи тега
для валідаційного preflight дозволено повний 40-символьний SHA релізної гілки.
Збережіть успішний `preflight_run_id`.
7. Запустіть усі передрелізні тести через `Full Release Validation` для
гілки випуску, тега або повного SHA коміту. Це єдина ручна точка входу
для чотирьох великих тестових середовищ випуску: Vitest, Docker, QA Lab і Package.
8. Якщо перевірка не пройшла, виправте в гілці випуску та повторно запустіть найменший невдалий
файл, канал, завдання workflow, профіль пакета, провайдера або allowlist моделі, що
доводить виправлення. Повторно запускайте повну парасолькову перевірку лише тоді, коли змінена поверхня робить
релізної гілки, тега або повного SHA коміту. Це єдина ручна точка входу
для чотирьох великих релізних тестових боксів: Vitest, Docker, QA Lab і Package.
8. Якщо валідація не пройшла, виправте в релізній гілці й повторно запустіть найменший невдалий
файл, канал, job workflow, профіль пакета, провайдера або allowlist моделі, що
доводить виправлення. Повторно запускайте повну парасольку лише тоді, коли змінена поверхня робить
попередні докази застарілими.
9. Для бета-версії поставте тег `vYYYY.M.D-beta.N`, опублікуйте з npm dist-tag `beta`, потім запустіть
приймальну перевірку пакета після публікації для опублікованого пакета `openclaw@YYYY.M.D-beta.N`
9. Для бета-версії створіть тег `vYYYY.M.D-beta.N`, опублікуйте з npm dist-tag `beta`, потім запустіть
post-publish package acceptance проти опублікованого пакета `openclaw@YYYY.M.D-beta.N`
або `openclaw@beta`. Якщо надіслана або опублікована бета-версія потребує виправлення, створіть
наступний `-beta.N`; не видаляйте й не переписуйте стару бета-версію.
10. Для стабільного випуску продовжуйте лише після того, як перевірена бета-версія або кандидат випуску матиме
потрібні докази перевірки. Публікація стабільного npm повторно використовує успішний
артефакт попередньої перевірки через `preflight_run_id`; готовність стабільного випуску macOS
також потребує запакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого
10. Для стабільного релізу продовжуйте лише після того, як перевірена бета-версія або release candidate матиме
потрібні докази валідації. Публікація стабільного npm-релізу повторно використовує успішний
preflight-артефакт через `preflight_run_id`; готовність стабільного релізу macOS
також вимагає упаковані `.zip`, `.dmg`, `.dSYM.zip` і оновлений
`appcast.xml` у `main`.
11. Після публікації запустіть верифікатор npm після публікації, необов’язковий самостійний
E2E Telegram для опублікованого npm, коли потрібен доказ каналу після публікації,
просування dist-tag за потреби, нотатки GitHub release/prerelease з
повного відповідного розділу `CHANGELOG.md` і кроки оголошення випуску.
11. Після публікації запустіть npm post-publish verifier, за потреби опційний автономний
published-npm Telegram E2E, коли потрібен доказ каналу після публікації,
просування dist-tag, коли потрібно, нотатки GitHub release/prerelease з
повного відповідного розділу `CHANGELOG.md` і кроки оголошення релізу.
## Попередня перевірка випуску
## Release preflight
- Запустіть `pnpm check:test-types` перед передрелізною перевіркою, щоб тестовий TypeScript залишався
покритим поза швидшим локальним шлюзом `pnpm check`
- Запустіть `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші перевірки циклів
імпорту та архітектурних меж були зеленими поза швидшим локальним шлюзом
імпортів і архітектурних меж були зеленими поза швидшим локальним шлюзом
- Запустіть `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані
релізні артефакти `dist/*` і пакет Control UI існували для кроку валідації
релізні артефакти `dist/*` і бандл Control UI існували для кроку валідації
пакування
- Запустіть ручний workflow `Full Release Validation` перед схваленням релізу, щоб
запустити всі передрелізні тестові бокси з однієї точки входу. Він приймає гілку,
тег або повний SHA коміту, запускає ручний `CI` і запускає
`OpenClaw Release Checks` для перевірки встановлення, приймання пакета, наборів
релізного шляху Docker, live/E2E, OpenWebUI, паритету QA Lab, Matrix і Telegram
lanes. З `release_profile=full` і `rerun_group=all` він також запускає пакетний
Telegram E2E для артефакту `release-package-under-test` з релізних перевірок.
`OpenClaw Release Checks` для інсталяційного smoke-тесту, приймання пакета, Docker
наборів release-path, live/E2E, OpenWebUI, паритету QA Lab, Matrix і Telegram
lane. З `release_profile=full` і `rerun_group=all` він також запускає package
Telegram E2E проти артефакту `release-package-under-test` із release checks.
Надайте `npm_telegram_package_spec` після публікації, коли той самий Telegram E2E
також має підтвердити опублікований npm-пакет. Надайте
має також підтвердити опублікований npm-пакет. Надайте
`evidence_package_spec`, коли приватний звіт доказів має підтвердити, що
валідація відповідає опублікованому npm-пакету без примусового Telegram E2E.
валідація відповідає опублікованому npm-пакету, без примусового запуску Telegram E2E.
Приклад:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Запустіть ручний workflow `Package Acceptance`, коли потрібен побічний доказ
- Запустіть ручний workflow `Package Acceptance`, коли потрібне побічне підтвердження
для кандидата пакета, поки релізна робота триває. Використовуйте `source=npm` для
`openclaw@beta`, `openclaw@latest` або точної версії релізу; `source=ref`,
щоб запакувати довірену гілку/тег/SHA `package_ref` з поточним harness
`openclaw@beta`, `openclaw@latest` або точної версії релізу; `source=ref`, щоб
запакувати довірену гілку/тег/SHA `package_ref` з поточним harness
`workflow_ref`; `source=url` для HTTPS tarball з обов’язковим SHA-256; або
`source=artifact` для tarball, завантаженого іншим запуском GitHub
Actions. Workflow розв’язує кандидата до
`package-under-test`, повторно використовує релізний планувальник Docker E2E для цього
tarball і може запускати Telegram QA для того самого tarball з
`telegram_mode=mock-openai` або `telegram_mode=live-frontier`. Коли
вибрані Docker lanes містять `published-upgrade-survivor`, артефакт пакета
є кандидатом, а `published_upgrade_survivor_baseline` вибирає
опублікований базовий рівень.
Actions. Workflow визначає кандидата як
`package-under-test`, повторно використовує Docker E2E release scheduler проти цього
tarball і може запускати Telegram QA проти того самого tarball з
`telegram_mode=mock-openai` або `telegram_mode=live-frontier`. Коли вибрані
Docker lanes містять `published-upgrade-survivor`, артефакт пакета є кандидатом, а
`published_upgrade_survivor_baseline` вибирає опубліковану базову версію.
Приклад: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
Поширені профілі:
- `smoke`: lanes встановлення/каналу/агента, мережі Gateway і перезавантаження конфігурації
- `package`: нативні для артефакту lanes пакета/оновлення/Plugin без OpenWebUI або live ClawHub
- `product`: профіль пакета плюс канали MCP, очищення cron/subagent,
Типові профілі:
- `smoke`: lane для install/channel/agent, gateway network і config reload
- `package`: lane для package/update/Plugin, нативні до артефакту, без OpenWebUI або live ClawHub
- `product`: профіль package плюс MCP channels, очищення cron/subagent,
вебпошук OpenAI і OpenWebUI
- `full`: фрагменти релізного шляху Docker з OpenWebUI
- `full`: частини Docker release-path з OpenWebUI
- `custom`: точний вибір `docker_lanes` для сфокусованого повторного запуску
- Запустіть ручний workflow `CI` напряму, коли потрібне лише повне звичайне покриття CI
для кандидата релізу. Ручні запуски CI обходять changed scoping і примусово запускають
Linux Node shards, bundled-plugin shards, контракти каналів,
сумісність Node 22, `check`, `check-additional`, перевірку збірки,
перевірки документації, Python Skills, Windows, macOS, Android і Control UI i18n
- Запустіть ручний workflow `CI` напряму, коли потрібне лише повне звичайне CI
покриття для release candidate. Ручні CI dispatch оминають changed
scoping і примусово запускають Linux Node shards, bundled-plugin shards, channel
contracts, сумісність Node 22, `check`, `check-additional`, build smoke,
перевірки документації, Python skills, Windows, macOS, Android і Control UI i18n
lanes.
Приклад: `gh workflow run ci.yml --ref release/YYYY.M.D`
- Запустіть `pnpm qa:otel:smoke` під час валідації релізної телеметрії. Він перевіряє
QA-lab через локальний приймач OTLP/HTTP і перевіряє експортовані назви trace
QA-lab через локальний OTLP/HTTP receiver і валідує експортовані назви trace
span, обмежені атрибути та редагування вмісту/ідентифікаторів без
потреби в Opik, Langfuse або іншому зовнішньому collector.
- Запускайте `pnpm release:check` перед кожним релізом із тегом
- Релізні перевірки тепер виконуються в окремому ручному workflow:
- Запускайте `pnpm release:check` перед кожним релізом з тегом
- Release checks тепер виконуються в окремому ручному workflow:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` також запускає mock parity gate QA Lab плюс швидкий
live-профіль Matrix і lane Telegram QA перед схваленням релізу. Live
lanes використовують середовище `qa-live-shared`; Telegram також використовує leases
облікових даних Convex CI. Запустіть ручний workflow `QA-Lab - All Lanes` з
- `OpenClaw Release Checks` також запускає QA Lab mock parity gate плюс швидкий
live Matrix profile і Telegram QA lane перед схваленням релізу. Live
lanes використовують середовище `qa-live-shared`; Telegram також використовує Convex CI
leases облікових даних. Запустіть ручний workflow `QA-Lab - All Lanes` з
`matrix_profile=all` і `matrix_shards=true`, коли потрібен повний інвентар Matrix
transport, media та E2EE паралельно.
- Крос-ОС валідація встановлення й оновлення runtime є частиною публічних
`OpenClaw Release Checks` і `Full Release Validation`, які викликають
transport, media і E2EE паралельно.
- Cross-OS інсталяційна та upgrade runtime валідація є частиною публічних
`OpenClaw Release Checks` і `Full Release Validation`, які напряму викликають
reusable workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml` напряму
- Це розділення навмисне: тримати реальний шлях npm-релізу коротким,
детермінованим і зосередженим на артефактах, тоді як повільніші live-перевірки залишаються у власній
lane, щоб вони не затримували й не блокували публікацію
- Релізні перевірки з секретами слід запускати через `Full Release
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- Цей поділ навмисний: тримайте реальний npm release path коротким,
детермінованим і сфокусованим на артефактах, тоді як повільніші live checks залишаються у своїй
окремій lane, щоб не затримувати й не блокувати публікацію
- Release checks із секретами слід запускати через `Full Release
Validation` або з workflow ref `main`/release, щоб логіка workflow і
секрети залишалися контрольованими
- `OpenClaw Release Checks` приймає гілку, тег або повний SHA коміту, якщо
розв’язаний коміт досяжний з гілки OpenClaw або релізного тегу
- Validation-only preflight `OpenClaw NPM Release` також приймає поточний
повний 40-символьний SHA коміту гілки workflow без вимоги запушеного тегу
- Цей шлях SHA є лише валідаційним і не може бути підвищений до реальної публікації
- У режимі SHA workflow синтезує `v<package.json version>` лише для перевірки
метаданих пакета; реальна публікація все одно потребує справжнього релізного тегу
- Обидва workflow тримають реальний шлях публікації та promotion на GitHub-hosted
визначений коміт доступний з гілки OpenClaw або релізного тегу
- validation-only preflight `OpenClaw NPM Release` також приймає поточний
повний 40-символьний SHA коміту workflow-гілки без вимоги до запушеного тегу
- Цей шлях SHA призначений лише для валідації й не може бути підвищений до реальної публікації
- У режимі SHA workflow синтезує `v<package.json version>` лише для
перевірки метаданих пакета; реальна публікація все ще потребує справжнього релізного тегу
- Обидва workflow залишають реальний шлях публікації та promotion на GitHub-hosted
runners, тоді як немутувальний шлях валідації може використовувати більші
Blacksmith Linux runners
- Цей workflow запускає
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
з використанням workflow secrets `OPENAI_API_KEY` і `ANTHROPIC_API_KEY`
- npm release preflight більше не чекає на окрему lane релізних перевірок
- npm release preflight більше не чекає на окрему release checks lane
- Запустіть `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(або відповідний beta/correction тег) перед схваленням
(або відповідний beta/correction tag) перед схваленням
- Після npm publish запустіть
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(або відповідну beta/correction версію), щоб перевірити шлях встановлення з опублікованого registry
(або відповідну beta/correction version), щоб перевірити шлях інсталяції з опублікованого registry
у свіжому тимчасовому prefix
- Після beta publish запустіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`,
щоб перевірити onboarding встановленого пакета, налаштування Telegram і реальний Telegram E2E
для опублікованого npm-пакета з використанням спільного пулу leased облікових даних Telegram.
Локальні одноразові запуски maintainers можуть опускати Convex vars і передавати три
- Після beta publish запустіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
для перевірки onboarding встановленого пакета, налаштування Telegram і реального Telegram E2E
проти опублікованого npm-пакета з використанням спільного leased pool облікових даних Telegram.
Локальні одноразові maintainer-запуски можуть пропустити Convex vars і передати три
env credentials `OPENCLAW_QA_TELEGRAM_*` напряму.
- Maintainers можуть запускати ту саму post-publish перевірку з GitHub Actions через
ручний workflow `NPM Telegram Beta E2E`. Він навмисно лише ручний і
не запускається на кожному merge.
- Автоматизація релізів maintainer тепер використовує preflight-then-promote:
- реальний npm publish має пройти успішний npm `preflight_run_id`
- реальний npm publish має бути запущений з тієї самої гілки `main` або
не запускається після кожного merge.
- Maintainer release automation тепер використовує preflight-then-promote:
- реальна npm publish має пройти успішний npm `preflight_run_id`
- реальна npm publish має запускатися з тієї самої гілки `main` або
`release/YYYY.M.D`, що й успішний preflight run
- стабільні npm-релізи за замовчуванням спрямовуються на `beta`
- стабільні npm releases за замовчуванням мають `beta`
- стабільний npm publish може явно націлюватися на `latest` через workflow input
- мутація npm dist-tag на основі токена тепер розміщена в
- token-based npm dist-tag mutation тепер живе в
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
для безпеки, бо `npm dist-tag add` досі потребує `NPM_TOKEN`, тоді як
публічний репозиторій зберігає OIDC-only publish
- публічний `macOS Release` є лише валідаційним; коли тег існує лише на
релізній гілці, але workflow запускається з `main`, встановіть
з міркувань безпеки, бо `npm dist-tag add` усе ще потребує `NPM_TOKEN`, тоді як
публічний repo зберігає OIDC-only publish
- публічний `macOS Release` є validation-only; коли тег існує лише на
release branch, але workflow запущено з `main`, задайте
`public_release_branch=release/YYYY.M.D`
- реальний приватний mac publish має пройти успішні приватні mac
- реальний private mac publish має пройти успішні private mac
`preflight_run_id` і `validate_run_id`
- реальні шляхи publish просувають підготовлені артефакти замість того, щоб збирати
їх знову
- реальні publish paths просувають підготовлені артефакти замість повторної
перебудови
- Для стабільних correction releases на кшталт `YYYY.M.D-N` post-publish verifier
також перевіряє той самий шлях оновлення temp-prefix з `YYYY.M.D` до `YYYY.M.D-N`,
щоб release corrections не могли непомітно залишити старіші глобальні встановлення на
базовому стабільному payload
- npm release preflight fails closed, якщо tarball не містить одночасно
також перевіряє той самий temp-prefix upgrade path з `YYYY.M.D` до `YYYY.M.D-N`,
щоб release corrections не могли непомітно залишити старіші global installs на
базовому stable payload
- npm release preflight завершується fail closed, якщо tarball не містить одночасно
`dist/control-ui/index.html` і непорожній payload `dist/control-ui/assets/`,
щоб ми знову не поставили порожній браузерний dashboard
- Post-publish verification також перевіряє, що опубліковані entrypoints Plugin і
щоб ми знову не відправили порожній browser dashboard
- Post-publish verification також перевіряє, що опубліковані Plugin entrypoints і
метадані пакета присутні в установленому registry layout. Реліз, який
постачає відсутні runtime payloads Plugin, провалює postpublish verifier і
не може бути promoted до `latest`.
- `pnpm test:install:smoke` також забезпечує бюджет npm pack `unpackedSize` для
candidate update tarball, тож installer e2e ловить випадкове роздуття пакета
до шляху release publish
- Якщо релізна робота торкалася планування CI, extension timing manifests або
extension test matrices, повторно згенеруйте й перегляньте planner-owned
candidate update tarball, тож installer e2e ловить випадкове pack bloat
до release publish path
- Якщо релізна робота торкалася CI planning, extension timing manifests або
extension test matrices, згенеруйте повторно й перегляньте planner-owned
matrix outputs `plugin-prerelease-extension-shard` з
`.github/workflows/plugin-prerelease.yml` перед схваленням, щоб release notes не
описували застарілий CI layout
- Готовність стабільного релізу macOS також включає поверхні оновлювача:
- GitHub release має врешті містити запаковані `.zip`, `.dmg` і `.dSYM.zip`
- `appcast.xml` на `main` має вказувати на новий стабільний zip після publish
- запакований app має зберігати non-debug bundle id, непорожню Sparkle feed
- Готовність стабільного macOS release також включає updater surfaces:
- GitHub release має зрештою містити запаковані `.zip`, `.dmg` і `.dSYM.zip`
- `appcast.xml` на `main` має вказувати на новий stable zip після publish
- запакований app має зберігати non-debug bundle id, непорожній Sparkle feed
URL і `CFBundleVersion` на рівні або вище канонічного Sparkle build floor
для цієї версії релізу
## Релізні тестові бокси
`Full Release Validation` — це спосіб, яким оператори запускають усі передрелізні тести з
однієї точки входу. Запускайте його з довіреного workflow ref `main` і передавайте релізну
гілку, тег або повний SHA коміту як `ref`:
однієї точки входу. Для підтвердження pinned commit на швидко змінюваній гілці використовуйте
helper, щоб кожен child workflow запускався з тимчасової гілки, зафіксованої на цільовому
SHA:
```bash
pnpm ci:full-release --sha <full-sha>
```
Helper пушить `release-ci/<sha>-...`, запускає `Full Release Validation`
з цієї гілки з `ref=<sha>`, перевіряє, що кожен child workflow `headSha`
відповідає цільовому, а потім видаляє тимчасову гілку. Це запобігає випадковому підтвердженню
новішого child run `main`.
Для валідації release branch або tag запустіть його з довіреного workflow
ref `main` і передайте release branch або tag як `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -254,34 +266,47 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
Workflow розв’язує target ref, запускає ручний `CI` з
Робочий процес визначає цільове посилання, запускає ручний `CI` з
`target_ref=<release-ref>`, запускає `OpenClaw Release Checks` і запускає
окремий пакетний Telegram E2E, коли `release_profile=full` з
`rerun_group=all` або коли задано `npm_telegram_package_spec`. `OpenClaw Release
Checks` далі розгалужується на перевірку встановлення, cross-OS release checks, live/E2E Docker
release-path coverage, Package Acceptance з Telegram package QA, паритет QA Lab,
live Matrix і live Telegram. Повний запуск прийнятний лише тоді, коли
summary `Full Release Validation`
показує `normal_ci` і `release_checks` як успішні. У режимі full/all
дочірній `npm_telegram` також має бути успішним; поза full/all його пропускають,
якщо не було надано опублікований `npm_telegram_package_spec`. Фінальний
verifier summary містить таблиці slowest-job для кожного дочірнього запуску, тож release
manager може бачити поточний critical path без завантаження логів.
Див. [Повна валідація релізу](/uk/reference/full-release-validation) для
повної матриці етапів, точних назв job workflow, відмінностей між stable і full profile,
артефактів і ручок для сфокусованого повторного запуску.
Дочірні workflow запускаються з довіреного ref, який запускає `Full Release
Validation`, зазвичай `--ref main`, навіть коли target `ref` вказує на
старішу релізну гілку або тег. Окремого input workflow-ref для Full Release Validation
немає; вибирайте довірений harness, вибираючи ref запуску workflow.
`rerun_group=all` або коли задано `npm_telegram_package_spec`. Потім `OpenClaw Release
Checks` розгортає перевірку встановлення, кросплатформні перевірки релізу,
live/E2E покриття релізного шляху Docker, Package Acceptance з QA пакета
Telegram, паритет QA Lab, live Matrix і live Telegram. Повний запуск прийнятний
лише тоді, коли зведення `Full Release Validation` показує `normal_ci` і
`release_checks` як успішні. У режимі full/all дочірній `npm_telegram` також має
бути успішним; поза full/all його пропускають, якщо не було надано опублікований
`npm_telegram_package_spec`. Фінальне зведення верифікатора містить таблиці
найповільніших завдань для кожного дочірнього запуску, щоб менеджер релізу міг
бачити поточний критичний шлях без завантаження логів.
Див. [Повну валідацію релізу](/uk/reference/full-release-validation), щоб отримати
повну матрицю етапів, точні назви завдань workflow, відмінності між stable і
full профілями, артефакти та цільові засоби повторного запуску.
Дочірні workflow запускаються з довіреного посилання, яке запускає `Full Release
Validation`, зазвичай `--ref main`, навіть коли цільове `ref` вказує на старішу
релізну гілку або тег. Окремого input для workflow-ref у Full Release Validation
немає; вибирайте довірену обв'язку, вибираючи ref запуску workflow.
Не використовуйте `--ref main -f ref=<sha>` для доказу точного коміту на рухомій
`main`; сирі SHA комітів не можуть бути refs для запуску workflow, тому
використовуйте `pnpm ci:full-release --sha <sha>`, щоб створити закріплену
тимчасову гілку.
Використовуйте `release_profile`, щоб вибрати ширину live/provider:
- `minimum`: найшвидший release-critical OpenAI/core live і Docker path
- `stable`: minimum плюс stable provider/backend coverage для схвалення релізу
- `full`: stable плюс broad advisory provider/media coverage
- `minimum`: найшвидший релізно-критичний OpenAI/core live і шлях Docker
- `stable`: minimum плюс stable покриття provider/backend для схвалення релізу
- `full`: stable плюс широке advisory покриття provider/media
`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз розв’язати цільове посилання як `release-package-under-test`, і повторно використовує цей артефакт як у Docker-перевірках release-path, так і в Package Acceptance. Це утримує всі package-facing бокси на тих самих байтах і уникає повторних збірок пакета. Cross-OS OpenAI install smoke використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли змінну repo/org задано, інакше `openai/gpt-5.5`, бо ця лінія доводить установлення пакета, onboarding, запуск Gateway і один live agent turn, а не бенчмарк найповільнішої стандартної моделі. Ширша матриця live provider залишається місцем для покриття, специфічного для моделей.
`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз
визначити цільовий ref як `release-package-under-test`, і повторно використовує
цей артефакт як у Docker-перевірках релізного шляху, так і в Package Acceptance.
Це тримає всі пакетно-орієнтовані бокси на тих самих байтах і уникає повторних
збірок пакета. Кросплатформна OpenAI перевірка встановлення використовує
`OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли задано змінну repo/org, інакше
`openai/gpt-5.5`, оскільки ця лінія доводить встановлення пакета, onboarding,
запуск Gateway і один live хід агента, а не бенчмарк найповільнішої стандартної
моделі. Ширша live матриця provider залишається місцем для model-specific
покриття.
Використовуйте ці варіанти залежно від етапу релізу:
@ -313,22 +338,45 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
Не використовуйте повну парасольку як перший повторний запуск після сфокусованого виправлення. Якщо один бокс падає, використайте невдалий дочірній workflow, job, Docker-лінію, профіль пакета, provider моделі або QA-лінію для наступного доказу. Запускайте повну парасольку знову лише тоді, коли виправлення змінило спільну оркестрацію релізу або зробило попередні докази з усіх боксів застарілими. Фінальний верифікатор парасольки повторно перевіряє записані ids запусків дочірніх workflow, тож після успішного повторного запуску дочірнього workflow повторно запустіть лише невдалий батьківський job `Verify full validation`.
Не використовуйте повну парасолькову перевірку як перший повторний запуск після
цільового виправлення. Якщо один бокс падає, для наступного доказу використайте
невдалий дочірній workflow, завдання, Docker-лінію, профіль пакета, model
provider або QA-лінію. Запускайте повну парасолькову перевірку знову лише тоді,
коли виправлення змінило спільну оркестрацію релізу або зробило попередні
докази all-box застарілими. Фінальний верифікатор парасольки повторно перевіряє
записані id запусків дочірніх workflow, тому після успішного повторного запуску
дочірнього workflow повторно запускайте лише невдале батьківське завдання
`Verify full validation`.
Для обмеженого відновлення передайте `rerun_group` до парасольки. `all` — це справжній запуск release-candidate, `ci` запускає лише звичайний дочірній CI, `plugin-prerelease` запускає лише release-only дочірній Plugin, `release-checks` запускає кожен релізний бокс, а вужчі релізні групи — це `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` і `npm-telegram`. Сфокусовані повторні запуски `npm-telegram` потребують `npm_telegram_package_spec`; повні/all запуски з `release_profile=full` використовують артефакт пакета release-checks.
Для обмеженого відновлення передайте `rerun_group` до парасольки. `all` є
справжнім запуском release-candidate, `ci` запускає лише звичайний дочірній CI,
`plugin-prerelease` запускає лише релізний дочірній Plugin, `release-checks`
запускає кожен релізний бокс, а вужчі релізні групи: `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` і `npm-telegram`.
Цільові повторні запуски `npm-telegram` потребують `npm_telegram_package_spec`;
full/all запуски з `release_profile=full` використовують артефакт пакета
release-checks.
### Vitest
Бокс Vitest — це ручний дочірній workflow `CI`. Ручний CI навмисно обходить changed scoping і примусово запускає звичайний граф тестів для release candidate: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS, Android і Control UI i18n.
Бокс Vitest є ручним дочірнім workflow `CI`. Ручний CI навмисно обходить
changed scoping і примусово запускає звичайний граф тестів для кандидата
релізу: Linux Node shards, shards bundled-plugin, контракти каналів,
сумісність Node 22, `check`, `check-additional`, build smoke, перевірки docs,
Python skills, Windows, macOS, Android і Control UI i18n.
Використовуйте цей бокс, щоб відповісти: «чи пройшло дерево вихідного коду повний звичайний набір тестів?» Це не те саме, що product validation на release-path. Докази, які потрібно зберегти:
Використовуйте цей бокс, щоб відповісти: «чи пройшло дерево вихідного коду
повний звичайний набір тестів?» Це не те саме, що продуктова валідація
релізного шляху. Докази, які слід зберігати:
- зведення `Full Release Validation`, що показує URL відправленого запуску `CI`
- зведення `Full Release Validation`, що показує URL запущеного `CI`
- зелений запуск `CI` на точному цільовому SHA
- назви невдалих або повільних shard із CI jobs під час розслідування регресій
- артефакти таймінгів Vitest, як-от `.artifacts/vitest-shard-timings.json`, коли запуск потребує аналізу продуктивності
- назви невдалих або повільних shards із завдань CI під час розслідування регресій
- артефакти таймінгів Vitest, як-от `.artifacts/vitest-shard-timings.json`, коли
запуск потребує аналізу продуктивності
Запускайте ручний CI напряму лише тоді, коли релізу потрібен детермінований звичайний CI, але не Docker, QA Lab, live, cross-OS або package бокси:
Запускайте ручний CI напряму лише тоді, коли релізу потрібен детермінований
звичайний CI, але не Docker, QA Lab, live, cross-OS або пакетні бокси:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -336,61 +384,113 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Бокс Docker живе в `OpenClaw Release Checks` через `openclaw-live-and-e2e-checks-reusable.yml`, плюс release-mode workflow `install-smoke`. Він перевіряє release candidate через запаковані Docker-середовища, а не лише тести на рівні вихідного коду.
Бокс Docker живе в `OpenClaw Release Checks` через
`openclaw-live-and-e2e-checks-reusable.yml`, а також у релізному workflow
`install-smoke`. Він валідує кандидата релізу через пакетовані середовища
Docker, а не лише тести рівня вихідного коду.
Покриття Release Docker включає:
Релізне Docker-покриття містить:
- повний install smoke із увімкненим повільним Bun global install smoke
- підготовку/повторне використання smoke image кореневого Dockerfile за цільовим SHA, з QR, root/gateway та installer/Bun smoke jobs, що запускаються як окремі install-smoke shards
- repository E2E lanes
- Docker chunks release-path: `core`, `package-update-openai`,
- повну перевірку встановлення з увімкненою повільною Bun global install smoke
- підготовку/повторне використання root Dockerfile smoke image за цільовим SHA,
із QR, root/gateway та installer/Bun smoke завданнями, що запускаються як
окремі install-smoke shards
- repository E2E лінії
- Docker chunks релізного шляху: `core`, `package-update-openai`,
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
`plugins-runtime-services`,
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
`plugins-runtime-install-c`, `plugins-runtime-install-d`,
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
`plugins-runtime-install-g` і `plugins-runtime-install-h`
- покриття OpenWebUI всередині chunk `plugins-runtime-services`, коли його запитано
- розділені лінії встановлення/видалення bundled plugin
`bundled-plugin-install-uninstall-0` до
- покриття OpenWebUI всередині chunk `plugins-runtime-services`, коли запитано
- розділені лінії встановлення/видалення bundled Plugin
`bundled-plugin-install-uninstall-0` через
`bundled-plugin-install-uninstall-23`
- live/E2E provider suites і Docker live model coverage, коли release checks
включають live suites
- live/E2E набори provider і Docker live model покриття, коли release checks
містять live suites
Використовуйте Docker-артефакти перед повторним запуском. Планувальник release-path завантажує `.artifacts/docker-tests/` з логами ліній, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника та командами повторного запуску. Для сфокусованого відновлення використовуйте `docker_lanes=<lane[,lane]>` у reusable live/E2E workflow замість повторного запуску всіх release chunks. Згенеровані команди повторного запуску включають попередні `package_artifact_run_id` і prepared Docker image inputs, коли доступні, тож невдала лінія може повторно використати той самий tarball і GHCR images.
Використовуйте артефакти Docker перед повторним запуском. Планувальник
релізного шляху завантажує `.artifacts/docker-tests/` із логами ліній,
`summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника та
командами повторного запуску. Для цільового відновлення використовуйте
`docker_lanes=<lane[,lane]>` у reusable live/E2E workflow замість повторного
запуску всіх релізних chunks. Згенеровані команди повторного запуску містять
попередній `package_artifact_run_id` і prepared Docker image inputs, коли вони
доступні, щоб невдала лінія могла повторно використати той самий tarball і
GHCR images.
### QA Lab
Бокс QA Lab також є частиною `OpenClaw Release Checks`. Це agentic behavior і channel-level release gate, окремий від Vitest і механіки Docker package.
Бокс QA Lab також є частиною `OpenClaw Release Checks`. Це релізний gate для
agentic поведінки та рівня каналів, окремий від Vitest і механіки пакетів
Docker.
Покриття Release QA Lab включає:
Релізне покриття QA Lab містить:
- mock parity gate, що порівнює OpenAI candidate lane з Opus 4.6 baseline за допомогою agentic parity pack
- швидкий live Matrix QA profile з використанням середовища `qa-live-shared`
- mock parity gate, що порівнює candidate lane OpenAI з baseline Opus 4.6 за
допомогою agentic parity pack
- fast live Matrix QA profile з використанням середовища `qa-live-shared`
- live Telegram QA lane з використанням Convex CI credential leases
- `pnpm qa:otel:smoke`, коли release telemetry потребує явного локального доказу
Використовуйте цей бокс, щоб відповісти: «чи поводиться реліз правильно у QA scenarios і live channel flows?» Зберігайте URL артефактів для parity, Matrix і Telegram lanes під час схвалення релізу. Повне покриття Matrix залишається доступним як ручний sharded QA-Lab run, а не стандартна release-critical lane.
Використовуйте цей бокс, щоб відповісти: «чи поводиться реліз правильно у QA
сценаріях і live channel flows?» Зберігайте URL артефактів для ліній parity,
Matrix і Telegram під час схвалення релізу. Повне покриття Matrix залишається
доступним як ручний sharded QA-Lab запуск, а не стандартна релізно-критична
лінія.
### Пакет
Бокс Package — це installable-product gate. Він підтримується `Package Acceptance` і resolver `scripts/resolve-openclaw-package-candidate.mjs`. Resolver нормалізує candidate у tarball `package-under-test`, який споживає Docker E2E, перевіряє package inventory, записує версію пакета і SHA-256 та тримає workflow harness ref окремо від package source ref.
Бокс Package є gate installable-product. Він підтримується `Package Acceptance`
і resolver `scripts/resolve-openclaw-package-candidate.mjs`. Resolver
нормалізує candidate у tarball `package-under-test`, який споживає Docker E2E,
валідує інвентар пакета, записує версію пакета та SHA-256 і тримає ref обв'язки
workflow окремо від ref джерела пакета.
Підтримувані джерела candidate:
- `source=npm`: `openclaw@beta`, `openclaw@latest` або точна версія релізу OpenClaw
- `source=ref`: pack довірену `package_ref` branch, tag або full commit SHA з вибраним `workflow_ref` harness
- `source=url`: download HTTPS `.tgz` з обов’язковим `package_sha256`
- `source=artifact`: повторно використати `.tgz`, завантажений іншим GitHub Actions run
- `source=ref`: запакувати довірену гілку `package_ref`, тег або повний SHA
коміту з вибраною обв'язкою `workflow_ref`
- `source=url`: завантажити HTTPS `.tgz` з обов'язковим `package_sha256`
- `source=artifact`: повторно використати `.tgz`, завантажений іншим запуском
GitHub Actions
`OpenClaw Release Checks` запускає Package Acceptance з `source=artifact`, підготовленим артефактом release package, `suite_profile=custom`, `docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Package Acceptance тримає migration, update, stale Plugin dependency cleanup, offline Plugin fixtures, Plugin update і Telegram package QA проти того самого розв’язаного tarball. Це GitHub-native заміна для більшості покриття package/update, яке раніше вимагало Parallels. Cross-OS release checks досі важливі для OS-specific onboarding, installer і platform behavior, але product validation package/update має віддавати перевагу Package Acceptance.
`OpenClaw Release Checks` запускає Package Acceptance з `source=artifact`,
підготовленим артефактом релізного пакета, `suite_profile=custom`,
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
`published_upgrade_survivor_baselines=release-history`,
`published_upgrade_survivor_scenarios=reported-issues` і
`telegram_mode=mock-openai`. Package Acceptance тримає migration, update,
очищення застарілих залежностей Plugin, offline Plugin fixtures, plugin update і
QA пакета Telegram на тому самому визначеному tarball. Це GitHub-native заміна
для більшості package/update покриття, яке раніше потребувало Parallels.
Кросплатформні release checks усе ще важливі для OS-specific onboarding,
installer і platform behavior, але продуктова валідація package/update має
віддавати перевагу Package Acceptance.
Канонічний checklist для update і Plugin validation —
[Тестування оновлень і Plugins](/uk/help/testing-updates-plugins). Використовуйте його, коли вирішуєте, яка local, Docker, Package Acceptance або release-check lane доводить plugin install/update, doctor cleanup або published-package migration change. Вичерпна published update migration з кожного stable пакета `2026.4.23+` — це окремий ручний workflow `Update Migration`, а не частина Full Release CI.
Канонічний checklist для валідації update і Plugin:
[Тестування оновлень і plugins](/uk/help/testing-updates-plugins). Використовуйте
його, коли вирішуєте, яка локальна, Docker, Package Acceptance або release-check
лінія доводить зміну встановлення/оновлення Plugin, doctor cleanup або
published-package migration. Вичерпна published update migration з кожного
stable пакета `2026.4.23+` є окремим ручним workflow `Update Migration`, а не
частиною Full Release CI.
Legacy package-acceptance leniency навмисно обмежена в часі. Пакети до `2026.4.25` можуть використовувати compatibility path для metadata gaps, уже опублікованих в npm: private QA inventory entries, відсутні в tarball, відсутній `gateway install --wrapper`, відсутні patch files у tarball-derived git fixture, відсутній збережений `update.channel`, legacy plugin install-record locations, відсутня marketplace install-record persistence і config metadata migration під час `plugins update`. Опублікований пакет `2026.4.26` може попереджати про local build metadata stamp files, які вже були відвантажені. Пізніші пакети мають відповідати сучасним package contracts; ті самі прогалини провалюють release validation.
Застаріла поблажливість package-acceptance навмисно обмежена в часі. Пакети до
`2026.4.25` включно можуть використовувати шлях сумісності для metadata gaps,
уже опублікованих до npm: приватні записи QA inventory, відсутні в tarball,
відсутній `gateway install --wrapper`, відсутні patch files у tarball-derived
git fixture, відсутній збережений `update.channel`, застарілі розташування
plugin install-record, відсутня persistence marketplace install-record і config
metadata migration під час `plugins update`. Опублікований пакет `2026.4.26`
може попереджати про local build metadata stamp files, які вже були shipped.
Пізніші пакети мають задовольняти сучасні package contracts; ті самі gaps
провалюють release validation.
Використовуйте ширші профілі Package Acceptance, коли релізне питання стосується фактичного installable package:
Використовуйте ширші профілі Package Acceptance, коли релізне питання стосується
реального installable package:
```bash
gh workflow run package-acceptance.yml \
@ -404,79 +504,85 @@ gh workflow run package-acceptance.yml \
Поширені package profiles:
- `smoke`: швидкі package install/channel/agent, gateway network і config reload lanes
- `package`: контракти install/update/plugin package без live ClawHub; це стандарт release-check
- `product`: `package` плюс MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI
- `full`: Docker release-path chunks з OpenWebUI
- `custom`: точний список `docker_lanes` для сфокусованих повторних запусків
- `smoke`: швидкі лінії package install/channel/agent, gateway network і config
reload
- `package`: контракти install/update/plugin package без live ClawHub; це стандарт
release-check
- `product`: `package` плюс MCP channels, cron/subagent cleanup, OpenAI web
search і OpenWebUI
- `full`: Docker chunks релізного шляху з OpenWebUI
- `custom`: точний список `docker_lanes` для цільових повторних запусків
Для package-candidate Telegram proof увімкніть `telegram_mode=mock-openai` або `telegram_mode=live-frontier` у Package Acceptance. Workflow передає розв’язаний tarball `package-under-test` у Telegram lane; standalone Telegram workflow досі приймає published npm spec для post-publish checks.
Для підтвердження Telegram кандидата пакета увімкніть `telegram_mode=mock-openai` або
`telegram_mode=live-frontier` у Package Acceptance. Workflow передає
визначений tarball `package-under-test` у лінію Telegram; окремий
workflow Telegram досі приймає опубліковану специфікацію npm для перевірок після публікації.
## Вхідні параметри NPM workflow
## Вхідні параметри workflow NPM
`OpenClaw NPM Release` приймає такі operator-controlled inputs:
`OpenClaw NPM Release` приймає такі вхідні параметри, керовані оператором:
- `tag`: обов’язковий release tag, як-от `v2026.4.2`, `v2026.4.2-1` або
- `tag`: обов’язковий тег релізу, як-от `v2026.4.2`, `v2026.4.2-1` або
`v2026.4.2-beta.1`; коли `preflight_only=true`, це також може бути поточний
повний 40-символьний workflow-branch commit SHA для validation-only preflight
- `preflight_only`: `true` для validation/build/package only, `false` для
справжнього publish path
- `preflight_run_id`: обов’язковий на справжньому publish path, щоб workflow повторно використовував
підготовлений tarball з успішного preflight run
- `npm_dist_tag`: цільовий npm tag для publish path; стандартно `beta`
повний 40-символьний SHA коміту гілки workflow для preflight лише з валідацією
- `preflight_only`: `true` лише для валідації/збірки/пакета, `false` для
реального шляху публікації
- `preflight_run_id`: обов’язковий у реальному шляху публікації, щоб workflow повторно використав
підготовлений tarball з успішного preflight-запуску
- `npm_dist_tag`: цільовий тег npm для шляху публікації; за замовчуванням `beta`
`OpenClaw Release Checks` приймає такі operator-controlled inputs:
`OpenClaw Release Checks` приймає такі вхідні параметри, керовані оператором:
- `ref`: branch, tag або full commit SHA для перевірки. Secret-bearing checks
потребують, щоб розв’язаний commit був reachable з OpenClaw branch або
release tag.
- `ref`: гілка, тег або повний SHA коміту для валідації. Перевірки, що використовують секрети,
вимагають, щоб визначений коміт був досяжний з гілки OpenClaw або
тега релізу.
Правила:
- Stable і correction tags можуть публікуватися або в `beta`, або в `latest`
- Beta prerelease tags можуть публікуватися лише в `beta`
- Для `OpenClaw NPM Release` вхідний full commit SHA дозволений лише коли
- Стабільні й корекційні теги можуть публікуватися або в `beta`, або в `latest`
- Теги prerelease beta можуть публікуватися лише в `beta`
- Для `OpenClaw NPM Release` введення повного SHA коміту дозволене лише коли
`preflight_only=true`
- `OpenClaw Release Checks` і `Full Release Validation` завжди є
validation-only
- Справжній publish path має використовувати той самий `npm_dist_tag`, що використовувався під час preflight;
workflow перевіряє, що metadata before publish продовжується
- `OpenClaw Release Checks` і `Full Release Validation` завжди виконують
лише валідацію
- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, що використовувався під час preflight;
workflow перевіряє ці метадані перед продовженням публікації
## Послідовність stable npm release
## Послідовність стабільного npm-релізу
Під час підготовки stable npm release:
Під час підготовки стабільного npm-релізу:
1. Запустіть `OpenClaw NPM Release` з `preflight_only=true`
- До появи тегу можна використати поточний повний SHA коміту гілки workflow
для пробного запуску workflow попередньої перевірки лише для валідації
2. Виберіть `npm_dist_tag=beta` для звичайного потоку спочатку `beta`, або `latest` лише
коли ви навмисно хочете виконати пряму стабільну публікацію
3. Запустіть `Full Release Validation` на гілці релізу, тегу релізу або повному
SHA коміту, коли вам потрібне звичайне CI разом із покриттям live prompt cache, Docker, QA Lab,
- Поки тег ще не існує, можна використати поточний повний SHA коміту гілки workflow
для пробного запуску preflight workflow лише з валідацією
2. Виберіть `npm_dist_tag=beta` для звичайного потоку спершу через beta або `latest` лише
тоді, коли навмисно потрібна пряма стабільна публікація
3. Запустіть `Full Release Validation` на гілці релізу, тезі релізу або повному
SHA коміту, коли потрібні звичайний CI плюс покриття live prompt cache, Docker, QA Lab,
Matrix і Telegram з одного ручного workflow
4. Якщо вам навмисно потрібен лише детермінований звичайний граф тестів, натомість запустіть
4. Якщо навмисно потрібен лише детермінований звичайний граф тестів, натомість запустіть
ручний workflow `CI` на ref релізу
5. Збережіть успішний `preflight_run_id`
6. Запустіть `OpenClaw NPM Release` ще раз із `preflight_only=false`, тим самим
6. Знову запустіть `OpenClaw NPM Release` з `preflight_only=false`, тим самим
`tag`, тим самим `npm_dist_tag` і збереженим `preflight_run_id`
7. Якщо реліз потрапив на `beta`, використайте приватний workflow
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
7. Якщо реліз потрапив у `beta`, використайте приватний
workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
щоб підвищити цю стабільну версію з `beta` до `latest`
8. Якщо реліз навмисно опубліковано безпосередньо в `latest`, а `beta`
має негайно відповідати тій самій стабільній збірці, використайте той самий приватний
8. Якщо реліз навмисно опубліковано безпосередньо в `latest` і `beta`
має одразу вказувати на ту саму стабільну збірку, використайте той самий приватний
workflow, щоб спрямувати обидва dist-tags на стабільну версію, або дозвольте його запланованій
самовідновлюваній синхронізації перемістити `beta` пізніше
самовідновлювальній синхронізації перемістити `beta` пізніше
Мутація dist-tag розташована в приватному репозиторії з міркувань безпеки, оскільки вона все ще
Зміна dist-tag розміщена в приватному репозиторії з міркувань безпеки, бо вона досі
потребує `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікацію лише через OIDC.
Це зберігає як шлях прямої публікації, так і шлях просування спочатку через beta
задокументованими й видимими для оператора.
Це робить і шлях прямої публікації, і шлях просування спершу через beta
задокументованими та видимими для оператора.
Якщо maintainer мусить повернутися до локальної автентифікації npm, запускайте будь-які команди 1Password
CLI (`op`) лише всередині окремої сесії tmux. Не викликайте `op`
безпосередньо з основної оболонки агента; утримання його всередині tmux робить prompts,
alerts і обробку OTP видимими та запобігає повторним alerts хоста.
Якщо супровідник мусить повернутися до локальної автентифікації npm, запускайте будь-які команди 1Password
CLI (`op`) лише всередині окремої tmux-сесії. Не викликайте `op`
безпосередньо з основної оболонки агента; утримання цього всередині tmux робить запити,
сповіщення та обробку OTP видимими й запобігає повторним сповіщенням хоста.
## Публічні посилання
@ -490,7 +596,7 @@ alerts і обробку OTP видимими та запобігає повто
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
Maintainers використовують приватну документацію релізів у
Супровідники використовують приватну документацію релізів у
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
для фактичного runbook.

77
docs/uk/tools/gemini-search.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Ви хочете використовувати Gemini для web_search
- Вам потрібен GEMINI_API_KEY
- Вам потрібне обґрунтування результатами Google Search
summary: Вебпошук Gemini з обґрунтуванням за допомогою Google Search
- Потрібен GEMINI_API_KEY або models.providers.google.apiKey
- Вам потрібне обґрунтування за допомогою Google Search
summary: Вебпошук Gemini із прив’язкою до Google Search
title: Пошук Gemini
x-i18n:
generated_at: "2026-05-02T04:05:01Z"
generated_at: "2026-05-02T04:48:28Z"
model: gpt-5.5
provider: openai
source_hash: e48b73a59f1af08cb1e30f149a18534dc76ba8dff26935d83fe8ccdaa8ab74e6
source_hash: 015d77fef123b1fd99d43eb6472bb8c672585328e17735d1fa0ead387cd2066a
source_path: tools/gemini-search.md
workflow: 16
---
OpenClaw підтримує моделі Gemini з вбудованим
[обґрунтуванням Google Search](https://ai.google.dev/gemini-api/docs/grounding),
яке повертає синтезовані ШІ відповіді, підкріплені актуальними результатами Google Search із
OpenClaw підтримує моделі Gemini з вбудованою
[прив’язкою до Google Search](https://ai.google.dev/gemini-api/docs/grounding),
яка повертає синтезовані ШІ відповіді на основі актуальних результатів Google Search із
цитуваннями.
## Отримання API-ключа
@ -27,7 +27,8 @@ OpenClaw підтримує моделі Gemini з вбудованим
API-ключ.
</Step>
<Step title="Збережіть ключ">
Установіть `GEMINI_API_KEY` в оточенні Gateway або налаштуйте через:
Задайте `GEMINI_API_KEY` у середовищі Gateway, повторно використайте
`models.providers.google.apiKey` або налаштуйте окремий ключ для вебпошуку через:
```bash
openclaw configure --section web
@ -45,8 +46,8 @@ OpenClaw підтримує моделі Gemini з вбудованим
google: {
config: {
webSearch: {
apiKey: "AIza...", // optional if GEMINI_API_KEY is set
baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional proxy/base URL override
apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set
baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional; falls back to models.providers.google.baseUrl
model: "gemini-2.5-flash", // default
},
},
@ -63,51 +64,57 @@ OpenClaw підтримує моделі Gemini з вбудованим
}
```
**Альтернатива через оточення:** установіть `GEMINI_API_KEY` в оточенні Gateway.
Для встановлення gateway помістіть його в `~/.openclaw/.env`.
**Пріоритет облікових даних:** вебпошук Gemini спочатку використовує
`plugins.entries.google.config.webSearch.apiKey`, потім `GEMINI_API_KEY`,
а тоді `models.providers.google.apiKey`. Для базових URL окреме значення
`plugins.entries.google.config.webSearch.baseUrl` має пріоритет перед
`models.providers.google.baseUrl`.
Для встановлення Gateway розмістіть ключі середовища в `~/.openclaw/.env`.
## Як це працює
На відміну від традиційних постачальників пошуку, які повертають список посилань і фрагментів,
Gemini використовує обґрунтування Google Search, щоб створювати синтезовані ШІ відповіді з
вбудованими цитуваннями. Результати містять як синтезовану відповідь, так і вихідні
URL-адреси.
На відміну від традиційних пошукових провайдерів, які повертають список посилань і фрагментів,
Gemini використовує прив’язку до Google Search, щоб створювати синтезовані ШІ відповіді з
вбудованими цитуваннями. Результати містять і синтезовану відповідь, і вихідні
URL.
- URL-адреси цитувань із обґрунтування Gemini автоматично перетворюються з URL-адрес
перенаправлення Google на прямі URL-адреси.
- Обробка перенаправлень використовує шлях захисту від SSRF (HEAD + перевірки перенаправлень +
перевірка http/https) перед поверненням фінальної URL-адреси цитування.
- Обробка перенаправлень використовує строгі стандартні налаштування SSRF, тому перенаправлення на
- URL цитувань із прив’язки Gemini автоматично перетворюються з URL
перенаправлення Google на прямі URL.
- Розв’язання перенаправлень використовує шлях захисту від SSRF (HEAD + перевірки перенаправлень +
перевірка http/https), перш ніж повернути фінальний URL цитування.
- Розв’язання перенаправлень використовує суворі стандартні налаштування SSRF, тому перенаправлення на
приватні/внутрішні цілі блокуються.
## Підтримувані параметри
Пошук Gemini підтримує `query`, `freshness`, `date_after` і `date_before`.
`count` приймається для сумісності зі спільним `web_search`, але обґрунтування Gemini
все одно повертає одну синтезовану відповідь із цитуваннями, а не список із N результатів.
`count` приймається для сумісності зі спільним `web_search`, але прив’язка Gemini
усе одно повертає одну синтезовану відповідь із цитуваннями, а не список із N результатів.
`freshness` приймає `day`, `week`, `month`, `year` і спільні скорочення
`pd`, `pw`, `pm` та `py`. OpenClaw перетворює ці значення або явний
діапазон `date_after`/`date_before` на `timeRangeFilter` обґрунтування
Gemini Google Search. `country`, `language` і `domain_filter` не підтримуються.
діапазон `date_after`/`date_before` на `timeRangeFilter` для прив’язки Gemini Google Search.
`country`, `language` і `domain_filter` не підтримуються.
## Вибір моделі
Стандартна модель — `gemini-2.5-flash` (швидка й економічно ефективна). Будь-яку модель Gemini,
що підтримує обґрунтування, можна використовувати через
Стандартна модель — `gemini-2.5-flash` (швидка та економічна). Будь-яку модель Gemini,
що підтримує прив’язку, можна використовувати через
`plugins.entries.google.config.webSearch.model`.
## Перевизначення базової URL-адреси
## Перевизначення базового URL
Установіть `plugins.entries.google.config.webSearch.baseUrl`, коли вебпошук Gemini
має проходити через операторський проксі або власну сумісну з Gemini кінцеву точку. Значення
`https://generativelanguage.googleapis.com` нормалізується до
`https://generativelanguage.googleapis.com/v1beta`; власні шляхи проксі залишаються
такими, як надано, після обрізання кінцевих скісних рисок.
Задайте `plugins.entries.google.config.webSearch.baseUrl`, коли вебпошук Gemini
має проходити через проксі оператора або користувацький Gemini-сумісний endpoint. Якщо
це значення не задано, вебпошук Gemini повторно використовує `models.providers.google.baseUrl`. Звичайне
значення `https://generativelanguage.googleapis.com` нормалізується до
`https://generativelanguage.googleapis.com/v1beta`; користувацькі шляхи проксі зберігаються
як надано після обрізання кінцевих скісних рисок.
## Пов’язане
- [Огляд вебпошуку](/uk/tools/web) -- усі постачальники та автовиявлення
- [Огляд вебпошуку](/uk/tools/web) -- усі провайдери й автоматичне виявлення
- [Brave Search](/uk/tools/brave-search) -- структуровані результати з фрагментами
- [Perplexity Search](/uk/tools/perplexity-search) -- структуровані результати + витягування вмісту

60
docs/uk/tools/minimax-search.md
View File

@ -1,29 +1,30 @@
---
read_when:
- Ви хочете використовувати MiniMax для web_search
- Вам потрібен ключ MiniMax Coding Plan
- Вам потрібні вказівки щодо хостів пошуку MiniMax CN/global
summary: MiniMax Search через API пошуку Coding Plan
- Потрібен ключ MiniMax Token Plan або токен OAuth
- Вам потрібні настанови щодо хоста пошуку MiniMax CN/global
summary: MiniMax Search через API пошуку Token Plan
title: Пошук MiniMax
x-i18n:
generated_at: "2026-04-23T21:16:12Z"
model: gpt-5.4
generated_at: "2026-05-02T04:48:36Z"
model: gpt-5.5
provider: openai
source_hash: 20a91bfae72661efd5e0bc3b6247ab05c3487db40ecd9cd5a874858bf3c69df3
source_hash: cf721a293d6b244e69d952f433bde83417eb907ef8c0b46d04a567f1b668a32e
source_path: tools/minimax-search.md
workflow: 15
workflow: 16
---
OpenClaw підтримує MiniMax як провайдера `web_search` через API пошуку MiniMax
Coding Plan. Він повертає структуровані результати пошуку із заголовками, URL,
snippets і related queries.
OpenClaw підтримує MiniMax як провайдера `web_search` через пошуковий API MiniMax
Token Plan. Він повертає структуровані результати пошуку з назвами, URL,
фрагментами та пов’язаними запитами.
## Отримайте ключ Coding Plan
## Отримайте облікові дані Token Plan
<Steps>
<Step title="Створіть ключ">
Створіть або скопіюйте ключ MiniMax Coding Plan з
Створіть або скопіюйте ключ MiniMax Token Plan із
[MiniMax Platform](https://platform.minimax.io/user-center/basic-information/interface-key).
Налаштування OAuth натомість можуть повторно використовувати `MINIMAX_OAUTH_TOKEN`.
</Step>
<Step title="Збережіть ключ">
Задайте `MINIMAX_CODE_PLAN_KEY` у середовищі Gateway або налаштуйте через:
@ -35,8 +36,9 @@ snippets і related queries.
</Step>
</Steps>
OpenClaw також приймає `MINIMAX_CODING_API_KEY` як alias env. `MINIMAX_API_KEY`
і далі читається як compatibility fallback, коли він уже вказує на токен coding-plan.
OpenClaw також приймає `MINIMAX_CODING_API_KEY` і `MINIMAX_OAUTH_TOKEN` як
псевдоніми змінних середовища. `MINIMAX_API_KEY` досі зчитується як резервний варіант сумісності, коли він
уже вказує на облікові дані token-plan.
## Конфігурація
@ -47,7 +49,7 @@ OpenClaw також приймає `MINIMAX_CODING_API_KEY` як alias env. `MIN
minimax: {
config: {
webSearch: {
apiKey: "sk-cp-...", // optional if MINIMAX_CODE_PLAN_KEY is set
apiKey: "sk-cp-...", // optional if a MiniMax Token Plan env var is set
region: "global", // or "cn"
},
},
@ -64,41 +66,43 @@ OpenClaw також приймає `MINIMAX_CODING_API_KEY` як alias env. `MIN
}
```
**Альтернатива через середовище:** задайте `MINIMAX_CODE_PLAN_KEY` у середовищі Gateway.
Для встановленого gateway помістіть його в `~/.openclaw/.env`.
**Альтернатива через середовище:** задайте `MINIMAX_CODE_PLAN_KEY` або `MINIMAX_OAUTH_TOKEN`
у середовищі Gateway.
Для встановлення Gateway помістіть його в `~/.openclaw/.env`.
## Вибір регіону
MiniMax Search використовує такі endpoint-и:
MiniMax Search використовує такі кінцеві точки:
- Global: `https://api.minimax.io/v1/coding_plan/search`
- Глобальний: `https://api.minimax.io/v1/coding_plan/search`
- CN: `https://api.minimaxi.com/v1/coding_plan/search`
Якщо `plugins.entries.minimax.config.webSearch.region` не задано, OpenClaw розв’язує
Якщо `plugins.entries.minimax.config.webSearch.region` не задано, OpenClaw визначає
регіон у такому порядку:
1. `tools.web.search.minimax.region` / `webSearch.region`, яким володіє plugin
1. `tools.web.search.minimax.region` / належний Plugin `webSearch.region`
2. `MINIMAX_API_HOST`
3. `models.providers.minimax.baseUrl`
4. `models.providers.minimax-portal.baseUrl`
Це означає, що onboarding CN або `MINIMAX_API_HOST=https://api.minimaxi.com/...`
автоматично утримує MiniMax Search також на хості CN.
Це означає, що налаштування CN або `MINIMAX_API_HOST=https://api.minimaxi.com/...`
автоматично також залишає MiniMax Search на хості CN.
Навіть якщо ви автентифікували MiniMax через шлях OAuth `minimax-portal`,
web search усе одно реєструється як provider id `minimax`; base URL OAuth-провайдера
використовується лише як підказка регіону для вибору хоста CN/global.
вебпошук усе одно реєструється з ідентифікатором провайдера `minimax`; базовий URL провайдера OAuth
використовується як підказка регіону для вибору хоста CN/global, а `MINIMAX_OAUTH_TOKEN`
може задовольнити облікові дані bearer для MiniMax Search.
## Підтримувані параметри
MiniMax Search підтримує:
- `query`
- `count` (OpenClaw обрізає повернений список результатів до запитаного count)
- `count` (OpenClaw обрізає повернений список результатів до запитаної кількості)
Фільтри, специфічні для провайдера, наразі не підтримуються.
## Пов’язане
- [Огляд Web Search](/uk/tools/web) -- усі провайдери й auto-detection
- [MiniMax](/uk/providers/minimax) -- налаштування моделей, image, speech і auth
- [Огляд вебпошуку](/uk/tools/web) -- усі провайдери й автоматичне виявлення
- [MiniMax](/uk/providers/minimax) -- налаштування моделі, зображень, мовлення й автентифікації

236
docs/uk/tools/web.md
View File

@ -1,51 +1,51 @@
---
read_when:
- Ви хочете ввімкнути або налаштувати web_search
- Ви хочете ввімкнути або налаштувати x_search
- Потрібно вибрати провайдера пошуку
- Ви хочете зрозуміти автоматичне виявлення та резервне перемикання провайдера
- Ви хочете увімкнути або налаштувати web_search
- Ви хочете увімкнути або налаштувати x_search
- Потрібно вибрати пошукового провайдера
- Ви хочете зрозуміти автоматичне виявлення та резервне перемикання провайдерів
sidebarTitle: Web Search
summary: web_search, x_search і web_fetch -- пошук в інтернеті, пошук дописів X або отримання вмісту сторінки
summary: web_search, x_search і web_fetch -- шукати в інтернеті, шукати дописи X або отримувати вміст сторінки
title: Пошук в інтернеті
x-i18n:
generated_at: "2026-05-02T04:05:02Z"
generated_at: "2026-05-02T04:49:14Z"
model: gpt-5.5
provider: openai
source_hash: 6112a067d6261dcad47a3a83c5185e6e492693b6df6a9d0bb2ca83d7ce2294cb
source_hash: 6200b148d750e1ed7205bd256ba6d33b4f6491577ba7544a684ffd11990ac274
source_path: tools/web.md
workflow: 16
---
Інструмент `web_search` шукає в інтернеті за допомогою налаштованого вами провайдера та
повертає результати. Результати кешуються за запитом на 15 хвилин (налаштовується).
повертає результати. Результати кешуються за запитом на 15 хвилин (можна налаштувати).
OpenClaw також включає `x_search` для дописів X (раніше Twitter) і
OpenClaw також містить `x_search` для дописів X (раніше Twitter) і
`web_fetch` для легкого отримання URL. На цьому етапі `web_fetch` залишається
локальним, тоді як `web_search` і `x_search` можуть використовувати xAI Responses під капотом.
локальним, тоді як `web_search` і `x_search` можуть внутрішньо використовувати xAI Responses.
<Info>
`web_search` — це легкий HTTP-інструмент, а не автоматизація браузера. Для
сайтів із великою кількістю JS або входів у систему використовуйте [Веббраузер](/uk/tools/browser). Для
отримання конкретного URL використовуйте [Web Fetch](/uk/tools/web-fetch).
сайтів, що активно використовують JS, або входу в обліковий запис використовуйте [Веббраузер](/uk/tools/browser). Для
отримання конкретної URL-адреси використовуйте [Web Fetch](/uk/tools/web-fetch).
</Info>
## Швидкий старт
<Steps>
<Step title="Виберіть провайдера">
Виберіть провайдера й виконайте всі потрібні кроки налаштування. Деякі провайдери
не потребують ключів, тоді як інші використовують API-ключі. Докладніше дивіться
Виберіть провайдера та виконайте всі потрібні налаштування. Деякі провайдери
не потребують ключів, тоді як інші використовують ключі API. Докладніше дивіться
на сторінках провайдерів нижче.
</Step>
<Step title="Налаштуйте">
```bash
openclaw configure --section web
```
Це збереже провайдера й будь-які потрібні облікові дані. Ви також можете задати env
var (наприклад `BRAVE_API_KEY`) і пропустити цей крок для провайдерів
на основі API.
Це зберігає провайдера та всі потрібні облікові дані. Ви також можете задати env
var (наприклад `BRAVE_API_KEY`) і пропустити цей крок для провайдерів,
що працюють через API.
</Step>
<Step title="Використовуйте">
<Step title="Використайте">
Тепер агент може викликати `web_search`:
```javascript
@ -65,74 +65,74 @@ OpenClaw також включає `x_search` для дописів X (рані
<CardGroup cols={2}>
<Card title="Brave Search" icon="shield" href="/uk/tools/brave-search">
Структуровані результати з фрагментами. Підтримує режим `llm-context`, фільтри країни/мови. Доступний безкоштовний рівень.
Структуровані результати з фрагментами. Підтримує режим `llm-context`, фільтри країни/мови. Доступний безкоштовний тариф.
</Card>
<Card title="DuckDuckGo" icon="bird" href="/uk/tools/duckduckgo-search">
Резервний варіант без ключа. API-ключ не потрібен. Неофіційна інтеграція на основі HTML.
Резервний варіант без ключа. Ключ API не потрібен. Неофіційна інтеграція на основі HTML.
</Card>
<Card title="Exa" icon="brain" href="/uk/tools/exa-search">
Нейронний + ключовий пошук із витягуванням вмісту (виділення, текст, підсумки).
</Card>
<Card title="Firecrawl" icon="flame" href="/uk/tools/firecrawl">
Структуровані результати. Найкраще використовувати разом із `firecrawl_search` і `firecrawl_scrape` для глибокого витягування.
Структуровані результати. Найкраще поєднувати з `firecrawl_search` і `firecrawl_scrape` для глибокого витягування.
</Card>
<Card title="Gemini" icon="sparkles" href="/uk/tools/gemini-search">
Синтезовані AI відповіді з цитуваннями через Google Search grounding.
Відповіді, синтезовані ШІ, з цитуваннями через прив’язку до Google Search.
</Card>
<Card title="Grok" icon="zap" href="/uk/tools/grok-search">
Синтезовані AI відповіді з цитуваннями через xAI web grounding.
Відповіді, синтезовані ШІ, з цитуваннями через вебприв’язку xAI.
</Card>
<Card title="Kimi" icon="moon" href="/uk/tools/kimi-search">
Синтезовані AI відповіді з цитуваннями через вебпошук Moonshot.
Відповіді, синтезовані ШІ, з цитуваннями через вебпошук Moonshot.
</Card>
<Card title="MiniMax Search" icon="globe" href="/uk/tools/minimax-search">
Структуровані результати через пошуковий API MiniMax Coding Plan.
Структуровані результати через пошуковий API MiniMax Token Plan.
</Card>
<Card title="Ollama Web Search" icon="globe" href="/uk/tools/ollama-search">
Пошук через локальний хост Ollama з виконаним входом або розміщений Ollama API.
</Card>
<Card title="Perplexity" icon="search" href="/uk/tools/perplexity-search">
Структуровані результати з елементами керування витягуванням вмісту та фільтрацією доменів.
Структуровані результати з керуванням витягуванням вмісту та фільтрацією доменів.
</Card>
<Card title="SearXNG" icon="server" href="/uk/tools/searxng-search">
Самостійно розгорнутий метапошук. API-ключ не потрібен. Агрегує Google, Bing, DuckDuckGo та інші.
Самостійно розгорнутий метапошук. Ключ API не потрібен. Агрегує Google, Bing, DuckDuckGo та інші.
</Card>
<Card title="Tavily" icon="globe" href="/uk/tools/tavily">
Структуровані результати з глибиною пошуку, фільтрацією тем і `tavily_extract` для витягування URL.
Структуровані результати з глибиною пошуку, фільтрацією за темою та `tavily_extract` для витягування URL.
</Card>
</CardGroup>
### Порівняння провайдерів
| Провайдер | Стиль результатів | Фільтри | API-ключ |
| ----------------------------------------- | -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- |
| [Brave](/uk/tools/brave-search) | Структуровані фрагменти | Країна, мова, час, режим `llm-context` | `BRAVE_API_KEY` |
| [DuckDuckGo](/uk/tools/duckduckgo-search) | Структуровані фрагменти | -- | Немає (без ключа) |
| [Exa](/uk/tools/exa-search) | Структуровані + витягнуті | Нейронний/ключовий режим, дата, витягування вмісту | `EXA_API_KEY` |
| [Firecrawl](/uk/tools/firecrawl) | Структуровані фрагменти | Через інструмент `firecrawl_search` | `FIRECRAWL_API_KEY` |
| [Gemini](/uk/tools/gemini-search) | Синтезовані AI + цитування | -- | `GEMINI_API_KEY` |
| [Grok](/uk/tools/grok-search) | Синтезовані AI + цитування | -- | `XAI_API_KEY` |
| [Kimi](/uk/tools/kimi-search) | Синтезовані AI + цитування | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [MiniMax Search](/uk/tools/minimax-search) | Структуровані фрагменти | Регіон (`global` / `cn`) | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` |
| [Ollama Web Search](/uk/tools/ollama-search) | Структуровані фрагменти | -- | Немає для локальних хостів із виконаним входом; `OLLAMA_API_KEY` для прямого пошуку `https://ollama.com` |
| [Perplexity](/uk/tools/perplexity-search) | Структуровані фрагменти | Країна, мова, час, домени, обмеження вмісту | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
| [SearXNG](/uk/tools/searxng-search) | Структуровані фрагменти | Категорії, мова | Немає (самостійно розгорнутий) |
| [Tavily](/uk/tools/tavily) | Структуровані фрагменти | Через інструмент `tavily_search` | `TAVILY_API_KEY` |
| Провайдер | Стиль результатів | Фільтри | Ключ API |
| ----------------------------------------- | -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| [Brave](/uk/tools/brave-search) | Структуровані фрагменти | Країна, мова, час, режим `llm-context` | `BRAVE_API_KEY` |
| [DuckDuckGo](/uk/tools/duckduckgo-search) | Структуровані фрагменти | -- | Немає (без ключа) |
| [Exa](/uk/tools/exa-search) | Структуровані + витягнуті | Нейронний/ключовий режим, дата, витягування вмісту | `EXA_API_KEY` |
| [Firecrawl](/uk/tools/firecrawl) | Структуровані фрагменти | Через інструмент `firecrawl_search` | `FIRECRAWL_API_KEY` |
| [Gemini](/uk/tools/gemini-search) | Синтезовано ШІ + цитування | -- | `GEMINI_API_KEY` |
| [Grok](/uk/tools/grok-search) | Синтезовано ШІ + цитування | -- | `XAI_API_KEY` |
| [Kimi](/uk/tools/kimi-search) | Синтезовано ШІ + цитування | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [MiniMax Search](/uk/tools/minimax-search) | Структуровані фрагменти | Регіон (`global` / `cn`) | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN` |
| [Ollama Web Search](/uk/tools/ollama-search) | Структуровані фрагменти | -- | Немає для локальних хостів із виконаним входом; `OLLAMA_API_KEY` для прямого пошуку `https://ollama.com` |
| [Perplexity](/uk/tools/perplexity-search) | Структуровані фрагменти | Країна, мова, час, домени, обмеження вмісту | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
| [SearXNG](/uk/tools/searxng-search) | Структуровані фрагменти | Категорії, мова | Немає (самостійно розгорнуто) |
| [Tavily](/uk/tools/tavily) | Структуровані фрагменти | Через інструмент `tavily_search` | `TAVILY_API_KEY` |
## Автовиявлення
## Нативний вебпошук OpenAI
Прямі моделі OpenAI Responses автоматично використовують розміщений OpenAI інструмент `web_search`, коли вебпошук OpenClaw увімкнено й не закріплено жодного керованого провайдера. Це поведінка, що належить провайдеру, у вбудованому Plugin OpenAI й застосовується лише до нативного трафіку OpenAI API, а не до OpenAI-сумісних проксі базових URL або маршрутів Azure. Установіть `tools.web.search.provider` на іншого провайдера, наприклад `brave`, щоб зберегти керований інструмент `web_search` для моделей OpenAI, або встановіть `tools.web.search.enabled: false`, щоб вимкнути і керований пошук, і нативний пошук OpenAI.
Прямі моделі OpenAI Responses автоматично використовують розміщений OpenAI інструмент `web_search`, коли вебпошук OpenClaw увімкнено й жоден керований провайдер не закріплено. Це поведінка, що належить провайдеру, у вбудованому Plugin OpenAI і застосовується лише до нативного трафіку OpenAI API, а не до OpenAI-сумісних проксі-базових URL чи маршрутів Azure. Установіть `tools.web.search.provider` на іншого провайдера, наприклад `brave`, щоб залишити керований інструмент `web_search` для моделей OpenAI, або встановіть `tools.web.search.enabled: false`, щоб вимкнути і керований пошук, і нативний пошук OpenAI.
## Нативний вебпошук Codex
Моделі з підтримкою Codex можуть за бажанням використовувати провайдер-нативний інструмент Responses `web_search` замість керованої функції OpenClaw `web_search`.
Моделі, сумісні з Codex, можуть за бажанням використовувати провайдерський нативний інструмент Responses `web_search` замість керованої функції OpenClaw `web_search`.
- Налаштуйте його в `tools.web.search.openaiCodex`
- Він активується лише для моделей із підтримкою Codex (`openai-codex/*` або провайдерів, що використовують `api: "openai-codex-responses"`)
- Керований `web_search` усе ще застосовується до моделей без Codex
- `mode: "cached"` — типове й рекомендоване налаштування
- Він активується лише для моделей, сумісних із Codex (`openai-codex/*` або провайдерів, що використовують `api: "openai-codex-responses"`)
- Керований `web_search` надалі застосовується до моделей не Codex
- `mode: "cached"` — стандартне та рекомендоване налаштування
- `tools.web.search.enabled: false` вимикає і керований, і нативний пошук
```json5
@ -158,21 +158,21 @@ OpenClaw також включає `x_search` для дописів X (рані
}
```
Якщо нативний пошук Codex увімкнено, але поточна модель не підтримує Codex, OpenClaw зберігає звичайну керовану поведінку `web_search`.
Якщо нативний пошук Codex увімкнено, але поточна модель не сумісна з Codex, OpenClaw зберігає звичайну керовану поведінку `web_search`.
## Налаштування вебпошуку
Списки провайдерів у документації та потоках налаштування впорядковані за абеткою. Автовиявлення зберігає
окремий порядок пріоритету.
Якщо `provider` не задано, OpenClaw перевіряє провайдерів у такому порядку й використовує
першого, який готовий:
Якщо `provider` не задано, OpenClaw перевіряє провайдерів у такому порядку та використовує
першого готового:
Спочатку провайдери на основі API:
Спершу провайдери, що працюють через API:
1. **Brave** -- `BRAVE_API_KEY` або `plugins.entries.brave.config.webSearch.apiKey` (порядок 10)
2. **MiniMax Search** -- `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` або `plugins.entries.minimax.config.webSearch.apiKey` (порядок 15)
3. **Gemini** -- `GEMINI_API_KEY` або `plugins.entries.google.config.webSearch.apiKey` (порядок 20)
2. **MiniMax Search** -- `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` / `MINIMAX_OAUTH_TOKEN` або `plugins.entries.minimax.config.webSearch.apiKey` (порядок 15)
3. **Gemini** -- `plugins.entries.google.config.webSearch.apiKey`, `GEMINI_API_KEY` або `models.providers.google.apiKey` (порядок 20)
4. **Grok** -- `XAI_API_KEY` або `plugins.entries.xai.config.webSearch.apiKey` (порядок 30)
5. **Kimi** -- `KIMI_API_KEY` / `MOONSHOT_API_KEY` або `plugins.entries.moonshot.config.webSearch.apiKey` (порядок 40)
6. **Perplexity** -- `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` або `plugins.entries.perplexity.config.webSearch.apiKey` (порядок 50)
@ -180,23 +180,23 @@ OpenClaw також включає `x_search` для дописів X (рані
8. **Exa** -- `EXA_API_KEY` або `plugins.entries.exa.config.webSearch.apiKey` (порядок 65)
9. **Tavily** -- `TAVILY_API_KEY` або `plugins.entries.tavily.config.webSearch.apiKey` (порядок 70)
Після цього резервні варіанти без ключів:
Після цього резервні варіанти без ключа:
10. **DuckDuckGo** -- резервний HTML-варіант без ключа, без облікового запису або API-ключа (порядок 100)
11. **Ollama Web Search** -- резервний варіант без ключа через ваш налаштований локальний хост Ollama, коли він доступний і виконано вхід за допомогою `ollama signin`; може повторно використовувати bearer-автентифікацію провайдера Ollama, коли хост її потребує, і може викликати прямий пошук `https://ollama.com`, коли налаштовано `OLLAMA_API_KEY` (порядок 110)
10. **DuckDuckGo** -- резервний HTML-варіант без ключа, без облікового запису чи ключа API (порядок 100)
11. **Ollama Web Search** -- резервний варіант без ключа через ваш налаштований локальний хост Ollama, коли він доступний і в ньому виконано `ollama signin`; може повторно використовувати bearer-автентифікацію провайдера Ollama, коли вона потрібна хосту, і може викликати прямий пошук `https://ollama.com`, коли налаштовано `OLLAMA_API_KEY` (порядок 110)
12. **SearXNG** -- `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl` (порядок 200)
Якщо провайдера не виявлено, використовується резервний Brave (ви отримаєте помилку про відсутній ключ
із підказкою налаштувати його).
Якщо жодного провайдера не виявлено, виконується резервний перехід до Brave (ви отримаєте помилку про відсутній ключ
із пропозицією його налаштувати).
<Note>
Усі поля ключів провайдерів підтримують об’єкти SecretRef. Plugin-обмежені SecretRefs
Усі поля ключів провайдерів підтримують об’єкти SecretRef. Plugin-обмежені SecretRef
у `plugins.entries.<plugin>.config.webSearch.apiKey` розв’язуються для
вбудованих провайдерів вебпошуку на основі API, зокрема Brave, Exa, Firecrawl,
вбудованих провайдерів вебпошуку, що працюють через API, зокрема Brave, Exa, Firecrawl,
Gemini, Grok, Kimi, MiniMax, Perplexity і Tavily,
незалежно від того, чи провайдера вибрано явно через `tools.web.search.provider`, чи
вибрано через автовиявлення. У режимі автовиявлення OpenClaw розв’язує лише
ключ вибраного провайдера -- невибрані SecretRefs залишаються неактивними, тож ви можете
незалежно від того, чи провайдера явно вибрано через `tools.web.search.provider`, чи
вибрано через автовиявлення. У режимі автовиявлення OpenClaw розв’язує лише ключ
вибраного провайдера -- невибрані SecretRef залишаються неактивними, тож ви можете
тримати кілька провайдерів налаштованими без витрат на розв’язання для тих,
які не використовуєте.
</Note>
@ -219,36 +219,34 @@ OpenClaw також включає `x_search` для дописів X (рані
}
```
Специфічна для провайдера конфігурація (API-ключі, базові URL, режими) розміщується в
`plugins.entries.<plugin>.config.webSearch.*`. Приклади дивіться на сторінках
провайдерів.
Конфігурація, специфічна для провайдера (ключі API, базові URL, режими), розміщується в
`plugins.entries.<plugin>.config.webSearch.*`. Gemini також може повторно використовувати
`models.providers.google.apiKey` і `models.providers.google.baseUrl` як резервні варіанти з нижчим пріоритетом
після своєї спеціальної конфігурації вебпошуку та `GEMINI_API_KEY`. Дивіться
приклади на сторінках провайдерів.
Вибір резервного провайдера `web_fetch` є окремим:
Вибір резервного провайдера `web_fetch` окремий:
- виберіть його за допомогою `tools.web.fetch.provider`
- або пропустіть це поле й дозвольте OpenClaw автовиявити першого готового провайдера
web-fetch із доступних облікових даних
- або пропустіть це поле й дозвольте OpenClaw автоматично виявити першого готового провайдера web-fetch
з доступних облікових даних
- `web_fetch` без пісочниці може використовувати встановлені провайдери Plugin, які оголошують
`contracts.webFetchProviders`; отримання в пісочниці залишається лише вбудованим
- сьогодні вбудований провайдер web-fetch — Firecrawl, налаштований у
- наразі вбудований провайдер web-fetch — Firecrawl, налаштований у
`plugins.entries.firecrawl.config.webFetch.*`
Коли ви вибираєте **Kimi** під час `openclaw onboard` або
`openclaw configure --section web`, OpenClaw також може запитати:
- регіон Moonshot API (`https://api.moonshot.ai/v1` або `https://api.moonshot.cn/v1`)
- типову модель вебпошуку Kimi (типово `kimi-k2.6`)
- стандартну модель вебпошуку Kimi (за замовчуванням `kimi-k2.6`)
Для `x_search` налаштуйте `plugins.entries.xai.config.xSearch.*`. Він використовує
той самий резервний `XAI_API_KEY`, що й вебпошук Grok.
Для `x_search` налаштуйте `plugins.entries.xai.config.xSearch.*`. Він використовує той самий fallback `XAI_API_KEY`, що й вебпошук Grok.
Застарілу конфігурацію `tools.web.x_search.*` автоматично мігрує `openclaw doctor --fix`.
Коли ви вибираєте Grok під час `openclaw onboard` або `openclaw configure --section web`,
OpenClaw також може запропонувати необов’язкове налаштування `x_search` із тим самим ключем.
Це окремий наступний крок у шляху Grok, а не окремий вибір провайдера
вебпошуку верхнього рівня. Якщо ви виберете іншого провайдера, OpenClaw не
показуватиме запит `x_search`.
Коли ви вибираєте Grok під час `openclaw onboard` або `openclaw configure --section web`, OpenClaw також може запропонувати необов’язкове налаштування `x_search` із тим самим ключем.
Це окремий наступний крок у межах шляху Grok, а не окремий вибір провайдера вебпошуку верхнього рівня. Якщо ви виберете іншого провайдера, OpenClaw не показуватиме запит `x_search`.
### Зберігання ключів API
### Зберігання API-ключів
<Tabs>
<Tab title="Файл конфігурації">
@ -272,67 +270,67 @@ OpenClaw також може запропонувати необов’язко
</Tab>
<Tab title="Змінна середовища">
Задайте змінну середовища провайдера в середовищі процесу Gateway:
Задайте env-змінну провайдера в середовищі процесу Gateway:
```bash
export BRAVE_API_KEY="YOUR_KEY"
```
Для встановлення Gateway помістіть її в `~/.openclaw/.env`.
Див. [Змінні середовища](/uk/help/faq#env-vars-and-env-loading).
Для встановлення gateway помістіть її в `~/.openclaw/.env`.
Див. [Env vars](/uk/help/faq#env-vars-and-env-loading).
</Tab>
</Tabs>
## Параметри інструмента
| Параметр | Опис |
| --------------------- | ----------------------------------------------------- |
| `query` | Пошуковий запит (обов’язково) |
| `count` | Результати для повернення (1–10, типово: 5) |
| `country` | 2-літерний код країни ISO (наприклад, "US", "DE") |
| `language` | Код мови ISO 639-1 (наприклад, "en", "de") |
| `search_lang` | Код мови пошуку (лише Brave) |
| `freshness` | Фільтр часу: `day`, `week`, `month` або `year` |
| `date_after` | Результати після цієї дати (YYYY-MM-DD) |
| `date_before` | Результати до цієї дати (YYYY-MM-DD) |
| `ui_lang` | Код мови UI (лише Brave) |
| `domain_filter` | Масив дозволених/заборонених доменів (лише Perplexity) |
| `max_tokens` | Загальний бюджет вмісту, типово 25000 (лише Perplexity) |
| `max_tokens_per_page` | Ліміт токенів на сторінку, типово 2048 (лише Perplexity) |
| Параметр | Опис |
| --------------------- | -------------------------------------------------------------- |
| `query` | Пошуковий запит (обов’язково) |
| `count` | Кількість результатів для повернення (1-10, типово: 5) |
| `country` | 2-літерний код країни ISO (наприклад, "US", "DE") |
| `language` | Код мови ISO 639-1 (наприклад, "en", "de") |
| `search_lang` | Код мови пошуку (лише Brave) |
| `freshness` | Фільтр часу: `day`, `week`, `month` або `year` |
| `date_after` | Результати після цієї дати (YYYY-MM-DD) |
| `date_before` | Результати до цієї дати (YYYY-MM-DD) |
| `ui_lang` | Код мови UI (лише Brave) |
| `domain_filter` | Масив allowlist/denylist доменів (лише Perplexity) |
| `max_tokens` | Загальний бюджет вмісту, типово 25000 (лише Perplexity) |
| `max_tokens_per_page` | Ліміт токенів на сторінку, типово 2048 (лише Perplexity) |
<Warning>
Не всі параметри працюють з усіма провайдерами. Режим Brave `llm-context`
відхиляє `ui_lang`; `date_before` також потребує `date_after`, бо власні
діапазони актуальності Brave вимагають і початкової, і кінцевої дат.
відхиляє `ui_lang`; `date_before` також потребує `date_after`, оскільки
користувацькі діапазони свіжості Brave вимагають і початкової, і кінцевої дат.
Gemini, Grok і Kimi повертають одну синтезовану відповідь із цитуваннями. Вони
приймають `count` для сумісності зі спільним інструментом, але це не змінює
форму обґрунтованої відповіді. Gemini підтримує `freshness`, `date_after` і
`date_before`, перетворюючи їх на часові діапазони обґрунтування Google Search.
`date_before`, перетворюючи їх на часові діапазони grounding Google Search.
Perplexity поводиться так само, коли ви використовуєте шлях сумісності
Sonar/OpenRouter (`plugins.entries.perplexity.config.webSearch.baseUrl` /
`model` або `OPENROUTER_API_KEY`).
SearXNG приймає `http://` лише для довірених хостів приватної мережі або local loopback;
SearXNG приймає `http://` лише для довірених приватних мережевих або loopback-хостів;
публічні кінцеві точки SearXNG мають використовувати `https://`.
Firecrawl і Tavily підтримують лише `query` і `count` через `web_search`
-- використовуйте їхні спеціалізовані інструменти для розширених параметрів.
-- використовуйте їхні спеціальні інструменти для розширених параметрів.
</Warning>
## x_search
`x_search` запитує дописи X (раніше Twitter) за допомогою xAI і повертає
`x_search` запитує дописи X (раніше Twitter) за допомогою xAI та повертає
синтезовані AI відповіді з цитуваннями. Він приймає запити природною мовою та
необов’язкові структуровані фільтри. OpenClaw вмикає вбудований інструмент xAI `x_search`
лише для запиту, який обслуговує цей виклик інструмента.
необов’язкові структуровані фільтри. OpenClaw вмикає вбудований інструмент xAI
`x_search` лише для запиту, який обслуговує цей виклик інструмента.
<Note>
xAI документує `x_search` як такий, що підтримує пошук за ключовими словами,
семантичний пошук, пошук користувачів і отримання тредів. Для статистики
взаємодії з окремим дописом, як-от репости, відповіді, закладки або перегляди,
надавайте перевагу цільовому пошуку за точною URL-адресою допису або ID статусу.
надавайте перевагу цільовому пошуку за точною URL-адресою допису або status ID.
Широкі пошуки за ключовими словами можуть знайти потрібний допис, але повернути
менш повні метадані окремого допису. Добрий шаблон: спершу знайдіть допис, потім
виконайте другий запит `x_search`, зосереджений на цьому точному дописі.
менш повні метадані для окремого допису. Хороший шаблон: спочатку знайти допис,
потім виконати другий запит `x_search`, сфокусований на цьому точному дописі.
</Note>
### Конфігурація x_search
@ -363,20 +361,20 @@ OpenClaw також може запропонувати необов’язко
}
```
`x_search` надсилає POST-запити до `<baseUrl>/responses`, коли
задано `plugins.entries.xai.config.xSearch.baseUrl`. Якщо це поле пропущено,
`x_search` надсилає POST на `<baseUrl>/responses`, коли встановлено
`plugins.entries.xai.config.xSearch.baseUrl`. Якщо це поле пропущено,
він повертається до `plugins.entries.xai.config.webSearch.baseUrl`, потім до
застарілого `tools.web.search.grok.baseUrl` і зрештою до публічної кінцевої точки xAI.
застарілого `tools.web.search.grok.baseUrl`, і нарешті до публічної кінцевої точки xAI.
### Параметри x_search
| Параметр | Опис |
| ---------------------------- | -------------------------------------------------------- |
| `query` | Пошуковий запит (обов’язково) |
| `allowed_x_handles` | Обмежити результати певними іменами користувачів X |
| `excluded_x_handles` | Виключити певні імена користувачів X |
| `from_date` | Включати лише дописи на цю дату або після неї (YYYY-MM-DD) |
| `to_date` | Включати лише дописи на цю дату або до неї (YYYY-MM-DD) |
| Параметр | Опис |
| ---------------------------- | ----------------------------------------------------------- |
| `query` | Пошуковий запит (обов’язково) |
| `allowed_x_handles` | Обмежити результати певними X handles |
| `excluded_x_handles` | Виключити певні X handles |
| `from_date` | Включати лише дописи на цю дату або після неї (YYYY-MM-DD) |
| `to_date` | Включати лише дописи на цю дату або до неї (YYYY-MM-DD) |
| `enable_image_understanding` | Дозволити xAI аналізувати зображення, прикріплені до відповідних дописів |
| `enable_video_understanding` | Дозволити xAI аналізувати відео, прикріплені до відповідних дописів |
@ -425,7 +423,7 @@ await web_search({
## Профілі інструментів
Якщо ви використовуєте профілі інструментів або списки дозволів, додайте `web_search`, `x_search` або `group:web`:
Якщо ви використовуєте профілі інструментів або allowlist, додайте `web_search`, `x_search` або `group:web`:
```json5
{
@ -439,6 +437,6 @@ await web_search({
## Пов’язане
- [Web Fetch](/uk/tools/web-fetch) -- отримати URL і витягти читабельний вміст
- [Web Browser](/uk/tools/browser) -- повна автоматизація браузера для сайтів із великою кількістю JS
- [Web Browser](/uk/tools/browser) -- повна автоматизація браузера для JS-heavy сайтів
- [Grok Search](/uk/tools/grok-search) -- Grok як провайдер `web_search`
- [Ollama Web Search](/uk/tools/ollama-search) -- вебпошук без ключа через ваш хост Ollama