@dingxiang-me/openclaw-wechat 1.4.1 → 1.7.2

package/src/core.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { buildDefaultBotWebhookPath } from "./wecom/account-paths.js";
 
 export const WECOM_TEXT_BYTE_LIMIT = 2000;
 export const INBOUND_DEDUPE_TTL_MS = 5 * 60 * 1000;
@@ -41,17 +42,59 @@ const DEFAULT_COMMAND_ALLOWLIST = Object.freeze([
   "/compact",
 ]);
 const DEFAULT_ALLOW_FROM_REJECT_MESSAGE = "当前账号未授权，请联系管理员。";
+const DEFAULT_EVENT_ENTER_AGENT_WELCOME_TEXT = "你好，我是 AI 助手，直接发消息即可开始对话。";
 const DEFAULT_DELIVERY_FALLBACK_ORDER = Object.freeze([
   "active_stream",
   "response_url",
   "webhook_bot",
   "agent_push",
 ]);
+const DEFAULT_BOT_CARD_MODE = "markdown";
+const BOT_CARD_MODE_SET = new Set(["markdown", "template_card"]);
 const DELIVERY_FALLBACK_LAYER_SET = new Set(DEFAULT_DELIVERY_FALLBACK_ORDER);
 const DYNAMIC_AGENT_MAP_SPLITTER = /[,\n]/;
 const GROUP_CHAT_TRIGGER_MODE_SET = new Set(["direct", "mention", "keyword"]);
+const DM_POLICY_MODE_SET = new Set(["open", "allowlist", "deny"]);
 const DYNAMIC_AGENT_MODE_SET = new Set(["mapping", "deterministic", "hybrid"]);
 const DYNAMIC_AGENT_ID_STRATEGY_SET = new Set(["readable-hash"]);
+const LEGACY_INLINE_ACCOUNT_RESERVED_KEYS = new Set([
+  "name",
+  "enabled",
+  "corpId",
+  "corpSecret",
+  "agentId",
+  "callbackToken",
+  "token",
+  "callbackAesKey",
+  "encodingAesKey",
+  "webhookPath",
+  "outboundProxy",
+  "proxyUrl",
+  "proxy",
+  "webhooks",
+  "allowFrom",
+  "allowFromRejectMessage",
+  "rejectUnauthorizedMessage",
+  "adminUsers",
+  "commandAllowlist",
+  "commandBlockMessage",
+  "commands",
+  "workspaceTemplate",
+  "groupChat",
+  "dynamicAgent",
+  "dynamicAgents",
+  "dm",
+  "debounce",
+  "streaming",
+  "bot",
+  "delivery",
+  "webhookBot",
+  "stream",
+  "observability",
+  "voiceTranscription",
+  "accounts",
+  "agent",
+]);
 
 const inboundMessageDedupe = new Map();
 
@@ -188,6 +231,32 @@ function normalizeAccountIdForEnv(accountId) {
   return normalized || "default";
 }
 
+function resolveLegacyInlineAccountConfig(channelConfig, accountId) {
+  if (!channelConfig || typeof channelConfig !== "object") return null;
+  const normalizedAccountId = normalizeAccountIdForEnv(accountId);
+  for (const [key, value] of Object.entries(channelConfig)) {
+    const normalizedKey = normalizeAccountIdForEnv(key);
+    if (LEGACY_INLINE_ACCOUNT_RESERVED_KEYS.has(normalizedKey)) continue;
+    if (normalizedKey !== normalizedAccountId) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    return value;
+  }
+  return null;
+}
+
+function collectLegacyInlineAccountIds(channelConfig) {
+  if (!channelConfig || typeof channelConfig !== "object") return [];
+  const ids = [];
+  for (const [key, value] of Object.entries(channelConfig)) {
+    const normalizedKey = normalizeAccountIdForEnv(key);
+    if (!normalizedKey) continue;
+    if (LEGACY_INLINE_ACCOUNT_RESERVED_KEYS.has(normalizedKey)) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    ids.push(normalizedKey);
+  }
+  return Array.from(new Set(ids));
+}
+
 function readAllowFromEnv(envVars, processEnv, accountId = "default") {
   const normalizedId = normalizeAccountIdForEnv(accountId);
   const scopedAllowFromKey = normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_ALLOW_FROM`;
@@ -211,6 +280,98 @@ function readAllowFromRejectMessageEnv(envVars, processEnv, accountId = "default
   );
 }
 
+function readDmPolicyModeEnv(envVars, processEnv, accountId = "default") {
+  const normalizedId = normalizeAccountIdForEnv(accountId);
+  const scopedDmPolicyKey = normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_DM_POLICY`;
+  const scopedDmModeKey = normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_DM_MODE`;
+  return pickFirstNonEmptyString(
+    scopedDmPolicyKey ? envVars?.[scopedDmPolicyKey] : undefined,
+    scopedDmPolicyKey ? processEnv?.[scopedDmPolicyKey] : undefined,
+    scopedDmModeKey ? envVars?.[scopedDmModeKey] : undefined,
+    scopedDmModeKey ? processEnv?.[scopedDmModeKey] : undefined,
+    envVars?.WECOM_DM_POLICY,
+    processEnv?.WECOM_DM_POLICY,
+    envVars?.WECOM_DM_MODE,
+    processEnv?.WECOM_DM_MODE,
+  );
+}
+
+function readDmAllowFromEnv(envVars, processEnv, accountId = "default") {
+  const normalizedId = normalizeAccountIdForEnv(accountId);
+  const scopedAllowFromKey = normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_DM_ALLOW_FROM`;
+  const scoped = parseStringList(
+    scopedAllowFromKey ? envVars?.[scopedAllowFromKey] : undefined,
+    scopedAllowFromKey ? processEnv?.[scopedAllowFromKey] : undefined,
+  );
+  if (scoped.length > 0) return scoped;
+  return parseStringList(envVars?.WECOM_DM_ALLOW_FROM, processEnv?.WECOM_DM_ALLOW_FROM);
+}
+
+function readDmRejectMessageEnv(envVars, processEnv, accountId = "default") {
+  const normalizedId = normalizeAccountIdForEnv(accountId);
+  const scopedRejectMessageKey =
+    normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_DM_REJECT_MESSAGE`;
+  return pickFirstNonEmptyString(
+    scopedRejectMessageKey ? envVars?.[scopedRejectMessageKey] : undefined,
+    scopedRejectMessageKey ? processEnv?.[scopedRejectMessageKey] : undefined,
+    envVars?.WECOM_DM_REJECT_MESSAGE,
+    processEnv?.WECOM_DM_REJECT_MESSAGE,
+  );
+}
+
+function readEventEnabledEnv(envVars, processEnv, accountId = "default") {
+  const normalizedId = normalizeAccountIdForEnv(accountId);
+  const scopedEnabledKey = normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_EVENT_ENABLED`;
+  const scopedEventsEnabledKey =
+    normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_EVENTS_ENABLED`;
+  return pickFirstNonEmptyString(
+    scopedEnabledKey ? envVars?.[scopedEnabledKey] : undefined,
+    scopedEnabledKey ? processEnv?.[scopedEnabledKey] : undefined,
+    scopedEventsEnabledKey ? envVars?.[scopedEventsEnabledKey] : undefined,
+    scopedEventsEnabledKey ? processEnv?.[scopedEventsEnabledKey] : undefined,
+    envVars?.WECOM_EVENT_ENABLED,
+    processEnv?.WECOM_EVENT_ENABLED,
+    envVars?.WECOM_EVENTS_ENABLED,
+    processEnv?.WECOM_EVENTS_ENABLED,
+  );
+}
+
+function readEventEnterAgentWelcomeEnabledEnv(envVars, processEnv, accountId = "default") {
+  const normalizedId = normalizeAccountIdForEnv(accountId);
+  const scopedEnabledKey =
+    normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_EVENT_ENTER_AGENT_WELCOME_ENABLED`;
+  const scopedEventsEnabledKey =
+    normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_EVENTS_ENTER_AGENT_WELCOME_ENABLED`;
+  return pickFirstNonEmptyString(
+    scopedEnabledKey ? envVars?.[scopedEnabledKey] : undefined,
+    scopedEnabledKey ? processEnv?.[scopedEnabledKey] : undefined,
+    scopedEventsEnabledKey ? envVars?.[scopedEventsEnabledKey] : undefined,
+    scopedEventsEnabledKey ? processEnv?.[scopedEventsEnabledKey] : undefined,
+    envVars?.WECOM_EVENT_ENTER_AGENT_WELCOME_ENABLED,
+    processEnv?.WECOM_EVENT_ENTER_AGENT_WELCOME_ENABLED,
+    envVars?.WECOM_EVENTS_ENTER_AGENT_WELCOME_ENABLED,
+    processEnv?.WECOM_EVENTS_ENTER_AGENT_WELCOME_ENABLED,
+  );
+}
+
+function readEventEnterAgentWelcomeTextEnv(envVars, processEnv, accountId = "default") {
+  const normalizedId = normalizeAccountIdForEnv(accountId);
+  const scopedTextKey =
+    normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_EVENT_ENTER_AGENT_WELCOME_TEXT`;
+  const scopedEventsTextKey =
+    normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_EVENTS_ENTER_AGENT_WELCOME_TEXT`;
+  return pickFirstNonEmptyString(
+    scopedTextKey ? envVars?.[scopedTextKey] : undefined,
+    scopedTextKey ? processEnv?.[scopedTextKey] : undefined,
+    scopedEventsTextKey ? envVars?.[scopedEventsTextKey] : undefined,
+    scopedEventsTextKey ? processEnv?.[scopedEventsTextKey] : undefined,
+    envVars?.WECOM_EVENT_ENTER_AGENT_WELCOME_TEXT,
+    processEnv?.WECOM_EVENT_ENTER_AGENT_WELCOME_TEXT,
+    envVars?.WECOM_EVENTS_ENTER_AGENT_WELCOME_TEXT,
+    processEnv?.WECOM_EVENTS_ENTER_AGENT_WELCOME_TEXT,
+  );
+}
+
 function readProxyEnv(envVars, processEnv, accountId = "default") {
   const normalizedId = normalizeAccountIdForEnv(accountId);
   const scopedProxyKey = normalizedId === "default" ? null : `WECOM_${normalizedId.toUpperCase()}_PROXY`;
@@ -389,6 +550,27 @@ function uniqueDeliveryFallbackOrder(values) {
   return deduped;
 }
 
+function normalizeWecomBotCardMode(value, fallback = DEFAULT_BOT_CARD_MODE) {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!normalized) return fallback;
+  if (normalized === "template-card" || normalized === "templatecard") return "template_card";
+  if (BOT_CARD_MODE_SET.has(normalized)) return normalized;
+  return fallback;
+}
+
+function normalizeWecomDmPolicyMode(value, fallback = "open") {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!normalized) return fallback;
+  if (normalized === "closed" || normalized === "close") return "deny";
+  if (normalized === "whitelist") return "allowlist";
+  if (DM_POLICY_MODE_SET.has(normalized)) return normalized;
+  return fallback;
+}
+
 export function normalizeWecomAllowFromEntry(raw) {
   const trimmed = String(raw ?? "").trim();
   if (!trimmed) return "";
@@ -541,23 +723,31 @@ export function resolveWecomCommandPolicyConfig({
 } = {}) {
   const commandConfig =
     channelConfig?.commands && typeof channelConfig.commands === "object" ? channelConfig.commands : {};
-  const enabled = parseBooleanLike(
-    commandConfig.enabled,
-    parseBooleanLike(envVars?.WECOM_COMMANDS_ENABLED, parseBooleanLike(processEnv?.WECOM_COMMANDS_ENABLED, false)),
-  );
+  const legacyAllowlist = uniqueCommandList(parseStringList(channelConfig?.commandAllowlist));
   const configuredAllowlist = uniqueCommandList(
     parseStringList(
       commandConfig.allowlist,
+      legacyAllowlist,
       envVars?.WECOM_COMMANDS_ALLOWLIST,
       processEnv?.WECOM_COMMANDS_ALLOWLIST,
     ),
   );
+  const allowlistEnabledByConfig = configuredAllowlist.length > 0;
+  const enabled = parseBooleanLike(
+    commandConfig.enabled,
+    parseBooleanLike(
+      envVars?.WECOM_COMMANDS_ENABLED,
+      parseBooleanLike(processEnv?.WECOM_COMMANDS_ENABLED, allowlistEnabledByConfig),
+    ),
+  );
   const allowlist = configuredAllowlist.length > 0 ? configuredAllowlist : Array.from(DEFAULT_COMMAND_ALLOWLIST);
   const adminUsers = uniqueLowerCaseList(
     parseStringList(channelConfig?.adminUsers, envVars?.WECOM_ADMIN_USERS, processEnv?.WECOM_ADMIN_USERS),
   );
   const rejectMessage = pickFirstNonEmptyString(
     commandConfig.rejectMessage,
+    commandConfig.blockMessage,
+    channelConfig?.commandBlockMessage,
     envVars?.WECOM_COMMANDS_REJECT_MESSAGE,
     processEnv?.WECOM_COMMANDS_REJECT_MESSAGE,
     "该指令未开放，请联系管理员。",
@@ -578,8 +768,12 @@ export function resolveWecomAllowFromPolicyConfig({
   processEnv = process.env,
   accountId = "default",
 } = {}) {
-  const accountAllowFrom = uniqueAllowFromList(parseStringList(accountConfig?.allowFrom));
-  const channelAllowFrom = uniqueAllowFromList(parseStringList(channelConfig?.allowFrom));
+  const accountAllowFrom = uniqueAllowFromList(
+    parseStringList(accountConfig?.allowFrom, accountConfig?.dm?.allowFrom),
+  );
+  const channelAllowFrom = uniqueAllowFromList(
+    parseStringList(channelConfig?.allowFrom, channelConfig?.dm?.allowFrom),
+  );
   const envAllowFrom = uniqueAllowFromList(readAllowFromEnv(envVars, processEnv, accountId));
   const allowFrom = accountAllowFrom.length > 0 ? accountAllowFrom : channelAllowFrom.length > 0 ? channelAllowFrom : envAllowFrom;
   const rejectMessage = pickFirstNonEmptyString(
@@ -596,6 +790,85 @@ export function resolveWecomAllowFromPolicyConfig({
   };
 }
 
+export function resolveWecomDmPolicyConfig({
+  channelConfig = {},
+  accountConfig = {},
+  envVars = {},
+  processEnv = process.env,
+  accountId = "default",
+} = {}) {
+  const channelDmConfig = channelConfig?.dm && typeof channelConfig.dm === "object" ? channelConfig.dm : {};
+  const accountDmConfig = accountConfig?.dm && typeof accountConfig.dm === "object" ? accountConfig.dm : {};
+  const mode = normalizeWecomDmPolicyMode(
+    pickFirstNonEmptyString(
+      accountDmConfig.mode,
+      channelDmConfig.mode,
+      readDmPolicyModeEnv(envVars, processEnv, accountId),
+      "open",
+    ),
+  );
+  const allowFrom = uniqueAllowFromList(
+    parseStringList(
+      accountDmConfig.allowFrom,
+      channelDmConfig.allowFrom,
+      readDmAllowFromEnv(envVars, processEnv, accountId),
+    ),
+  );
+  const rejectMessage = pickFirstNonEmptyString(
+    accountDmConfig.rejectMessage,
+    accountDmConfig.blockMessage,
+    channelDmConfig.rejectMessage,
+    channelDmConfig.blockMessage,
+    readDmRejectMessageEnv(envVars, processEnv, accountId),
+    mode === "deny" ? "当前渠道私聊已关闭，请联系管理员。" : "当前私聊账号未授权，请联系管理员。",
+  );
+  const effectiveMode = mode === "allowlist" && allowFrom.length === 0 ? "deny" : mode;
+  return {
+    mode: effectiveMode,
+    allowFrom,
+    rejectMessage,
+    enabled: effectiveMode !== "open" || allowFrom.length > 0,
+  };
+}
+
+export function resolveWecomEventPolicyConfig({
+  channelConfig = {},
+  accountConfig = {},
+  envVars = {},
+  processEnv = process.env,
+  accountId = "default",
+} = {}) {
+  const channelEventConfig = channelConfig?.events && typeof channelConfig.events === "object" ? channelConfig.events : {};
+  const accountEventConfig = accountConfig?.events && typeof accountConfig.events === "object" ? accountConfig.events : {};
+  const enabled = parseBooleanLike(
+    accountEventConfig.enabled,
+    parseBooleanLike(
+      channelEventConfig.enabled,
+      parseBooleanLike(readEventEnabledEnv(envVars, processEnv, accountId), true),
+    ),
+  );
+  const enterAgentWelcomeEnabled = enabled
+    ? parseBooleanLike(
+        accountEventConfig.enterAgentWelcomeEnabled,
+        parseBooleanLike(
+          channelEventConfig.enterAgentWelcomeEnabled,
+          parseBooleanLike(readEventEnterAgentWelcomeEnabledEnv(envVars, processEnv, accountId), false),
+        ),
+      )
+    : false;
+  const enterAgentWelcomeText = pickFirstNonEmptyString(
+    accountEventConfig.enterAgentWelcomeText,
+    channelEventConfig.enterAgentWelcomeText,
+    readEventEnterAgentWelcomeTextEnv(envVars, processEnv, accountId),
+    DEFAULT_EVENT_ENTER_AGENT_WELCOME_TEXT,
+  );
+  return {
+    enabled,
+    enterAgentWelcomeEnabled,
+    enterAgentWelcomeText,
+  };
+}
+
 export function isWecomSenderAllowed({ senderId, allowFrom = [] } = {}) {
   const sender = normalizeWecomAllowFromEntry(senderId);
   if (!sender) return false;
@@ -817,8 +1090,16 @@ export function resolveWecomDynamicAgentConfig({
   envVars = {},
   processEnv = process.env,
 } = {}) {
-  const dynamicConfig =
-    channelConfig?.dynamicAgent && typeof channelConfig.dynamicAgent === "object" ? channelConfig.dynamicAgent : {};
+  const dynamicAgentConfig =
+    channelConfig?.dynamicAgent && typeof channelConfig.dynamicAgent === "object"
+      ? channelConfig.dynamicAgent
+      : {};
+  const dynamicAgentsCompatConfig =
+    channelConfig?.dynamicAgents && typeof channelConfig.dynamicAgents === "object"
+      ? channelConfig.dynamicAgents
+      : {};
+  const dynamicConfig = Object.keys(dynamicAgentConfig).length > 0 ? dynamicAgentConfig : dynamicAgentsCompatConfig;
+  const dmCompatConfig = channelConfig?.dm && typeof channelConfig.dm === "object" ? channelConfig.dm : {};
   const enabled = parseBooleanLike(
     dynamicConfig.enabled,
     parseBooleanLike(
@@ -866,6 +1147,7 @@ export function resolveWecomDynamicAgentConfig({
   );
   const workspaceTemplate = pickFirstNonEmptyString(
     dynamicConfig.workspaceTemplate,
+    channelConfig?.workspaceTemplate,
     envVars?.WECOM_DYNAMIC_AGENT_WORKSPACE_TEMPLATE,
     processEnv?.WECOM_DYNAMIC_AGENT_WORKSPACE_TEMPLATE,
   );
@@ -911,6 +1193,23 @@ export function resolveWecomDynamicAgentConfig({
       parseBooleanLike(processEnv?.WECOM_DYNAMIC_AGENT_ALLOW_FALLBACK, true),
     ),
   );
+  const dmCreateAgent = parseBooleanLike(
+    dynamicConfig.dmCreateAgentOnFirstMessage,
+    parseBooleanLike(
+      dmCompatConfig.createAgentOnFirstMessage,
+      parseBooleanLike(
+        envVars?.WECOM_DM_CREATE_AGENT_ON_FIRST_MESSAGE,
+        parseBooleanLike(processEnv?.WECOM_DM_CREATE_AGENT_ON_FIRST_MESSAGE, true),
+      ),
+    ),
+  );
+  const groupEnabled = parseBooleanLike(
+    dynamicConfig.groupEnabled,
+    parseBooleanLike(
+      channelConfig?.groupChat?.enabled,
+      parseBooleanLike(envVars?.WECOM_GROUP_CHAT_ENABLED, parseBooleanLike(processEnv?.WECOM_GROUP_CHAT_ENABLED, true)),
+    ),
+  );
   const userMap = parseDynamicAgentMap(
     dynamicConfig.userMap,
     envVars?.WECOM_DYNAMIC_AGENT_USER_MAP,
@@ -941,6 +1240,8 @@ export function resolveWecomDynamicAgentConfig({
     forceAgentSessionKey,
     preferMentionMap,
     allowFallbackToDefaultRoute,
+    dmCreateAgent,
+    groupEnabled,
     userMap,
     groupMap,
     mentionMap,
@@ -1077,90 +1378,318 @@ export function resolveWecomObservabilityConfig({
   };
 }
 
+export function resolveWecomBotCardConfig({
+  botConfig = {},
+  envVars = {},
+  processEnv = process.env,
+} = {}) {
+  const cardConfig = botConfig?.card && typeof botConfig.card === "object" ? botConfig.card : {};
+  const enabled = parseBooleanLike(
+    cardConfig.enabled,
+    parseBooleanLike(
+      envVars?.WECOM_BOT_CARD_ENABLED,
+      parseBooleanLike(processEnv?.WECOM_BOT_CARD_ENABLED, false),
+    ),
+  );
+  const mode = normalizeWecomBotCardMode(
+    pickFirstNonEmptyString(
+      cardConfig.mode,
+      envVars?.WECOM_BOT_CARD_MODE,
+      processEnv?.WECOM_BOT_CARD_MODE,
+      DEFAULT_BOT_CARD_MODE,
+    ),
+  );
+  const title = pickFirstNonEmptyString(
+    cardConfig.title,
+    envVars?.WECOM_BOT_CARD_TITLE,
+    processEnv?.WECOM_BOT_CARD_TITLE,
+    "OpenClaw-Wechat",
+  );
+  const subtitle = pickFirstNonEmptyString(
+    cardConfig.subtitle,
+    cardConfig.subTitle,
+    envVars?.WECOM_BOT_CARD_SUBTITLE,
+    processEnv?.WECOM_BOT_CARD_SUBTITLE,
+  );
+  const footer = pickFirstNonEmptyString(
+    cardConfig.footer,
+    envVars?.WECOM_BOT_CARD_FOOTER,
+    processEnv?.WECOM_BOT_CARD_FOOTER,
+  );
+  const maxContentLength = asBoundedPositiveInteger(
+    cardConfig.maxContentLength ??
+      cardConfig.maxBodyChars ??
+      envVars?.WECOM_BOT_CARD_MAX_CONTENT_LENGTH ??
+      processEnv?.WECOM_BOT_CARD_MAX_CONTENT_LENGTH,
+    1400,
+    200,
+    4000,
+  );
+  const responseUrlEnabled = parseBooleanLike(
+    cardConfig.responseUrlEnabled,
+    parseBooleanLike(
+      envVars?.WECOM_BOT_CARD_RESPONSE_URL_ENABLED,
+      parseBooleanLike(processEnv?.WECOM_BOT_CARD_RESPONSE_URL_ENABLED, true),
+    ),
+  );
+  const webhookBotEnabled = parseBooleanLike(
+    cardConfig.webhookBotEnabled,
+    parseBooleanLike(
+      envVars?.WECOM_BOT_CARD_WEBHOOK_BOT_ENABLED,
+      parseBooleanLike(processEnv?.WECOM_BOT_CARD_WEBHOOK_BOT_ENABLED, true),
+    ),
+  );
+  return {
+    enabled,
+    mode,
+    title,
+    subtitle: subtitle || undefined,
+    footer: footer || undefined,
+    maxContentLength,
+    responseUrlEnabled,
+    webhookBotEnabled,
+  };
+}
+
 export function resolveWecomBotModeConfig({
   channelConfig = {},
   envVars = {},
   processEnv = process.env,
+  accountId = "default",
+  botConfigOverride,
 } = {}) {
-  const botConfig = channelConfig?.bot && typeof channelConfig.bot === "object" ? channelConfig.bot : {};
+  const normalizedAccountId = normalizeAccountIdForEnv(accountId);
+  const legacyInlineAccountConfig = resolveLegacyInlineAccountConfig(channelConfig, normalizedAccountId);
+  const defaultInlineAccountConfig = resolveLegacyInlineAccountConfig(channelConfig, "default");
+  const accountConfig =
+    normalizedAccountId === "default"
+      ? (defaultInlineAccountConfig ?? channelConfig)
+      : channelConfig?.accounts && typeof channelConfig.accounts === "object"
+        ? (channelConfig.accounts[normalizedAccountId] ?? legacyInlineAccountConfig)
+        : legacyInlineAccountConfig;
+  const scopedBotConfig =
+    normalizedAccountId === "default"
+      ? channelConfig?.bot
+      : accountConfig && typeof accountConfig === "object"
+        ? accountConfig.bot
+        : null;
+  const botConfig =
+    botConfigOverride && typeof botConfigOverride === "object"
+      ? botConfigOverride
+      : scopedBotConfig && typeof scopedBotConfig === "object"
+        ? scopedBotConfig
+        : {};
+
+  const scopedEnvVars = { ...(envVars && typeof envVars === "object" ? envVars : {}) };
+  const scopedProcessEnv = { ...(processEnv && typeof processEnv === "object" ? processEnv : {}) };
+  const botEnvSuffixes = [
+    "ENABLED",
+    "TOKEN",
+    "ENCODING_AES_KEY",
+    "WEBHOOK_PATH",
+    "PLACEHOLDER_TEXT",
+    "STREAM_EXPIRE_MS",
+    "REPLY_TIMEOUT_MS",
+    "LATE_REPLY_WATCH_MS",
+    "LATE_REPLY_POLL_MS",
+    "CARD_ENABLED",
+    "CARD_MODE",
+    "CARD_TITLE",
+    "CARD_SUBTITLE",
+    "CARD_FOOTER",
+    "CARD_MAX_CONTENT_LENGTH",
+    "CARD_RESPONSE_URL_ENABLED",
+    "CARD_WEBHOOK_BOT_ENABLED",
+  ];
+  if (normalizedAccountId !== "default") {
+    const accountPrefix = `WECOM_${normalizedAccountId.toUpperCase()}_BOT_`;
+    for (const suffix of botEnvSuffixes) {
+      const scopedKey = `${accountPrefix}${suffix}`;
+      const mappedKey = `WECOM_BOT_${suffix}`;
+      if (Object.prototype.hasOwnProperty.call(scopedEnvVars, scopedKey)) {
+        scopedEnvVars[mappedKey] = scopedEnvVars[scopedKey];
+      }
+      if (Object.prototype.hasOwnProperty.call(scopedProcessEnv, scopedKey)) {
+        scopedProcessEnv[mappedKey] = scopedProcessEnv[scopedKey];
+      }
+    }
+  }
   const enabled = parseBooleanLike(
     botConfig.enabled,
-    parseBooleanLike(envVars?.WECOM_BOT_ENABLED, parseBooleanLike(processEnv?.WECOM_BOT_ENABLED, false)),
+    parseBooleanLike(scopedEnvVars?.WECOM_BOT_ENABLED, parseBooleanLike(scopedProcessEnv?.WECOM_BOT_ENABLED, false)),
   );
+  const legacyAgentCompat =
+    accountConfig?.agent && typeof accountConfig.agent === "object" ? accountConfig.agent : null;
+  const legacyTopLevelBotToken = legacyAgentCompat ? pickFirstNonEmptyString(accountConfig?.token) : "";
+  const legacyTopLevelBotAesKey = legacyAgentCompat ? pickFirstNonEmptyString(accountConfig?.encodingAesKey) : "";
+  const legacyTopLevelBotWebhookPath = legacyAgentCompat ? pickFirstNonEmptyString(accountConfig?.webhookPath) : "";
   const token = pickFirstNonEmptyString(
     botConfig.token,
-    envVars?.WECOM_BOT_TOKEN,
-    processEnv?.WECOM_BOT_TOKEN,
+    botConfig.callbackToken,
+    legacyTopLevelBotToken,
+    scopedEnvVars?.WECOM_BOT_TOKEN,
+    scopedProcessEnv?.WECOM_BOT_TOKEN,
   );
   const encodingAesKey = pickFirstNonEmptyString(
     botConfig.encodingAesKey,
-    envVars?.WECOM_BOT_ENCODING_AES_KEY,
-    processEnv?.WECOM_BOT_ENCODING_AES_KEY,
+    botConfig.callbackAesKey,
+    legacyTopLevelBotAesKey,
+    scopedEnvVars?.WECOM_BOT_ENCODING_AES_KEY,
+    scopedProcessEnv?.WECOM_BOT_ENCODING_AES_KEY,
   );
   const webhookPath = pickFirstNonEmptyString(
     botConfig.webhookPath,
-    envVars?.WECOM_BOT_WEBHOOK_PATH,
-    processEnv?.WECOM_BOT_WEBHOOK_PATH,
-    "/wecom/bot/callback",
+    legacyTopLevelBotWebhookPath,
+    scopedEnvVars?.WECOM_BOT_WEBHOOK_PATH,
+    scopedProcessEnv?.WECOM_BOT_WEBHOOK_PATH,
+    buildDefaultBotWebhookPath(normalizedAccountId),
   );
   const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj ?? {}, key);
   const placeholderText = (() => {
     if (hasOwn(botConfig, "placeholderText")) return String(botConfig.placeholderText ?? "");
-    if (hasOwn(envVars, "WECOM_BOT_PLACEHOLDER_TEXT")) return String(envVars.WECOM_BOT_PLACEHOLDER_TEXT ?? "");
-    if (hasOwn(processEnv, "WECOM_BOT_PLACEHOLDER_TEXT"))
-      return String(processEnv.WECOM_BOT_PLACEHOLDER_TEXT ?? "");
+    if (hasOwn(scopedEnvVars, "WECOM_BOT_PLACEHOLDER_TEXT")) return String(scopedEnvVars.WECOM_BOT_PLACEHOLDER_TEXT ?? "");
+    if (hasOwn(scopedProcessEnv, "WECOM_BOT_PLACEHOLDER_TEXT"))
+      return String(scopedProcessEnv.WECOM_BOT_PLACEHOLDER_TEXT ?? "");
     return "消息已收到，正在处理中，请稍等片刻。";
   })();
   const streamExpireMs = asBoundedPositiveInteger(
     botConfig.streamExpireMs ??
-      envVars?.WECOM_BOT_STREAM_EXPIRE_MS ??
-      processEnv?.WECOM_BOT_STREAM_EXPIRE_MS,
+      scopedEnvVars?.WECOM_BOT_STREAM_EXPIRE_MS ??
+      scopedProcessEnv?.WECOM_BOT_STREAM_EXPIRE_MS,
     10 * 60 * 1000,
     30 * 1000,
     60 * 60 * 1000,
   );
   const replyTimeoutMs = asBoundedPositiveInteger(
     botConfig.replyTimeoutMs ??
-      envVars?.WECOM_BOT_REPLY_TIMEOUT_MS ??
-      processEnv?.WECOM_BOT_REPLY_TIMEOUT_MS ??
-      envVars?.WECOM_REPLY_TIMEOUT_MS ??
-      processEnv?.WECOM_REPLY_TIMEOUT_MS,
+      scopedEnvVars?.WECOM_BOT_REPLY_TIMEOUT_MS ??
+      scopedProcessEnv?.WECOM_BOT_REPLY_TIMEOUT_MS ??
+      scopedEnvVars?.WECOM_REPLY_TIMEOUT_MS ??
+      scopedProcessEnv?.WECOM_REPLY_TIMEOUT_MS,
     90000,
     15000,
     10 * 60 * 1000,
   );
   const lateReplyWatchMs = asBoundedPositiveInteger(
     botConfig.lateReplyWatchMs ??
-      envVars?.WECOM_BOT_LATE_REPLY_WATCH_MS ??
-      processEnv?.WECOM_BOT_LATE_REPLY_WATCH_MS ??
-      envVars?.WECOM_LATE_REPLY_WATCH_MS ??
-      processEnv?.WECOM_LATE_REPLY_WATCH_MS,
+      scopedEnvVars?.WECOM_BOT_LATE_REPLY_WATCH_MS ??
+      scopedProcessEnv?.WECOM_BOT_LATE_REPLY_WATCH_MS ??
+      scopedEnvVars?.WECOM_LATE_REPLY_WATCH_MS ??
+      scopedProcessEnv?.WECOM_LATE_REPLY_WATCH_MS,
     180000,
     30000,
     10 * 60 * 1000,
   );
   const lateReplyPollMs = asBoundedPositiveInteger(
     botConfig.lateReplyPollMs ??
-      envVars?.WECOM_BOT_LATE_REPLY_POLL_MS ??
-      processEnv?.WECOM_BOT_LATE_REPLY_POLL_MS ??
-      envVars?.WECOM_LATE_REPLY_POLL_MS ??
-      processEnv?.WECOM_LATE_REPLY_POLL_MS,
+      scopedEnvVars?.WECOM_BOT_LATE_REPLY_POLL_MS ??
+      scopedProcessEnv?.WECOM_BOT_LATE_REPLY_POLL_MS ??
+      scopedEnvVars?.WECOM_LATE_REPLY_POLL_MS ??
+      scopedProcessEnv?.WECOM_LATE_REPLY_POLL_MS,
     2000,
     500,
     10000,
   );
+  const card = resolveWecomBotCardConfig({
+    botConfig,
+    envVars: scopedEnvVars,
+    processEnv: scopedProcessEnv,
+  });
 
   return {
+    accountId: normalizedAccountId,
     enabled,
     token: token || undefined,
     encodingAesKey: encodingAesKey || undefined,
-    webhookPath: webhookPath || "/wecom/bot/callback",
+    webhookPath: webhookPath || buildDefaultBotWebhookPath(normalizedAccountId),
     placeholderText,
     streamExpireMs,
     replyTimeoutMs,
     lateReplyWatchMs,
     lateReplyPollMs,
+    card,
+  };
+}
+
+export function resolveWecomBotModeAccountsConfig({
+  channelConfig = {},
+  envVars = {},
+  processEnv = process.env,
+} = {}) {
+  const accountIds = new Set(["default"]);
+  const channelAccounts = channelConfig?.accounts;
+  if (channelAccounts && typeof channelAccounts === "object") {
+    for (const accountId of Object.keys(channelAccounts)) {
+      accountIds.add(normalizeAccountIdForEnv(accountId));
+    }
+  }
+  for (const accountId of collectLegacyInlineAccountIds(channelConfig)) {
+    accountIds.add(normalizeAccountIdForEnv(accountId));
+  }
+
+  const scopedBotIdRegex =
+    /^WECOM_([A-Z0-9]+)_BOT_(ENABLED|TOKEN|ENCODING_AES_KEY|WEBHOOK_PATH|PLACEHOLDER_TEXT|STREAM_EXPIRE_MS|REPLY_TIMEOUT_MS|LATE_REPLY_WATCH_MS|LATE_REPLY_POLL_MS|PROXY|CARD_ENABLED|CARD_MODE|CARD_TITLE|CARD_SUBTITLE|CARD_FOOTER|CARD_MAX_CONTENT_LENGTH|CARD_RESPONSE_URL_ENABLED|CARD_WEBHOOK_BOT_ENABLED)$/;
+  const collectScopedIds = (obj) => {
+    if (!obj || typeof obj !== "object") return;
+    for (const key of Object.keys(obj)) {
+      const match = key.match(scopedBotIdRegex);
+      if (!match) continue;
+      const candidate = String(match[1] ?? "").trim().toLowerCase();
+      if (candidate) accountIds.add(candidate);
+    }
+  };
+  collectScopedIds(envVars);
+  collectScopedIds(processEnv);
+
+  const hasScopedBotEnv = (accountId) => {
+    const normalizedAccountId = normalizeAccountIdForEnv(accountId);
+    if (normalizedAccountId === "default") return false;
+    const prefix = `WECOM_${normalizedAccountId.toUpperCase()}_BOT_`;
+    const hasIn = (obj) =>
+      Boolean(
+        obj &&
+          typeof obj === "object" &&
+          Object.keys(obj).some((key) => String(key ?? "").startsWith(prefix)),
+      );
+    return hasIn(envVars) || hasIn(processEnv);
   };
+
+  const ordered = Array.from(accountIds).sort((a, b) => {
+    if (a === "default" && b !== "default") return -1;
+    if (a !== "default" && b === "default") return 1;
+    return a.localeCompare(b);
+  });
+
+  const botConfigs = [];
+  for (const accountId of ordered) {
+    const resolved = resolveWecomBotModeConfig({
+      channelConfig,
+      envVars,
+      processEnv,
+      accountId,
+    });
+    const normalizedAccountId = normalizeAccountIdForEnv(accountId);
+    const accountCfg =
+      normalizedAccountId === "default"
+        ? channelConfig
+        : channelConfig?.accounts && typeof channelConfig.accounts === "object"
+          ? (channelConfig.accounts[normalizedAccountId] ??
+            resolveLegacyInlineAccountConfig(channelConfig, normalizedAccountId))
+          : resolveLegacyInlineAccountConfig(channelConfig, normalizedAccountId);
+    const hasBotConfigObject = Boolean(accountCfg && typeof accountCfg === "object" && accountCfg.bot && typeof accountCfg.bot === "object");
+    if (
+      normalizedAccountId !== "default" &&
+      !hasBotConfigObject &&
+      !hasScopedBotEnv(normalizedAccountId) &&
+      resolved.enabled !== true &&
+      !resolved.token &&
+      !resolved.encodingAesKey
+    ) {
+      continue;
+    }
+    botConfigs.push(resolved);
+  }
+  return botConfigs;
 }
 
 function readVoiceEnv(envVars, processEnv, suffix) {