OpenClaw

OpenClaw Mattermost Channel

Enterprise
Medium

Connect OpenClaw to Mattermost, the open-source enterprise messaging platform, enabling your AI assistant to participate in direct messages, group channels, and team conversations. The integration uses bot token authentication and WebSocket events for real-time bidirectional communication, with flexible chat modes and granular access control policies.

Quick Info
DifficultyMedium
CategoryEnterprise
Features Supported5 / 6

Mattermost Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Supported

Voice Messages

Not Supported

Group Chat

Supported

Mattermost Prerequisites

  • A Mattermost server (self-hosted or cloud) with admin access to create bot accounts
  • A Bot Account with a bot token created in Mattermost System Console
  • The Mattermost server base URL accessible from the OpenClaw Gateway
  • OpenClaw Gateway installed and running
  • The Mattermost plugin installed via 'openclaw plugins install @openclaw/mattermost'

Mattermost Quick Setup

1

Install the Mattermost plugin

Run 'openclaw plugins install @openclaw/mattermost' to add Mattermost support to your Gateway.

2

Create a Bot Account in Mattermost

Go to Mattermost System Console > Integrations > Bot Accounts. Click 'Add Bot Account', set a display name and description, and copy the generated bot token. Make sure 'Enable Bot Account Creation' is set to true in System Console > Integrations > Integration Management.

3

Configure and launch

Add the Mattermost channel configuration to ~/.openclaw/openclaw.json with your botToken, baseUrl, and desired policies. Start the Gateway with 'openclaw start'. Send a direct message to the bot or @mention it in a channel to verify the connection.

Mattermost Configuration Example

config.json
{
  "channels": {
    "mattermost": {
      "enabled": true,
      "botToken": "your-bot-token",
      "baseUrl": "https://mattermost.example.com",
      "dmPolicy": "pairing",
      "chatmode": "oncall"
    }
  }
}

Mattermost Deep Dive

Architecture Overview

OpenClaw connects to Mattermost through its REST API and WebSocket event stream. On startup, the Gateway authenticates using your bot token, establishes a persistent WebSocket connection, and begins listening for message events. When a message matches the active chat mode trigger (mention, prefix, or all messages), the Gateway forwards it to your AI agent. The agent's response is posted back to the same channel or DM thread via the Mattermost REST API. The integration supports rich features including media attachments, message reactions, threaded replies, and group channel management — making it one of the most fully-featured enterprise channel integrations available.
The WebSocket connection automatically reconnects if the connection drops.
Each account generates a unique session key (agent:<agentId>:mattermost:<accountName>) for independent conversation tracking.

Creating a Bot Account

Mattermost bot accounts are dedicated service accounts that don't consume a user license. 1. Navigate to System Console > Integrations > Bot Accounts. 2. Ensure 'Enable Bot Account Creation' is enabled under Integration Management. 3. Click 'Add Bot Account' and fill in the display name, description, and icon. 4. Select the appropriate role (System Admin is NOT recommended — use the default Member role). 5. Copy the generated bot token immediately — it won't be shown again. The bot must be added to any channels where it needs to operate. Team admins or system admins can add the bot to channels manually, or users can invite it via @mention.
openclaw.json
{
  "channels": {
    "mattermost": {
      "botToken": "your-bot-token",
      "baseUrl": "https://mattermost.example.com"
    }
  }
}
Store the bot token securely. If lost, you must regenerate it from System Console.
Bot accounts do not count against your Mattermost license seat limit.

Chat Modes

OpenClaw supports three chat modes that control when the bot responds to messages in channels: **oncall (default)** — The bot only responds when @mentioned by name. This is the safest mode for busy channels, as the bot stays silent unless explicitly invoked. **onmessage** — The bot responds to every message from allowed users. Best suited for dedicated bot channels or low-traffic environments where every message should receive a response. **onchar** — The bot responds when a message starts with a specific prefix character (e.g., '!' or '/'). Configure the trigger prefixes with oncharPrefixes. This mode is useful when you want explicit but concise activation without typing the full bot name.
openclaw.json
{
  "channels": {
    "mattermost": {
      "chatmode": "onchar",
      "oncharPrefixes": ["!", "/ai"]
    }
  }
}
In DMs, the bot always responds to all messages regardless of chat mode.
The oncall mode is recommended for team channels to avoid noise.

DM Policies

Direct Message (DM) policies control who can interact with the bot via private messages. **pairing (default)** — Only users explicitly listed in the allowFrom array can DM the bot. This is the most restrictive mode, ideal for controlling exactly which users have access. **open** — Any Mattermost user who sends a DM to the bot will receive a response. Use this when you want the bot to be broadly accessible across your organization. The allowFrom field accepts Mattermost user IDs. You can find a user's ID in System Console > Users, or via the Mattermost API.
openclaw.json
{
  "channels": {
    "mattermost": {
      "dmPolicy": "pairing",
      "allowFrom": ["user-id-1", "user-id-2"]
    }
  }
}
Setting dmPolicy to 'open' allows any user on your Mattermost server to consume AI quota via DMs. Use with caution on large servers.

Group and Channel Policies

Group policies control which channels the bot participates in when receiving group messages. **allowlist (default)** — The bot only responds in channels explicitly listed in groupAllowFrom. Messages in other channels are silently ignored. **open** — The bot responds in any channel it has been added to. This is convenient but may lead to unintended interactions if the bot is added to many channels. The groupAllowFrom field accepts Mattermost channel IDs. You can find a channel's ID from the channel URL or via the Mattermost API.
openclaw.json
{
  "channels": {
    "mattermost": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["channel-id-1", "channel-id-2"]
    }
  }
}
Use allowlist mode in production to prevent the bot from responding in unintended channels.
The bot must be a member of the channel to receive messages, regardless of the group policy.

Multi-Account Setup

OpenClaw supports running multiple Mattermost bot accounts simultaneously, each targeting a different Mattermost server or operating with different configurations. Use the accounts.<name> pattern to configure multiple accounts. Each account has its own bot token, base URL, chat mode, and access policies. This is useful for organizations running multiple Mattermost instances (e.g., production and staging) or when different teams need bots with different behaviors.
openclaw.json
{
  "channels": {
    "mattermost": {
      "accounts": {
        "production": {
          "botToken": "prod-bot-token",
          "baseUrl": "https://mattermost.company.com",
          "chatmode": "oncall",
          "dmPolicy": "pairing",
          "allowFrom": ["user-1", "user-2"]
        },
        "dev-team": {
          "botToken": "dev-bot-token",
          "baseUrl": "https://mm-dev.company.com",
          "chatmode": "onmessage",
          "dmPolicy": "open"
        }
      }
    }
  }
}

Outbound Messaging

AI agents can proactively send messages to Mattermost channels and users using the mattermost tool action. This enables scheduled notifications, alerts, and automated updates without a user trigger. Supported target formats: • channel:<channel-id> — Send to a specific channel by ID • user:<user-id> — Send a direct message to a specific user by ID • @username — Send a direct message to a user by their username The bot must have permission to post in the target channel or initiate a DM with the target user.
agent-action.json
{
  "action": "mattermost",
  "params": {
    "message": "Daily standup reminder: please post your updates!",
    "to": "channel:abc123def456"
  }
}
Use channel IDs (not names) for reliable delivery. Channel names can be renamed.
The bot must be a member of the target channel to post messages.

Rich Message Features

Mattermost supports a wide range of message features that OpenClaw fully leverages: **Media Attachments** — The bot can send and receive images, files, and other attachments. Media shared by users is forwarded to the AI agent for processing. **Reactions** — The bot can add emoji reactions to messages. This is useful for acknowledgment or status indicators. **Threaded Replies** — The bot supports Mattermost's threading model. When a user replies in a thread, the bot maintains context within that thread. **Markdown** — Mattermost natively renders Markdown, so the bot's responses can include formatted text, code blocks, tables, and links.
Threaded replies help keep conversations organized, especially in busy channels.
File attachments are subject to your Mattermost server's upload size limits.

Rate Limits and Best Practices

Mattermost applies rate limiting to its REST API to protect server performance. The default limits are: • 10 requests per second per user (sustained) • 100 requests burst capacity These limits apply to the bot account's API calls, including posting messages, adding reactions, and uploading files. Best practices for production deployments: 1. Use oncall or onchar chat mode in busy channels to reduce unnecessary API calls. 2. Keep groupPolicy as allowlist to prevent the bot from responding in every channel. 3. Monitor the bot's API usage in Mattermost System Console > Environment > Rate Limiting. 4. For high-traffic deployments, consider running separate accounts for different teams.
If the bot exceeds rate limits, Mattermost returns HTTP 429 errors. The Gateway will retry with backoff, but sustained overuse may require configuration adjustments.

Mattermost Configuration Reference

enabled
Type: booleanDefault: true

Enable or disable the Mattermost channel

botToken
Type: stringDefault: ""

Bot token from Mattermost System Console > Bot Accounts

baseUrl
Type: stringDefault: ""

Full URL of your Mattermost server (e.g., https://mattermost.example.com)

chatmode
Type: stringDefault: "oncall"

Chat trigger mode: 'oncall' (mention), 'onmessage' (all), or 'onchar' (prefix)

oncharPrefixes
Type: string[]Default: []

Prefix characters that trigger the bot when chatmode is 'onchar'

dmPolicy
Type: stringDefault: "pairing"

DM access policy: 'pairing' (allowlist only) or 'open' (any user)

allowFrom
Type: string[]Default: []

Mattermost user IDs allowed to DM the bot (used with dmPolicy: pairing)

groupPolicy
Type: stringDefault: "allowlist"

Group channel policy: 'allowlist' (specified channels only) or 'open' (any channel)

groupAllowFrom
Type: string[]Default: []

Mattermost channel IDs where the bot is allowed to respond (used with groupPolicy: allowlist)

requireMention
Type: booleanDefault: true

Legacy setting — prefer using chatmode: 'oncall' instead

accounts.<id>.botToken
Type: stringDefault: ""

Bot token for a specific account in multi-account mode

accounts.<id>.baseUrl
Type: stringDefault: ""

Mattermost server URL for a specific account

accounts.<id>.chatmode
Type: stringDefault: "oncall"

Chat trigger mode for a specific account

accounts.<id>.dmPolicy
Type: stringDefault: "pairing"

DM access policy for a specific account

Mattermost Frequently Asked Questions

Mattermost Troubleshooting

Bot does not respond to messages

The chat mode or access policy may be filtering out the messages.

Check that chatmode matches your expected trigger (oncall requires @mention, onchar requires a prefix). Verify that dmPolicy and allowFrom include the user's ID for DMs, or that groupPolicy and groupAllowFrom include the channel ID for group messages.
WebSocket connection fails on startup

The baseUrl is incorrect, the bot token is invalid, or the server is unreachable.

Verify that baseUrl points to the correct Mattermost server (include the protocol, e.g., https://). Ensure the bot token is valid and has not been revoked. Check network connectivity and firewall rules between the Gateway and the Mattermost server.
Bot cannot post in a channel

The bot is not a member of the target channel.

Add the bot to the channel manually via Mattermost (click 'Add Members' in the channel), or invite it by @mentioning its username. The bot must be a channel member to post messages.
Media attachments are not being processed

The Mattermost server's file upload settings may restrict file types or sizes.

Check System Console > Environment > File Storage for upload limits. Ensure the bot account has permission to access file attachments. Verify that the Gateway can reach the Mattermost file API endpoint.
Rate limit errors (HTTP 429) in logs

The bot is making too many API requests in a short period.

Switch from onmessage to oncall or onchar mode to reduce API calls. Limit the number of channels the bot is active in. Check System Console > Environment > Rate Limiting to view or adjust server-side rate limits.
View Full DocumentationBack to All Channels

Related Channels

Feishu / Lark

Medium

OpenClaw Feishu/Lark integration via WebSocket

Setup Guide

Slack

Medium

OpenClaw workspace app via Bolt SDK

Setup Guide

Google Chat

Medium

OpenClaw Google Chat API app via HTTP endpoint

Setup Guide