openclaw/docs/channels/mattermost.md

summary	read_when
Mattermost bot setup and Clawdbot config	Setting up Mattermost Debugging Mattermost routing

Mattermost (plugin)

Status: supported via plugin (bot token + WebSocket events). Channels, groups, and DMs are supported. Mattermost is a self-hostable team messaging platform; see the official site at mattermost.com for product details and downloads.

Plugin setup

Mattermost is bundled with Clawdbot. Its dependencies are automatically installed on first load when you enable the plugin.

To enable, add mattermost to your plugins allow list:

{
  plugins: {
    allow: ["mattermost"]
  }
}

The onboarding wizard and clawdbot channels add also offer to enable Mattermost.

Alternatively, install explicitly from npm:

clawdbot plugins install @clawdbot/mattermost

Details: Plugins

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 Clawdbot and start the gateway.

Minimal config:

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

Environment variables (default account)

Set these on the gateway host if you prefer env vars:

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

Env vars apply only to the default account (default). Other accounts must use config values.

Chat modes

Mattermost responds to DMs automatically. Channel behavior is controlled by chatmode:

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

Config example:

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

Notes:

• 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:
  • clawdbot pairing list mattermost
  • clawdbot pairing approve mattermost <CODE>
• Public DMs: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].

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

Use these target formats with clawdbot message send or cron/webhooks:

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

Bare IDs are treated as channels.

Multi-account

Mattermost supports 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" }
      }
    }
  }
}

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.