npm - openclaw-plugin-wecom - Versions diffs - 1.0.0 → 1.0.2 - Mend

openclaw-plugin-wecom 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,148 +1,131 @@
 # 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.
+- 🛠️ **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
+### Advanced Configuration
-Under `channels.wecom`:
+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 +137,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 +154,126 @@ 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 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 CHANGED Viewed

@@ -13,128 +13,109 @@
 - 🔒 **安全与认证**: 完整支持企业微信消息加解密、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 +123,8 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 | `groupChat.enabled` | boolean | `true` | 启用群聊处理 |
 | `groupChat.requireMention` | boolean | `true` | 群聊必须 @ 提及才响应 |
+### 禁用动态 Agent
 如果需要所有消息进入默认 Agent：
 ```json
@@ -156,9 +139,7 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 ## 🛠️ 指令白名单
-为防止普通用户通过企业微信消息执行敏感的 Gateway 管理指令，本插件支持**指令白名单**机制。只有配置在白名单中的指令才会被执行，其他指令将被忽略。
-> 💡 **提示**：此配置已包含在 `deploy/openclaw.json.template` 中，部署时会自动生效。
+为防止普通用户通过企业微信消息执行敏感的 Gateway 管理指令，本插件支持**指令白名单**机制。
 ```json
 {
@@ -173,6 +154,8 @@ OpenClaw 会通过解析 `SessionKey` 来决定本次消息由哪个 Agent 处
 }
 ```
+### 推荐白名单指令
 | 指令 | 说明 | 安全级别 |
 |------|------|----------|
 | `/new` | 重置当前对话，开启全新会话 | ✅ 用户级 |
@@ -182,10 +165,115 @@ 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: 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/index.js CHANGED Viewed

@@ -807,6 +807,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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "openclaw-plugin-wecom",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",