@max1874/openclaw-wecom 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@max1874/openclaw-wecom",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw WeChat/WeCom channel plugin via Stride",
+  "license": "MIT",
+  "author": "max1874",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/max1874/openclaw-wecom.git"
+  },
+  "homepage": "https://github.com/max1874/openclaw-wecom#readme",
+  "bugs": {
+    "url": "https://github.com/max1874/openclaw-wecom/issues"
+  },
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./plugin-sdk": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "docs",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "wechat",
+    "wecom",
+    "微信",
+    "企业微信",
+    "stride",
+    "chatbot",
+    "ai",
+    "claude"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "WeChat",
+      "selectionLabel": "WeChat/WeCom (微信/企业微信)",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom",
+      "blurb": "WeChat/WeCom messaging via Stride.",
+      "aliases": [
+        "wechat",
+        "stride"
+      ],
+      "order": 80
+    },
+    "install": {
+      "npmSpec": "@max1874/openclaw-wecom",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "openclaw": "2026.1.29",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,42 @@
+import type { ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { WecomConfig, ResolvedWecomAccount } from "./types.js";
+
+/**
+ * Resolve WeChat credentials from config or environment variables.
+ */
+export function resolveWecomCredentials(
+  wecomCfg?: WecomConfig,
+): { token: string; chatId?: string } | null {
+  const token = wecomCfg?.token ?? process.env.WECOM_TOKEN ?? process.env.STRIDE_TOKEN;
+  if (!token) return null;
+
+  const chatId = wecomCfg?.chatId ?? process.env.WECOM_CHAT_ID ?? process.env.STRIDE_CHAT_ID;
+
+  return { token, chatId };
+}
+
+/**
+ * Check if WeChat channel is configured.
+ */
+export function isWecomConfigured(wecomCfg?: WecomConfig): boolean {
+  return Boolean(resolveWecomCredentials(wecomCfg));
+}
+
+/**
+ * Resolve account information from config.
+ */
+export function resolveWecomAccount(params: {
+  cfg: ClawdbotConfig;
+}): ResolvedWecomAccount {
+  const wecomCfg = params.cfg.channels?.wecom as WecomConfig | undefined;
+  const creds = resolveWecomCredentials(wecomCfg);
+
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    enabled: wecomCfg?.enabled ?? true,
+    configured: Boolean(creds),
+    token: creds?.token,
+    chatId: creds?.chatId,
+  };
+}

package/src/bot.ts

@@ -0,0 +1,377 @@
+import type { ClawdbotConfig, RuntimeEnv, HistoryEntry } from "openclaw/plugin-sdk";
+import {
+  buildPendingHistoryContextFromMap,
+  recordPendingHistoryEntryIfEnabled,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+} from "openclaw/plugin-sdk";
+import type {
+  WecomConfig,
+  WecomMessageContext,
+  WecomWebhookEvent,
+  TextPayload,
+  VoicePayload,
+  ImagePayload,
+  FilePayload,
+  LinkPayload,
+  ChatHistoryPayload,
+} from "./types.js";
+import { getWecomRuntime } from "./runtime.js";
+import {
+  resolveWecomGroupConfig,
+  resolveWecomReplyPolicy,
+  resolveWecomAllowlistMatch,
+  isWecomGroupAllowed,
+} from "./policy.js";
+import { createWecomReplyDispatcher } from "./reply-dispatcher.js";
+import { resolveWecomMediaList, buildWecomMediaPayload } from "./media.js";
+
+/**
+ * Parse message content from webhook event payload.
+ */
+function parseMessageContent(event: WecomWebhookEvent): {
+  content: string;
+  contentType: string;
+  mediaUrl?: string;
+} {
+  const { type, payload } = event;
+
+  switch (type) {
+    case 7: {
+      // Text message
+      const textPayload = payload as TextPayload;
+      // Use pureText if available (removes @mentions), otherwise use text
+      return {
+        content: textPayload.pureText?.trim() || textPayload.text || "",
+        contentType: "text",
+      };
+    }
+
+    case 2: {
+      // Voice message - use transcribed text if available
+      const voicePayload = payload as VoicePayload;
+      const voiceContent = voicePayload.text
+        ? `[Voice] ${voicePayload.text}`
+        : "[Voice message]";
+      return {
+        content: voiceContent,
+        contentType: "voice",
+        mediaUrl: voicePayload.voiceUrl,
+      };
+    }
+
+    case 6: {
+      // Image message
+      const imagePayload = payload as ImagePayload;
+      return {
+        content: "[Image]",
+        contentType: "image",
+        mediaUrl: imagePayload.imageUrl,
+      };
+    }
+
+    case 1: {
+      // File message
+      const filePayload = payload as FilePayload;
+      return {
+        content: `[File] ${filePayload.name || "file"}`,
+        contentType: "file",
+        mediaUrl: filePayload.fileUrl,
+      };
+    }
+
+    case 12: {
+      // Link message
+      const linkPayload = payload as LinkPayload;
+      return {
+        content: `[Link] ${linkPayload.title || ""}\n${linkPayload.url || ""}`,
+        contentType: "link",
+      };
+    }
+
+    case 4: {
+      // Chat history (merged forward)
+      const historyPayload = payload as ChatHistoryPayload;
+      const historyContent = historyPayload.chatHistoryList
+        ?.map((item) => {
+          const sender = item.senderName || "Unknown";
+          const msg = item.message.content || item.message.imageUrl || "[media]";
+          return `${sender}: ${msg}`;
+        })
+        .join("\n");
+      return {
+        content: `[Chat History]\n${historyContent || historyPayload.content || ""}`,
+        contentType: "chatHistory",
+      };
+    }
+
+    case 10000:
+    case 10001: {
+      // System messages - ignore for now
+      return {
+        content: "",
+        contentType: "system",
+      };
+    }
+
+    default:
+      return {
+        content: "[Unknown message type]",
+        contentType: "unknown",
+      };
+  }
+}
+
+/**
+ * Parse a webhook event into a message context.
+ */
+export function parseWecomMessageEvent(event: WecomWebhookEvent): WecomMessageContext {
+  const { content, contentType, mediaUrl } = parseMessageContent(event);
+
+  // Determine if this is a group or DM
+  // If roomId exists, it's a group chat
+  const isGroup = Boolean(event.roomId);
+
+  return {
+    chatId: event.chatId,
+    contactId: event.contactId,
+    contactName: event.contactName,
+    roomId: event.roomId,
+    roomTopic: event.roomTopic,
+    chatType: isGroup ? "group" : "dm",
+    mentionedBot: event.mentionSelf,
+    content,
+    contentType,
+    mediaUrl,
+  };
+}
+
+/**
+ * Handle an incoming WeChat message webhook event.
+ */
+export async function handleWecomMessage(params: {
+  cfg: ClawdbotConfig;
+  event: WecomWebhookEvent;
+  runtime?: RuntimeEnv;
+  chatHistories?: Map<string, HistoryEntry[]>;
+}): Promise<void> {
+  const { cfg, event, runtime, chatHistories } = params;
+  const wecomCfg = cfg.channels?.wecom as WecomConfig | undefined;
+  const log = runtime?.log ?? console.log;
+  const error = runtime?.error ?? console.error;
+
+  // Skip self messages
+  if (event.isSelf) {
+    log(`wecom: skipping self message`);
+    return;
+  }
+
+  // Skip system messages
+  if (event.type === 10000 || event.type === 10001) {
+    log(`wecom: skipping system message type ${event.type}`);
+    return;
+  }
+
+  const ctx = parseWecomMessageEvent(event);
+  const isGroup = ctx.chatType === "group";
+
+  // Skip empty content
+  if (!ctx.content.trim()) {
+    log(`wecom: skipping empty message`);
+    return;
+  }
+
+  log(`wecom: received ${ctx.contentType} from ${ctx.contactName} (${ctx.contactId}) in ${ctx.chatId} (${ctx.chatType})`);
+
+  const historyLimit = Math.max(
+    0,
+    wecomCfg?.historyLimit ?? cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT,
+  );
+
+  // Check policies
+  if (isGroup) {
+    const groupPolicy = wecomCfg?.groupPolicy ?? "allowlist";
+    const groupAllowFrom = wecomCfg?.groupAllowFrom ?? [];
+    const groupConfig = resolveWecomGroupConfig({ cfg: wecomCfg, groupId: ctx.roomId ?? ctx.chatId });
+
+    const senderAllowFrom = groupConfig?.allowFrom ?? groupAllowFrom;
+    const allowed = isWecomGroupAllowed({
+      groupPolicy,
+      allowFrom: senderAllowFrom,
+      senderId: ctx.contactId,
+      senderName: ctx.contactName,
+    });
+
+    if (!allowed) {
+      log(`wecom: sender ${ctx.contactId} not in group allowlist`);
+      return;
+    }
+
+    const { requireMention } = resolveWecomReplyPolicy({
+      isDirectMessage: false,
+      globalConfig: wecomCfg,
+      groupConfig,
+    });
+
+    if (requireMention && !ctx.mentionedBot) {
+      log(`wecom: message in group ${ctx.chatId} did not mention bot, recording to history`);
+      if (chatHistories) {
+        recordPendingHistoryEntryIfEnabled({
+          historyMap: chatHistories,
+          historyKey: ctx.chatId,
+          limit: historyLimit,
+          entry: {
+            sender: ctx.contactId,
+            body: `${ctx.contactName}: ${ctx.content}`,
+            timestamp: Date.now(),
+            messageId: `${ctx.chatId}:${Date.now()}`,
+          },
+        });
+      }
+      return;
+    }
+  } else {
+    // DM policy check
+    const dmPolicy = wecomCfg?.dmPolicy ?? "allowlist";
+    const allowFrom = wecomCfg?.allowFrom ?? [];
+
+    if (dmPolicy === "allowlist") {
+      const match = resolveWecomAllowlistMatch({
+        allowFrom,
+        senderId: ctx.contactId,
+        senderName: ctx.contactName,
+      });
+      if (!match.allowed) {
+        log(`wecom: sender ${ctx.contactId} not in DM allowlist`);
+        return;
+      }
+    }
+  }
+
+  try {
+    const core = getWecomRuntime();
+
+    // Build From/To identifiers
+    const wecomFrom = `wecom:${ctx.contactId}`;
+    const wecomTo = isGroup ? `chat:${ctx.chatId}` : `user:${ctx.contactId}`;
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "wecom",
+      peer: {
+        kind: isGroup ? "group" : "dm",
+        id: isGroup ? (ctx.roomId ?? ctx.chatId) : ctx.contactId,
+      },
+    });
+
+    const preview = ctx.content.replace(/\s+/g, " ").slice(0, 160);
+    const inboundLabel = isGroup
+      ? `WeChat message in group ${ctx.roomTopic || ctx.chatId}`
+      : `WeChat DM from ${ctx.contactName}`;
+
+    core.system.enqueueSystemEvent(`${inboundLabel}: ${preview}`, {
+      sessionKey: route.sessionKey,
+      contextKey: `wecom:message:${ctx.chatId}:${Date.now()}`,
+    });
+
+    // Resolve media from message
+    const mediaMaxBytes = (wecomCfg?.mediaMaxMb ?? 30) * 1024 * 1024;
+    const mediaList = await resolveWecomMediaList({
+      cfg,
+      type: event.type,
+      payload: event.payload as Record<string, unknown>,
+      maxBytes: mediaMaxBytes,
+      log,
+    });
+    const mediaPayload = buildWecomMediaPayload(mediaList);
+
+    const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+
+    // Build message body with speaker label
+    const speaker = ctx.contactName || ctx.contactId;
+    let messageBody = `${speaker}: ${ctx.content}`;
+
+    const envelopeFrom = isGroup ? `${ctx.chatId}:${ctx.contactId}` : ctx.contactId;
+
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "WeChat",
+      from: envelopeFrom,
+      timestamp: new Date(),
+      envelope: envelopeOptions,
+      body: messageBody,
+    });
+
+    let combinedBody = body;
+    const historyKey = isGroup ? ctx.chatId : undefined;
+
+    if (isGroup && historyKey && chatHistories) {
+      combinedBody = buildPendingHistoryContextFromMap({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+        currentMessage: combinedBody,
+        formatEntry: (entry) =>
+          core.channel.reply.formatAgentEnvelope({
+            channel: "WeChat",
+            from: `${ctx.chatId}:${entry.sender}`,
+            timestamp: entry.timestamp,
+            body: entry.body,
+            envelope: envelopeOptions,
+          }),
+      });
+    }
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: combinedBody,
+      RawBody: ctx.content,
+      CommandBody: ctx.content,
+      From: wecomFrom,
+      To: wecomTo,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: isGroup ? "group" : "direct",
+      GroupSubject: isGroup ? (ctx.roomTopic ?? ctx.chatId) : undefined,
+      SenderName: ctx.contactName || ctx.contactId,
+      SenderId: ctx.contactId,
+      Provider: "wecom" as const,
+      Surface: "wecom" as const,
+      MessageSid: `${ctx.chatId}:${Date.now()}`,
+      Timestamp: Date.now(),
+      WasMentioned: ctx.mentionedBot,
+      CommandAuthorized: true,
+      OriginatingChannel: "wecom" as const,
+      OriginatingTo: wecomTo,
+      ...mediaPayload,
+    });
+
+    const { dispatcher, replyOptions, markDispatchIdle } = createWecomReplyDispatcher({
+      cfg,
+      agentId: route.agentId,
+      runtime: runtime as RuntimeEnv,
+      chatId: ctx.chatId,
+    });
+
+    log(`wecom: dispatching to agent (session=${route.sessionKey})`);
+
+    const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+      ctx: ctxPayload,
+      cfg,
+      dispatcher,
+      replyOptions,
+    });
+
+    markDispatchIdle();
+
+    if (isGroup && historyKey && chatHistories) {
+      clearHistoryEntriesIfEnabled({
+        historyMap: chatHistories,
+        historyKey,
+        limit: historyLimit,
+      });
+    }
+
+    log(`wecom: dispatch complete (queuedFinal=${queuedFinal}, replies=${counts.final})`);
+  } catch (err) {
+    error(`wecom: failed to dispatch message: ${String(err)}`);
+  }
+}

package/src/channel.ts

@@ -0,0 +1,208 @@
+import type { ChannelPlugin, ClawdbotConfig } from "openclaw/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { ResolvedWecomAccount, WecomConfig } from "./types.js";
+import { resolveWecomAccount, resolveWecomCredentials } from "./accounts.js";
+import { wecomOutbound } from "./outbound.js";
+import { probeWecom } from "./probe.js";
+import { resolveWecomGroupToolPolicy } from "./policy.js";
+import { normalizeWecomTarget, looksLikeWecomId, formatWecomTarget } from "./targets.js";
+import { sendMessageWecom } from "./send.js";
+
+const meta = {
+  id: "wecom",
+  label: "WeChat",
+  selectionLabel: "WeChat/WeCom (微信/企业微信)",
+  docsPath: "/channels/wecom",
+  docsLabel: "wecom",
+  blurb: "WeChat/WeCom messaging via Stride.",
+  aliases: ["wechat", "stride"],
+  order: 80,
+} as const;
+
+export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
+  id: "wecom",
+  meta: {
+    ...meta,
+  },
+  pairing: {
+    idLabel: "wecomContactId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(wecom|user|contact):/i, ""),
+    notifyApproval: async ({ cfg, id }) => {
+      await sendMessageWecom({
+        cfg,
+        to: id,
+        text: "Your access has been approved. You can now start chatting!",
+      });
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "channel"],
+    polls: false,
+    threads: false, // WeChat doesn't support threads
+    media: true,
+    reactions: false, // Not supported via Stride
+    edit: false, // Not supported via Stride
+    reply: false, // Not supported via Stride
+  },
+  agentPrompt: {
+    messageToolHints: () => [
+      "- WeChat targeting: omit `target` to reply to the current conversation (auto-inferred). Explicit targets: `user:contactId` or `chat:chatId`.",
+      "- WeChat does not support interactive cards or markdown. Use plain text.",
+    ],
+  },
+  groups: {
+    resolveToolPolicy: resolveWecomGroupToolPolicy,
+  },
+  reload: { configPrefixes: ["channels.wecom"] },
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean" },
+        token: { type: "string" },
+        chatId: { type: "string" },
+        webhookPath: { type: "string" },
+        webhookPort: { type: "integer", minimum: 1 },
+        dmPolicy: { type: "string", enum: ["open", "allowlist"] },
+        allowFrom: { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
+        groupPolicy: { type: "string", enum: ["open", "allowlist", "disabled"] },
+        groupAllowFrom: { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } },
+        requireMention: { type: "boolean" },
+        historyLimit: { type: "integer", minimum: 0 },
+        dmHistoryLimit: { type: "integer", minimum: 0 },
+        textChunkLimit: { type: "integer", minimum: 1 },
+        chunkMode: { type: "string", enum: ["length", "newline"] },
+        mediaMaxMb: { type: "number", minimum: 0 },
+        renderMode: { type: "string", enum: ["auto", "raw"] },
+      },
+    },
+  },
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg) => resolveWecomAccount({ cfg }),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, enabled }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        wecom: {
+          ...cfg.channels?.wecom,
+          enabled,
+        },
+      },
+    }),
+    deleteAccount: ({ cfg }) => {
+      const next = { ...cfg } as ClawdbotConfig;
+      const nextChannels = { ...cfg.channels };
+      delete (nextChannels as Record<string, unknown>).wecom;
+      if (Object.keys(nextChannels).length > 0) {
+        next.channels = nextChannels;
+      } else {
+        delete next.channels;
+      }
+      return next;
+    },
+    isConfigured: (_account, cfg) =>
+      Boolean(resolveWecomCredentials(cfg.channels?.wecom as WecomConfig | undefined)),
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+    resolveAllowFrom: ({ cfg }) =>
+      (cfg.channels?.wecom as WecomConfig | undefined)?.allowFrom ?? [],
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    collectWarnings: ({ cfg }) => {
+      const wecomCfg = cfg.channels?.wecom as WecomConfig | undefined;
+      const defaultGroupPolicy = (cfg.channels as Record<string, { groupPolicy?: string }> | undefined)?.defaults?.groupPolicy;
+      const groupPolicy = wecomCfg?.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- WeChat groups: groupPolicy="open" allows any member to trigger (mention-gated). Set channels.wecom.groupPolicy="allowlist" + channels.wecom.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  setup: {
+    resolveAccountId: () => DEFAULT_ACCOUNT_ID,
+    applyAccountConfig: ({ cfg }) => ({
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        wecom: {
+          ...cfg.channels?.wecom,
+          enabled: true,
+        },
+      },
+    }),
+  },
+  messaging: {
+    normalizeTarget: normalizeWecomTarget,
+    targetResolver: {
+      looksLikeId: looksLikeWecomId,
+      hint: "<chatId|user:contactId|chat:chatId>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async () => [],
+    listGroups: async () => [],
+    listPeersLive: async () => [],
+    listGroupsLive: async () => [],
+  },
+  outbound: wecomOutbound,
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+      port: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      port: snapshot.port ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ cfg }) =>
+      await probeWecom(cfg.channels?.wecom as WecomConfig | undefined),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      port: runtime?.port ?? null,
+      probe,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const { monitorWecomProvider } = await import("./monitor.js");
+      const wecomCfg = ctx.cfg.channels?.wecom as WecomConfig | undefined;
+      const port = wecomCfg?.webhookPort ?? 3000;
+      ctx.setStatus({ accountId: ctx.accountId, port });
+      ctx.log?.info(`starting wecom provider (webhook mode)`);
+      return monitorWecomProvider({
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        accountId: ctx.accountId,
+      });
+    },
+  },
+};