openclaw-deploy/how-to/mattermost-openclaw.md

OpenClaw + Mattermost notes

===========================

Current working state

• OpenClaw gateway is reachable on port 18789
• Mattermost channel connects as @claw
• Native slash commands are working
• Slash commands were registered successfully for 1 team
• Inline buttons are enabled in channel config
• Button callback handling is working

What was wrong

1. A manual Mattermost plugin install was present even though Mattermost is bundled in current OpenClaw.
2. The bot account was not a member of any Mattermost team.
3. Because the bot had zero teams, OpenClaw had nowhere to register native slash commands.

Observed failure mode

• Logs showed:
  • mattermost: registered slash command callback at /api/channels/mattermost/command
  • mattermost: connected as @claw
  • mattermost: native slash commands enabled but no commands could be registered; keeping slash callbacks inactive

Actual root cause

• Mattermost API check showed the bot user belonged to zero teams.
• Native slash command registration is team-scoped, so no team membership means no commands can be created.

What was cleaned up

• Moved manual override plugin out of the active extensions path:
  • /home/user/.openclaw/extensions/mattermost
  • -> /home/user/.openclaw/extensions/mattermost.disabled-20260410-230312
• Removed stale plugin install metadata from /home/user/.openclaw/openclaw.json:
  • plugins.installs.mattermost
• Removed stale disabled bundled plugin config warning:
  • plugins.entries.huggingface

Mattermost config in use

• baseUrl: https://mm.an2.io
• commands.native: true
• commands.nativeSkills: true
• callbackPath: /api/channels/mattermost/command
• callbackUrl: http://159.69.76.190:18789/api/channels/mattermost/command
• interactions.allowedSourceIps: ["172.20.0.3", "172.20.0.0/16", "127.0.0.1", "::1"]

What fixed it

• Added the @claw bot to a Mattermost team
• After reconnect/restart, OpenClaw successfully registered slash commands

Successful log indicators

• mattermost: connected as @claw
• mattermost: registered command /oc_status
• mattermost: registered command /oc_model
• mattermost: registered command /oc_models
• mattermost: slash commands activated for account default (20 commands)
• mattermost: slash commands registered (20 commands across 1 teams, callback=http://159.69.76.190:18789/api/channels/mattermost/command)

Important reminder

• The bot must belong to at least one team for native slash command registration to work.
• The bot should also be added to the channels where you want it to interact.
• If native slash commands fail again, first check team membership before debugging callback URLs.

Useful checks

• curl -sS -H 'Authorization: Bearer <BOT_TOKEN>' https://mm.an2.io/api/v4/users/me
• curl -sS -H 'Authorization: Bearer <BOT_TOKEN>' https://mm.an2.io/api/v4/users/<BOT_USER_ID>/teams
• grep -Ei 'mattermost|slash|callback' /tmp/openclaw-gateway-run.log

If slash commands break again

1. Confirm the bot is still in a team
2. Confirm callbackUrl is reachable from the Mattermost server
3. Check for old leftover manually installed overrides in ~/.openclaw/extensions/
4. Restart gateway and re-read Mattermost startup logs

Button callback note

• Native slash commands now work.
• Button callback test initially failed with: mattermost interaction: rejected callback source remote=172.20.0.3
• Updated channels.mattermost.interactions.allowedSourceIps to include:
  • 172.20.0.3
  • 172.20.0.0/16
  • 127.0.0.1
  • ::1
• After the allowlist update, button callbacks worked end-to-end.

Elevated exec from Mattermost

• Added tools.elevated.enabled = true
• Added tools.elevated.allowFrom.mattermost = ["63rzn4hbijnrmjbomxxugntg9h"]
• This allows elevated exec only from the specified Mattermost source/account instead of opening it broadly.
• Gateway restart is required for this change to take full effect.

Provider routing note for elevated exec

• Elevated exec checks for this session path were evaluated under provider=webchat, not provider=mattermost.
• Because of that, tools.elevated.allowFrom needed both:
  • mattermost: ["63rzn4hbijnrmjbomxxugntg9h"]
  • webchat: ["63rzn4hbijnrmjbomxxugntg9h"]
• Gateway restart is required after changing these allowFrom rules.

Elevated exec verification

• After adding both provider allowlists and restarting the gateway, elevated exec from the Mattermost session path worked.
• Confirmed in-session test: sudo -n true -> SUDO_OK
• This verified that elevated exec was allowed for the effective provider path used by that session.