diff --git a/docs/uk/channels/mattermost.md b/docs/uk/channels/mattermost.md index d912b5530..d81813782 100644 --- a/docs/uk/channels/mattermost.md +++ b/docs/uk/channels/mattermost.md @@ -2,71 +2,77 @@ read_when: - Налаштування Mattermost - Налагодження маршрутизації Mattermost +sidebarTitle: Mattermost summary: Налаштування бота Mattermost і конфігурація OpenClaw title: Mattermost x-i18n: - generated_at: "2026-04-23T20:44:25Z" + generated_at: "2026-04-26T07:59:35Z" model: gpt-5.4 provider: openai - source_hash: 09c91790a2ea0149c179031b6c08e06358cb4efa5a027778cec87b38444d7718 + source_hash: 22916fcff2eeccf53055f2ebf60fc621d595991d0ca4cd148015b61cce09c52f source_path: channels/mattermost.md workflow: 15 --- -Статус: bundled plugin (токен бота + події WebSocket). Підтримуються канали, групи та DM. -Mattermost — це платформа командного обміну повідомленнями, яку можна самостійно розгорнути; офіційний сайт із подробицями про продукт і завантаженнями: -[mattermost.com](https://mattermost.com). +Статус: вбудований Plugin (токен бота + події WebSocket). Підтримуються канали, групи та DM. Mattermost — це self-hostable платформа командного обміну повідомленнями; деталі про продукт і завантаження див. на офіційному сайті [mattermost.com](https://mattermost.com). -## Bundled plugin +## Вбудований Plugin -Mattermost постачається як bundled plugin у поточних випусках OpenClaw, тому звичайні -зібрані пакети не потребують окремого встановлення. + +Mattermost постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення. + -Якщо у вас старіша збірка або нетипове встановлення без Mattermost, -встановіть його вручну: +Якщо ви використовуєте старішу збірку або кастомне встановлення без Mattermost, встановіть його вручну: -Установлення через CLI (реєстр npm): - -```bash -openclaw plugins install @openclaw/mattermost -``` - -Локальний checkout (під час запуску з git-репозиторію): - -```bash -openclaw plugins install ./path/to/local/mattermost-plugin -``` + + + ```bash + openclaw plugins install @openclaw/mattermost + ``` + + + ```bash + openclaw plugins install ./path/to/local/mattermost-plugin + ``` + + Докладніше: [Plugins](/uk/tools/plugin) ## Швидке налаштування -1. Переконайтеся, що Plugin Mattermost доступний. - - Поточні пакетні випуски OpenClaw уже містять його в комплекті. - - У старіших/нетипових встановленнях його можна додати вручну командами вище. -2. Створіть обліковий запис бота Mattermost і скопіюйте **токен бота**. -3. Скопіюйте **базовий URL** Mattermost (наприклад, `https://chat.example.com`). -4. Налаштуйте OpenClaw і запустіть Gateway. + + + У поточних пакетованих релізах OpenClaw він уже вбудований. У старіших або кастомних встановленнях його можна додати вручну за допомогою наведених вище команд. + + + Створіть обліковий запис бота Mattermost і скопіюйте **токен бота**. + + + Скопіюйте **базову URL-адресу** Mattermost (наприклад, `https://chat.example.com`). + + + Мінімальна конфігурація: -Мінімальна конфігурація: + ```json5 + { + channels: { + mattermost: { + enabled: true, + botToken: "mm-token", + baseUrl: "https://chat.example.com", + dmPolicy: "pairing", + }, + }, + } + ``` -```json5 -{ - channels: { - mattermost: { - enabled: true, - botToken: "mm-token", - baseUrl: "https://chat.example.com", - dmPolicy: "pairing", - }, - }, -} -``` + + -## Вбудовані slash-команди +## Власні slash-команди -Вбудовані slash-команди є опціональними. Коли їх увімкнено, OpenClaw реєструє slash-команди `oc_*` через -API Mattermost і отримує callback POST-запити на HTTP-сервері Gateway. +Власні slash-команди є опційними. Коли їх увімкнено, OpenClaw реєструє slash-команди `oc_*` через API Mattermost і отримує callback POST-запити на HTTP-сервері Gateway. ```json5 { @@ -76,7 +82,7 @@ API Mattermost і отримує callback POST-запити на HTTP-серве native: true, nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Використовуйте, коли Mattermost не може напряму звернутися до Gateway (reverse proxy/публічний URL). + // Використовуйте, коли Mattermost не може напряму дістатися до Gateway (reverse proxy/публічна URL-адреса). callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, }, @@ -84,45 +90,61 @@ API Mattermost і отримує callback POST-запити на HTTP-серве } ``` -Примітки: + + + - `native: "auto"` типово вимкнено для Mattermost. Установіть `native: true`, щоб увімкнути. + - Якщо `callbackUrl` не вказано, OpenClaw формує його з хоста/порту gateway + `callbackPath`. + - Для конфігурацій з кількома обліковими записами `commands` можна задати на верхньому рівні або в `channels.mattermost.accounts..commands` (значення облікового запису перевизначають поля верхнього рівня). + - Callback-и команд перевіряються за допомогою токенів команд, які Mattermost повертає, коли OpenClaw реєструє команди `oc_*`. + - Callback-и slash-команд працюють у режимі fail closed, якщо реєстрація не вдалася, запуск був частковим або токен callback не збігається з одним із зареєстрованих команд. + + + Endpoint callback має бути доступним із сервера Mattermost. + + - Не встановлюйте `callbackUrl` у `localhost`, якщо Mattermost не працює на тому самому хості/в тому самому network namespace, що й OpenClaw. + - Не встановлюйте `callbackUrl` у базову URL-адресу вашого Mattermost, якщо ця URL-адреса не проксіює `/api/channels/mattermost/command` до OpenClaw через reverse proxy. + - Швидка перевірка: `curl https:///api/channels/mattermost/command`; GET-запит має повертати `405 Method Not Allowed` від OpenClaw, а не `404`. + + + + Якщо ваш callback спрямовано на приватні/tailnet/внутрішні адреси, установіть у Mattermost `ServiceSettings.AllowedUntrustedInternalConnections`, щоб включити хост/домен callback. + + Використовуйте записи хоста/домену, а не повні URL-адреси. -- `native: "auto"` типово вимкнено для Mattermost. Щоб увімкнути, встановіть `native: true`. -- Якщо `callbackUrl` не вказано, OpenClaw виводить його з host/port Gateway + `callbackPath`. -- Для конфігурацій із кількома обліковими записами `commands` можна задавати на верхньому рівні або під - `channels.mattermost.accounts..commands` (значення облікового запису перевизначають поля верхнього рівня). -- Command callback перевіряються за токенами окремих команд, які повертає - Mattermost, коли OpenClaw реєструє команди `oc_*`. -- Slash callback працюють у режимі fail closed, якщо реєстрація не вдалася, запуск був частковим або - токен callback не збігається з жодною із зареєстрованих команд. -- Вимога доступності: endpoint callback має бути доступним із сервера Mattermost. - - Не встановлюйте `callbackUrl` у `localhost`, якщо Mattermost не працює на тому самому host/network namespace, що й OpenClaw. - - Не встановлюйте `callbackUrl` у базовий URL вашого Mattermost, якщо цей URL не проксіює `/api/channels/mattermost/command` до OpenClaw через reverse proxy. - - Швидка перевірка: `curl https:///api/channels/mattermost/command`; GET-запит має повертати `405 Method Not Allowed` від OpenClaw, а не `404`. -- Вимога allowlist вихідних з’єднань Mattermost: - - Якщо ваш callback націлений на приватні/tailnet/internal адреси, налаштуйте Mattermost - `ServiceSettings.AllowedUntrustedInternalConnections`, щоб він містив host/domain callback. - - Використовуйте записи host/domain, а не повні URL. - Правильно: `gateway.tailnet-name.ts.net` - Неправильно: `https://gateway.tailnet-name.ts.net` -## Змінні середовища (типовий обліковий запис) + + -Установіть їх на host Gateway, якщо віддаєте перевагу env vars: +## Змінні середовища (обліковий запис за замовчуванням) + +Установіть їх на хості gateway, якщо віддаєте перевагу змінним середовища: - `MATTERMOST_BOT_TOKEN=...` - `MATTERMOST_URL=https://chat.example.com` -Env vars застосовуються лише до **типового** облікового запису (`default`). Для інших облікових записів потрібно використовувати значення конфігурації. + +Змінні середовища застосовуються лише до **облікового запису за замовчуванням** (`default`). Для інших облікових записів потрібно використовувати значення в конфігурації. -`MATTERMOST_URL` не можна задати з робочого простору `.env`; див. [Workspace `.env` files](/uk/gateway/security). +`MATTERMOST_URL` не можна задавати з робочого `.env`; див. [Workspace `.env` files](/uk/gateway/security). + ## Режими чату -Mattermost автоматично відповідає на DM. Поведінка в каналах керується `chatmode`: +Mattermost автоматично відповідає на DM. Поведінка в каналах керується через `chatmode`: -- `oncall` (типово): відповідати в каналах лише при @згадці. -- `onmessage`: відповідати на кожне повідомлення в каналі. -- `onchar`: відповідати, коли повідомлення починається з trigger prefix. + + + Відповідає лише при @згадуванні в каналах. + + + Відповідає на кожне повідомлення в каналі. + + + Відповідає, коли повідомлення починається з префікса-тригера. + + Приклад конфігурації: @@ -139,19 +161,17 @@ Mattermost автоматично відповідає на DM. Поведінк Примітки: -- `onchar` усе одно відповідає на явні @згадки. -- `channels.mattermost.requireMention` враховується для застарілих конфігурацій, але переважно слід використовувати `chatmode`. +- `onchar` усе одно реагує на явні @згадування. +- `channels.mattermost.requireMention` враховується для застарілих конфігурацій, але рекомендовано використовувати `chatmode`. -## Гілки та сесії +## Потоки та сесії -Використовуйте `channels.mattermost.replyToMode`, щоб керувати тим, чи відповіді в каналах і групах залишаються в -основному каналі, чи починають гілку під постом, що їх викликав. +Використовуйте `channels.mattermost.replyToMode`, щоб керувати тим, чи залишаються відповіді в каналах і групах в основному каналі, чи починають потік під повідомленням-тригером. -- `off` (типово): відповідати в гілці лише тоді, коли вхідний пост уже перебуває в ній. -- `first`: для повідомлень верхнього рівня в каналі/групі почати гілку під цим постом і спрямувати - розмову до сесії з областю дії цієї гілки. -- `all`: наразі для Mattermost поводиться так само, як `first`. -- Прямі повідомлення ігнорують це налаштування й залишаються без гілок. +- `off` (типово): відповідати в потоці лише тоді, коли вхідне повідомлення вже перебуває в ньому. +- `first`: для повідомлень верхнього рівня в каналі/групі запускати потік під цим повідомленням і спрямовувати розмову в сесію, прив'язану до потоку. +- `all`: на сьогодні для Mattermost поводиться так само, як `first`. +- Прямі повідомлення ігнорують цей параметр і залишаються без потоків. Приклад конфігурації: @@ -167,26 +187,24 @@ Mattermost автоматично відповідає на DM. Поведінк Примітки: -- Сесії з областю дії гілки використовують id поста, що спрацював, як корінь гілки. -- `first` і `all` наразі еквівалентні, оскільки щойно Mattermost має корінь гілки, - подальші фрагменти й медіа продовжуються в тій самій гілці. +- Сесії, прив'язані до потоку, використовують id повідомлення-тригера як корінь потоку. +- `first` і `all` наразі еквівалентні, оскільки щойно Mattermost має корінь потоку, наступні чанки та медіа продовжують іти в той самий потік. -## Керування доступом (DM) +## Контроль доступу (DM) -- Типово: `channels.mattermost.dmPolicy = "pairing"` (невідомі відправники отримують код спарювання). -- Схвалення через: +- Типово: `channels.mattermost.dmPolicy = "pairing"` (невідомі відправники отримують код pairing). +- Підтвердження через: - `openclaw pairing list mattermost` - `openclaw pairing approve mattermost ` - Публічні DM: `channels.mattermost.dmPolicy="open"` плюс `channels.mattermost.allowFrom=["*"]`. ## Канали (групи) -- Типово: `channels.mattermost.groupPolicy = "allowlist"` (із перевіркою згадки). -- Додавайте відправників до allowlist через `channels.mattermost.groupAllowFrom` (рекомендуються ID користувачів). -- Перевизначення згадки для окремих каналів задаються в `channels.mattermost.groups..requireMention` - або `channels.mattermost.groups["*"].requireMention` як типове значення. -- Відповідність `@username` є змінною та ввімкнена лише коли `channels.mattermost.dangerouslyAllowNameMatching: true`. -- Відкриті канали: `channels.mattermost.groupPolicy="open"` (із перевіркою згадки). +- Типово: `channels.mattermost.groupPolicy = "allowlist"` (із вимогою згадування). +- Дозволяйте відправників через `channels.mattermost.groupAllowFrom` (рекомендовано ID користувачів). +- Перевизначення згадувань для окремих каналів розміщуються в `channels.mattermost.groups..requireMention` або `channels.mattermost.groups["*"].requireMention` як значення за замовчуванням. +- Відповідність `@username` є змінною та вмикається лише коли `channels.mattermost.dangerouslyAllowNameMatching: true`. +- Відкриті канали: `channels.mattermost.groupPolicy="open"` (із вимогою згадування). - Примітка щодо runtime: якщо `channels.mattermost` повністю відсутній, runtime повертається до `groupPolicy="allowlist"` для перевірок груп (навіть якщо задано `channels.defaults.groupPolicy`). Приклад: @@ -207,28 +225,28 @@ Mattermost автоматично відповідає на DM. Поведінк ## Цілі для вихідної доставки -Використовуйте ці формати цілей із `openclaw message send` або cron/webhooks: +Використовуйте ці формати цілей з `openclaw message send` або cron/webhooks: - `channel:` для каналу - `user:` для DM - `@username` для DM (визначається через API Mattermost) -Звичайні непрозорі ID (наприклад `64ifufp...`) у Mattermost є **неоднозначними** (ID користувача чи ID каналу). + +Голі непрозорі ID (наприклад `64ifufp...`) у Mattermost **неоднозначні** (ID користувача чи ID каналу). OpenClaw визначає їх у порядку **спочатку користувач**: -- Якщо ID існує як користувач (`GET /api/v4/users/` виконується успішно), OpenClaw надсилає **DM**, визначаючи direct channel через `/api/v4/channels/direct`. -- Інакше ID вважається **ID каналу**. +- Якщо ID існує як користувач (`GET /api/v4/users/` виконується успішно), OpenClaw надсилає **DM**, визначаючи прямий канал через `/api/v4/channels/direct`. +- Інакше ID розглядається як **ID каналу**. Якщо вам потрібна детермінована поведінка, завжди використовуйте явні префікси (`user:` / `channel:`). + ## Повторні спроби для DM-каналу -Коли OpenClaw надсилає в ціль DM Mattermost і спочатку має визначити direct channel, -він типово повторює транзитні збої створення direct channel. +Коли OpenClaw надсилає повідомлення до цілі DM у Mattermost і спочатку має визначити прямий канал, за замовчуванням він повторює спроби при тимчасових збоях створення прямого каналу. -Використовуйте `channels.mattermost.dmChannelRetry`, щоб налаштувати цю поведінку глобально для Plugin Mattermost, -або `channels.mattermost.accounts..dmChannelRetry` для окремого облікового запису. +Використовуйте `channels.mattermost.dmChannelRetry`, щоб налаштувати цю поведінку глобально для Plugin Mattermost, або `channels.mattermost.accounts..dmChannelRetry` для окремого облікового запису. ```json5 { @@ -248,12 +266,12 @@ OpenClaw визначає їх у порядку **спочатку корист Примітки: - Це застосовується лише до створення DM-каналу (`/api/v4/channels/direct`), а не до кожного виклику API Mattermost. -- Повторні спроби застосовуються до транзитних збоїв, як-от обмеження швидкості, відповіді 5xx, а також помилки мережі чи тайм-ауту. +- Повторні спроби застосовуються до тимчасових збоїв, таких як обмеження швидкості, відповіді 5xx, а також помилки мережі чи тайм-аути. - Клієнтські помилки 4xx, окрім `429`, вважаються постійними й не повторюються. -## Попередній перегляд Streaming +## Потокове попереднє відображення -Mattermost передає міркування, активність інструментів і частковий текст відповіді в один **чернетковий пост попереднього перегляду**, який фіналізується на місці, коли фінальну відповідь безпечно надсилати. Попередній перегляд оновлюється в межах того самого id поста замість засмічення каналу повідомленнями для кожного фрагмента. Фінальні медіа/помилки скасовують відкладені редагування попереднього перегляду й використовують звичайну доставку замість вивантаження тимчасового поста попереднього перегляду. +Mattermost передає thinking, активність інструментів і частковий текст відповіді в один **чернетковий пост попереднього перегляду**, який завершується на місці, коли фінальну відповідь безпечно надсилати. Попередній перегляд оновлюється в тому самому id поста замість засмічення каналу повідомленнями для кожного чанка. Фінальні повідомлення з медіа/помилками скасовують відкладені редагування попереднього перегляду й використовують звичайну доставку замість скидання одноразового поста попереднього перегляду. Увімкнення через `channels.mattermost.streaming`: @@ -267,23 +285,27 @@ Mattermost передає міркування, активність інстр } ``` -Примітки: - -- `partial` — звичний вибір: один пост попереднього перегляду, який редагується в міру зростання відповіді, а потім фіналізується повною відповіддю. -- `block` використовує чернеткові фрагменти у стилі append всередині поста попереднього перегляду. -- `progress` показує попередній перегляд статусу під час генерування й публікує фінальну відповідь лише після завершення. -- `off` вимикає попередній перегляд Streaming. -- Якщо потік неможливо фіналізувати на місці (наприклад, пост було видалено під час потоку), OpenClaw повертається до надсилання нового фінального поста, щоб відповідь ніколи не була втрачена. -- Дані лише з міркуваннями не потрапляють до постів у каналі, зокрема текст, що надходить як blockquote `> Reasoning:`. Установіть `/reasoning on`, щоб бачити міркування в інших поверхнях; фінальний пост Mattermost містить лише відповідь. -- Див. [Streaming](/uk/concepts/streaming#preview-streaming-modes) для матриці відповідності каналів. + + + - `partial` — звичайний вибір: один пост попереднього перегляду, який редагується в міру зростання відповіді, а потім завершується повною відповіддю. + - `block` використовує чернеткові чанки в стилі додавання всередині поста попереднього перегляду. + - `progress` показує статусне попереднє відображення під час генерації та публікує фінальну відповідь лише після завершення. + - `off` вимикає потокове попереднє відображення. + + + - Якщо потік неможливо завершити на місці (наприклад, пост було видалено під час потоку), OpenClaw повертається до надсилання нового фінального поста, щоб відповідь ніколи не загубилася. + - Дані лише з reasoning не потрапляють у пости каналу, зокрема текст, що надходить як blockquote `> Reasoning:`. Установіть `/reasoning on`, щоб бачити thinking в інших поверхнях; фінальний пост Mattermost містить лише відповідь. + - Див. [Streaming](/uk/concepts/streaming#preview-streaming-modes) для матриці відповідності каналів. + + ## Реакції (інструмент повідомлень) - Використовуйте `message action=react` з `channel=mattermost`. - `messageId` — це id поста Mattermost. -- `emoji` приймає назви на кшталт `thumbsup` або `:+1:` (двокрапки необов’язкові). -- Установіть `remove=true` (boolean), щоб прибрати реакцію. -- Події додавання/видалення реакцій пересилаються як системні події до маршрутизованої сесії агента. +- `emoji` приймає назви на кшталт `thumbsup` або `:+1:` (двокрапки необов'язкові). +- Установіть `remove=true` (boolean), щоб видалити реакцію. +- Події додавання/видалення реакцій пересилаються як системні події до сесії агента, куди спрямовано маршрут. Приклади: @@ -295,12 +317,11 @@ message action=react channel=mattermost target=channel: messageId=.actions.reactions`. +- Перевизначення для окремого облікового запису: `channels.mattermost.accounts..actions.reactions`. ## Інтерактивні кнопки (інструмент повідомлень) -Надсилайте повідомлення з кнопками, на які можна натискати. Коли користувач натискає кнопку, агент отримує -вибір і може відповісти. +Надсилайте повідомлення з кнопками, які можна натискати. Коли користувач натискає кнопку, агент отримує вибір і може відповісти. Увімкніть кнопки, додавши `inlineButtons` до можливостей каналу: @@ -314,74 +335,76 @@ message action=react channel=mattermost target=channel: messageId= buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]] ``` -Поля кнопок: +Поля кнопки: -- `text` (обов’язково): мітка для показу. -- `callback_data` (обов’язково): значення, що повертається при натисканні (використовується як ID дії). -- `style` (необов’язково): `"default"`, `"primary"` або `"danger"`. + + Мітка для відображення. + + + Значення, яке надсилається назад при натисканні (використовується як ID дії). + + + Стиль кнопки. + Коли користувач натискає кнопку: -1. Усі кнопки замінюються рядком підтвердження (наприклад, "✓ **Yes** selected by @user"). -2. Агент отримує вибір як вхідне повідомлення та відповідає. + + + Усі кнопки замінюються рядком підтвердження (наприклад, "✓ **Yes** selected by @user"). + + + Агент отримує вибір як вхідне повідомлення і відповідає. + + -Примітки: - -- Button callback використовують перевірку HMAC-SHA256 (автоматично, без додаткової конфігурації). -- Mattermost прибирає callback data зі своїх відповідей API (функція безпеки), тому всі кнопки - видаляються при натисканні — часткове видалення неможливе. -- ID дій, що містять дефіси або підкреслення, автоматично санітизуються - (обмеження маршрутизації Mattermost). - -Конфігурація: - -- `channels.mattermost.capabilities`: масив рядків можливостей. Додайте `"inlineButtons"`, щоб - увімкнути опис інструмента кнопок у системному запиті агента. -- `channels.mattermost.interactions.callbackBaseUrl`: необов’язковий зовнішній базовий URL для - callback кнопок (наприклад, `https://gateway.example.com`). Використовуйте це, коли Mattermost не може - напряму звернутися до Gateway за його bind host. -- У конфігураціях із кількома обліковими записами те саме поле також можна задати в - `channels.mattermost.accounts..interactions.callbackBaseUrl`. -- Якщо `interactions.callbackBaseUrl` не вказано, OpenClaw виводить URL callback із - `gateway.customBindHost` + `gateway.port`, а потім повертається до `http://localhost:`. -- Правило доступності: URL callback кнопок має бути доступним із сервера Mattermost. - `localhost` працює лише тоді, коли Mattermost і OpenClaw запущені на тому самому host/network namespace. -- Якщо ваша ціль callback є приватною/tailnet/internal, додайте її host/domain до Mattermost - `ServiceSettings.AllowedUntrustedInternalConnections`. + + + - Callback-и кнопок використовують перевірку HMAC-SHA256 (автоматично, без потреби в налаштуванні). + - Mattermost видаляє callback data зі своїх API-відповідей (функція безпеки), тому всі кнопки видаляються при натисканні — часткове видалення неможливе. + - ID дій, що містять дефіси або підкреслення, автоматично санітизуються (обмеження маршрутизації Mattermost). + + + - `channels.mattermost.capabilities`: масив рядків можливостей. Додайте `"inlineButtons"`, щоб увімкнути опис інструмента кнопок у системному prompt агента. + - `channels.mattermost.interactions.callbackBaseUrl`: необов'язкова зовнішня базова URL-адреса для callback-ів кнопок (наприклад, `https://gateway.example.com`). Використовуйте це, коли Mattermost не може напряму дістатися Gateway за його bind host. + - У конфігураціях із кількома обліковими записами це саме поле також можна задати в `channels.mattermost.accounts..interactions.callbackBaseUrl`. + - Якщо `interactions.callbackBaseUrl` не вказано, OpenClaw формує callback URL з `gateway.customBindHost` + `gateway.port`, а потім повертається до `http://localhost:`. + - Правило доступності: URL callback кнопки має бути доступним із сервера Mattermost. `localhost` працює лише тоді, коли Mattermost і OpenClaw запущені на тому самому хості/в тому самому network namespace. + - Якщо ваша ціль callback є приватною/tailnet/внутрішньою, додайте її хост/домен до `ServiceSettings.AllowedUntrustedInternalConnections` у Mattermost. + + ### Пряма інтеграція API (зовнішні скрипти) -Зовнішні скрипти та Webhook можуть напряму публікувати кнопки через REST API Mattermost -замість використання інструмента `message` агента. Використовуйте `buildButtonAttachments()` із -Plugin, коли це можливо; якщо надсилаєте необроблений JSON, дотримуйтеся таких правил: +Зовнішні скрипти й Webhook-и можуть напряму надсилати кнопки через Mattermost REST API замість використання інструмента `message` агента. Використовуйте `buildButtonAttachments()` із Plugin, коли це можливо; якщо надсилаєте raw JSON, дотримуйтесь таких правил: **Структура payload:** ```json5 { channel_id: "", - message: "Choose an option:", + message: "Виберіть варіант:", props: { attachments: [ { actions: [ { id: "mybutton01", // лише буквено-цифрові символи — див. нижче - type: "button", // обов’язково, інакше натискання тихо ігноруються - name: "Approve", // мітка для показу - style: "primary", // необов’язково: "default", "primary", "danger" + type: "button", // обов'язково, інакше натискання буде мовчки проігноровано + name: "Approve", // мітка для відображення + style: "primary", // необов'язково: "default", "primary", "danger" integration: { url: "https://gateway.example.com/mattermost/interactions/default", context: { - action_id: "mybutton01", // має збігатися з id кнопки (для пошуку назви) + action_id: "mybutton01", // має збігатися з id кнопки (для визначення назви) action: "approve", - // ... будь-які власні поля ... + // ... будь-які користувацькі поля ... _token: "", // див. розділ HMAC нижче }, }, @@ -393,31 +416,40 @@ Plugin, коли це можливо; якщо надсилаєте необро } ``` -**Критично важливі правила:** + +**Критично важливі правила** -1. Attachments розміщуються в `props.attachments`, а не в top-level `attachments` (інакше тихо ігноруються). -2. Для кожної дії потрібне `type: "button"` — без цього натискання тихо поглинаються. -3. Для кожної дії потрібне поле `id` — Mattermost ігнорує дії без ID. -4. `id` дії має містити **лише буквено-цифрові символи** (`[a-zA-Z0-9]`). Дефіси й підкреслення ламають - серверну маршрутизацію дій Mattermost (повертає 404). Видаляйте їх перед використанням. -5. `context.action_id` має збігатися з `id` кнопки, щоб у повідомленні підтвердження показувалася - назва кнопки (наприклад, "Approve"), а не необроблений ID. -6. `context.action_id` є обов’язковим — без нього обробник взаємодії повертає 400. +1. Attachments мають бути в `props.attachments`, а не у верхньорівневому `attachments` (інакше їх буде мовчки проігноровано). +2. Кожна дія потребує `type: "button"` — без цього натискання будуть мовчки проковтнуті. +3. Кожна дія потребує поле `id` — Mattermost ігнорує дії без ID. +4. `id` дії має містити **лише буквено-цифрові символи** (`[a-zA-Z0-9]`). Дефіси й підкреслення ламають серверну маршрутизацію дій у Mattermost (повертається 404). Видаляйте їх перед використанням. +5. `context.action_id` має збігатися з `id` кнопки, щоб у повідомленні підтвердження відображалася назва кнопки (наприклад, "Approve"), а не raw ID. +6. `context.action_id` є обов'язковим — без нього обробник інтеракцій повертає 400. + -**Генерування токена HMAC:** +**Генерація HMAC-токена** -Gateway перевіряє натискання кнопок за допомогою HMAC-SHA256. Зовнішні скрипти мають генерувати токени, -які відповідають логіці перевірки Gateway: +Gateway перевіряє натискання кнопок за допомогою HMAC-SHA256. Зовнішні скрипти мають генерувати токени, що відповідають логіці перевірки Gateway: -1. Виведіть секрет із токена бота: - `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` -2. Побудуйте об’єкт context з усіма полями **крім** `_token`. -3. Серіалізуйте з **відсортованими ключами** і **без пробілів** (Gateway використовує `JSON.stringify` - з відсортованими ключами, що дає компактний вивід). -4. Підпишіть: `HMAC-SHA256(key=secret, data=serializedContext)` -5. Додайте отриманий hex digest як `_token` у context. + + + `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` + + + Побудуйте об'єкт context з усіма полями **крім** `_token`. + + + Серіалізуйте з **відсортованими ключами** і **без пробілів** (Gateway використовує `JSON.stringify` з відсортованими ключами, що дає компактний вивід). + + + `HMAC-SHA256(key=secret, data=serializedContext)` + + + Додайте отриманий hex-дайджест як `_token` у context. + + -Приклад на Python: +Приклад Python: ```python import hmac, hashlib, json @@ -434,24 +466,20 @@ token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() context = {**ctx, "_token": token} ``` -Поширені помилки з HMAC: + + + - `json.dumps` у Python типово додає пробіли (`{"key": "val"}`). Використовуйте `separators=(",", ":")`, щоб відповідати компактному виводу JavaScript (`{"key":"val"}`). + - Завжди підписуйте **всі** поля context (окрім `_token`). Gateway прибирає `_token`, а потім підписує все, що залишилося. Підписування лише підмножини спричиняє мовчазний збій перевірки. + - Використовуйте `sort_keys=True` — Gateway сортує ключі перед підписуванням, а Mattermost може змінювати порядок полів context під час збереження payload. + - Отримуйте секрет із токена бота (детерміновано), а не з випадкових байтів. Секрет має бути однаковим у процесі, який створює кнопки, і в Gateway, який їх перевіряє. + + -- `json.dumps` у Python типово додає пробіли (`{"key": "val"}`). Використовуйте - `separators=(",", ":")`, щоб відповідати компактному виводу JavaScript (`{"key":"val"}`). -- Завжди підписуйте **всі** поля context (крім `_token`). Gateway видаляє `_token`, а потім - підписує все, що лишається. Підписування лише підмножини призводить до тихого збою перевірки. -- Використовуйте `sort_keys=True` — Gateway сортує ключі перед підписуванням, і Mattermost може - змінювати порядок полів context під час зберігання payload. -- Виводьте секрет із токена бота (детерміновано), а не з випадкових байтів. Секрет - має бути однаковим у процесі, який створює кнопки, і в Gateway, який їх перевіряє. +## Адаптер directory -## Адаптер каталогу +Plugin Mattermost містить адаптер directory, який визначає назви каналів і користувачів через API Mattermost. Це дає змогу використовувати цілі `#channel-name` і `@username` в `openclaw message send` і доставках Cron/Webhook. -Plugin Mattermost містить адаптер каталогу, який визначає назви каналів і користувачів -через API Mattermost. Це дає змогу використовувати цілі `#channel-name` і `@username` у -`openclaw message send` і доставці через cron/Webhook. - -Налаштування не потрібне — адаптер використовує токен бота з конфігурації облікового запису. +Конфігурація не потрібна — адаптер використовує токен бота з конфігурації облікового запису. ## Кілька облікових записів @@ -472,34 +500,38 @@ Mattermost підтримує кілька облікових записів у ## Усунення несправностей -- Немає відповідей у каналах: переконайтеся, що бот є в каналі та його згадують (oncall), використовуйте trigger prefix (onchar) або встановіть `chatmode: "onmessage"`. -- Помилки автентифікації: перевірте токен бота, базовий URL і чи ввімкнено обліковий запис. -- Проблеми з кількома обліковими записами: env vars застосовуються лише до облікового запису `default`. -- Вбудовані slash-команди повертають `Unauthorized: invalid command token.`: OpenClaw - не прийняв токен callback. Типові причини: - - реєстрація slash-команд не вдалася або була завершена лише частково під час запуску - - callback потрапляє не до того Gateway/облікового запису - - Mattermost усе ще має старі команди, що вказують на попередню ціль callback - - Gateway перезапустився без повторної активації slash-команд -- Якщо вбудовані slash-команди перестали працювати, перевірте журнали на наявність - `mattermost: failed to register slash commands` або - `mattermost: native slash commands enabled but no commands could be registered`. -- Якщо `callbackUrl` не вказано, а журнали попереджають, що callback було визначено як - `http://127.0.0.1:18789/...`, цей URL, імовірно, доступний лише тоді, - коли Mattermost працює на тому самому host/network namespace, що й OpenClaw. Замість цього задайте - явний зовнішньо доступний `commands.callbackUrl`. -- Кнопки відображаються як білі прямокутники: агент може надсилати некоректні дані кнопок. Переконайтеся, що кожна кнопка має поля `text` і `callback_data`. -- Кнопки відображаються, але натискання нічого не роблять: перевірте, що `AllowedUntrustedInternalConnections` у конфігурації сервера Mattermost містить `127.0.0.1 localhost`, і що `EnablePostActionIntegration` має значення `true` у ServiceSettings. -- Кнопки повертають 404 при натисканні: `id` кнопки, імовірно, містить дефіси або підкреслення. Маршрутизатор дій Mattermost ламається на небуквено-цифрових ID. Використовуйте лише `[a-zA-Z0-9]`. -- Gateway журналює `invalid _token`: невідповідність HMAC. Перевірте, що ви підписуєте всі поля context (а не лише підмножину), використовуєте відсортовані ключі й компактний JSON (без пробілів). Див. розділ HMAC вище. -- Gateway журналює `missing _token in context`: поле `_token` відсутнє в context кнопки. Переконайтеся, що його включено під час побудови payload integration. -- У підтвердженні показується необроблений ID замість назви кнопки: `context.action_id` не збігається з `id` кнопки. Установіть обидва значення однаковими й санітизованими. -- Агент не знає про кнопки: додайте `capabilities: ["inlineButtons"]` до конфігурації каналу Mattermost. + + + Переконайтеся, що бот є в каналі, і згадайте його (oncall), використайте префікс-тригер (onchar) або встановіть `chatmode: "onmessage"`. + + + - Перевірте токен бота, базову URL-адресу та чи ввімкнено обліковий запис. + - Проблеми з кількома обліковими записами: змінні середовища застосовуються лише до облікового запису `default`. + + + - `Unauthorized: invalid command token.`: OpenClaw не прийняв токен callback. Типові причини: + - реєстрація slash-команд не вдалася або завершилася лише частково під час запуску + - callback потрапляє не в той gateway/обліковий запис + - у Mattermost все ще залишилися старі команди, що вказують на попередню ціль callback + - gateway перезапустився без повторної активації slash-команд + - Якщо власні slash-команди перестали працювати, перевірте логи на `mattermost: failed to register slash commands` або `mattermost: native slash commands enabled but no commands could be registered`. + - Якщо `callbackUrl` не вказано, а логи попереджають, що callback було визначено як `http://127.0.0.1:18789/...`, ця URL-адреса, імовірно, доступна лише тоді, коли Mattermost працює на тому самому хості/в тому самому network namespace, що й OpenClaw. Натомість задайте явний зовнішньо доступний `commands.callbackUrl`. + + + - Кнопки відображаються як білі прямокутники: агент може надсилати некоректні дані кнопок. Переконайтеся, що кожна кнопка має поля `text` і `callback_data`. + - Кнопки відображаються, але натискання нічого не робить: перевірте, що `AllowedUntrustedInternalConnections` у конфігурації сервера Mattermost включає `127.0.0.1 localhost`, і що `EnablePostActionIntegration` має значення `true` у ServiceSettings. + - Кнопки повертають 404 при натисканні: `id` кнопки, імовірно, містить дефіси або підкреслення. Маршрутизатор дій Mattermost ламається на не буквено-цифрових ID. Використовуйте лише `[a-zA-Z0-9]`. + - Gateway логуватиме `invalid _token`: невідповідність HMAC. Перевірте, що ви підписуєте всі поля context (а не підмножину), використовуєте відсортовані ключі та компактний JSON (без пробілів). Див. розділ HMAC вище. + - Gateway логуватиме `missing _token in context`: поле `_token` відсутнє в context кнопки. Переконайтеся, що воно включене під час побудови payload інтеграції. + - У підтвердженні показується raw ID замість назви кнопки: `context.action_id` не збігається з `id` кнопки. Установіть обидва в одне й те саме санітизоване значення. + - Агент не знає про кнопки: додайте `capabilities: ["inlineButtons"]` до конфігурації каналу Mattermost. + + -## Пов’язане +## Пов'язане -- [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Спарювання](/uk/channels/pairing) — автентифікація DM і процес спарювання -- [Групи](/uk/channels/groups) — поведінка групових чатів і керування через згадки -- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту +- [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень +- [Channels Overview](/uk/channels) — усі підтримувані канали +- [Groups](/uk/channels/groups) — поведінка групового чату та вимога згадування +- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing +- [Security](/uk/gateway/security) — модель доступу та зміцнення безпеки