How to Connect OpenClaw to Mattermost

Prerequisites

• ✓A running Mattermost server with access to create a bot account and obtain a bot token.
• ✓An OpenClaw gateway installation that can load bundled plugins and reach your Mattermost server over HTTPS.
• ✓A Mattermost base URL such as `https://chat.example.com` that OpenClaw can reach from the gateway host.

Steps

1. 1

   Ensure the Mattermost plugin is available in OpenClaw

   OpenClaw’s Mattermost support ships as a bundled plugin in current releases, so most installs work out of the box. If you run an older build or a custom install that excludes Mattermost, install the plugin explicitly so the gateway can connect to your server.

   bashCopy

   openclaw plugins install @openclaw/mattermost

2. 2

   Install the Mattermost plugin from a local checkout when developing

   If you work from a git repo and have the Mattermost plugin checked out locally, point OpenClaw at that path. This is useful when you modify the plugin and want the gateway to load your local version instead of the npm package.

   bashCopy

   openclaw plugins install ./path/to/local/mattermost-plugin

3. 3

   Create a Mattermost bot and collect the bot token and base URL

   In your Mattermost server, create a bot account and copy its bot token; OpenClaw uses this to authenticate API calls and WebSocket events. com`) so the plugin knows where to connect.

4. 4

   Configure the Mattermost channel in OpenClaw

   Add a minimal Mattermost channel configuration so the gateway can log in with your bot and start handling DMs and channels. This is the core wiring: enable the plugin, set the bot token, base URL, and DM policy, then start or reload your gateway.

   jsonCopy

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

5. 5

   Optionally configure Mattermost via environment variables

   If you prefer env vars over inline config for the default account, set the Mattermost bot token and URL on the gateway host. These only apply to the `default` account, so keep that in mind if you later add multi-account setups.

   bashCopy

   MATTERMOST_BOT_TOKEN=...
   MATTERMOST_URL=https://chat.example.com
   

6. 6

   Enable native slash commands for Mattermost

   To let users trigger agents with `/oc_*` commands, turn on native slash commands in the Mattermost channel config. You can also set a public `callbackUrl` when Mattermost cannot reach the gateway directly, which is common when the gateway sits behind a reverse proxy.

   jsonCopy

   {
     channels: {
       mattermost: {
         commands: {
           native: true,
           nativeSkills: true,
           callbackPath: "/api/channels/mattermost/command",
           // Use when Mattermost cannot reach the gateway directly (reverse proxy/public URL).
           callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
         },
       },
     },
   }
   

7. 7

   Tune chat modes and channel behavior

   Control how your agent responds in Mattermost channels by setting `chatmode` and optional trigger prefixes. This lets you keep channels quiet until mentioned, respond to every message, or only react when messages start with specific characters.

   jsonCopy

   {
     channels: {
       mattermost: {
         chatmode: "onchar",
         oncharPrefixes: [">", "!"],
       },
     },
   }
   

8. 8

   Configure threading and sessions for channel replies

   Decide whether the agent replies inline in channels or starts threads under the triggering post. Thread-scoped sessions keep long conversations organized and easier to follow for your team.

   jsonCopy

   {
     channels: {
       mattermost: {
         replyToMode: "all",
       },
     },
   }
   

9. 9

   Set DM access control and group policies

   Lock down who can DM the bot and how it behaves in channels by configuring DM policy, allowlists, and per-channel mention rules. This prevents the agent from responding in places you don’t expect and gives you fine-grained control over exposure.

   jsonCopy

   {
     channels: {
       mattermost: {
         groupPolicy: "open",
         groups: {
           "*": { requireMention: true },
           "team-channel-id": { requireMention: false },
         },
       },
     },
   }
   

10. 10

    Enable interactive buttons and reactions for richer UX

    Turn on inline buttons so your agent can send clickable options, and use the reactions message tool to react to posts. Buttons require the `inlineButtons` capability and a reachable callback URL from the Mattermost server.

    jsonCopy

    {
      channels: {
        mattermost: {
          capabilities: ["inlineButtons"],
        },
      },
    }
    

11. 11

    Configure multi-account Mattermost setups in OpenClaw

    accounts`. Each account gets its own bot token and base URL, and you can override settings like DM retry or commands per account.

    jsonCopy

    {
      channels: {
        mattermost: {
          accounts: {
            default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
            alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
          },
        },
      },
    }
    

Configuration

Troubleshooting

id: "mybutton01" // alphanumeric only — see below

Frequently asked questions