Mattermost is an open-source team collaboration platform often used as a self-hosted alternative to Slack. It supports private deployment, making it ideal for enterprises and organizations with strict data security requirements. OpenClaw provides Mattermost channel support through its plugin system, allowing you to interact with AI agents directly within Mattermost.
Prerequisites
Before starting the configuration, ensure the following conditions are met:
- An OpenClaw instance is deployed and running normally
- An accessible Mattermost server (self-hosted or cloud-hosted)
- Mattermost system administrator privileges (for creating a Bot account)
- Mattermost server version 5.0 or above is recommended
Creating a Mattermost Bot Account
Log in to the Mattermost admin console and navigate to "Integrations" > "Bot Accounts". Click "Create Bot Account" and fill in the username, display name, and description. After creation, the system will generate an Access Token — save this token carefully, as it will only be displayed once.
If your Mattermost instance doesn't have the Bot Accounts feature enabled, you'll need to go to the System Console under "Integrations" > "Bot Accounts" and set "Enable Bot Account Creation" to true.
Additionally, make sure that "Enable Incoming Webhooks" and "Enable Outgoing Webhooks" are both turned on under "Integrations" > "Integration Management".
Installing the Mattermost Plugin
Install Mattermost support through the OpenClaw plugin system:
openclaw plugin install mattermost
Then use the interactive login command for configuration:
openclaw channels login mattermost
The system will prompt you to enter the Mattermost server address, the Bot's Access Token, and other information.
Configuring openclaw.json
You can also manually configure it directly in openclaw.json:
{
"channels": {
"mattermost": {
"enabled": true,
"serverUrl": "https://mattermost.your-company.com",
"token": "your-bot-access-token",
"teamName": "your-team-name"
}
}
}
serverUrl is the full address of your Mattermost server, token is the Access Token obtained when creating the Bot, and teamName is the name of the team the Bot belongs to.
WebSocket Connection Mode
The Mattermost plugin uses WebSocket connections by default to receive messages in real time. This means OpenClaw actively connects to the Mattermost server, requiring no additional webhook callback URL configuration. This mode is very friendly to self-hosted environments behind firewalls, as it only requires outbound connections.
Once the connection is established, OpenClaw automatically listens for events where the Bot is mentioned or receives direct messages, forwarding them to the AI model for processing.
Channel and Direct Message Behavior
In Mattermost, the Bot can handle both direct messages and @mention messages in channels. The default behavior is as follows:
- Direct Messages: The Bot responds to all received messages
- Public/Private Channels: The Bot only responds to @mentions
You can customize this behavior in the configuration:
{
"channels": {
"mattermost": {
"respondToDirectMessages": true,
"respondToMentions": true,
"respondToAll": false
}
}
}
Setting respondToAll to true will make the Bot respond to all messages in channels it has joined, but this may generate a large number of API calls in active channels — use with caution.
Slash Command Integration
Mattermost supports custom slash commands. You can create a slash command pointing to OpenClaw, allowing users to invoke AI through commands like /ask. In the Mattermost admin console under "Integrations" > "Slash Commands", create a new command and set the request URL to OpenClaw's Mattermost webhook endpoint.
Security and Access Control
Using OpenClaw's allowlist feature, you can precisely control which Mattermost users can interact with the AI:
{
"channels": {
"mattermost": {
"allowlist": ["username1", "username2"],
"allowedChannels": ["channel-id-1", "channel-id-2"]
}
}
}
allowlist restricts which users can interact, and allowedChannels limits the Bot to responding only in specified channels. This is useful for controlling AI usage costs and scope.
You can also combine this with OpenClaw's DM pairing feature, requiring users to complete identity verification through a direct message first.
Multi-Channel Coexistence
The Mattermost channel can run simultaneously with other OpenClaw channels. Multiple channels can be enabled in the configuration file, all sharing the same AI backend. For example, you can run Mattermost for internal team communication and Telegram for external community support at the same time. Messages from all channels are processed independently without interfering with each other.
Troubleshooting
If the Bot cannot connect to the Mattermost server, first check whether the server address is correct and the Token is valid. You can test connectivity with the following command:
curl -H "Authorization: Bearer your-token" https://mattermost.your-company.com/api/v4/users/me
If it returns the Bot's user information, authentication is working correctly. If WebSocket connections disconnect frequently, check whether proxies or firewalls in your network environment are interfering with long-lived connections, and configure the WebSocket ping interval parameter if necessary.