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

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-26 08:00:52 +00:00
parent 46d399dd38
commit 4e5382ca62
1 changed files with 252 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

472
docs/uk/channels/mattermost.md
View File

@ -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, тому звичайні
зібрані пакети не потребують окремого встановлення.
<Note>
Mattermost постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення.
</Note>
Якщо у вас старіша збірка або нетипове встановлення без Mattermost,
встановіть його вручну:
Якщо ви використовуєте старішу збірку або кастомне встановлення без Mattermost, встановіть його вручну:
Установлення через CLI (реєстр npm):
```bash
openclaw plugins install @openclaw/mattermost
```
Локальний checkout (під час запуску з git-репозиторію):
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
```
<Tabs>
<Tab title="npm registry">
```bash
openclaw plugins install @openclaw/mattermost
```
</Tab>
<Tab title="Local checkout">
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
```
</Tab>
</Tabs>
Докладніше: [Plugins](/uk/tools/plugin)
## Швидке налаштування
1. Переконайтеся, що Plugin Mattermost доступний.
- Поточні пакетні випуски OpenClaw уже містять його в комплекті.
- У старіших/нетипових встановленнях його можна додати вручну командами вище.
2. Створіть обліковий запис бота Mattermost і скопіюйте **токен бота**.
3. Скопіюйте **базовий URL** Mattermost (наприклад, `https://chat.example.com`).
4. Налаштуйте OpenClaw і запустіть Gateway.
<Steps>
<Step title="Переконайтеся, що Plugin доступний">
У поточних пакетованих релізах OpenClaw він уже вбудований. У старіших або кастомних встановленнях його можна додати вручну за допомогою наведених вище команд.
</Step>
<Step title="Створіть бота Mattermost">
Створіть обліковий запис бота Mattermost і скопіюйте **токен бота**.
</Step>
<Step title="Скопіюйте базову URL-адресу">
Скопіюйте **базову URL-адресу** Mattermost (наприклад, `https://chat.example.com`).
</Step>
<Step title="Налаштуйте OpenClaw і запустіть Gateway">
Мінімальна конфігурація:
Мінімальна конфігурація:
```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",
},
},
}
```
</Step>
</Steps>
## Вбудовані 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-серве
}
```
Примітки:
<AccordionGroup>
<Accordion title="Примітки щодо поведінки">
- `native: "auto"` типово вимкнено для Mattermost. Установіть `native: true`, щоб увімкнути.
- Якщо `callbackUrl` не вказано, OpenClaw формує його з хоста/порту gateway + `callbackPath`.
- Для конфігурацій з кількома обліковими записами `commands` можна задати на верхньому рівні або в `channels.mattermost.accounts.<id>.commands` (значення облікового запису перевизначають поля верхнього рівня).
- Callback-и команд перевіряються за допомогою токенів команд, які Mattermost повертає, коли OpenClaw реєструє команди `oc_*`.
- Callback-и slash-команд працюють у режимі fail closed, якщо реєстрація не вдалася, запуск був частковим або токен callback не збігається з одним із зареєстрованих команд.
</Accordion>
<Accordion title="Вимога доступності">
Endpoint callback має бути доступним із сервера Mattermost.
- Не встановлюйте `callbackUrl` у `localhost`, якщо Mattermost не працює на тому самому хості/в тому самому network namespace, що й OpenClaw.
- Не встановлюйте `callbackUrl` у базову URL-адресу вашого Mattermost, якщо ця URL-адреса не проксіює `/api/channels/mattermost/command` до OpenClaw через reverse proxy.
- Швидка перевірка: `curl https://<gateway-host>/api/channels/mattermost/command`; GET-запит має повертати `405 Method Not Allowed` від OpenClaw, а не `404`.
</Accordion>
<Accordion title="Allowlist вихідних з'єднань Mattermost">
Якщо ваш callback спрямовано на приватні/tailnet/внутрішні адреси, установіть у Mattermost `ServiceSettings.AllowedUntrustedInternalConnections`, щоб включити хост/домен callback.
Використовуйте записи хоста/домену, а не повні URL-адреси.
- `native: "auto"` типово вимкнено для Mattermost. Щоб увімкнути, встановіть `native: true`.
- Якщо `callbackUrl` не вказано, OpenClaw виводить його з host/port Gateway + `callbackPath`.
- Для конфігурацій із кількома обліковими записами `commands` можна задавати на верхньому рівні або під
`channels.mattermost.accounts.<id>.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://<gateway-host>/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`
## Змінні середовища (типовий обліковий запис)
</Accordion>
</AccordionGroup>
Установіть їх на host Gateway, якщо віддаєте перевагу env vars:
## Змінні середовища (обліковий запис за замовчуванням)
Установіть їх на хості gateway, якщо віддаєте перевагу змінним середовища:
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
Env vars застосовуються лише до **типового** облікового запису (`default`). Для інших облікових записів потрібно використовувати значення конфігурації.
<Note>
Змінні середовища застосовуються лише до **облікового запису за замовчуванням** (`default`). Для інших облікових записів потрібно використовувати значення в конфігурації.
`MATTERMOST_URL` не можна задати з робочого простору `.env`; див. [Workspace `.env` files](/uk/gateway/security).
`MATTERMOST_URL` не можна задавати з робочого `.env`; див. [Workspace `.env` files](/uk/gateway/security).
</Note>
## Режими чату
Mattermost автоматично відповідає на DM. Поведінка в каналах керується `chatmode`:
Mattermost автоматично відповідає на DM. Поведінка в каналах керується через `chatmode`:
- `oncall` (типово): відповідати в каналах лише при @згадці.
- `onmessage`: відповідати на кожне повідомлення в каналі.
- `onchar`: відповідати, коли повідомлення починається з trigger prefix.
<Tabs>
<Tab title="oncall (типово)">
Відповідає лише при @згадуванні в каналах.
</Tab>
<Tab title="onmessage">
Відповідає на кожне повідомлення в каналі.
</Tab>
<Tab title="onchar">
Відповідає, коли повідомлення починається з префікса-тригера.
</Tab>
</Tabs>
Приклад конфігурації:
@ -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 <CODE>`
- Публічні DM: `channels.mattermost.dmPolicy="open"` плюс `channels.mattermost.allowFrom=["*"]`.
## Канали (групи)
- Типово: `channels.mattermost.groupPolicy = "allowlist"` (із перевіркою згадки).
- Додавайте відправників до allowlist через `channels.mattermost.groupAllowFrom` (рекомендуються ID користувачів).
- Перевизначення згадки для окремих каналів задаються в `channels.mattermost.groups.<channelId>.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.<channelId>.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:<id>` для каналу
- `user:<id>` для DM
- `@username` для DM (визначається через API Mattermost)
Звичайні непрозорі ID (наприклад `64ifufp...`) у Mattermost є **неоднозначними** (ID користувача чи ID каналу).
<Warning>
Голі непрозорі ID (наприклад `64ifufp...`) у Mattermost **неоднозначні** (ID користувача чи ID каналу).
OpenClaw визначає їх у порядку **спочатку користувач**:
- Якщо ID існує як користувач (`GET /api/v4/users/<id>` виконується успішно), OpenClaw надсилає **DM**, визначаючи direct channel через `/api/v4/channels/direct`.
- Інакше ID вважається **ID каналу**.
- Якщо ID існує як користувач (`GET /api/v4/users/<id>` виконується успішно), OpenClaw надсилає **DM**, визначаючи прямий канал через `/api/v4/channels/direct`.
- Інакше ID розглядається як **ID каналу**.
Якщо вам потрібна детермінована поведінка, завжди використовуйте явні префікси (`user:<id>` / `channel:<id>`).
</Warning>
## Повторні спроби для DM-каналу
Коли OpenClaw надсилає в ціль DM Mattermost і спочатку має визначити direct channel,
він типово повторює транзитні збої створення direct channel.
Коли OpenClaw надсилає повідомлення до цілі DM у Mattermost і спочатку має визначити прямий канал, за замовчуванням він повторює спроби при тимчасових збоях створення прямого каналу.
Використовуйте `channels.mattermost.dmChannelRetry`, щоб налаштувати цю поведінку глобально для Plugin Mattermost,
або `channels.mattermost.accounts.<id>.dmChannelRetry` для окремого облікового запису.
Використовуйте `channels.mattermost.dmChannelRetry`, щоб налаштувати цю поведінку глобально для Plugin Mattermost, або `channels.mattermost.accounts.<id>.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) для матриці відповідності каналів.
<AccordionGroup>
<Accordion title="Режими потокової передачі">
- `partial` — звичайний вибір: один пост попереднього перегляду, який редагується в міру зростання відповіді, а потім завершується повною відповіддю.
- `block` використовує чернеткові чанки в стилі додавання всередині поста попереднього перегляду.
- `progress` показує статусне попереднє відображення під час генерації та публікує фінальну відповідь лише після завершення.
- `off` вимикає потокове попереднє відображення.
</Accordion>
<Accordion title="Примітки щодо поведінки потокової передачі">
- Якщо потік неможливо завершити на місці (наприклад, пост було видалено під час потоку), OpenClaw повертається до надсилання нового фінального поста, щоб відповідь ніколи не загубилася.
- Дані лише з reasoning не потрапляють у пости каналу, зокрема текст, що надходить як blockquote `> Reasoning:`. Установіть `/reasoning on`, щоб бачити thinking в інших поверхнях; фінальний пост Mattermost містить лише відповідь.
- Див. [Streaming](/uk/concepts/streaming#preview-streaming-modes) для матриці відповідності каналів.
</Accordion>
</AccordionGroup>
## Реакції (інструмент повідомлень)
- Використовуйте `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:<channelId> messageId=<po
Конфігурація:
- `channels.mattermost.actions.reactions`: увімкнути/вимкнути дії реакцій (типово true).
- Перевизначення для облікового запису: `channels.mattermost.accounts.<id>.actions.reactions`.
- Перевизначення для окремого облікового запису: `channels.mattermost.accounts.<id>.actions.reactions`.
## Інтерактивні кнопки (інструмент повідомлень)
Надсилайте повідомлення з кнопками, на які можна натискати. Коли користувач натискає кнопку, агент отримує
вибір і може відповісти.
Надсилайте повідомлення з кнопками, які можна натискати. Коли користувач натискає кнопку, агент отримує вибір і може відповісти.
Увімкніть кнопки, додавши `inlineButtons` до можливостей каналу:
@ -314,74 +335,76 @@ message action=react channel=mattermost target=channel:<channelId> messageId=<po
}
```
Використовуйте `message action=send` із параметром `buttons`. Кнопки — це двовимірний масив (ряди кнопок):
Використовуйте `message action=send` з параметром `buttons`. Кнопки — це двовимірний масив (ряди кнопок):
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
```
Поля кнопок:
Поля кнопки:
- `text` (обов’язково): мітка для показу.
- `callback_data` (обов’язково): значення, що повертається при натисканні (використовується як ID дії).
- `style` (необов’язково): `"default"`, `"primary"` або `"danger"`.
<ParamField path="text" type="string" required>
Мітка для відображення.
</ParamField>
<ParamField path="callback_data" type="string" required>
Значення, яке надсилається назад при натисканні (використовується як ID дії).
</ParamField>
<ParamField path="style" type='"default" | "primary" | "danger"'>
Стиль кнопки.
</ParamField>
Коли користувач натискає кнопку:
1. Усі кнопки замінюються рядком підтвердження (наприклад, "✓ **Yes** selected by @user").
2. Агент отримує вибір як вхідне повідомлення та відповідає.
<Steps>
<Step title="Кнопки замінюються підтвердженням">
Усі кнопки замінюються рядком підтвердження (наприклад, "✓ **Yes** selected by @user").
</Step>
<Step title="Агент отримує вибір">
Агент отримує вибір як вхідне повідомлення і відповідає.
</Step>
</Steps>
Примітки:
- 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.<id>.interactions.callbackBaseUrl`.
- Якщо `interactions.callbackBaseUrl` не вказано, OpenClaw виводить URL callback із
`gateway.customBindHost` + `gateway.port`, а потім повертається до `http://localhost:<port>`.
- Правило доступності: URL callback кнопок має бути доступним із сервера Mattermost.
`localhost` працює лише тоді, коли Mattermost і OpenClaw запущені на тому самому host/network namespace.
- Якщо ваша ціль callback є приватною/tailnet/internal, додайте її host/domain до Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections`.
<AccordionGroup>
<Accordion title="Примітки щодо реалізації">
- Callback-и кнопок використовують перевірку HMAC-SHA256 (автоматично, без потреби в налаштуванні).
- Mattermost видаляє callback data зі своїх API-відповідей (функція безпеки), тому всі кнопки видаляються при натисканні — часткове видалення неможливе.
- ID дій, що містять дефіси або підкреслення, автоматично санітизуються (обмеження маршрутизації Mattermost).
</Accordion>
<Accordion title="Конфігурація та доступність">
- `channels.mattermost.capabilities`: масив рядків можливостей. Додайте `"inlineButtons"`, щоб увімкнути опис інструмента кнопок у системному prompt агента.
- `channels.mattermost.interactions.callbackBaseUrl`: необов'язкова зовнішня базова URL-адреса для callback-ів кнопок (наприклад, `https://gateway.example.com`). Використовуйте це, коли Mattermost не може напряму дістатися Gateway за його bind host.
- У конфігураціях із кількома обліковими записами це саме поле також можна задати в `channels.mattermost.accounts.<id>.interactions.callbackBaseUrl`.
- Якщо `interactions.callbackBaseUrl` не вказано, OpenClaw формує callback URL з `gateway.customBindHost` + `gateway.port`, а потім повертається до `http://localhost:<port>`.
- Правило доступності: URL callback кнопки має бути доступним із сервера Mattermost. `localhost` працює лише тоді, коли Mattermost і OpenClaw запущені на тому самому хості/в тому самому network namespace.
- Якщо ваша ціль callback є приватною/tailnet/внутрішньою, додайте її хост/домен до `ServiceSettings.AllowedUntrustedInternalConnections` у Mattermost.
</Accordion>
</AccordionGroup>
### Пряма інтеграція API (зовнішні скрипти)
Зовнішні скрипти та Webhook можуть напряму публікувати кнопки через REST API Mattermost
замість використання інструмента `message` агента. Використовуйте `buildButtonAttachments()` із
Plugin, коли це можливо; якщо надсилаєте необроблений JSON, дотримуйтеся таких правил:
Зовнішні скрипти й Webhook-и можуть напряму надсилати кнопки через Mattermost REST API замість використання інструмента `message` агента. Використовуйте `buildButtonAttachments()` із Plugin, коли це можливо; якщо надсилаєте raw JSON, дотримуйтесь таких правил:
**Структура payload:**
```json5
{
channel_id: "<channelId>",
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>", // див. розділ HMAC нижче
},
},
@ -393,31 +416,40 @@ Plugin, коли це можливо; якщо надсилаєте необро
}
```
**Критично важливі правила:**
<Warning>
**Критично важливі правила**
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.
</Warning>
**Генерування токена 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.
<Steps>
<Step title="Отримайте секрет із токена бота">
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
</Step>
<Step title="Побудуйте об'єкт context">
Побудуйте об'єкт context з усіма полями **крім** `_token`.
</Step>
<Step title="Серіалізуйте з відсортованими ключами">
Серіалізуйте з **відсортованими ключами** і **без пробілів** (Gateway використовує `JSON.stringify` з відсортованими ключами, що дає компактний вивід).
</Step>
<Step title="Підпишіть payload">
`HMAC-SHA256(key=secret, data=serializedContext)`
</Step>
<Step title="Додайте токен">
Додайте отриманий hex-дайджест як `_token` у context.
</Step>
</Steps>
Приклад на 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:
<AccordionGroup>
<Accordion title="Поширені помилки з HMAC">
- `json.dumps` у Python типово додає пробіли (`{"key": "val"}`). Використовуйте `separators=(",", ":")`, щоб відповідати компактному виводу JavaScript (`{"key":"val"}`).
- Завжди підписуйте **всі** поля context (окрім `_token`). Gateway прибирає `_token`, а потім підписує все, що залишилося. Підписування лише підмножини спричиняє мовчазний збій перевірки.
- Використовуйте `sort_keys=True` — Gateway сортує ключі перед підписуванням, а Mattermost може змінювати порядок полів context під час збереження payload.
- Отримуйте секрет із токена бота (детерміновано), а не з випадкових байтів. Секрет має бути однаковим у процесі, який створює кнопки, і в Gateway, який їх перевіряє.
</Accordion>
</AccordionGroup>
- `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.
<AccordionGroup>
<Accordion title="Немає відповідей у каналах">
Переконайтеся, що бот є в каналі, і згадайте його (oncall), використайте префікс-тригер (onchar) або встановіть `chatmode: "onmessage"`.
</Accordion>
<Accordion title="Помилки автентифікації або кількох облікових записів">
- Перевірте токен бота, базову URL-адресу та чи ввімкнено обліковий запис.
- Проблеми з кількома обліковими записами: змінні середовища застосовуються лише до облікового запису `default`.
</Accordion>
<Accordion title="Не працюють власні 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 працює на тому самому хості/в тому самому network namespace, що й OpenClaw. Натомість задайте явний зовнішньо доступний `commands.callbackUrl`.
</Accordion>
<Accordion title="Проблеми з кнопками">
- Кнопки відображаються як білі прямокутники: агент може надсилати некоректні дані кнопок. Переконайтеся, що кожна кнопка має поля `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.
</Accordion>
</AccordionGroup>
## Пов’язане
## Пов'язане
- [Огляд каналів](/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) — модель доступу та зміцнення безпеки