Mattermost

Status: Plugin do pobrania (token bota + zdarzenia WebSocket). Obsługiwane są kanały, grupy i wiadomości DM. Mattermost to platforma do zespołowej komunikacji, którą można hostować samodzielnie; szczegóły produktu i pliki do pobrania znajdziesz na oficjalnej stronie mattermost.com.

# Instalacja

Zainstaluj Mattermost przed skonfigurowaniem kanału:

openclaw plugins install @openclaw/mattermost

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

Szczegóły: Plugins

# Szybka konfiguracja

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

# Natywne polecenia slash

Natywne polecenia slash są opcjonalne. Po włączeniu OpenClaw rejestruje polecenia slash oc_* przez API Mattermost i odbiera żądania zwrotne POST na serwerze 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",
      },
    },
  },
}

# Zmienne środowiskowe (konto domyślne)

Ustaw je na hoście Gateway, jeśli wolisz zmienne środowiskowe:

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

# Tryby czatu

Mattermost odpowiada na DM-y automatycznie. Zachowaniem kanału steruje chatmode:

Przykład konfiguracji:

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

Uwagi:

• onchar nadal odpowiada na jawne @wzmianki.
• channels.mattermost.requireMention jest respektowane dla starszych konfiguracji, ale preferowane jest chatmode.

# Wątki i sesje

Użyj channels.mattermost.replyToMode, aby kontrolować, czy odpowiedzi w kanałach i grupach pozostają w głównym kanale, czy rozpoczynają wątek pod postem wyzwalającym.

• off (domyślnie): odpowiadaj w wątku tylko wtedy, gdy przychodzący post już w nim jest.
• first: dla postów najwyższego poziomu w kanale/grupie rozpocznij wątek pod tym postem i przekieruj rozmowę do sesji ograniczonej do wątku.
• all: obecnie takie samo zachowanie jak first dla Mattermost.
• Wiadomości bezpośrednie ignorują to ustawienie i pozostają bez wątków.

Przykład konfiguracji:

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

Uwagi:

• Sesje ograniczone do wątku używają identyfikatora posta wyzwalającego jako korzenia wątku.
• first i all są obecnie równoważne, ponieważ gdy Mattermost ma korzeń wątku, kolejne fragmenty i media są kontynuowane w tym samym wątku.

# Kontrola dostępu (DM-y)

• Domyślnie: channels.mattermost.dmPolicy = "pairing" (nieznani nadawcy otrzymują kod parowania).
• Zatwierdzanie przez:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• Publiczne DM-y: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

# Kanały (grupy)

• Domyślnie: channels.mattermost.groupPolicy = "allowlist" (bramkowane wzmianką).
• Dodaj nadawców do listy dozwolonych przez channels.mattermost.groupAllowFrom (zalecane identyfikatory użytkowników).
• Zastąpienia wzmianek dla poszczególnych kanałów znajdują się pod channels.mattermost.groups.<channelId>.requireMention albo channels.mattermost.groups["*"].requireMention jako wartość domyślna.
• Dopasowywanie @username jest zmienne i włączone tylko wtedy, gdy channels.mattermost.dangerouslyAllowNameMatching: true.
• Otwarte kanały: channels.mattermost.groupPolicy="open" (bramkowane wzmianką).
• Uwaga dotycząca środowiska uruchomieniowego: jeśli channels.mattermost całkowicie brakuje, środowisko uruchomieniowe używa awaryjnie groupPolicy="allowlist" dla kontroli grup (nawet jeśli ustawiono channels.defaults.groupPolicy).

Przykład:

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

# Cele dla dostarczania wychodzącego

Użyj tych formatów celów z openclaw message send albo cron/webhooks:

• channel:<id> dla kanału
• user:<id> dla DM
• @username dla DM (rozpoznawane przez API Mattermost)

# Ponawianie kanału DM

Gdy OpenClaw wysyła do celu DM Mattermost i musi najpierw rozpoznać kanał bezpośredni, domyślnie ponawia przejściowe błędy tworzenia kanału bezpośredniego.

Użyj channels.mattermost.dmChannelRetry, aby dostroić to zachowanie globalnie dla Plugin Mattermost, albo channels.mattermost.accounts.<id>.dmChannelRetry dla jednego konta.

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

Uwagi:

• Dotyczy to tylko tworzenia kanału DM (/api/v4/channels/direct), a nie każdego wywołania API Mattermost.
• Ponowienia dotyczą przejściowych błędów, takich jak limity szybkości, odpowiedzi 5xx oraz błędy sieci lub przekroczenia czasu.
• Błędy klienta 4xx inne niż 429 są traktowane jako trwałe i nie są ponawiane.

# Strumieniowanie podglądu

Mattermost strumieniuje myślenie, aktywność narzędzi i częściowy tekst odpowiedzi do jednego roboczego posta podglądu, który jest finalizowany w miejscu, gdy końcowa odpowiedź jest bezpieczna do wysłania. Podgląd jest aktualizowany na tym samym identyfikatorze posta zamiast zasypywać kanał wiadomościami dla każdego fragmentu. Końcowe wiadomości z mediami/błędami anulują oczekujące edycje podglądu i używają normalnego dostarczania zamiast opróżniać jednorazowy post podglądu.

Włącz przez channels.mattermost.streaming:

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

# Reakcje (narzędzie wiadomości)

• Użyj message action=react z channel=mattermost.
• messageId to identyfikator posta Mattermost.
• emoji przyjmuje nazwy takie jak thumbsup albo :+1: (dwukropki są opcjonalne).
• Ustaw remove=true (wartość logiczna), aby usunąć reakcję.
• Zdarzenia dodania/usunięcia reakcji są przekazywane jako zdarzenia systemowe do skierowanej sesji agenta.

Przykłady:

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

Konfiguracja:

• channels.mattermost.actions.reactions: włącza/wyłącza akcje reakcji (domyślnie true).
• Zastąpienie dla konta: channels.mattermost.accounts.<id>.actions.reactions.

# Interaktywne przyciski (narzędzie wiadomości)

Wysyłaj wiadomości z klikalnymi przyciskami. Gdy użytkownik kliknie przycisk, agent otrzymuje wybór i może odpowiedzieć.

Włącz przyciski, dodając inlineButtons do możliwości kanału:

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

Użyj message action=send z parametrem buttons. Przyciski są tablicą 2D (wiersze przycisków):

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

Pola przycisków:

Gdy użytkownik kliknie przycisk:

# Bezpośrednia integracja API (skrypty zewnętrzne)

Skrypty zewnętrzne i Webhooki mogą publikować przyciski bezpośrednio przez Mattermost REST API zamiast przez narzędzie message agenta. Gdy to możliwe, używaj buildButtonAttachments() z Plugin; jeśli publikujesz surowy JSON, przestrzegaj tych reguł:

Struktura ładunku:

{
  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
              },
            },
          },
        ],
      },
    ],
  },
}

Generowanie tokenu HMAC

Gateway weryfikuje kliknięcia przycisków za pomocą HMAC-SHA256. Skrypty zewnętrzne muszą generować tokeny zgodne z logiką weryfikacji gatewaya:

Przykład w Pythonie:

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}

# Adapter katalogu

Plugin Mattermost zawiera adapter katalogu, który rozwiązuje nazwy kanałów i użytkowników przez Mattermost API. Umożliwia to używanie celów #channel-name i @username w openclaw message send oraz dostawach Cron/Webhook.

Konfiguracja nie jest potrzebna - adapter używa tokenu bota z konfiguracji konta.

# Wiele kont

Mattermost obsługuje wiele kont pod 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" },
      },
    },
  },
}

# Rozwiązywanie problemów

# Powiązane

• Routing kanałów - routing sesji dla wiadomości
• Przegląd kanałów - wszystkie obsługiwane kanały
• Grupy - zachowanie czatu grupowego i bramkowanie wzmianek
• Parowanie - uwierzytelnianie DM i przepływ parowania
• Bezpieczeństwo - model dostępu i wzmacnianie zabezpieczeń