diff --git a/docs/channels/mattermost.md b/docs/channels/mattermost.md
index e0e6d9f6363..ff732de87b6 100644
--- a/docs/channels/mattermost.md
+++ b/docs/channels/mattermost.md
@@ -82,7 +82,10 @@ Notes:
 - If `callbackUrl` is omitted, OpenClaw derives one from gateway host/port + `callbackPath`.
 - 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).
-- Command callbacks are validated with per-command tokens and fail closed when token checks fail.
+- Command callbacks are validated with the per-command tokens returned by
+  Mattermost when OpenClaw registers `oc_*` commands.
+- Slash callbacks fail closed when registration failed, startup was partial, or
+  the callback token does not match one of the registered commands.
 - Reachability requirement: 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.
@@ -418,6 +421,19 @@ Mattermost supports multiple accounts under `channels.mattermost.accounts`:
 - 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.
+- Native slash commands return `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
+  `http://127.0.0.1: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: the agent may be sending malformed button data. Check that each button has both `text` and `callback_data` fields.
 - Buttons render but clicks do nothing: verify `AllowedUntrustedInternalConnections` in Mattermost server config includes `127.0.0.1 localhost`, and that `EnablePostActionIntegration` is `true` in ServiceSettings.
 - 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.
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 74b149050c0..b766b8e2ce9 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -472,6 +472,10 @@ When Mattermost native commands are enabled:
 
 - `commands.callbackPath` must be a path (for example `/api/channels/mattermost/command`), not a full URL.
 - `commands.callbackUrl` must resolve to the OpenClaw gateway endpoint and be reachable from the Mattermost server.
+- Native slash callbacks are authenticated with the per-command tokens returned
+  by Mattermost during slash command registration. If registration fails or no
+  commands are activated, OpenClaw rejects callbacks with
+  `Unauthorized: invalid command token.`
 - For private/tailnet/internal callback hosts, Mattermost may require
   `ServiceSettings.AllowedUntrustedInternalConnections` to include the callback host/domain.
   Use host/domain values, not full URLs.