@max1874/openclaw-wecom 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# OpenClaw WeChat/WeCom Plugin
+
+通过 Stride 服务与微信/企业微信对接的 OpenClaw 渠道插件。
+
+## 安装
+
+```bash
+npm install
+```
+
+## 配置
+
+在 `openclaw.yaml` 或环境变量中配置：
+
+```yaml
+channels:
+  wecom:
+    enabled: true
+    token: "your-stride-token"  # Stride API token
+    chatId: "your-default-chat-id"  # 默认 chatId
+    webhookPath: "/webhooks/wechat"  # Webhook 路径
+    webhookPort: 3000  # Webhook 端口
+
+    # 私聊策略
+    dmPolicy: "allowlist"  # "open" | "allowlist"
+    allowFrom:
+      - "7881303019076556"  # 允许的用户 ID
+      - "username"  # 或用户名
+
+    # 群聊策略
+    groupPolicy: "allowlist"  # "open" | "allowlist" | "disabled"
+    groupAllowFrom:
+      - "R:10917132666297873"  # 允许的群 ID
+    requireMention: true  # 群聊是否需要 @
+
+    # 单群配置 (可选)
+    groups:
+      "R:10917132666297873":
+        requireMention: false
+        allowFrom:
+          - "*"  # 允许所有群成员
+
+    # 消息配置
+    textChunkLimit: 4000  # 单条消息字符限制
+    mediaMaxMb: 30  # 媒体文件大小限制 (MB)
+```
+
+环境变量支持：
+- `WECOM_TOKEN` 或 `STRIDE_TOKEN`: API token
+- `WECOM_CHAT_ID` 或 `STRIDE_CHAT_ID`: 默认 chatId
+
+## Webhook 端点
+
+启动后，插件会监听以下 Webhook 端点：
+
+| 路径 | 说明 |
+|------|------|
+| `/webhooks/wechat/events/message` | 消息事件 |
+| `/webhooks/wechat/events/room/joined` | 群成员加入 |
+| `/webhooks/wechat/events/chatroom/loaded` | 群信息加载 |
+| `/webhooks/wechat/events/chatroom/joined` | 入群完成 |
+| `/health` | 健康检查 |
+
+## 消息类型
+
+### 支持接收的消息类型
+
+| type | 类型 | 说明 |
+|------|------|------|
+| 1 | 文件 | 下载并保存本地 |
+| 2 | 语音 | 使用 Stride 转写的文本 |
+| 4 | 聊天记录 | 合并转发的消息 |
+| 6 | 图片 | 下载并保存本地 |
+| 7 | 文字 | 主要消息类型 |
+| 12 | 链接 | 提取标题和 URL |
+
+### 支持发送的消息类型
+
+| messageType | 类型 | 说明 |
+|-------------|------|------|
+| 0 | 文字 | 主要发送类型 |
+| 1 | 图片 | 需要可访问的 URL |
+| 2 | 链接 | 卡片式链接 |
+| 3 | 文件 | 需要可访问的 URL |
+
+## 与飞书插件的差异
+
+| 特性 | 飞书插件 | 微信插件 |
+|------|---------|----------|
+| 连接方式 | WebSocket | Webhook 回调 |
+| SDK | 官方 SDK | HTTP REST API |
+| ID 类型 | open_id / chat_id | contactId / chatId / roomId |
+| 媒体处理 | 需要上传下载 | URL 直接可用 |
+| Card 消息 | 支持 | 不支持 |
+| 消息编辑 | 支持 | 不支持 |
+| Typing 指示器 | 反应替代 | 不支持 |
+
+## 开发
+
+```bash
+# 类型检查
+npx tsc --noEmit
+
+# 运行测试
+npm test
+```
+
+## 许可
+
+MIT

package/docs/CONFIG.md

@@ -0,0 +1,362 @@
+# OpenClaw WeChat/WeCom 配置指南
+
+## 快速开始
+
+### 1. 获取 Stride 凭证
+
+从 Stride 服务获取：
+- **token**: API 访问令牌
+- **chatId**: 默认聊天 ID（可选，用于主动发送消息）
+
+### 2. 最小配置
+
+```yaml
+# openclaw.yaml
+channels:
+  wecom:
+    enabled: true
+    token: "693b9eba76962211776ef462"
+    webhookPort: 3000
+    allowFrom:
+      - "*"  # 允许所有人私聊
+```
+
+### 3. 配置 Webhook 回调
+
+将 Stride 的回调地址配置为：
+```
+http://your-server:3000/webhooks/wechat/events/message
+```
+
+如果使用 ngrok/cloudflare tunnel：
+```bash
+ngrok http 3000
+# 然后使用 https://xxx.ngrok.io/webhooks/wechat/events/message
+```
+
+---
+
+## 完整配置参考
+
+```yaml
+channels:
+  wecom:
+    # ========== 基础配置 ==========
+    enabled: true                    # 是否启用
+    token: "your-stride-token"       # Stride API token (必需)
+    chatId: "697dea419d6d3a463be7b4df"  # 默认 chatId (可选)
+
+    # ========== Webhook 配置 ==========
+    webhookPath: "/webhooks/wechat"  # Webhook 路径前缀
+    webhookPort: 3000                # 监听端口
+
+    # ========== 私聊策略 ==========
+    dmPolicy: "allowlist"            # "open" | "allowlist"
+    allowFrom:                       # 私聊白名单
+      - "7881303019076556"           # 用户 contactId
+      - "lin"                        # 或用户名 (contactName)
+      - "*"                          # 通配符，允许所有人
+
+    # ========== 群聊策略 ==========
+    groupPolicy: "allowlist"         # "open" | "allowlist" | "disabled"
+    groupAllowFrom:                  # 群聊白名单 (群 ID 或发送者)
+      - "R:10917132666297873"        # roomId
+      - "697dea419d6d3a463be7b4df"   # chatId
+    requireMention: true             # 群聊是否需要 @机器人
+
+    # ========== 单群配置 (可选) ==========
+    groups:
+      "R:10917132666297873":         # 群 ID
+        enabled: true                # 是否启用
+        requireMention: false        # 覆盖全局设置
+        allowFrom:                   # 该群的发送者白名单
+          - "*"                      # 允许所有群成员
+        systemPrompt: "你是群助手"    # 该群专用的系统提示词
+        tools:                       # 工具策略
+          allow: ["web_search"]
+          deny: ["file_write"]
+
+    # ========== 私聊配置 (可选) ==========
+    dms:
+      "7881303019076556":            # 用户 contactId
+        enabled: true
+        systemPrompt: "你是私人助理"
+
+    # ========== 消息配置 ==========
+    textChunkLimit: 4000             # 单条消息字符限制
+    chunkMode: "length"              # "length" | "newline"
+    renderMode: "auto"               # "auto" | "raw"
+
+    # ========== 历史记录 ==========
+    historyLimit: 10                 # 群聊历史记录条数
+    dmHistoryLimit: 5                # 私聊历史记录条数
+
+    # ========== 媒体配置 ==========
+    mediaMaxMb: 30                   # 媒体文件大小限制 (MB)
+```
+
+---
+
+## 策略配置详解
+
+### 私聊策略 (dmPolicy)
+
+| 值 | 说明 |
+|---|------|
+| `open` | 允许所有人私聊，需要 `allowFrom: ["*"]` |
+| `allowlist` | 只允许白名单用户私聊 |
+
+```yaml
+# 示例：开放私聊
+dmPolicy: "open"
+allowFrom:
+  - "*"
+
+# 示例：仅允许特定用户
+dmPolicy: "allowlist"
+allowFrom:
+  - "7881303019076556"
+  - "lin"
+```
+
+### 群聊策略 (groupPolicy)
+
+| 值 | 说明 |
+|---|------|
+| `open` | 允许所有群（需 @机器人） |
+| `allowlist` | 只响应白名单群/用户 |
+| `disabled` | 禁用群聊功能 |
+
+```yaml
+# 示例：开放所有群
+groupPolicy: "open"
+requireMention: true  # 必须 @机器人
+
+# 示例：仅特定群
+groupPolicy: "allowlist"
+groupAllowFrom:
+  - "R:10917132666297873"
+
+# 示例：禁用群聊
+groupPolicy: "disabled"
+```
+
+### 白名单匹配规则
+
+白名单支持三种匹配方式：
+
+1. **通配符**: `"*"` 匹配所有
+2. **ID 匹配**: contactId / roomId / chatId
+3. **名称匹配**: contactName (大小写不敏感)
+
+```yaml
+allowFrom:
+  - "*"                    # 通配符
+  - "7881303019076556"     # contactId
+  - "lin"                  # contactName
+  - "R:10917132666297873"  # roomId
+```
+
+---
+
+## 单群配置
+
+为特定群设置独立策略：
+
+```yaml
+groups:
+  # 测试群 - 宽松策略
+  "R:10917132666297873":
+    requireMention: false      # 不需要 @
+    allowFrom: ["*"]           # 允许所有人
+    systemPrompt: |
+      你是测试群的助手。
+      请用简洁的方式回答问题。
+
+  # 工作群 - 严格策略
+  "R:20917132666297874":
+    requireMention: true
+    allowFrom:
+      - "7881303019076556"     # 只允许管理员
+    tools:
+      allow: ["web_search"]
+      deny: ["*"]              # 禁用其他工具
+```
+
+---
+
+## 环境变量
+
+支持通过环境变量配置敏感信息：
+
+```bash
+# Stride 凭证
+export WECOM_TOKEN="693b9eba76962211776ef462"
+export WECOM_CHAT_ID="697dea419d6d3a463be7b4df"
+
+# 或使用 STRIDE_ 前缀
+export STRIDE_TOKEN="693b9eba76962211776ef462"
+export STRIDE_CHAT_ID="697dea419d6d3a463be7b4df"
+```
+
+配置文件中可以省略这些值：
+
+```yaml
+channels:
+  wecom:
+    enabled: true
+    # token 和 chatId 从环境变量读取
+    webhookPort: 3000
+```
+
+---
+
+## ID 格式说明
+
+微信插件使用以下 ID 格式：
+
+| ID 类型 | 格式 | 示例 |
+|--------|------|------|
+| chatId | 24位十六进制 | `697dea419d6d3a463be7b4df` |
+| contactId | 数字字符串 | `7881303019076556` |
+| roomId | R:数字 | `R:10917132666297873` |
+
+在配置中引用：
+
+```yaml
+# 直接使用
+allowFrom:
+  - "7881303019076556"
+  - "R:10917132666297873"
+
+# 或带前缀 (可选)
+allowFrom:
+  - "user:7881303019076556"
+  - "room:R:10917132666297873"
+  - "chat:697dea419d6d3a463be7b4df"
+```
+
+---
+
+## 常见配置场景
+
+### 场景 1: 个人助手
+
+只允许自己使用，禁用群聊：
+
+```yaml
+channels:
+  wecom:
+    enabled: true
+    token: "your-token"
+    webhookPort: 3000
+    dmPolicy: "allowlist"
+    allowFrom:
+      - "your-contact-id"
+    groupPolicy: "disabled"
+```
+
+### 场景 2: 团队机器人
+
+只在特定群响应，需要 @：
+
+```yaml
+channels:
+  wecom:
+    enabled: true
+    token: "your-token"
+    webhookPort: 3000
+    dmPolicy: "allowlist"
+    allowFrom: []              # 禁用私聊
+    groupPolicy: "allowlist"
+    groupAllowFrom:
+      - "R:team-room-id"
+    requireMention: true
+```
+
+### 场景 3: 客服机器人
+
+开放所有人私聊：
+
+```yaml
+channels:
+  wecom:
+    enabled: true
+    token: "your-token"
+    webhookPort: 3000
+    dmPolicy: "open"
+    allowFrom:
+      - "*"
+    groupPolicy: "disabled"
+    textChunkLimit: 2000       # 较短的回复
+```
+
+### 场景 4: 多群差异化配置
+
+不同群使用不同策略：
+
+```yaml
+channels:
+  wecom:
+    enabled: true
+    token: "your-token"
+    webhookPort: 3000
+    groupPolicy: "allowlist"
+    groupAllowFrom:
+      - "R:group1"
+      - "R:group2"
+    requireMention: true       # 默认需要 @
+
+    groups:
+      "R:group1":
+        requireMention: false  # 这个群不需要 @
+        systemPrompt: "你是技术支持"
+
+      "R:group2":
+        allowFrom:
+          - "admin-id"         # 只有管理员能触发
+        systemPrompt: "你是项目助手"
+```
+
+---
+
+## 调试与排查
+
+### 查看 Webhook 日志
+
+插件启动时会打印：
+```
+wecom: starting webhook server...
+wecom webhook: server listening on port 3000
+wecom webhook: message endpoint: http://localhost:3000/webhooks/wechat/events/message
+```
+
+收到消息时：
+```
+wecom webhook: POST /webhooks/wechat/events/message
+wecom: received text from lin (7881303019076556) in 697dea419d6d3a463be7b4df (dm)
+wecom: dispatching to agent (session=wecom:7881303019076556)
+```
+
+### 健康检查
+
+```bash
+curl http://localhost:3000/health
+# {"status":"ok","channel":"wecom"}
+```
+
+### 常见问题
+
+**Q: 消息收不到？**
+- 检查 Stride 回调地址是否正确
+- 确认端口是否开放
+- 查看 webhook 日志是否有请求
+
+**Q: 机器人不回复？**
+- 检查 `allowFrom` 白名单
+- 群聊检查 `requireMention` 和 `mentionSelf`
+- 查看日志中的策略检查结果
+
+**Q: 消息被截断？**
+- 调整 `textChunkLimit` 参数
+- 微信单条消息限制约 4000 字符

package/docs/SETUP.md

@@ -0,0 +1,162 @@
+# OpenClaw WeChat/WeCom 配置指南
+
+## 快速配置
+
+```bash
+# 启用插件
+openclaw config set channels.wecom.enabled true
+
+# Stride 凭证
+openclaw config set channels.wecom.token "693b9eba76962211776ef462"
+openclaw config set channels.wecom.chatId "697dea419d6d3a463be7b4df"
+
+# Webhook 配置
+openclaw config set channels.wecom.webhookPort 3000
+openclaw config set channels.wecom.webhookPath "/webhooks/wechat"
+```
+
+## 策略配置
+
+### 私聊策略
+
+```bash
+# 私聊策略: "open" | "allowlist"
+openclaw config set channels.wecom.dmPolicy "allowlist"
+
+# 私聊白名单 (contactId 或 contactName)
+openclaw config set channels.wecom.allowFrom '["7881303019076556", "lin"]'
+
+# 开放所有人私聊
+openclaw config set channels.wecom.dmPolicy "open"
+openclaw config set channels.wecom.allowFrom '["*"]'
+```
+
+### 群聊策略
+
+```bash
+# 群聊策略: "open" | "allowlist" | "disabled"
+openclaw config set channels.wecom.groupPolicy "allowlist"
+
+# 群聊白名单 (roomId 或 chatId)
+openclaw config set channels.wecom.groupAllowFrom '["R:10917132666297873"]'
+
+# 是否需要 @机器人
+openclaw config set channels.wecom.requireMention true
+```
+
+## 消息配置
+
+```bash
+# 单条消息字符限制 (默认 4000)
+openclaw config set channels.wecom.textChunkLimit 4000
+
+# 分块模式: "length" | "newline"
+openclaw config set channels.wecom.chunkMode "length"
+
+# 渲染模式: "auto" | "raw"
+openclaw config set channels.wecom.renderMode "auto"
+```
+
+## 历史记录
+
+```bash
+# 群聊历史记录条数
+openclaw config set channels.wecom.historyLimit 10
+
+# 私聊历史记录条数
+openclaw config set channels.wecom.dmHistoryLimit 5
+```
+
+## 媒体配置
+
+```bash
+# 媒体文件大小限制 (MB)
+openclaw config set channels.wecom.mediaMaxMb 30
+```
+
+## 单群配置
+
+```bash
+# 特定群不需要 @
+openclaw config set channels.wecom.groups.R:10917132666297873.requireMention false
+
+# 特定群允许所有人
+openclaw config set channels.wecom.groups.R:10917132666297873.allowFrom '["*"]'
+
+# 特定群的系统提示词
+openclaw config set channels.wecom.groups.R:10917132666297873.systemPrompt "你是测试群的助手"
+```
+
+## 完整示例
+
+### 个人助手配置
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.token "your-stride-token"
+openclaw config set channels.wecom.webhookPort 3000
+openclaw config set channels.wecom.dmPolicy "allowlist"
+openclaw config set channels.wecom.allowFrom '["your-contact-id"]'
+openclaw config set channels.wecom.groupPolicy "disabled"
+```
+
+### 团队机器人配置
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.token "your-stride-token"
+openclaw config set channels.wecom.webhookPort 3000
+openclaw config set channels.wecom.dmPolicy "allowlist"
+openclaw config set channels.wecom.allowFrom '[]'
+openclaw config set channels.wecom.groupPolicy "allowlist"
+openclaw config set channels.wecom.groupAllowFrom '["R:team-room-id"]'
+openclaw config set channels.wecom.requireMention true
+```
+
+### 开放客服配置
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.token "your-stride-token"
+openclaw config set channels.wecom.webhookPort 3000
+openclaw config set channels.wecom.dmPolicy "open"
+openclaw config set channels.wecom.allowFrom '["*"]'
+openclaw config set channels.wecom.groupPolicy "disabled"
+openclaw config set channels.wecom.textChunkLimit 2000
+```
+
+## 查看配置
+
+```bash
+# 查看所有 wecom 配置
+openclaw config get channels.wecom
+
+# 查看特定配置
+openclaw config get channels.wecom.token
+openclaw config get channels.wecom.webhookPort
+```
+
+## 环境变量 (可选)
+
+```bash
+export WECOM_TOKEN="your-stride-token"
+export WECOM_CHAT_ID="your-default-chat-id"
+```
+
+## Stride 回调配置
+
+启动后，配置 Stride 回调地址为：
+
+```
+http://your-server:3000/webhooks/wechat/events/message
+```
+
+使用 tunnel 时：
+```bash
+# ngrok
+ngrok http 3000
+# 使用 https://xxx.ngrok.io/webhooks/wechat/events/message
+
+# cloudflared
+cloudflared tunnel --url http://localhost:3000
+```

package/index.ts

@@ -0,0 +1,43 @@
+import type { ClawdbotPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { wecomPlugin } from "./src/channel.js";
+import { setWecomRuntime } from "./src/runtime.js";
+
+// Re-export main components
+export { monitorWecomProvider, stopWecomMonitor } from "./src/monitor.js";
+export {
+  sendMessageWecom,
+  sendImageWecom,
+  sendFileWecom,
+  sendLinkWecom,
+} from "./src/send.js";
+export { probeWecom } from "./src/probe.js";
+export { wecomPlugin } from "./src/channel.js";
+export { handleWecomMessage, parseWecomMessageEvent } from "./src/bot.js";
+export { startWebhookServer, stopWebhookServer } from "./src/webhook.js";
+
+// Re-export types
+export type {
+  WecomConfig,
+  WecomGroupConfig,
+  ResolvedWecomAccount,
+  WecomWebhookEvent,
+  WecomMessageContext,
+  WecomSendResult,
+  WecomProbeResult,
+  InboundMessageType,
+  OutboundMessageType,
+} from "./src/types.js";
+
+const plugin = {
+  id: "wecom",
+  name: "WeChat",
+  description: "WeChat/WeCom channel plugin via Stride",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setWecomRuntime(api.runtime);
+    api.registerChannel({ plugin: wecomPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://openclaw.dev/schemas/plugin.json",
+  "id": "wecom",
+  "name": "WeChat/WeCom",
+  "version": "0.1.0",
+  "description": "WeChat/WeCom channel plugin via Stride",
+  "author": "OpenClaw",
+  "license": "MIT",
+  "channel": {
+    "id": "wecom",
+    "label": "WeChat",
+    "selectionLabel": "WeChat/WeCom (微信/企业微信)",
+    "blurb": "WeChat/WeCom messaging via Stride.",
+    "aliases": ["wechat", "stride"]
+  },
+  "extensions": ["./index.ts"]
+}