当前位置：首页 > news >正文

微信机器人开发实战：Wechaty SDK 从入门到 Token 服务化

news 2026/6/15 21:26:42

想把微信变成可编程的接口？给业务加上自动回复、消息转发、群管理？Wechaty 是目前最成熟的微信个人号 Bot SDK，本文带你从零搭建一个属于自己的微信机器人。

## 架构一览

```
你的代码 (JS/Python/Go) → Wechaty SDK → Puppet (协议层) → 微信
```

Wechaty 本身是上层 API，真正和微信通信的是 Puppet。常用 Puppet：

| Puppet | 协议 | 状态 |
|--------|------|------|
| wechaty-puppet-wechat4u | Web 微信 | ✅ 免费可用 |
| wechaty-puppet-padlocal | iPad | 付费 |
| wechaty-puppet-service | Token 网关 | 自建 |

## 最小可用代码

6 行 JavaScript 启动一个 Bot：

```javascript
const { WechatyBuilder } = require('wechaty')
const bot = WechatyBuilder.build({ puppet: 'wechaty-puppet-wechat4u' })

bot.on('scan', qr => console.log('扫码:', qr))
bot.on('login', u => console.log('登录:', u.name()))
bot.on('message', m => console.log('消息:', m.text()))
bot.start()
```

跑起来就会打印二维码，微信扫码即上线。

## 实用功能清单

### 1. 消息路由

```javascript
bot.on('message', async (msg) => {
if (msg.self()) return // 忽略自己发的
if (msg.type() !== Message.Type.Text) return

const text = msg.text()
const talker = msg.talker()

if (text.includes('帮助')) await talker.say('发送"天气"查天气')
if (text.includes('天气')) await talker.say('今天晴，22°C')
if (text.includes('群号')) await talker.say('AI Agent全栈技术交流群：463866405')
})
```

### 2. 好友请求自动通过

```javascript
bot.on('friendship', async (friendship) => {
if (friendship.type() === Friendship.Type.Receive) {
await friendship.accept()
// 通过后发欢迎语
const contact = friendship.contact()
await contact.say('你好！我是 AI 助手，发送"帮助"查看功能')
}
})
```

### 3. 群管理 — 欢迎新成员

```javascript
bot.on('room-join', async (room, inviteeList, inviter) => {
const topic = await room.topic()
const names = inviteeList.map(c => c.name()).join('、')
await room.say(`欢迎 ${names} 加入「${topic}」！\n\n本群交流 AI Agent 开发，请先看群公告`)
})
```

### 4. HTTP API 桥接

把 Bot 包装成 HTTP 服务，外部系统也能调用：

```javascript
const http = require('http')
http.createServer(async (req, res) => {
const { contactName, text } = JSON.parse(await body(req))
const contact = await bot.Contact.find({ name: contactName })
await contact.say(text)
res.end(JSON.stringify({ ok: true }))
}).listen(9527)
```

## Token 模式：让你的 Bot 变成云服务

上面的模式只能在你自己机器上跑。如果想做成 SaaS，需要 Token 模式：

```
Token Server (Docker) → 绑定微信号扫码 → 对外暴露 gRPC 端口
→ 客户端拿 Token 远程调用 → 无需自己扫码
```

核心命令：

```bash
export WECHATY_PUPPET=wechaty-puppet-wechat4u
export WECHATY_TOKEN=***
export WECHATY_PUPPET_SERVER_PORT=8788

docker run -d --network=host \
-e WECHATY_PUPPET \
-e WECHATY_TOKEN \
-e WECHATY_PUPPET_SERVER_PORT \
wechaty/wechaty
```

Token 自动注册到 Wechaty 的 discovery 服务，客户端填入 Token 即可接入。这也就是市面上「微信机器人 Token」产品的底层原理。

## 踩坑记录

**400 != 400 错误** — wechat4u 协议偶尔会报这个，不影响使用，底层自动重试。

**联系人缓存** — `Contact.findAll()` 建议登录后立即执行并缓存，否则后续 find 可能查不到。

**扫码时效** — Web 微信二维码约 2 分钟有效，到期后需要重新生成。

**消息去重** — 微信可能重复推送同一条消息，业务侧需要做 id 去重。