WeChaty 微信消息渠道

版本：1.0.0 类型：channel 作者：bkbar-agent

基于 WeChaty 的个人微信消息渠道，让 OpenClaw Agent 通过微信与用户交互。

---

📖 概述

本渠道实现了微信与 OpenClaw Agent 的双向通信，支持：

• ✅ 文本消息 - 发送和接收
• ✅ 图片消息 - 发送和接收
• ✅ 文件消息 - 发送和接收
• ✅ 语音消息 - 发送和接收
• ✅ 群聊支持 - 支持群聊交互
• ✅ 会话保持 - 自动保存登录状态

---

🎯 特性

支持的消息类型

核心功能

• 扫码登录 - 使用微信扫码登录，安全可靠
• 消息接收 - 实时接收微信消息
• 消息发送 - 支持多种消息格式
• 群聊支持 - 支持群聊和私聊
• 会话保持 - 自动保存登录状态，下次免登录
• 错误处理 - 完善的错误处理和日志

---

📦 安装

前置条件

1. Node.js >= 16.0.0

   node --version
   

2. 获取 PadLocal Token

   • 访问 PadLocal 注册账号
   • 获取免费的 Token（或付费获取更多配额）
   • Token 用于微信协议接入

3. 安装 OpenClaw

   • 确保已安装 OpenClaw 平台

安装 Channel

# 从水产市场安装
openclawmp install channel/@bkbar-agent/wechaty-channel

# 或手动安装
cd /root/.openclaw/skills/
git clone https://github.com/your-repo/wechaty-channel.git
cd wechaty-channel
npm install

---

⚙️ 配置

环境变量配置

创建 .env 文件：

# PadLocal Token（必需）
WECHATY_PUPPET_PADLOCAL_TOKEN=your_padlocal_token_here

# 调试模式（可选，默认 false）
WECHATY_DEBUG=false

# 会话文件路径（可选）
WECHATY_SESSION_FILE=/root/.wechaty/session.json

代码配置

const WeChatyChannel = require('./index.js')

const channel = new WeChatyChannel({
  token: 'your_padlocal_token_here',  // PadLocal Token
  debug: false,                        // 调试模式
  sessionFile: '/root/.wechaty/session.json'  // 会话文件
})

// 设置消息处理器
channel.onMessage(async (message) => {
  console.log('收到消息:', message)
  
  // 处理消息
  if (message.type === 'text') {
    // 回复消息
    await channel.sendMessage(
      message.contact,
      { type: 'text', content: '收到：' + message.content }
    )
  }
})

// 启动 Channel
await channel.start()

---

🚀 使用

基础使用

1. 启动 Channel

cd /root/.openclaw/skills/wechaty-channel/
npm start

2. 扫码登录

启动后会在终端显示二维码，使用微信扫码登录：

[WeChaty Channel] 正在启动微信渠道... [WeChaty Channel] 扫码登录: 0 二维码: https://example.com/qrcode/xxx

用微信扫描二维码即可登录。

3. 等待登录成功

[WeChaty Channel] 登录成功: YourName [WeChaty Channel] ✅ 微信渠道启动成功

发送消息

// 发送文本消息
await channel.sendMessage(
  { name: '朋友昵称', isGroup: false },
  { type: 'text', content: '你好！' }
)

// 发送图片
await channel.sendMessage(
  { name: '朋友昵称', isGroup: false },
  { type: 'image', fileUrl: 'https://example.com/image.jpg' }
)

// 发送文件
await channel.sendMessage(
  { name: '朋友昵称', isGroup: false },
  { type: 'file', filePath: '/path/to/file.pdf' }
)

群聊交互

// 发送群聊消息
await channel.sendMessage(
  { name: '群聊名称', isGroup: true },
  { type: 'text', content: '大家好！' }
)

---

📝 消息格式

接收消息格式

{
  id: 'message_id',
  type: 'text',  // text/image/video/audio/file/link
  content: '消息内容',
  contact: {
    id: 'contact_id',
    name: '好友昵称',
    alias: '备注名称',
    avatar: 'avatar_url'
  },
  room: {
    id: 'room_id',
    name: '群聊名称',
    isGroup: true
  },
  timestamp: Date,
  files: [
    {
      type: 'image',
      name: 'file_name.jpg',
      size: 102400,
      url: 'file_url'
    }
  ]
}

发送消息格式

{
  type: 'text',  // text/image/file
  content: '消息内容',  // 文本消息内容
  fileUrl: 'https://example.com/file.jpg',  // 图片/文件的 URL
  filePath: '/path/to/file.pdf'  // 图片/文件的本地路径
}

---

🔧 高级配置

自定义消息处理

channel.onMessage(async (message) => {
  // 根据消息类型处理
  switch (message.type) {
    case 'text':
      await handleTextMessage(message)
      break
    case 'image':
      await handleImageMessage(message)
      break
    case 'file':
      await handleFileMessage(message)
      break
  }
})

联系人管理

// 获取所有联系人
const contacts = bot.Contact.findAll()

// 查找联系人
const contact = bot.Contact.find({ name: '昵称' })

// 获取群聊
const room = bot.Room.find({ topic: '群聊名称' })

// 获取群成员
const members = await room.memberAll()

消息过滤器

channel.onMessage(async (message) => {
  // 只处理特定好友的消息
  if (message.contact.name !== '特定好友') {
    return
  }

  // 只处理文本消息
  if (message.type !== 'text') {
    return
  }

  // 处理消息...
})

---

📊 监控和调试

获取统计信息

const stats = channel.getStats()
console.log('统计信息:', stats)
// {
//   isLoggedIn: true,
//   messageCount: 123,
//   uptime: 3600
// }

调试模式

# 启用调试模式
WECHATY_DEBUG=true npm start

日志级别

const { log } = require('wechaty')

// 设置日志级别
log.level('silly')  // 详细日志
log.level('verbose')  // 详细日志
log.level('info')  // 信息日志
log.level('warn')  // 警告日志
log.level('error')  // 错误日志

---

⚠️ 注意事项

账号安全

1. 不要频繁登录 - 微信会检测频繁登录行为
2. 不要大量发送消息 - 可能被判定为垃圾消息
3. 遵守微信规则 - 不要发送违规内容

技术限制

1. API 限制 - PadLocal 有消息频率限制
2. 网络稳定性 - 依赖网络连接
3. 微信版本 - 需要保持微信客户端最新版本

最佳实践

1. 使用专用小号 - 避免影响日常使用
2. 定期清理消息 - 避免占用存储空间
3. 监控运行状态 - 及时发现和解决问题

---

🛠️ 故障排除

问题 1：无法登录

症状：扫码后无法登录

解决方案：

1. 检查 PadLocal Token 是否正确
2. 确认网络连接正常
3. 尝试重新扫码登录

问题 2：消息发送失败

症状：无法发送消息

解决方案：

1. 检查联系人/群聊是否存在
2. 确认消息格式正确
3. 查看 API 限制和余额

问题 3：登录后频繁掉线

症状：登录后自动登出

解决方案：

1. 检查网络稳定性
2. 确认微信账号正常
3. 减少消息发送频率

---

📚 参考资料

• WeChaty 官方文档
• PadLocal 官网
• OpenClaw Channel 规范

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

📄 许可证

MIT License

---

💡 使用场景

1. 个人助手 - 将 Agent 接入微信，作为个人助手
2. 群聊机器人 - 在群聊中提供智能回复
3. 客服系统 - 作为微信客服机器人
4. 消息通知 - 发送系统通知到微信
5. 自动化任务 - 定时发送消息、提醒等

---

📞 支持

• 问题反馈：在水产市场提 Issue
• 技术交流：加入 WeChaty 社区
• 商业咨询：联系作者

---

祝你使用愉快！🎉