Mattermost (plugin)

Plugin required

openclaw plugins install @openclaw/mattermost

openclaw plugins install ./extensions/mattermost

Quick setup

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.

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

Environment variables (default account)

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

Chat modes

• oncall (default): respond only when @mentioned in channels.
• onmessage: respond to every channel message.
• onchar: respond when a message starts with a trigger prefix.

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

• onchar still responds to explicit @mentions.
• channels.mattermost.requireMention is honored for legacy configs but chatmode is preferred.

Access control (DMs)

• Default: channels.mattermost.dmPolicy = "pairing" (unknown senders get a pairing code).
• Approve via:
  • openclaw pairing list mattermost
  • openclaw pairing approve mattermost <CODE>
• openclaw pairing list mattermost
• openclaw pairing approve mattermost <CODE>
• Public DMs: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

• openclaw pairing list mattermost
• openclaw pairing approve mattermost <CODE>

Channels (groups)

• Default: channels.mattermost.groupPolicy = "allowlist" (mention-gated).
• Allowlist senders with channels.mattermost.groupAllowFrom (user IDs or @username).
• Open channels: channels.mattermost.groupPolicy="open" (mention-gated).

Targets for outbound delivery

• channel:<id> for a channel
• user:<id> for a DM
• @username for a DM (resolved via the Mattermost API)

Multi-account

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

Troubleshooting

• No replies in channels: ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set chatmode: "onmessage".
• Auth errors: check the bot token, base URL, and whether the account is enabled.
• Multi-account issues: env vars only apply to the default account.