How to Connect OpenClaw to Mattermost - Bot Token Setup

Mattermost is a strong self-hosted alternative when you want team chat, channels, threads, and bot control without giving up operator visibility. OpenClaw documents Mattermost as a bundled plugin using a bot token plus WebSocket events, with support for DMs, channels, and groups.

What the official docs support

The official docs cover more than just basic messaging. In addition to the minimal botToken and baseUrl setup, they document native slash commands, multiple chat modes, thread reply modes, preview streaming, DM channel retry behavior, and explicit outbound target formats such as user:<id> and channel:<id>.

This is a good integration for teams that want a bot to feel native inside a work chat product rather than bolted on top. The docs make it possible to keep DMs automatic, keep channels mention-gated by default, and then selectively enable thread replies or slash commands for teams that actually benefit from them.

What you need first

• A Mattermost bot account and bot token
• The base URL of your Mattermost server
• A decision on whether channels should be mention-gated or chatmode-driven
• A reachable callback endpoint if you plan to enable native slash commands

Recommended setup flow

The clean baseline is simple: get the bot token working first, then add the more opinionated features like native slash commands only when the normal chat path is already healthy.

1. Create the Mattermost bot account, copy the bot token, and record the base URL of the server. That is all you need for the documented minimal config.
2. Configure channels.mattermost with enabled, botToken, baseUrl, and a DM policy. DMs default to pairing, which is sensible for most internal deployments and lets you see exactly who is trying to talk to the bot.
3. Choose the channel behavior you want. The docs document chatmode oncall as the default, which replies only when the bot is @ mentioned. You can switch to onmessage for every message or onchar if you want a prefix-triggered style.
4. If thread behavior matters, set replyToMode after the baseline works. The docs explain off, first, and all, with first and all both creating thread-scoped sessions for top-level posts today.
5. Enable native slash commands only after verifying reachability from Mattermost to the callback path. OpenClaw can register oc_* commands automatically, but the callback endpoint must be reachable from the Mattermost server and not just from your laptop.

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

Access, safety, and operational notes

Mattermost access control stays sane if you separate DMs from channels. DMs use pairing by default, channels use groupPolicy allowlist and mention gating by default, and the docs strongly prefer stable IDs over mutable usernames when you are doing sender allowlists or outbound targeting.

The callback notes for native slash commands are worth taking seriously. The docs explicitly warn against using localhost in callbackUrl unless Mattermost runs in the same namespace, and they recommend checking for a 405 response on the callback path as proof that OpenClaw is actually serving it.

How to verify it is working

Test in three passes: a DM, a mention in one channel, and then a slash command only if you enabled native commands. If a DM works but a channel does not, that usually points to group policy, requireMention, or chatmode rather than an auth problem.

Common gotchas

• Native slash commands must be reachable from the Mattermost server, not only from your browser
• Use explicit user:<id> or channel:<id> targets to avoid ambiguous IDs
• oncall is the documented default chatmode, so channel silence may be expected until you mention the bot

If you want the operator version with tighter rollout checklists, safer defaults, and more production patterns, The OpenClaw Playbook is the easiest shortcut.