Channels: move single-account config into accounts.default (#27334)

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: 50b5771808
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

src/commands/channels.adds-non-default-telegram-account.test.ts

@@ -66,6 +66,96 @@ describe("channels command", () => {
     expect(next.channels?.telegram?.accounts?.alerts?.botToken).toBe("123:abc");
   });
 
+  it("moves single-account telegram config into accounts.default when adding non-default", async () => {
+    configMocks.readConfigFileSnapshot.mockResolvedValue({
+      ...baseConfigSnapshot,
+      config: {
+        channels: {
+          telegram: {
+            enabled: true,
+            botToken: "legacy-token",
+            dmPolicy: "allowlist",
+            allowFrom: ["111"],
+            groupPolicy: "allowlist",
+            streaming: "partial",
+          },
+        },
+      },
+    });
+
+    await channelsAddCommand(
+      { channel: "telegram", account: "alerts", token: "alerts-token" },
+      runtime,
+      { hasFlags: true },
+    );
+
+    const next = configMocks.writeConfigFile.mock.calls[0]?.[0] as {
+      channels?: {
+        telegram?: {
+          botToken?: string;
+          dmPolicy?: string;
+          allowFrom?: string[];
+          groupPolicy?: string;
+          streaming?: string;
+          accounts?: Record<
+            string,
+            {
+              botToken?: string;
+              dmPolicy?: string;
+              allowFrom?: string[];
+              groupPolicy?: string;
+              streaming?: string;
+            }
+          >;
+        };
+      };
+    };
+    expect(next.channels?.telegram?.accounts?.default).toEqual({
+      botToken: "legacy-token",
+      dmPolicy: "allowlist",
+      allowFrom: ["111"],
+      groupPolicy: "allowlist",
+      streaming: "partial",
+    });
+    expect(next.channels?.telegram?.botToken).toBeUndefined();
+    expect(next.channels?.telegram?.dmPolicy).toBeUndefined();
+    expect(next.channels?.telegram?.allowFrom).toBeUndefined();
+    expect(next.channels?.telegram?.groupPolicy).toBeUndefined();
+    expect(next.channels?.telegram?.streaming).toBeUndefined();
+    expect(next.channels?.telegram?.accounts?.alerts?.botToken).toBe("alerts-token");
+  });
+
+  it("seeds accounts.default for env-only single-account telegram config when adding non-default", async () => {
+    configMocks.readConfigFileSnapshot.mockResolvedValue({
+      ...baseConfigSnapshot,
+      config: {
+        channels: {
+          telegram: {
+            enabled: true,
+          },
+        },
+      },
+    });
+
+    await channelsAddCommand(
+      { channel: "telegram", account: "alerts", token: "alerts-token" },
+      runtime,
+      { hasFlags: true },
+    );
+
+    const next = configMocks.writeConfigFile.mock.calls[0]?.[0] as {
+      channels?: {
+        telegram?: {
+          enabled?: boolean;
+          accounts?: Record<string, { botToken?: string }>;
+        };
+      };
+    };
+    expect(next.channels?.telegram?.enabled).toBe(true);
+    expect(next.channels?.telegram?.accounts?.default).toEqual({});
+    expect(next.channels?.telegram?.accounts?.alerts?.botToken).toBe("alerts-token");
+  });
+
   it("adds a default slack account with tokens", async () => {
     configMocks.readConfigFileSnapshot.mockResolvedValue({ ...baseConfigSnapshot });
     await channelsAddCommand(

src/commands/channels/add.ts

@@ -1,6 +1,7 @@
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { listChannelPluginCatalogEntries } from "../../channels/plugins/catalog.js";
 import { getChannelPlugin, normalizeChannelId } from "../../channels/plugins/index.js";
+import { moveSingleAccountChannelSectionToDefaultAccount } from "../../channels/plugins/setup-helpers.js";
 import type { ChannelId, ChannelSetupInput } from "../../channels/plugins/types.js";
 import { writeConfigFile, type OpenClawConfig } from "../../config/config.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../routing/session-key.js";
@@ -283,6 +284,13 @@ export async function channelsAddCommand(
       ? resolveTelegramAccount({ cfg: nextConfig, accountId }).token.trim()
       : "";
 
+  if (accountId !== DEFAULT_ACCOUNT_ID) {
+    nextConfig = moveSingleAccountChannelSectionToDefaultAccount({
+      cfg: nextConfig,
+      channelKey: channel,
+    });
+  }
+
   nextConfig = applyChannelAccountConfig({
     cfg: nextConfig,
     channel,

src/commands/doctor-config-flow.missing-default-account-bindings.integration.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from "vitest";
+import { withEnvAsync } from "../test-utils/env.js";
+import { runDoctorConfigWithInput } from "./doctor-config-flow.test-utils.js";
+
+const { noteSpy } = vi.hoisted(() => ({
+  noteSpy: vi.fn(),
+}));
+
+vi.mock("../terminal/note.js", () => ({
+  note: noteSpy,
+}));
+
+vi.mock("./doctor-legacy-config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./doctor-legacy-config.js")>();
+  return {
+    ...actual,
+    normalizeLegacyConfigValues: (cfg: unknown) => ({
+      config: cfg,
+      changes: [],
+    }),
+  };
+});
+
+import { loadAndMaybeMigrateDoctorConfig } from "./doctor-config-flow.js";
+
+describe("doctor missing default account binding warning", () => {
+  it("emits a doctor warning when named accounts have no valid account-scoped bindings", async () => {
+    await withEnvAsync(
+      {
+        TELEGRAM_BOT_TOKEN: undefined,
+        TELEGRAM_BOT_TOKEN_FILE: undefined,
+      },
+      async () => {
+        await runDoctorConfigWithInput({
+          config: {
+            channels: {
+              telegram: {
+                accounts: {
+                  alerts: {},
+                  work: {},
+                },
+              },
+            },
+            bindings: [{ agentId: "ops", match: { channel: "telegram" } }],
+          },
+          run: loadAndMaybeMigrateDoctorConfig,
+        });
+      },
+    );
+
+    expect(noteSpy).toHaveBeenCalledWith(
+      expect.stringContaining("channels.telegram: accounts.default is missing"),
+      "Doctor warnings",
+    );
+  });
+});

src/commands/doctor-config-flow.missing-default-account-bindings.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import { collectMissingDefaultAccountBindingWarnings } from "./doctor-config-flow.js";
+
+describe("collectMissingDefaultAccountBindingWarnings", () => {
+  it("warns when named accounts exist without default and no valid binding exists", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        telegram: {
+          accounts: {
+            alerts: { botToken: "a" },
+            work: { botToken: "w" },
+          },
+        },
+      },
+      bindings: [{ agentId: "ops", match: { channel: "telegram" } }],
+    };
+
+    const warnings = collectMissingDefaultAccountBindingWarnings(cfg);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("channels.telegram");
+    expect(warnings[0]).toContain("alerts, work");
+  });
+
+  it("does not warn when an explicit account binding exists", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        telegram: {
+          accounts: {
+            alerts: { botToken: "a" },
+          },
+        },
+      },
+      bindings: [{ agentId: "ops", match: { channel: "telegram", accountId: "alerts" } }],
+    };
+
+    expect(collectMissingDefaultAccountBindingWarnings(cfg)).toEqual([]);
+  });
+
+  it("warns when bindings cover only a subset of configured accounts", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        telegram: {
+          accounts: {
+            alerts: { botToken: "a" },
+            work: { botToken: "w" },
+          },
+        },
+      },
+      bindings: [{ agentId: "ops", match: { channel: "telegram", accountId: "alerts" } }],
+    };
+
+    const warnings = collectMissingDefaultAccountBindingWarnings(cfg);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("subset");
+    expect(warnings[0]).toContain("Uncovered accounts: work");
+  });
+
+  it("does not warn when wildcard account binding exists", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        telegram: {
+          accounts: {
+            alerts: { botToken: "a" },
+          },
+        },
+      },
+      bindings: [{ agentId: "ops", match: { channel: "telegram", accountId: "*" } }],
+    };
+
+    expect(collectMissingDefaultAccountBindingWarnings(cfg)).toEqual([]);
+  });
+
+  it("does not warn when default account is present", () => {
+    const cfg: OpenClawConfig = {
+      channels: {
+        telegram: {
+          accounts: {
+            default: { botToken: "d" },
+            alerts: { botToken: "a" },
+          },
+        },
+      },
+      bindings: [{ agentId: "ops", match: { channel: "telegram" } }],
+    };
+
+    expect(collectMissingDefaultAccountBindingWarnings(cfg)).toEqual([]);
+  });
+});

src/commands/doctor-config-flow.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { ZodIssue } from "zod";
+import { normalizeChatChannelId } from "../channels/registry.js";
 import {
   isNumericTelegramUserId,
   normalizeTelegramAllowFromEntry,
@@ -27,6 +28,7 @@ import {
   isTrustedSafeBinPath,
   normalizeTrustedSafeBinDirs,
 } from "../infra/exec-safe-bin-trust.js";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
 import {
   isDiscordMutableAllowEntry,
   isGoogleChatMutableAllowEntry,
@@ -207,6 +209,103 @@ function asObjectRecord(value: unknown): Record<string, unknown> | null {
   return value as Record<string, unknown>;
 }
 
+function normalizeBindingChannelKey(raw?: string | null): string {
+  const normalized = normalizeChatChannelId(raw);
+  if (normalized) {
+    return normalized;
+  }
+  return (raw ?? "").trim().toLowerCase();
+}
+
+export function collectMissingDefaultAccountBindingWarnings(cfg: OpenClawConfig): string[] {
+  const channels = asObjectRecord(cfg.channels);
+  if (!channels) {
+    return [];
+  }
+
+  const bindings = Array.isArray(cfg.bindings) ? cfg.bindings : [];
+  const warnings: string[] = [];
+
+  for (const [channelKey, rawChannel] of Object.entries(channels)) {
+    const channel = asObjectRecord(rawChannel);
+    if (!channel) {
+      continue;
+    }
+    const accounts = asObjectRecord(channel.accounts);
+    if (!accounts) {
+      continue;
+    }
+
+    const normalizedAccountIds = Array.from(
+      new Set(
+        Object.keys(accounts)
+          .map((accountId) => normalizeAccountId(accountId))
+          .filter(Boolean),
+      ),
+    );
+    if (normalizedAccountIds.length === 0 || normalizedAccountIds.includes(DEFAULT_ACCOUNT_ID)) {
+      continue;
+    }
+    const accountIdSet = new Set(normalizedAccountIds);
+    const channelPattern = normalizeBindingChannelKey(channelKey);
+
+    let hasWildcardBinding = false;
+    const coveredAccountIds = new Set<string>();
+    for (const binding of bindings) {
+      const bindingRecord = asObjectRecord(binding);
+      if (!bindingRecord) {
+        continue;
+      }
+      const match = asObjectRecord(bindingRecord.match);
+      if (!match) {
+        continue;
+      }
+
+      const matchChannel =
+        typeof match.channel === "string" ? normalizeBindingChannelKey(match.channel) : "";
+      if (!matchChannel || matchChannel !== channelPattern) {
+        continue;
+      }
+
+      const rawAccountId = typeof match.accountId === "string" ? match.accountId.trim() : "";
+      if (!rawAccountId) {
+        continue;
+      }
+      if (rawAccountId === "*") {
+        hasWildcardBinding = true;
+        continue;
+      }
+      const normalizedBindingAccountId = normalizeAccountId(rawAccountId);
+      if (accountIdSet.has(normalizedBindingAccountId)) {
+        coveredAccountIds.add(normalizedBindingAccountId);
+      }
+    }
+
+    if (hasWildcardBinding) {
+      continue;
+    }
+
+    const uncoveredAccountIds = normalizedAccountIds.filter(
+      (accountId) => !coveredAccountIds.has(accountId),
+    );
+    if (uncoveredAccountIds.length === 0) {
+      continue;
+    }
+    if (coveredAccountIds.size > 0) {
+      warnings.push(
+        `- channels.${channelKey}: accounts.default is missing and account bindings only cover a subset of configured accounts. Uncovered accounts: ${uncoveredAccountIds.join(", ")}. Add bindings[].match.accountId for uncovered accounts (or "*"), or add channels.${channelKey}.accounts.default.`,
+      );
+      continue;
+    }
+
+    warnings.push(
+      `- channels.${channelKey}: accounts.default is missing and no valid account-scoped binding exists for configured accounts (${normalizedAccountIds.join(", ")}). Channel-only bindings (no accountId) match only default. Add bindings[].match.accountId for one of these accounts (or "*"), or add channels.${channelKey}.accounts.default.`,
+    );
+  }
+
+  return warnings;
+}
+
 function collectTelegramAccountScopes(
   cfg: OpenClawConfig,
 ): Array<{ prefix: string; account: Record<string, unknown> }> {
@@ -1421,6 +1520,12 @@ export async function loadAndMaybeMigrateDoctorConfig(params: {
     }
   }
 
+  const missingDefaultAccountBindingWarnings =
+    collectMissingDefaultAccountBindingWarnings(candidate);
+  if (missingDefaultAccountBindingWarnings.length > 0) {
+    note(missingDefaultAccountBindingWarnings.join("\n"), "Doctor warnings");
+  }
+
   if (shouldRepair) {
     const repair = await maybeRepairTelegramAllowFromUsernames(candidate);
     if (repair.changes.length > 0) {

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

@@ -164,10 +164,12 @@ describe("normalizeLegacyConfigValues", () => {
     expect(res.config.channels?.discord?.streamMode).toBeUndefined();
     expect(res.config.channels?.discord?.accounts?.work?.streaming).toBe("off");
     expect(res.config.channels?.discord?.accounts?.work?.streamMode).toBeUndefined();
-    expect(res.changes).toEqual([
+    expect(res.changes).toContain(
       "Normalized channels.discord.streaming boolean → enum (partial).",
+    );
+    expect(res.changes).toContain(
       "Normalized channels.discord.accounts.work.streaming boolean → enum (off).",
-    ]);
+    );
   });
 
   it("migrates Discord legacy streamMode into streaming enum", () => {
@@ -223,6 +225,44 @@ describe("normalizeLegacyConfigValues", () => {
     ]);
   });
 
+  it("moves missing default account from single-account top-level config when named accounts already exist", () => {
+    const res = normalizeLegacyConfigValues({
+      channels: {
+        telegram: {
+          enabled: true,
+          botToken: "legacy-token",
+          dmPolicy: "allowlist",
+          allowFrom: ["123"],
+          groupPolicy: "allowlist",
+          streaming: "partial",
+          accounts: {
+            alerts: {
+              enabled: true,
+              botToken: "alerts-token",
+            },
+          },
+        },
+      },
+    });
+
+    expect(res.config.channels?.telegram?.accounts?.default).toEqual({
+      botToken: "legacy-token",
+      dmPolicy: "allowlist",
+      allowFrom: ["123"],
+      groupPolicy: "allowlist",
+      streaming: "partial",
+    });
+    expect(res.config.channels?.telegram?.botToken).toBeUndefined();
+    expect(res.config.channels?.telegram?.dmPolicy).toBeUndefined();
+    expect(res.config.channels?.telegram?.allowFrom).toBeUndefined();
+    expect(res.config.channels?.telegram?.groupPolicy).toBeUndefined();
+    expect(res.config.channels?.telegram?.streaming).toBeUndefined();
+    expect(res.config.channels?.telegram?.accounts?.alerts?.botToken).toBe("alerts-token");
+    expect(res.changes).toContain(
+      "Moved channels.telegram single-account top-level values into channels.telegram.accounts.default.",
+    );
+  });
+
   it("migrates browser ssrfPolicy allowPrivateNetwork to dangerouslyAllowPrivateNetwork", () => {
     const res = normalizeLegacyConfigValues({
       browser: {

src/commands/doctor-legacy-config.ts

@@ -1,3 +1,4 @@
+import { shouldMoveSingleAccountChannelKey } from "../channels/plugins/setup-helpers.js";
 import type { OpenClawConfig } from "../config/config.js";
 import {
   resolveDiscordPreviewStreamMode,
@@ -5,6 +6,7 @@ import {
   resolveSlackStreamingMode,
   resolveTelegramPreviewStreamMode,
 } from "../config/discord-preview-streaming.js";
+import { DEFAULT_ACCOUNT_ID } from "../routing/session-key.js";
 
 export function normalizeLegacyConfigValues(cfg: OpenClawConfig): {
   config: OpenClawConfig;
@@ -289,9 +291,80 @@ export function normalizeLegacyConfigValues(cfg: OpenClawConfig): {
     }
   };
 
+  const seedMissingDefaultAccountsFromSingleAccountBase = () => {
+    const channels = next.channels as Record<string, unknown> | undefined;
+    if (!channels) {
+      return;
+    }
+
+    let channelsChanged = false;
+    const nextChannels = { ...channels };
+    for (const [channelId, rawChannel] of Object.entries(channels)) {
+      if (!isRecord(rawChannel)) {
+        continue;
+      }
+      const rawAccounts = rawChannel.accounts;
+      if (!isRecord(rawAccounts)) {
+        continue;
+      }
+      const accountKeys = Object.keys(rawAccounts);
+      if (accountKeys.length === 0) {
+        continue;
+      }
+      const hasDefault = accountKeys.some((key) => key.trim().toLowerCase() === DEFAULT_ACCOUNT_ID);
+      if (hasDefault) {
+        continue;
+      }
+
+      const keysToMove = Object.entries(rawChannel)
+        .filter(
+          ([key, value]) =>
+            key !== "accounts" &&
+            key !== "enabled" &&
+            value !== undefined &&
+            shouldMoveSingleAccountChannelKey({ channelKey: channelId, key }),
+        )
+        .map(([key]) => key);
+      if (keysToMove.length === 0) {
+        continue;
+      }
+
+      const defaultAccount: Record<string, unknown> = {};
+      for (const key of keysToMove) {
+        const value = rawChannel[key];
+        defaultAccount[key] = value && typeof value === "object" ? structuredClone(value) : value;
+      }
+      const nextChannel: Record<string, unknown> = {
+        ...rawChannel,
+      };
+      for (const key of keysToMove) {
+        delete nextChannel[key];
+      }
+      nextChannel.accounts = {
+        ...rawAccounts,
+        [DEFAULT_ACCOUNT_ID]: defaultAccount,
+      };
+
+      nextChannels[channelId] = nextChannel;
+      channelsChanged = true;
+      changes.push(
+        `Moved channels.${channelId} single-account top-level values into channels.${channelId}.accounts.default.`,
+      );
+    }
+
+    if (!channelsChanged) {
+      return;
+    }
+    next = {
+      ...next,
+      channels: nextChannels as OpenClawConfig["channels"],
+    };
+  };
+
   normalizeProvider("telegram");
   normalizeProvider("slack");
   normalizeProvider("discord");
+  seedMissingDefaultAccountsFromSingleAccountBase();
 
   const normalizeBrowserSsrFPolicyAlias = () => {
     const rawBrowser = next.browser;