wecom-automation

用途

本技能用于企业微信个人账号的直连自动化，基于 Wechaty 框架连接企业微信个人账号，构建完整的 AI 助手功能，适用于企业微信机器人、自动化客服、个人助手等场景。

主要能力

自动同意好友添加：监听好友请求事件，自动通过好友验证，发送个性化欢迎消息，并标注用户信息和来源。
智能问答（基于知识库）：使用向量知识库存储企业知识，通过语义搜索匹配问题，由 LLM 生成专业回复，支持多轮对话上下文。
人工介入提醒：按置信度阈值自动判断，通过 Telegram/飞书通知人工，记录未解决问题用于优化，并平滑转接到人工客服。
消息类型支持：文本消息（问答、对话）、图片消息（OCR、识别）、文件消息（DOCX、PDF 等）、语音消息（转文字、语音交互）、链接消息（预览、摘要）、名片消息（保存、处理）。

技术架构

整体链路为：企业微信个人账号 → Wechaty（PadLocal）→ OpenClaw Gateway（消息分发、处理）→ 向量知识库（PG+pgvector）、LLM API（Kimi/GPT）、通知服务（Telegram）。

使用方式

方案选择：

方案 A：Wechaty + PadLocal（推荐，适合个人）。优点是配置简单、稳定性高、支持所有消息类型；缺点是 PadLocal 需要付费（约 50 元/月）、单账号限制。适用个人助手、小规模客服。
方案 B：企业微信内部应用 API（适合企业）。优点是官方 API 免费、稳定性最高、支持大规模部署；缺点是需要企业认证、配置相对复杂、功能受限于 API。

本技能使用方案 A（Wechaty + PadLocal）。

第一步：申请 PadLocal Token。访问 https://github.com/wechaty/wechaty ，选择 "PadLocal" 协议，注册账号并获取 Token，保存 Token 到 pass：pass insert api/wechaty-padlocal。

第二步：安装依赖。

# 1. 安装 Node.js 依赖
cd ~/clawd/skills/wecom-automation
npm install

# 2. 安装 Python 依赖
pip3 install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env

第三步：配置环境变量。编辑 ~/clawd/skills/wecom-automation/.env，包含 Wechaty 配置（WECHATY_PUPPET、WECHATY_TOKEN、WECHATY_LOG_LEVEL）、企业微信账号配置（WECOM_NAME、WECOM_QR_CODE_PATH）、知识库配置（KB_DB_URL、KB_SIMILARITY_THRESHOLD、KB_TOP_K）、LLM 配置（LLM_PROVIDER、LLM_API_KEY、LLM_API_BASE、LLM_MODEL）、人工介入通知（NOTIFICATION_CHANNEL、NOTIFICATION_ENABLED）、OpenClaw Gateway 配置（GATEWAY_URL、GATEWAY_TOKEN）。

第四步：初始化数据库。

# 创建数据库
sudo -u postgres createdb wecom_kb

# 初始化表结构
psql wecom_kb < ~/clawd/skills/wecom-automation/schema.sql

# 导入示例知识库
python3 ~/clawd/skills/wecom-automation/scripts/import_kb.py \
  --input ~/clawd/skills/wecom-automation/knowledge/sample.md \
  --category "常见问题" \
  --key "$(pass show api/kimi)"

第五步：启动机器人。

# 方式 1：直接运行
cd ~/clawd/skills/wecom-automation
npm start

# 方式 2：通过 PM2（推荐）
pm2 start ~/clawd/skills/wecom-automation/ecosystem.config.js

# 查看日志
pm2 logs wecom-bot

第六步：扫码登录。启动机器人后会显示二维码，使用企业微信扫码登录后，机器人即可正常工作。

适用场景

新好友自动欢迎：自动通过好友请求并发送欢迎消息，同时保存用户信息。
知识库问答：搜索知识库、生成答案，置信度低于阈值时转人工。
文件处理：接收 DOCX/PDF 等附件，下载并提取内容后回复。
人工介入提醒：向用户提示转接人工，通过 Telegram 通知人工客服，并记录未解决问题。

目录结构

~/clawd/skills/wecom-automation/
├── SKILL.md                    # 本文件
├── package.json                # Node.js 依赖
├── requirements.txt            # Python 依赖
├── ecosystem.config.js         # PM2 配置
├── .env.example                # 环境变量模板
├── schema.sql                  # 数据库表结构
├── bot.js                      # Wechaty 机器人主文件
├── config/
│   ├── knowledge.js            # 知识库配置
│   └── escalation.js           # 人工介入规则
├── workflows/
│   ├── on_friend_add.js        # 好友添加处理
│   ├── answer_question.js      # 问答处理
│   ├── handle_file.js          # 文件处理
│   └── escalate.js             # 人工介入
├── lib/
│   ├── knowledge.js            # 知识库操作
│   ├── llm.js                  # LLM 调用
│   ├── notification.js         # 通知服务
│   └── database.js             # 数据库操作
└── knowledge/
    └── sample.md               # 示例知识文档

高级功能

多轮对话记忆：使用 Redis 存储会话上下文。
文件处理：提取 DOCX 内容、提取 PDF 内容。
语音转文字：使用 Whisper API。
图片 OCR：使用 Kimi Vision。

监控与维护

日志查看：pm2 logs wecom-bot、pm2 logs wecom-bot --err、pm2 logs wecom-bot --lines 100。
性能监控：使用 prom-client 添加自定义指标（消息计数、回答延迟直方图）。
人工介入统计：通过 SQL 查询未解决问题分布与每日介入次数。

故障排查

无法扫码登录：检查 Wechaty 日志、重启机器人、清理缓存。
消息不回复：检查知识库连接、测试 LLM API、检查环境变量。
文件无法接收：检查临时目录权限、创建日志目录、检查磁盘空间。

安全最佳实践

密钥管理：所有密钥使用 pass 存储，环境变量引用不硬编码，定期轮换 Token。
数据隐私：客户信息加密存储，定期清理敏感日志，遵守数据保护法规。
访问控制：API 接口鉴权、IP 白名单限制、请求频率限制。
审计日志：记录所有人工介入，定期审查访问日志，异常行为告警。

扩展功能

主动营销：定期推送优惠信息。
群组管理：自动邀请用户加入群组。
数据统计：每日生成报表。

成本对比

Wechaty + PadLocal：约 50 元/月，适用个人、小团队。
企业微信内部应用：免费，适用企业、大规模。
企业微信客服 API：按量，适用企业客服。

限制

方案 A 依赖 PadLocal 付费服务，存在单账号限制。
方案 B 需要企业认证，配置相对复杂，功能受限于 API。
其他未在资料中明确说明的限制暂未提供。

技能介绍

用途