openclaw-plugin-wecom 1.0.0 → 1.1.0

package/README.md

@@ -1,148 +1,132 @@
 # OpenClaw WeCom (Enterprise WeChat) AI Bot Plugin
 
-[简体中文](https://github.com/sunnoy/openclaw-plugin-wecom/blob/main/README_ZH.md) | [English](https://github.com/sunnoy/openclaw-plugin-wecom/blob/main/README.md)
+[English](https://github.com/sunnoy/openclaw-plugin-wecom/blob/main/README.md) | [简体中文](https://github.com/sunnoy/openclaw-plugin-wecom/blob/main/README_ZH.md)
 
-`openclaw-plugin-wecom` is a WeCom (Enterprise WeChat) integration plugin developed for the [OpenClaw](https://github.com/openclaw/openclaw) framework. It enables seamless integration of powerful AI capabilities into WeCom with advanced features.
+`openclaw-plugin-wecom` is an Enterprise WeChat (WeCom) integration plugin developed for the [OpenClaw](https://github.com/openclaw/openclaw) framework. It enables seamless AI capabilities in Enterprise WeChat with advanced features.
 
 ## ✨ Key Features
 
-- 🌊 **Streaming Output**: Smooth typewriter-style responses using WeCom's latest AI bot streaming mechanism.
-- 🤖 **Dynamic Agent Management**: Automatically creates independent Agents per user/group chat with isolated workspaces and conversation contexts.
-- 👥 **Group Chat Integration**: Full support for group messages with @mention triggering.
-- 🛠️ **Command Support**: Built-in commands (`/new`, `/status`, `/help`, `/compact`) with configurable whitelist.
-- 🔒 **Security**: Complete support for WeCom message encryption/decryption and sender verification.
-- ⚡ **Async Processing**: High-performance async architecture ensures gateway responsiveness during AI inference.
+- 🌊 **Streaming Output**: Built on WeCom's latest AI bot streaming mechanism for smooth typewriter-style responses.
+- 🤖 **Dynamic Agent Management**: Automatically creates isolated agents per direct message user or group chat, with independent workspaces and conversation contexts.
+- 👥 **Deep Group Chat Integration**: Supports group message parsing with @mention triggering.
+- 🖼️ **Image Support**: Automatic base64 encoding and sending of local images (screenshots, generated images) without requiring additional configuration.
+- 🛠️ **Command Enhancement**: Built-in commands (e.g., `/new` for new sessions, `/status` for status) with allowlist configuration.
+- 🔒 **Security & Authentication**: Full support for WeCom message encryption/decryption, URL verification, and sender validation.
+- ⚡ **High-Performance Async Processing**: Asynchronous message architecture ensures responsive gateway even during long AI inference.
 
-## 🚀 Quick Start
+## 📋 Prerequisites
 
-### Option 1: Docker Deployment (Recommended)
+- [OpenClaw](https://github.com/openclaw/openclaw) installed (version 2026.1.30+)
+- Enterprise WeChat admin access to create intelligent robot applications
+- Server address accessible from Enterprise WeChat (HTTP/HTTPS)
 
-This repository provides a complete Docker deployment solution that **deploys OpenClaw + WeCom plugin in one step**, with automated installation and configuration.
+## 🚀 Installation
 
-```bash
-# 1. Clone the repository
-git clone https://github.com/sunnoy/openclaw-plugin-wecom.git
-cd openclaw-plugin-wecom/deploy
-
-# 2. Copy environment configuration
-cp .env.example .env
-
-# 3. Edit .env file with your settings
-vim .env
-
-# 4. Run deployment script
-./deploy.sh
-```
-
-The deployment script automatically:
-- Creates data directories and sets permissions
-- Generates configuration files
-- Starts Docker containers
-- Installs the WeCom plugin
-- Configures and restarts services
-
-#### 🌟 Deployment Highlights
-
-**Custom Data Directory & Agent Workspace Paths**
-
-The core advantage of this deployment is unified data storage in a custom path, effectively utilizing data disks:
-
-```bash
-# .env configuration example
-OPENCLAW_DATA_DIR=/data/openclaw    # Custom data directory
-```
-
-- **OpenClaw State Directory**: `/data/openclaw/`
-- **Dynamic Agent Workspace**: `/data/openclaw/.openclaw/` 
-- **Plugin Directory**: `/data/openclaw/extensions/`
-- **Canvas Data**: `/data/openclaw/canvas/`
-
-Benefits:
-- ✅ All Agent workspace data stored on data disk, avoiding system disk usage
-- ✅ Independent Agent files for each user/group managed under unified path
-- ✅ Easy backup, migration, and expansion
-- ✅ Enterprise-ready deployment with independently mountable data disks
-
-### Option 2: Manual Plugin Installation
-
-Install in an existing OpenClaw environment:
+### Method 1: Using OpenClaw CLI (Recommended)
 
 ```bash
 openclaw plugins install openclaw-plugin-wecom
 ```
 
-Or via npm:
+### Method 2: Using npm
 
 ```bash
 npm install openclaw-plugin-wecom
 ```
 
-Then add to your OpenClaw configuration:
+## ⚙️ Configuration
+
+Add to your OpenClaw configuration file (`~/.openclaw/openclaw.json`):
 
 ```json
 {
   "plugins": {
+    "deny": ["wecom"],
     "entries": {
-      "wecom": { "enabled": true }
+      "openclaw-plugin-wecom": {
+        "enabled": true
+      }
     }
   },
   "channels": {
     "wecom": {
       "enabled": true,
       "token": "Your Token",
-      "encodingAesKey": "Your EncodingAESKey"
+      "encodingAesKey": "Your EncodingAESKey",
+      "commands": {
+        "enabled": true,
+        "allowlist": ["/new", "/status", "/help", "/compact"]
+      }
     }
   }
 }
 ```
 
-### WeCom Backend Setup
+### Configuration Options
 
-1. Create an "Intelligent Bot" in WeCom Admin Console.
-2. Set the "Receive Message" URL to your service address (e.g., `https://your-domain.com/webhooks/wecom`).
-3. Enter the corresponding Token and EncodingAESKey.
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `plugins.deny` | array | Recommended | Add `["wecom"]` to prevent OpenClaw from auto-enabling built-in channel |
+| `plugins.entries.openclaw-plugin-wecom.enabled` | boolean | Yes | Enable the plugin |
+| `channels.wecom.token` | string | Yes | WeCom bot Token |
+| `channels.wecom.encodingAesKey` | string | Yes | WeCom message encryption key (43 chars) |
+| `channels.wecom.commands.allowlist` | array | No | Command allowlist |
 
-## 📂 Project Structure
+## 🔌 Enterprise WeChat Configuration
 
-```
-openclaw-plugin-wecom/
-├── deploy/                      # Deployment files
-│   ├── deploy.sh               # One-click deployment script
-│   ├── docker-compose.yml      # Docker Compose configuration
-│   ├── .env.example            # Environment variables template
-│   ├── openclaw.json.base      # Base configuration template
-│   └── openclaw.json.template  # Full configuration template
-├── Dockerfile                   # OpenClaw image build file
-├── local.sh                     # Local image build script
-├── index.js                     # Plugin entry point
-├── webhook.js                   # WeCom HTTP communication
-├── dynamic-agent.js             # Dynamic Agent routing
-├── stream-manager.js            # Streaming response management
-├── crypto.js                    # WeCom encryption
-└── client.js                    # Client logic
-```
+1. Log in to [Enterprise WeChat Admin Console](https://work.weixin.qq.com/)
+2. Navigate to "Application Management" → "Applications" → "Create Application" → Select "Intelligent Robot"
+3. Configure "Receive Messages":
+   - **URL**: `https://your-domain.com/webhooks/wecom`
+   - **Token**: Match `channels.wecom.token`
+   - **EncodingAESKey**: Match `channels.wecom.encodingAesKey`
+4. Save and enable message receiving
 
 ## 🤖 Dynamic Agent Routing
 
-The plugin implements per-user/per-group isolation:
+The plugin implements per-user/per-group agent isolation:
 
-1. On message arrival, generates a deterministic `agentId`:
-   - DM: `wecom-dm-<userId>`
-   - Group: `wecom-group-<chatId>`
-2. OpenClaw automatically creates/reuses the corresponding Agent workspace.
+### How It Works
 
-### Configuration Options
+1. When a WeCom message arrives, the plugin generates a deterministic `agentId`:
+   - **Direct Messages**: `wecom-dm-<userId>`
+   - **Group Chats**: `wecom-group-<chatId>`
+2. OpenClaw automatically creates/reuses the corresponding agent workspace
+3. Each user/group has independent conversation history and context
 
-Under `channels.wecom`:
+### Advanced Configuration
+
+Configure under `channels.wecom`:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dynamicAgents": {
+        "enabled": true
+      },
+      "dm": {
+        "createAgentOnFirstMessage": true
+      },
+      "groupChat": {
+        "enabled": true,
+        "requireMention": true
+      }
+    }
+  }
+}
+```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `dynamicAgents.enabled` | boolean | `true` | Enable dynamic Agents |
-| `dm.createAgentOnFirstMessage` | boolean | `true` | Use dynamic Agent for DMs |
-| `groupChat.enabled` | boolean | `true` | Enable group chat handling |
+| `dynamicAgents.enabled` | boolean | `true` | Enable dynamic agents |
+| `dm.createAgentOnFirstMessage` | boolean | `true` | Use dynamic agents for DMs |
+| `groupChat.enabled` | boolean | `true` | Enable group chat processing |
 | `groupChat.requireMention` | boolean | `true` | Require @mention in groups |
 
-To route all messages to the default Agent:
+### Disable Dynamic Agents
+
+To route all messages to the default agent:
 
 ```json
 {
@@ -154,11 +138,9 @@ To route all messages to the default Agent:
 }
 ```
 
-## 🛠️ Command Whitelist
-
-To prevent regular users from executing sensitive Gateway management commands via WeCom messages, this plugin supports a **command whitelist** mechanism. Only commands in the whitelist will be executed; others are ignored.
+## 🛠️ Command Allowlist
 
-> 💡 **Note**: This configuration is already included in `deploy/openclaw.json.template` and takes effect automatically upon deployment.
+Prevent regular users from executing sensitive Gateway management commands through WeCom messages.
 
 ```json
 {
@@ -173,19 +155,143 @@ To prevent regular users from executing sensitive Gateway management commands vi
 }
 ```
 
-| Command | Description | Security Level |
-|---------|-------------|----------------|
-| `/new` | Reset conversation, start fresh | ✅ User-level |
-| `/compact` | Compress conversation context | ✅ User-level |
+### Recommended Allowlist Commands
+
+| Command | Description | Safety Level |
+|---------|-------------|--------------|
+| `/new` | Reset conversation, start new session | ✅ User-level |
+| `/compact` | Compress current session context | ✅ User-level |
 | `/help` | Show help information | ✅ User-level |
 | `/status` | Show Agent status | ✅ User-level |
 
-> ⚠️ **Security Note**: Do not add `/gateway`, `/plugins`, or other management commands to the whitelist to prevent regular users from gaining Gateway instance admin privileges.
+> ⚠️ **Security Note**: Do not add `/gateway`, `/plugins`, or other management commands to the allowlist to prevent regular users from gaining Gateway instance admin privileges.
+
+## ❓ FAQ
+
+### Q: What plugin ID should I use in the configuration file?
+
+**A:** Use the **complete plugin ID** in `plugins.entries`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-plugin-wecom": { "enabled": true }  // ✅ Correct
+    }
+  }
+}
+```
+
+**Do not** use the channel id:
+```json
+{
+  "plugins": {
+    "entries": {
+      "wecom": { "enabled": true }  // ❌ Incorrect
+    }
+  }
+}
+```
+
+### Q: Why does `openclaw doctor` keep reporting "wecom configured, not enabled yet"?
+
+**A:** Add `"deny": ["wecom"]` to your `plugins` configuration:
+
+```json
+{
+  "plugins": {
+    "deny": ["wecom"],
+    "entries": {
+      "openclaw-plugin-wecom": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+**Reason:** OpenClaw tries to auto-enable built-in channel configurations with the id `wecom`. Adding `deny` prevents this auto-enablement, ensuring only the `openclaw-plugin-wecom` plugin is used.
+
+### Q: How does image sending work?
+
+**A:** The plugin automatically handles images generated by OpenClaw (such as browser screenshots):
+
+- **Local images** (from `~/.openclaw/media/`) are automatically encoded to base64 and sent via WeCom's `msg_item` API
+- **Image constraints**: Max 2MB per image, supports JPG and PNG formats, up to 10 images per message
+- **No configuration needed**: Works out of the box with tools like browser screenshot
+- Images appear when the AI completes its response (streaming doesn't support incremental image sending)
+
+**Example:**
+```
+User: "Take a screenshot of GitHub homepage"
+AI: [Takes screenshot] → Image displays properly in WeCom ✅
+```
+
+If an image fails to process (size limit, invalid format), the text response will still be delivered and an error will be logged.
+
+### Q: How to configure auth token for public-facing OpenClaw with WeCom callbacks?
+
+**A:** WeCom bot **does not need** OpenClaw's Gateway Auth Token.
+
+- **Gateway Auth Token** (`gateway.auth.token`) is used for:
+  - WebUI access authentication
+  - WebSocket connection authentication
+  - CLI remote connection authentication
+
+- **WeCom Webhook** (`/webhooks/wecom`) authentication:
+  - Uses WeCom's own signature verification (Token + EncodingAESKey)
+  - Does not require Gateway Auth Token
+  - OpenClaw plugin system automatically handles webhook routing
+
+**Deployment suggestions:**
+1. If using a reverse proxy (e.g., Nginx), configure authentication exemption for `/webhooks/wecom` path
+2. Or expose the webhook endpoint on a separate port without Gateway Auth
+
+### Q: How to fix EncodingAESKey length validation failure?
+
+**A:** Common causes and solutions:
+
+1. **Check configuration key name**: Ensure correct key name `encodingAesKey` (case-sensitive)
+   ```json
+   {
+     "channels": {
+       "wecom": {
+         "encodingAesKey": "..."  // ✅ Correct
+       }
+     }
+   }
+   ```
+
+2. **Check key length**: EncodingAESKey must be exactly 43 characters
+   ```bash
+   # Check length
+   echo -n "your-key" | wc -c
+   ```
+
+3. **Check for extra spaces/newlines**: Ensure no leading/trailing whitespace in the key string
+
+## 📂 Project Structure
+
+```
+openclaw-plugin-wecom/
+├── index.js              # Plugin entry point
+├── webhook.js            # WeCom HTTP communication handler
+├── dynamic-agent.js      # Dynamic agent routing logic
+├── stream-manager.js     # Streaming response manager
+├── crypto.js             # WeCom encryption algorithms
+├── client.js             # Client logic
+├── logger.js             # Logging module
+├── utils.js              # Utility functions
+├── package.json          # npm package config
+└── openclaw.plugin.json  # OpenClaw plugin manifest
+```
 
 ## 🤝 Contributing
 
 We welcome contributions! Please submit Issues or Pull Requests for bugs or feature suggestions.
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
 ## 📄 License
 
 This project is licensed under the [ISC License](./LICENSE).

package/README_ZH.md

@@ -9,132 +9,114 @@
 - 🌊 **流式输出 (Streaming)**: 基于企业微信最新的 AI 机器人流式分片机制，实现流畅的打字机式回复体验。
 - 🤖 **动态 Agent 管理**: 默认按"每个私聊用户 / 每个群聊"自动创建独立 Agent。每个 Agent 拥有独立的工作区与对话上下文，实现更强的数据隔离。
 - 👥 **群聊深度集成**: 支持群聊消息解析，可通过 @提及（At-mention）精准触发机器人响应。
+- 🖼️ **图片支持**: 自动将本地图片（截图、生成的图像）进行 base64 编码并发送，无需额外配置。
 - 🛠️ **指令增强**: 内置常用指令支持（如 `/new` 开启新会话、`/status` 查看状态等），并提供指令白名单配置功能。
 - 🔒 **安全与认证**: 完整支持企业微信消息加解密、URL 验证及发送者身份校验。
 - ⚡ **高性能异步处理**: 采用异步消息处理架构，确保即使在长耗时 AI 推理过程中，企业微信网关也能保持高响应性。
 
-## 🚀 快速开始
+## 📋 前置要求
 
-### 方式一：Docker 一键部署（推荐）
+- 已安装 [OpenClaw](https://github.com/openclaw/openclaw) (版本 2026.1.30+)
+- 企业微信管理后台权限，可创建智能机器人应用
+- 可从企业微信访问的服务器地址（HTTP/HTTPS）
 
-本仓库提供了完整的 Docker 部署方案，**一键部署 OpenClaw + 企业微信插件**，包含自动化安装和配置。
+## 🚀 安装
 
-```bash
-# 1. 克隆仓库
-git clone https://github.com/sunnoy/openclaw-plugin-wecom.git
-cd openclaw-plugin-wecom/deploy
-
-# 2. 复制环境变量配置
-cp .env.example .env
-
-# 3. 编辑 .env 文件，填写实际配置
-vim .env
-
-# 4. 运行部署脚本
-./deploy.sh
-```
-
-部署脚本会自动执行：
-- 创建数据目录和设置权限
-- 生成配置文件
-- 启动 Docker 容器
-- 安装企业微信插件
-- 配置并重启服务
-
-#### 🌟 部署亮点
-
-**自定义数据目录 & Agent Workspace 路径**
-
-本部署方案的核心优势是将所有数据统一存储到自定义路径，有效利用数据盘：
-
-```bash
-# .env 配置示例
-OPENCLAW_DATA_DIR=/data/openclaw    # 自定义数据目录
-```
-
-- **OpenClaw 状态目录**：`/data/openclaw/`
-- **动态 Agent Workspace**：`/data/openclaw/.openclaw/` 
-- **插件目录**：`/data/openclaw/extensions/`
-- **Canvas 数据**：`/data/openclaw/canvas/`
-
-这意味着：
-- ✅ 所有 Agent 工作区数据存储在数据盘，避免占用系统盘空间
-- ✅ 每个用户/群聊的独立 Agent 文件都在统一路径下管理
-- ✅ 方便备份、迁移和扩容
-- ✅ 适合企业级部署，数据盘可独立挂载和扩展
-
-### 方式二：手动安装插件
-
-在已有的 OpenClaw 环境中安装：
+### 方式一：使用 OpenClaw CLI（推荐）
 
 ```bash
 openclaw plugins install openclaw-plugin-wecom
 ```
 
-或通过 npm：
+### 方式二：使用 npm
 
 ```bash
 npm install openclaw-plugin-wecom
 ```
 
-然后在 OpenClaw 配置文件中添加：
+## ⚙️ 配置
+
+在 OpenClaw 配置文件（`~/.openclaw/openclaw.json`）中添加：
 
 ```json
 {
   "plugins": {
+    "deny": ["wecom"],
     "entries": {
-      "wecom": { "enabled": true }
+      "openclaw-plugin-wecom": {
+        "enabled": true
+      }
     }
   },
   "channels": {
     "wecom": {
       "enabled": true,
       "token": "你的 Token",
-      "encodingAesKey": "你的 EncodingAESKey"
+      "encodingAesKey": "你的 EncodingAESKey",
+      "commands": {
+        "enabled": true,
+        "allowlist": ["/new", "/status", "/help", "/compact"]
+      }
     }
   }
 }
 ```
 
-### 企业微信后台设置
+### 配置说明
 
-1. 在企业微信管理后台创建一个"智能机器人"。
-2. 将机器人的"接收消息配置"中的 URL 设置为你的服务地址（例如：`https://your-domain.com/webhooks/wecom`）。
-3. 填入对应的 Token 和 EncodingAESKey。
+| 配置项 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `plugins.deny` | array | 推荐 | 添加 `["wecom"]` 防止 OpenClaw 自动启用内置 channel |
+| `plugins.entries.openclaw-plugin-wecom.enabled` | boolean | 是 | 启用插件 |
+| `channels.wecom.token` | string | 是 | 企业微信机器人 Token |
+| `channels.wecom.encodingAesKey` | string | 是 | 企业微信消息加密密钥（43 位） |
+| `channels.wecom.commands.allowlist` | array | 否 | 允许的指令白名单 |
 
-## 📂 项目结构
+## 🔌 企业微信后台配置
 
-```
-openclaw-plugin-wecom/
-├── deploy/                      # 部署相关文件
-│   ├── deploy.sh               # 一键部署脚本
-│   ├── docker-compose.yml      # Docker Compose 配置
-│   ├── .env.example            # 环境变量示例
-│   ├── openclaw.json.base      # 基础配置模板
-│   └── openclaw.json.template  # 完整配置模板
-├── Dockerfile                   # OpenClaw 镜像构建文件
-├── local.sh                     # 本地镜像构建脚本
-├── index.js                     # 插件入口
-├── webhook.js                   # 企业微信 HTTP 通信处理
-├── dynamic-agent.js             # 动态 Agent 分配逻辑
-├── stream-manager.js            # 流式回复管理
-├── crypto.js                    # 企业微信加密算法
-└── client.js                    # 客户端逻辑
-```
+1. 登录[企业微信管理后台](https://work.weixin.qq.com/)
+2. 进入"应用管理" → "应用" → "创建应用" → 选择"智能机器人"
+3. 在"接收消息配置"中设置：
+   - **URL**: `https://your-domain.com/webhooks/wecom`
+   - **Token**: 与 `channels.wecom.token` 一致
+   - **EncodingAESKey**: 与 `channels.wecom.encodingAesKey` 一致
+4. 保存配置并启用消息接收
 
 ## 🤖 动态 Agent 路由
 
-OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处理。本插件实现"按人/按群隔离"：
+本插件实现"按人/按群隔离"的 Agent 管理：
+
+### 工作原理
 
 1. 企业微信消息到达后，插件生成确定性的 `agentId`：
-   - 私聊：`wecom-dm-<userId>`
-   - 群聊：`wecom-group-<chatId>`
-2. OpenClaw 自动创建/复用对应的 Agent 工作区。
+   - **私聊**: `wecom-dm-<userId>`
+   - **群聊**: `wecom-group-<chatId>`
+2. OpenClaw 自动创建/复用对应的 Agent 工作区
+3. 每个用户/群聊拥有独立的对话历史和上下文
 
-### 配置选项
+### 高级配置
 
 配置在 `channels.wecom` 下：
 
+```json
+{
+  "channels": {
+    "wecom": {
+      "dynamicAgents": {
+        "enabled": true
+      },
+      "dm": {
+        "createAgentOnFirstMessage": true
+      },
+      "groupChat": {
+        "enabled": true,
+        "requireMention": true
+      }
+    }
+  }
+}
+```
+
 | 配置项 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | `dynamicAgents.enabled` | boolean | `true` | 是否启用动态 Agent |
@@ -142,6 +124,8 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 | `groupChat.enabled` | boolean | `true` | 启用群聊处理 |
 | `groupChat.requireMention` | boolean | `true` | 群聊必须 @ 提及才响应 |
 
+### 禁用动态 Agent
+
 如果需要所有消息进入默认 Agent：
 
 ```json
@@ -156,9 +140,7 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 
 ## 🛠️ 指令白名单
 
-为防止普通用户通过企业微信消息执行敏感的 Gateway 管理指令，本插件支持**指令白名单**机制。只有配置在白名单中的指令才会被执行，其他指令将被忽略。
-
-> 💡 **提示**：此配置已包含在 `deploy/openclaw.json.template` 中，部署时会自动生效。
+为防止普通用户通过企业微信消息执行敏感的 Gateway 管理指令，本插件支持**指令白名单**机制。
 
 ```json
 {
@@ -173,6 +155,8 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 }
 ```
 
+### 推荐白名单指令
+
 | 指令 | 说明 | 安全级别 |
 |------|------|----------|
 | `/new` | 重置当前对话，开启全新会话 | ✅ 用户级 |
@@ -182,10 +166,132 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 
 > ⚠️ **安全提示**：不要将 `/gateway`、`/plugins` 等管理指令添加到白名单，避免普通用户获得 Gateway 实例的管理权限。
 
+## ❓ 常见问题 (FAQ)
+
+### Q: 配置文件中的插件 ID 应该使用什么？
+
+**A:** 在 `plugins.entries` 中，应该使用**完整的插件 ID**：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-plugin-wecom": { "enabled": true }  // ✅ 正确
+    }
+  }
+}
+```
+
+**不要**使用 channel id：
+```json
+{
+  "plugins": {
+    "entries": {
+      "wecom": { "enabled": true }  // ❌ 错误
+    }
+  }
+}
+```
+
+### Q: 为什么 `openclaw doctor` 一直报错 "wecom configured, not enabled yet"？
+
+**A:** 需要在 `plugins` 配置中添加 `"deny": ["wecom"]`：
+
+```json
+{
+  "plugins": {
+    "deny": ["wecom"],
+    "entries": {
+      "openclaw-plugin-wecom": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+**原因：** OpenClaw 会尝试自动启用 channel id 为 `wecom` 的内置插件配置，添加 `deny` 可以防止这种自动启用，确保只使用 `openclaw-plugin-wecom` 插件。
+
+### Q: 图片发送是如何工作的？
+
+**A:** 插件会自动处理 OpenClaw 生成的图片（如浏览器截图）：
+
+- **本地图片**（来自 `~/.openclaw/media/`）会自动进行 base64 编码，通过企业微信 `msg_item` API 发送
+- **图片限制**：单张图片最大 2MB，支持 JPG 和 PNG 格式，每条消息最多 10 张图片
+- **无需配置**：开箱即用，配合浏览器截图等工具自动生效
+- 图片会在 AI 完成回复后显示（流式输出不支持增量发送图片）
+
+**示例：**
+```
+用户："帮我截个 GitHub 首页的图"
+AI：[执行截图] → 图片在企业微信中正常显示 ✅
+```
+
+如果图片处理失败（超出大小限制、格式不支持等），文本回复仍会正常发送，错误信息会记录在日志中。
+
+### Q: OpenClaw 开放公网需要 auth token，企业微信回调如何配置？
+
+**A:** 企业微信机器人**不需要**配置 OpenClaw 的 Gateway Auth Token。
+
+- **Gateway Auth Token** (`gateway.auth.token`) 主要用于：
+  - WebUI 访问认证
+  - WebSocket 连接认证
+  - CLI 远程连接认证
+
+- **企业微信 Webhook** (`/webhooks/wecom`) 的认证机制：
+  - 使用企业微信自己的签名验证（Token + EncodingAESKey）
+  - 不需要 Gateway Auth Token
+  - OpenClaw 插件系统会自动处理 webhook 路由
+
+**部署建议：**
+1. 如果使用反向代理（如 Nginx），可以为 `/webhooks/wecom` 路径配置豁免认证
+2. 或者将 webhook 端点暴露在独立端口，不经过 Gateway Auth
+
+### Q: EncodingAESKey 长度验证失败怎么办？
+
+**A:** 常见原因和解决方法：
+
+1. **检查配置键名**：确保使用正确的键名 `encodingAesKey`（注意大小写）
+   ```json
+   {
+     "channels": {
+       "wecom": {
+         "encodingAesKey": "..."  // ✅ 正确
+       }
+     }
+   }
+   ```
+
+2. **检查密钥长度**：EncodingAESKey 必须是 43 位字符
+   ```bash
+   # 检查长度
+   echo -n "你的密钥" | wc -c
+   ```
+
+3. **检查是否有多余空格/换行**：确保密钥字符串前后没有空格或换行符
+
+## 📂 项目结构
+
+```
+openclaw-plugin-wecom/
+├── index.js              # 插件入口
+├── webhook.js            # 企业微信 HTTP 通信处理
+├── dynamic-agent.js      # 动态 Agent 分配逻辑
+├── stream-manager.js     # 流式回复管理
+├── crypto.js             # 企业微信加密算法
+├── client.js             # 客户端逻辑
+├── logger.js             # 日志模块
+├── utils.js              # 工具函数
+├── package.json          # npm 包配置
+└── openclaw.plugin.json  # OpenClaw 插件清单
+```
+
 ## 🤝 贡献规范
 
 我们非常欢迎开发者参与贡献！如果你发现了 Bug 或有更好的功能建议，请提交 Issue 或 Pull Request。
 
+详见 [CONTRIBUTING.md](./CONTRIBUTING.md)
+
 ## 📄 开源协议
 
 本项目采用 [ISC License](./LICENSE) 协议。

package/image-processor.js

@@ -0,0 +1,179 @@
+import { readFile } from "fs/promises";
+import { createHash } from "crypto";
+import { logger } from "./logger.js";
+
+/**
+ * Image Processing Module for WeCom
+ *
+ * Handles loading, validating, and encoding images for WeCom msg_item
+ * Supports JPG and PNG formats up to 2MB
+ */
+
+// Image format signatures (magic bytes)
+const IMAGE_SIGNATURES = {
+    JPG: [0xFF, 0xD8, 0xFF],
+    PNG: [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A],
+};
+
+// 2MB size limit (before base64 encoding)
+const MAX_IMAGE_SIZE = 2 * 1024 * 1024;
+
+/**
+ * Load image file from filesystem
+ * @param {string} filePath - Absolute path to image file
+ * @returns {Promise<Buffer>} Image data buffer
+ * @throws {Error} If file not found or cannot be read
+ */
+export async function loadImageFromPath(filePath) {
+    try {
+        logger.debug("Loading image from path", { filePath });
+        const buffer = await readFile(filePath);
+        logger.debug("Image loaded successfully", {
+            filePath,
+            size: buffer.length
+        });
+        return buffer;
+    } catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Image file not found: ${filePath}`);
+        } else if (error.code === "EACCES") {
+            throw new Error(`Permission denied reading image: ${filePath}`);
+        } else {
+            throw new Error(`Failed to read image file: ${error.message}`);
+        }
+    }
+}
+
+/**
+ * Convert buffer to base64 string
+ * @param {Buffer} buffer - Image data buffer
+ * @returns {string} Base64-encoded string
+ */
+export function encodeImageToBase64(buffer) {
+    return buffer.toString("base64");
+}
+
+/**
+ * Calculate MD5 checksum of buffer
+ * @param {Buffer} buffer - Image data buffer
+ * @returns {string} MD5 hash in hexadecimal
+ */
+export function calculateMD5(buffer) {
+    return createHash("md5").update(buffer).digest("hex");
+}
+
+/**
+ * Validate image size is within limits
+ * @param {Buffer} buffer - Image data buffer
+ * @throws {Error} If size exceeds 2MB limit
+ */
+export function validateImageSize(buffer) {
+    const sizeBytes = buffer.length;
+    const sizeMB = (sizeBytes / 1024 / 1024).toFixed(2);
+
+    if (sizeBytes > MAX_IMAGE_SIZE) {
+        throw new Error(
+            `Image size ${sizeMB}MB exceeds 2MB limit (actual: ${sizeBytes} bytes)`
+        );
+    }
+
+    logger.debug("Image size validated", { sizeBytes, sizeMB });
+}
+
+/**
+ * Detect image format from magic bytes
+ * @param {Buffer} buffer - Image data buffer
+ * @returns {string} Format: "JPG" or "PNG"
+ * @throws {Error} If format is not supported
+ */
+export function detectImageFormat(buffer) {
+    // Check PNG signature
+    if (buffer.length >= IMAGE_SIGNATURES.PNG.length) {
+        const isPNG = IMAGE_SIGNATURES.PNG.every(
+            (byte, index) => buffer[index] === byte
+        );
+        if (isPNG) {
+            logger.debug("Image format detected: PNG");
+            return "PNG";
+        }
+    }
+
+    // Check JPG signature
+    if (buffer.length >= IMAGE_SIGNATURES.JPG.length) {
+        const isJPG = IMAGE_SIGNATURES.JPG.every(
+            (byte, index) => buffer[index] === byte
+        );
+        if (isJPG) {
+            logger.debug("Image format detected: JPG");
+            return "JPG";
+        }
+    }
+
+    // Unknown format
+    const header = buffer.slice(0, 16).toString("hex");
+    throw new Error(
+        `Unsupported image format. Only JPG and PNG are supported. ` +
+        `File header: ${header}`
+    );
+}
+
+/**
+ * Complete image processing pipeline
+ *
+ * Loads image from filesystem, validates format and size,
+ * then encodes to base64 and calculates MD5 checksum.
+ *
+ * @param {string} filePath - Absolute path to image file
+ * @returns {Promise<Object>} Processed image data
+ * @returns {string} return.base64 - Base64-encoded image data
+ * @returns {string} return.md5 - MD5 checksum
+ * @returns {string} return.format - Image format (JPG or PNG)
+ * @returns {number} return.size - Original size in bytes
+ *
+ * @throws {Error} If any step fails (file not found, invalid format, size exceeded, etc.)
+ *
+ * @example
+ * const result = await prepareImageForMsgItem('/path/to/image.jpg');
+ * // Returns: { base64: "...", md5: "...", format: "JPG", size: 123456 }
+ */
+export async function prepareImageForMsgItem(filePath) {
+    logger.debug("Starting image processing pipeline", { filePath });
+
+    try {
+        // Step 1: Load image
+        const buffer = await loadImageFromPath(filePath);
+
+        // Step 2: Validate size
+        validateImageSize(buffer);
+
+        // Step 3: Detect format
+        const format = detectImageFormat(buffer);
+
+        // Step 4: Encode to base64
+        const base64 = encodeImageToBase64(buffer);
+
+        // Step 5: Calculate MD5
+        const md5 = calculateMD5(buffer);
+
+        logger.info("Image processed successfully", {
+            filePath,
+            format,
+            size: buffer.length,
+            md5,
+            base64Length: base64.length
+        });
+
+        return {
+            base64,
+            md5,
+            format,
+            size: buffer.length
+        };
+    } catch (error) {
+        logger.error("Image processing failed", {
+            filePath,
+            error: error.message
+        });
+        throw error;
+    }
+}

package/index.js

@@ -184,7 +184,7 @@ const wecomChannelPlugin = {
     chatTypes: ["direct", "group"],  // 支持私聊和群聊
     reactions: false,
     threads: false,
-    media: false,
+    media: true,  // Supports image sending via base64 encoding
     nativeCommands: false,
     blockStreaming: true, // WeCom AI Bot uses stream response format
   },
@@ -264,8 +264,60 @@ const wecomChannelPlugin = {
       const streamId = activeStreams.get(userId);
 
       if (streamId && streamManager.hasStream(streamId)) {
+        // Check if mediaUrl is a local path (sandbox: prefix or absolute path)
+        const isLocalPath = mediaUrl.startsWith("sandbox:") || mediaUrl.startsWith("/");
+
+        if (isLocalPath) {
+          // Convert sandbox: URLs to absolute paths
+          // Support both sandbox:/ and sandbox:// formats
+          const absolutePath = mediaUrl
+            .replace(/^sandbox:\/\//, "")
+            .replace(/^sandbox:\//, "");
+
+          logger.debug("Queueing local image for stream", {
+            userId,
+            streamId,
+            mediaUrl,
+            absolutePath
+          });
+
+          // Queue the image for processing when stream finishes
+          const queued = streamManager.queueImage(streamId, absolutePath);
+
+          if (queued) {
+            // Append text content to stream (without markdown image)
+            if (text) {
+              const stream = streamManager.getStream(streamId);
+              const separator = stream && stream.content.length > 0 ? "\n\n" : "";
+              streamManager.appendStream(streamId, separator + text);
+            }
+
+            // Append placeholder indicating image will follow
+            const imagePlaceholder = "\n\n[图片]";
+            streamManager.appendStream(streamId, imagePlaceholder);
+
+            return {
+              channel: "wecom",
+              messageId: `msg_stream_img_${Date.now()}`,
+            };
+          } else {
+            logger.warn("Failed to queue image, falling back to markdown", {
+              userId,
+              streamId,
+              mediaUrl
+            });
+            // Fallback to old behavior
+          }
+        }
+
+        // OLD BEHAVIOR: For external URLs or if queueing failed, use markdown
         const content = text ? `${text}\n\n![image](${mediaUrl})` : `![image](${mediaUrl})`;
-        logger.debug("Appending outbound media to stream", { userId, streamId, mediaUrl });
+        logger.debug("Appending outbound media to stream (markdown)", {
+          userId,
+          streamId,
+          mediaUrl
+        });
+
         // 使用 appendStream 追加内容
         const stream = streamManager.getStream(streamId);
         const separator = stream && stream.content.length > 0 ? "\n\n" : "";
@@ -412,10 +464,10 @@ async function wecomHttpHandler(req, res) {
         nonce,
         account: target.account,
         config: target.config,
-      }).catch((err) => {
+      }).catch(async (err) => {
         logger.error("WeCom message processing failed", { error: err.message });
         // 即使失败也要标记流为完成
-        streamManager.finishStream(streamId);
+        await streamManager.finishStream(streamId);
       });
 
       return true;
@@ -450,7 +502,11 @@ async function wecomHttpHandler(req, res) {
         stream.content,
         stream.finished,
         timestamp,
-        nonce
+        nonce,
+        // Pass msgItem when stream is finished and has images
+        stream.finished && stream.msgItem.length > 0
+          ? { msgItem: stream.msgItem }
+          : {}
       );
 
       res.writeHead(200, { "Content-Type": "application/json" });
@@ -495,7 +551,7 @@ async function wecomHttpHandler(req, res) {
         const streamId = `welcome_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
         streamManager.createStream(streamId);
         streamManager.appendStream(streamId, welcomeMessage);
-        streamManager.finishStream(streamId);
+        await streamManager.finishStream(streamId);
 
         const streamResponse = webhook.buildStreamResponse(
           streamId,
@@ -592,7 +648,7 @@ async function processInboundMessage({ message, streamId, timestamp, nonce, acco
     // 通过流式响应返回拦截消息
     if (streamId) {
       streamManager.appendStream(streamId, cmdConfig.blockMessage);
-      streamManager.finishStream(streamId);
+      await streamManager.finishStream(streamId);
       activeStreams.delete(streamKey);
     }
     return;
@@ -713,15 +769,15 @@ async function processInboundMessage({ message, streamId, timestamp, nonce, acco
 
         // 如果是最终回复,标记流为完成
         if (streamId && info.kind === "final") {
-          streamManager.finishStream(streamId);
+          await streamManager.finishStream(streamId);
           logger.info("WeCom stream finished", { streamId });
         }
       },
-      onError: (err, info) => {
+      onError: async (err, info) => {
         logger.error("WeCom reply failed", { error: err.message, kind: info.kind });
         // 发生错误时也标记流为完成
         if (streamId) {
-          streamManager.finishStream(streamId);
+          await streamManager.finishStream(streamId);
         }
       },
     },
@@ -729,7 +785,7 @@ async function processInboundMessage({ message, streamId, timestamp, nonce, acco
 
   // 确保在dispatch完成后标记流为完成（兜底机制）
   if (streamId) {
-    streamManager.finishStream(streamId);
+    await streamManager.finishStream(streamId);
     activeStreams.delete(streamKey);  // 清理活跃流映射
     logger.info("WeCom stream finished (dispatch complete)", { streamId });
   }
@@ -807,6 +863,7 @@ async function deliverWecomReply({ payload, account, responseUrl, senderId, stre
 // =============================================================================
 
 const plugin = {
+  // Plugin id should match `openclaw.plugin.json` id (and config.plugins.entries key).
   id: "openclaw-plugin-wecom",
   name: "Enterprise WeChat",
   description: "Enterprise WeChat AI Bot channel plugin for OpenClaw",

package/logger.js

@@ -1,12 +1,30 @@
 /**
  * Structured logging for WeCom plugin
  */
+const LEVELS = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 100,
+};
+
+function getEnvLogLevel() {
+    const raw = (process.env.WECOM_LOG_LEVEL || process.env.LOG_LEVEL || "info").toLowerCase();
+    return Object.prototype.hasOwnProperty.call(LEVELS, raw) ? raw : "info";
+}
+
 export class Logger {
     prefix;
-    constructor(prefix = "[wecom]") {
+    level;
+    constructor(prefix = "[wecom]", level = getEnvLogLevel()) {
         this.prefix = prefix;
+        this.level = level;
     }
     log(level, message, context) {
+        if (LEVELS[level] < LEVELS[this.level]) {
+            return;
+        }
         const timestamp = new Date().toISOString();
         const contextStr = context ? ` ${JSON.stringify(context)}` : "";
         const logMessage = `${timestamp} ${level.toUpperCase()} ${this.prefix} ${message}${contextStr}`;
@@ -38,9 +56,9 @@ export class Logger {
         this.log("error", message, context);
     }
     child(subPrefix) {
-        return new Logger(`${this.prefix}:${subPrefix}`);
+        return new Logger(`${this.prefix}:${subPrefix}`, this.level);
     }
 }
 // Default logger instance
 export const logger = new Logger();
-//# sourceMappingURL=logger.js.map
+//# sourceMappingURL=logger.js.map

package/openclaw.plugin.json

@@ -10,4 +10,4 @@
     "additionalProperties": false,
     "properties": {}
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "openclaw-plugin-wecom",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -9,6 +9,7 @@
         "client.js",
         "crypto.js",
         "dynamic-agent.js",
+        "image-processor.js",
         "logger.js",
         "README.md",
         "README_ZH.md",
@@ -47,7 +48,7 @@
     "keywords": [
         "openclaw",
         "wecom",
-        "wecom",
+        "enterprise-wechat",
         "chat",
         "plugin"
     ],

package/stream-manager.js

@@ -1,4 +1,5 @@
 import { logger } from "./logger.js";
+import { prepareImageForMsgItem } from "./image-processor.js";
 
 /**
  * 流式消息状态管理器
@@ -6,7 +7,7 @@ import { logger } from "./logger.js";
  */
 class StreamManager {
     constructor() {
-        // streamId -> { content: string, finished: boolean, updatedAt: number, feedbackId: string|null, msgItem: Array }
+        // streamId -> { content: string, finished: boolean, updatedAt: number, feedbackId: string|null, msgItem: Array, pendingImages: Array }
         this.streams = new Map();
         this._cleanupInterval = null;
     }
@@ -42,6 +43,7 @@ class StreamManager {
             updatedAt: Date.now(),
             feedbackId: options.feedbackId || null,  // 用户反馈追踪
             msgItem: [],  // 图文混排消息列表
+            pendingImages: [],  // 待处理的图片路径列表
         });
         return streamId;
     }
@@ -117,9 +119,101 @@ class StreamManager {
     }
 
     /**
-     * 标记流为完成状态
+     * Queue image for inclusion when stream finishes
+     * @param {string} streamId - 流ID
+     * @param {string} imagePath - 图片绝对路径
+     * @returns {boolean} 是否成功队列
      */
-    finishStream(streamId) {
+    queueImage(streamId, imagePath) {
+        this.startCleanup();
+        const stream = this.streams.get(streamId);
+        if (!stream) {
+            logger.warn("Stream not found for queueImage", { streamId });
+            return false;
+        }
+
+        stream.pendingImages.push({
+            path: imagePath,
+            queuedAt: Date.now()
+        });
+
+        logger.debug("Image queued for stream", {
+            streamId,
+            imagePath,
+            totalQueued: stream.pendingImages.length
+        });
+
+        return true;
+    }
+
+    /**
+     * Process all pending images and build msgItem array
+     * @param {string} streamId - 流ID
+     * @returns {Promise<Array>} msg_item 数组
+     */
+    async processPendingImages(streamId) {
+        const stream = this.streams.get(streamId);
+        if (!stream || stream.pendingImages.length === 0) {
+            return [];
+        }
+
+        logger.debug("Processing pending images", {
+            streamId,
+            count: stream.pendingImages.length
+        });
+
+        const msgItems = [];
+
+        for (const img of stream.pendingImages) {
+            try {
+                // Limit to 10 images per WeCom API spec
+                if (msgItems.length >= 10) {
+                    logger.warn("Stream exceeded 10 image limit, truncating", {
+                        streamId,
+                        total: stream.pendingImages.length,
+                        processed: msgItems.length
+                    });
+                    break;
+                }
+
+                const processed = await prepareImageForMsgItem(img.path);
+                msgItems.push({
+                    msgtype: "image",
+                    image: {
+                        base64: processed.base64,
+                        md5: processed.md5
+                    }
+                });
+
+                logger.debug("Image processed successfully", {
+                    streamId,
+                    imagePath: img.path,
+                    format: processed.format,
+                    size: processed.size
+                });
+            } catch (error) {
+                logger.error("Failed to process image for stream", {
+                    streamId,
+                    imagePath: img.path,
+                    error: error.message
+                });
+                // Continue processing other images even if one fails
+            }
+        }
+
+        logger.info("Completed processing images for stream", {
+            streamId,
+            processed: msgItems.length,
+            pending: stream.pendingImages.length
+        });
+
+        return msgItems;
+    }
+
+    /**
+     * 标记流为完成状态（异步，处理待发送的图片）
+     */
+    async finishStream(streamId) {
         this.startCleanup();
         const stream = this.streams.get(streamId);
         if (!stream) {
@@ -127,12 +221,18 @@ class StreamManager {
             return false;
         }
 
+        // Process pending images before finishing
+        if (stream.pendingImages.length > 0) {
+            stream.msgItem = await this.processPendingImages(streamId);
+        }
+
         stream.finished = true;
         stream.updatedAt = Date.now();
 
         logger.info("Stream finished", {
             streamId,
-            contentLength: stream.content.length
+            contentLength: stream.content.length,
+            imageCount: stream.msgItem.length
         });
 
         return true;