From 1520aa5369727c24eadf2d17a910de121462afb0 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 15:03:43 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/matrix-push-rules.md | 157 ++++++ docs/uk/channels/matrix.md | 734 +++++++++----------------- docs/uk/ci.md | 113 ++-- 3 files changed, 451 insertions(+), 553 deletions(-) create mode 100644 docs/uk/channels/matrix-push-rules.md diff --git a/docs/uk/channels/matrix-push-rules.md b/docs/uk/channels/matrix-push-rules.md new file mode 100644 index 000000000..3feec2360 --- /dev/null +++ b/docs/uk/channels/matrix-push-rules.md @@ -0,0 +1,157 @@ +--- +read_when: + - Налаштування тихої потокової передачі Matrix для самохостингового Synapse або Tuwunel + - Користувачі хочуть отримувати сповіщення лише про завершені блоки, а не про кожне редагування попереднього перегляду +summary: Правила push-сповіщень Matrix для тихих фіналізованих редагувань попереднього перегляду +title: Правила push-сповіщень Matrix для тихих попередніх переглядів +x-i18n: + generated_at: "2026-04-23T15:01:14Z" + model: gpt-5.4 + provider: openai + source_hash: dbfdf2552ca352858d4e8d03a2a0f5f3b420d33b01063c111c0335c0229f0534 + source_path: channels/matrix-push-rules.md + workflow: 15 +--- + +# Правила push-сповіщень Matrix для тихих попередніх переглядів + +Коли `channels.matrix.streaming` має значення `"quiet"`, OpenClaw редагує одну подію попереднього перегляду на місці й позначає фіналізоване редагування спеціальним прапорцем у вмісті. Клієнти Matrix надсилають сповіщення лише про фінальне редагування, якщо правило push для конкретного користувача відповідає цьому прапорцю. Ця сторінка призначена для операторів, які самостійно хостять Matrix і хочуть встановити це правило для кожного облікового запису одержувача. + +Якщо вам потрібна лише стандартна поведінка сповіщень Matrix, використовуйте `streaming: "partial"` або залиште потокову передачу вимкненою. Див. [Налаштування каналу Matrix](/uk/channels/matrix#streaming-previews). + +## Передумови + +- користувач-одержувач = людина, яка має отримувати сповіщення +- бот-користувач = обліковий запис OpenClaw Matrix, який надсилає відповідь +- для наведених нижче викликів API використовуйте токен доступу користувача-одержувача +- у правилі push значення `sender` має збігатися з повним MXID бот-користувача +- обліковий запис одержувача вже повинен мати справні pushers — правила тихого попереднього перегляду працюють лише тоді, коли звичайна доставка push у Matrix працює коректно + +## Кроки + + + + +```json5 +{ + channels: { + matrix: { + streaming: "quiet", + }, + }, +} +``` + + + + + Повторно використайте токен наявної сесії клієнта, якщо це можливо. Щоб випустити новий: + +```bash +curl -sS -X POST \ + "https://matrix.example.org/_matrix/client/v3/login" \ + -H "Content-Type: application/json" \ + --data '{ + "type": "m.login.password", + "identifier": { "type": "m.id.user", "user": "@alice:example.org" }, + "password": "REDACTED" + }' +``` + + + + + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushers" +``` + +Якщо pushers не повертаються, спочатку виправте звичайну доставку push у Matrix для цього облікового запису. + + + + + OpenClaw позначає фіналізовані редагування текстового попереднього перегляду через `content["com.openclaw.finalized_preview"] = true`. Встановіть правило, яке відповідає цьому маркеру, а також MXID бота як відправнику: + +```bash +curl -sS -X PUT \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + --data '{ + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, + { + "kind": "event_property_is", + "key": "content.m\\.relates_to.rel_type", + "value": "m.replace" + }, + { + "kind": "event_property_is", + "key": "content.com\\.openclaw\\.finalized_preview", + "value": true + }, + { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" }, + { "set_tweak": "highlight", "value": false } + ] + }' +``` + + Перед запуском замініть: + + - `https://matrix.example.org`: базовий URL вашого homeserver + - `$USER_ACCESS_TOKEN`: токен доступу користувача-одержувача + - `openclaw-finalized-preview-botname`: ID правила, унікальний для кожного бота й одержувача (шаблон: `openclaw-finalized-preview-`) + - `@bot:example.org`: MXID вашого бота OpenClaw, а не одержувача + + + + + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" +``` + +Потім протестуйте потокову відповідь. У тихому режимі в кімнаті показується чернетка тихого попереднього перегляду, а сповіщення надходить один раз, коли блок або хід завершується. + + + + +Щоб пізніше видалити правило, виконайте `DELETE` для того самого URL правила з токеном одержувача. + +## Примітки щодо кількох ботів + +Ключем push-правил є `ruleId`: повторний запуск `PUT` для того самого ID оновлює одне правило. Якщо кілька ботів OpenClaw надсилають сповіщення одному одержувачу, створіть окреме правило для кожного бота з різним збігом `sender`. + +Нові користувацькі правила `override` вставляються перед стандартними правилами приглушення, тому жоден додатковий параметр упорядкування не потрібен. Правило впливає лише на редагування текстового попереднього перегляду, які можна фіналізувати на місці; резервні варіанти для медіа та застарілого попереднього перегляду використовують звичайну доставку Matrix. + +## Примітки щодо homeserver + + + + Спеціальні зміни в `homeserver.yaml` не потрібні. Якщо звичайні сповіщення Matrix уже доходять до цього користувача, головний крок налаштування — це токен одержувача та виклик `pushrules`, наведений вище. + + Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно доходить до Synapse. Доставка push обробляється основним процесом або `synapse.app.pusher` / налаштованими pusher workers — переконайтеся, що вони працюють справно. + + + + + Такий самий процес, як і для Synapse; жодна специфічна для Tuwunel конфігурація для маркера фіналізованого попереднього перегляду не потрібна. + + Якщо сповіщення зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено `suppress_push_when_active`. Tuwunel додав цю опцію у версії 1.4.2 (вересень 2025 року), і вона може навмисно приглушувати push на інших пристроях, поки один пристрій активний. + + + + +## Пов’язане + +- [Налаштування каналу Matrix](/uk/channels/matrix) +- [Концепції потокової передачі](/uk/concepts/streaming) diff --git a/docs/uk/channels/matrix.md b/docs/uk/channels/matrix.md index 79f59f587..6efae2666 100644 --- a/docs/uk/channels/matrix.md +++ b/docs/uk/channels/matrix.md @@ -5,25 +5,25 @@ read_when: summary: Статус підтримки Matrix, налаштування та приклади конфігурації title: Matrix x-i18n: - generated_at: "2026-04-23T07:25:05Z" + generated_at: "2026-04-23T15:01:12Z" model: gpt-5.4 provider: openai - source_hash: 14873e9d65994138d26ad0bc1bf9bc6e00bea17f9306d592c757503d363de71a + source_hash: 2e9d4d656b47aca2dacb00e591378cb26631afc5b634074bc26e21741b418b47 source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix — це вбудований плагін каналу для OpenClaw. -Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, локацію та E2EE. +Matrix — це вбудований channel Plugin для OpenClaw. +Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, геолокацію та E2EE. -## Вбудований плагін +## Вбудований Plugin -Matrix постачається як вбудований плагін у поточних релізах OpenClaw, тому звичайним +Matrix постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайним пакетним збіркам не потрібне окреме встановлення. -Якщо ви використовуєте старішу збірку або власне встановлення без Matrix, встановіть +Якщо ви використовуєте старішу збірку або нестандартне встановлення без Matrix, встановіть його вручну: Встановлення з npm: @@ -38,22 +38,22 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -Див. [Plugins](/uk/tools/plugin), щоб дізнатися про поведінку плагінів і правила встановлення. +Див. [Plugins](/uk/tools/plugin) щодо поведінки Plugin і правил встановлення. ## Налаштування -1. Переконайтеся, що плагін Matrix доступний. +1. Переконайтеся, що Plugin Matrix доступний. - У поточних пакетних релізах OpenClaw він уже вбудований. - - У старих/власних встановленнях його можна додати вручну за допомогою наведених вище команд. + - У старіших/нестандартних встановленнях його можна додати вручну командами вище. 2. Створіть обліковий запис Matrix на своєму homeserver. 3. Налаштуйте `channels.matrix`, використовуючи один із варіантів: - `homeserver` + `accessToken`, або - `homeserver` + `userId` + `password`. 4. Перезапустіть Gateway. -5. Почніть DM з ботом або запросіть його до кімнати. +5. Почніть DM із ботом або запросіть його до кімнати. - Нові запрошення Matrix працюють лише тоді, коли це дозволяє `channels.matrix.autoJoin`. -Шляхи інтерактивного налаштування: +Інтерактивні шляхи налаштування: ```bash openclaw channels add @@ -63,25 +63,25 @@ openclaw configure --section channels Майстер Matrix запитує: - URL homeserver -- метод автентифікації: токен доступу або пароль -- ID користувача (лише для автентифікації за паролем) +- метод автентифікації: access token або пароль +- ID користувача (лише для автентифікації паролем) - необов’язкову назву пристрою - чи вмикати E2EE - чи налаштовувати доступ до кімнат і автоматичне приєднання за запрошенням -Ключові особливості майстра: +Ключові особливості роботи майстра: -- Якщо змінні середовища автентифікації Matrix вже існують і для цього облікового запису автентифікація ще не збережена в конфігурації, майстер запропонує скорочений варіант із env, щоб зберегти автентифікацію у змінних середовища. -- Назви облікових записів нормалізуються до ID облікового запису. Наприклад, `Ops Bot` стане `ops-bot`. -- Записи allowlist для DM приймають `@user:server` безпосередньо; відображувані імена працюють лише тоді, коли live-пошук у каталозі знаходить один точний збіг. -- Записи allowlist для кімнат приймають ID кімнат і псевдоніми безпосередньо. Віддавайте перевагу `!room:server` або `#alias:server`; нерозв’язані назви ігноруються під час виконання механізмом розв’язання allowlist. -- У режимі allowlist для автоматичного приєднання за запрошенням використовуйте лише стабільні цілі запрошення: `!roomId:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються. -- Щоб розв’язати назви кімнат перед збереженням, використайте `openclaw channels resolve --channel matrix "Project Room"`. +- Якщо змінні середовища для автентифікації Matrix вже існують і для цього облікового запису автентифікацію ще не збережено в конфігурації, майстер запропонує скорочений варіант із використанням env vars, щоб зберегти автентифікацію в змінних середовища. +- Назви облікових записів нормалізуються до ID облікового запису. Наприклад, `Ops Bot` стає `ops-bot`. +- Записи allowlist для DM приймають `@user:server` напряму; відображувані імена працюють лише тоді, коли live lookup каталогу знаходить один точний збіг. +- Записи allowlist для кімнат приймають ID кімнат і псевдоніми напряму. Надавайте перевагу `!room:server` або `#alias:server`; імена, які не вдалося розв’язати, ігноруються під час виконання механізмом розв’язання allowlist. +- У режимі allowlist для автоматичного приєднання за запрошенням використовуйте лише стабільні цілі запрошень: `!roomId:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються. +- Щоб розв’язати назви кімнат перед збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. Значенням за замовчуванням для `channels.matrix.autoJoin` є `off`. -Якщо залишити його невстановленим, бот не приєднуватиметься до запрошених кімнат або нових запрошень у стилі DM, тому він не з’являтиметься в нових групах чи запрошених DM, якщо ви спершу не приєднаєтеся вручну. +Якщо залишити його не заданим, бот не приєднуватиметься до запрошених кімнат або нових запрошень у стилі DM, тому він не з’являтиметься в нових групах або запрошених DM, якщо ви спочатку не приєднаєте його вручну. Установіть `autoJoin: "allowlist"` разом із `autoJoinAllowlist`, щоб обмежити, які запрошення він прийматиме, або встановіть `autoJoin: "always"`, якщо хочете, щоб він приєднувався до кожного запрошення. @@ -151,9 +151,9 @@ openclaw configure --section channels Matrix зберігає кешовані облікові дані в `~/.openclaw/credentials/matrix/`. Для облікового запису за замовчуванням використовується `credentials.json`; для іменованих облікових записів — `credentials-.json`. -Якщо там існують кешовані облікові дані, OpenClaw вважає Matrix налаштованим для setup, doctor і виявлення статусу каналу, навіть якщо поточна автентифікація не задана безпосередньо в конфігурації. +Якщо там існують кешовані облікові дані, OpenClaw вважає Matrix налаштованим для setup, doctor і виявлення статусу channel, навіть якщо поточну автентифікацію не задано безпосередньо в конфігурації. -Еквіваленти змінних середовища (використовуються, коли ключ конфігурації не задано): +Відповідники у змінних середовища (використовуються, коли ключ конфігурації не задано): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ Matrix зберігає кешовані облікові дані в `~/.opencl - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Для облікових записів не за замовчуванням використовуйте змінні середовища з областю облікового запису: +Для облікових записів, відмінних від стандартного, використовуйте змінні середовища з областю облікового запису: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -182,11 +182,11 @@ Matrix зберігає кешовані облікові дані в `~/.opencl - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` Matrix екранує розділові знаки в ID облікових записів, щоб уникнути колізій у змінних середовища з областю. -Наприклад, `-` перетворюється на `_X2D_`, тому `ops-prod` відповідає `MATRIX_OPS_X2D_PROD_*`. +Наприклад, `-` стає `_X2D_`, тому `ops-prod` мапиться на `MATRIX_OPS_X2D_PROD_*`. -Інтерактивний майстер пропонує скорочений варіант через env vars лише тоді, коли ці змінні середовища автентифікації вже присутні й для вибраного облікового запису автентифікацію Matrix ще не збережено в конфігурації. +Інтерактивний майстер пропонує скорочений варіант із env vars лише тоді, коли ці env vars автентифікації вже присутні й для вибраного облікового запису автентифікацію Matrix ще не збережено в конфігурації. -`MATRIX_HOMESERVER` не можна задати з workspace `.env`; див. [Workspace `.env` files](/uk/gateway/security). +`MATRIX_HOMESERVER` не можна задавати з workspace `.env`; див. [Workspace `.env` files](/uk/gateway/security). ## Приклад конфігурації @@ -227,15 +227,15 @@ Matrix екранує розділові знаки в ID облікових з `autoJoin` застосовується до всіх запрошень Matrix, включно із запрошеннями у стилі DM. OpenClaw не може надійно класифікувати запрошену кімнату як DM або групу в момент запрошення, тому всі запрошення спочатку проходять через `autoJoin`. -`dm.policy` застосовується після того, як бот уже приєднався і кімнату класифіковано як DM. +`dm.policy` застосовується після того, як бот приєднався і кімнату класифіковано як DM. -## Попередній перегляд потокової передачі +## Потокові прев’ю -Потокова передача відповідей у Matrix є opt-in. +Потокова передача відповідей Matrix вмикається за бажанням. -Установіть `channels.matrix.streaming` у `"partial"`, якщо хочете, щоб OpenClaw надсилав одну live-відповідь попереднього перегляду, -редагував цей попередній перегляд на місці, поки модель генерує текст, а потім завершував його, коли -відповідь буде готова: +Установіть `channels.matrix.streaming` у `"partial"`, якщо хочете, щоб OpenClaw надсилав одну live preview +відповідь, редагував це прев’ю на місці, поки модель генерує текст, а потім фіналізував його після +завершення відповіді: ```json5 { @@ -247,186 +247,32 @@ Matrix екранує розділові знаки в ID облікових з } ``` -- `streaming: "off"` — значення за замовчуванням. OpenClaw чекає фінальної відповіді та надсилає її один раз. -- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку помічника, використовуючи звичайні текстові повідомлення Matrix. Це зберігає застарілу поведінку Matrix із нотифікаціями за першим попереднім переглядом, тому стандартні клієнти можуть надсилати сповіщення за першим текстом потокового попереднього перегляду, а не за завершеним блоком. -- `streaming: "quiet"` створює одне редаговане тихе повідомлення-попередній перегляд для поточного блоку помічника. Використовуйте це лише тоді, коли ви також налаштовуєте push rules отримувача для завершених редагувань попереднього перегляду. -- `blockStreaming: true` вмикає окремі повідомлення прогресу Matrix. Якщо ввімкнено потоковий попередній перегляд, Matrix зберігає live-чернетку для поточного блоку та залишає завершені блоки як окремі повідомлення. -- Коли попередній потоковий перегляд увімкнено, а `blockStreaming` вимкнено, Matrix редагує live-чернетку на місці та фіналізує ту саму подію, коли блок або хід завершується. -- Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw припиняє потоковий попередній перегляд і повертається до звичайної фінальної доставки. -- Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застарілий попередній перегляд більше не можна безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної відповіді з медіа. -- Редагування попереднього перегляду створює додаткові виклики API Matrix. Залиште streaming вимкненим, якщо хочете максимально консервативну поведінку щодо обмеження частоти. +- `streaming: "off"` — значення за замовчуванням. OpenClaw чекає фінальну відповідь і надсилає її один раз. +- `streaming: "partial"` створює одне редаговане preview message для поточного блоку відповіді асистента, використовуючи звичайні текстові повідомлення Matrix. Це зберігає традиційну поведінку Matrix із сповіщеннями спочатку про прев’ю, тому стандартні клієнти можуть сповіщати про перший текст потокового прев’ю, а не про завершений блок. +- `streaming: "quiet"` створює одне редаговане тихе preview notice для поточного блоку відповіді асистента. Використовуйте це лише тоді, коли ви також налаштовуєте правила push для отримувачів для фіналізованих редагувань прев’ю. +- `blockStreaming: true` вмикає окремі повідомлення про прогрес Matrix. Коли потокове передавання прев’ю ввімкнено, Matrix зберігає live draft для поточного блоку та лишає завершені блоки як окремі повідомлення. +- Коли потокове передавання прев’ю ввімкнено, а `blockStreaming` вимкнено, Matrix редагує live draft на місці й фіналізує ту саму подію, коли завершується блок або хід. +- Якщо прев’ю більше не вміщується в одну подію Matrix, OpenClaw припиняє потокове передавання прев’ю і повертається до звичайної фінальної доставки. +- Відповіді з медіа, як і раніше, надсилають вкладення у звичайному режимі. Якщо застаріле прев’ю більше не можна безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної відповіді з медіа. +- Редагування прев’ю потребують додаткових викликів Matrix API. Залиште streaming вимкненим, якщо хочете найконсервативнішу поведінку щодо обмеження частоти. -`blockStreaming` сам по собі не вмикає чернетки попереднього перегляду. -Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань попереднього перегляду; потім додавайте `blockStreaming: true`, лише якщо ви також хочете, щоб завершені блоки помічника залишалися видимими як окремі повідомлення прогресу. +`blockStreaming` сам по собі не вмикає чернеткові прев’ю. +Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагування прев’ю; потім додавайте `blockStreaming: true` лише якщо також хочете, щоб завершені блоки асистента лишалися видимими як окремі повідомлення про прогрес. -Якщо вам потрібні стандартні сповіщення Matrix без користувацьких push rules, використовуйте `streaming: "partial"` для поведінки з попереднім переглядом спочатку або залиште `streaming` вимкненим для доставки лише фінальної відповіді. Якщо `streaming: "off"`: +Якщо вам потрібні стандартні сповіщення Matrix без власних правил push, використовуйте `streaming: "partial"` для поведінки зі сповіщенням спочатку про прев’ю або залиште `streaming` вимкненим для доставки лише фінальної відповіді. За `streaming: "off"`: - `blockStreaming: true` надсилає кожен завершений блок як звичайне повідомлення Matrix зі сповіщенням. - `blockStreaming: false` надсилає лише фінальну завершену відповідь як звичайне повідомлення Matrix зі сповіщенням. -### Self-hosted push rules для тихих завершених попередніх переглядів +### Власні push rules для тихих фіналізованих прев’ю -Якщо ви використовуєте власну інфраструктуру Matrix і хочете, щоб тихі попередні перегляди сповіщали лише тоді, коли блок або -фінальна відповідь завершені, установіть `streaming: "quiet"` і додайте per-user push rule для завершених редагувань попереднього перегляду. +Тихий streaming (`streaming: "quiet"`) сповіщає отримувачів лише тоді, коли блок або хід фіналізовано — правило push для користувача має збігтися з маркером фіналізованого прев’ю. Див. [Matrix push rules for quiet previews](/uk/channels/matrix-push-rules) для повного налаштування (токен отримувача, перевірка pusher, встановлення rules, примітки для різних homeserver). -Зазвичай це налаштування на боці користувача-одержувача, а не глобальна зміна конфігурації homeserver: - -Швидка схема перед початком: - -- користувач-одержувач = людина, яка має отримати сповіщення -- користувач-бот = обліковий запис Matrix OpenClaw, який надсилає відповідь -- для наведених нижче викликів API використовуйте access token користувача-одержувача -- зіставляйте `sender` у push rule з повним MXID користувача-бота - -1. Налаштуйте OpenClaw на використання тихих попередніх переглядів: - -```json5 -{ - channels: { - matrix: { - streaming: "quiet", - }, - }, -} -``` - -2. Переконайтеся, що обліковий запис одержувача вже отримує звичайні push-сповіщення Matrix. Правила для тихих попередніх переглядів - працюють лише тоді, коли в цього користувача вже належно працюють pushers/devices. - -3. Отримайте access token користувача-одержувача. - - Використовуйте токен користувача-одержувача, а не токен бота. - - Зазвичай найпростіше повторно використати токен наявної сесії клієнта. - - Якщо потрібно створити новий токен, можна ввійти через стандартний Matrix Client-Server API: - -```bash -curl -sS -X POST \ - "https://matrix.example.org/_matrix/client/v3/login" \ - -H "Content-Type: application/json" \ - --data '{ - "type": "m.login.password", - "identifier": { - "type": "m.id.user", - "user": "@alice:example.org" - }, - "password": "REDACTED" - }' -``` - -4. Переконайтеся, що обліковий запис одержувача вже має pushers: - -```bash -curl -sS \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushers" -``` - -Якщо це повертає відсутність активних pushers/devices, спочатку виправте звичайні сповіщення Matrix, а вже потім додавайте -наведене нижче правило OpenClaw. - -OpenClaw позначає завершені редагування попереднього перегляду лише з текстом так: - -```json -{ - "com.openclaw.finalized_preview": true -} -``` - -5. Створіть override push rule для кожного облікового запису одержувача, який має отримувати ці сповіщення: - -```bash -curl -sS -X PUT \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - -H "Content-Type: application/json" \ - --data '{ - "conditions": [ - { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, - { - "kind": "event_property_is", - "key": "content.m\\.relates_to.rel_type", - "value": "m.replace" - }, - { - "kind": "event_property_is", - "key": "content.com\\.openclaw\\.finalized_preview", - "value": true - }, - { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } - ], - "actions": [ - "notify", - { "set_tweak": "sound", "value": "default" }, - { "set_tweak": "highlight", "value": false } - ] - }' -``` - -Замініть ці значення перед виконанням команди: - -- `https://matrix.example.org`: базовий URL вашого homeserver -- `$USER_ACCESS_TOKEN`: access token користувача-одержувача -- `openclaw-finalized-preview-botname`: ID правила, унікальний для цього бота для цього користувача-одержувача -- `@bot:example.org`: MXID вашого Matrix-бота OpenClaw, а не MXID користувача-одержувача - -Важливо для конфігурацій із кількома ботами: - -- Push rules прив’язані до `ruleId`. Повторний запуск `PUT` для того самого ID правила оновлює саме це правило. -- Якщо один користувач-одержувач має отримувати сповіщення від кількох облікових записів Matrix бота OpenClaw, створіть одне правило на кожного бота з унікальним ID правила для кожного збігу `sender`. -- Простий шаблон — `openclaw-finalized-preview-`, наприклад `openclaw-finalized-preview-ops` або `openclaw-finalized-preview-support`. - -Правило перевіряється відносно відправника події: - -- автентифікуйтеся за допомогою токена користувача-одержувача -- зіставте `sender` з MXID бота OpenClaw - -6. Переконайтеся, що правило існує: - -```bash -curl -sS \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" -``` - -7. Протестуйте потокову відповідь. У тихому режимі кімната повинна показати тихий чернетковий попередній перегляд, а фінальне - редагування на місці має надіслати сповіщення, щойно блок або хід завершиться. - -Якщо вам потрібно пізніше видалити правило, видаліть той самий ID правила за допомогою токена користувача-одержувача: - -```bash -curl -sS -X DELETE \ - -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ - "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" -``` - -Примітки: - -- Створюйте правило за допомогою access token користувача-одержувача, а не токена бота. -- Нові користувацькі правила `override` вставляються перед стандартними правилами приглушення, тому додатковий параметр порядку не потрібен. -- Це впливає лише на редагування попереднього перегляду лише з текстом, які OpenClaw може безпечно фіналізувати на місці. Резервні варіанти для медіа та застарілого попереднього перегляду, як і раніше, використовують звичайну доставку Matrix. -- Якщо `GET /_matrix/client/v3/pushers` не показує pushers, то для цього облікового запису/пристрою користувач ще не має працездатної доставки push-сповіщень Matrix. - -#### Synapse - -Для Synapse наведеного вище налаштування зазвичай достатньо саме по собі: - -- Жодних спеціальних змін у `homeserver.yaml` для сповіщень про фіналізований попередній перегляд OpenClaw не потрібно. -- Якщо ваше розгортання Synapse вже надсилає звичайні push-сповіщення Matrix, то токен користувача + наведений вище виклик `pushrules` є основним кроком налаштування. -- Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно доходить до Synapse. -- Якщо ви використовуєте workers у Synapse, переконайтеся, що pushers працюють справно. Доставка push-сповіщень обробляється головним процесом або `synapse.app.pusher` / налаштованими pusher workers. - -#### Tuwunel - -Для Tuwunel використовуйте той самий процес налаштування та виклик API `pushrules`, показаний вище: - -- Жодна специфічна для Tuwunel конфігурація для самого маркера фіналізованого попереднього перегляду не потрібна. -- Якщо звичайні сповіщення Matrix для цього користувача вже працюють, то токен користувача + наведений вище виклик `pushrules` є основним кроком налаштування. -- Якщо сповіщення начебто зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено `suppress_push_when_active`. Tuwunel додав цей параметр у Tuwunel 1.4.2 12 вересня 2025 року, і він може навмисно приглушувати push-сповіщення на інших пристроях, поки один пристрій активний. - -## Кімнати бот-до-бота +## Кімнати bot-to-bot За замовчуванням повідомлення Matrix від інших налаштованих облікових записів Matrix OpenClaw ігноруються. -Використовуйте `allowBots`, якщо ви навмисно хочете міжагентський трафік Matrix: +Використовуйте `allowBots`, якщо ви навмисно хочете дозволити міжагентний трафік Matrix: ```json5 { @@ -443,17 +289,17 @@ curl -sS -X DELETE \ } ``` -- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів Matrix ботів у дозволених кімнатах і DM. -- `allowBots: "mentions"` приймає такі повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM усе одно дозволяються. -- `groups..allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати. -- OpenClaw, як і раніше, ігнорує повідомлення від того самого ID користувача Matrix, щоб уникати циклів самовідповіді. -- Matrix тут не надає вбудованого прапорця бота; OpenClaw трактує "bot-authored" як "надіслано іншим налаштованим обліковим записом Matrix на цьому Gateway OpenClaw". +- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і DM. +- `allowBots: "mentions"` приймає такі повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM як і раніше дозволені. +- `groups..allowBots` перевизначає параметр рівня облікового запису для однієї кімнати. +- OpenClaw все одно ігнорує повідомлення від того самого ID користувача Matrix, щоб уникнути циклів самовідповіді. +- Тут Matrix не надає вбудованого прапорця бота; OpenClaw трактує «створене ботом» як «надіслане іншим налаштованим обліковим записом Matrix на цьому Gateway OpenClaw». -Під час увімкнення трафіку бот-до-бота в спільних кімнатах використовуйте суворі allowlist кімнат і вимоги до згадувань. +Використовуйте суворі allowlist для кімнат і вимоги до згадок, коли вмикаєте трафік bot-to-bot у спільних кімнатах. ## Шифрування та верифікація -В encrypted (E2EE) кімнатах вихідні події зображень використовують `thumbnail_file`, тому попередні перегляди зображень шифруються разом із повним вкладенням. У незашифрованих кімнатах, як і раніше, використовується звичайний `thumbnail_url`. Жодної конфігурації не потрібно — плагін автоматично визначає стан E2EE. +У зашифрованих кімнатах (E2EE) вихідні події зображень використовують `thumbnail_file`, тож прев’ю зображень шифруються разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Нічого налаштовувати не потрібно — Plugin автоматично визначає стан E2EE. Увімкнення шифрування: @@ -471,92 +317,22 @@ curl -sS -X DELETE \ } ``` -Перевірка статусу верифікації: +Команди верифікації (усі приймають `--verbose` для діагностики та `--json` для машинозчитуваного виводу): -```bash -openclaw matrix verify status -``` +| Команда | Призначення | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `openclaw matrix verify status` | Перевірити стан cross-signing і верифікації пристрою | +| `openclaw matrix verify status --include-recovery-key --json` | Включити збережений recovery key | +| `openclaw matrix verify bootstrap` | Ініціалізувати cross-signing і верифікацію (див. нижче) | +| `openclaw matrix verify bootstrap --force-reset-cross-signing` | Відкинути поточну identity cross-signing і створити нову | +| `openclaw matrix verify device ""` | Верифікувати цей пристрій за допомогою recovery key | +| `openclaw matrix verify backup status` | Перевірити стан резервної копії room key | +| `openclaw matrix verify backup restore` | Відновити room keys із резервної копії на сервері | +| `openclaw matrix verify backup reset --yes` | Видалити поточну резервну копію і створити нову базову точку (може повторно створити secret storage) | -Докладний статус (повна діагностика): - -```bash -openclaw matrix verify status --verbose -``` - -Включити збережений recovery key у machine-readable вивід: - -```bash -openclaw matrix verify status --include-recovery-key --json -``` - -Ініціалізація cross-signing і стану верифікації: - -```bash -openclaw matrix verify bootstrap -``` - -Докладна діагностика bootstrap: - -```bash -openclaw matrix verify bootstrap --verbose -``` - -Примусово скинути поточну ідентичність cross-signing перед ініціалізацією: - -```bash -openclaw matrix verify bootstrap --force-reset-cross-signing -``` - -Верифікація цього пристрою за допомогою recovery key: - -```bash -openclaw matrix verify device "" -``` - -Докладні відомості про верифікацію пристрою: - -```bash -openclaw matrix verify device "" --verbose -``` - -Перевірка стану резервного копіювання ключів кімнат: - -```bash -openclaw matrix verify backup status -``` - -Докладна діагностика стану резервного копіювання: - -```bash -openclaw matrix verify backup status --verbose -``` - -Відновлення ключів кімнат із резервної копії на сервері: - -```bash -openclaw matrix verify backup restore -``` - -Докладна діагностика відновлення: - -```bash -openclaw matrix verify backup restore --verbose -``` - -Видалити поточну резервну копію на сервері та створити нову базову резервну копію. Якщо збережений -ключ резервного копіювання не вдається коректно завантажити, це скидання також може повторно створити secret storage, щоб -майбутні cold start могли завантажувати новий ключ резервного копіювання: - -```bash -openclaw matrix verify backup reset --yes -``` - -Усі команди `verify` за замовчуванням є лаконічними (включно з тихим внутрішнім логуванням SDK) і показують докладну діагностику лише з `--verbose`. -Для повного machine-readable виводу під час написання скриптів використовуйте `--json`. - -У конфігураціях із кількома обліковими записами команди Matrix CLI використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account `. -Якщо у вас налаштовано кілька іменованих облікових записів, спочатку встановіть `channels.matrix.defaultAccount`, інакше ці неявні операції CLI зупинятимуться та проситимуть вас явно вибрати обліковий запис. -Використовуйте `--account`, коли хочете, щоб операції верифікації або роботи з пристроєм явно були націлені на іменований обліковий запис: +У конфігураціях із кількома обліковими записами команди Matrix CLI використовують неявний стандартний обліковий запис Matrix, якщо ви не передасте `--account `. +Якщо ви налаштували кілька іменованих облікових записів, спочатку задайте `channels.matrix.defaultAccount`, інакше такі неявні операції CLI зупиняться й попросять вас явно вибрати обліковий запис. +Використовуйте `--account`, коли хочете, щоб операції верифікації або роботи з пристроями явно були спрямовані на іменований обліковий запис: ```bash openclaw matrix verify status --account assistant @@ -566,41 +342,32 @@ openclaw matrix devices list --account assistant Коли шифрування вимкнене або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ конфігурації цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`. -### Що означає "verified" + + + OpenClaw вважає пристрій verified лише тоді, коли його підписує ваша власна identity cross-signing. `verify status --verbose` показує три сигнали довіри: -OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифіковано вашою власною ідентичністю cross-signing. -На практиці `openclaw matrix verify status --verbose` показує три сигнали довіри: + - `Locally trusted`: довіряється лише цим клієнтом + - `Cross-signing verified`: SDK повідомляє про верифікацію через cross-signing + - `Signed by owner`: підписано вашим власним self-signing key -- `Locally trusted`: цьому пристрою довіряє лише поточний клієнт -- `Cross-signing verified`: SDK повідомляє, що пристрій верифіковано через cross-signing -- `Signed by owner`: пристрій підписано вашим власним ключем self-signing + `Verified by owner` стає `yes` лише за наявності cross-signing або підпису власника. Самої лише локальної довіри недостатньо. -`Verified by owner` стає `yes` лише тоді, коли присутня верифікація через cross-signing або підпис власника. -Локальної довіри самої по собі недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим. + -### Що робить bootstrap + + `verify bootstrap` — це команда відновлення та налаштування для зашифрованих облікових записів. По черзі вона: -`openclaw matrix verify bootstrap` — це команда відновлення та налаштування для encrypted облікових записів Matrix. -Вона послідовно виконує все наведене нижче: + - ініціалізує secret storage, повторно використовуючи наявний recovery key, коли це можливо + - ініціалізує cross-signing і завантажує відсутні публічні ключі cross-signing + - позначає й підписує через cross-signing поточний пристрій + - створює серверну резервну копію room key, якщо її ще не існує -- ініціалізує secret storage, повторно використовуючи наявний recovery key, коли це можливо -- ініціалізує cross-signing і завантажує відсутні публічні ключі cross-signing -- намагається позначити та підписати поточний пристрій через cross-signing -- створює нову серверну резервну копію ключів кімнат, якщо вона ще не існує + Якщо homeserver вимагає UIA для завантаження ключів cross-signing, OpenClaw спочатку пробує без автентифікації, потім `m.login.dummy`, потім `m.login.password` (потребує `channels.matrix.password`). Використовуйте `--force-reset-cross-signing` лише якщо свідомо відкидаєте поточну identity. -Якщо homeserver вимагає інтерактивної автентифікації для завантаження ключів cross-signing, OpenClaw спочатку намагається виконати завантаження без автентифікації, потім із `m.login.dummy`, а потім із `m.login.password`, коли налаштовано `channels.matrix.password`. + -Використовуйте `--force-reset-cross-signing` лише тоді, коли ви навмисно хочете відкинути поточну ідентичність cross-signing і створити нову. - -Якщо ви навмисно хочете відкинути поточну резервну копію ключів кімнат і почати нову -базову резервну копію для майбутніх повідомлень, використайте `openclaw matrix verify backup reset --yes`. -Робіть це лише тоді, коли ви погоджуєтеся з тим, що невідновлювана стара encrypted історія залишиться -недоступною і що OpenClaw може повторно створити secret storage, якщо поточний секрет -резервного копіювання неможливо безпечно завантажити. - -### Нова базова резервна копія - -Якщо ви хочете, щоб майбутні encrypted повідомлення й надалі працювали, і погоджуєтеся на втрату невідновлюваної старої історії, виконайте ці команди по черзі: + + Якщо ви хочете зберегти працездатність майбутніх зашифрованих повідомлень і погоджуєтеся втратити стару історію, яку неможливо відновити: ```bash openclaw matrix verify backup reset --yes @@ -608,72 +375,45 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Додайте `--account ` до кожної команди, якщо хочете явно націлити їх на іменований обліковий запис Matrix. + Додайте `--account `, щоб націлити команду на іменований обліковий запис. Це також може повторно створити secret storage, якщо поточний секрет резервної копії не вдається безпечно завантажити. -### Поведінка під час запуску + -Коли `encryption: true`, значенням за замовчуванням для `startupVerification` у Matrix є `"if-unverified"`. -Під час запуску, якщо цей пристрій усе ще не верифіковано, Matrix запитуватиме самоверифікацію в іншому клієнті Matrix, -пропускатиме дубльовані запити, якщо один уже очікує, і застосовуватиме локальний cooldown перед повторною спробою після перезапусків. -Спроби запиту, що завершилися невдачею, за замовчуванням повторюються раніше, ніж після успішного створення запиту. -Установіть `startupVerification: "off"`, щоб вимкнути автоматичні запити під час запуску, або налаштуйте `startupVerificationCooldownHours`, -якщо хочете коротше або довше вікно повторних спроб. + + За `encryption: true` значенням за замовчуванням для `startupVerification` є `"if-unverified"`. Під час запуску неверифікований пристрій запитує самоверифікацію в іншому клієнті Matrix, пропускаючи дублікати та застосовуючи cooldown. Налаштуйте це через `startupVerificationCooldownHours` або вимкніть за допомогою `startupVerification: "off"`. -Під час запуску також автоматично виконується консервативний прохід crypto bootstrap. -Цей прохід спочатку намагається повторно використати поточні secret storage та ідентичність cross-signing і уникає скидання cross-signing, якщо ви не запускаєте явний процес відновлення bootstrap. + Під час запуску також виконується консервативний прохід crypto bootstrap, який повторно використовує поточні secret storage та identity cross-signing. Якщо стан bootstrap пошкоджено, OpenClaw намагається виконати захищене відновлення навіть без `channels.matrix.password`; якщо homeserver вимагає password UIA, під час запуску журналюється попередження, але помилка не стає фатальною. Пристрої, уже підписані власником, зберігаються. -Якщо під час запуску все ще виявляється зламаний стан bootstrap, OpenClaw може спробувати захищений шлях відновлення навіть тоді, коли `channels.matrix.password` не налаштовано. -Якщо homeserver вимагає UIA на основі пароля для цього відновлення, OpenClaw записує попередження в журнал і зберігає запуск нефатальним замість переривання роботи бота. -Якщо поточний пристрій уже підписано власником, OpenClaw зберігає цю ідентичність замість автоматичного скидання. + Див. [Міграція Matrix](/uk/install/migrating-matrix) для повного процесу оновлення. -Див. [Matrix migration](/uk/install/migrating-matrix), щоб ознайомитися з повним процесом оновлення, обмеженнями, командами відновлення та поширеними повідомленнями міграції. + -### Сповіщення про верифікацію + + Matrix публікує повідомлення про життєвий цикл верифікації в сувору DM-кімнату для верифікації як повідомлення `m.notice`: запит, готовність (із підказкою «Verify by emoji»), початок/завершення та деталі SAS (emoji/десяткові), якщо вони доступні. -Matrix публікує сповіщення про життєвий цикл верифікації безпосередньо в сувору DM-кімнату верифікації як повідомлення `m.notice`. -Це включає: + Вхідні запити з іншого клієнта Matrix відстежуються й автоматично приймаються. Для самоверифікації OpenClaw автоматично запускає потік SAS і підтверджує свій бік, щойно стає доступною верифікація через emoji — вам усе одно потрібно порівняти й підтвердити «They match» у своєму клієнті Matrix. -- сповіщення про запит верифікації -- сповіщення про готовність до верифікації (з явною вказівкою "Verify by emoji") -- сповіщення про початок і завершення верифікації -- деталі SAS (emoji та десяткові числа), коли вони доступні + Системні повідомлення про верифікацію не пересилаються до конвеєра чату агента. -Вхідні запити на верифікацію з іншого клієнта Matrix відстежуються та автоматично приймаються OpenClaw. -Для сценаріїв самоверифікації OpenClaw також автоматично запускає SAS-процес, коли стає доступною верифікація за emoji, і підтверджує свою сторону. -Для запитів на верифікацію від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім чекає, поки SAS-процес продовжиться звичайним чином. -Вам усе одно потрібно порівняти emoji або десятковий SAS у своєму клієнті Matrix і підтвердити там "They match", щоб завершити верифікацію. + -OpenClaw не приймає автоматично наосліп дубльовані self-initiated процеси. Під час запуску пропускається створення нового запиту, якщо запит на самоверифікацію вже очікує. - -Сповіщення протоколу/системи верифікації не передаються в конвеєр чату агента, тому вони не створюють `NO_REPLY`. - -### Гігієна пристроїв - -Старі пристрої Matrix, якими керував OpenClaw, можуть накопичуватися в обліковому записі та ускладнювати розуміння довіри в encrypted кімнатах. -Отримайте їх список за допомогою: + + Старі пристрої під керуванням OpenClaw можуть накопичуватися. Перелічіть і приберіть застарілі: ```bash openclaw matrix devices list -``` - -Видаліть застарілі пристрої Matrix, якими керував OpenClaw, за допомогою: - -```bash openclaw matrix devices prune-stale ``` -### Crypto store + -Matrix E2EE використовує офіційний Rust crypto path `matrix-js-sdk` у Node, із `fake-indexeddb` як shim для IndexedDB. Crypto state зберігається у файл snapshot (`crypto-idb-snapshot.json`) і відновлюється під час запуску. Файл snapshot є чутливим runtime state і зберігається з обмежувальними правами доступу до файлу. + + Matrix E2EE використовує офіційний шлях Rust crypto з `matrix-js-sdk` із `fake-indexeddb` як shim для IndexedDB. Стан crypto зберігається в `crypto-idb-snapshot.json` (з обмежувальними правами доступу до файла). -Зашифрований runtime state розміщується в коренях для кожного облікового запису та користувача з хешем токена в -`~/.openclaw/matrix/accounts//__//`. -Цей каталог містить sync store (`bot-storage.json`), crypto store (`crypto/`), -файл recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`), -прив’язки тредів (`thread-bindings.json`) і стан startup verification (`startup-verification.json`). -Коли токен змінюється, але ідентичність облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний -корінь для цього кортежу обліковий запис/homeserver/користувач, щоб попередній sync state, crypto state, прив’язки тредів -і стан startup verification залишалися доступними. + Зашифрований стан виконання зберігається в `~/.openclaw/matrix/accounts//__//` і містить sync store, crypto store, recovery key, знімок IDB, прив’язки тредів і стан startup verification. Коли токен змінюється, але identity облікового запису лишається тією самою, OpenClaw повторно використовує найкращий наявний кореневий каталог, тож попередній стан лишається видимим. + + + ## Керування профілем @@ -686,35 +426,35 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png Додайте `--account `, якщо хочете явно націлити команду на іменований обліковий запис Matrix. -Matrix безпосередньо приймає URL аватарів `mxc://`. Якщо ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його до Matrix, а потім зберігає розв’язаний URL `mxc://` назад у `channels.matrix.avatarUrl` (або у перевизначення вибраного облікового запису). +Matrix напряму приймає URL аватарів `mxc://`. Коли ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його в Matrix, а потім зберігає розв’язаний URL `mxc://` назад у `channels.matrix.avatarUrl` (або у вибране перевизначення облікового запису). ## Треди -Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилання через message-tool. +Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилання message-tool. -- `dm.sessionScope: "per-user"` (типове значення) зберігає маршрутизацію DM Matrix в області відправника, тому кілька кімнат DM можуть спільно використовувати одну сесію, якщо вони розв’язуються до того самого співрозмовника. -- `dm.sessionScope: "per-room"` ізолює кожну кімнату DM Matrix у власний ключ сесії, при цьому все ще використовуються звичайні перевірки автентифікації DM і allowlist. -- Явні прив’язки розмов Matrix, як і раніше, мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибрану ними цільову сесію. -- `threadReplies: "off"` зберігає відповіді на верхньому рівні та прив’язує вхідні повідомлення з тредів до батьківської сесії. +- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію DM Matrix в області відправника, тому кілька DM-кімнат можуть ділити одну сесію, якщо вони розв’язуються до того самого співрозмовника. +- `dm.sessionScope: "per-room"` ізолює кожну DM-кімнату Matrix у власний ключ сесії, як і раніше використовуючи звичайні перевірки автентифікації та allowlist для DM. +- Явні прив’язки розмов Matrix усе одно мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибрану цільову сесію. +- `threadReplies: "off"` залишає відповіді на верхньому рівні та зберігає вхідні повідомлення в треді в батьківській сесії. - `threadReplies: "inbound"` відповідає всередині треду лише тоді, коли вхідне повідомлення вже було в цьому треді. -- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, коренем якого є повідомлення-тригер, і маршрутизує цю розмову через відповідну сесію з областю треду від першого повідомлення-тригера. -- `dm.threadReplies` перевизначає налаштування верхнього рівня лише для DM. Наприклад, ви можете ізолювати треди в кімнатах, залишивши DM пласкими. -- Вхідні повідомлення в тредах включають кореневе повідомлення треду як додатковий контекст агента. -- Надсилання через message-tool автоматично успадковує поточний тред Matrix, коли ціль — та сама кімната або та сама ціль DM користувача, якщо не вказано явний `threadId`. -- Повторне використання тієї самої цілі DM користувача для тієї самої сесії спрацьовує лише тоді, коли метадані поточної сесії підтверджують того самого співрозмовника DM в тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації в області користувача. -- Коли OpenClaw бачить, що кімната DM Matrix конфліктує з іншою кімнатою DM у межах тієї самої спільної сесії DM Matrix, він публікує одноразове `m.notice` у цій кімнаті з аварійним варіантом `/focus`, коли прив’язки тредів увімкнені, і з підказкою `dm.sessionScope`. -- Runtime-прив’язки тредів підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до треду `/acp spawn` працюють у кімнатах і DM Matrix. -- `/focus` верхнього рівня в кімнаті/DM Matrix створює новий тред Matrix і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. -- Виконання `/focus` або `/acp spawn --thread here` всередині наявного треду Matrix натомість прив’язує цей поточний тред. +- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, вкоріненому у повідомленні-тригері, і спрямовує цю розмову через відповідну сесію з областю треду від першого повідомлення-тригера. +- `dm.threadReplies` перевизначає параметр верхнього рівня лише для DM. Наприклад, ви можете ізолювати треди в кімнатах, залишаючи DM пласкими. +- Вхідні повідомлення в треді включають кореневе повідомлення треду як додатковий контекст агента. +- Надсилання через message-tool автоматично успадковує поточний тред Matrix, коли ціллю є та сама кімната або та сама DM-ціль користувача, якщо явно не задано `threadId`. +- Повторне використання тієї самої DM-цілі користувача в межах однієї сесії спрацьовує лише тоді, коли метадані поточної сесії підтверджують того самого співрозмовника DM у тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації в області користувача. +- Коли OpenClaw бачить, що DM-кімната Matrix конфліктує з іншою DM-кімнатою в межах тієї самої спільної DM-сесії Matrix, він одноразово публікує `m.notice` у цій кімнаті з аварійним варіантом `/focus`, якщо прив’язки тредів увімкнено, і з підказкою `dm.sessionScope`. +- Прив’язки тредів під час виконання підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до треду `/acp spawn` працюють у кімнатах і DM Matrix. +- `/focus` на верхньому рівні в кімнаті/DM Matrix створює новий тред Matrix і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. +- Запуск `/focus` або `/acp spawn --thread here` усередині наявного треду Matrix натомість прив’язує цей поточний тред. ## Прив’язки розмов ACP -Кімнати, DM і наявні треди Matrix можна перетворити на довговічні робочі простори ACP без зміни поверхні чату. +Кімнати, DM і наявні треди Matrix можна перетворити на довготривалі робочі простори ACP без зміни поверхні чату. -Швидкий робочий процес оператора: +Швидкий операторський сценарій: -- Виконайте `/acp spawn codex --bind here` всередині DM, кімнати або наявного треду Matrix, який ви хочете й надалі використовувати. -- У DM або кімнаті Matrix верхнього рівня поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної сесії ACP. +- Запустіть `/acp spawn codex --bind here` усередині DM, кімнати або наявного треду Matrix, яким хочете й надалі користуватися. +- На верхньому рівні в DM або кімнаті Matrix поточний DM/кімната лишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної сесії ACP. - Усередині наявного треду Matrix `--bind here` прив’язує цей поточний тред на місці. - `/new` і `/reset` скидають ту саму прив’язану сесію ACP на місці. - `/acp close` закриває сесію ACP і видаляє прив’язку. @@ -726,7 +466,7 @@ Matrix підтримує нативні треди Matrix як для авто ### Конфігурація прив’язки тредів -Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для конкретного каналу: +Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для окремого channel: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -734,29 +474,29 @@ Matrix успадковує глобальні значення за замов - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Прапорці створення з прив’язкою до треду в Matrix є opt-in: +Прапорці створення для прив’язаних до тредів сесій Matrix є opt-in: -- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити `/focus` верхнього рівня створювати й прив’язувати нові треди Matrix. +- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити `/focus` на верхньому рівні створювати й прив’язувати нові треди Matrix. - Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати сесії ACP до тредів Matrix. ## Реакції -Matrix підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні реакції підтвердження. +Matrix підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні реакції-підтвердження. -- Інструменти вихідних реакцій керуються `channels["matrix"].actions.reactions`. +- Інструментарій вихідних реакцій контролюється через `channels["matrix"].actions.reactions`. - `react` додає реакцію до конкретної події Matrix. -- `reactions` перелічує поточне зведення реакцій для конкретної події Matrix. +- `reactions` показує поточне зведення реакцій для конкретної події Matrix. - `emoji=""` видаляє власні реакції облікового запису бота на цю подію. -- `remove: true` видаляє лише вказану emoji-реакцію з облікового запису бота. +- `remove: true` видаляє лише вказану реакцію emoji з облікового запису бота. -Область реакцій підтвердження визначається у стандартному порядку розв’язання OpenClaw: +Область застосування реакцій-підтверджень визначається у стандартному порядку OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- резервний emoji з ідентичності агента +- резервний emoji з identity агента -Область дії реакції підтвердження визначається в такому порядку: +Область дії реакції-підтвердження визначається в такому порядку: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -766,32 +506,32 @@ Matrix підтримує вихідні дії реакцій, вхідні с - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` -- типове значення: `own` +- значення за замовчуванням: `own` Поведінка: -- `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони націлені на повідомлення Matrix, створені ботом. +- `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони спрямовані на повідомлення Matrix, створені ботом. - `reactionNotifications: "off"` вимикає системні події реакцій. -- Видалення реакцій не синтезуються в системні події, оскільки Matrix показує їх як редагування, а не як окремі видалення `m.reaction`. +- Видалення реакцій не синтезується в системні події, оскільки Matrix показує їх як редагування, а не як окремі видалення `m.reaction`. ## Контекст історії -- `channels.matrix.historyLimit` визначає, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення кімнати Matrix запускає агента. Якщо не задано, використовується `messages.groupChat.historyLimit`; якщо не задано жодне з них, ефективним значенням за замовчуванням є `0`. Установіть `0`, щоб вимкнути. -- Історія кімнати Matrix стосується лише кімнати. DM і далі використовують звичайну історію сесії. -- Історія кімнати Matrix — лише pending: OpenClaw буферизує повідомлення кімнати, які ще не спричинили відповідь, а потім фіксує це вікно, коли надходить згадка або інший тригер. -- Поточне повідомлення-тригер не включається до `InboundHistory`; воно залишається в основному вхідному тілі для цього ходу. -- Повторні спроби для тієї самої події Matrix повторно використовують початковий snapshot історії, а не зсуваються вперед до новіших повідомлень кімнати. +- `channels.matrix.historyLimit` визначає, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення в кімнаті Matrix запускає агента. Використовує резервне значення з `messages.groupChat.historyLimit`; якщо обидва не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути. +- Історія кімнат Matrix обмежується лише кімнатою. DM і далі використовують звичайну історію сесії. +- Історія кімнат Matrix працює лише для очікуваних повідомлень: OpenClaw буферизує повідомлення кімнати, які ще не спричинили відповідь, а потім фіксує це вікно, коли надходить згадка або інший тригер. +- Поточне повідомлення-тригер не включається в `InboundHistory`; воно лишається в основному вхідному тілі для цього ходу. +- Повторні спроби для тієї самої події Matrix повторно використовують початковий знімок історії замість того, щоб зсуватися вперед до новіших повідомлень кімнати. ## Видимість контексту -Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, такого як отриманий текст відповіді, корені тредів і pending history. +Matrix підтримує спільний механізм керування `contextVisibility` для додаткового контексту кімнати, такого як отриманий текст відповіді, корені тредів і очікувана історія. -- `contextVisibility: "all"` — типове значення. Додатковий контекст зберігається як отримано. +- `contextVisibility: "all"` — значення за замовчуванням. Додатковий контекст зберігається в отриманому вигляді. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist для кімнати/користувача. - `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну цитовану відповідь. -Це налаштування впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення запускати відповідь. -Авторизація тригера, як і раніше, визначається налаштуваннями `groupPolicy`, `groups`, `groupAllowFrom` і політикою DM. +Цей параметр впливає на видимість додаткового контексту, а не на те, чи саме вхідне повідомлення може запустити відповідь. +Авторизація тригера, як і раніше, визначається через `groupPolicy`, `groups`, `groupAllowFrom` і параметри політики DM. ## Політика DM і кімнат @@ -816,28 +556,28 @@ Matrix підтримує спільний елемент керування `co } ``` -Див. [Groups](/uk/channels/groups), щоб дізнатися про поведінку керування згадуваннями та allowlist. +Див. [Groups](/uk/channels/groups) щодо поведінки обмеження за згадками та allowlist. -Приклад pairing для DM Matrix: +Приклад pairing для Matrix DM: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Якщо не схвалений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий pending pairing code і може знову надіслати відповідь-нагадування після короткого cooldown замість створення нового коду. +Якщо непідтверджений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий очікуваний код pairing і може знову надіслати нагадування після короткого cooldown, замість того щоб створювати новий код. -Див. [Pairing](/uk/channels/pairing), щоб ознайомитися зі спільним процесом pairing для DM і схемою зберігання. +Див. [Pairing](/uk/channels/pairing) щодо спільного процесу pairing для DM і структури зберігання. ## Відновлення direct room -Якщо стан direct-message виходить із синхронізації, OpenClaw може отримати застарілі відображення `m.direct`, які вказують на старі solo rooms замість активного DM. Переглянути поточне відображення для співрозмовника можна так: +Якщо стан direct message розсинхронізується, OpenClaw може отримати застарілі зіставлення `m.direct`, які вказують на старі одиночні кімнати замість актуального DM. Перегляньте поточне зіставлення для співрозмовника за допомогою: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Виправити його можна так: +Відновіть його командою: ```bash openclaw matrix direct repair --user-id @alice:example.org @@ -845,47 +585,47 @@ openclaw matrix direct repair --user-id @alice:example.org Процес відновлення: -- надає перевагу строгому 1:1 DM, який уже відображений у `m.direct` -- у разі відсутності використовує будь-який поточний strict 1:1 DM із цим користувачем, до якого вже виконано приєднання -- створює нову direct room і переписує `m.direct`, якщо не існує здорового DM +- надає перевагу суворому 1:1 DM, який уже зіставлено в `m.direct` +- у разі потреби переходить до будь-якого поточного приєднаного суворого 1:1 DM із цим користувачем +- створює нову direct room і переписує `m.direct`, якщо справного DM не існує -Процес відновлення не видаляє старі кімнати автоматично. Він лише вибирає здоровий DM і оновлює відображення, щоб нові надсилання Matrix, сповіщення про верифікацію та інші direct-message потоки знову націлювалися на правильну кімнату. +Процес відновлення не видаляє старі кімнати автоматично. Він лише вибирає справний DM і оновлює зіставлення, щоб нові надсилання Matrix, сповіщення про верифікацію та інші потоки direct message знову спрямовувалися до правильної кімнати. -## Підтвердження exec +## Схвалення exec -Matrix може виступати як нативний клієнт підтвердження для облікового запису Matrix. Нативні -елементи керування маршрутизацією DM/каналу, як і раніше, знаходяться в конфігурації підтвердження exec: +Matrix може виступати нативним клієнтом схвалення для облікового запису Matrix. Нативні +перемикачі маршрутизації DM/channel, як і раніше, розміщуються в конфігурації схвалення exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (необов’язково; якщо не задано, використовується `channels.matrix.dm.allowFrom`) -- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, типове значення: `dm`) +- `channels.matrix.execApprovals.approvers` (необов’язково; використовує резервне значення з `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Схвалювачами мають бути ID користувачів Matrix, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні підтвердження, коли `enabled` не задано або дорівнює `"auto"` і принаймні одного схвалювача можна розв’язати. Підтвердження exec спочатку використовують `execApprovals.approvers` і можуть повертатися до `channels.matrix.dm.allowFrom`. Підтвердження Plugin авторизуються через `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт підтвердження. Інакше запити на підтвердження повертаються до інших налаштованих маршрутів підтвердження або до резервної політики підтвердження. +Схвалювачі мають бути ID користувачів Matrix, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні схвалення, коли `enabled` не задано або дорівнює `"auto"`, і можна розв’язати принаймні одного схвалювача. Схвалення exec спочатку використовують `execApprovals.approvers` і можуть використовувати резервне значення з `channels.matrix.dm.allowFrom`. Схвалення Plugin авторизуються через `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт схвалення. Інакше запити на схвалення використовують резервні інші налаштовані маршрути схвалення або політику резервного оброблення схвалень. -Нативна маршрутизація Matrix підтримує обидва типи підтверджень: +Нативна маршрутизація Matrix підтримує обидва типи схвалень: -- `channels.matrix.execApprovals.*` керує нативним режимом fanout для DM/каналу для запитів підтвердження Matrix. -- Підтвердження exec використовують набір схвалювачів exec із `execApprovals.approvers` або `channels.matrix.dm.allowFrom`. -- Підтвердження Plugin використовують allowlist DM Matrix із `channels.matrix.dm.allowFrom`. -- Скорочення через реакції Matrix і оновлення повідомлень застосовуються як до підтверджень exec, так і до підтверджень Plugin. +- `channels.matrix.execApprovals.*` керує нативним режимом fanout для DM/channel у Matrix для запитів на схвалення. +- Схвалення exec використовують набір схвалювачів exec із `execApprovals.approvers` або `channels.matrix.dm.allowFrom`. +- Схвалення Plugin використовують allowlist DM Matrix з `channels.matrix.dm.allowFrom`. +- Скорочення через реакції Matrix і оновлення повідомлень застосовуються як до схвалень exec, так і до схвалень Plugin. Правила доставки: -- `target: "dm"` надсилає запити на підтвердження в DM схвалювачів -- `target: "channel"` надсилає запит назад у вихідну кімнату або DM Matrix -- `target: "both"` надсилає запит у DM схвалювачів і в початкову кімнату або DM Matrix +- `target: "dm"` надсилає запити на схвалення в DM схвалювачів +- `target: "channel"` надсилає запит назад до вихідної кімнати або DM Matrix +- `target: "both"` надсилає і в DM схвалювачів, і до вихідної кімнати або DM Matrix -Запити на підтвердження Matrix додають скорочення реакцій до основного повідомлення підтвердження: +Запити на схвалення в Matrix додають скорочення-реакції до основного повідомлення схвалення: - `✅` = дозволити один раз -- `❌` = відхилити -- `♾️` = дозволити завжди, якщо це рішення дозволене ефективною політикою exec +- `❌` = заборонити +- `♾️` = дозволити завжди, якщо таке рішення дозволене ефективною політикою exec -Схвалювачі можуть реагувати на це повідомлення або використовувати резервні slash-команди: `/approve allow-once`, `/approve allow-always` або `/approve deny`. +Схвалювачі можуть реагувати на це повідомлення або використовувати резервні slash commands: `/approve allow-once`, `/approve allow-always` або `/approve deny`. -Лише розв’язані схвалювачі можуть схвалювати або відхиляти. Для підтверджень exec доставка в канал включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. +Лише розв’язані схвалювачі можуть дозволяти або забороняти. Для схвалень exec доставка через channel включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. Перевизначення для окремого облікового запису: @@ -893,11 +633,11 @@ Matrix може виступати як нативний клієнт підтв Пов’язана документація: [Exec approvals](/uk/tools/exec-approvals) -## Slash-команди +## Slash commands -Slash-команди Matrix (наприклад `/new`, `/reset`, `/model`) працюють безпосередньо в DM. У кімнатах OpenClaw також розпізнає slash-команди, перед якими стоїть власна згадка Matrix бота, тому `@bot:server /new` запускає шлях команди без потреби в користувацькому regex для згадок. Це дає змогу боту лишатися чутливим до повідомлень у стилі кімнат `@mention /command`, які Element і подібні клієнти надсилають, коли користувач вибирає бота через tab-complete перед введенням команди. +Slash commands Matrix (наприклад `/new`, `/reset`, `/model`) працюють безпосередньо в DM. У кімнатах OpenClaw також розпізнає slash commands, перед якими стоїть власна згадка Matrix бота, тож `@bot:server /new` запускає шлях команд без потреби в спеціальному regex для згадок. Це дає змогу боту реагувати на публікації у стилі кімнати `@mention /command`, які Element та подібні клієнти створюють, коли користувач автодоповнює бота перед введенням команди. -Правила авторизації, як і раніше, застосовуються: відправники команд повинні відповідати політикам allowlist/owner для DM або кімнат так само, як і для звичайних повідомлень. +Правила авторизації, як і раніше, діють: відправники команд мають відповідати політикам allowlist/owner для DM або кімнат так само, як і для звичайних повідомлень. ## Кілька облікових записів @@ -929,24 +669,24 @@ Slash-команди Matrix (наприклад `/new`, `/reset`, `/model`) пр } ``` -Значення верхнього рівня `channels.matrix` працюють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис не перевизначає їх. -Ви можете обмежити успадковані записи кімнат одним обліковим записом Matrix за допомогою `groups..account`. -Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` і далі працюють, коли обліковий запис за замовчуванням налаштовано безпосередньо на верхньому рівні `channels.matrix.*`. -Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей обліковий запис за замовчуванням має актуальну автентифікацію (`homeserver` плюс `accessToken`, або `homeserver` плюс `userId` і `password`); іменовані облікові записи все одно можуть залишатися доступними через `homeserver` плюс `userId`, коли кешовані облікові дані пізніше задовольняють автентифікацію. -Якщо Matrix уже має рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, відновлення/підвищення з одного облікового запису до кількох зберігає цей обліковий запис замість створення нового запису `accounts.default`. У цей підвищений обліковий запис переносяться лише ключі автентифікації/bootstrap Matrix; спільні ключі політики доставки залишаються на верхньому рівні. -Установіть `defaultAccount`, якщо хочете, щоб OpenClaw надавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probing і операцій CLI. -Якщо налаштовано кілька облікових записів Matrix і один із їхніх id — `default`, OpenClaw неявно використовує цей обліковий запис, навіть якщо `defaultAccount` не задано. -Якщо ви налаштовуєте кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account ` для команд CLI, які покладаються на неявний вибір облікового запису. -Передавайте `--account ` до `openclaw matrix verify ...` і `openclaw matrix devices ...`, якщо хочете перевизначити цей неявний вибір для однієї команди. +Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис їх не перевизначає. +Ви можете обмежити успадковані записи кімнат одним обліковим записом Matrix через `groups..account`. +Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` і далі працюють, коли стандартний обліковий запис налаштовано безпосередньо на верхньому рівні `channels.matrix.*`. +Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний стандартний обліковий запис. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей стандартний обліковий запис має актуальну автентифікацію (`homeserver` плюс `accessToken`, або `homeserver` плюс `userId` і `password`); іменовані облікові записи все одно можуть лишатися доступними для виявлення через `homeserver` плюс `userId`, якщо кешовані облікові дані задовольнять автентифікацію пізніше. +Якщо Matrix уже має рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, відновлення/налаштування під час переходу з одного облікового запису на кілька зберігає цей обліковий запис замість створення нового запису `accounts.default`. До цього підвищеного облікового запису переміщуються лише ключі автентифікації/bootstrap Matrix; спільні ключі політики доставки лишаються на верхньому рівні. +Установіть `defaultAccount`, якщо хочете, щоб OpenClaw надавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probe і операцій CLI. +Якщо налаштовано кілька облікових записів Matrix і один із їхніх ID дорівнює `default`, OpenClaw неявно використовує цей обліковий запис, навіть якщо `defaultAccount` не задано. +Якщо ви налаштували кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account ` для команд CLI, що покладаються на неявний вибір облікового запису. +Передавайте `--account ` до `openclaw matrix verify ...` і `openclaw matrix devices ...`, коли хочете перевизначити цей неявний вибір для однієї команди. -Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels), щоб ознайомитися зі спільним шаблоном для кількох облікових записів. +Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels) щодо спільного шаблону для кількох облікових записів. ## Приватні/LAN homeserver За замовчуванням OpenClaw блокує приватні/внутрішні homeserver Matrix для захисту від SSRF, якщо ви -явно не дозволите це для кожного облікового запису окремо. +явно не ввімкнете це окремо для кожного облікового запису. -Якщо ваш homeserver працює на localhost, IP LAN/Tailscale або внутрішньому імені хоста, увімкніть +Якщо ваш homeserver працює на localhost, IP-адресі LAN/Tailscale або внутрішньому hostname, увімкніть `network.dangerouslyAllowPrivateNetwork` для цього облікового запису Matrix: ```json5 @@ -973,12 +713,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Цей opt-in дозволяє лише довірені приватні/внутрішні цілі. Публічні homeserver без шифрування, такі як -`http://matrix.example.org:8008`, як і раніше, блокуються. За можливості віддавайте перевагу `https://`. +Це явне ввімкнення дозволяє лише довірені приватні/внутрішні цілі. Публічні homeserver без шифрування, такі як +`http://matrix.example.org:8008`, як і раніше, блокуються. За можливості надавайте перевагу `https://`. ## Проксіювання трафіку Matrix -Якщо для вашого розгортання Matrix потрібен явний вихідний HTTP(S)-проксі, установіть `channels.matrix.proxy`: +Якщо для вашого розгортання Matrix потрібен явний вихідний HTTP(S)-проксі, задайте `channels.matrix.proxy`: ```json5 { @@ -993,85 +733,85 @@ openclaw matrix account add \ ``` Іменовані облікові записи можуть перевизначати значення верхнього рівня через `channels.matrix.accounts..proxy`. -OpenClaw використовує те саме налаштування проксі як для runtime-трафіку Matrix, так і для probes статусу облікового запису. +OpenClaw використовує той самий параметр проксі як для робочого трафіку Matrix, так і для probe стану облікового запису. ## Розв’язання цілей -Matrix приймає такі форми цілей усюди, де OpenClaw просить вказати ціль кімнати або користувача: +Matrix приймає такі форми цілей скрізь, де OpenClaw просить вас указати ціль кімнати або користувача: - Користувачі: `@user:server`, `user:@user:server` або `matrix:user:@user:server` - Кімнати: `!room:server`, `room:!room:server` або `matrix:room:!room:server` - Псевдоніми: `#alias:server`, `channel:#alias:server` або `matrix:channel:#alias:server` -Live-пошук у каталозі використовує обліковий запис Matrix, під яким виконано вхід: +Live lookup каталогу використовує обліковий запис Matrix, під яким виконано вхід: - Пошук користувачів виконує запити до каталогу користувачів Matrix на цьому homeserver. -- Пошук кімнат безпосередньо приймає явні ID кімнат і псевдоніми, а потім, у разі потреби, переходить до пошуку за назвами кімнат, до яких приєднано цей обліковий запис. -- Пошук за назвами кімнат, до яких приєднано, є best-effort. Якщо назву кімнати не вдається розв’язати до ID або псевдоніма, вона ігнорується під час runtime-розв’язання allowlist. +- Пошук кімнат напряму приймає явні ID кімнат і псевдоніми, а потім у разі потреби переходить до пошуку назв серед приєднаних кімнат цього облікового запису. +- Пошук назв серед приєднаних кімнат є best-effort. Якщо назву кімнати не вдається розв’язати до ID або псевдоніма, вона ігнорується під час розв’язання allowlist у runtime. ## Довідник конфігурації -- `enabled`: увімкнути або вимкнути канал. +- `enabled`: увімкнути або вимкнути channel. - `name`: необов’язкова мітка для облікового запису. -- `defaultAccount`: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix. +- `defaultAccount`: пріоритетний ID облікового запису, коли налаштовано кілька облікових записів Matrix. - `homeserver`: URL homeserver, наприклад `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, коли homeserver розв’язується в `localhost`, IP LAN/Tailscale або внутрішній хост, наприклад `matrix-synapse`. -- `proxy`: необов’язковий URL HTTP(S)-проксі для трафіку Matrix. Іменовані облікові записи можуть перевизначати верхньорівневе значення `proxy` власним. +- `network.dangerouslyAllowPrivateNetwork`: дозволяє цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, коли homeserver розв’язується в `localhost`, IP-адресу LAN/Tailscale або внутрішній хост на кшталт `matrix-synapse`. +- `proxy`: необов’язковий URL HTTP(S)-проксі для трафіку Matrix. Іменовані облікові записи можуть перевизначати значення верхнього рівня власним `proxy`. - `userId`: повний ID користувача Matrix, наприклад `@bot:example.org`. -- `accessToken`: токен доступу для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються як plaintext-значення, так і значення SecretRef у провайдерах env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). -- `password`: пароль для входу за паролем. Підтримуються як plaintext-значення, так і значення SecretRef. +- `accessToken`: access token для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються як прості текстові значення, так і значення SecretRef у провайдерах env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). +- `password`: пароль для входу на основі пароля. Підтримуються як прості текстові значення, так і значення SecretRef. - `deviceId`: явний ID пристрою Matrix. - `deviceName`: відображувана назва пристрою для входу за паролем. -- `avatarUrl`: збережений URL self-avatar для синхронізації профілю та оновлень через `profile set`. +- `avatarUrl`: збережений URL self-avatar для синхронізації профілю та оновлень `profile set`. - `initialSyncLimit`: максимальна кількість подій, що отримуються під час стартової синхронізації. - `encryption`: увімкнути E2EE. -- `allowlistOnly`: якщо `true`, підвищує політику кімнат `open` до `allowlist` і примусово переводить усі активні політики DM, окрім `disabled` (включно з `pairing` і `open`), у `allowlist`. Не впливає на політики `disabled`. +- `allowlistOnly`: коли має значення `true`, підвищує політику кімнат `open` до `allowlist` і примусово переводить усі активні політики DM, крім `disabled` (включно з `pairing` і `open`), у `allowlist`. Не впливає на політики `disabled`. - `allowBots`: дозволити повідомлення від інших налаштованих облікових записів Matrix OpenClaw (`true` або `"mentions"`). - `groupPolicy`: `open`, `allowlist` або `disabled`. - `contextVisibility`: режим видимості додаткового контексту кімнати (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: allowlist ID користувачів для трафіку в кімнатах. Найбезпечніше використовувати повні ID користувачів Matrix; точні збіги з каталогу розв’язуються під час запуску та коли allowlist змінюється під час роботи монітора. Нерозв’язані імена ігноруються. -- `historyLimit`: максимальна кількість повідомлень кімнати, що включаються як контекст історії групи. Якщо не задано, використовується `messages.groupChat.historyLimit`; якщо не задано жодне з них, ефективним значенням за замовчуванням є `0`. Установіть `0`, щоб вимкнути. +- `groupAllowFrom`: allowlist ID користувачів для трафіку кімнат. Найбезпечніше використовувати повні ID користувачів Matrix; точні збіги в каталозі розв’язуються під час запуску та коли allowlist змінюється під час роботи монітора. Імена, які не вдалося розв’язати, ігноруються. +- `historyLimit`: максимальна кількість повідомлень кімнати, які включаються як контекст історії групи. Використовує резервне значення з `messages.groupChat.historyLimit`; якщо обидва не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути. - `replyToMode`: `off`, `first`, `all` або `batched`. - `markdown`: необов’язкова конфігурація рендерингу Markdown для вихідного тексту Matrix. -- `streaming`: `off` (типове значення), `"partial"`, `"quiet"`, `true` або `false`. `"partial"` і `true` вмикають оновлення чернетки за принципом preview-first зі звичайними текстовими повідомленнями Matrix. `"quiet"` використовує попередні тихі сповіщення для self-hosted конфігурацій із push rules. `false` еквівалентне `"off"`. -- `blockStreaming`: `true` вмикає окремі повідомлення прогресу для завершених блоків помічника, коли активна потокова передача чернетки попереднього перегляду. +- `streaming`: `off` (за замовчуванням), `"partial"`, `"quiet"`, `true` або `false`. `"partial"` і `true` вмикають оновлення чернеток у режимі preview-first зі звичайними текстовими повідомленнями Matrix. `"quiet"` використовує прев’ю-нотатки без сповіщень для власних конфігурацій push rules. `false` еквівалентне `"off"`. +- `blockStreaming`: `true` вмикає окремі повідомлення про прогрес для завершених блоків асистента, поки активне потокове передавання чернеткового прев’ю. - `threadReplies`: `off`, `inbound` або `always`. -- `threadBindings`: перевизначення на рівні каналу для маршрутизації сесій, прив’язаних до тредів, і їхнього життєвого циклу. -- `startupVerification`: режим автоматичного запиту на самоверифікацію під час запуску (`if-unverified`, `off`). +- `threadBindings`: перевизначення для окремого channel для маршрутизації та життєвого циклу сесій, прив’язаних до тредів. +- `startupVerification`: режим автоматичного запиту самоверифікації під час запуску (`if-unverified`, `off`). - `startupVerificationCooldownHours`: cooldown перед повторною спробою автоматичних запитів на верифікацію під час запуску. -- `textChunkLimit`: розмір фрагмента вихідного повідомлення в символах (застосовується, коли `chunkMode` дорівнює `length`). -- `chunkMode`: `length` ділить повідомлення за кількістю символів; `newline` ділить за межами рядків. -- `responsePrefix`: необов’язковий рядок, що додається на початок усіх вихідних відповідей для цього каналу. -- `ackReaction`: необов’язкове перевизначення реакції підтвердження для цього каналу/облікового запису. -- `ackReactionScope`: необов’язкове перевизначення області реакції підтвердження (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `textChunkLimit`: розмір фрагмента вихідного повідомлення в символах (застосовується, коли `chunkMode` має значення `length`). +- `chunkMode`: `length` розбиває повідомлення за кількістю символів; `newline` розбиває на межах рядків. +- `responsePrefix`: необов’язковий рядок, що додається на початок усіх вихідних відповідей для цього channel. +- `ackReaction`: необов’язкове перевизначення реакції-підтвердження для цього channel/облікового запису. +- `ackReactionScope`: необов’язкове перевизначення області реакції-підтвердження (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: режим вхідних сповіщень про реакції (`own`, `off`). - `mediaMaxMb`: ліміт розміру медіа в МБ для вихідних надсилань і обробки вхідних медіа. -- `autoJoin`: політика автоматичного приєднання за запрошенням (`always`, `allowlist`, `off`). Типове значення: `off`. Застосовується до всіх запрошень Matrix, включно із запрошеннями у стилі DM. -- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` дорівнює `allowlist`. Записи псевдонімів розв’язуються до ID кімнат під час обробки запрошення; OpenClaw не довіряє стану псевдоніма, заявленому запрошеною кімнатою. +- `autoJoin`: політика автоматичного приєднання за запрошенням (`always`, `allowlist`, `off`). За замовчуванням: `off`. Застосовується до всіх запрошень Matrix, включно із запрошеннями у стилі DM. +- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` має значення `allowlist`. Записи-псевдоніми розв’язуються до ID кімнат під час обробки запрошення; OpenClaw не довіряє стану псевдоніма, заявленому запрошеною кімнатою. - `dm`: блок політики DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати й класифікував її як DM. Це не змінює того, чи буде виконано автоматичне приєднання за запрошенням. -- `dm.allowFrom`: allowlist ID користувачів для DM-трафіку. Найбезпечніше використовувати повні ID користувачів Matrix; точні збіги з каталогу розв’язуються під час запуску та коли allowlist змінюється під час роботи монітора. Нерозв’язані імена ігноруються. -- `dm.sessionScope`: `per-user` (типове значення) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна кімната DM Matrix зберігала окремий контекст, навіть якщо співрозмовник той самий. -- `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає верхньорівневе налаштування `threadReplies` як для розміщення відповідей, так і для ізоляції сесій у DM. -- `execApprovals`: нативна доставка підтверджень exec у Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: ID користувачів Matrix, яким дозволено підтверджувати exec-запити. Необов’язково, якщо `dm.allowFrom` уже визначає схвалювачів. -- `execApprovals.target`: `dm | channel | both` (типове значення: `dm`). +- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати й класифікував її як DM. Це не змінює те, чи буде запрошення автоматично прийнято. +- `dm.allowFrom`: allowlist ID користувачів для трафіку DM. Найбезпечніше використовувати повні ID користувачів Matrix; точні збіги в каталозі розв’язуються під час запуску та коли allowlist змінюється під час роботи монітора. Імена, які не вдалося розв’язати, ігноруються. +- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна DM-кімната Matrix зберігала окремий контекст, навіть якщо співрозмовник той самий. +- `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає параметр верхнього рівня `threadReplies` як для розміщення відповідей, так і для ізоляції сесій у DM. +- `execApprovals`: нативна доставка схвалень exec у Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: ID користувачів Matrix, яким дозволено схвалювати запити exec. Необов’язково, якщо `dm.allowFrom` уже визначає схвалювачів. +- `execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`). - `accounts`: іменовані перевизначення для окремих облікових записів. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів. -- `groups`: карта політик для окремих кімнат. Віддавайте перевагу ID кімнат або псевдонімам; нерозв’язані назви кімнат ігноруються під час runtime. Ідентичність сесії/групи використовує стабільний ID кімнати після розв’язання. +- `groups`: мапа політик для окремих кімнат. Надавайте перевагу ID кімнат або псевдонімам; назви кімнат, які не вдалося розв’язати, ігноруються під час виконання. Ідентичність сесії/групи використовує стабільний ID кімнати після розв’язання. - `groups..account`: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами. -- `groups..allowBots`: перевизначення на рівні кімнати для відправників-ботів із конфігурації (`true` або `"mentions"`). +- `groups..allowBots`: перевизначення рівня кімнати для відправників-ботів із конфігурації (`true` або `"mentions"`). - `groups..users`: allowlist відправників для окремої кімнати. -- `groups..tools`: перевизначення allow/deny інструментів для окремої кімнати. -- `groups..autoReply`: перевизначення на рівні кімнати для керування згадуваннями. `true` вимикає вимоги до згадувань для цієї кімнати; `false` примусово знову вмикає їх. +- `groups..tools`: перевизначення allow/deny для інструментів у межах окремої кімнати. +- `groups..autoReply`: перевизначення обмеження згадками на рівні кімнати. `true` вимикає вимоги до згадок для цієї кімнати; `false` примусово вмикає їх знову. - `groups..skills`: необов’язковий фільтр Skills на рівні кімнати. - `groups..systemPrompt`: необов’язковий фрагмент system prompt на рівні кімнати. - `rooms`: застарілий псевдонім для `groups`. -- `actions`: керування доступом до інструментів для окремих дій (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `actions`: обмеження інструментів за діями (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Пов’язане -- [Channels Overview](/uk/channels) — усі підтримувані канали +- [Channels Overview](/uk/channels) — усі підтримувані channels - [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing -- [Groups](/uk/channels/groups) — поведінка групового чату та керування згадуваннями +- [Groups](/uk/channels/groups) — поведінка групового чату та обмеження за згадками - [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень - [Security](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 95568d18e..c0f4023fa 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -2,99 +2,100 @@ read_when: - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, перевірки за областю змін і локальні еквіваленти команд +summary: Граф завдань CI, обмеження області дії та локальні еквіваленти команд title: Конвеєр CI x-i18n: - generated_at: "2026-04-23T14:40:11Z" + generated_at: "2026-04-23T15:01:12Z" model: gpt-5.4 provider: openai - source_hash: b9ab8559ab9ac781ae87f94374840a21a0c588e7cd289c6bb8a8cd07e8df6083 + source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d source_path: ci.md workflow: 15 --- # Конвеєр CI -CI запускається для кожного push до `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінювалися лише не пов’язані між собою частини. +CI запускається для кожного push у `main` і для кожного pull request. Він використовує розумне обмеження області дії, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. -QA Lab має окремі смуги CI поза основним робочим процесом із розумним визначенням області змін. Робочий процес `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне середовище виконання QA та порівнює агентні пакети mock GPT-5.4 і Opus 4.6. Робочий процес `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а смуга Telegram використовує оренди Convex. `OpenClaw Release Checks` також запускає ті самі смуги QA Lab перед погодженням релізу. +QA Lab має окремі смуги CI поза основним робочим процесом із розумним обмеженням області. Робочий процес `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне середовище виконання QA та порівнює агентні пакети mock GPT-5.4 і Opus 4.6. Робочий процес `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а смуга Telegram використовує Convex leases. `OpenClaw Release Checks` також запускає ті самі смуги QA Lab перед погодженням релізу. ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | -| `preflight` | Визначає зміни лише в документації, змінені області, змінені extensions і формує CI-маніфест | Завжди для push і PR, що не є draft | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для push і PR, що не є draft | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory з npm | Завжди для push і PR, що не є draft | -| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для push і PR, що не є draft | -| `build-artifacts` | Збирає `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-смуги коректності, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шардовані тести bundled-plugin у всьому наборі extension | Зміни, релевантні для Node | -| `checks-node-core-test` | Шарди основних Node-тестів, без смуг каналів, bundled, контрактів і extension | Зміни, релевантні для Node | -| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request зі змінами в extension | -| `check` | Шардований еквівалент основної локальної перевірки: production types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Архітектурні перевірки, перевірки меж, surface guards для extension, package-boundary і шарди gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI та smoke-тест пам’яті під час запуску | Зміни, релевантні для Node | -| `checks` | Верифікатор для тестів каналів на зібраних артефактах плюс лише для push — сумісність із Node 22 | Зміни, релевантні для Node | -| `check-docs` | Форматування документації, lint і перевірки на зламані посилання | Змінено документацію | -| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Специфічні для Windows тестові смуги | Зміни, релевантні для Windows | -| `macos-node` | Смуга TypeScript-тестів на macOS із використанням спільних зібраних артефактів | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit-тести для обох flavor плюс одна збірка debug APK | Зміни, релевантні для Android | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | +| `preflight` | Визначення змін лише в документації, змінених областей, змінених розширень і побудова маніфесту CI | Завжди для push і PR, що не є draft | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для push і PR, що не є draft | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для push і PR, що не є draft | +| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для push і PR, що не є draft | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built-artifact і багаторазово використовуваних downstream-артефактів | Зміни, релевантні Node | +| `checks-fast-core` | Швидкі Linux-смуги коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні Node | +| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extension | Зміни, релевантні Node | +| `checks-node-core-test` | Шарди тестів core Node, без смуг каналів, bundled, contract і extension | Зміни, релевантні Node | +| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request зі змінами в extension | +| `check` | Шардований еквівалент основного локального gate: production types, lint, guards, test types і strict smoke | Зміни, релевантні Node | +| `check-additional` | Шарди architecture, boundary, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні Node | +| `build-smoke` | Smoke-тести built-CLI і smoke перевірка пам’яті під час запуску | Зміни, релевантні Node | +| `checks` | Верифікатор для channel-тестів built-artifact плюс сумісність Node 22 лише для push | Зміни, релевантні Node | +| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Документацію змінено | +| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні Python Skills | +| `checks-windows` | Windows-специфічні тестові смуги | Зміни, релевантні Windows | +| `macos-node` | Смуга тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні macOS | +| `macos-swift` | Lint, збірка та тести Swift для застосунку macOS | Зміни, релевантні macOS | +| `android` | Юніт-тести Android для обох flavor плюс одна збірка debug APK | Зміни, релевантні Android | ## Порядок fail-fast -Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж почнуть працювати дорогі: +Завдання впорядковано так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запустяться дорогі: 1. `preflight` вирішує, які смуги взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються з помилкою, не чекаючи на важчі завдання з артефактами та платформними матрицями. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` завершуються швидко, не чекаючи важчих матричних завдань артефактів і платформ. 3. `build-artifacts` виконується паралельно зі швидкими Linux-смугами, щоб downstream-споживачі могли стартувати, щойно спільна збірка буде готова. -4. Після цього розгалужуються важчі платформні та runtime-смуги: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише для PR — `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +4. Після цього розгалужуються важчі платформні та runtime-смуги: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, PR-only `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка області змін міститься в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Зміни workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не змушують виконувати нативні збірки для Windows, Android або macOS; ці платформні смуги й далі визначаються лише змінами у платформному коді. -Перевірки Windows Node обмежені Windows-специфічними обгортками для process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цю смугу; не пов’язані зміни вихідного коду, plugin, install-smoke і зміни лише в тестах залишаються в Linux Node lanes, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже проходить у звичайних тестових шардах. -Окремий workflow `install-smoke` повторно використовує той самий скрипт області змін через власне завдання `preflight`. Він обчислює `run_install_smoke` на основі вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, пов’язаних з інсталяцією, пакуванням, контейнерами, production-змінами bundled extension і поверхнями core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише в тестах і лише в документації не резервують Docker workers. Його QR package smoke примусово повторно запускає шар Docker `pnpm install`, зберігаючи кеш BuildKit pnpm store, тож він і далі перевіряє встановлення без повторного завантаження залежностей на кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в цьому завданні, тож додає реальне WebSocket-покриття container-to-container без додавання ще однієї Docker-збірки. Локальний `test:docker:all` попередньо збирає один спільний live-test image і один спільний image зібраного застосунку `scripts/e2e/Dockerfile`, а потім паралельно запускає live/E2E smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте стандартний рівень паралелізму 4 через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегат за замовчуванням припиняє планувати нові pooled lanes після першого збою, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Смуги, чутливі до запуску або провайдера, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний live/E2E workflow віддзеркалює шаблон shared-image: він збирає й публікує один SHA-tagged GHCR Docker E2E image перед Docker matrix, а потім запускає матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний release-path Docker suite. QR і installer Docker-тести зберігають власні Dockerfile, зосереджені на інсталяції. Окреме завдання `docker-e2e-fast` запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс ізоляція синтетичного збою bundled-loader. Повна bundled update/channel matrix залишається ручною/для повного набору, оскільки виконує повторні реальні проходи npm update і doctor repair. +Логіка області дії міститься в `scripts/ci-changed-scope.mjs` і покрита юніт-тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни в workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують виконувати нативні збірки Windows, Android або macOS; ці платформні смуги залишаються прив’язаними до змін у вихідному коді відповідних платформ. +Перевірки Windows Node обмежені специфічними для Windows обгортками процесів/шляхів, допоміжними засобами запуску npm/pnpm/UI runner, конфігурацією менеджера пакунків і поверхнями workflow CI, які виконують цю смугу; не пов’язані зміни у вихідному коді, plugin, install-smoke і зміни лише в тестах залишаються в Linux Node lanes, щоб не резервувати Windows worker на 16 vCPU для покриття, яке вже виконується звичайними тестовими шардами. +Окремий workflow `install-smoke` повторно використовує той самий скрипт області дії через власне завдання `preflight`. Він обчислює `run_install_smoke` на основі вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, релевантних встановленню, пакуванню, контейнерам, production changes у bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які використовують Docker smoke jobs. Зміни лише в тестах і лише в документації не резервують Docker workers. Його smoke для QR package примушує Docker-шар `pnpm install` виконатися повторно, зберігаючи кеш BuildKit pnpm store, тому інсталяція все одно перевіряється без повторного завантаження залежностей під час кожного запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах цього завдання, тому додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локальна команда `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім паралельно запускає live/E2E smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте типову паралельність 4 через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор типово припиняє планувати нові pooled lanes після першої помилки, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Смуги, чутливі до запуску або провайдера, виконуються ексклюзивно після паралельного пулу. Багаторазово використовуваний workflow live/E2E відтворює шаблон shared-image: спочатку збирає і публікує один Docker E2E image із тегом SHA у GHCR перед матрицею Docker, а потім запускає матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker-набір для release-path. Тести QR та installer Docker зберігають власні Dockerfile, орієнтовані на встановлення. Окреме завдання `docker-e2e-fast` запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс ізоляція синтетичної помилки bundled-loader. Повна матриця bundled update/channel залишається ручною/для повного набору, оскільки вона виконує повторні реальні проходи npm update і doctor repair. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Ця локальна перевірка суворіше ставиться до архітектурних меж, ніж широка CI-область платформ: production-зміни в core запускають core prod typecheck плюс core-тести, зміни лише в core-тестах запускають лише core test typecheck/tests, production-зміни в extension запускають extension prod typecheck плюс extension-тести, а зміни лише в extension-тестах запускають лише extension test typecheck/tests. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extension, тому що extension залежать від цих core-контрактів. Зміни лише в release metadata під час version bump запускають цільові перевірки версії, конфігурації та root-залежностей. Невідомі зміни в root/config безпечно розширюються до всіх смуг. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо архітектурних меж, ніж широка платформа області дії CI: зміни production у core запускають перевірку типів core prod плюс тести core, зміни лише в тестах core запускають лише перевірку типів/тести core test, зміни production у extension запускають перевірку типів extension prod плюс тести extension, а зміни лише в тестах extension запускають лише перевірку типів/тести extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку до extension, оскільки extension залежать від цих контрактів core. Зміни лише в метаданих релізу з оновленням версій запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно призводять до запуску всіх смуг. -Для push матриця `checks` додає смугу `compat-node22`, яка виконується лише для push. Для pull request ця смуга пропускається, і матриця зосереджується на звичайних test/channel lanes. +Для push матриця `checks` додає смугу `compat-node22`, яка запускається лише для push. Для pull request ця смуга пропускається, і матриця зосереджується на звичайних test/channel lanes. -Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим і не резервувало зайві ранери: channel contracts запускаються як три зважені шарди, bundled plugin tests балансуються між шістьма workers для extension, невеликі core unit lanes об’єднуються в пари, auto-reply працює на трьох збалансованих workers замість шести дрібних, а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування зібраних артефактів. Широкі browser, QA, media і miscellaneous plugin tests використовують свої окремі конфігурації Vitest замість спільного plugin catch-all. Широка agents lane використовує спільний планувальник file-parallel Vitest, оскільки в ній домінують імпорт і планування, а не один повільний тестовий файл. `runtime-config` запускається разом із шардом infra core-runtime, щоб спільний runtime shard не утримував найдовший хвіст. `check-additional` тримає разом роботу package-boundary compile/canary і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guards паралельно всередині одного завдання. Gateway watch, channel tests і core support-boundary shard виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи їхні старі назви перевірок як легковагі завдання-верифікатори та водночас уникаючи двох додаткових Blacksmith workers і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane усе одно компілює цей flavor з прапорцями SMS/call-log BuildConfig, водночас уникаючи дубльованого пакування debug APK для кожного Android-релевантного push. -`extension-fast` виконується лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це дає швидкий зворотний зв’язок щодо змінених plugins під час review без резервування додаткового Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. +Найповільніші сімейства тестів Node розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів запускаються як три зважені шарди, тести bundled plugin балансуються між шістьма workers extension, малі core unit lanes об’єднані в пари, auto-reply виконується на трьох збалансованих workers замість шести малих workers, а agentic gateway/plugin configs розподілено між наявними agentic Node jobs лише для вихідного коду, замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої спеціалізовані конфігурації Vitest замість спільного універсального набору plugin. Широка смуга agents використовує спільний планувальник file-parallel Vitest, оскільки в ній домінують імпорти/планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard infra core-runtime, щоб спільний runtime shard не утримував хвіст виконання. `check-additional` тримає compile/canary роботу package-boundary разом і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard виконує свої малі незалежні guards паралельно в межах одного завдання. Gateway watch, channel tests і shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи їхні старі назви перевірок як легкі завдання-верифікатори та уникаючи двох додаткових Blacksmith workers і другої черги споживачів артефактів. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Варіант third-party не має окремого source set або manifest; його смуга юніт-тестів усе одно компілює цей flavor із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK для кожного push, релевантного Android. +`extension-fast` є лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це зберігає швидкий зворотний зв’язок щодо змінених plugin для рев’ю, не резервуючи додатковий Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. -GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий ref PR або `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не завершується з помилкою. Агреговані шардові перевірки використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні збої шард, але не стають у чергу після того, як увесь workflow уже був замінений новішим запуском. -Ключ конкурентності CI версіонований (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати нові запуски на main. +GitHub може позначати застарілі завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не завершується помилкою. Агреговані shard-перевірки використовують `!cancelled() && always()`, щоб і далі повідомляти про звичайні помилки shard, але не ставали в чергу після того, як увесь workflow уже було витіснено новішим запуском. +Ключ конкурентності CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски main. -## Ранери +## Runners -| Ранер | Завдання | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, крім lint, шарди й агрегати `check-additional`, агреговані верифікатори Node-тестів, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла стати в чергу раніше | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди Linux Node-тестів, шарди bundled plugin tests, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який досі достатньо чутливий до CPU, тож 8 vCPU коштували дорожче, ніж давали вигоди; Docker-збірки install-smoke, де час очікування в черзі для 32 vCPU коштував дорожче, ніж давав вигоди | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; для форків використовується резервний `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; для форків використовується резервний `macos-latest` | +| Runner | Завдання | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегатори (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегатори `check-additional`, агрегатори-верифікатори тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує Ubuntu на GitHub-hosted, щоб матриця Blacksmith могла стати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо чутливим до CPU, так що 8 vCPU коштували дорожче, ніж дали виграш; Docker-збірки install-smoke, де час очікування в черзі для 32 vCPU коштував дорожче, ніж давав виграш | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для fork використовується резервний варіант `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork використовується резервний варіант `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумна локальна перевірка: changed typecheck/lint/tests за boundary lane -pnpm check # швидка локальна перевірка: production tsgo + шардований lint + паралельні швидкі guards +pnpm check:changed # розумний локальний gate: changed typecheck/lint/tests за boundary lane +pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні fast guards pnpm check:test-types -pnpm check:timed # та сама перевірка з вимірюванням часу для кожного етапу +pnpm check:timed # той самий gate із таймінгами для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування документації + lint + перевірка зламаних посилань -pnpm build # зібрати dist, коли важливі смуги CI artifact/build-smoke -node scripts/ci-run-timings.mjs # підсумувати загальний час, час у черзі й найповільніші завдання +pnpm check:docs # форматування документації + lint + зламані посилання +pnpm build # збирає dist, коли важливі смуги CI artifact/build-smoke +node scripts/ci-run-timings.mjs # підсумувати wall time, час у черзі та найповільніші завдання +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI ```