Mattermost

Status: downloadbare Plugin (bottoken + WebSocket-gebeurtenissen). Kanalen, groepen en DM's worden ondersteund. Mattermost is een zelf te hosten platform voor teamberichten; zie de officiële site op mattermost.com voor productdetails en downloads.

# Installeren

Installeer Mattermost voordat je het kanaal configureert:

openclaw plugins install @openclaw/mattermost

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

Details: Plugins

# Snelle configuratie

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

# Native slashcommando's

Native slashcommando's zijn opt-in. Wanneer ze zijn ingeschakeld, registreert OpenClaw oc_*-slashcommando's via de Mattermost-API en ontvangt het callback-POST's op de HTTP-server van de 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",
      },
    },
  },
}

# Omgevingsvariabelen (standaardaccount)

Stel deze in op de Gateway-host als je liever env vars gebruikt:

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

# Chatmodi

Mattermost reageert automatisch op DM's. Kanaalgedrag wordt beheerd door chatmode:

Configuratievoorbeeld:

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

Opmerkingen:

• onchar reageert nog steeds op expliciete @vermeldingen.
• channels.mattermost.requireMention wordt gerespecteerd voor legacyconfiguraties, maar chatmode heeft de voorkeur.

# Threads en sessies

Gebruik channels.mattermost.replyToMode om te bepalen of kanaal- en groepsantwoorden in het hoofdkanaal blijven of een thread starten onder de activerende post.

• off (standaard): antwoord alleen in een thread wanneer de binnenkomende post er al in staat.
• first: start voor posts op het hoogste niveau in kanalen/groepen een thread onder die post en routeer het gesprek naar een thread-gebonden sessie.
• all: hetzelfde gedrag als first voor Mattermost vandaag.
• Direct messages negeren deze instelling en blijven zonder thread.

Configuratievoorbeeld:

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

Opmerkingen:

• Thread-gebonden sessies gebruiken de activerende post-id als threadroot.
• first en all zijn momenteel equivalent, omdat zodra Mattermost een threadroot heeft, vervolgchunks en media in dezelfde thread doorgaan.

# Toegangscontrole (DM's)

• Standaard: channels.mattermost.dmPolicy = "pairing" (onbekende afzenders krijgen een koppelingscode).
• Goedkeuren via:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• Openbare DM's: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

# Kanalen (groepen)

• Standaard: channels.mattermost.groupPolicy = "allowlist" (afgeschermd door vermeldingen).
• Zet afzenders op de allowlist met channels.mattermost.groupAllowFrom (gebruikers-ID's aanbevolen).
• Vermeldingsoverschrijvingen per kanaal staan onder channels.mattermost.groups.<channelId>.requireMention of channels.mattermost.groups["*"].requireMention voor een standaardwaarde.
• @username-matching is veranderlijk en alleen ingeschakeld wanneer channels.mattermost.dangerouslyAllowNameMatching: true.
• Open kanalen: channels.mattermost.groupPolicy="open" (afgeschermd door vermeldingen).
• Runtime-opmerking: als channels.mattermost volledig ontbreekt, valt runtime terug op groupPolicy="allowlist" voor groepscontroles (zelfs als channels.defaults.groupPolicy is ingesteld).

Voorbeeld:

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

# Targets voor uitgaande aflevering

Gebruik deze targetindelingen met openclaw message send of cron/webhooks:

• channel:<id> voor een kanaal
• user:<id> voor een DM
• @username voor een DM (opgelost via de Mattermost-API)

# Opnieuw proberen voor DM-kanaal

Wanneer OpenClaw verzendt naar een Mattermost-DM-target en eerst het directe kanaal moet oplossen, probeert het standaard tijdelijke fouten bij het aanmaken van directe kanalen opnieuw.

Gebruik channels.mattermost.dmChannelRetry om dat gedrag globaal af te stemmen voor de Mattermost-Plugin, of channels.mattermost.accounts.<id>.dmChannelRetry voor één account.

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

Opmerkingen:

• Dit geldt alleen voor het aanmaken van DM-kanalen (/api/v4/channels/direct), niet voor elke Mattermost-API-aanroep.
• Nieuwe pogingen gelden voor tijdelijke fouten zoals rate limits, 5xx-responsen en netwerk- of time-outfouten.
• 4xx-clientfouten anders dan 429 worden als permanent behandeld en worden niet opnieuw geprobeerd.

# Preview-streaming

Mattermost streamt denkwerk, toolactiviteit en gedeeltelijke antwoordtekst naar één conceptpreviewpost die op zijn plek wordt definitief gemaakt wanneer het definitieve antwoord veilig kan worden verzonden. De preview wordt bijgewerkt op dezelfde post-id in plaats van het kanaal te spammen met berichten per chunk. Definitieve media-/foutberichten annuleren wachtende previewbewerkingen en gebruiken normale aflevering in plaats van een wegwerppreviewpost te flushen.

Inschakelen via channels.mattermost.streaming:

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

# Reacties (berichtentool)

• Gebruik message action=react met channel=mattermost.
• messageId is de Mattermost-post-id.
• emoji accepteert namen zoals thumbsup of :+1: (dubbele punten zijn optioneel).
• Stel remove=true (boolean) in om een reactie te verwijderen.
• Gebeurtenissen voor toevoegen/verwijderen van reacties worden als systeemgebeurtenissen doorgestuurd naar de gerouteerde agentsessie.

Voorbeelden:

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

Configuratie:

• channels.mattermost.actions.reactions: reactieacties in-/uitschakelen (standaard true).
• Overschrijving per account: channels.mattermost.accounts.<id>.actions.reactions.

# Interactieve knoppen (berichtentool)

Verzend berichten met aanklikbare knoppen. Wanneer een gebruiker op een knop klikt, ontvangt de agent de selectie en kan deze reageren.

Schakel knoppen in door inlineButtons toe te voegen aan de kanaalmogelijkheden:

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

Gebruik message action=send met een buttons-parameter. Knoppen zijn een 2D-array (rijen knoppen):

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

Knopvelden:

Wanneer een gebruiker op een knop klikt:

# Directe API-integratie (externe scripts)

Externe scripts en webhooks kunnen knoppen rechtstreeks plaatsen via de Mattermost REST API in plaats van via de message-tool van de agent. Gebruik waar mogelijk buildButtonAttachments() uit de Plugin; als je onbewerkte JSON plaatst, volg dan deze regels:

Payloadstructuur:

{
  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-token genereren

De gateway verifieert knopklikken met HMAC-SHA256. Externe scripts moeten tokens genereren die overeenkomen met de verificatielogica van de gateway:

Python-voorbeeld:

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}

# Directory-adapter

De Mattermost-Plugin bevat een directory-adapter die kanaal- en gebruikersnamen oplost via de Mattermost API. Dit maakt #channel-name- en @username-doelen mogelijk in openclaw message send en cron/webhook-leveringen.

Er is geen configuratie nodig - de adapter gebruikt het bottoken uit de accountconfiguratie.

# Multi-account

Mattermost ondersteunt meerdere accounts onder 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" },
      },
    },
  },
}

# Probleemoplossing

# Gerelateerd

• Kanaalroutering - sessieroutering voor berichten
• Kanalenoverzicht - alle ondersteunde kanalen
• Groepen - gedrag van groepschats en vermeldingsgating
• Koppelen - DM-authenticatie en koppelingsflow
• Beveiliging - toegangsmodel en hardening