diff --git a/docs/channels/mattermost.md b/docs/channels/mattermost.md
index 9ee21ba5597..d5cd044a707 100644
--- a/docs/channels/mattermost.md
+++ b/docs/channels/mattermost.md
@@ -83,6 +83,16 @@ Notes:
 - 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.
+- 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.
+  - A quick check is `curl https://<gateway-host>/api/channels/mattermost/command`; a GET should return `405 Method Not Allowed` from OpenClaw, not `404`.
+- Mattermost egress allowlist requirement:
+  - 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`
 
 ## Environment variables (default account)
 
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index b6ab61fb2d5..ca0a17f9542 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -459,6 +459,13 @@ Mattermost ships as a plugin: `openclaw plugins install @openclaw/mattermost`.
 
 Chat modes: `oncall` (respond on @-mention, default), `onmessage` (every message), `onchar` (messages starting with trigger prefix).
 
+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.
+- For private/tailnet/internal callback hosts, Mattermost may require
+  `ServiceSettings.AllowedUntrustedInternalConnections` to include the callback host/domain.
+  Use host/domain values, not full URLs.
 - `channels.mattermost.configWrites`: allow or deny Mattermost-initiated config writes.
 - `channels.mattermost.requireMention`: require `@mention` before replying in channels.
 - Optional `channels.mattermost.defaultAccount` overrides default account selection when it matches a configured account id.