@openclaw/whatsapp 2026.5.1-beta.1

package/outbound-payload-test-api.ts

@@ -0,0 +1 @@
+export { whatsappOutbound } from "./src/outbound-adapter.js";

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@openclaw/whatsapp",
+  "version": "2026.5.1-beta.1",
+  "description": "OpenClaw WhatsApp channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "@whiskeysockets/baileys": "7.0.0-rc.9",
+    "https-proxy-agent": "^9.0.0",
+    "jimp": "^1.6.1",
+    "typebox": "1.1.37",
+    "undici": "8.1.0"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*",
+    "openclaw": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.4.25"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "setupFeatures": {
+      "legacyStateMigrations": true,
+      "legacySessionSurfaces": true
+    },
+    "channel": {
+      "id": "whatsapp",
+      "label": "WhatsApp",
+      "selectionLabel": "WhatsApp (QR link)",
+      "detailLabel": "WhatsApp Web",
+      "docsPath": "/channels/whatsapp",
+      "docsLabel": "whatsapp",
+      "blurb": "works with your own number; recommend a separate phone + eSIM.",
+      "systemImage": "message",
+      "persistedAuthState": {
+        "specifier": "./auth-presence",
+        "exportName": "hasAnyWhatsAppAuth"
+      },
+      "cliAddOptions": [
+        {
+          "flags": "--auth-dir <path>",
+          "description": "WhatsApp auth directory override"
+        }
+      ]
+    },
+    "install": {
+      "npmSpec": "@openclaw/whatsapp",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.25"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.25"
+    },
+    "build": {
+      "openclawVersion": "2026.5.1-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,86 @@
+export {
+  getActiveWebListener,
+  resolveWebAccountId,
+  type ActiveWebListener,
+  type ActiveWebSendOptions,
+} from "./src/active-listener.js";
+export { handleWhatsAppAction, whatsAppActionRuntime } from "./src/action-runtime.js";
+export { createWhatsAppLoginTool } from "./src/agent-tools-login.js";
+export {
+  formatWhatsAppWebAuthStatusState,
+  getWebAuthAgeMs,
+  hasWebCredsSync,
+  logWebSelfId,
+  logoutWeb,
+  pickWebChannel,
+  readCredsJsonRaw,
+  readWebAuthExistsBestEffort,
+  readWebAuthExistsForDecision,
+  readWebAuthSnapshot,
+  readWebAuthSnapshotBestEffort,
+  readWebAuthState,
+  readWebSelfId,
+  readWebSelfIdentity,
+  readWebSelfIdentityForDecision,
+  resolveDefaultWebAuthDir,
+  resolveWebCredsBackupPath,
+  resolveWebCredsPath,
+  restoreCredsFromBackupIfNeeded,
+  WA_WEB_AUTH_DIR,
+  webAuthExists,
+  WHATSAPP_AUTH_UNSTABLE_CODE,
+  WhatsAppAuthUnstableError,
+  type WhatsAppWebAuthState,
+} from "./src/auth-store.js";
+export {
+  DEFAULT_WEB_MEDIA_BYTES,
+  HEARTBEAT_PROMPT,
+  HEARTBEAT_TOKEN,
+  monitorWebChannel,
+  resolveHeartbeatRecipients,
+  runWebHeartbeatOnce,
+  SILENT_REPLY_TOKEN,
+  stripHeartbeatToken,
+  type WebChannelStatus,
+  type WebMonitorTuning,
+} from "./src/auto-reply.js";
+export {
+  extractContactContext,
+  extractLocationData,
+  extractMediaPlaceholder,
+  extractText,
+  monitorWebInbox,
+  resetWebInboundDedupe,
+  type WebInboundMessage,
+  type WebListenerCloseReason,
+} from "./src/inbound.js";
+export { loginWeb } from "./src/login.js";
+export {
+  getDefaultLocalRoots,
+  loadWebMedia,
+  loadWebMediaRaw,
+  LocalMediaAccessError,
+  optimizeImageToJpeg,
+  optimizeImageToPng,
+  type LocalMediaAccessErrorCode,
+  type WebMediaResult,
+} from "./src/media.js";
+export {
+  sendMessageWhatsApp,
+  sendPollWhatsApp,
+  sendReactionWhatsApp,
+  sendTypingWhatsApp,
+} from "./src/send.js";
+export {
+  createWaSocket,
+  formatError,
+  getStatusCode,
+  newConnectionId,
+  waitForCredsSaveQueue,
+  waitForCredsSaveQueueWithTimeout,
+  waitForWaConnection,
+  writeCredsJsonAtomically,
+  type CredsQueueWaitResult,
+} from "./src/session.js";
+export { setWhatsAppRuntime } from "./src/runtime.js";
+export { startWebLoginWithQr, waitForWebLogin } from "./login-qr-runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,4 @@
+// WhatsApp does not expose secret-contract surfaces.
+export const secretTargetRegistryEntries: readonly [] = [];
+
+export function collectRuntimeConfigAssignments(): void {}

package/security-contract-api.ts

@@ -0,0 +1,4 @@
+export {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./src/security-contract.js";

package/setup-entry.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@whiskeysockets/baileys", () => {
+  throw new Error("setup plugin load must not load Baileys");
+});
+
+describe("whatsapp setup entry", () => {
+  it("loads the setup plugin without installing or importing runtime dependencies", async () => {
+    const { default: setupEntry } = await import("./setup-entry.js");
+    const { whatsappSetupPlugin } = await import("./setup-plugin-api.js");
+
+    expect(setupEntry.kind).toBe("bundled-channel-setup-entry");
+    expect(whatsappSetupPlugin.id).toBe("whatsapp");
+  });
+
+  it("loads the delegated setup wizard without importing runtime dependencies", async () => {
+    const { whatsappSetupWizard } = await import("./src/setup-surface.js");
+
+    expect(whatsappSetupWizard.channel).toBe("whatsapp");
+  });
+});

package/setup-entry.ts

@@ -0,0 +1,21 @@
+import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  features: {
+    legacyStateMigrations: true,
+    legacySessionSurfaces: true,
+  },
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "whatsappSetupPlugin",
+  },
+  legacyStateMigrations: {
+    specifier: "./legacy-state-migrations-api.js",
+    exportName: "detectWhatsAppLegacyStateMigrations",
+  },
+  legacySessionSurface: {
+    specifier: "./legacy-session-surface-api.js",
+    exportName: "whatsappLegacySessionSurface",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader WhatsApp channel plugin surface.
+export { whatsappSetupPlugin } from "./src/channel.setup.js";

package/src/account-config.ts

@@ -0,0 +1,77 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  mergeAccountConfig,
+  resolveAccountEntry,
+  resolveMergedAccountConfig,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/account-core";
+import {
+  resolveChannelStreamingBlockEnabled,
+  resolveChannelStreamingChunkMode,
+} from "openclaw/plugin-sdk/channel-streaming";
+import type { WhatsAppAccountConfig } from "./account-types.js";
+
+function resolveWhatsAppDefaultAccountSharedConfig(
+  cfg: OpenClawConfig,
+): Partial<WhatsAppAccountConfig> | undefined {
+  const defaultAccount = resolveAccountEntry(cfg.channels?.whatsapp?.accounts, DEFAULT_ACCOUNT_ID);
+  if (!defaultAccount) {
+    return undefined;
+  }
+  const {
+    enabled: _ignoredEnabled,
+    name: _ignoredName,
+    authDir: _ignoredAuthDir,
+    selfChatMode: _ignoredSelfChatMode,
+    ...sharedDefaults
+  } = defaultAccount;
+  return sharedDefaults;
+}
+
+function _resolveWhatsAppAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+): WhatsAppAccountConfig | undefined {
+  return resolveAccountEntry(cfg.channels?.whatsapp?.accounts, accountId);
+}
+
+function resolveMergedNamedWhatsAppAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+}): WhatsAppAccountConfig {
+  const rootCfg = params.cfg.channels?.whatsapp;
+  const accountConfig = _resolveWhatsAppAccountConfig(params.cfg, params.accountId);
+  return {
+    ...mergeAccountConfig<WhatsAppAccountConfig>({
+      channelConfig: rootCfg as WhatsAppAccountConfig | undefined,
+      accountConfig: undefined,
+      omitKeys: ["defaultAccount"],
+    }),
+    ...resolveWhatsAppDefaultAccountSharedConfig(params.cfg),
+    ...accountConfig,
+  };
+}
+
+export function resolveMergedWhatsAppAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): WhatsAppAccountConfig & { accountId: string } {
+  const rootCfg = params.cfg.channels?.whatsapp;
+  const accountId = params.accountId?.trim() || rootCfg?.defaultAccount || DEFAULT_ACCOUNT_ID;
+  const base = resolveMergedAccountConfig<WhatsAppAccountConfig>({
+    channelConfig: rootCfg as WhatsAppAccountConfig | undefined,
+    accounts: rootCfg?.accounts as Record<string, Partial<WhatsAppAccountConfig>> | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+  });
+  const merged =
+    accountId === DEFAULT_ACCOUNT_ID
+      ? base
+      : resolveMergedNamedWhatsAppAccountConfig({ cfg: params.cfg, accountId });
+  return {
+    accountId,
+    ...merged,
+    chunkMode: resolveChannelStreamingChunkMode(merged) ?? merged.chunkMode,
+    blockStreaming: resolveChannelStreamingBlockEnabled(merged) ?? merged.blockStreaming,
+  };
+}

package/src/account-ids.ts

@@ -0,0 +1,13 @@
+import { createAccountListHelpers } from "openclaw/plugin-sdk/account-core";
+
+const {
+  listConfiguredAccountIds,
+  listAccountIds,
+  resolveDefaultAccountId: resolveDefaultWhatsAppAccountId,
+} = createAccountListHelpers("whatsapp");
+
+export {
+  listConfiguredAccountIds,
+  listAccountIds as listWhatsAppAccountIds,
+  resolveDefaultWhatsAppAccountId,
+};

package/src/account-types.ts

@@ -0,0 +1,5 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+
+export type WhatsAppAccountConfig = NonNullable<
+  NonNullable<NonNullable<OpenClawConfig["channels"]>["whatsapp"]>["accounts"]
+>[string];

package/src/accounts.test.ts

@@ -0,0 +1,182 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveWhatsAppAccount, resolveWhatsAppAuthDir } from "./accounts.js";
+
+describe("resolveWhatsAppAuthDir", () => {
+  const stubCfg = { channels: { whatsapp: { accounts: {} } } } as Parameters<
+    typeof resolveWhatsAppAuthDir
+  >[0]["cfg"];
+
+  it("sanitizes path traversal sequences in accountId", () => {
+    const { authDir } = resolveWhatsAppAuthDir({
+      cfg: stubCfg,
+      accountId: "../../../etc/passwd",
+    });
+    // Sanitized accountId must not escape the whatsapp auth directory.
+    expect(authDir).not.toContain("..");
+    expect(path.basename(authDir)).not.toContain("/");
+  });
+
+  it("sanitizes special characters in accountId", () => {
+    const { authDir } = resolveWhatsAppAuthDir({
+      cfg: stubCfg,
+      accountId: "foo/bar\\baz",
+    });
+    // Sprawdzaj sanityzacje na segmencie accountId, nie na calej sciezce
+    // (Windows uzywa backslash jako separator katalogow).
+    const segment = path.basename(authDir);
+    expect(segment).not.toContain("/");
+    expect(segment).not.toContain("\\");
+  });
+
+  it("returns default directory for empty accountId", () => {
+    const { authDir } = resolveWhatsAppAuthDir({
+      cfg: stubCfg,
+      accountId: "",
+    });
+    expect(authDir).toMatch(/whatsapp[/\\]default$/);
+  });
+
+  it("preserves valid accountId unchanged", () => {
+    const { authDir } = resolveWhatsAppAuthDir({
+      cfg: stubCfg,
+      accountId: "my-account-1",
+    });
+    expect(authDir).toMatch(/whatsapp[/\\]my-account-1$/);
+  });
+
+  it("merges top-level and account-specific config through shared helpers", () => {
+    const resolved = resolveWhatsAppAccount({
+      cfg: {
+        messages: {
+          messagePrefix: "[global]",
+        },
+        channels: {
+          whatsapp: {
+            sendReadReceipts: false,
+            messagePrefix: "[root]",
+            debounceMs: 100,
+            accounts: {
+              work: {
+                debounceMs: 250,
+              },
+            },
+          },
+        },
+      } as Parameters<typeof resolveWhatsAppAccount>[0]["cfg"],
+      accountId: "work",
+    });
+
+    expect(resolved.sendReadReceipts).toBe(false);
+    expect(resolved.messagePrefix).toBe("[root]");
+    expect(resolved.debounceMs).toBe(250);
+  });
+
+  it("inherits shared defaults from accounts.default for named accounts", () => {
+    const resolved = resolveWhatsAppAccount({
+      cfg: {
+        channels: {
+          whatsapp: {
+            accounts: {
+              default: {
+                dmPolicy: "allowlist",
+                allowFrom: ["+15550001111"],
+                groupPolicy: "open",
+                groupAllowFrom: ["+15550002222"],
+                defaultTo: "+15550003333",
+                reactionLevel: "extensive",
+                historyLimit: 42,
+                mediaMaxMb: 12,
+              },
+              work: {
+                authDir: "/tmp/work",
+              },
+            },
+          },
+        },
+      } as Parameters<typeof resolveWhatsAppAccount>[0]["cfg"],
+      accountId: "work",
+    });
+
+    expect(resolved.dmPolicy).toBe("allowlist");
+    expect(resolved.allowFrom).toEqual(["+15550001111"]);
+    expect(resolved.groupPolicy).toBe("open");
+    expect(resolved.groupAllowFrom).toEqual(["+15550002222"]);
+    expect(resolved.defaultTo).toBe("+15550003333");
+    expect(resolved.reactionLevel).toBe("extensive");
+    expect(resolved.historyLimit).toBe(42);
+    expect(resolved.mediaMaxMb).toBe(12);
+  });
+
+  it("prefers account overrides and accounts.default over root defaults", () => {
+    const resolved = resolveWhatsAppAccount({
+      cfg: {
+        channels: {
+          whatsapp: {
+            dmPolicy: "open",
+            allowFrom: ["*"],
+            groupPolicy: "disabled",
+            accounts: {
+              default: {
+                dmPolicy: "allowlist",
+                allowFrom: ["+15550001111"],
+                groupPolicy: "open",
+              },
+              work: {
+                authDir: "/tmp/work",
+                dmPolicy: "pairing",
+              },
+            },
+          },
+        },
+      } as Parameters<typeof resolveWhatsAppAccount>[0]["cfg"],
+      accountId: "work",
+    });
+
+    expect(resolved.dmPolicy).toBe("pairing");
+    expect(resolved.allowFrom).toEqual(["+15550001111"]);
+    expect(resolved.groupPolicy).toBe("open");
+  });
+
+  it("does not inherit default-account authDir for named accounts", () => {
+    const resolved = resolveWhatsAppAccount({
+      cfg: {
+        channels: {
+          whatsapp: {
+            accounts: {
+              default: {
+                authDir: "/tmp/default-auth",
+                name: "Personal",
+              },
+              work: {},
+            },
+          },
+        },
+      } as Parameters<typeof resolveWhatsAppAccount>[0]["cfg"],
+      accountId: "work",
+    });
+
+    expect(resolved.authDir).toMatch(/whatsapp[/\\]work$/);
+    expect(resolved.name).toBeUndefined();
+  });
+
+  it("does not inherit default-account selfChatMode for named accounts", () => {
+    const resolved = resolveWhatsAppAccount({
+      cfg: {
+        channels: {
+          whatsapp: {
+            accounts: {
+              default: {
+                selfChatMode: true,
+              },
+              work: {},
+            },
+          },
+        },
+      } as Parameters<typeof resolveWhatsAppAccount>[0]["cfg"],
+      accountId: "work",
+    });
+
+    expect(resolved.selfChatMode).toBeUndefined();
+  });
+});

package/src/accounts.ts

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  resolveUserPath,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/account-core";
+import type { DmPolicy, GroupPolicy, ReplyToMode } from "openclaw/plugin-sdk/config-types";
+import { resolveOAuthDir } from "openclaw/plugin-sdk/state-paths";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { resolveMergedWhatsAppAccountConfig } from "./account-config.js";
+import {
+  listConfiguredAccountIds,
+  listWhatsAppAccountIds,
+  resolveDefaultWhatsAppAccountId,
+} from "./account-ids.js";
+import type { WhatsAppAccountConfig } from "./account-types.js";
+import { hasWebCredsSync } from "./creds-files.js";
+
+export { listWhatsAppAccountIds, resolveDefaultWhatsAppAccountId } from "./account-ids.js";
+
+export type ResolvedWhatsAppAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  sendReadReceipts: boolean;
+  messagePrefix?: string;
+  defaultTo?: string;
+  authDir: string;
+  isLegacyAuthDir: boolean;
+  selfChatMode?: boolean;
+  allowFrom?: string[];
+  groupAllowFrom?: string[];
+  groupPolicy?: GroupPolicy;
+  dmPolicy?: DmPolicy;
+  historyLimit?: number;
+  textChunkLimit?: number;
+  chunkMode?: "length" | "newline";
+  mediaMaxMb?: number;
+  blockStreaming?: boolean;
+  ackReaction?: WhatsAppAccountConfig["ackReaction"];
+  reactionLevel?: WhatsAppAccountConfig["reactionLevel"];
+  groups?: WhatsAppAccountConfig["groups"];
+  direct?: WhatsAppAccountConfig["direct"];
+  debounceMs?: number;
+  replyToMode?: ReplyToMode;
+};
+
+export const DEFAULT_WHATSAPP_MEDIA_MAX_MB = 50;
+
+export function listWhatsAppAuthDirs(cfg: OpenClawConfig): string[] {
+  const oauthDir = resolveOAuthDir();
+  const whatsappDir = path.join(oauthDir, "whatsapp");
+  const authDirs = new Set<string>([oauthDir, path.join(whatsappDir, DEFAULT_ACCOUNT_ID)]);
+
+  const accountIds = listConfiguredAccountIds(cfg);
+  for (const accountId of accountIds) {
+    authDirs.add(resolveWhatsAppAuthDir({ cfg, accountId }).authDir);
+  }
+
+  try {
+    const entries = fs.readdirSync(whatsappDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      authDirs.add(path.join(whatsappDir, entry.name));
+    }
+  } catch {
+    // ignore missing dirs
+  }
+
+  return Array.from(authDirs);
+}
+
+export function hasAnyWhatsAppAuth(cfg: OpenClawConfig): boolean {
+  return listWhatsAppAuthDirs(cfg).some((authDir) => hasWebCredsSync(authDir));
+}
+
+function resolveDefaultAuthDir(accountId: string): string {
+  return path.join(resolveOAuthDir(), "whatsapp", normalizeAccountId(accountId));
+}
+
+function resolveLegacyAuthDir(): string {
+  // Legacy Baileys creds lived in the same directory as OAuth tokens.
+  return resolveOAuthDir();
+}
+
+function legacyAuthExists(authDir: string): boolean {
+  try {
+    return fs.existsSync(path.join(authDir, "creds.json"));
+  } catch {
+    return false;
+  }
+}
+
+export function resolveWhatsAppAuthDir(params: { cfg: OpenClawConfig; accountId: string }): {
+  authDir: string;
+  isLegacy: boolean;
+} {
+  const accountId = params.accountId.trim() || DEFAULT_ACCOUNT_ID;
+  const account = resolveMergedWhatsAppAccountConfig({ cfg: params.cfg, accountId });
+  const configured = account?.authDir?.trim();
+  if (configured) {
+    return { authDir: resolveUserPath(configured), isLegacy: false };
+  }
+
+  const defaultDir = resolveDefaultAuthDir(accountId);
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const legacyDir = resolveLegacyAuthDir();
+    if (legacyAuthExists(legacyDir) && !legacyAuthExists(defaultDir)) {
+      return { authDir: legacyDir, isLegacy: true };
+    }
+  }
+
+  return { authDir: defaultDir, isLegacy: false };
+}
+
+export function resolveWhatsAppAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedWhatsAppAccount {
+  const merged = resolveMergedWhatsAppAccountConfig({
+    cfg: params.cfg,
+    accountId: params.accountId?.trim() || resolveDefaultWhatsAppAccountId(params.cfg),
+  });
+  const accountId = merged.accountId;
+  const enabled = merged.enabled !== false;
+  const { authDir, isLegacy } = resolveWhatsAppAuthDir({
+    cfg: params.cfg,
+    accountId,
+  });
+  return {
+    accountId,
+    name: normalizeOptionalString(merged.name),
+    enabled,
+    sendReadReceipts: merged.sendReadReceipts ?? true,
+    messagePrefix: merged.messagePrefix ?? params.cfg.messages?.messagePrefix,
+    defaultTo: merged.defaultTo,
+    authDir,
+    isLegacyAuthDir: isLegacy,
+    selfChatMode: merged.selfChatMode,
+    dmPolicy: merged.dmPolicy,
+    allowFrom: merged.allowFrom,
+    groupAllowFrom: merged.groupAllowFrom,
+    groupPolicy: merged.groupPolicy,
+    historyLimit: merged.historyLimit,
+    textChunkLimit: merged.textChunkLimit,
+    chunkMode: merged.chunkMode,
+    mediaMaxMb: merged.mediaMaxMb,
+    blockStreaming: merged.blockStreaming,
+    ackReaction: merged.ackReaction,
+    reactionLevel: merged.reactionLevel,
+    groups: merged.groups,
+    direct: merged.direct,
+    debounceMs: merged.debounceMs,
+    replyToMode: merged.replyToMode,
+  };
+}
+
+export function resolveWhatsAppMediaMaxBytes(
+  account: Pick<ResolvedWhatsAppAccount, "mediaMaxMb">,
+): number {
+  const mediaMaxMb =
+    typeof account.mediaMaxMb === "number" && account.mediaMaxMb > 0
+      ? account.mediaMaxMb
+      : DEFAULT_WHATSAPP_MEDIA_MAX_MB;
+  return mediaMaxMb * 1024 * 1024;
+}
+
+export function listEnabledWhatsAppAccounts(cfg: OpenClawConfig): ResolvedWhatsAppAccount[] {
+  return listWhatsAppAccountIds(cfg)
+    .map((accountId) => resolveWhatsAppAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}