Mattermost

• native and nativeSkills default to "auto", which resolves to disabled for Mattermost. Set them to true explicitly.
• callbackPath defaults to /api/channels/mattermost/command.
• If callbackUrl is omitted, OpenClaw derives http://<gateway.customBindHost or localhost>:<gateway.port, default 18789><callbackPath>. Wildcard bind hosts (0.0.0.0, ::) fall back to localhost.
• For multi-account setups, commands can be set at the top level or under channels.mattermost.accounts.<id>.commands (account values override top-level fields).
• Existing slash commands with the same trigger created by other integrations are left untouched (registration skips them); commands the bot created are updated or recreated when the callback URL drifts.
• Command callbacks are validated with the per-command tokens returned by Mattermost when OpenClaw registers oc_* commands.
• OpenClaw refreshes current Mattermost command registration before accepting each callback, so stale tokens from deleted or regenerated slash commands stop being accepted without a gateway restart.
• Callback validation fails closed if the Mattermost API cannot confirm the command is still current; failed validations are cached briefly, concurrent lookups are coalesced, and fresh lookup starts are rate-limited per command to bound replay pressure.
• Slash callbacks fail closed when registration failed, startup was partial, or the callback token does not match the resolved command's registered token (a token valid for one command cannot reach upstream validation for a different command).
• Accepted callbacks are acknowledged with an ephemeral "Processing..." reply; the real answer arrives as a normal message.

The callback endpoint must be reachable from the Mattermost server.

• Do not set callbackUrl to localhost unless Mattermost runs on the same host/network namespace as OpenClaw.
• Do not set callbackUrl to your Mattermost base URL unless that URL reverse-proxies /api/channels/mattermost/command to OpenClaw.
• A quick check is curl https://<gateway-host>/api/channels/mattermost/command; a GET should return 405 Method Not Allowed from OpenClaw, not 404.

If your callback targets private/tailnet/internal addresses, set Mattermost ServiceSettings.AllowedUntrustedInternalConnections to include the callback host/domain.

Use host/domain entries, not full URLs.

• Good: gateway.tailnet-name.ts.net
• Bad: https://gateway.tailnet-name.ts.net

• partial (default): one preview post that is edited as the reply grows, then finalized with the complete answer.
• block rotates the preview between completed text and tool-activity blocks, so each block stays visible as its own post instead of being overwritten in place. Parallel and consecutive tool updates share the current tool-activity post.
• progress shows a status preview while generating and only posts the final answer at completion.
• off disables preview streaming. With streaming.block.enabled: true, completed assistant blocks are still delivered as normal block replies (separate posts) rather than a single coalesced final post.

• If the stream cannot be finalized in place (for example the post was deleted mid-stream), OpenClaw falls back to sending a fresh final post so the reply is never lost.
• Thinking-only payloads are suppressed from channel posts, including text that arrives as a > Thinking blockquote. Set /reasoning on to see thinking in other surfaces; the Mattermost final post keeps the answer only.
• See Streaming for the channel-mapping matrix.

• Button callbacks use HMAC-SHA256 verification (automatic, no config needed).
• The whole attachment block is replaced on click, so all buttons are removed together - partial removal is not possible.
• Action IDs containing hyphens or underscores are sanitized automatically (Mattermost routing limitation).
• Clicks whose action_id does not match an action on the original post are rejected with 403 ("Unknown action").

• channels.mattermost.capabilities: array of capability strings. Add "inlineButtons" to enable the buttons tool description in the agent system prompt.
• channels.mattermost.interactions.callbackBaseUrl: optional external base URL for button callbacks (for example https://gateway.example.com). Use this when Mattermost cannot reach the gateway at its bind host directly.
• In multi-account setups, you can also set the same field under channels.mattermost.accounts.<id>.interactions.callbackBaseUrl.
• If interactions.callbackBaseUrl is omitted, OpenClaw derives the callback URL from gateway.customBindHost + gateway.port (default 18789), then falls back to http://localhost:<port>. The callback path is /mattermost/interactions/<accountId>.
• Reachability rule: the button callback URL must be reachable from the Mattermost server. localhost only works when Mattermost and OpenClaw run on the same host/network namespace.
• channels.mattermost.interactions.allowedSourceIps: source-IP allowlist for button callbacks. Without it, only loopback sources (127.0.0.1, ::1) are accepted, so a remote Mattermost server must be allowlisted here or its clicks are rejected with 403. Behind a reverse proxy, also set gateway.trustedProxies so the real client IP is derived from forwarded headers.
• If your callback target is private/tailnet/internal, add its host/domain to Mattermost ServiceSettings.AllowedUntrustedInternalConnections.

• Python's json.dumps adds spaces by default ({"key": "val"}). Use separators=(",", ":") to match JavaScript's compact output ({"key":"val"}).
• Always sign all context fields (minus _token). The gateway strips _token then signs everything remaining. Signing a subset causes silent verification failure.
• Use sort_keys=True - the gateway sorts keys before signing, and Mattermost may reorder context fields when storing the payload.
• Derive the secret from the bot token (deterministic), not random bytes. The secret must be the same across the process that creates buttons and the gateway that verifies.

Ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set chatmode: "onmessage".

• Check the bot token, base URL, and whether the account is enabled.
• Multi-account issues: env vars only apply to the default account.
• Private/LAN Mattermost hosts need network.dangerouslyAllowPrivateNetwork: true (the SSRF guard blocks private IPs by default).

• Unauthorized: invalid command token.: OpenClaw did not accept the callback token. Typical causes:
  • slash command registration failed or only partially completed at startup
  • the callback is hitting the wrong gateway/account
  • Mattermost still has old commands pointing at a previous callback target
  • the gateway restarted without reactivating slash commands
• If native slash commands stop working, check logs for mattermost: failed to register slash commands or mattermost: native slash commands enabled but no commands could be registered.
• If callbackUrl is omitted and logs warn that the callback resolved to a loopback URL like http://localhost:18789/..., that URL is probably only reachable when Mattermost runs on the same host/network namespace as OpenClaw. Set an explicit externally reachable commands.callbackUrl instead.

• Buttons appear as white boxes or not at all: the button data is malformed. Each presentation button needs a label and a value (buttons missing either are dropped).
• Buttons render but clicks do nothing: verify the gateway is reachable from the Mattermost server, the Mattermost server IP is included in channels.mattermost.interactions.allowedSourceIps (only loopback is accepted without it), and ServiceSettings.AllowedUntrustedInternalConnections includes the callback host for private targets.
• Buttons return 404 on click: the button id likely contains hyphens or underscores. Mattermost's action router breaks on non-alphanumeric IDs. Use [a-zA-Z0-9] only.
• Gateway logs rejected callback source: the click came from an IP outside interactions.allowedSourceIps. Allowlist the Mattermost server or your ingress, and set gateway.trustedProxies behind a reverse proxy.
• Gateway logs invalid _token: HMAC mismatch. Check that you sign all context fields (not a subset), use sorted keys, and use compact JSON (no spaces). See the HMAC section above.
• Gateway logs missing _token in context: the _token field is not in the button's context. Ensure it is included when building the integration payload.
• Gateway rejects the click with Unknown action: context.action_id does not match any action id on the post. Set both to the same sanitized value.
• Agent does not offer buttons: add capabilities: ["inlineButtons"] to the Mattermost channel config.