@sunnoy/wecom 1.3.0 → 1.4.1

package/README.md

@@ -61,6 +61,46 @@ npm test
 
 运行单元测试（使用 Node.js 内置测试运行器）。
 
+### 运行真实 E2E 测试（远程 OpenClaw）
+
+本项目新增了真实联调 e2e 用例（`tests/e2e/remote-wecom.e2e.test.js`），会对真实 `/webhooks/wecom` 做加密请求、验证握手、发送消息并轮询 stream 直到结束。
+
+1. 使用你当前环境的 `ssh ali-ai` 一键执行（自动读取远程 `~/.openclaw/openclaw.json`，并建立本地隧道）：
+
+```bash
+npm run test:e2e:ali-ai
+```
+
+2. 或者手动指定环境变量执行：
+
+```bash
+E2E_WECOM_BASE_URL=http://127.0.0.1:28789 \
+E2E_WECOM_TOKEN=xxx \
+E2E_WECOM_ENCODING_AES_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
+E2E_WECOM_WEBHOOK_PATH=/webhooks/wecom \
+npm run test:e2e
+```
+
+可选变量：
+- `E2E_WECOM_TEST_USER`（默认 `wecom-e2e-user`）
+- `E2E_WECOM_TEST_COMMAND`（默认 `/status`）
+- `E2E_WECOM_POLL_INTERVAL_MS`（默认 `1200`）
+- `E2E_WECOM_STREAM_TIMEOUT_MS`（默认 `90000`）
+- `E2E_WECOM_ENABLE_BROWSER_CASE`（默认 `1`，设置 `0` 可跳过浏览器场景）
+- `E2E_WECOM_BROWSER_TIMEOUT_MS`（默认 `180000`）
+- `E2E_WECOM_BROWSER_REQUIRE_IMAGE`（默认 `0`，设置 `1` 强制断言 `msg_item` 图片出站）
+- `E2E_WECOM_BROWSER_PROMPT`（浏览器场景自定义提示词）
+- `E2E_WECOM_BROWSER_BING_PDF_PROMPT`（Bing + 保存 PDF 场景提示词）
+- `E2E_WECOM_ENABLE_BROWSER_BING_PDF_CASE`（默认 `1`）
+- `E2E_BROWSER_PREPARE_MODE`（`check`/`install`/`off`，默认 `check`）
+- `E2E_BROWSER_REQUIRE_READY`（默认 `0`，设置 `1` 时浏览器环境不满足则中止）
+- `E2E_COLLECT_BROWSER_PDF`（默认 `1`，执行后自动收集远程 sandbox 中的 PDF）
+- `E2E_PDF_OUTPUT_DIR`（默认 `tests/e2e/artifacts`）
+
+> 说明：`test:e2e:ali-ai` 会消耗远程实例的真实 LLM token，并覆盖多种真实入站/出站场景（含浏览器相关场景）。
+> 说明：执行 `test:e2e:ali-ai` 会先做 browser sandbox 准备检查（`prepare-browser-sandbox.sh`），测试后会尝试抓取 PDF 产物（`collect-browser-pdf.sh`）供用户下载。
+> 说明：当 browser sandbox 未就绪（缺浏览器二进制或缺 `browser` skill）时，Bing+PDF case 会自动跳过，并在准备检查输出中标记 `STATUS=MISSING`。
+
 ## 配置
 
 在 OpenClaw 配置文件（`~/.openclaw/openclaw.json`）中添加：
@@ -264,8 +304,10 @@ Webhook Bot 用于向群聊发送通知消息。
 ### 工作原理
 
 1. 企业微信消息到达后，插件生成确定性的 `agentId`：
-   - **私聊**: `wecom-dm-<userId>`
-   - **群聊**: `wecom-group-<chatId>`
+   - **单账号私聊**: `wecom-dm-<userId>`
+   - **单账号群聊**: `wecom-group-<chatId>`
+   - **多账号私聊**: `wecom-<accountId>-dm-<userId>`
+   - **多账号群聊**: `wecom-<accountId>-group-<chatId>`
 2. OpenClaw 自动创建/复用对应的 Agent 工作区
 3. 每个用户/群聊拥有独立的对话历史和上下文
 4. **管理员用户**跳过动态路由，直接使用主 Agent
@@ -314,6 +356,60 @@ Webhook Bot 用于向群聊发送通知消息。
 }
 ```
 
+### 多账号配置（Multi-Bot）
+
+支持在一个 OpenClaw 实例中接入多个企业微信机器人，每个机器人独立配置 Token、Agent 凭证、Webhook 等，互不干扰。
+
+> 💡 **典型场景**：一个企业微信里创建多个 AI 机器人（如「客服助手」「技术支持」），各自对应不同的 Agent 和会话空间。
+
+**配置方式：** 将 `channels.wecom` 下的值改为字典结构，每个 key 是账号 ID（如 `bot1`、`bot2`），value 包含该账号的完整配置：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "bot1": {
+        "token": "Bot1 的 Token",
+        "encodingAesKey": "Bot1 的 EncodingAESKey",
+        "adminUsers": ["admin1"],
+        "agent": {
+          "corpId": "企业 CorpID",
+          "corpSecret": "Bot1 应用 Secret",
+          "agentId": 1000001,
+          "token": "Bot1 回调 Token",
+          "encodingAesKey": "Bot1 回调 EncodingAESKey"
+        },
+        "webhooks": {
+          "ops-group": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
+        }
+      },
+      "bot2": {
+        "token": "Bot2 的 Token",
+        "encodingAesKey": "Bot2 的 EncodingAESKey",
+        "agent": {
+          "corpId": "企业 CorpID",
+          "corpSecret": "Bot2 应用 Secret",
+          "agentId": 1000002
+        }
+      }
+    }
+  }
+}
+```
+
+**说明：**
+
+| 项目 | 说明 |
+|------|------|
+| 账号 ID | 字典的 key，如 `bot1`、`bot2`，仅支持小写字母、数字、`-`、`_` |
+| 完全兼容 | 旧的单账号配置（`token` 直接写在 `wecom` 下）自动识别为 `default` 账号，无需修改 |
+| Webhook 路径 | 自动按账号分配：`/webhooks/wecom/bot1`、`/webhooks/wecom/bot2` |
+| Agent 回调路径 | 自动按账号分配：`/webhooks/app/bot1`、`/webhooks/app/bot2` |
+| 动态 Agent ID | 按账号隔离：`wecom-bot1-dm-{userId}`、`wecom-bot2-group-{chatId}` |
+| 冲突检测 | 启动时自动检测重复的 Token 或 Agent ID，避免消息路由错乱 |
+
+> ⚠️ **注意**：多账号模式下，每个账号的 Webhook URL 需要在企业微信后台分别配置对应的路径（如 `/webhooks/wecom/bot1`）。
+
 ### 工作区模板
 
 可以为动态创建的 Agent 工作区预置初始化文件。当新 Agent 首次创建时，会自动从模板目录复制 bootstrap 文件。
@@ -559,6 +655,36 @@ openclaw send "party:2" "全体员工通知"
 
 3. **检查是否有多余空格/换行**：确保密钥字符串前后没有空格或换行符
 
+### Q: 日志报错 reply delivery failed ... 60020 not allow to access from your ip 怎么办？
+
+**A:** 这是企业微信对「自建应用 API 主动发送消息」的安全限制。错误码 60020 表示：当前服务器出口公网 IP 未加入企业微信应用的可信 IP 白名单。
+
+**典型日志示例：**
+
+```bash
+[wecom] [agent-inbound] reply delivery failed {"error":"agent send text failed: 60020 not allow to access from your ip, ... from ip: xx.xx.xx.xx"}
+```
+
+
+
+**原因说明**
+
+当插件使用 Agent API 回退（或 Agent 模式主动推送）发送消息时，会调用企业微信开放接口（如 qyapi.weixin.qq.com）。
+如果企业微信后台为该应用启用了 企业可信IP / 接口可信IP 校验，而当前服务器出口公网 IP 不在白名单内，企业微信会拒绝请求并返回 60020。
+
+**解决方法**
+
+1. 登录企业微信管理后台
+
+2. 进入对应的 自建应用 详情页
+
+3. 找到 企业可信IP 配置项
+
+4. 将服务器公网出口 IP 加入白名单
+   - 建议以错误日志中的 from ip 为准（你的服务器公网ip）
+
+5. 保存配置后重试发送消息
+
 ## 项目结构
 
 ```
@@ -592,6 +718,12 @@ openclaw-plugin-wecom/
 │   ├── webhook-targets.js   # Webhook 目标管理
 │   └── workspace-template.js # 工作区模板
 ├── tests/                   # 测试目录
+│   ├── e2e/
+│   │   ├── remote-wecom.e2e.test.js # 真实远程 E2E（加密请求 + stream 轮询）
+│   │   └── run-ali-ai.sh    # ssh ali-ai 一键联调脚本
+│   │   ├── prepare-browser-sandbox.sh # browser sandbox 环境检查/准备
+│   │   └── collect-browser-pdf.sh # 收集并下载 PDF 测试产物
+│   ├── outbound.test.js     # 出站投递回退逻辑测试
 │   ├── target.test.js       # 目标解析器测试
 │   └── xml-parser.test.js   # XML 解析器测试
 ├── README.md                # 本文档
@@ -608,3 +740,248 @@ openclaw-plugin-wecom/
 ## 开源协议
 
 本项目采用 [ISC License](./LICENSE) 协议。
+
+## 配置示例参考
+
+以下是一个生产环境的脱敏配置示例，供参考：
+
+```json
+{
+  "meta": {
+    "lastTouchedVersion": "2026.2.25",
+    "lastTouchedAt": "2026-02-28T03:14:11.564Z"
+  },
+  "wizard": {
+    "lastRunAt": "2026-02-26T09:29:04.028Z",
+    "lastRunVersion": "2026.2.25",
+    "lastRunCommand": "onboard",
+    "lastRunMode": "local"
+  },
+  "logging": {
+    "level": "info",
+    "consoleLevel": "debug",
+    "consoleStyle": "pretty"
+  },
+  "models": {
+    "mode": "merge",
+    "providers": {
+      "bailian": {
+        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
+        "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxx",
+        "api": "openai-completions",
+        "models": [
+          { "id": "qwen3.5-plus", "name": "qwen3.5-plus", "reasoning": false, "input": ["text", "image"], "contextWindow": 1000000, "maxTokens": 65536 },
+          { "id": "MiniMax-M2.5", "name": "MiniMax-M2.5", "reasoning": false, "input": ["text"], "contextWindow": 1000000, "maxTokens": 65536 },
+          { "id": "glm-5", "name": "glm-5", "reasoning": false, "input": ["text"], "contextWindow": 202752, "maxTokens": 16384 },
+          { "id": "glm-4.7", "name": "glm-4.7", "reasoning": false, "input": ["text"], "contextWindow": 202752, "maxTokens": 16384 },
+          { "id": "kimi-k2.5", "name": "kimi-k2.5", "reasoning": false, "input": ["text", "image"], "contextWindow": 262144, "maxTokens": 32768 }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": { "primary": "bailian/kimi-k2.5" },
+      "models": {
+        "bailian/qwen3.5-plus": {},
+        "bailian/MiniMax-M2.5": {},
+        "bailian/glm-5": {},
+        "bailian/glm-4.7": {},
+        "bailian/kimi-k2.5": {}
+      },
+      "workspace": "/path/to/workspace",
+      "userTimezone": "Asia/Shanghai",
+      "timeFormat": "24",
+      "compaction": {
+        "mode": "safeguard",
+        "reserveTokensFloor": 20000,
+        "memoryFlush": {
+          "enabled": true,
+          "softThresholdTokens": 4000
+        }
+      },
+      "thinkingDefault": "medium",
+      "verboseDefault": "on",
+      "heartbeat": {
+        "every": "10m",
+        "target": "last",
+        "directPolicy": "allow"
+      },
+      "sandbox": {
+        "mode": "all",
+        "workspaceAccess": "rw",
+        "scope": "agent",
+        "docker": {
+          "image": "your-registry.com/openclaw-agent:v2026.x.x",
+          "readOnlyRoot": false,
+          "network": "bridge",
+          "extraHosts": [
+            "your-domain.internal:xxx.xxx.xxx.xxx"
+          ],
+          "binds": [
+            "/path/to/skills:/workspace/skills:ro"
+          ],
+          "dangerouslyAllowReservedContainerTargets": true,
+          "dangerouslyAllowExternalBindSources": true
+        },
+        "prune": {
+          "idleHours": 87600,
+          "maxAgeDays": 3650
+        }
+      }
+    },
+    "list": [
+      { "id": "main" },
+      { "id": "wecom-dm-xxxxxx" }
+    ]
+  },
+  "commands": {
+    "native": "auto",
+    "nativeSkills": "auto",
+    "restart": true,
+    "ownerDisplay": "raw"
+  },
+  "session": {
+    "dmScope": "per-channel-peer"
+  },
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "boot-md": { "enabled": true },
+        "command-logger": { "enabled": true },
+        "session-memory": { "enabled": true },
+        "bootstrap-extra-files": { "enabled": true }
+      }
+    }
+  },
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "encodingAesKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      "commands": {
+        "enabled": true,
+        "allowlist": ["/help", "/commands", "/status", "/context", "/whoami", "/new", "/compact", "/stop", "/reset", "/usage", "/think", "/thinking", "/t", "/verbose", "/v", "/reasoning", "/reason", "/model", "/models", "/skill"]
+      },
+      "dynamicAgents": { "enabled": true },
+      "dm": { "createAgentOnFirstMessage": true },
+      "groupChat": { "enabled": true, "requireMention": true },
+      "adminUsers": ["admin_userid"],
+      "workspaceTemplate": "/path/to/workspace-template",
+      "agent": {
+        "corpId": "wwxxxxxxxxxxxxxxxx",
+        "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "agentId": 1000002,
+        "token": "xxxxxxxxxxxxxxx",
+        "encodingAesKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  },
+  "gateway": {
+    "port": 18789,
+    "mode": "local",
+    "bind": "lan",
+    "controlUi": {
+      "dangerouslyAllowHostHeaderOriginFallback": true,
+      "allowInsecureAuth": true
+    },
+    "auth": {
+      "mode": "token",
+      "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+    },
+    "tailscale": {
+      "mode": "off",
+      "resetOnExit": false
+    }
+  },
+  "skills": {
+    "allowBundled": ["_none_"],
+    "load": {
+      "extraDirs": ["/path/to/skills"],
+      "watch": true,
+      "watchDebounceMs": 250
+    },
+    "install": { "nodeManager": "npm" }
+  },
+  "plugins": {
+    "allow": ["wecom"],
+    "entries": { "wecom": { "enabled": true } }
+  }
+}
+```
+
+## 自定义 Skills 配合沙箱使用实践
+
+OpenClaw 支持自定义 Skills 并通过沙箱（Docker）隔离执行，以下是生产环境的实践配置：
+
+
+### 沙箱配置关键点
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "all",
+        "workspaceAccess": "rw",
+        "scope": "agent",
+        "docker": {
+          "image": "your-registry.com/openclaw-agent:v2026.x.x",
+          "readOnlyRoot": false,
+          "network": "bridge",
+          "extraHosts": [
+            "your-domain.internal:xxx.xxx.xxx.xxx"
+          ],
+          "binds": [
+            "/path/to/skills:/workspace/skills:ro"
+          ],
+          "dangerouslyAllowReservedContainerTargets": true,
+          "dangerouslyAllowExternalBindSources": true
+        },
+        "prune": {
+          "idleHours": 87600,
+          "maxAgeDays": 3650
+        }
+      }
+    }
+  },
+  "skills": {
+    "allowBundled": ["_none_"],
+    "load": {
+      "extraDirs": ["/path/to/skills"],
+      "watch": true,
+      "watchDebounceMs": 250
+    }
+  }
+}
+```
+
+### 配置说明
+
+| 配置项 | 说明 |
+|--------|------|
+| `sandbox.mode` | 沙箱模式：`all` 所有操作都走沙箱 |
+| `sandbox.workspaceAccess` | 工作区访问权限：`rw` 读写 |
+| `sandbox.scope` | 沙箱作用域：`agent` 每个 Agent 独立沙箱 |
+| `sandbox.docker.image` | 沙箱使用的 Docker 镜像 |
+| `sandbox.docker.readOnlyRoot` | 是否只读根文件系统 |
+| `sandbox.docker.network` | 网络模式：`bridge` 桥接网络 |
+| `sandbox.docker.binds` | 挂载目录：将宿主机 skills 目录映射到沙箱内 `/workspace/skills`（只读） |
+| `sandbox.docker.extraHosts` | 添加额外 hosts，解决内网服务域名解析 |
+| `sandbox.docker.dangerouslyAllowReservedContainerTargets` | 允许容器访问保留目标 |
+| `sandbox.docker.dangerouslyAllowExternalBindSources` | 允许外部绑定源 |
+| `sandbox.prune.idleHours` | 空闲容器清理时间（小时） |
+| `sandbox.prune.maxAgeDays` | 容器最大存活天数 |
+| `skills.allowBundled` | 允许的内置 skills（`["_none_"]` 表示禁用所有内置） |
+| `skills.load.extraDirs` | 自定义 skills 加载目录 |
+| `skills.load.watch` | 启用热加载，修改 skill 无需重启 |
+| `skills.load.watchDebounceMs` | 热加载防抖时间（毫秒） |
+
+### 使用流程
+
+1. 在宿主机创建自定义 skill 目录
+2. 配置 `binds` 将目录映射到沙箱
+3. 在 `skills.load.extraDirs` 指定加载路径
+4. Agent 在沙箱中可通过 `/workspace/skills` 访问自定义 skills
+5. 使用 `/skill` 命令查看和管理 skills

package/dynamic-agent.js

@@ -8,25 +8,39 @@
 /**
  * Build a deterministic agent id for dm/group contexts.
  *
+ * When running in multi-account mode the accountId is embedded as a
+ * namespace segment so each account's conversations stay isolated:
+ *   default  → wecom-dm-{peerId}         (backward compatible)
+ *   "sales"  → wecom-sales-dm-{peerId}
+ *
  * @param {string} chatType - "dm" or "group"
  * @param {string} peerId - user id or group id
+ * @param {string} [accountId] - optional account namespace ("default" is omitted)
  * @returns {string} agentId
  */
-export function generateAgentId(chatType, peerId) {
+export function generateAgentId(chatType, peerId, accountId) {
   const sanitizedId = String(peerId)
     .toLowerCase()
     .replace(/[^a-z0-9_-]/g, "_");
+  // Only embed the account prefix for non-default accounts so existing
+  // single-account deployments keep identical agent ids (zero breaking change).
+  const ns = accountId && accountId !== "default" ? `${accountId}-` : "";
   if (chatType === "group") {
-    return `wecom-group-${sanitizedId}`;
+    return `wecom-${ns}group-${sanitizedId}`;
   }
-  return `wecom-dm-${sanitizedId}`;
+  return `wecom-${ns}dm-${sanitizedId}`;
 }
 
 /**
  * Resolve runtime dynamic-agent settings from config.
+ *
+ * Accepts either the full openclaw config (legacy) or a per-account wecom
+ * config block directly (multi-account).  Detection: if the object has
+ * `channels.wecom`, unwrap it; otherwise treat the object itself as the
+ * wecom account config.
  */
 export function getDynamicAgentConfig(config) {
-  const wecom = config?.channels?.wecom || {};
+  const wecom = config?.channels?.wecom ?? config ?? {};
   return {
     enabled: wecom.dynamicAgents?.enabled !== false,
     dmCreateAgent: wecom.dm?.createAgentOnFirstMessage !== false,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "1.3.0",
+    "version": "1.4.1",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -23,7 +23,10 @@
         "openclaw": "*"
     },
     "scripts": {
-        "test": "node --test tests/*.test.js"
+        "test": "npm run test:unit",
+        "test:unit": "node --test tests/*.test.js",
+        "test:e2e": "node --test tests/e2e/*.e2e.test.js",
+        "test:e2e:ali-ai": "bash tests/e2e/run-ali-ai.sh"
     },
     "openclaw": {
         "extensions": [