Mattermost

Status: Supported via plugin (bot token + WebSocket events). Supports channels, groups, and DMs.

Mattermost is a self-hostable team messaging platform; product and downloads at ''mattermost.com''.

Mattermost is provided as a plugin and is not bundled with core installation.

Install via CLI (npm registry):

openclaw plugins install @openclaw/mattermost

Local installation (when running from a git repository):

openclaw plugins install ./extensions/mattermost

If you selected Mattermost in configure/onboarding and a git checkout is detected, OpenClaw will automatically prompt to use the local installation path.

More: ''/plugin''

1. Install the Mattermost plugin.

2. Create a Mattermost bot account and copy the bot token.

3. Copy the Mattermost base URL (e.g., https://chat.example.com).

4. Configure OpenClaw and start the gateway.

Minimal configuration:

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

If you prefer env vars, set on the gateway host:

- MATTERMOST_BOT_TOKEN=...

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

Note: Environment variables only apply to the default account (default). Other accounts must be provided in the configuration file.

Mattermost auto-replies to DMs by default. Channel behavior is controlled by chatmode:

- oncall (default): Only reply when @mentioned in channels.

- onmessage: Reply to every message in channels.

- onchar: Reply when messages start with certain trigger prefixes.

Example:

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

Notes:

- onchar still replies to explicit @mentions.

- channels.mattermost.requireMention in old configs is still compatible, but chatmode is recommended.

- Default: channels.mattermost.dmPolicy = "pairing" (unknown senders receive a pairing code).

- Approve:

- openclaw pairing list mattermost

- openclaw pairing approve mattermost <CODE>

- Public DMs: channels.mattermost.dmPolicy="open" and channels.mattermost.allowFrom=["*"].

- Default: channels.mattermost.groupPolicy = "allowlist" (also affected by mention gating).

- Use channels.mattermost.groupAllowFrom for sender allowlist (user ids or @username).

- Open channels: channels.mattermost.groupPolicy="open" (still affected by mention gating).

Use in openclaw message send or cron/webhooks:

- channel:<id>: Deliver to a channel

- user:<id>: Deliver to a DM

- @username: Deliver to a DM (resolved via Mattermost API)

Bare IDs are treated as channel IDs.

Configure multiple accounts under channels.mattermost.accounts:

{
  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" },
      },
    },
  },
}

- No reply in channels: Ensure bot has joined the channel; @mention is needed in oncall mode; trigger prefix is needed in onchar mode; or set chatmode to onmessage.

- Authentication errors: Check bot token, base URL, and whether the account is enabled.

- Multi-account issues: Environment variables only apply to the default account.