fix(doctor): explain discord streaming opt-in (#52450)

src/commands/doctor-legacy-config.test.ts

@@ -32,6 +32,23 @@ describe("normalizeCompatibilityConfigValues preview streaming aliases", () => {
     ]);
   });
 
+  it("explains why discord preview streaming stays off when legacy config resolves to off", () => {
+    const res = normalizeCompatibilityConfigValues({
+      channels: {
+        discord: {
+          streamMode: "off",
+        },
+      },
+    });
+
+    expect(res.config.channels?.discord?.streaming).toBe("off");
+    expect(res.config.channels?.discord?.streamMode).toBeUndefined();
+    expect(res.changes).toEqual([
+      "Moved channels.discord.streamMode → channels.discord.streaming (off).",
+      'channels.discord.streaming remains off by default to avoid Discord preview-edit rate limits; set channels.discord.streaming="partial" to opt in explicitly.',
+    ]);
+  });
+
   it("normalizes slack boolean streaming aliases to enum and native streaming", () => {
     const res = normalizeCompatibilityConfigValues({
       channels: {

src/commands/doctor-legacy-config.ts

@@ -142,6 +142,11 @@ export function normalizeCompatibilityConfigValues(cfg: OpenClawConfig): {
         `Normalized ${params.pathPrefix}.streaming (${beforeStreaming}) → (${resolved}).`,
       );
     }
+    if (params.pathPrefix.startsWith("channels.discord") && resolved === "off") {
+      changes.push(
+        `${params.pathPrefix}.streaming remains off by default to avoid Discord preview-edit rate limits; set ${params.pathPrefix}.streaming="partial" to opt in explicitly.`,
+      );
+    }
 
     return { entry: updated, changed };
   };

src/config/discord-preview-streaming.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { resolveDiscordPreviewStreamMode } from "./discord-preview-streaming.js";
+
+describe("resolveDiscordPreviewStreamMode", () => {
+  it("defaults to off when unset", () => {
+    expect(resolveDiscordPreviewStreamMode({})).toBe("off");
+  });
+
+  it("preserves explicit off", () => {
+    expect(resolveDiscordPreviewStreamMode({ streaming: "off" })).toBe("off");
+    expect(resolveDiscordPreviewStreamMode({ streamMode: "off" })).toBe("off");
+    expect(resolveDiscordPreviewStreamMode({ streaming: false })).toBe("off");
+  });
+});

src/config/discord-preview-streaming.ts

@@ -104,6 +104,9 @@ export function resolveDiscordPreviewStreamMode(
   if (typeof params.streaming === "boolean") {
     return params.streaming ? "partial" : "off";
   }
+  // Discord preview streaming edits can hit aggressive rate limits, especially
+  // when multiple gateways or multiple bots share the same account/server. Keep
+  // the default off unless the operator opts in explicitly.
   return "off";
 }