From 2ead75ea0e5aa259cd055871d587d9e542b2051f Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Sat, 21 Mar 2026 08:23:42 -0700
Subject: [PATCH] fix(doctor): add telegram first-run guidance

---
 src/commands/doctor-config-flow.test.ts | 22 ++++++++++++++++++++--
 src/commands/doctor-config-flow.ts      | 14 ++++++++++++--
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/src/commands/doctor-config-flow.test.ts b/src/commands/doctor-config-flow.test.ts
index 046744d0ec5..9952705d312 100644
--- a/src/commands/doctor-config-flow.test.ts
+++ b/src/commands/doctor-config-flow.test.ts
@@ -109,7 +109,7 @@ describe("doctor config flow", () => {
     ).toBe(false);
   });
 
-  it("does not warn for fresh Telegram baseline without configured groups", async () => {
+  it("shows first-time Telegram guidance without the old groupAllowFrom warning", async () => {
     const doctorWarnings = await collectDoctorWarnings({
       channels: {
         telegram: {
@@ -126,9 +126,17 @@ describe("doctor config flow", () => {
           line.includes("groupAllowFrom"),
       ),
     ).toBe(false);
+    expect(
+      doctorWarnings.some(
+        (line) =>
+          line.includes("channels.telegram: Telegram is in first-time setup mode.") &&
+          line.includes("DMs use pairing mode") &&
+          line.includes("channels.telegram.groups"),
+      ),
+    ).toBe(true);
   });
 
-  it("does not warn for account-scoped Telegram baseline without configured groups", async () => {
+  it("shows account-scoped first-time Telegram guidance without the old groupAllowFrom warning", async () => {
     const doctorWarnings = await collectDoctorWarnings({
       channels: {
         telegram: {
@@ -149,6 +157,16 @@ describe("doctor config flow", () => {
           line.includes("groupAllowFrom"),
       ),
     ).toBe(false);
+    expect(
+      doctorWarnings.some(
+        (line) =>
+          line.includes(
+            "channels.telegram.accounts.default: Telegram is in first-time setup mode.",
+          ) &&
+          line.includes("DMs use pairing mode") &&
+          line.includes("channels.telegram.accounts.default.groups"),
+      ),
+    ).toBe(true);
   });
 
   it("warns on mutable Zalouser group entries when dangerous name matching is disabled", async () => {
diff --git a/src/commands/doctor-config-flow.ts b/src/commands/doctor-config-flow.ts
index d4ba2afb184..3080fa42dcd 100644
--- a/src/commands/doctor-config-flow.ts
+++ b/src/commands/doctor-config-flow.ts
@@ -1383,8 +1383,18 @@ function detectEmptyAllowlistPolicy(cfg: OpenClawConfig): string[] {
 
     if (groupPolicy === "allowlist" && usesSenderBasedGroupAllowlist(channelName)) {
       if (channelName === "telegram" && !hasConfiguredGroups(account, parent)) {
-        // Fresh Telegram installs default to fail-closed group access until the
-        // operator explicitly configures allowed groups or sender filters.
+        const effectiveDmPolicy = dmPolicy ?? "pairing";
+        const dmSetupLine =
+          effectiveDmPolicy === "pairing"
+            ? `DMs use pairing mode, so new senders must start a chat and be approved before regular messages are accepted.`
+            : effectiveDmPolicy === "allowlist"
+              ? `DMs use allowlist mode, so only sender IDs in ${prefix}.allowFrom are accepted.`
+              : effectiveDmPolicy === "open"
+                ? `DMs are open.`
+                : `DMs are disabled.`;
+        warnings.push(
+          `- ${prefix}: Telegram is in first-time setup mode. ${dmSetupLine} Group messages stay blocked until you add allowed chats under ${prefix}.groups (and optional sender IDs under ${prefix}.groupAllowFrom), or set ${prefix}.groupPolicy to "open" if you want broad group access.`,
+        );
         return;
       }
       const rawGroupAllowFrom =