Mattermost

Self-hosted Mattermost integration via bot token and WebSocket events with DMs, channels, reactions, inline buttons, native slash commands, and directory adapter.

Mattermost is a self-hosted, open-source team messaging platform that gives organizations full control over their communication infrastructure. OpenClaw's Mattermost integration connects via bot token and WebSocket events, providing a real-time bidirectional link between your AI agent and your Mattermost workspace. The plugin handles DMs, public and private channels, reactions, interactive inline buttons with HMAC verification, and a directory adapter for @username resolution. The integration supports three chat modes: 'oncall' (respond only when @mentioned), 'onmessage' (respond to every message), and 'onchar' (respond when messages start with a trigger prefix). Native slash commands are opt-in — when enabled, OpenClaw registers oc_* commands via the Mattermost API and receives callback POSTs on the gateway HTTP server. Thread-scoped sessions are supported via replyToMode, routing conversations into threads under triggering posts. Access control is granular: DM policies range from pairing (approval required) to open, and group policies let you allowlist specific channels and senders. The directory adapter resolves @usernames to Mattermost user IDs, though user ID-based allowlists are recommended for stability. Multi-account support lets you connect multiple Mattermost instances or bot accounts from a single OpenClaw gateway. For self-hosted teams that want complete data sovereignty without sacrificing enterprise features, Mattermost + OpenClaw is an excellent pairing. Your messages, your AI, your servers — no third-party cloud involved.

Tags: workspace, self-hosted, open-source, enterprise

Category: Workspace

Use Cases

Self-hosted AI assistant for engineering teams using Mattermost
DevOps chatbot with slash commands for infrastructure queries
Enterprise knowledge base bot in controlled Mattermost channels
Multi-team AI deployment with separate bot accounts per team
Data-sovereign AI assistant where all messages stay on-premises
Internal helpdesk bot with mention-gated access in support channels

Tips

Use 'oncall' chat mode for channels and 'onmessage' for dedicated AI channels to control noise
Set replyToMode: 'all' to automatically route channel conversations into threads for cleaner UX
Use channel:<id> or user:<id> prefixes for outbound messages to avoid ambiguous ID resolution
Configure dmChannelRetry for robust DM delivery in environments with flaky direct channel creation
Prefer user IDs over usernames in allowFrom lists — IDs are immutable
For multi-server setups, each account can have independent commands, chatmode, and access control settings
Test slash command reachability with: curl https://<gateway-host>/api/channels/mattermost/command (should return 405)

Known Issues & Gotchas

Bot accounts must be explicitly enabled in Mattermost System Console → Integrations → Bot Accounts
Native slash commands default to disabled — set commands.native: true explicitly to enable
callbackUrl for slash commands must NOT point to localhost unless Mattermost is on the same host
If Mattermost uses private/tailnet addresses, set AllowedUntrustedInternalConnections in Mattermost config to include the callback host
Env vars (MATTERMOST_BOT_TOKEN, MATTERMOST_URL) only apply to the default account — additional accounts must use config
groupPolicy falls back to 'allowlist' for group checks even if channels.defaults.groupPolicy is set — must configure explicitly
dangerouslyAllowNameMatching: true is required for @username matching in allowlists (disabled by default for security)
Bare opaque IDs are resolved user-first — use user:<id> or channel:<id> prefixes for deterministic outbound delivery

Alternatives

Slack
Discord
Microsoft Teams
Matrix

Community Feedback

Mattermost + OpenClaw is the self-hoster's dream. Both run on your infrastructure, both are open source. I've got them side by side on a Docker Compose stack and it just works.
— Reddit r/selfhosted

The Mattermost plugin for OpenClaw is surprisingly complete — slash commands, inline buttons, even a directory adapter. Setup took me about 10 minutes including the bot account creation.
— Dev.to

Had some trouble with the initial plugin enable step but once configured, Mattermost integration is rock solid. The HMAC-verified buttons are a nice security touch.
— GitHub Issues

Frequently Asked Questions

Is the Mattermost plugin bundled with OpenClaw?

No. Mattermost is a plugin that must be installed separately: openclaw plugins install @openclaw/mattermost. It's not included in the core OpenClaw package.

How do I enable native slash commands?

Set channels.mattermost.commands.native: true in your config. OpenClaw will register oc_* slash commands via the Mattermost API. You also need to ensure the callback URL is reachable from your Mattermost server.

What's the difference between oncall, onmessage, and onchar chat modes?

oncall: bot responds only when @mentioned in channels. onmessage: bot responds to every channel message. onchar: bot responds when messages start with a configured trigger prefix (e.g., '>' or '!'). All modes always respond in DMs.

Can I connect multiple Mattermost servers?

Yes. Use the accounts section under channels.mattermost to configure additional servers. Each account can have its own bot token, base URL, chat mode, and access control settings.

Does Mattermost support streaming responses?

No. The Mattermost plugin sends complete messages rather than streaming edits. This is a limitation of the Mattermost bot API.

How do I make the bot respond in threads instead of the main channel?

Set channels.mattermost.replyToMode to 'all' or 'first'. This routes channel conversations into threads under the triggering post, keeping the main channel clean.

Configuration Examples

Basic bot setup

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

Channel bot with slash commands

channels:
  mattermost:
    enabled: true
    botToken: "mm-token"
    baseUrl: "https://chat.example.com"
    chatmode: oncall
    commands:
      native: true
      nativeSkills: true
      callbackUrl: "https://gateway.example.com/api/channels/mattermost/command"
    groupPolicy: open

Multi-account with threads

channels:
  mattermost:
    enabled: true
    botToken: "token-main"
    baseUrl: "https://chat.example.com"
    replyToMode: all
    accounts:
      ops:
        botToken: "token-ops"
        baseUrl: "https://ops-chat.internal"
        chatmode: onmessage
        dmPolicy: allowlist
        allowFrom:
          - "user-id-1"
          - "user-id-2"

Installation

openclaw plugins install @openclaw/mattermost