Huo15 Wecom Plugin

核心用法

@huo15/wecom 是 OpenClaw 生态的企业微信（WeCom）官方通道插件，fork 自 yanhaidao/wecom 并持续维护。插件提供三条独立消息通道：

1. Bot WebSocket（默认推荐）：基于企业微信"智能机器人"WS长连接协议，无需公网回调部署，配置极简、响应延迟低
2. Agent 自建应用：调用企业微信官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户或群聊
3. 微信客服：接管外部客户在微信/视频号内发起的客服会话

三条通道可单独或组合启用，多账号场景下每个账号独立配置。关键配置入口为 channels.wecom.accounts.<id>.{bot|agent|kefu}。

显著优点

• 零回调部署：Bot WS 模式免公网 endpoint，降低运维复杂度与安全暴露面
• 端到端媒体处理：内置 AES-256-CBC 解密，图片/文件/语音可直接送入 Agent 做 OCR/ASR/文档解析
• 富文本适配：自动将 Markdown V2 转换为企业微信支持的格式（标题、表格、代码块、引用等）
• 流式交互体验：placeholder + 最多8次中间更新 + ack timeout 自动重连，缓解大模型长回复等待焦虑
• 多账号原生支持：单实例可并发接入多个企业、多个智能体，按 conversation 自动路由
• 安全加固：touser/chatid 经 sanitizer 过滤，拒绝 @all/@everyone/* 等广播字面量（v2.8.1 安全修复）

潜在缺点与局限性

• 协议边界明确：不支持个人微信（WeChat），与企业微信为两套独立协议
• 大文件分流逻辑复杂：v2.8.25 引入 GUIDANCE 决策表管理 MEDIA: 直发与 enhance_share_file 链接的优先级翻转，配置理解成本上升
• 上游依赖风险：持续 fork 自 yanhaidao/wecom，仅单向 fetch 不 push，若上游停更需独立维护
• WS 连接稳定性：虽具备 8 次重连 watchdog，但在弱网或企微服务端限流场景下仍可能丢消息，需依赖 Agent API fallback
• COS/OSS 预签名兼容：部分腾讯云/阿里云 bucket 对 Node 默认 UA 敏感，虽已修复（v2.8.8），但自定义存储后端仍需测试验证

适合人群

• 需要为企业微信组织接入 AI 客服/智能助手的开发团队
• 追求低运维、快速上线的中小型企业（优先 Bot WS 模式）
• 有跨企业、多账号管理需求的 SaaS 服务商或 IT 集成商
• 需处理加密媒体文件（图片、语音、文档）的 RAG 或自动化工作流场景

常规风险

• 密钥泄露风险：botSecret、corpSecret 配置于本地或 CI/CD 环境，需配合密钥管理服务（KMS/Vault）使用
• 消息广播误触：虽 sanitizer 拦截常见广播字面量，但 LLM 输出解析仍存在绕过可能，建议生产环境启用二次确认
• API 速率限制：企业微信官方对自建应用有频次配额，高并发场景需评估是否需要多账号分流
• 版本漂移：频繁小版本迭代（v2.8.x 密集发布），建议锁定版本并阅读 changelog 后再升级

核心用法

@huo15/wecom 是面向 OpenClaw 生态的企业微信（WeCom）官方通道插件，通过三种消息通道实现 Agent 与企业微信的深度集成：

Bot WebSocket 模式（默认推荐）：基于企业微信"智能机器人"的 WebSocket 协议，免公网回调配置，响应速度快、部署零门槛。只需配置 botId 和 secret 即可实现双向消息收发，适合快速启动场景。

Agent 自建应用模式：调用企业微信官方 REST API（CorpId/AgentId/Secret），支持主动推送给指定用户或群组，适合需要定时任务、系统告警等主动触达场景。

微信客服模式：接管"客服会话"，处理外部客户在微信/视频号中发起的客服咨询，打通公域流量与私域 Agent 服务。

插件支持多账号并存，单实例可同时接入多个企业、多个智能体，按 conversation 自动路由。核心功能包括 AES-256-CBC 加密媒体解密（让 Agent 直接处理图片 OCR、语音 ASR、文档解析）、Markdown V2 富文本适配、图片自动上传与降级处理、流式回复（placeholder + 最多 8 次中间更新）等。

显著优点

架构设计优秀：Bot WS 优先原则减少配置复杂度；失败自动降级机制（WS ack timeout fallback 到 Agent API）保障消息可达性；watchdog 连续 8 次失败后触发重连，稳定性强。

媒体处理能力突出：原生支持加密媒体解密，企业微信下发的图片、文件、语音可直接转为 buffer 供 Agent 处理，解决了企业微信生态常见的"收得到、读不了"痛点。图片回复支持 COS/OSS 预签名 URL 自动降级，避免过期链接暴露给用户。

安全实践到位：resolveWecomTarget 过滤器拒绝 @all/@everyone/\* 等广播字面量，防止误操作群发；微信客服 corpSecret 与 Agent corpSecret 支持独立配置，实现权限隔离；跨企业上下游消息走独立通道，不与本企业 Agent API 混用。

迭代响应迅速：从 v2.8.20 到 v2.9.4 持续迭代，针对群聊主动推送、placeholder 超时解锁、GUIDANCE 决策表优化等场景快速修复，社区活跃。

潜在缺点与局限性

平台锁定风险：专为企业微信协议设计，与个人微信（WeChat）协议不兼容，无法用于个人号场景。若企业后续迁移至飞书、钉钉等平台，需更换通道插件。

部署依赖 OpenClaw：作为 OpenClaw 生态的 Channel Plugin，无法独立运行，必须先部署 OpenClaw 核心框架。

文件大小限制：企业微信本身对单文件大小有上限（如 20MB），超大文件需走 enhance_share_file 链接模式，用户体验有损。

网络环境要求：Bot WebSocket 模式虽免公网回调，但仍需能访问企业微信服务器，部分隔离网络环境需配置代理。

适合的目标群体

• 企业 IT 部门：需要将现有 OpenClaw Agent 快速接入企业微信，为员工提供智能问答、文档助手等服务
• SaaS 服务商：基于企业微信构建客服、CRM、HR 等垂直场景 Agent 应用，利用三通道设计满足不同交互模式
• 开发者/系统集成商：fork 自 yanhaidao/wecom 并有活跃维护，适合二次开发定制企业微信生态应用
• 安全意识较强的组织：对广播消息过滤、密钥隔离、权限分离有明确要求的金融、政务、医疗等行业客户

使用风险与注意事项

性能风险：流式回复最多 8 次中间更新，若 Agent 生成内容过长或网络延迟高，可能触发 watchdog 重连，导致用户体验波动。

依赖稳定性：核心依赖 @wecom/aibot-node-sdk 为企业微信官方 SDK，若腾讯调整接口或字段，需等待插件更新适配。

日志安全：当前版本日志可能输出完整 corpId、userId 等敏感字段，建议生产环境配置日志脱敏或限制访问权限。

文件路径安全：媒体文件发送功能建议配合严格的沙箱边界验证，防止路径遍历风险（插件本身已做基础防护，但极端场景仍需关注）。

API 限流：企业微信官方 API 有频率限制（如每应用每企业最多 20 次/秒），高并发场景需合理规划或申请提额。