Use this file to discover all available pages before exploring further.

Mattermost

Status: bundled 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.

Bundled plugin

note

Mattermost ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.

If you are on an older build or a custom install that excludes Mattermost, install a current npm package when one is published:

```bash} openclaw plugins install @openclaw/mattermost ``` ```bash} openclaw plugins install ./path/to/local/mattermost-plugin ```

If npm reports the OpenClaw-owned package as deprecated, use a current packaged OpenClaw build or the local checkout path until a newer npm package is published.

Details: Plugins

Quick setup

Ensure plugin is available

Current packaged OpenClaw releases already bundle it. Older/custom installs can add it manually with the commands above.

Create a Mattermost bot

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

Copy the base URL

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

Configure OpenClaw and start the gateway

Minimal config:


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

Native slash commands

Native slash commands are opt-in. When enabled, OpenClaw registers

text

oc_*

slash commands via the Mattermost API and receives callback POSTs on the gateway HTTP server.


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

Environment variables (default account)

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

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

note

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

text

MATTERMOST_URL

cannot be set from a workspace

text

.env

; see Workspace

text

.env

files.

Chat modes

Mattermost responds to DMs automatically. Channel behavior is controlled by

text

chatmode

Respond only when @mentioned in channels. Respond to every channel message. Respond when a message starts with a trigger prefix.

Config example:


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

Notes:

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

Threading and sessions

Use

text

channels.mattermost.replyToMode

to control whether channel and group replies stay in the main channel or start a thread under the triggering post.

text
off
(default): only reply in a thread when the inbound post is already in one.
text
first
: for top-level channel/group posts, start a thread under that post and route the conversation to a thread-scoped session.
text
all
: same behavior as
text
first
for Mattermost today.
Direct messages ignore this setting and stay non-threaded.

Config example:


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

Notes:

Thread-scoped sessions use the triggering post id as the thread root.
text
first
and
text
all
are currently equivalent because once Mattermost has a thread root, follow-up chunks and media continue in that same thread.

Access control (DMs)

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

Channels (groups)

Default:
text
channels.mattermost.groupPolicy = "allowlist"
(mention-gated).
Allowlist senders with
text
channels.mattermost.groupAllowFrom
(user IDs recommended).
Per-channel mention overrides live under
text
channels.mattermost.groups.<channelId>.requireMention
or
text
channels.mattermost.groups["*"].requireMention
for a default.
text
@username
matching is mutable and only enabled when
text
channels.mattermost.dangerouslyAllowNameMatching: true
.
Open channels:
text
channels.mattermost.groupPolicy="open"
(mention-gated).
Runtime note: if
text
channels.mattermost
is completely missing, runtime falls back to
text
groupPolicy="allowlist"
for group checks (even if
text
channels.defaults.groupPolicy
is set).

Example:


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

Targets for outbound delivery

Use these target formats with

text

openclaw message send

or cron/webhooks:

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

warning

Bare opaque IDs (like `64ifufp...`) are **ambiguous** in Mattermost (user ID vs channel ID).

OpenClaw resolves them user-first:

If the ID exists as a user (
text
GET /api/v4/users/<id>
succeeds), OpenClaw sends a DM by resolving the direct channel via
text
/api/v4/channels/direct
.
Otherwise the ID is treated as a channel ID.

If you need deterministic behavior, always use the explicit prefixes (

text

user:<id>

text

channel:<id>

DM channel retry

When OpenClaw sends to a Mattermost DM target and needs to resolve the direct channel first, it retries transient direct-channel creation failures by default.

Use

text

channels.mattermost.dmChannelRetry

to tune that behavior globally for the Mattermost plugin, or

text

channels.mattermost.accounts.<id>.dmChannelRetry

for one account.


json5
{
  channels: {
    mattermost: {
      dmChannelRetry: {
        maxRetries: 3,
        initialDelayMs: 1000,
        maxDelayMs: 10000,
        timeoutMs: 30000,
      },
    },
  },
}

Notes:

This applies only to DM channel creation (
text
/api/v4/channels/direct
), not every Mattermost API call.
Retries apply to transient failures such as rate limits, 5xx responses, and network or timeout errors.
4xx client errors other than
text
429
are treated as permanent and are not retried.

Preview streaming

Mattermost streams thinking, tool activity, and partial reply text into a single draft preview post that finalizes in place when the final answer is safe to send. The preview updates on the same post id instead of spamming the channel with per-chunk messages. Media/error finals cancel pending preview edits and use normal delivery instead of flushing a throwaway preview post.

Enable via

text

channels.mattermost.streaming


json5
{
  channels: {
    mattermost: {
      streaming: "partial", // off | partial | block | progress
    },
  },
}

Reactions (message tool)

Use
text
message action=react
with
text
channel=mattermost
.
text
messageId
is the Mattermost post id.
text
emoji
accepts names like
text
thumbsup
or
text
:+1:
(colons are optional).
Set
text
remove=true
(boolean) to remove a reaction.
Reaction add/remove events are forwarded as system events to the routed agent session.

Examples:


text
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true

Config:

text
channels.mattermost.actions.reactions
: enable/disable reaction actions (default true).
Per-account override:
text
channels.mattermost.accounts.<id>.actions.reactions
.

Interactive buttons (message tool)

Send messages with clickable buttons. When a user clicks a button, the agent receives the selection and can respond.

Enable buttons by adding

text

inlineButtons

to the channel capabilities:


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

Use

text

message action=send

with a

text

buttons

parameter. Buttons are a 2D array (rows of buttons):


text
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]

Button fields:

Display label. Value sent back on click (used as the action ID). Button style.

When a user clicks a button:

Buttons replaced with confirmation

All buttons are replaced with a confirmation line (e.g., "✓ **Yes** selected by @user").

Agent receives the selection

The agent receives the selection as an inbound message and responds.

Direct API integration (external scripts)

External scripts and webhooks can post buttons directly via the Mattermost REST API instead of going through the agent's

text

message

tool. Use

text

buildButtonAttachments()

from the plugin when possible; if posting raw JSON, follow these rules:

Payload structure:


json5
{
  channel_id: "<channelId>",
  message: "Choose an option:",
  props: {
    attachments: [
      {
        actions: [
          {
            id: "mybutton01", // alphanumeric only — see below
            type: "button", // required, or clicks are silently ignored
            name: "Approve", // display label
            style: "primary", // optional: "default", "primary", "danger"
            integration: {
              url: "https://gateway.example.com/mattermost/interactions/default",
              context: {
                action_id: "mybutton01", // must match button id (for name lookup)
                action: "approve",
                // ... any custom fields ...
                _token: "<hmac>", // see HMAC section below
              },
            },
          },
        ],
      },
    ],
  },
}

warning

**Critical rules**

Attachments go in
text
props.attachments
, not top-level
text
attachments
(silently ignored).
Every action needs
text
type: "button"
— without it, clicks are swallowed silently.
Every action needs an
text
id
field — Mattermost ignores actions without IDs.
Action
text
id
must be alphanumeric only (
text
[a-zA-Z0-9]
). Hyphens and underscores break Mattermost's server-side action routing (returns 404). Strip them before use.
text
context.action_id
must match the button's
text
id
so the confirmation message shows the button name (e.g., "Approve") instead of a raw ID.
text
context.action_id
is required — the interaction handler returns 400 without it.

HMAC token generation

The gateway verifies button clicks with HMAC-SHA256. External scripts must generate tokens that match the gateway's verification logic:

Derive the secret from the bot token

`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`

Build the context object

Build the context object with all fields **except** `_token`.

Serialize with sorted keys

Serialize with **sorted keys** and **no spaces** (the gateway uses `JSON.stringify` with sorted keys, which produces compact output).

Sign the payload

`HMAC-SHA256(key=secret, data=serializedContext)`

Add the token

Add the resulting hex digest as `_token` in the context.

Python example:


python
import hmac, hashlib, json

secret = hmac.new(
    b"openclaw-mattermost-interactions",
    bot_token.encode(), hashlib.sha256
).hexdigest()

ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

context = {**ctx, "_token": token}

Directory adapter

The Mattermost plugin includes a directory adapter that resolves channel and user names via the Mattermost API. This enables

text

#channel-name

and

text

@username

targets in

text

openclaw message send

and cron/webhook deliveries.

No configuration is needed — the adapter uses the bot token from the account config.

Multi-account

Mattermost supports multiple accounts under

text

channels.mattermost.accounts


json5
{
  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

Channel Routing — session routing for messages
Channels Overview — all supported channels
Groups — group chat behavior and mention gating
Pairing — DM authentication and pairing flow
Security — access model and hardening

OpenClaw Docs

Mattermost

Bundled plugin

note

Quick setup

Ensure plugin is available

Create a Mattermost bot

Copy the base URL

Configure OpenClaw and start the gateway

Native slash commands

Environment variables (default account)

note

Chat modes

Threading and sessions

Access control (DMs)

Channels (groups)

Targets for outbound delivery

warning

DM channel retry

Preview streaming

Reactions (message tool)

Interactive buttons (message tool)

Buttons replaced with confirmation

Agent receives the selection

Direct API integration (external scripts)

warning

Derive the secret from the bot token

Build the context object

Serialize with sorted keys

Sign the payload

Add the token

Directory adapter

Multi-account

Troubleshooting

Related