chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
ff9b1e5bf0
commit
a85e6cae47
@ -7,15 +7,15 @@ sidebarTitle: Scheduled tasks
|
||||
summary: Заплановані завдання, Webhook-и та тригери Gmail PubSub для планувальника Gateway
|
||||
title: Заплановані завдання
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T01:19:13Z"
|
||||
generated_at: "2026-04-28T03:20:29Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c1a044f3d76acebec45e631b6b5c3bffc753543afd21f8e1a16326d1c50aa50b
|
||||
source_hash: df45c96f3e803ede8c4c2d24a9c3ae489967f052d0279235c17fef4759771dbb
|
||||
source_path: automation/cron-jobs.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у чат-канал або до кінцевої точки Webhook.
|
||||
Cron — це вбудований планувальник Gateway. Він зберігає завдання, пробуджує агента в потрібний час і може повертати результат назад у чат-канал або на кінцеву точку Webhook.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -44,41 +44,41 @@ 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`, але можуть трактувати завдання як нові, оскільки поля часу виконання тепер зберігаються в `jobs-state.json`.
|
||||
- Коли `jobs.json` редагується під час роботи або зупинки Gateway, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного слота часу виконання та очищає застарілі значення `nextRunAtMs`. Просте переформатування або переписування лише з іншим порядком ключів зберігає очікуваний слот.
|
||||
- Стан виконання під час роботи зберігається поруч у `~/.openclaw/cron/jobs-state.json`. Якщо ви відстежуєте визначення cron у git, відстежуйте `jobs.json`, а `jobs-state.json` додайте до gitignore.
|
||||
- Після цього розділення старіші версії OpenClaw можуть читати `jobs.json`, але можуть сприймати завдання як нові, оскільки поля стану виконання тепер зберігаються в `jobs-state.json`.
|
||||
- Коли `jobs.json` змінюється під час роботи Gateway або коли він зупинений, OpenClaw порівнює змінені поля розкладу з метаданими очікуваного слота виконання та очищає застарілі значення `nextRunAtMs`. Перезапис лише форматування або порядку ключів зберігає очікуваний слот.
|
||||
- Усі виконання cron створюють записи [фонових завдань](/uk/automation/tasks).
|
||||
- Одноразові завдання (`--at`) автоматично видаляються після успішного виконання за замовчуванням.
|
||||
- Ізольовані запуски cron в межах найкращого зусилля закривають відстежувані вкладки браузера/процеси для своєї сесії `cron:<jobId>` після завершення запуску, щоб відокремлена автоматизація браузера не залишала сирітські процеси.
|
||||
- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки), і жоден дочірній запуск субагента більше не відповідає за фінальну відповідь, OpenClaw один раз повторно формує запит для отримання фактичного результату перед доставкою.
|
||||
- Ізольовані запуски cron віддають перевагу структурованим метаданим відмови виконання з вбудованого запуску, а потім використовують відомі фінальні маркери підсумку/виводу, такі як `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, щоб заблокована команда не була позначена як успішний запуск.
|
||||
- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть коли відповідь не була згенерована, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збій замість позначення завдання як успішного.
|
||||
- Одноразові завдання (`--at`) за замовчуванням автоматично видаляються після успішного виконання.
|
||||
- Ізольовані запуски cron у межах best-effort закривають відстежувані вкладки браузера/процеси для їхньої сесії `cron:<jobId>` після завершення запуску, щоб відокремлена автоматизація браузера не залишала після себе осиротілі процеси.
|
||||
- Ізольовані запуски cron також захищаються від застарілих відповідей-підтверджень. Якщо перший результат — це лише проміжне оновлення статусу (`on it`, `pulling everything together` та подібні підказки) і жоден дочірній запуск subagent більше не відповідає за фінальну відповідь, OpenClaw один раз повторно надсилає запит для отримання фактичного результату перед доставленням.
|
||||
- Ізольовані запуски cron віддають перевагу структурованим метаданим відмови у виконанні з вбудованого запуску, а потім використовують відомі фінальні маркери підсумку/виводу, як-от `SYSTEM_RUN_DENIED` і `INVALID_REQUEST`, тож заблокована команда не позначається як успішний запуск.
|
||||
- Ізольовані запуски cron також трактують збої агента на рівні запуску як помилки завдання, навіть якщо payload відповіді не було створено, тому збої моделі/провайдера збільшують лічильники помилок і запускають сповіщення про збої, замість того щоб позначати завдання як успішне.
|
||||
|
||||
<a id="maintenance"></a>
|
||||
|
||||
<Note>
|
||||
Узгодження завдань для cron насамперед належить часу виконання, а вже потім спирається на довговічну історію: активне cron-завдання залишається активним, поки середовище виконання cron усе ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії ще існує. Щойно середовище виконання перестає володіти завданням і минає 5-хвилинне пільгове вікно, перевірки обслуговування аналізують збережені журнали запусків і стан завдання для відповідного запуску `cron:<jobId>:<startedAt>`. Якщо ця довговічна історія показує фінальний результат, журнал завдань фіналізується на її основі; інакше обслуговування, що належить Gateway, може позначити завдання як `lost`. Автономний аудит CLI може відновлювати стан з довговічної історії, але він не трактує власний порожній внутрішньопроцесний набір активних завдань як доказ того, що запуск cron, яким володіє Gateway, зник.
|
||||
Узгодження завдань для cron спочатку належить runtime, а вже потім спирається на стійку історію: активне cron-завдання залишається активним, поки runtime cron все ще відстежує це завдання як таке, що виконується, навіть якщо старий рядок дочірньої сесії все ще існує. Щойно runtime перестає володіти завданням і минає 5-хвилинне вікно пільгового часу, перевірки обслуговування аналізують збережені журнали запусків і стан завдання для відповідного запуску `cron:<jobId>:<startedAt>`. Якщо ця стійка історія показує термінальний результат, журнал завдань фіналізується на її основі; інакше обслуговування, яким володіє Gateway, може позначити завдання як `lost`. Офлайн-аудит CLI може відновитися зі стійкої історії, але він не трактує власний порожній набір активних завдань у процесі як доказ того, що запуск cron, яким володіє Gateway, зник.
|
||||
</Note>
|
||||
|
||||
## Типи розкладу
|
||||
|
||||
| Вид | Прапорець CLI | Опис |
|
||||
| ------- | ------------- | --------------------------------------------------------- |
|
||||
| `at` | `--at` | Одноразова часова мітка (ISO 8601 або відносна, як `20m`) |
|
||||
| `every` | `--every` | Фіксований інтервал |
|
||||
| `cron` | `--cron` | Cron-вираз із 5 або 6 полів з необов’язковим `--tz` |
|
||||
| Тип | Прапорець CLI | Опис |
|
||||
| ------- | ------------- | ------------------------------------------------------- |
|
||||
| `at` | `--at` | Одноразова позначка часу (ISO 8601 або відносна, як `20m`) |
|
||||
| `every` | `--every` | Фіксований інтервал |
|
||||
| `cron` | `--cron` | Вираз cron із 5 або 6 полів з необов’язковим `--tz` |
|
||||
|
||||
Часові мітки без часової зони трактуються як UTC. Додайте `--tz America/New_York` для планування за місцевим настінним часом.
|
||||
Позначки часу без часового поясу трактуються як UTC. Додайте `--tz America/New_York` для планування за локальним настінним часом.
|
||||
|
||||
Повторювані вирази на початок кожної години автоматично зсуваються до 5 хвилин, щоб зменшити пікове навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна.
|
||||
Періодичні вирази на початок кожної години автоматично зміщуються до 5 хвилин, щоб зменшити піки навантаження. Використовуйте `--exact`, щоб примусово задати точний час, або `--stagger 30s` для явного вікна.
|
||||
|
||||
### День місяця і день тижня використовують логіку OR
|
||||
### День місяця та день тижня використовують логіку OR
|
||||
|
||||
Cron-вирази розбираються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є шаблонами-джокерами, croner виконує збіг, коли **збігається будь-яке** з полів — а не обидва. Це стандартна поведінка Vixie cron.
|
||||
Вирази cron аналізуються за допомогою [croner](https://github.com/Hexagon/croner). Коли і поле дня місяця, і поле дня тижня не є wildcard, croner виконує збіг, коли **збігається будь-яке** з цих полів — а не обидва. Це стандартна поведінка cron у стилі Vixie.
|
||||
|
||||
```
|
||||
# Intended: "9 AM on the 15th, only if it's a Monday"
|
||||
@ -86,34 +86,34 @@ Cron-вирази розбираються за допомогою [croner](http
|
||||
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 | Нагадувань, системних подій |
|
||||
| Ізольований | `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`). Ці системні події не подовжують актуальність щоденного/неактивного скидання для цільової сесії. **Ізольовані** завдання виконують окремий хід агента з новою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу реалізовувати процеси на кшталт щоденних стендапів, які спираються на попередні підсумки.
|
||||
<Accordion title="Основна сесія vs ізольована vs користувацька">
|
||||
Завдання **основної сесії** ставлять у чергу системну подію та за потреби пробуджують Heartbeat (`--wake now` або `--wake next-heartbeat`). Ці системні події не подовжують актуальність щоденного/idle скидання для цільової сесії. **Ізольовані** завдання виконують окремий цикл агента зі свіжою сесією. **Користувацькі сесії** (`session:xxx`) зберігають контекст між запусками, що дає змогу будувати сценарії на кшталт щоденних стендапів, які спираються на попередні підсумки.
|
||||
</Accordion>
|
||||
<Accordion title="Що означає 'нова сесія' для ізольованих завдань">
|
||||
Для ізольованих завдань «нова сесія» означає новий ідентифікатор транскрипту/сесії для кожного запуску. OpenClaw може переносити безпечні вподобання, такі як налаштування thinking/fast/verbose, мітки та явні вибрані користувачем перевизначення моделі/автентифікації, але не успадковує фоновий контекст розмови зі старішого рядка cron: маршрутизацію каналу/групи, політику надсилання або черги, підвищення привілеїв, походження чи прив’язку часу виконання ACP. Використовуйте `current` або `session:<id>`, коли періодичне завдання має навмисно розвиватися в межах того самого контексту розмови.
|
||||
<Accordion title="Що означає 'свіжа сесія' для ізольованих завдань">
|
||||
Для ізольованих завдань "свіжа сесія" означає новий transcript/session id для кожного запуску. OpenClaw може переносити безпечні налаштування, як-от параметри thinking/fast/verbose, мітки та явно вибрані користувачем перевизначення model/auth, але не успадковує фоновий контекст розмови зі старого рядка cron: маршрутизацію каналу/групи, політику надсилання чи черги, підвищення привілеїв, походження або прив’язку runtime ACP. Використовуйте `current` або `session:<id>`, коли періодичне завдання має навмисно розвиватися в межах того самого контексту розмови.
|
||||
</Accordion>
|
||||
<Accordion title="Очищення під час виконання">
|
||||
Для ізольованих завдань завершення часу виконання тепер включає очищення браузера для цієї cron-сесії в межах найкращого зусилля. Помилки очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет.
|
||||
<Accordion title="Очищення runtime">
|
||||
Для ізольованих завдань завершення runtime тепер включає best-effort очищення браузера для цієї сесії cron. Збої очищення ігноруються, щоб фактичний результат cron усе одно мав пріоритет.
|
||||
|
||||
Ізольовані запуски cron також звільняють будь-які вбудовані екземпляри часу виконання MCP, створені для завдання, через спільний шлях очищення часу виконання. Це відповідає тому, як завершуються клієнти MCP для основної та користувацьких сесій, тому ізольовані cron-завдання не спричиняють витоки дочірніх stdio-процесів або довготривалих MCP-з’єднань між запусками.
|
||||
Ізольовані запуски cron також звільняють будь-які вбудовані екземпляри runtime MCP, створені для завдання, через спільний шлях очищення runtime. Це відповідає тому, як клієнти MCP для основної сесії та користувацької сесії завершуються, тому ізольовані cron-завдання не спричиняють витоки дочірніх stdio-процесів або довготривалих з’єднань MCP між запусками.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Доставка через субагента та Discord">
|
||||
Коли ізольовані запуски cron оркеструють субагентів, доставка також віддає перевагу фінальному виводу нащадка замість застарілого проміжного тексту батьківського запуску. Якщо нащадки все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість його оголошення.
|
||||
<Accordion title="Доставлення subagent і Discord">
|
||||
Коли ізольовані запуски cron оркеструють subagent-ів, доставлення також віддає перевагу фінальному виводу дочірнього елемента замість застарілого проміжного тексту батьківського. Якщо дочірні елементи все ще виконуються, OpenClaw пригнічує це часткове батьківське оновлення замість того, щоб оголошувати його.
|
||||
|
||||
Для цілей оголошення в Discord лише з текстом OpenClaw надсилає канонічний фінальний текст помічника один раз, замість повторного відтворення і потокового/проміжного текстового вмісту, і фінальної відповіді. Медіа та структуровані payload-и Discord, як і раніше, доставляються окремо, щоб не втратити вкладення та компоненти.
|
||||
Для цілей оголошення Discord лише з текстом OpenClaw надсилає канонічний фінальний текст помічника один раз, замість того щоб повторно відтворювати і streamed/intermediate text payloads, і фінальну відповідь. Медіа та структуровані payload-и Discord, як і раніше, доставляються окремими payload-ами, щоб не втрачати вкладення та компоненти.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -121,7 +121,7 @@ Cron-вирази розбираються за допомогою [croner](http
|
||||
### Параметри payload для ізольованих завдань
|
||||
|
||||
<ParamField path="--message" type="string" required>
|
||||
Текст prompt-а (обов’язковий для isolated).
|
||||
Текст prompt (обов’язковий для isolated).
|
||||
</ParamField>
|
||||
<ParamField path="--model" type="string">
|
||||
Перевизначення моделі; використовує вибрану дозволену модель для завдання.
|
||||
@ -130,50 +130,50 @@ Cron-вирази розбираються за допомогою [croner](http
|
||||
Перевизначення рівня thinking.
|
||||
</ParamField>
|
||||
<ParamField path="--light-context" type="boolean">
|
||||
Пропустити інʼєкцію bootstrap-файлів робочого простору.
|
||||
Пропустити ін’єкцію bootstrap-файлу робочого простору.
|
||||
</ParamField>
|
||||
<ParamField path="--tools" type="string">
|
||||
Обмежити набір інструментів, які може використовувати завдання, наприклад `--tools exec,read`.
|
||||
Обмежити, які інструменти може використовувати завдання, наприклад `--tools exec,read`.
|
||||
</ParamField>
|
||||
|
||||
`--model` використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення `/model` у чат-сесії: налаштовані ланцюжки резервних варіантів усе одно застосовуються, коли основна модель завдання завершується невдачею. Якщо запитана модель не дозволена, cron записує попередження в журнал і повертається до вибору моделі агента/моделі за замовчуванням для цього завдання.
|
||||
`--model` використовує вибрану дозволену модель як основну модель цього завдання. Це не те саме, що перевизначення `/model` для чат-сесії: налаштовані ланцюжки fallback, як і раніше, застосовуються, коли основна модель завдання зазнає збою. Якщо запитана модель не дозволена або її не вдається визначити, cron завершує запуск із явною помилкою валідації замість тихого fallback до моделі агента/моделі за замовчуванням для цього завдання.
|
||||
|
||||
Cron-завдання також можуть містити `fallbacks` на рівні payload. Якщо вони присутні, цей список замінює налаштований ланцюжок резервних варіантів для завдання. Використовуйте `fallbacks: []` у payload/API завдання, якщо вам потрібен строгий запуск cron, який пробує лише вибрану модель. Якщо в завдання є `--model`, але немає ні payload-, ні налаштованих fallback-ів, OpenClaw передає явне порожнє перевизначення fallback-ів, щоб основна модель агента не додавалася як прихована додаткова ціль повторної спроби.
|
||||
Cron-завдання також можуть містити `fallbacks` на рівні payload. Якщо вони присутні, цей список замінює налаштований ланцюжок fallback для завдання. Використовуйте `fallbacks: []` у payload/API завдання, коли хочете суворий запуск cron, який пробує лише вибрану модель. Якщо завдання має `--model`, але не має fallback-ів ні в payload, ні в конфігурації, OpenClaw передає явне порожнє перевизначення fallback, щоб primary агента не додавався як прихована додаткова ціль повторної спроби.
|
||||
|
||||
Пріоритет вибору моделі для ізольованих завдань такий:
|
||||
|
||||
1. Перевизначення моделі Gmail hook (коли запуск надійшов із Gmail і це перевизначення дозволене)
|
||||
2. `model` у payload конкретного завдання
|
||||
1. Перевизначення моделі з hook Gmail (коли запуск походить із Gmail і це перевизначення дозволене)
|
||||
2. `model` у payload окремого завдання
|
||||
3. Збережене перевизначення моделі сесії cron, вибране користувачем
|
||||
4. Вибір моделі агента/за замовчуванням
|
||||
|
||||
Fast mode також слідує за визначеним актуальним вибором. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron використовує його за замовчуванням. Збережене перевизначення сесії `fastMode` усе одно має пріоритет над конфігурацією в обох напрямках.
|
||||
Швидкий режим також дотримується визначеного активного вибору. Якщо конфігурація вибраної моделі має `params.fastMode`, ізольований cron за замовчуванням використовує це значення. Збережене в сесії перевизначення `fastMode` все одно має пріоритет над конфігурацією в будь-якому напрямку.
|
||||
|
||||
Якщо ізольований запуск натрапляє на живу передачу під час перемикання моделі, cron повторює спробу з перемкненим провайдером/моделлю та зберігає цей живий вибір для активного запуску перед повтором. Якщо перемикання також містить новий профіль автентифікації, cron теж зберігає це перевизначення профілю автентифікації для активного запуску. Кількість повторів обмежена: після початкової спроби плюс 2 повтори через перемикання cron припиняє роботу замість нескінченного циклу.
|
||||
Якщо ізольований запуск натрапляє на live model-switch handoff, cron виконує повторну спробу з перемкненим провайдером/моделлю та зберігає цей live selection для активного запуску перед повторною спробою. Коли перемикання також містить новий auth profile, cron також зберігає це перевизначення auth profile для активного запуску. Повторні спроби обмежені: після початкової спроби плюс 2 повторних спроб перемикання cron перериває виконання, а не зациклюється безкінечно.
|
||||
|
||||
Перш ніж ізольований запуск cron увійде в runner агента, OpenClaw перевіряє досяжні локальні кінцеві точки провайдерів для налаштованих провайдерів `api: "ollama"` і `api: "openai-completions"`, у яких `baseUrl` вказує на loopback, приватну мережу або `.local`. Якщо така кінцева точка недоступна, запуск записується як `skipped` із чіткою помилкою провайдера/моделі замість початку виклику моделі. Результат перевірки кінцевої точки кешується на 5 хвилин, тому багато прострочених завдань, що використовують той самий недоступний локальний сервер Ollama, vLLM, SGLang або LM Studio, спільно використовують одну невелику перевірку замість створення шторму запитів. Запуски, пропущені через попередню перевірку провайдера, не збільшують backoff для помилок виконання; увімкніть `failureAlert.includeSkipped`, якщо хочете отримувати повторні сповіщення про пропуски.
|
||||
Перш ніж ізольований запуск cron увійде в runner агента, OpenClaw перевіряє досяжні локальні кінцеві точки провайдерів для налаштованих провайдерів `api: "ollama"` і `api: "openai-completions"`, у яких `baseUrl` є loopback, приватною мережею або `.local`. Якщо ця кінцева точка недоступна, запуск записується як `skipped` із чіткою помилкою провайдера/моделі замість початку виклику моделі. Результат перевірки кінцевої точки кешується на 5 хвилин, тож багато завдань, строк виконання яких настав і які використовують той самий недоступний локальний сервер Ollama, vLLM, SGLang або LM Studio, спільно використовують одну невелику перевірку замість створення шторму запитів. Запуски, пропущені через попередню перевірку провайдера, не збільшують backoff помилок виконання; увімкніть `failureAlert.includeSkipped`, якщо хочете отримувати повторні сповіщення про пропуски.
|
||||
|
||||
## Доставка та вивід
|
||||
## Доставлення та вивід
|
||||
|
||||
| Режим | Що відбувається |
|
||||
| ---------- | ------------------------------------------------------------------- |
|
||||
| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент не надіслав його |
|
||||
| `announce` | Резервно доставляє фінальний текст до цілі, якщо агент його не надіслав |
|
||||
| `webhook` | Надсилає payload завершеної події методом POST на URL |
|
||||
| `none` | Без резервної доставки з боку runner |
|
||||
| `none` | Без резервного доставлення з runner |
|
||||
|
||||
Використовуйте `--announce --channel telegram --to "-1001234567890"` для доставки в канал. Для тем форуму Telegram використовуйте `-1001234567890:topic:123`; прямі RPC/конфігураційні виклики також можуть передавати `delivery.threadId` як рядок або число. Для цілей Slack/Discord/Mattermost слід використовувати явні префікси (`channel:<id>`, `user:<id>`). Ідентифікатори кімнат Matrix чутливі до регістру; використовуйте точний ідентифікатор кімнати або форму `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 ID або форму `room:!room:server` із Matrix.
|
||||
|
||||
Для ізольованих завдань доставка в чат є спільною. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення до налаштованої/поточної цілі, OpenClaw пропускає резервне оголошення. В інших випадках `announce`, `webhook` і `none` визначають лише те, що runner робить із фінальною відповіддю після ходу агента.
|
||||
Для ізольованих завдань доставлення в чат є спільним. Якщо маршрут чату доступний, агент може використовувати інструмент `message`, навіть коли завдання використовує `--no-deliver`. Якщо агент надсилає повідомлення на налаштовану/поточну ціль, OpenClaw пропускає резервне announce. Інакше `announce`, `webhook` і `none` керують лише тим, що runner робить із фінальною відповіддю після циклу агента.
|
||||
|
||||
Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену актуальну ціль доставки для резервного маршруту announce. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставки провайдерів не реконструюються з цих ключів, коли доступний контекст поточного чату.
|
||||
Коли агент створює ізольоване нагадування з активного чату, OpenClaw зберігає збережену активну ціль доставлення для резервного маршруту announce. Внутрішні ключі сесії можуть бути в нижньому регістрі; цілі доставлення провайдера не відтворюються з цих ключів, коли доступний контекст поточного чату.
|
||||
|
||||
Сповіщення про збої використовують окремий шлях призначення:
|
||||
Сповіщення про збої проходять окремим шляхом призначення:
|
||||
|
||||
- `cron.failureDestination` задає глобальне значення за замовчуванням для сповіщень про збої.
|
||||
- `job.delivery.failureDestination` перевизначає його для окремого завдання.
|
||||
- Якщо не задано жодного з них і завдання вже доставляє через `announce`, сповіщення про збої тепер резервно надсилаються до цієї основної цілі announce.
|
||||
- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо основний режим доставки не є `webhook`.
|
||||
- `failureAlert.includeSkipped: true` додає для завдання або глобальної політики сповіщень cron повторні сповіщення про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому не впливають на backoff помилок виконання.
|
||||
- `job.delivery.failureDestination` перевизначає це для окремого завдання.
|
||||
- Якщо не задано жодного з них і завдання вже доставляє через `announce`, сповіщення про збої тепер резервно надсилаються до цієї основної announce-цілі.
|
||||
- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо тільки основний режим доставлення не є `webhook`.
|
||||
- `failureAlert.includeSkipped: true` додає завдання або глобальну політику сповіщень cron до повторних сповіщень про пропущені запуски. Пропущені запуски ведуть окремий лічильник послідовних пропусків, тому вони не впливають на backoff помилок виконання.
|
||||
|
||||
## Приклади CLI
|
||||
|
||||
@ -218,7 +218,7 @@ Fast mode також слідує за визначеним актуальним
|
||||
|
||||
## Webhook-и
|
||||
|
||||
Gateway може надавати кінцеві точки HTTP Webhook для зовнішніх тригерів. Увімкніть у конфігурації:
|
||||
Gateway може надавати HTTP-кінцеві точки Webhook для зовнішніх тригерів. Увімкніть у конфігурації:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -237,11 +237,11 @@ Gateway може надавати кінцеві точки HTTP Webhook для
|
||||
- `Authorization: Bearer <token>` (рекомендовано)
|
||||
- `x-openclaw-token: <token>`
|
||||
|
||||
Токени в рядку запиту відхиляються.
|
||||
Токени в query-string відхиляються.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="POST /hooks/wake">
|
||||
Додає системну подію до черги для основної сесії:
|
||||
Поставити системну подію в чергу для основної сесії:
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:18789/hooks/wake \
|
||||
@ -259,7 +259,7 @@ Gateway може надавати кінцеві точки HTTP Webhook для
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="POST /hooks/agent">
|
||||
Запускає ізольований хід агента:
|
||||
Запустити ізольований цикл агента:
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:18789/hooks/agent \
|
||||
@ -268,31 +268,31 @@ Gateway може надавати кінцеві точки HTTP Webhook для
|
||||
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
|
||||
```
|
||||
|
||||
Поля: `message` (обов’язкове), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `fallbacks`, `thinking`, `timeoutSeconds`.
|
||||
Поля: `message` (обов’язково), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `fallbacks`, `thinking`, `timeoutSeconds`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Зіставлені hooks (POST /hooks/<name>)">
|
||||
Користувацькі назви hook розв’язуються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload-и на дії `wake` або `agent` за допомогою шаблонів або перетворень коду.
|
||||
Користувацькі назви hook-ів визначаються через `hooks.mappings` у конфігурації. Зіставлення можуть перетворювати довільні payload-и на дії `wake` або `agent` за допомогою шаблонів або перетворень коду.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Warning>
|
||||
Тримайте кінцеві точки hook за loopback, tailnet або довіреним reverse proxy.
|
||||
Тримайте кінцеві точки hook-ів за loopback, tailnet або довіреним reverse proxy.
|
||||
|
||||
- Використовуйте окремий токен hook; не використовуйте повторно токени автентифікації gateway.
|
||||
- Тримайте `hooks.path` на окремому підшляху; `/` відхиляється.
|
||||
- Установіть `hooks.allowedAgentIds`, щоб обмежити явну маршрутизацію `agentId`.
|
||||
- Залишайте `hooks.allowRequestSessionKey=false`, якщо вам не потрібні сесії, вибрані викликачем.
|
||||
- Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити дозволені форми ключів сесії.
|
||||
- Payload-и hook за замовчуванням обгортаються межами безпеки.
|
||||
- Якщо ви вмикаєте `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.
|
||||
**Необхідні умови:** CLI `gcloud`, `gog` (gogcli), увімкнені hooks OpenClaw, Tailscale для публічної HTTPS-кінцевої точки.
|
||||
</Note>
|
||||
|
||||
### Налаштування через майстер (рекомендовано)
|
||||
@ -307,7 +307,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com
|
||||
|
||||
Коли `hooks.enabled=true` і задано `hooks.gmail.account`, Gateway запускає `gog gmail watch serve` під час завантаження та автоматично поновлює watch. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб відмовитися.
|
||||
|
||||
### Одноразове ручне налаштування
|
||||
### Ручне одноразове налаштування
|
||||
|
||||
<Steps>
|
||||
<Step title="Виберіть проєкт GCP">
|
||||
@ -320,7 +320,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Створіть topic і надайте Gmail доступ до push">
|
||||
<Step title="Створіть topic і надайте Gmail доступ для push">
|
||||
```bash
|
||||
gcloud pubsub topics create gog-gmail-watch
|
||||
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
|
||||
@ -384,11 +384,11 @@ openclaw cron edit <jobId> --clear-agent
|
||||
Примітка щодо перевизначення моделі:
|
||||
|
||||
- `openclaw cron add|edit --model ...` змінює вибрану модель завдання.
|
||||
- Якщо модель дозволена, саме ця пара провайдер/модель потрапляє до ізольованого запуску агента.
|
||||
- Якщо вона не дозволена, cron показує попередження і повертається до вибору моделі агента/моделі за замовчуванням для цього завдання.
|
||||
- Налаштовані ланцюжки резервних варіантів усе одно застосовуються, оскільки `--model` у cron — це основна модель завдання, а не перевизначення `/model` сесії.
|
||||
- `fallbacks` у payload замінює налаштовані fallback-и для цього завдання; `fallbacks: []` вимикає fallback і робить запуск строгим.
|
||||
- Звичайний `--model` без явного або налаштованого списку fallback-ів не переходить до основної моделі агента як до тихої додаткової цілі повторної спроби.
|
||||
- Якщо модель дозволена, саме ця комбінація провайдера/моделі потрапляє в ізольований запуск агента.
|
||||
- Якщо вона не дозволена або її не вдається визначити, cron завершує запуск із явною помилкою валідації.
|
||||
- Налаштовані ланцюжки fallback, як і раніше, застосовуються, тому що cron `--model` — це primary завдання, а не перевизначення `/model` для сесії.
|
||||
- `fallbacks` у payload замінює налаштовані fallback-и для цього завдання; `fallbacks: []` вимикає fallback і робить запуск суворим.
|
||||
- Звичайний `--model` без явного або налаштованого списку fallback не переходить до primary агента як до прихованої додаткової цілі повторної спроби.
|
||||
</Note>
|
||||
|
||||
## Конфігурація
|
||||
@ -411,29 +411,29 @@ openclaw cron edit <jobId> --clear-agent
|
||||
}
|
||||
```
|
||||
|
||||
`maxConcurrentRuns` обмежує як запланований dispatch cron, так і виконання ізольованих ходів агента. Ізольовані ходи агента cron внутрішньо використовують виділену чергу виконання `cron-nested`, тому збільшення цього значення дозволяє незалежним LLM-запускам cron просуватися паралельно, а не лише запускати їхні зовнішні оболонки cron. Спільна lane `nested`, що не належить cron, цим параметром не розширюється.
|
||||
`maxConcurrentRuns` обмежує як заплановане диспетчеризування cron, так і виконання ізольованих циклів агента. Ізольовані цикли агента cron внутрішньо використовують окрему смугу виконання черги `cron-nested`, тому збільшення цього значення дає змогу незалежним LLM-запускам cron просуватися паралельно, а не лише запускати їхні зовнішні обгортки cron. Спільна не-cron смуга `nested` цим параметром не розширюється.
|
||||
|
||||
Sidecar стану часу виконання виводиться з `cron.store`: сховище `.json`, таке як `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, тоді як до шляху сховища без суфікса `.json` додається `-state.json`.
|
||||
Побічний файл стану runtime виводиться з `cron.store`: сховище `.json`, таке як `~/clawd/cron/jobs.json`, використовує `~/clawd/cron/jobs-state.json`, а шлях сховища без суфікса `.json` отримує доданий суфікс `-state.json`.
|
||||
|
||||
Якщо ви вручну редагуєте `jobs.json`, не включайте `jobs-state.json` до системи контролю версій. OpenClaw використовує цей sidecar для очікуваних слотів, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка повідомляє планувальнику, коли завдання, відредаговане зовні, потребує нового `nextRunAtMs`.
|
||||
Якщо ви редагуєте `jobs.json` вручну, не додавайте `jobs-state.json` до контролю версій. OpenClaw використовує цей побічний файл для очікуваних слотів, активних маркерів, метаданих останнього запуску та ідентичності розкладу, яка повідомляє планувальнику, коли завданню, відредагованому зовні, потрібен свіжий `nextRunAtMs`.
|
||||
|
||||
Вимкнути cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`.
|
||||
Вимкнення cron: `cron.enabled: false` або `OPENCLAW_SKIP_CRON=1`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Поведінка повторних спроб">
|
||||
**Повтор одноразового завдання**: тимчасові помилки (ліміт швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки одразу вимикають завдання.
|
||||
**Повторна спроба одноразового завдання**: тимчасові помилки (обмеження швидкості, перевантаження, мережа, помилка сервера) повторюються до 3 разів з експоненційним backoff. Постійні помилки вимикаються негайно.
|
||||
|
||||
**Повтор періодичного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Після наступного успішного запуску backoff скидається.
|
||||
**Повторна спроба періодичного завдання**: експоненційний backoff (від 30 с до 60 хв) між повторними спробами. Backoff скидається після наступного успішного запуску.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Обслуговування">
|
||||
`cron.sessionRetention` (за замовчуванням `24h`) очищає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично очищають файли журналів запусків.
|
||||
`cron.sessionRetention` (типово `24h`) обрізає записи сесій ізольованих запусків. `cron.runLog.maxBytes` / `cron.runLog.keepLines` автоматично обрізають файли журналів запуску.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Усунення неполадок
|
||||
## Усунення несправностей
|
||||
|
||||
### Послідовність команд
|
||||
### Ланцюжок команд
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -449,22 +449,22 @@ openclaw doctor
|
||||
<AccordionGroup>
|
||||
<Accordion title="Cron не спрацьовує">
|
||||
- Перевірте `cron.enabled` і змінну середовища `OPENCLAW_SKIP_CRON`.
|
||||
- Підтвердьте, що Gateway працює безперервно.
|
||||
- Для розкладів `cron` перевірте часовий пояс (`--tz`) порівняно з часовим поясом хоста.
|
||||
- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено за допомогою `openclaw cron run <jobId> --due`, і час виконання завдання ще не настав.
|
||||
- Переконайтеся, що Gateway працює безперервно.
|
||||
- Для розкладів `cron` перевірте часовий пояс (`--tz`) відносно часового поясу хоста.
|
||||
- `reason: not-due` у виводі запуску означає, що ручний запуск було перевірено через `openclaw cron run <jobId> --due`, і час виконання завдання ще не настав.
|
||||
</Accordion>
|
||||
<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 пригнічує пряме вихідне надсилання, а також резервний шлях постановки підсумку в чергу, тому назад у чат нічого не публікується.
|
||||
- Якщо агент має сам написати користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль).
|
||||
<Accordion title="Cron спрацював, але доставлення немає">
|
||||
- Режим доставлення `none` означає, що резервне надсилання з runner не очікується. Агент усе ще може надсилати напряму за допомогою інструмента `message`, коли доступний маршрут чату.
|
||||
- Відсутня/недійсна ціль доставлення (`channel`/`to`) означає, що вихідне надсилання було пропущено.
|
||||
- Для Matrix скопійовані або застарілі завдання з room ID у `delivery.to`, записаними в нижньому регістрі, можуть завершуватися помилкою, тому що room ID у Matrix чутливі до регістру. Відредагуйте завдання, вказавши точне значення `!room:server` або `room:!room:server` із Matrix.
|
||||
- Помилки автентифікації каналу (`unauthorized`, `Forbidden`) означають, що доставлення було заблоковано обліковими даними.
|
||||
- Якщо ізольований запуск повертає лише тихий токен (`NO_REPLY` / `no_reply`), OpenClaw пригнічує пряме вихідне доставлення, а також резервний шлях queued summary, тому назад у чат нічого не публікується.
|
||||
- Якщо агент має сам надіслати повідомлення користувачу, перевірте, що завдання має придатний маршрут (`channel: "last"` із попереднім чатом або явний канал/ціль).
|
||||
</Accordion>
|
||||
<Accordion title="Схоже, що Cron або Heartbeat заважає rollover у стилі /new">
|
||||
- Актуальність щоденного та неактивного скидання не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle).
|
||||
- Пробудження cron, запуски heartbeat, сповіщення exec і службовий облік gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не подовжують `sessionStartedAt` або `lastInteractionAt`.
|
||||
- Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії в JSONL-транскрипті, якщо файл усе ще доступний. Застарілі неактивні рядки без `lastInteractionAt` використовують цей відновлений час початку як базову точку неактивності.
|
||||
<Accordion title="Схоже, що Cron або Heartbeat заважає переходу в стилі /new">
|
||||
- Актуальність щоденного та idle скидання не базується на `updatedAt`; див. [Керування сесіями](/uk/concepts/session#session-lifecycle).
|
||||
- Пробудження cron, запуски heartbeat, сповіщення exec і службові дії gateway можуть оновлювати рядок сесії для маршрутизації/статусу, але вони не продовжують `sessionStartedAt` або `lastInteractionAt`.
|
||||
- Для застарілих рядків, створених до появи цих полів, OpenClaw може відновити `sessionStartedAt` із заголовка сесії transcript JSONL, якщо файл ще доступний. Застарілі idle-рядки без `lastInteractionAt` використовують цей відновлений час запуску як базову точку idle.
|
||||
</Accordion>
|
||||
<Accordion title="Підводні камені часових поясів">
|
||||
- Cron без `--tz` використовує часовий пояс хоста gateway.
|
||||
@ -475,7 +475,7 @@ openclaw doctor
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації в одному огляді
|
||||
- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації з першого погляду
|
||||
- [Фонові завдання](/uk/automation/tasks) — журнал завдань для виконань cron
|
||||
- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії
|
||||
- [Часовий пояс](/uk/concepts/timezone) — налаштування часового поясу
|
||||
- [Heartbeat](/uk/gateway/heartbeat) — періодичні цикли основної сесії
|
||||
- [Часовий пояс](/uk/concepts/timezone) — конфігурація часового поясу
|
||||
|
||||
@ -2,23 +2,23 @@
|
||||
read_when:
|
||||
- Вам потрібні заплановані завдання та пробудження
|
||||
- Ви налагоджуєте виконання Cron і журнали
|
||||
summary: Довідка CLI для `openclaw cron` (планування та запуск фонових завдань)
|
||||
summary: Довідник CLI для `openclaw cron` (планування та запуск фонових завдань)
|
||||
title: Cron
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T01:19:14Z"
|
||||
generated_at: "2026-04-28T03:20:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 35a9ba4c89c6022bda7e8c4dfb81d2efae7c541d73f4c4b36683fd128af0ba4d
|
||||
source_hash: 15a67675caea0948e698f7c054da2662f4bcbcd8bdfe6c8c4d14b8f092076375
|
||||
source_path: cli/cron.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw cron`
|
||||
|
||||
Керуйте завданнями Cron для планувальника Gateway.
|
||||
Керуйте Cron-завданнями для планувальника Gateway.
|
||||
|
||||
<Tip>
|
||||
Запустіть `openclaw cron --help`, щоб переглянути повну поверхню команд. Див. [Завдання Cron](/uk/automation/cron-jobs) для концептуального посібника.
|
||||
Запустіть `openclaw cron --help`, щоб переглянути повну поверхню команд. Див. [Cron-завдання](/uk/automation/cron-jobs) для концептуального посібника.
|
||||
</Tip>
|
||||
|
||||
## Сеанси
|
||||
@ -30,33 +30,33 @@ x-i18n:
|
||||
- `main` прив’язується до основного сеансу агента.
|
||||
- `isolated` створює новий transcript та ідентифікатор сеансу для кожного запуску.
|
||||
- `current` прив’язується до активного сеансу на момент створення.
|
||||
- `session:<id>` фіксує явний ключ постійного сеансу.
|
||||
- `session:<id>` закріплює явний постійний ключ сеансу.
|
||||
</Accordion>
|
||||
<Accordion title="Семантика ізольованого сеансу">
|
||||
Ізольовані запуски скидають фоновий контекст розмови. Маршрутизація каналу та групи, політика надсилання/черги, підвищення привілеїв, походження та прив’язка середовища виконання ACP скидаються для нового запуску. Безпечні налаштування, а також явні вибрані користувачем перевизначення моделі чи автентифікації можуть переноситися між запусками.
|
||||
Ізольовані запуски скидають фоновий контекст розмови. Маршрутизація каналу та групи, політика надсилання/черги, підвищення привілеїв, походження та прив’язка середовища виконання ACP скидаються для нового запуску. Безпечні налаштування та явні вибрані користувачем перевизначення моделі або автентифікації можуть зберігатися між запусками.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Доставка
|
||||
|
||||
`openclaw cron list` і `openclaw cron show <job-id>` показують попередній перегляд визначеного маршруту доставки. Для `channel: "last"` попередній перегляд показує, чи маршрут було визначено з основного або поточного сеансу, чи він завершиться безпечною відмовою.
|
||||
`openclaw cron list` і `openclaw cron show <job-id>` попередньо показують визначений маршрут доставки. Для `channel: "last"` попередній перегляд показує, чи маршрут визначено з основного або поточного сеансу, чи він завершиться безпечною відмовою.
|
||||
|
||||
<Note>
|
||||
Ізольовані завдання `cron add` за замовчуванням використовують доставку `--announce`. Використовуйте `--no-deliver`, щоб залишити вивід внутрішнім. `--deliver` лишається застарілим псевдонімом для `--announce`.
|
||||
Ізольовані завдання `cron add` типово використовують доставку `--announce`. Використовуйте `--no-deliver`, щоб зберегти вивід внутрішнім. `--deliver` залишається застарілим псевдонімом для `--announce`.
|
||||
</Note>
|
||||
|
||||
### Володіння доставкою
|
||||
### Власність доставки
|
||||
|
||||
Доставка чату для ізольованого Cron ділиться між агентом і виконавцем:
|
||||
Для ізольованої доставки в чат Cron відповідальність спільно поділяють агент і виконавець:
|
||||
|
||||
- Агент може надсилати напряму за допомогою інструмента `message`, коли маршрут чату доступний.
|
||||
- `announce` резервно доставляє лише остаточну відповідь, якщо агент не надіслав її напряму до визначеної цілі.
|
||||
- Агент може надсилати безпосередньо за допомогою інструмента `message`, коли маршрут чату доступний.
|
||||
- `announce` резервно доставляє лише фінальну відповідь, якщо агент не надіслав її безпосередньо до визначеної цілі.
|
||||
- `webhook` надсилає завершене корисне навантаження на URL.
|
||||
- `none` вимикає резервну доставку виконавця.
|
||||
- `none` вимикає резервну доставку виконавцем.
|
||||
|
||||
`--announce` — це резервна доставка виконавця для остаточної відповіді. `--no-deliver` вимикає цю резервну поведінку, але не прибирає інструмент `message` агента, коли маршрут чату доступний.
|
||||
`--announce` — це резервна доставка виконавцем для фінальної відповіді. `--no-deliver` вимикає цю резервну доставку, але не прибирає інструмент `message` агента, коли маршрут чату доступний.
|
||||
|
||||
Нагадування, створені з активного чату, зберігають ціль доставки активного чату для резервної доставки announce. Внутрішні ключі сеансу можуть бути в нижньому регістрі; не використовуйте їх як джерело істини для чутливих до регістру ідентифікаторів провайдерів, таких як ідентифікатори кімнат Matrix.
|
||||
Нагадування, створені з активного чату, зберігають ціль доставки поточного чату для резервної доставки announce. Внутрішні ключі сеансу можуть бути в нижньому регістрі; не використовуйте їх як джерело істини для чутливих до регістру ідентифікаторів постачальників, таких як ідентифікатори кімнат Matrix.
|
||||
|
||||
### Доставка збоїв
|
||||
|
||||
@ -70,34 +70,34 @@ x-i18n:
|
||||
Завдання основного сеансу можуть використовувати `delivery.failureDestination` лише тоді, коли основний режим доставки — `webhook`. Ізольовані завдання приймають його в усіх режимах.
|
||||
</Note>
|
||||
|
||||
Примітка: ізольовані запуски Cron трактують збої агента на рівні запуску як помилки завдання, навіть коли корисне навантаження відповіді не створюється, тому збої моделі/провайдера все одно збільшують лічильники помилок і запускають сповіщення про збої.
|
||||
Примітка: ізольовані запуски Cron трактують збої агента на рівні запуску як помилки завдання, навіть коли не створено payload відповіді, тому збої моделі/постачальника все одно збільшують лічильники помилок і запускають сповіщення про збої.
|
||||
|
||||
## Планування
|
||||
|
||||
### Одноразові завдання
|
||||
|
||||
`--at <datetime>` планує одноразовий запуск. Дати й час без зсуву трактуються як UTC, якщо ви також не передасте `--tz <iana>`, що інтерпретує локальний час у вказаному часовому поясі.
|
||||
`--at <datetime>` планує одноразовий запуск. Дата й час без зміщення трактуються як UTC, якщо ви також не передасте `--tz <iana>`, що інтерпретує локальний час у вказаному часовому поясі.
|
||||
|
||||
<Note>
|
||||
Одноразові завдання після успішного виконання за замовчуванням видаляються. Використовуйте `--keep-after-run`, щоб зберегти їх.
|
||||
Одноразові завдання типово видаляються після успішного виконання. Використовуйте `--keep-after-run`, щоб зберегти їх.
|
||||
</Note>
|
||||
|
||||
### Повторювані завдання
|
||||
|
||||
Повторювані завдання використовують експоненційний retry backoff після послідовних помилок: 30 с, 1 хв, 5 хв, 15 хв, 60 хв. Після наступного успішного запуску розклад повертається до нормального режиму.
|
||||
Повторювані завдання використовують експоненціальну затримку повторних спроб після послідовних помилок: 30 с, 1 хв, 5 хв, 15 хв, 60 хв. Після наступного успішного запуску графік повертається до нормального режиму.
|
||||
|
||||
Пропущені запуски відстежуються окремо від помилок виконання. Вони не впливають на retry backoff, але `openclaw cron edit <job-id> --failure-alert-include-skipped` може додати повторні сповіщення про пропущені запуски до сповіщень про збої.
|
||||
Пропущені запуски відстежуються окремо від помилок виконання. Вони не впливають на затримку повторних спроб, але `openclaw cron edit <job-id> --failure-alert-include-skipped` може додати повторювані сповіщення про пропущені запуски до сповіщень про збої.
|
||||
|
||||
Для ізольованих завдань, націлених на локально налаштованого провайдера моделі, Cron виконує легку попередню перевірку провайдера перед запуском ходу агента. Провайдери `api: "ollama"` через loopback, приватну мережу та `.local` перевіряються на `/api/tags`; локальні OpenAI-сумісні провайдери, як-от vLLM, SGLang і LM Studio, перевіряються на `/models`. Якщо endpoint недоступний, запуск записується як `skipped` і повторюється за наступним розкладом; відповідні недоступні endpoint-и кешуються на 5 хвилин, щоб багато завдань не перевантажували один і той самий локальний сервер.
|
||||
Для ізольованих завдань, які націлені на локально налаштованого постачальника моделі, Cron виконує легку попередню перевірку постачальника перед початком ходу агента. Постачальники `api: "ollama"` у loopback, приватній мережі та з адресами `.local` перевіряються через `/api/tags`; локальні OpenAI-сумісні постачальники, такі як vLLM, SGLang і LM Studio, перевіряються через `/models`. Якщо кінцева точка недоступна, запуск записується як `skipped` і повторюється за наступним розкладом; відповідні недоступні кінцеві точки кешуються на 5 хвилин, щоб багато завдань не перевантажували той самий локальний сервер.
|
||||
|
||||
Примітка: визначення завдань Cron зберігаються в `jobs.json`, а стан очікування середовища виконання — у `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>`, щоб відстежити підсумковий результат.
|
||||
|
||||
<Note>
|
||||
`openclaw cron run <job-id>` за замовчуванням виконує примусовий запуск. Використовуйте `--due`, щоб зберегти попередню поведінку «запускати лише коли настав час».
|
||||
`openclaw cron run <job-id>` типово примусово запускає завдання. Використовуйте `--due`, щоб зберегти стару поведінку «запускати лише якщо настав час».
|
||||
</Note>
|
||||
|
||||
## Моделі
|
||||
@ -105,101 +105,101 @@ x-i18n:
|
||||
`cron add|edit --model <ref>` вибирає дозволену модель для завдання.
|
||||
|
||||
<Warning>
|
||||
Якщо модель не дозволена, Cron показує попередження і повертається до вибору моделі агента або моделі за замовчуванням для завдання.
|
||||
Якщо модель не дозволена або її не вдається визначити, Cron завершує запуск явною помилкою валідації замість того, щоб повертатися до агента завдання або типового вибору моделі.
|
||||
</Warning>
|
||||
|
||||
Cron `--model` — це **основна модель завдання**, а не перевизначення `/model` для сеансу чату. Це означає, що:
|
||||
Cron `--model` — це **основний параметр завдання**, а не перевизначення `/model` сеансу чату. Це означає:
|
||||
|
||||
- Налаштовані резервні моделі все одно застосовуються, коли вибрана модель завдання завершується помилкою.
|
||||
- `fallbacks` у корисному навантаженні для окремого завдання замінює налаштований список резервних варіантів, якщо він присутній.
|
||||
- Порожній список резервних варіантів для окремого завдання (`fallbacks: []` у корисному навантаженні/API завдання) робить запуск Cron строгим.
|
||||
- Коли завдання має `--model`, але список резервних варіантів не налаштований, OpenClaw передає явне порожнє перевизначення резервних варіантів, щоб основна модель агента не додавалася як прихована ціль повторної спроби.
|
||||
- Налаштовані резервні моделі все одно застосовуються, коли вибрана модель завдання зазнає збою.
|
||||
- `fallbacks` у payload для кожного завдання замінює налаштований список резервних варіантів, якщо присутній.
|
||||
- Порожній список резервних варіантів для завдання (`fallbacks: []` у payload/API завдання) робить запуск Cron строгим.
|
||||
- Коли завдання має `--model`, але список резервних варіантів не налаштовано, OpenClaw передає явне порожнє перевизначення резервних варіантів, щоб основна модель агента не додавалася як прихована ціль повторної спроби.
|
||||
|
||||
### Пріоритет моделей ізольованого Cron
|
||||
### Пріоритет моделі для ізольованого Cron
|
||||
|
||||
Ізольований Cron визначає активну модель у такому порядку:
|
||||
|
||||
1. Перевизначення Gmail-hook.
|
||||
2. `--model` для окремого завдання.
|
||||
3. Збережене перевизначення моделі сеансу Cron (коли користувач його вибрав).
|
||||
4. Вибір моделі агента або моделі за замовчуванням.
|
||||
3. Збережене перевизначення моделі сеансу Cron (коли користувач вибрав його).
|
||||
4. Агент або типовий вибір моделі.
|
||||
|
||||
### Швидкий режим
|
||||
|
||||
Швидкий режим ізольованого Cron дотримується визначеного вибору активної моделі. За замовчуванням застосовується конфігурація моделі `params.fastMode`, але збережене перевизначення `fastMode` сеансу все одно має вищий пріоритет над конфігурацією.
|
||||
Швидкий режим ізольованого Cron дотримується визначеного поточного вибору моделі. Налаштування моделі `params.fastMode` застосовується типово, але збережене перевизначення `fastMode` сеансу все одно має вищий пріоритет за конфігурацію.
|
||||
|
||||
### Повторні спроби перемикання live-моделі
|
||||
### Повторні спроби перемикання поточної моделі
|
||||
|
||||
Якщо ізольований запуск викидає `LiveSessionModelSwitchError`, Cron зберігає перемкненого провайдера й модель (а також перевизначення профілю автентифікації після перемикання, якщо воно є) для активного запуску перед повторною спробою. Зовнішній цикл повторних спроб обмежено двома повторними спробами перемикання після початкової спроби, після чого він переривається замість нескінченного циклу.
|
||||
Якщо ізольований запуск викидає `LiveSessionModelSwitchError`, Cron зберігає перемкненого постачальника та модель (а також перевизначення профілю автентифікації після перемикання, якщо воно присутнє) для активного запуску перед повторною спробою. Зовнішній цикл повторних спроб обмежено двома повторними спробами перемикання після початкової спроби, після чого він переривається замість нескінченного зациклення.
|
||||
|
||||
## Вивід запуску та відмови
|
||||
|
||||
### Приглушення застарілих підтверджень
|
||||
### Придушення застарілих підтверджень
|
||||
|
||||
Ізольовані ходи Cron приглушують відповіді, що містять лише застаріле підтвердження. Якщо перший результат — це лише проміжне оновлення стану й жоден дочірній запуск subagent не відповідає за остаточну відповідь, 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.sessionRetention` (типово `24h`) очищає завершені сеанси ізольованих запусків.
|
||||
- `cron.sessionRetention` (типово `24h`) очищає сеанси завершених ізольованих запусків.
|
||||
- `cron.runLog.maxBytes` і `cron.runLog.keepLines` очищають `~/.openclaw/cron/runs/<jobId>.jsonl`.
|
||||
|
||||
## Міграція старіших завдань
|
||||
|
||||
<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` у payload) і мігрує прості резервні 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-контекст для ізольованого завдання:
|
||||
Увімкніть легкий bootstrap-контекст для ізольованого завдання:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --light-context
|
||||
```
|
||||
|
||||
Оголосити в конкретний канал:
|
||||
Оголосіть у певний канал:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
```
|
||||
|
||||
Створити ізольоване завдання з легким bootstrap-контекстом:
|
||||
Створіть ізольоване завдання з легким bootstrap-контекстом:
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
--name "Lightweight morning brief" \
|
||||
--name "Короткий ранковий огляд" \
|
||||
--cron "0 7 * * *" \
|
||||
--session isolated \
|
||||
--message "Summarize overnight updates." \
|
||||
--message "Підсумуй оновлення за ніч." \
|
||||
--light-context \
|
||||
--no-deliver
|
||||
```
|
||||
|
||||
`--light-context` застосовується лише до ізольованих завдань ходу агента. Для запусків Cron легкий режим зберігає bootstrap-контекст порожнім замість упровадження повного набору bootstrap-контексту робочого простору.
|
||||
`--light-context` застосовується лише до ізольованих завдань ходу агента. Для запусків Cron легкий режим зберігає bootstrap-контекст порожнім замість ін’єкції повного набору bootstrap робочого простору.
|
||||
|
||||
## Поширені команди адміністрування
|
||||
|
||||
@ -213,7 +213,7 @@ openclaw cron run <job-id> --due
|
||||
openclaw cron runs --id <job-id> --limit 50
|
||||
```
|
||||
|
||||
Записи `cron runs` містять діагностику доставки з ціллю Cron, що була задумана, визначеною ціллю, надсиланнями через інструмент message, використанням резервного механізму та станом доставки.
|
||||
Записи `cron runs` містять діагностику доставки з наміченою ціллю Cron, визначеною ціллю, надсиланнями через інструмент message, використанням резервного механізму та станом доставки.
|
||||
|
||||
Переналаштування агента та сеансу:
|
||||
|
||||
@ -235,5 +235,5 @@ openclaw cron edit <job-id> --no-deliver
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Заплановані завдання](/uk/automation/cron-jobs)
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете налаштувати QMD як свій бекенд пам’яті
|
||||
- Ви хочете розширені функції пам’яті, як-от реранжування або додаткові індексовані шляхи
|
||||
summary: Локальний пошуковий сайдкар із BM25, векторами, реранжуванням і розширенням запиту
|
||||
- Ви хочете налаштувати QMD як бекенд пам’яті
|
||||
- Вам потрібні розширені можливості пам’яті, як-от переранжування або додаткові індексовані шляхи
|
||||
summary: Локальний пошуковий сайдкар із підтримкою BM25, векторів, переранжування та розширення запитів
|
||||
title: Рушій пам’яті QMD
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T14:18:18Z"
|
||||
generated_at: "2026-04-28T03:20:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1995a2b087c484595b0e0efed7a4ae3987b8fb3ac95e3c41bdf5335ba6240e73
|
||||
source_hash: 09de0490a2584d1c7eeccd4ba8613d63ea4c69e62e5eb5a0492a8baa1a6c7eea
|
||||
source_path: concepts/memory-qmd.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
[QMD](https://github.com/tobi/qmd) — це локальний пошуковий сайдкар, що працює
|
||||
поруч з OpenClaw. Він поєднує BM25, векторний пошук і реранжування в одному
|
||||
бінарному файлі, а також може індексувати вміст поза файлами пам’яті вашого робочого простору.
|
||||
[QMD](https://github.com/tobi/qmd) — це локальний пошуковий сайдкар, який працює
|
||||
поруч з OpenClaw. Він поєднує BM25, векторний пошук і переранжування в одному
|
||||
бінарному файлі, а також може індексувати вміст за межами файлів пам’яті вашого робочого простору.
|
||||
|
||||
## Що він додає понад вбудований рушій
|
||||
## Що він додає порівняно з вбудованим рушієм
|
||||
|
||||
- **Реранжування та розширення запиту** для кращої повноти пошуку.
|
||||
- **Індексація додаткових директорій** — документація проєкту, нотатки команди, будь-що на диску.
|
||||
- **Індексація транскриптів сесій** — відновлення попередніх розмов.
|
||||
- **Повністю локальна робота** — запускається з необов’язковим пакетом середовища виконання node-llama-cpp і
|
||||
- **Переранжування та розширення запитів** для кращої повноти пошуку.
|
||||
- **Індексація додаткових каталогів** — документація проєкту, командні нотатки, будь-що на диску.
|
||||
- **Індексація транскриптів сеансів** — для відновлення попередніх розмов.
|
||||
- **Повністю локальний** — працює з необов’язковим пакетом середовища виконання node-llama-cpp і
|
||||
автоматично завантажує моделі GGUF.
|
||||
- **Автоматичний резервний перехід** — якщо QMD недоступний, OpenClaw безшовно повертається до
|
||||
вбудованого рушія.
|
||||
- **Автоматичний резервний перехід** — якщо QMD недоступний, OpenClaw безшовно переходить на
|
||||
вбудований рушій.
|
||||
|
||||
## Початок роботи
|
||||
|
||||
### Передумови
|
||||
|
||||
- Установіть QMD: `npm install -g @tobilu/qmd` або `bun install -g @tobilu/qmd`
|
||||
- Встановіть QMD: `npm install -g @tobilu/qmd` або `bun install -g @tobilu/qmd`
|
||||
- Збірка SQLite, яка дозволяє розширення (`brew install sqlite` на macOS).
|
||||
- QMD має бути в `PATH` шлюзу.
|
||||
- macOS і Linux працюють одразу. Windows найкраще підтримується через WSL2.
|
||||
- macOS і Linux працюють одразу. На Windows найкраща підтримка через WSL2.
|
||||
|
||||
### Увімкнення
|
||||
|
||||
@ -47,66 +47,69 @@ x-i18n:
|
||||
```
|
||||
|
||||
OpenClaw створює ізольований домашній каталог QMD у
|
||||
`~/.openclaw/agents/<agentId>/qmd/` і автоматично керує життєвим циклом
|
||||
сайдкара — колекції, оновлення та запуск вбудовування обробляються за вас.
|
||||
Він віддає перевагу поточним формам колекцій QMD і запитів MCP, але за потреби
|
||||
все одно повертається до альтернативних прапорців шаблонів колекцій і старіших назв інструментів MCP.
|
||||
Під час звіряння на старті також повторно створюються застарілі керовані колекції за їхніми
|
||||
канонічними шаблонами, якщо старіша колекція QMD з такою самою назвою все ще присутня.
|
||||
`~/.openclaw/agents/<agentId>/qmd/` і автоматично керує життєвим циклом сайдкара —
|
||||
колекції, оновлення та запуск ембедингів обробляються за вас.
|
||||
Він надає перевагу актуальним формам колекцій QMD і запитів MCP, але за потреби
|
||||
все одно використовує резервні прапорці альтернативних шаблонів колекцій і
|
||||
старі назви інструментів MCP.
|
||||
Під час узгодження на старті також повторно створюються застарілі керовані колекції
|
||||
з поверненням до їхніх канонічних шаблонів, якщо стара колекція QMD з такою самою назвою
|
||||
ще присутня.
|
||||
|
||||
## Як працює сайдкар
|
||||
|
||||
- OpenClaw створює колекції з файлів пам’яті вашого робочого простору та всіх
|
||||
налаштованих `memory.qmd.paths`, потім запускає `qmd update` під час старту і
|
||||
періодично (типово кожні 5 хвилин). Семантичні режими також запускають `qmd embed`.
|
||||
- Типова колекція робочого простору відстежує `MEMORY.md` і дерево
|
||||
`memory/`. `memory.md` у нижньому регістрі не індексується як кореневий файл пам’яті.
|
||||
- Оновлення під час старту виконується у фоновому режимі, щоб не блокувати запуск чату.
|
||||
- Для пошуку використовується налаштований `searchMode` (типово: `search`; також підтримуються
|
||||
`vsearch` і `query`). `search` використовує лише BM25, тому OpenClaw пропускає перевірки готовності
|
||||
семантичних векторів і супровід вбудовувань у цьому режимі. Якщо режим не спрацьовує, OpenClaw
|
||||
повторює спробу з `qmd query`.
|
||||
- З випусками QMD, які оголошують підтримку фільтрів кількох колекцій, OpenClaw групує
|
||||
колекції з однаковим джерелом в один виклик пошуку QMD. Старіші випуски QMD
|
||||
зберігають сумісний резервний варіант по одній колекції.
|
||||
- Якщо QMD повністю не спрацьовує, OpenClaw повертається до вбудованого рушія SQLite.
|
||||
- Типова колекція робочого простору відстежує `MEMORY.md` і дерево `memory/`.
|
||||
`memory.md` у нижньому регістрі не індексується як кореневий файл пам’яті.
|
||||
- Оновлення під час старту виконується у фоновому режимі, тому запуск чату не блокується.
|
||||
- Пошук використовує налаштований `searchMode` (типово: `search`; також підтримуються
|
||||
`vsearch` і `query`). `search` використовує лише BM25, тому OpenClaw пропускає перевірки
|
||||
готовності семантичних векторів і обслуговування ембедингів у цьому режимі. Якщо режим не спрацьовує,
|
||||
OpenClaw повторює спробу з `qmd query`.
|
||||
- У випусках QMD, які оголошують підтримку фільтрів для кількох колекцій, OpenClaw групує
|
||||
колекції з однаковим джерелом в один виклик пошуку QMD. У старіших випусках QMD
|
||||
зберігається сумісний резервний варіант із пошуком по одній колекції.
|
||||
- Якщо QMD повністю не спрацьовує, OpenClaw переходить на вбудований рушій SQLite.
|
||||
Повторні спроби в межах одного ходу чату після збою відкриття ненадовго сповільнюються,
|
||||
щоб відсутній бінарний файл або зламана залежність сайдкара не спричинили шторм повторних спроб;
|
||||
`openclaw memory status` і одноразові перевірки через CLI усе одно напряму повторно перевіряють QMD.
|
||||
|
||||
<Info>
|
||||
Перший пошук може бути повільним — QMD автоматично завантажує моделі GGUF (~2 ГБ) для
|
||||
реранжування та розширення запиту під час першого запуску `qmd query`.
|
||||
переранжування і розширення запитів під час першого запуску `qmd query`.
|
||||
</Info>
|
||||
|
||||
## Продуктивність пошуку та сумісність
|
||||
|
||||
OpenClaw підтримує сумісність шляху пошуку QMD як з поточними, так і зі старішими
|
||||
установками QMD.
|
||||
OpenClaw зберігає сумісність шляху пошуку QMD як з актуальними, так і зі старішими
|
||||
встановленнями QMD.
|
||||
|
||||
Під час запуску OpenClaw один раз для кожного менеджера перевіряє текст довідки встановленого QMD. Якщо
|
||||
бінарний файл оголошує підтримку кількох фільтрів колекцій, OpenClaw шукає в усіх
|
||||
бінарний файл оголошує підтримку кількох фільтрів колекцій, OpenClaw виконує пошук в усіх
|
||||
колекціях з однаковим джерелом однією командою:
|
||||
|
||||
```bash
|
||||
qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
|
||||
```
|
||||
|
||||
Це дає змогу уникнути запуску окремого підпроцесу QMD для кожної колекції
|
||||
довготривалої пам’яті.
|
||||
Колекції транскриптів сесій залишаються у власній групі джерел, тож змішані пошуки
|
||||
Це дозволяє уникнути запуску окремого підпроцесу QMD для кожної колекції довготривалої пам’яті.
|
||||
Колекції транскриптів сеансів залишаються у власній групі джерел, тому змішані пошуки
|
||||
`memory` + `sessions` усе одно дають вхідні дані для диверсифікатора результатів з обох
|
||||
джерел.
|
||||
|
||||
Старіші збірки QMD приймають лише один фільтр колекції. Коли OpenClaw виявляє одну
|
||||
з таких збірок, він зберігає шлях сумісності й шукає в кожній колекції
|
||||
окремо перед злиттям і дедуплікацією результатів.
|
||||
Старіші збірки QMD приймають лише один фільтр колекції. Коли OpenClaw виявляє одну з
|
||||
таких збірок, він зберігає шлях сумісності та виконує пошук по кожній колекції окремо
|
||||
перед об’єднанням і дедуплікацією результатів.
|
||||
|
||||
Щоб вручну перевірити встановлений контракт, виконайте:
|
||||
Щоб вручну перевірити контракт установленої версії, виконайте:
|
||||
|
||||
```bash
|
||||
qmd --help | grep -i collection
|
||||
```
|
||||
|
||||
Поточна довідка QMD говорить, що фільтри колекцій можуть націлюватися на одну або
|
||||
кілька колекцій.
|
||||
У поточній довідці QMD зазначено, що фільтри колекцій можуть націлюватися на одну або кілька колекцій.
|
||||
Старіша довідка зазвичай описує одну колекцію.
|
||||
|
||||
## Перевизначення моделей
|
||||
@ -120,12 +123,12 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
|
||||
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
```
|
||||
|
||||
Після зміни моделі вбудовування повторно запустіть вбудовування, щоб індекс відповідав
|
||||
Після зміни моделі ембедингів повторно запустіть побудову ембедингів, щоб індекс відповідав
|
||||
новому векторному простору.
|
||||
|
||||
## Індексація додаткових шляхів
|
||||
|
||||
Спрямуйте QMD на додаткові директорії, щоб зробити їх доступними для пошуку:
|
||||
Спрямуйте QMD на додаткові каталоги, щоб зробити їх доступними для пошуку:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -139,12 +142,12 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
```
|
||||
|
||||
Фрагменти з додаткових шляхів з’являються як `qmd/<collection>/<relative-path>` у
|
||||
результатах пошуку. `memory_get` розуміє цей префікс і читає з правильного
|
||||
результатах пошуку. `memory_get` розуміє цей префікс і читає дані з правильного
|
||||
кореня колекції.
|
||||
|
||||
## Індексація транскриптів сесій
|
||||
## Індексація транскриптів сеансів
|
||||
|
||||
Увімкніть індексацію сесій, щоб відновлювати попередні розмови:
|
||||
Увімкніть індексацію сеансів, щоб відновлювати попередні розмови:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -157,13 +160,13 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
}
|
||||
```
|
||||
|
||||
Транскрипти експортуються як санітизовані репліки User/Assistant в окрему колекцію QMD
|
||||
Транскрипти експортуються як очищені ходи User/Assistant в окрему колекцію QMD
|
||||
у `~/.openclaw/agents/<id>/qmd/sessions/`.
|
||||
|
||||
## Область пошуку
|
||||
|
||||
Типово результати пошуку QMD показуються в прямих і канальних сесіях
|
||||
(не в групах). Налаштуйте `memory.qmd.scope`, щоб змінити це:
|
||||
Типово результати пошуку QMD відображаються в прямих сеансах і сеансах каналів
|
||||
(але не в групах). Щоб змінити це, налаштуйте `memory.qmd.scope`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -178,36 +181,36 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
}
|
||||
```
|
||||
|
||||
Коли область дії забороняє пошук, OpenClaw записує попередження з похідними значеннями каналу та
|
||||
типу чату, щоб порожні результати було легше налагоджувати.
|
||||
Коли область видимості забороняє пошук, OpenClaw записує попередження з похідними значеннями каналу та
|
||||
типу чату, щоб порожні результати було легше діагностувати.
|
||||
|
||||
## Посилання на джерела
|
||||
## Цитати
|
||||
|
||||
Коли `memory.citations` має значення `auto` або `on`, фрагменти пошуку містять
|
||||
нижній колонтитул `Source: <path#line>`. Установіть `memory.citations = "off"`, щоб прибрати цей нижній колонтитул,
|
||||
але при цьому все одно передавати шлях агенту внутрішньо.
|
||||
нижній колонтитул `Source: <path#line>`. Установіть `memory.citations = "off"`, щоб прибрати
|
||||
цей нижній колонтитул і водночас продовжити внутрішню передачу шляху агенту.
|
||||
|
||||
## Коли використовувати
|
||||
|
||||
Оберіть QMD, якщо вам потрібно:
|
||||
Обирайте QMD, коли вам потрібно:
|
||||
|
||||
- Реранжування для вищої якості результатів.
|
||||
- Шукати в документації проєкту або нотатках поза робочим простором.
|
||||
- Відновлювати попередні розмови в сесіях.
|
||||
- Переранжування для вищої якості результатів.
|
||||
- Шукати документацію проєкту або нотатки поза межами робочого простору.
|
||||
- Відновлювати попередні розмови із сеансів.
|
||||
- Повністю локальний пошук без API-ключів.
|
||||
|
||||
Для простіших налаштувань [вбудований рушій](/uk/concepts/memory-builtin) добре працює
|
||||
Для простіших налаштувань добре підходить [вбудований рушій](/uk/concepts/memory-builtin)
|
||||
без додаткових залежностей.
|
||||
|
||||
## Усунення проблем
|
||||
## Усунення несправностей
|
||||
|
||||
**QMD не знайдено?** Переконайтеся, що бінарний файл є в `PATH` шлюзу. Якщо OpenClaw
|
||||
працює як сервіс, створіть символічне посилання:
|
||||
працює як сервіс, створіть символьне посилання:
|
||||
`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.
|
||||
|
||||
Якщо `qmd --version` працює у вашій оболонці, але OpenClaw все одно повідомляє
|
||||
Якщо `qmd --version` працює у вашій оболонці, але OpenClaw усе ще повідомляє про
|
||||
`spawn qmd ENOENT`, імовірно, процес шлюзу має інший `PATH`, ніж ваша
|
||||
інтерактивна оболонка. Явно закріпіть бінарний файл:
|
||||
інтерактивна оболонка. Явно зафіксуйте шлях до бінарного файла:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -223,44 +226,44 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
Використайте `command -v qmd` у середовищі, де встановлено QMD, а потім повторно перевірте
|
||||
через `openclaw memory status --deep`.
|
||||
|
||||
**Перший пошук дуже повільний?** QMD завантажує моделі GGUF при першому використанні. Попередньо прогрійте
|
||||
через `qmd query "test"` з тими самими директоріями XDG, які використовує OpenClaw.
|
||||
**Перший пошук дуже повільний?** QMD завантажує моделі GGUF під час першого використання. Попередньо прогрійте
|
||||
його за допомогою `qmd query "test"` з тими самими каталогами XDG, які використовує OpenClaw.
|
||||
|
||||
**Під час пошуку запускається багато підпроцесів QMD?** За можливості оновіть QMD. OpenClaw використовує
|
||||
один процес для пошуку в кількох колекціях з однаковим джерелом лише тоді, коли встановлений
|
||||
QMD оголошує підтримку кількох фільтрів `-c`; інакше він зберігає старіший
|
||||
резервний варіант по одній колекції для коректності.
|
||||
один процес для пошуків по кількох колекціях з однаковим джерелом лише тоді, коли встановлений
|
||||
QMD оголошує підтримку кількох фільтрів `-c`; інакше він зберігає старий резервний
|
||||
варіант по одній колекції для коректності.
|
||||
|
||||
**QMD лише з BM25 все одно намагається зібрати llama.cpp?** Установіть
|
||||
**QMD лише з BM25 усе ще намагається зібрати llama.cpp?** Установіть
|
||||
`memory.qmd.searchMode = "search"`. OpenClaw трактує цей режим як суто лексичний,
|
||||
не запускає перевірки статусу векторів QMD або супровід вбудовувань і залишає
|
||||
не запускає перевірки стану векторів QMD чи обслуговування ембедингів і залишає
|
||||
перевірки семантичної готовності для конфігурацій `vsearch` або `query`.
|
||||
|
||||
**Пошук завершується за тайм-аутом?** Збільште `memory.qmd.limits.timeoutMs` (типово: 4000 мс).
|
||||
Для повільнішого обладнання встановіть `120000`.
|
||||
|
||||
**Порожні результати в групових чатах?** Перевірте `memory.qmd.scope` — типово дозволено
|
||||
лише прямі та канальні сесії.
|
||||
**Порожні результати в групових чатах?** Перевірте `memory.qmd.scope` — типове значення дозволяє
|
||||
лише прямі сеанси й сеанси каналів.
|
||||
|
||||
**Пошук у кореневій пам’яті раптом став надто широким?** Перезапустіть шлюз або дочекайтеся
|
||||
наступного звіряння під час старту. OpenClaw повторно створює застарілі керовані колекції
|
||||
за канонічними шаблонами `MEMORY.md` і `memory/`, коли виявляє конфлікт
|
||||
з однаковою назвою.
|
||||
наступного узгодження під час запуску. OpenClaw повторно створює застарілі керовані колекції,
|
||||
повертаючи їх до канонічних шаблонів `MEMORY.md` і `memory/`, коли виявляє конфлікт
|
||||
однойменних колекцій.
|
||||
|
||||
**Тимчасові репозиторії, видимі з робочого простору, спричиняють `ENAMETOOLONG` або зламану індексацію?**
|
||||
Обхід QMD зараз дотримується поведінки базового сканера QMD, а не
|
||||
правил символьних посилань вбудованого рушія OpenClaw. Тримайте тимчасові checkout-и
|
||||
монорепозиторіїв у прихованих директоріях на кшталт `.tmp/` або поза індексованими коренями QMD, доки QMD не надасть
|
||||
безпечний до циклів обхід або явні засоби керування виключеннями.
|
||||
**Тимчасові репозиторії, видимі в робочому просторі, спричиняють `ENAMETOOLONG` або ламане індексування?**
|
||||
Обхід QMD наразі наслідує поведінку базового сканера QMD, а не правила символьних посилань
|
||||
вбудованого рушія OpenClaw. Тримайте тимчасові checkout-и монорепозиторіїв у
|
||||
прихованих каталогах, як-от `.tmp/`, або поза індексованими коренями QMD, доки QMD не надасть
|
||||
безпечний щодо циклів обхід або явні засоби виключення.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Щоб переглянути повну поверхню конфігурації (`memory.qmd.*`), режими пошуку, інтервали оновлення,
|
||||
правила області дії та всі інші параметри, дивіться
|
||||
[довідник із конфігурації пам’яті](/uk/reference/memory-config).
|
||||
Повний опис поверхні конфігурації (`memory.qmd.*`), режимів пошуку, інтервалів оновлення,
|
||||
правил області видимості та всіх інших параметрів дивіться в
|
||||
[довіднику з конфігурації пам’яті](/uk/reference/memory-config).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд пам’яті](/uk/concepts/memory)
|
||||
- [Вбудований рушій пам’яті](/uk/concepts/memory-builtin)
|
||||
- [Пам’ять Honcho](/uk/concepts/memory-honcho)
|
||||
- [Рушій пам’яті Honcho](/uk/concepts/memory-honcho)
|
||||
|
||||
@ -3,22 +3,22 @@ read_when:
|
||||
- Локальний запуск `pnpm openclaw qa matrix`
|
||||
- Додавання або вибір сценаріїв Matrix QA
|
||||
- Тріаж збоїв Matrix QA, тайм-аутів або завислого очищення
|
||||
summary: 'Довідник для супровідників щодо live QA-лейну Matrix на базі Docker: CLI, профілі, змінні середовища, сценарії та вихідні артефакти.'
|
||||
summary: 'Довідник для супровідників щодо live QA-лейну Matrix на основі Docker: CLI, профілі, змінні середовища, сценарії та артефакти виводу.'
|
||||
title: Matrix QA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T20:27:55Z"
|
||||
generated_at: "2026-04-28T03:20:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 55fcacd1348b681ef9e550d3f4cdf7c5ed3a2cb8d0df6d93b8ac025ec3280329
|
||||
source_hash: 440c24f2f1b19331f6800bb3224075f718c2429688bb023e96c59f3d3e4c4932
|
||||
source_path: concepts/qa-matrix.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
QA-лейн Matrix запускає вбудований Plugin `@openclaw/matrix` проти тимчасового homeserver Tuwunel у Docker із тимчасовими обліковими записами driver, SUT і observer, а також із попередньо створеними кімнатами. Це live-покриття Matrix із реальним транспортом.
|
||||
Лейн Matrix QA запускає вбудований Plugin `@openclaw/matrix` проти тимчасового homeserver Tuwunel у Docker, з тимчасовими обліковими записами driver, SUT і observer, а також попередньо створеними кімнатами. Це live-покриття реального транспортного рівня для Matrix.
|
||||
|
||||
Це інструментарій лише для супровідників. Паковані релізи OpenClaw навмисно не містять `qa-lab`, тому `openclaw qa` доступний лише з checkout вихідного коду. Checkout вихідного коду завантажують вбудований runner напряму — окремий крок встановлення Plugin не потрібен.
|
||||
Це інструментарій лише для супровідників. Паковані релізи OpenClaw навмисно не містять `qa-lab`, тому `openclaw qa` доступний лише з checkout вихідного коду. Checkout вихідного коду завантажують вбудований раннер напряму — окремий крок встановлення Plugin не потрібен.
|
||||
|
||||
Для ширшого контексту QA-фреймворку див. [Огляд QA](/uk/concepts/qa-e2e-automation).
|
||||
Для ширшого контексту QA-фреймворку див. [огляд QA](/uk/concepts/qa-e2e-automation).
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -26,16 +26,16 @@ QA-лейн Matrix запускає вбудований Plugin `@openclaw/matri
|
||||
pnpm openclaw qa matrix --profile fast --fail-fast
|
||||
```
|
||||
|
||||
Звичайний `pnpm openclaw qa matrix` запускає `--profile all` і не зупиняється на першій помилці. Використовуйте `--profile fast --fail-fast` як релізний gate; розподіляйте каталог через `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli`, коли запускаєте весь набір паралельно.
|
||||
Звичайний `pnpm openclaw qa matrix` запускає `--profile all` і не зупиняється після першої помилки. Використовуйте `--profile fast --fail-fast` як релізний gate; розбивайте каталог за допомогою `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli`, коли запускаєте повний набір паралельно.
|
||||
|
||||
## Що робить лейн
|
||||
|
||||
1. Розгортає тимчасовий homeserver Tuwunel у Docker (типовий образ `ghcr.io/matrix-construct/tuwunel:v1.5.1`, назва сервера `matrix-qa.test`, порт `28008`).
|
||||
2. Реєструє трьох тимчасових користувачів — `driver` (надсилає вхідний трафік), `sut` (обліковий запис OpenClaw Matrix, що тестується), `observer` (захоплення стороннього трафіку).
|
||||
3. Створює кімнати, потрібні для вибраних сценаріїв (main, threading, media, restart, secondary, allowlist, E2EE, verification DM тощо).
|
||||
4. Запускає дочірній Gateway OpenClaw із реальним Plugin Matrix, обмеженим обліковим записом SUT; `qa-channel` у дочірньому процесі не завантажується.
|
||||
1. Розгортає тимчасовий homeserver Tuwunel у Docker (типовий образ `ghcr.io/matrix-construct/tuwunel:v1.5.1`, ім’я сервера `matrix-qa.test`, порт `28008`).
|
||||
2. Реєструє трьох тимчасових користувачів — `driver` (надсилає вхідний трафік), `sut` (обліковий запис Matrix OpenClaw, що тестується), `observer` (захоплення стороннього трафіку).
|
||||
3. Створює кімнати, потрібні для вибраних сценаріїв (основна, для тредів, медіа, перезапуску, додаткова, allowlist, E2EE, verification DM тощо).
|
||||
4. Запускає дочірній Gateway OpenClaw із реальним Plugin Matrix, обмеженим обліковим записом SUT; `qa-channel` у дочірній процес не завантажується.
|
||||
5. Послідовно виконує сценарії, спостерігаючи за подіями через Matrix-клієнти driver/observer.
|
||||
6. Зупиняє homeserver, записує артефакти звіту й підсумку, а потім завершує роботу.
|
||||
6. Зупиняє homeserver, записує артефакти звіту та підсумку, потім завершує роботу.
|
||||
|
||||
## CLI
|
||||
|
||||
@ -45,41 +45,41 @@ pnpm openclaw qa matrix [options]
|
||||
|
||||
### Поширені прапорці
|
||||
|
||||
| Прапорець | Типове значення | Опис |
|
||||
| -------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--profile <profile>` | `all` | Профіль сценаріїв. Див. [Профілі](#profiles). |
|
||||
| `--fail-fast` | вимкнено | Зупинитися після першої невдалої перевірки або сценарію. |
|
||||
| `--scenario <id>` | — | Запустити лише цей сценарій. Можна вказувати кілька разів. Див. [Сценарії](#scenarios). |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | Куди записуються звіти, підсумок, спостережені події та вихідний журнал. Відносні шляхи обчислюються від `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Корінь репозиторію під час виклику з нейтрального робочого каталогу. |
|
||||
| `--sut-account <id>` | `sut` | Ідентифікатор облікового запису Matrix у конфігурації QA Gateway. |
|
||||
| Прапорець | Типове значення | Опис |
|
||||
| -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--profile <profile>` | `all` | Профіль сценаріїв. Див. [Профілі](#profiles). |
|
||||
| `--fail-fast` | вимкнено | Зупинитися після першої невдалої перевірки або сценарію. |
|
||||
| `--scenario <id>` | — | Запустити лише цей сценарій. Можна вказувати кілька разів. Див. [Сценарії](#scenarios). |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | Куди записуються звіти, підсумок, спостережені події та журнал виводу. Відносні шляхи обчислюються відносно `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Корінь репозиторію при запуску з нейтрального робочого каталогу. |
|
||||
| `--sut-account <id>` | `sut` | Ідентифікатор облікового запису Matrix у конфігурації QA Gateway. |
|
||||
|
||||
### Прапорці провайдера
|
||||
|
||||
Лейн використовує реальний транспорт Matrix, але провайдер моделі можна налаштувати:
|
||||
|
||||
| Прапорець | Типове значення | Опис |
|
||||
| ----------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` для детермінованого mock-dispatch або `live-frontier` для live frontier-провайдерів. Історичний псевдонім `live-openai` також працює. |
|
||||
| `--model <ref>` | типове для провайдера | Основне посилання `provider/model`. |
|
||||
| `--alt-model <ref>` | типове для провайдера | Альтернативне посилання `provider/model`, коли сценарії перемикаються посеред запуску. |
|
||||
| `--fast` | вимкнено | Увімкнути швидкий режим провайдера там, де він підтримується. |
|
||||
| Прапорець | Типове значення | Опис |
|
||||
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` для детермінованого mock-диспетчування або `live-frontier` для live frontier-провайдерів. Історичний псевдонім `live-openai` також працює. |
|
||||
| `--model <ref>` | типове значення провайдера | Основне посилання `provider/model`. |
|
||||
| `--alt-model <ref>` | типове значення провайдера | Альтернативне посилання `provider/model` для сценаріїв, де перемикання відбувається під час виконання. |
|
||||
| `--fast` | вимкнено | Увімкнути швидкий режим провайдера там, де він підтримується. |
|
||||
|
||||
Matrix QA не приймає `--credential-source` або `--credential-role`. Лейн локально створює тимчасових користувачів; спільного пулу облікових даних для оренди немає.
|
||||
|
||||
## Профілі
|
||||
|
||||
Вибраний профіль визначає, які сценарії запускатимуться.
|
||||
Вибраний профіль визначає, які сценарії будуть запущені.
|
||||
|
||||
| Профіль | Використання |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `all` (типово) | Повний каталог. Повільно, але вичерпно. |
|
||||
| `fast` | Підмножина для релізного gate, яка перевіряє контракт live-транспорту: canary, gating згадок, блокування allowlist, форма відповіді, відновлення після restart, продовження треду, ізоляція треду, спостереження за реакціями. |
|
||||
| `transport` | Сценарії транспортного рівня для threading, DM, room, autojoin, mention/allowlist. |
|
||||
| `media` | Покриття вкладень image, audio, video, PDF, EPUB. |
|
||||
| `e2ee-smoke` | Мінімальне покриття E2EE — базова зашифрована відповідь, продовження треду, успішний bootstrap. |
|
||||
| `e2ee-deep` | Вичерпні сценарії E2EE для втрати стану, резервних копій, ключів і відновлення. |
|
||||
| `e2ee-cli` | CLI-сценарії `openclaw matrix encryption setup` і `verify *`, що запускаються через QA harness. |
|
||||
| Профіль | Коли використовувати |
|
||||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `all` (типовий) | Повний каталог. Повільно, але вичерпно. |
|
||||
| `fast` | Підмножина для релізного gate, яка перевіряє live-контракт транспортного рівня: canary, фільтрацію згадок, блокування allowlist, форму відповіді, відновлення після перезапуску, продовження треду, ізоляцію треду, спостереження реакцій і доставку метаданих approval exec. |
|
||||
| `transport` | Сценарії транспортного рівня для тредів, DM, кімнат, autojoin, згадок/allowlist, approval та реакцій. |
|
||||
| `media` | Покриття вкладень image, audio, video, PDF, EPUB. |
|
||||
| `e2ee-smoke` | Мінімальне покриття E2EE — базова зашифрована відповідь, продовження треду, успішний bootstrap. |
|
||||
| `e2ee-deep` | Вичерпні сценарії E2EE для втрати стану, резервних копій, ключів і відновлення. |
|
||||
| `e2ee-cli` | CLI-сценарії `openclaw matrix encryption setup` і `verify *`, керовані через QA harness. |
|
||||
|
||||
Точне зіставлення міститься у `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`.
|
||||
|
||||
@ -88,57 +88,58 @@ Matrix QA не приймає `--credential-source` або `--credential-role`.
|
||||
Повний список ідентифікаторів сценаріїв — це union `MatrixQaScenarioId` у `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15`. Категорії включають:
|
||||
|
||||
- threading — `matrix-thread-*`, `matrix-subagent-thread-spawn`
|
||||
- верхній рівень / DM / room — `matrix-top-level-reply-shape`, `matrix-room-*`, `matrix-dm-*`
|
||||
- top-level / DM / room — `matrix-top-level-reply-shape`, `matrix-room-*`, `matrix-dm-*`
|
||||
- streaming і перебіг інструментів — `matrix-room-partial-streaming-preview`, `matrix-room-quiet-streaming-preview`, `matrix-room-tool-progress-*`, `matrix-room-block-streaming`
|
||||
- media — `matrix-media-type-coverage`, `matrix-room-image-understanding-attachment`, `matrix-attachment-only-ignored`, `matrix-unsupported-media-safe`
|
||||
- маршрутизація — `matrix-room-autojoin-invite`, `matrix-secondary-room-*`
|
||||
- реакції — `matrix-reaction-*`
|
||||
- routing — `matrix-room-autojoin-invite`, `matrix-secondary-room-*`
|
||||
- reactions — `matrix-reaction-*`
|
||||
- approvals — `matrix-approval-*` (метадані exec/Plugin, chunked fallback, deny reactions, threads і маршрутизація `target: "both"`)
|
||||
- restart і replay — `matrix-restart-*`, `matrix-stale-sync-replay-dedupe`, `matrix-room-membership-loss`, `matrix-homeserver-restart-resume`, `matrix-initial-catchup-then-incremental`
|
||||
- gating згадок і allowlist — `matrix-mention-*`, `matrix-allowlist-*`, `matrix-multi-actor-ordering`, `matrix-inbound-edit-*`, `matrix-mxid-prefixed-command-block`, `matrix-observer-allowlist-override`
|
||||
- E2EE — `matrix-e2ee-*` (базова відповідь, продовження треду, bootstrap, життєвий цикл recovery key, варіанти втрати стану, поведінка резервного копіювання сервера, гігієна пристроїв, верифікація SAS / QR / DM, restart, редагування артефактів)
|
||||
- E2EE CLI — `matrix-e2ee-cli-*` (налаштування шифрування, ідемпотентне налаштування, збій bootstrap, життєвий цикл recovery key, кілька облікових записів, round-trip відповіді Gateway, self-verification)
|
||||
- фільтрація згадок і allowlists — `matrix-mention-*`, `matrix-allowlist-*`, `matrix-multi-actor-ordering`, `matrix-inbound-edit-*`, `matrix-mxid-prefixed-command-block`, `matrix-observer-allowlist-override`
|
||||
- E2EE — `matrix-e2ee-*` (базова відповідь, продовження треду, bootstrap, життєвий цикл recovery key, варіанти втрати стану, поведінка резервної копії сервера, hygiene пристроїв, перевірка SAS / QR / DM, перезапуск, редагування артефактів)
|
||||
- E2EE CLI — `matrix-e2ee-cli-*` (налаштування шифрування, ідемпотентне налаштування, помилка bootstrap, життєвий цикл recovery key, кілька облікових записів, повний цикл gateway-reply, self-verification)
|
||||
|
||||
Передайте `--scenario <id>` (можна вказувати кілька разів), щоб запустити вибраний набір; поєднуйте з `--profile all`, щоб ігнорувати gating профілю.
|
||||
Передайте `--scenario <id>` (можна повторювати), щоб запустити вручну вибраний набір; поєднуйте з `--profile all`, щоб ігнорувати фільтрацію за профілем.
|
||||
|
||||
## Змінні середовища
|
||||
|
||||
| Змінна | Типове значення | Дія |
|
||||
| -------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000` (30 хв) | Жорстка верхня межа для всього запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | Вікно тиші для негативних перевірок на відсутність відповіді. Обмежується значенням `≤` тайм-ауту запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Межа для teardown Docker. Повідомлення про збої включають recovery-команду `docker compose ... down --remove-orphans`. |
|
||||
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | Перевизначає образ homeserver під час перевірки з іншою версією Tuwunel. |
|
||||
| `OPENCLAW_QA_MATRIX_PROGRESS` | увімкнено | `0` вимикає рядки поступу `[matrix-qa] ...` у stderr. `1` примусово вмикає їх. |
|
||||
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | redacted | `1` зберігає тіло повідомлення і `formatted_body` у `matrix-qa-observed-events.json`. Типово дані редагуються, щоб артефакти CI були безпечними. |
|
||||
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | вимкнено | `1` пропускає детермінований `process.exit` після запису артефактів. Типова поведінка примусово завершує процес, оскільки native crypto handle із matrix-js-sdk можуть утримувати event loop активним після завершення запису артефактів. |
|
||||
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | не задано | Якщо цю змінну задає зовнішній launcher (наприклад, `scripts/run-node.mjs`), Matrix QA повторно використовує цей шлях журналу замість запуску власного tee. |
|
||||
| Змінна | Типове значення | Ефект |
|
||||
| -------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000` (30 хв) | Жорстка верхня межа для всього запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | Вікно тиші для негативних перевірок відсутності відповіді. Обмежується значенням `≤` тайм-ауту запуску. |
|
||||
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Межа часу для teardown Docker. Серед видимих збоїв — команда відновлення `docker compose ... down --remove-orphans`. |
|
||||
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | Перевизначає образ homeserver під час перевірки з іншою версією Tuwunel. |
|
||||
| `OPENCLAW_QA_MATRIX_PROGRESS` | увімкнено | `0` вимикає рядки поступу `[matrix-qa] ...` у stderr. `1` примусово вмикає їх. |
|
||||
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | відредаговано | `1` зберігає тіло повідомлення та `formatted_body` у `matrix-qa-observed-events.json`. Типова поведінка — редагування, щоб артефакти CI залишалися безпечними. |
|
||||
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | вимкнено | `1` пропускає детермінований `process.exit` після запису артефактів. Типова поведінка примусово завершує процес, оскільки native crypto-дескриптори `matrix-js-sdk` можуть утримувати event loop активним після завершення запису артефактів. |
|
||||
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | не задано | Якщо ця змінна встановлена зовнішнім запускальником (наприклад, `scripts/run-node.mjs`), Matrix QA повторно використовує цей шлях до журналу замість запуску власного `tee`. |
|
||||
|
||||
## Вихідні артефакти
|
||||
## Артефакти виводу
|
||||
|
||||
Записуються до `--output-dir`:
|
||||
|
||||
- `matrix-qa-report.md` — Markdown-звіт протоколу (що пройшло, не пройшло, було пропущено і чому).
|
||||
- `matrix-qa-summary.json` — структурований підсумок, придатний для розбору в CI та для dashboard.
|
||||
- `matrix-qa-observed-events.json` — спостережені події Matrix від клієнтів driver і observer. Тіла повідомлень редагуються, якщо не задано `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`.
|
||||
- `matrix-qa-output.log` — об’єднаний stdout/stderr із запуску. Якщо задано `OPENCLAW_RUN_NODE_OUTPUT_LOG`, натомість повторно використовується журнал зовнішнього launcher.
|
||||
- `matrix-qa-report.md` — Markdown-звіт протоколу (що пройшло, що впало, що було пропущено і чому).
|
||||
- `matrix-qa-summary.json` — структурований підсумок, придатний для парсингу в CI та дашбордів.
|
||||
- `matrix-qa-observed-events.json` — спостережені події Matrix від клієнтів driver і observer. Тіла повідомлень редагуються, якщо не встановлено `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`; метадані approval подаються як зведення з вибраними безпечними полями та скороченим попереднім переглядом команди.
|
||||
- `matrix-qa-output.log` — об’єднаний stdout/stderr із запуску. Якщо встановлено `OPENCLAW_RUN_NODE_OUTPUT_LOG`, замість цього повторно використовується журнал зовнішнього запускальника.
|
||||
|
||||
Типовий каталог виводу — `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`, тому послідовні запуски не перезаписують один одного.
|
||||
|
||||
## Поради для тріажу
|
||||
## Поради щодо тріажу
|
||||
|
||||
- **Запуск зависає наприкінці:** native crypto handle із `matrix-js-sdk` можуть жити довше за harness. Типова поведінка примусово виконує чистий `process.exit` після запису артефактів; якщо ви встановили `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`, очікуйте, що процес може зависнути.
|
||||
- **Помилка очищення:** знайдіть надруковану recovery-команду (виклик `docker compose ... down --remove-orphans`) і запустіть її вручну, щоб звільнити порт homeserver.
|
||||
- **Нестабільні вікна негативних перевірок у CI:** зменште `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` (типово 8 с), коли CI працює швидко; збільшуйте його на повільних спільних runner.
|
||||
- **Потрібні неретаговані тіла повідомлень для bug report:** перезапустіть із `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` і додайте `matrix-qa-observed-events.json`. Вважайте отриманий артефакт чутливим.
|
||||
- **Інша версія Tuwunel:** вкажіть у `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` версію, яка тестується. У лейні зафіксовано лише типовий pinned-образ.
|
||||
- **Запуск зависає ближче до завершення:** native crypto-дескриптори `matrix-js-sdk` можуть жити довше за harness. Типова поведінка примусово виконує чистий `process.exit` після запису артефактів; якщо ви встановили `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`, очікуйте, що процес буде зависати.
|
||||
- **Помилка очищення:** знайдіть надруковану команду відновлення (виклик `docker compose ... down --remove-orphans`) і виконайте її вручну, щоб звільнити порт homeserver.
|
||||
- **Нестабільні вікна негативних перевірок у CI:** зменште `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` (типово 8 с), якщо CI швидкий; збільште його на повільних спільних runners.
|
||||
- **Потрібні неретаговані тіла повідомлень для звіту про помилку:** перезапустіть із `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` і додайте `matrix-qa-observed-events.json`. Вважайте отриманий артефакт чутливим.
|
||||
- **Інша версія Tuwunel:** вкажіть у `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` версію, яку тестуєте. У репозиторії зафіксовано лише типове закріплене значення образу.
|
||||
|
||||
## Контракт live-транспорту
|
||||
## Live-контракт транспортного рівня
|
||||
|
||||
Matrix — один із трьох live-транспортних лейнів (Matrix, Telegram, Discord), які використовують спільний контрольний список контракту, визначений у [Огляд QA → Покриття live-транспорту](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` залишається широким синтетичним набором і навмисно не входить до цієї матриці.
|
||||
Matrix — один із трьох live-лейнів транспортного рівня (Matrix, Telegram, Discord), які використовують спільний контрольний список контракту, визначений у [Огляд QA → Live-покриття транспортного рівня](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` залишається широким синтетичним набором і навмисно не входить до цієї матриці.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд QA](/uk/concepts/qa-e2e-automation) — загальний стек QA і контракт live-транспорту
|
||||
- [QA Channel](/uk/channels/qa-channel) — адаптер синтетичного каналу для сценаріїв на базі репозиторію
|
||||
- [Тестування](/uk/help/testing) — запуск тестів і додавання покриття QA
|
||||
- [Огляд QA](/uk/concepts/qa-e2e-automation) — загальний стек QA і live-контракт транспортного рівня
|
||||
- [QA Channel](/uk/channels/qa-channel) — синтетичний адаптер каналу для сценаріїв на основі репозиторію
|
||||
- [Тестування](/uk/help/testing) — запуск тестів і додавання QA-покриття
|
||||
- [Matrix](/uk/channels/matrix) — Plugin каналу, що тестується
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user