指南 / Guides

让任意 AI agent 直接给你的微信发消息、读历史 —— 纯后台 LLDB,不碰 UI,不重签 WeChat.app,不重新登录。对上层框架,wechat-use 暴露三个稳定的网络面:本地 HTTP+SSE bridge、Wechaty Puppet gRPC gateway、以及可远程调用的 REST /v1。底层全部走同一个 wechatd daemon,没有第二套业务逻辑。

先看端口图

三个面,三个 loopback 端口。18401 和 18402 由同一个 wechat-wechaty-gateway 进程一起起。

# 18400  本地 HTTP + SSE bridge   →  wechat-bridge 进程
# 18401  Wechaty Puppet gRPC      →  wechat-wechaty-gateway 进程
# 18402  REST /v1(可走 tunnel 远程)→  同一个 gateway 进程

面一:本地 HTTP + SSE bridge(18400)

最通用的入口。wechat-bridge 绑在 127.0.0.1:18400,只走 loopback。给 agent 提供 REST 读写 + 一条 SSE 实时消息流。

入口 & 鉴权

• 启动:装好后 LaunchAgent ai.wechat.bridge 常驻;端口用 --port 或 WECHAT_BRIDGE_PORT 改。
• 鉴权:设了 WECHAT_BRIDGE_BEARER 就要求 Authorization: Bearer <x>;/health 永远公开。

路由

• GET /health · /chats · /unread · /contacts · /resolve
• GET /chat/{wxid} · GET /chat/{wxid}/history
• GET /messages/stream —— SSE 实时消息推送,毫秒级延迟
• POST /send

例子

# 拿一个起始游标(别用 since=0,否则回填全部历史 1.3MB+)
$ wechat new-messages -n 1 --json    # 取里面的 create_time

# 订阅实时消息流
$ curl -N http://127.0.0.1:18400/messages/stream?since=1719800000

# 发一条
$ curl -XPOST http://127.0.0.1:18400/send -d '{"to":"wxid_xxx","text":"hi"}'

Hermes shape —— 接 n8n / Dify 零改造

加 --shape hermes(或走 BridgeShape)后,多出一个 POST /typing,并且 SSE 的 wire shape 切成和 Hermes 的 WhatsApp-bridge 完全一致。所以 n8n / Dify / 各种 webhook adapter 直接对接,不用写适配层 —— 这是首选的框架集成路径。

群里想「只 @ 才回」?设 WECHAT_BRIDGE_GROUP_MENTION_ONLY=1,没被 @ 的群消息在 wire 层就丢掉。

面二:Wechaty Puppet gRPC gateway(18401)

wechat-wechaty-gateway 在 127.0.0.1:18401 上实现标准 Wechaty Puppet 服务(tonic gRPC)。任何现成的 Wechaty TS SDK bot 把 gRPC puppet 指到这个地址、带上 bearer,相对普通 Wechaty puppet 零代码改动就能跑在真实 macOS 微信账号上。

已实现的 Puppet RPC

真实现的部分(节选):start / stop / version / ding / logout、contact_list / contact_payload / contact_alias / contact_avatar、message_send_text / message_payload / message_image / message_file、以及 friendship_search_phone / friendship_add / friendship_accept 等。消息事件通过订阅 daemon 推流给 gRPC 客户端。

鉴权模式(WECHATY_GATEWAY_AUTH_MODE)

• static —— 需要 WECHATY_GATEWAY_BEARER
• jwt —— 需要 WECHATY_GATEWAY_JWKS_URL + _JWT_ISS + _JWT_AUD
• 本地开发:WECHATY_GATEWAY_DEV_INSECURE=1。缺 bearer / JWKS 时 fail-fast。

// 一个普通 Wechaty bot,puppet 指到本地 gateway
const bot = WechatyBuilder.build({
  puppet: 'wechaty-puppet-service',
  puppetOptions: {
    endpoint: '127.0.0.1:18401',
    token: process.env.WECHATY_GATEWAY_BEARER,
  },
})

面三:REST /v1 bridge(18402)—— 远程调用

版本化的 JSON REST,由 gateway 进程和 gRPC 一起起在 127.0.0.1:18402。给 LangChain / 自定义 agent / 远程服务用,可本地直连,也可以透过 Cloudflare Tunnel 远程暴露。

路由

• GET /health —— 公开,返回探针签名,让 profile-api 能确认 tunnel 指向的是真 gateway
• GET /v1/sessions?limit=&offset=
• GET /v1/contacts?limit=&offset=
• GET /v1/history?conversation_id=&limit=&offset=
• GET /v1/new-messages?since_ts=&limit= —— 返回 max_ts 供游标翻页
• POST /v1/send body {"to":"wxid_xxx","text":"...","mentions":[...]}

鉴权和 gRPC gateway 共用同一个 AuthMode(static bearer / jwt),每个数据路由都过 subscription gate。

远程暴露:wechat-use tunnel

想让公网上的 agent / Worker 调用本机微信,用 Cloudflare Tunnel 把 18402 安全穿出去。需要你自己的 CF zone。

# 一键 11 步:装 cloudflared → 建 tunnel → CNAME → 起服务
# → 等 /health 200 → 注册 → 把 bridge 鉴权从 static 翻成 jwt
$ wechat tunnel setup --hostname wx.yourdomain.com

$ wechat tunnel status              # cloudflared 健康 + 远端可达 + 当前鉴权模式
$ wechat tunnel token                # 给远程 bot 铸一个 1h TTL 的 JWT
$ wechat tunnel teardown             # 拆掉,翻回 static,保留 ~/.cloudflared 复用

选哪个面 —— 按框架对号入座