Connect Mattermost to Your AI Agent

Why It Is Straightforward

The bot connects outward to your Mattermost server over a WebSocket, so there is nothing to expose and no inbound endpoint to arrange. That makes it a clean fit for a hosted agent, provided your Mattermost server is reachable from the internet. If it lives entirely on an internal network, put both ends on a private network such as Tailscale.

Channels, private channels, group DMs and direct messages are all supported.

Create the Bot Account

1. Enable bot accounts in the system console if your server does not already allow them.
2. Create a bot account and give it a clear name and description.
3. Copy the token it generates. It is shown once.
4. Add the bot to the teams and channels it should take part in. A bot that is not a member of a channel cannot see it.

OpenClaw Setup

Install the plugin, then add the channel with your token and server URL:

openclaw plugins install @openclaw/mattermost
openclaw channels add --channel mattermost --bot-token <token> --http-url https://chat.example.com

Slash commands are available but opt-in. If you turn them on, OpenClaw registers its own commands on every team the bot belongs to, and your Mattermost server needs to be able to reach the bot's callback endpoint — which is the one part of this setup that does require inbound reachability. Leave them off if you only want conversation.

Hermes Setup

Run the guided setup and pick Mattermost:

hermes gateway setup

Or configure it directly:

MATTERMOST_URL=https://mm.example.com
MATTERMOST_TOKEN=your-bot-token

You will also want your own Mattermost user ID to hand, which the setup uses for access control so the agent is not open to your whole server.

Test It

Send the bot a direct message first — that isolates whether the connection works from whether it has channel access. Once DMs reply, mention it in a channel it has been added to.

Troubleshooting

• It replies in DMs but ignores a channel. The bot has not been added to that channel, or it is waiting to be mentioned.
• Connection refused or timeouts. The server URL is wrong, or your Mattermost is on a network the agent cannot reach.
• Authentication failures. The token was regenerated, or you copied a personal access token rather than the bot account token.
• Slash commands do nothing. Their callbacks need your Mattermost server to reach the bot. Plain messaging does not.

Need a Hand?

Contact support from your dashboard and we will set it up on your instance. Do not paste the bot token into chat — we will tell you where to put it.