openclaw-wap-channel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ca11back
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# OpenClaw WAP Channel
+
+OpenClaw AI 助手的微信消息通道插件，接收来自 WAuxiliary 插件的消息并调用 AI 处理。
+
+## 📦 安装
+
+```bash
+openclaw plugins install openclaw-wap-channel
+```
+
+## ⚙️ 配置
+
+编辑 OpenClaw 配置文件 `~/.openclaw/openclaw.json`，添加 WAP channel 配置：
+
+```json
+{
+  "channels": {
+    "wap": {
+      "enabled": true,
+      "port": 8765,
+      "authToken": "your-secret-token-here",
+      "whitelist": [
+        "wxid_example1",
+        "wxid_example2"
+      ]
+    }
+  }
+}
+```
+
+### 配置说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `enabled` | boolean | 是 | 是否启用此 channel |
+| `port` | number | 是 | WebSocket 服务器端口 |
+| `authToken` | string | 是 | 认证 Token（需与 WAP 插件配置一致） |
+| `whitelist` | string[] | 否 | 白名单用户列表（为空则不限制） |
+
+## 🚀 使用
+
+安装并配置后，插件会：
+
+1. 启动 WebSocket 服务器监听指定端口
+2. 验证来自 WAP 插件的连接 Token
+3. 接收微信消息并转发给 OpenClaw AI
+4. 将 AI 回复通过 WebSocket 发送回插件
+
+## 📡 协议
+
+### 接收消息（from WAP plugin）
+
+```json
+{
+  "type": "message",
+  "data": {
+    "msg_id": 12345678,
+    "talker": "wxid_xxx",
+    "content": "用户消息",
+    "timestamp": 1706600000000,
+    "is_private": true
+  }
+}
+```
+
+### 发送回复（to WAP plugin）
+
+```json
+{
+  "type": "send_text",
+  "data": {
+    "talker": "wxid_xxx",
+    "content": "AI 回复内容"
+  }
+}
+```
+
+## 🔧 开发与测试
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试服务器
+npm run test:server
+
+# 运行模拟客户端
+npm run test:client
+```
+
+## 📝 许可
+
+MIT License

package/index.ts

@@ -0,0 +1,23 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { wapPlugin } from "./src/channel.js";
+import { startWsService, stopWsService, setWapRuntime } from "./src/ws-server.js";
+
+const plugin = {
+    id: "wap",
+    name: "WeChat (WAP)",
+    description: "WeChat channel via WAuxiliary plugin",
+    configSchema: emptyPluginConfigSchema(),
+    register(api: OpenClawPluginApi) {
+        setWapRuntime(api);
+        api.registerChannel({ plugin: wapPlugin });
+        api.registerService({
+            id: "wap-ws-server",
+            start: () => startWsService(api),
+            stop: () => stopWsService(),
+        });
+    },
+};
+
+export default plugin;
+

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+    "id": "wap",
+    "channels": [
+        "wap"
+    ],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {}
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "openclaw-wap-channel",
+    "version": "1.0.0",
+    "description": "OpenClaw WAP channel plugin for WeChat message integration via WebSocket",
+    "type": "module",
+    "main": "./index.ts",
+    "keywords": [
+        "openclaw",
+        "wechat",
+        "wauxiliary",
+        "websocket",
+        "channel"
+    ],
+    "author": "ca11back",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Ca11back/openclaw_wap_channel.git"
+    },
+    "homepage": "https://github.com/Ca11back/openclaw_wap_channel#readme",
+    "bugs": {
+        "url": "https://github.com/Ca11back/openclaw_wap_channel/issues"
+    },
+    "files": [
+        "index.ts",
+        "src/",
+        "README.md",
+        "LICENSE",
+        "openclaw.plugin.json"
+    ],
+    "openclaw": {
+        "extensions": [
+            "./index.ts"
+        ]
+    },
+    "scripts": {
+        "test:server": "tsx test/standalone-server.ts",
+        "test:client": "tsx test/mock-client.ts"
+    },
+    "dependencies": {
+        "ws": "^8.18.0"
+    },
+    "devDependencies": {
+        "@types/ws": "^8.5.10",
+        "tsx": "^4.7.0"
+    },
+    "peerDependencies": {
+        "openclaw": "*"
+    }
+}

package/src/channel.ts

@@ -0,0 +1,201 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import { sendToClient, getClientCount, getWapRuntime, getClientStats } from "./ws-server.js";
+
+// ============================================================
+// 账户配置类型
+// ============================================================
+
+interface WapAccountConfig {
+    port?: number;
+    authToken?: string;
+    allowFrom?: string[];
+    enabled?: boolean;
+    name?: string;
+    dmPolicy?: "open" | "pairing" | "closed";
+}
+
+interface WapAccount {
+    accountId: string;
+    enabled: boolean;
+    name?: string;
+    config: WapAccountConfig;
+}
+
+// ============================================================
+// 配置 Schema
+// ============================================================
+
+const WapConfigSchema = {
+    type: "object" as const,
+    additionalProperties: false,
+    properties: {
+        enabled: { type: "boolean" as const },
+        port: { type: "number" as const },
+        authToken: { type: "string" as const },
+        accounts: {
+            type: "object" as const,
+            additionalProperties: {
+                type: "object" as const,
+                properties: {
+                    enabled: { type: "boolean" as const },
+                    name: { type: "string" as const },
+                    allowFrom: {
+                        type: "array" as const,
+                        items: { type: "string" as const },
+                    },
+                    dmPolicy: {
+                        type: "string" as const,
+                        enum: ["open", "pairing", "closed"],
+                    },
+                },
+            },
+        },
+    },
+};
+
+// ============================================================
+// Channel 插件定义
+// ============================================================
+
+export const wapPlugin: ChannelPlugin<WapAccount> = {
+    id: "wap",
+
+    meta: {
+        id: "wap",
+        label: "WeChat (WAP)",
+        selectionLabel: "WeChat via WAuxiliary",
+        docsPath: "/channels/wap",
+        blurb: "WeChat messaging via WAuxiliary Android plugin.",
+        aliases: ["wechat", "wx"],
+    },
+
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        media: false,      // 暂不支持媒体消息
+        threads: false,
+        reactions: false,
+        nativeCommands: false,
+    },
+
+    // 配置变更时触发重载
+    reload: { configPrefixes: ["channels.wap"] },
+
+    // 配置 Schema
+    configSchema: WapConfigSchema,
+
+    config: {
+        listAccountIds: (cfg) => {
+            const wapCfg = cfg.channels?.wap as { accounts?: Record<string, unknown> } | undefined;
+            const accounts = wapCfg?.accounts;
+            if (accounts && Object.keys(accounts).length > 0) {
+                return Object.keys(accounts);
+            }
+            return ["default"];
+        },
+
+        resolveAccount: (cfg, accountId) => {
+            const id = accountId ?? "default";
+            const wapCfg = cfg.channels?.wap as
+                | { accounts?: Record<string, WapAccountConfig> }
+                | undefined;
+            const accountCfg = wapCfg?.accounts?.[id] ?? {};
+            return {
+                accountId: id,
+                enabled: accountCfg.enabled ?? true,
+                name: accountCfg.name,
+                config: accountCfg,
+            };
+        },
+
+        isConfigured: (account) => {
+            // 检查是否有连接的客户端
+            const clientCount = getClientCount();
+            return clientCount > 0;
+        },
+
+        describeAccount: (account) => ({
+            accountId: account.accountId,
+            name: account.name,
+            enabled: account.enabled,
+            configured: getClientCount() > 0,
+            connectedClients: getClientCount(),
+        }),
+    },
+
+    security: {
+        resolveDmPolicy: ({ account }) => ({
+            policy: account.config.dmPolicy ?? ("open" as const),
+            allowFrom: account.config.allowFrom ?? [],
+            policyPath: `channels.wap.accounts.${account.accountId}.dmPolicy`,
+            allowFromPath: `channels.wap.accounts.${account.accountId}.allowFrom`,
+        }),
+    },
+
+    outbound: {
+        deliveryMode: "direct",
+        textChunkLimit: 4000,
+
+        sendText: async ({ to, text, accountId }) => {
+            const runtime = getWapRuntime();
+            const effectiveAccountId = accountId ?? "default";
+
+            const sent = sendToClient(
+                {
+                    type: "send_text",
+                    data: { talker: to, content: text },
+                },
+                effectiveAccountId
+            );
+
+            if (!sent) {
+                runtime?.logger.warn(
+                    `WAP sendText failed: no connected clients for account ${effectiveAccountId}`
+                );
+                return {
+                    ok: false,
+                    error: "No connected WAP clients",
+                    channel: "wap",
+                };
+            }
+
+            runtime?.logger.debug(`WAP sendText to ${to}: ${text.substring(0, 50)}...`);
+            return { ok: true, channel: "wap" };
+        },
+    },
+
+    status: {
+        defaultRuntime: {
+            accountId: "default",
+            running: false,
+            lastStartAt: null,
+            lastStopAt: null,
+            lastError: null,
+        },
+
+        buildAccountSnapshot: ({ account, runtime }) => {
+            const clients = getClientStats();
+            const accountClients = clients.filter((c) => c.accountId === account.accountId);
+
+            return {
+                accountId: account.accountId,
+                name: account.name,
+                enabled: account.enabled,
+                configured: accountClients.length > 0,
+                running: runtime?.running ?? (accountClients.length > 0),
+                connectedClients: accountClients.length,
+                lastStartAt: runtime?.lastStartAt ?? null,
+                lastStopAt: runtime?.lastStopAt ?? null,
+                lastError: runtime?.lastError ?? null,
+            };
+        },
+
+        buildChannelSummary: ({ snapshot }) => ({
+            configured: snapshot.configured ?? false,
+            running: snapshot.running ?? false,
+            connectedClients: (snapshot as { connectedClients?: number }).connectedClients ?? 0,
+            lastStartAt: snapshot.lastStartAt ?? null,
+            lastStopAt: snapshot.lastStopAt ?? null,
+            lastError: snapshot.lastError ?? null,
+        }),
+    },
+};

package/src/protocol.ts

@@ -0,0 +1,66 @@
+// ============================================================
+// 上行消息 (Android → Server)
+// ============================================================
+
+export interface WapMessageData {
+    msg_id: number;
+    msg_type: number;
+    talker: string; // 会话 ID (wxid 或群 ID)
+    sender: string; // 发送者 wxid
+    content: string; // 消息内容
+    timestamp: number; // 毫秒时间戳
+    is_private: boolean;
+    is_group: boolean;
+}
+
+export interface WapMessagePayload {
+    type: "message";
+    data: WapMessageData;
+}
+
+export interface WapHeartbeatPayload {
+    type: "heartbeat";
+}
+
+export type WapUpstreamMessage = WapMessagePayload | WapHeartbeatPayload;
+
+// ============================================================
+// 下行指令 (Server → Android)
+// ============================================================
+
+export interface WapSendTextCommand {
+    type: "send_text";
+    data: {
+        talker: string;  // Android 端期望 'talker' 字段
+        content: string;
+    };
+}
+
+export interface WapPongCommand {
+    type: "pong";
+}
+
+// 预留接口：图片消息
+export interface WapSendImageCommand {
+    type: "send_image";
+    data: {
+        talker: string;
+        image_url: string;
+    };
+}
+
+// 预留接口：语音消息
+export interface WapSendVoiceCommand {
+    type: "send_voice";
+    data: {
+        talker: string;
+        voice_url: string;
+        duration: number;
+    };
+}
+
+export type WapDownstreamCommand =
+    | WapSendTextCommand
+    | WapPongCommand
+    | WapSendImageCommand
+    | WapSendVoiceCommand;

package/src/types/openclaw-plugin-sdk.d.ts

@@ -0,0 +1,162 @@
+// Type declarations for openclaw plugin SDK
+// This is a minimal shim since openclaw doesn't export types separately
+
+declare module "openclaw/plugin-sdk" {
+    export interface OpenClawPluginApi {
+        id: string;
+        logger: {
+            debug: (msg: string) => void;
+            info: (msg: string) => void;
+            warn: (msg: string) => void;
+            error: (msg: string) => void;
+        };
+        config: OpenClawConfig;
+        runtime: PluginRuntime;
+        registerChannel: (opts: { plugin: ChannelPlugin<unknown> }) => void;
+        registerService: (opts: {
+            id: string;
+            start: () => void | Promise<void>;
+            stop: () => void | Promise<void>;
+        }) => void;
+    }
+
+    export interface OpenClawConfig {
+        channels?: Record<string, unknown>;
+        session?: {
+            store?: string;
+        };
+        [key: string]: unknown;
+    }
+
+    export interface PluginRuntime {
+        version: string;
+        config: {
+            loadConfig: () => OpenClawConfig;
+            writeConfigFile: (cfg: OpenClawConfig) => void;
+        };
+        system: {
+            enqueueSystemEvent: (text: string, opts?: { sessionKey?: string; contextKey?: string }) => void;
+        };
+        channel: {
+            text: {
+                resolveTextChunkLimit: (cfg: OpenClawConfig, channel: string, accountId?: string, opts?: { fallbackLimit?: number }) => number;
+                resolveChunkMode: (cfg: OpenClawConfig, channel: string, accountId?: string) => string;
+                chunkMarkdownTextWithMode: (text: string, limit: number, mode: string) => string[];
+                hasControlCommand: (text: string, cfg: OpenClawConfig) => boolean;
+            };
+            reply: {
+                dispatchReplyFromConfig: (opts: {
+                    ctx: unknown;
+                    cfg: OpenClawConfig;
+                    dispatcher: unknown;
+                    replyOptions?: unknown;
+                }) => Promise<{ queuedFinal?: boolean; counts?: Record<string, number> }>;
+                createReplyDispatcherWithTyping: (opts: {
+                    responsePrefix?: string;
+                    responsePrefixContextProvider?: () => Record<string, string>;
+                    humanDelay?: unknown;
+                    deliver: (payload: { text?: string; mediaUrl?: string; mediaUrls?: string[] }) => Promise<void>;
+                    onError?: (err: unknown, info: { kind: string }) => void;
+                    onReplyStart?: () => void;
+                }) => {
+                    dispatcher: unknown;
+                    replyOptions: unknown;
+                    markDispatchIdle: () => void;
+                };
+                resolveHumanDelayConfig: (cfg: OpenClawConfig, agentId?: string) => unknown;
+                formatInboundEnvelope: (opts: {
+                    channel: string;
+                    from: string;
+                    timestamp?: number;
+                    body: string;
+                    chatType: string;
+                    sender?: { name: string; id: string };
+                    senderLabel?: string;
+                }) => string;
+                finalizeInboundContext: (ctx: Record<string, unknown>) => Record<string, unknown>;
+            };
+            routing: {
+                resolveAgentRoute: (opts: {
+                    cfg: OpenClawConfig;
+                    channel: string;
+                    accountId: string;
+                    teamId?: string;
+                    peer: { kind: "dm" | "group" | "channel"; id: string };
+                }) => {
+                    sessionKey: string;
+                    mainSessionKey: string;
+                    accountId: string;
+                    agentId: string;
+                };
+            };
+            activity: {
+                record: (opts: { channel: string; accountId: string; direction: "inbound" | "outbound" }) => void;
+            };
+            session: {
+                resolveStorePath: (store: string | undefined, opts: { agentId?: string }) => string;
+                updateLastRoute: (opts: {
+                    storePath: string;
+                    sessionKey: string;
+                    deliveryContext: { channel: string; to: string; accountId: string };
+                }) => Promise<void>;
+            };
+        };
+        logging: {
+            shouldLogVerbose: () => boolean;
+            getChildLogger: (bindings?: Record<string, unknown>) => {
+                debug?: (msg: string) => void;
+                info: (msg: string) => void;
+                warn: (msg: string) => void;
+                error: (msg: string) => void;
+            };
+        };
+        state: {
+            resolveStateDir: (cfg: OpenClawConfig) => string;
+        };
+    }
+
+    export interface ChannelPlugin<TAccount> {
+        id: string;
+        meta: {
+            id: string;
+            label: string;
+            selectionLabel?: string;
+            docsPath?: string;
+            blurb?: string;
+            aliases?: string[];
+        };
+        capabilities: {
+            chatTypes: Array<"direct" | "group" | "channel">;
+        };
+        configSchema?: unknown;
+        reload?: {
+            configPrefixes?: string[];
+        };
+        config: {
+            listAccountIds: (cfg: OpenClawConfig) => string[];
+            isConfigured?: (cfg: OpenClawConfig, accountId?: string) => boolean;
+            resolveAccount: (cfg: OpenClawConfig, accountId?: string) => TAccount;
+            describeAccount?: (account: TAccount, opts?: { snapshot?: unknown }) => Record<string, unknown>;
+        };
+        outbound: {
+            deliveryMode: "direct" | "buffered";
+            sendText: (opts: { to: string; text: string; accountId?: string }) => Promise<{ ok: boolean; channel?: string }>;
+        };
+        gateway?: {
+            startAccount?: (opts: {
+                api: OpenClawPluginApi;
+                accountId: string;
+                abortSignal?: AbortSignal;
+                statusSink?: (status: Record<string, unknown>) => void;
+            }) => void | Promise<void>;
+            stopAccount?: (opts: { accountId: string }) => void | Promise<void>;
+        };
+        status?: {
+            buildConfiguredLabel?: (opts: { cfg: OpenClawConfig; account: TAccount }) => string;
+            buildChannelSummary?: (opts: { cfg: OpenClawConfig; account: TAccount; snapshot?: unknown }) => Record<string, unknown>;
+        };
+    }
+
+    // Re-export common types
+    export type ChannelPluginConfig<T> = ChannelPlugin<T>["config"];
+}

package/src/ws-server.ts

@@ -0,0 +1,420 @@
+import { WebSocketServer, WebSocket } from "ws";
+import type { IncomingMessage } from "http";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { WapUpstreamMessage, WapSendTextCommand, WapMessageData } from "./protocol.js";
+
+let wss: WebSocketServer | null = null;
+let runtime: OpenClawPluginApi | null = null;
+
+// 客户端管理：按 accountId 隔离
+interface ClientInfo {
+    ws: WebSocket;
+    accountId: string;
+    ip: string;
+    connectedAt: Date;
+    messageCount: number;
+    lastMessageAt: number;
+}
+const clients = new Map<string, ClientInfo>();
+
+// 安全配置
+const DEFAULT_PORT = 8765;
+const AUTH_TOKEN_ENV = "WAP_AUTH_TOKEN"; // 环境变量名称，不是 token 值！
+const MAX_MESSAGE_SIZE = 64 * 1024; // 64KB
+const RATE_LIMIT_WINDOW_MS = 1000; // 1 秒
+const RATE_LIMIT_MAX_MESSAGES = 10; // 每秒最多 10 条消息
+
+const wechatContextHint = `
+[WeChat Context]
+尽可能保持简洁（单条 < 300 字）
+禁止使用MarkDown
+`;
+
+export function setWapRuntime(api: OpenClawPluginApi) {
+    runtime = api;
+}
+
+export function getWapRuntime(): OpenClawPluginApi | null {
+    return runtime;
+}
+
+export function startWsService(api: OpenClawPluginApi) {
+    // 调试：输出完整配置
+    api.logger.debug(`WAP channels config: ${JSON.stringify(api.config.channels)}`);
+
+    const wapConfig = api.config.channels?.wap as
+        | { port?: number; authToken?: string; whitelist?: string[] }
+        | undefined;
+
+    api.logger.debug(`WAP wapConfig parsed: ${JSON.stringify(wapConfig)}`);
+
+    const port = wapConfig?.port ?? DEFAULT_PORT;
+    const authToken = process.env[AUTH_TOKEN_ENV] ?? wapConfig?.authToken;
+
+    // 【安全】强制要求配置 token
+    if (!authToken) {
+        api.logger.error(
+            "WAP WebSocket server NOT started: authToken is required. " +
+            "Set WAP_AUTH_TOKEN env or channels.wap.authToken in config."
+        );
+        return;
+    }
+
+    wss = new WebSocketServer({
+        port,
+        maxPayload: MAX_MESSAGE_SIZE, // 【安全】限制消息大小
+    });
+    api.logger.info(`WAP WebSocket server started on port ${port}`);
+
+    // 日志：白名单配置
+    const whitelist = wapConfig?.whitelist ?? [];
+    api.logger.info(`WAP whitelist configured: ${whitelist.length > 0 ? whitelist.join(", ") : "(empty - all allowed)"}`);
+
+    wss.on("connection", (ws, req) => {
+        const clientId = handleConnection(ws, req, authToken, api, whitelist);
+        if (!clientId) return;
+
+        ws.on("message", (data) => handleMessage(clientId, data, api));
+        ws.on("close", () => handleDisconnect(clientId, api));
+        ws.on("error", (err) => api.logger.error(`WebSocket error: ${err.message}`));
+    });
+}
+
+export function stopWsService() {
+    if (wss) {
+        wss.close();
+        wss = null;
+    }
+    clients.clear();
+    runtime?.logger.info("WAP WebSocket server stopped");
+}
+
+function handleConnection(
+    ws: WebSocket,
+    req: IncomingMessage,
+    authToken: string,
+    api: OpenClawPluginApi,
+    whitelist: string[]
+): string | null {
+    // 获取客户端 IP
+    const ip = req.headers["x-forwarded-for"]?.toString().split(",")[0]?.trim()
+        ?? req.socket.remoteAddress
+        ?? "unknown";
+
+    // 【安全】Token 认证（已强制要求）
+    const auth = req.headers.authorization;
+    if (auth !== `Bearer ${authToken}`) {
+        api.logger.warn(`WAP connection rejected from ${ip}: invalid token`);
+        ws.close(4001, "Unauthorized");
+        return null;
+    }
+
+    // 从 query 或 header 获取 accountId（可选，默认 "default"）
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const accountId = url.searchParams.get("accountId")
+        ?? req.headers["x-wap-account-id"]?.toString()
+        ?? "default";
+
+    const clientId = `wap-${accountId}-${Date.now()}`;
+    clients.set(clientId, {
+        ws,
+        accountId,
+        ip,
+        connectedAt: new Date(),
+        messageCount: 0,
+        lastMessageAt: 0,
+    });
+
+    api.logger.info(`WAP client connected: ${clientId} from ${ip} (account: ${accountId})`);
+
+    // 下发配置（白名单等）
+    const configMessage = {
+        type: "config",
+        data: {
+            whitelist: whitelist,
+        },
+    };
+    ws.send(JSON.stringify(configMessage));
+    api.logger.debug(`WAP config sent to ${clientId}: whitelist=${whitelist.length} items`);
+
+    return clientId;
+}
+
+async function handleMessage(
+    clientId: string,
+    data: Buffer | ArrayBuffer | Buffer[],
+    api: OpenClawPluginApi
+) {
+    const client = clients.get(clientId);
+    if (!client) return;
+
+    // 【安全】速率限制
+    const now = Date.now();
+    if (now - client.lastMessageAt < RATE_LIMIT_WINDOW_MS) {
+        client.messageCount++;
+        if (client.messageCount > RATE_LIMIT_MAX_MESSAGES) {
+            api.logger.warn(`WAP rate limit exceeded for ${clientId}, dropping message`);
+            return;
+        }
+    } else {
+        client.messageCount = 1;
+        client.lastMessageAt = now;
+    }
+
+    try {
+        const text = Buffer.isBuffer(data)
+            ? data.toString()
+            : Array.isArray(data)
+                ? Buffer.concat(data).toString()
+                : Buffer.from(data).toString();
+
+        // 【安全】先解析 JSON
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(text);
+        } catch {
+            api.logger.warn(`WAP invalid JSON from ${clientId}`);
+            return;
+        }
+
+        // 【安全】验证消息结构
+        const msg = validateUpstreamMessage(parsed);
+        if (!msg) {
+            api.logger.warn(`WAP invalid message structure from ${clientId}`);
+            return;
+        }
+
+        if (msg.type === "heartbeat") {
+            client.ws.send(JSON.stringify({ type: "pong" }));
+            return;
+        }
+
+        if (msg.type === "message") {
+            api.logger.debug(
+                `WAP message from ${msg.data.sender}: ${msg.data.content.substring(0, 50)}`
+            );
+
+            // 使用 OpenClaw 的正确 API 处理入站消息
+            await processWapInboundMessage(api, client.accountId, msg.data, client.ws);
+        }
+    } catch (err) {
+        api.logger.error(`Failed to handle WAP message: ${err}`);
+    }
+}
+
+/**
+ * 处理 WAP 入站消息，使用 OpenClaw 的 dispatchReplyFromConfig
+ */
+async function processWapInboundMessage(
+    api: OpenClawPluginApi,
+    accountId: string,
+    msgData: WapMessageData,
+    ws: WebSocket
+) {
+    const core = api.runtime;
+    const cfg = api.config;
+
+    // 确定消息类型
+    const kind: "dm" | "group" = msgData.is_group ? "group" : "dm";
+    const chatType = kind === "dm" ? "direct" : "group";
+
+    // 解析路由
+    const route = core.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "wap",
+        accountId,
+        peer: {
+            kind,
+            id: msgData.talker,
+        },
+    });
+
+    const sessionKey = route.sessionKey;
+    const bodyText = msgData.content.trim();
+
+    if (!bodyText) return;
+
+    // 记录 channel activity
+    core.channel.activity.record({
+        channel: "wap",
+        accountId,
+        direction: "inbound",
+    });
+
+    // 构建 from 标签
+    const fromLabel = kind === "dm"
+        ? msgData.sender
+        : `${msgData.sender} in ${msgData.talker}`;
+
+    // 格式化入站消息
+    const body = core.channel.reply.formatInboundEnvelope({
+        channel: "WeChat",
+        from: fromLabel,
+        timestamp: msgData.timestamp,
+        body: bodyText + "\n\n" + wechatContextHint,
+        chatType,
+        sender: { name: msgData.sender, id: msgData.sender },
+    });
+
+    // 构建 context payload
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+        Body: body,
+        RawBody: bodyText,
+        CommandBody: bodyText,
+        From: kind === "dm" ? `wap:${msgData.sender}` : `wap:group:${msgData.talker}`,
+        To: msgData.talker,
+        SessionKey: sessionKey,
+        AccountId: route.accountId,
+        ChatType: chatType,
+        ConversationLabel: fromLabel,
+        GroupSubject: kind !== "dm" ? msgData.talker : undefined,
+        SenderName: msgData.sender,
+        SenderId: msgData.sender,
+        Provider: "wap" as const,
+        Surface: "wap" as const,
+        MessageSid: String(msgData.msg_id),
+        Timestamp: msgData.timestamp,
+        WasMentioned: undefined,
+        CommandAuthorized: true, // WAP 默认授权（已通过 token 认证）
+        OriginatingChannel: "wap" as const,
+        OriginatingTo: msgData.talker,
+    });
+
+    // 获取文本分块限制
+    const textLimit = core.channel.text.resolveTextChunkLimit(cfg, "wap", accountId, {
+        fallbackLimit: 4000,
+    });
+
+    // 创建回复分发器
+    const { dispatcher, replyOptions, markDispatchIdle } =
+        core.channel.reply.createReplyDispatcherWithTyping({
+            humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+            deliver: async (payload: { text?: string; mediaUrl?: string; mediaUrls?: string[] }) => {
+                const replyText = payload.text ?? "";
+                if (!replyText) return;
+
+                // 分块发送
+                const chunkMode = core.channel.text.resolveChunkMode(cfg, "wap", accountId);
+                const chunks = core.channel.text.chunkMarkdownTextWithMode(replyText, textLimit, chunkMode);
+
+                for (const chunk of chunks.length > 0 ? chunks : [replyText]) {
+                    if (!chunk) continue;
+
+                    // 通过 WebSocket 发送回复
+                    const command: WapSendTextCommand = {
+                        type: "send_text",
+                        data: {
+                            talker: msgData.talker,
+                            content: chunk,
+                        },
+                    };
+
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.send(JSON.stringify(command));
+                        api.logger.debug(`WAP reply sent to ${msgData.talker}: ${chunk.substring(0, 50)}...`);
+                    } else {
+                        api.logger.warn(`WAP WebSocket not open, cannot send reply to ${msgData.talker}`);
+                    }
+                }
+            },
+            onError: (err: unknown, info: { kind: string }) => {
+                api.logger.error(`WAP ${info.kind} reply failed: ${String(err)}`);
+            },
+        });
+
+    // 调用 OpenClaw 的核心回复处理
+    await core.channel.reply.dispatchReplyFromConfig({
+        ctx: ctxPayload,
+        cfg,
+        dispatcher,
+        replyOptions,
+    });
+
+    markDispatchIdle();
+}
+
+// 【安全】验证上行消息结构
+function validateUpstreamMessage(data: unknown): WapUpstreamMessage | null {
+    if (typeof data !== "object" || data === null) return null;
+
+    const obj = data as Record<string, unknown>;
+
+    if (obj.type === "heartbeat") {
+        return { type: "heartbeat" };
+    }
+
+    if (obj.type === "message") {
+        const msgData = obj.data;
+        if (typeof msgData !== "object" || msgData === null) return null;
+
+        const d = msgData as Record<string, unknown>;
+
+        // 验证必须字段
+        if (
+            typeof d.msg_id !== "number" ||
+            typeof d.talker !== "string" ||
+            typeof d.sender !== "string" ||
+            typeof d.content !== "string" ||
+            typeof d.timestamp !== "number" ||
+            typeof d.is_private !== "boolean" ||
+            typeof d.is_group !== "boolean"
+        ) {
+            return null;
+        }
+
+        return {
+            type: "message",
+            data: {
+                msg_id: d.msg_id,
+                msg_type: typeof d.msg_type === "number" ? d.msg_type : 0,
+                talker: d.talker,
+                sender: d.sender,
+                content: d.content,
+                timestamp: d.timestamp,
+                is_private: d.is_private,
+                is_group: d.is_group,
+            },
+        };
+    }
+
+    return null;
+}
+
+function handleDisconnect(clientId: string, api: OpenClawPluginApi) {
+    const client = clients.get(clientId);
+    clients.delete(clientId);
+    api.logger.info(
+        `WAP client disconnected: ${clientId}` +
+        (client ? ` (was connected for ${Date.now() - client.connectedAt.getTime()}ms)` : "")
+    );
+}
+
+// 发送消息到指定 accountId 的客户端（而非广播）
+export function sendToClient(command: WapSendTextCommand, accountId?: string): boolean {
+    let sent = false;
+    const targetAccountId = accountId ?? "default";
+
+    for (const [, client] of clients) {
+        if (client.accountId === targetAccountId && client.ws.readyState === WebSocket.OPEN) {
+            client.ws.send(JSON.stringify(command));
+            sent = true;
+            break; // 只发送给第一个匹配的客户端
+        }
+    }
+    return sent;
+}
+
+// 获取当前连接的客户端数量
+export function getClientCount(): number {
+    return clients.size;
+}
+
+// 获取客户端状态（用于调试）
+export function getClientStats(): Array<{ clientId: string; accountId: string; ip: string; connectedAt: Date }> {
+    return Array.from(clients.entries()).map(([clientId, info]) => ({
+        clientId,
+        accountId: info.accountId,
+        ip: info.ip,
+        connectedAt: info.connectedAt,
+    }));
+}