npm package: @fengtc1182482/wecom-openclaw-plugin-multi-bot-min
Description: OpenClaw WeCom (企业微信) channel plugin - minimal multi-bot edition derived from the official implementation
Author: fengtc
Latest version: 1.0.12-multi-bot-min

# 🤖 WeCom OpenClaw Plugin（多 Bot 最小改造版）

> **说明：本仓库基于官方仓库 `WecomTeam/wecom-openclaw-plugin` 修改而来。**
>
> 本版本的目标是：在尽量少改原有代码结构的前提下，为企业微信 OpenClaw 插件补上 **多 Bot 绑定 / 多账户运行** 能力。
>
> 因此，下面文档中的“多 Bot 功能”“示例配置”“验证步骤”**对应的是本仓库当前代码**，
> **不是官方已发布 npm 包 `@wecom/wecom-openclaw-plugin` 默认就具备的能力。**

---

## 一、来源说明

### 官方来源
- 官方仓库：`https://github.com/WecomTeam/wecom-openclaw-plugin`
- 企业微信 AI Bot 官方文档：`https://open.work.weixin.qq.com/help?doc_id=21657`

### 本仓库定位
本仓库是：
- **参考官方仓库代码与文档**
- **基于官方实现修改出的多 Bot 版本**
- 当前属于：**最小可用改造版 / 可评审版**

也就是说：
- 单 Bot 基础能力来自官方实现思路
- 多 Bot 支持是本仓库新增的改造能力

---

## 二、这个版本解决了什么问题

官方版本当前主要是**单账户/单 Bot**实现，典型特征包括：

- 配置只有一套：
  - `channels.wecom.botId`
  - `channels.wecom.secret`
- 账户解析默认只有一个 `DEFAULT_ACCOUNT_ID`
- 多个 Bot 不能同时独立运行

本仓库在此基础上补上了：

- 多账户配置结构
- 默认账户选择
- 按账户隔离的群策略
- 默认发送账户按 `defaultAccountId` 回退
- MCP 默认账户路径修正

---

## 三、当前版本的能力范围

### 已支持
- 多 Bot / 多账户配置
- 旧单 Bot 配置兼容
- 账户级别的 `dmPolicy / allowFrom`
- 账户级别的 `groupPolicy / groupAllowFrom / groups`
- 默认账户 `defaultAccountId`
- build 可通过

### 当前限制
- `openclaw channels add` 交互式 onboarding 仍主要服务于**默认账户**
- 多 Bot 配置目前以**手工编辑配置文件**为主
- 这是“最小可用版”，不是完全产品化版本

---

## 四、安装方式

本仓库当前支持两种使用方式：

### 方式 A：源码构建使用（当前最稳妥）

```bash
git clone git@github.com:fengtc/wecom-openclaw-plugin-multi-bot-min.git
cd wecom-openclaw-plugin-multi-bot-min
npm install
npm run build
```

构建成功后会生成：

- `dist/index.cjs.js`
- `dist/index.esm.js`
- `dist/index.d.ts`

然后按你当前 OpenClaw 环境的**本地插件方式**接入。

---

### 方式 B：按 npm 包方式安装（发布后可用）

如果后续已发布到 npm，则可以这样安装：

```bash
openclaw plugins install @fengtc1182482/wecom-openclaw-plugin-multi-bot-min
```

> 注意：只有当 npm 上已经成功发布 `@fengtc1182482/wecom-openclaw-plugin-multi-bot-min` 后，这条命令才可直接使用。
>
> 它不是官方包 `@wecom/wecom-openclaw-plugin`，而是本仓库对应的派生多 Bot 版本。

---

## 五、配置方式

### 1. 兼容旧版单 Bot 配置

以下配置仍然兼容：

```json
{
  "channels": {
    "wecom": {
      "botId": "YOUR_BOT_ID",
      "secret": "YOUR_BOT_SECRET",
      "enabled": true
    }
  }
}
```

这会被视为默认账户。

---

### 2. 多 Bot 配置（本仓库新增能力）

```json
{
  "channels": {
    "wecom": {
      "defaultAccountId": "botA",
      "accounts": {
        "botA": {
          "name": "企微机器人A",
          "enabled": true,
          "botId": "YOUR_BOT_A_ID",
          "secret": "YOUR_BOT_A_SECRET",
          "dmPolicy": "open",
          "allowFrom": ["*"],
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["GROUP_ID_A"]
        },
        "botB": {
          "name": "企微机器人B",
          "enabled": true,
          "botId": "YOUR_BOT_B_ID",
          "secret": "YOUR_BOT_B_SECRET",
          "dmPolicy": "allowlist",
          "allowFrom": ["USER_ID_B_1"],
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["GROUP_ID_B"]
        }
      }
    }
  }
}
```

### 配置说明
- `defaultAccountId`：默认账户 ID
- `accounts.<accountId>`：每个 Bot 的独立配置
- `dmPolicy / allowFrom`：私聊控制
- `groupPolicy / groupAllowFrom / groups`：群聊控制

---

## 六、推荐阅读文件

### 说明文档
- `MULTI_BOT_MINIMAL.md`：最小改造说明
- `CHANGELOG_MULTI_BOT.md`：多 Bot 改造变更记录
- `PR_SUMMARY.md`：PR 说明草稿（中文）
- `NPM_PUBLISH.md`：npm 发布与安装说明

### 示例与验证
- `examples/multi-bot.config.example.json`：双 Bot 配置示例
- `MULTI_BOT_VERIFICATION.md`：验证清单

---

## 七、验证步骤

建议按以下顺序验证：

1. 配置两个 WeCom Bot
2. 重启 OpenClaw Gateway
3. 确认两个 Bot 都完成 WebSocket 认证
4. 验证 botA / botB 私聊策略隔离
5. 验证 botA / botB 群策略隔离
6. 验证默认发送路径遵循 `defaultAccountId`
7. 验证 MCP 路径也遵循默认账户

更完整的验证步骤见：
- `MULTI_BOT_VERIFICATION.md`

---

## 八、适合合并到上游的定位

本分支是一个：
- **最小功能可用的多 Bot 改造版**
- **优先保证兼容旧配置**
- **优先修正关键运行路径**

本版本暂不追求：
- 完整多账户 onboarding UX
- 全套产品化管理命令
- 全量自动化测试覆盖

---

## 九、许可证

沿用原项目许可证。具体请参考上游官方仓库中的 License 说明。