Interstellar-code
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/channels/mattermost.md‎
Lines changed: 29 additions & 0 deletions b/‎docs/channels/mattermost.md‎
Lines changed: 29 additions & 0 deletions
diff --git a/‎extensions/mattermost/src/config-schema.ts‎
Lines changed: 28 additions & 0 deletions b/‎extensions/mattermost/src/config-schema.ts‎
Lines changed: 28 additions & 0 deletions
@@ -133,6 +133,7 @@ Docs: https://docs.openclaw.ai
 - macOS/launch at login: stop emitting `KeepAlive` for the desktop app launch agent so OpenClaw no longer relaunches immediately after a manual quit while launch at login remains enabled. (#40213) Thanks @stablegenius49.
 - ACP/gateway startup: use direct Telegram and Discord startup/status helpers instead of routing probes through the plugin runtime, and prepend the selected daemon Node bin dir to service PATH so plugin-local installs can still find `npm` and `pnpm`.
 - ACP/configured bindings: reinitialize configured ACP sessions that are stuck in `error` state instead of reusing the failed runtime.
+- Mattermost/DM send: retry transient direct-channel creation failures for DM deliveries, with configurable backoff and per-request timeout. (#42398) Thanks @JonathanJing.
 
 ## 2026.3.13
 
 
@@ -191,6 +191,35 @@ OpenClaw resolves them **user-first**:
 
 If you need deterministic behavior, always use the explicit prefixes (`user:<id>` / `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 `channels.mattermost.dmChannelRetry` to tune that behavior globally for the Mattermost plugin,
+or `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 (`/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 `429` are treated as permanent and are not retried.
+
 ## Reactions (message tool)
 
 - Use `message action=react` with `channel=mattermost`.
 
@@ -9,6 +9,32 @@ import { z } from "zod";
 import { requireChannelOpenAllowFrom } from "../../shared/config-schema-helpers.js";
 import { buildSecretInputSchema } from "./secret-input.js";
 
+const DmChannelRetrySchema = z
+  .object({
+    /** Maximum number of retry attempts for DM channel creation (default: 3) */
+    maxRetries: z.number().int().min(0).max(10).optional(),
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelayMs: z.number().int().min(100).max(60000).optional(),
+    /** Maximum delay in milliseconds between retries (default: 10000) */
+    maxDelayMs: z.number().int().min(1000).max(60000).optional(),
+    /** Timeout for each individual DM channel creation request in milliseconds (default: 30000) */
+    timeoutMs: z.number().int().min(5000).max(120000).optional(),
+  })
+  .strict()
+  .refine(
+    (data) => {
+      if (data.initialDelayMs !== undefined && data.maxDelayMs !== undefined) {
+        return data.initialDelayMs <= data.maxDelayMs;
+      }
+      return true;
+    },
+    {
+      message: "initialDelayMs must be less than or equal to maxDelayMs",
+      path: ["initialDelayMs"],
+    },
+  )
+  .optional();
+
 const MattermostSlashCommandsSchema = z
   .object({
     /** Enable native slash commands. "auto" resolves to false (opt-in). */
@@ -58,6 +84,8 @@ const MattermostAccountSchemaBase = z
         allowedSourceIps: z.array(z.string()).optional(),
       })
       .optional(),
+    /** Retry configuration for DM channel creation */
+    dmChannelRetry: DmChannelRetrySchema,
   })
   .strict();