Mattermost

Status: завантажуваний Plugin (токен бота + події WebSocket). Підтримуються канали, групи та особисті повідомлення. Mattermost — це самостійно розгортувана платформа командного обміну повідомленнями; подробиці про продукт і завантаження див. на офіційному сайті mattermost.com.

# Встановлення

Установіть Mattermost перед налаштуванням каналу:

openclaw plugins install @openclaw/mattermost

openclaw plugins install ./path/to/local/mattermost-plugin

Докладніше: Plugins

# Швидке налаштування

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

# Нативні слеш-команди

Нативні слеш-команди вмикаються окремо. Коли їх увімкнено, OpenClaw реєструє слеш-команди oc_* через API Mattermost і отримує callback POST-запити на HTTP-сервері gateway.

{
  channels: {
    mattermost: {
      commands: {
        native: true,
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
    },
  },
}

# Змінні середовища (обліковий запис за замовчуванням)

Задайте їх на хості gateway, якщо віддаєте перевагу змінним середовища:

• MATTERMOST_BOT_TOKEN=...
• MATTERMOST_URL=https://chat.example.com

# Режими чату

Mattermost автоматично відповідає на особисті повідомлення. Поведінка каналу керується chatmode:

Приклад конфігурації:

{
  channels: {
    mattermost: {
      chatmode: "onchar",
      oncharPrefixes: [">", "!"],
    },
  },
}

Примітки:

• onchar все одно відповідає на явні @згадки.
• channels.mattermost.requireMention підтримується для застарілих конфігурацій, але перевага надається chatmode.

# Потоки та сеанси

Використовуйте channels.mattermost.replyToMode, щоб керувати тим, чи відповіді в каналах і групах залишаються в основному каналі, чи починають потік під дописом-тригером.

• off (за замовчуванням): відповідати в потоці лише тоді, коли вхідний допис уже в ньому.
• first: для дописів верхнього рівня в каналі/групі почати потік під цим дописом і маршрутизувати розмову до сеансу, прив’язаного до потоку.
• all: на сьогодні така сама поведінка, як first, для Mattermost.
• Особисті повідомлення ігнорують це налаштування й залишаються без потоків.

Приклад конфігурації:

{
  channels: {
    mattermost: {
      replyToMode: "all",
    },
  },
}

Примітки:

• Сеанси, прив’язані до потоку, використовують id допису-тригера як корінь потоку.
• first і all наразі еквівалентні, бо щойно Mattermost має корінь потоку, подальші фрагменти й медіа продовжуються в тому самому потоці.

# Керування доступом (особисті повідомлення)

• За замовчуванням: channels.mattermost.dmPolicy = "pairing" (невідомі відправники отримують код спарювання).
• Схвалення через:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• Публічні особисті повідомлення: 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" (із вимогою згадки).
• Примітка щодо runtime: якщо channels.mattermost повністю відсутній, runtime повертається до groupPolicy="allowlist" для перевірок груп (навіть якщо задано channels.defaults.groupPolicy).

Приклад:

{
  channels: {
    mattermost: {
      groupPolicy: "open",
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
    },
  },
}

# Цілі для вихідної доставки

Використовуйте ці формати цілей із openclaw message send або cron/webhooks:

• channel:<id> для каналу
• user:<id> для особистого повідомлення
• @username для особистого повідомлення (визначається через API Mattermost)

# Повторна спроба каналу особистих повідомлень

Коли OpenClaw надсилає до цілі особистого повідомлення Mattermost і спочатку має визначити прямий канал, він за замовчуванням повторює спроби для тимчасових збоїв створення прямого каналу.

Використовуйте channels.mattermost.dmChannelRetry, щоб налаштувати цю поведінку глобально для Plugin Mattermost, або channels.mattermost.accounts.<id>.dmChannelRetry для одного облікового запису.

{
  channels: {
    mattermost: {
      dmChannelRetry: {
        maxRetries: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        timeoutMs: 30000,
      },
    },
  },
}

Примітки:

• Це застосовується лише до створення каналу особистих повідомлень (/api/v4/channels/direct), а не до кожного виклику API Mattermost.
• Повторні спроби застосовуються до тимчасових збоїв, як-от обмеження частоти, відповіді 5xx і помилки мережі або тайм-ауту.
• Клієнтські помилки 4xx, окрім 429, вважаються постійними й не повторюються.

# Потоковий preview

Mattermost передає міркування, активність інструментів і частковий текст відповіді в один чернетковий preview-допис, який фіналізується на місці, коли фінальну відповідь безпечно надіслати. Preview оновлюється в тому самому id допису замість засмічення каналу повідомленнями для кожного фрагмента. Фінали з медіа/помилками скасовують очікувані редагування preview і використовують звичайну доставку замість скидання одноразового preview-допису.

Увімкніть через channels.mattermost.streaming:

{
  channels: {
    mattermost: {
      streaming: "partial", // off | partial | block | progress
    },
  },
}

# Реакції (інструмент повідомлень)

• Використовуйте message action=react із channel=mattermost.
• messageId — це id допису Mattermost.
• emoji приймає назви на кшталт thumbsup або :+1: (двокрапки необов’язкові).
• Установіть remove=true (логічне значення), щоб видалити реакцію.
• Події додавання/видалення реакцій пересилаються як системні події до маршрутизованого сеансу агента.

Приклади:

message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

Конфігурація:

• channels.mattermost.actions.reactions: увімкнути/вимкнути дії реакцій (за замовчуванням true).
• Перевизначення для окремого облікового запису: channels.mattermost.accounts.<id>.actions.reactions.

# Інтерактивні кнопки (інструмент повідомлень)

Надсилайте повідомлення з клікабельними кнопками. Коли користувач натискає кнопку, агент отримує вибір і може відповісти.

Увімкніть кнопки, додавши inlineButtons до можливостей каналу:

{
  channels: {
    mattermost: {
      capabilities: ["inlineButtons"],
    },
  },
}

Використовуйте message action=send з параметром buttons. Кнопки — це 2D-масив (рядки кнопок):

message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

Поля кнопок:

Коли користувач натискає кнопку:

# Пряма інтеграція API (зовнішні скрипти)

Зовнішні скрипти та webhooks можуть публікувати кнопки напряму через Mattermost REST API замість проходження через інструмент message агента. За можливості використовуйте buildButtonAttachments() із Plugin; якщо публікуєте необроблений JSON, дотримуйтеся цих правил:

Структура payload:

{
  channel_id: "<channelId>",
  message: "Choose an option:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // alphanumeric only - see below
            type: "button", // required, or clicks are silently ignored
            name: "Approve", // display label
            style: "primary", // optional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // must match button id (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

Генерування токена HMAC

Gateway перевіряє натискання кнопок за допомогою HMAC-SHA256. Зовнішні скрипти мають генерувати токени, що відповідають логіці перевірки Gateway:

Приклад Python:

secret = hmac.new(
    b"openclaw-mattermost-interactions",
    bot_token.encode(), hashlib.sha256
).hexdigest()

ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

context = {**ctx, "_token": token}

# Адаптер каталогу

Plugin Mattermost містить адаптер каталогу, який розв'язує назви каналів і користувачів через Mattermost API. Це вмикає цілі #channel-name і @username в openclaw message send та доставках cron/webhook.

Конфігурація не потрібна - адаптер використовує токен бота з конфігурації облікового запису.

# Кілька облікових записів

Mattermost підтримує кілька облікових записів у channels.mattermost.accounts:

{
  channels: {
    mattermost: {
      accounts: {
        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
      },
    },
  },
}

# Усунення неполадок

# Пов'язане

• Маршрутизація каналів - маршрутизація сеансів для повідомлень
• Огляд каналів - усі підтримувані канали
• Групи - поведінка групового чату та фільтрація згадок
• Сполучення - автентифікація DM і процес сполучення
• Безпека - модель доступу та посилення захисту