danni-cool/wechatbot-webhook · 上手攻略

• 仓库：danni-cool/wechatbot-webhook
• 链接：https://github.com/danni-cool/wechatbot-webhook
• 分类：integration / webhook(微信机器人)
• 作者：spark
• 更新：2026-08-20

---

是什么

wechatbot-webhook 是一个轻量、可自部署的微信个人号机器人,通过 HTTP webhook 暴露收/发消息能力,不需要企业微信认证、不需要公众号、不需要第三方平台账号。典型用法是把 n8n / Coze / 自家 AIGC 应用 / 自动化脚本的"通知 + 双向对话"接到个人微信上。

⚠️ 项目目前基于 Web 微信协议,作者已明示:大概两天一掉线,除了正常功能修补,不接新的 feature request。Windows 协议分支 windows 是 WIP(Work In Progress),当前生产可用性 = web 协议 = 不推荐做关键业务承载。这条限制会贯穿下面的所有命令和场景判断。

解决什么问题

1. 个人通知:CI 跑完 / 监控告警 / 定时任务 / Cron 结果 → 直接发到手机微信。比邮件及时,比 Server 酱便宜/不依赖第三方。
2. AIGC 应用的消息节点:Coze / Dify / 自建 LLM 应用 → webhook → 微信用户。让微信成为 LLM 应用的"前端"。
3. n8n / 自动化工作流的中转:把任何能发 HTTP POST 的节点(SSM、监控系统、爬虫)接到微信。
4. 个人号多端同步:用 webhook 把消息转发到 Telegram / Slack / 飞书 / Discord,做多通道备份。
5. 快速搭一个"反方向的 Webhook":用户给机器人发消息 → 项目 POST 到你的 RECVD_MSG_API → 你处理后用 webhook 发回。

快速安装

方式 A:npx(最简)

npx wechatbot-webhook

要求 Node.js >= 18.14.1(issue #227 提到过版本兼容问题)。默认端口 3001。除非掉线,默认记住上次登录——换号用 npx wechatbot-webhook -r。

启动后日志会输出一个 token 和登录 URL,形如:

https://localhost:3001/login?token=YOUR_PERSONAL_TOKEN

浏览器打开,扫码登录微信 web 版。

方式 B:Docker(推荐生产)

docker pull dannicool/docker-wechatbot-webhook
docker run -d --name wxBotWebhook -p 3001:3001 \
  -v ~/wxBot_logs:/app/log \
  dannicool/docker-wechatbot-webhook
docker logs -f wxBotWebhook   # 找二维码 / 登录地址

支持 arm64 + amd64。日志按天切分,形如 app.2024-01-01.log。

方式 C:docker-compose

wget -O docker-compose.yml \
  https://cdn.jsdelivr.net/gh/danni-cool/wechatbot-webhook@main/docker-compose.yml
docker-compose down
docker-compose -p wx_bot_webhook up

方式 D:包管理器迁移提示

项目已迁到 pnpm(支持 patches),从源码构建时请用 pnpm:

pnpm install

核心用法

1. 发送文字(单条)

URL: POST http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]

curl --location 'http://localhost:3001/webhook/msg/v2?token=YOUR_PERSONAL_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "testUser",
    "data": { "content": "你好👋" }
  }'

2. 发送图片(URL 自动解析)

curl --location 'http://localhost:3001/webhook/msg/v2?token=YOUR_PERSONAL_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "testUser",
    "data": {
      "type": "fileUrl",
      "content": "https://download.samplelib.com/jpeg/sample-clouds-400x300.jpg?$alias=cloud.jpg"
    }
  }'

$alias query 参数用来自定义收方看到的文件名。

3. 发送本地文件(multipart)

URL: POST http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN]

curl --location --request POST 'http://localhost:3001/webhook/msg?token=YOUR_PERSONAL_TOKEN' \
  --form 'to=testGroup' \
  --form content=@"$HOME/demo.jpg" \
  --form 'isRoom=1'

⚠️ 本地文件一次只能发一个,多文件手动调用多次。

4. 群发 + 多条消息

curl --location 'http://localhost:3001/webhook/msg/v2?token=YOUR_PERSONAL_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[
    { "to": "testUser1", "data": { "content": "你好👋" } },
    { "to": "testUser2", "data": [
        { "content": "你好👋" },
        { "content": "近况如何?" }
    ] }
  ]'

5. 接收消息(RECVD_MSG_API)

通过环境变量把项目反向 webhook 到你的服务:

docker run -d --name wxBotWebhook -p 3001:3001 \
  -e RECVD_MSG_API="https://example.com/your/url" \
  -e LOGIN_API_TOKEN="abcdefg123" \
  -v ~/wxBot_logs:/app/log \
  dannicool/docker-wechatbot-webhook

收到消息时项目会 POST 一份 FormData 到 RECVD_MSG_API,type 字段是核心调度维度:

type 类别	取值
用户消息	text / urlLink / file / friendship
系统事件	system_event_login / system_event_logout / system_event_error / system_event_push_notify
其他	unknown(未实现类型)

详细 spec 见 docs/recvdApi.example.md。

6. 关键环境变量

变量	作用	默认
LOG_LEVEL	日志输出级别(info / debug)	info(文件始终 debug)
RECVD_MSG_API	收消息回调 URL	未设 = 不接收
ACCEPT_RECVD_MSG_MYSELF	是否接收自己发的消息	false
LOGIN_API_TOKEN	自定义登录 token	随机生成
DISABLE_AUTO_LOGIN	禁用自动登录(每次扫码)	false

典型适用场景

1. 个人开发者监控告警:把 Prometheus AlertManager / uptime-kuma / 自家 cron 的告警推到微信。
2. AIGC 应用 demo / 玩具级产品:注意——两天一掉线,不适合做严肃产品承载;但 demo、PoC、内部工具够用。
3. n8n / Coze 工作流节点:n8n 内置 HTTP Request 节点对接 webhook/msg/v2,把任何上游事件落到微信。
4. 学习 webhook 模式:本项目是少有的双向 webhook(收 + 发)完整实现,可作学习样本。
5. 微信群自动回复 / 关键词机器人:RECVD_MSG_API 接到自己的关键词服务,实现"@机器人 -> 调 LLM -> 回复"。
6. 多通道备份:把微信消息 forward 到 Telegram / Slack,做个人消息归档。

坑与注意

⚠️ 两天一掉线是设计内限制,作者明示不接新 feature。Windows 协议分支(windows)在 WIP,不要把生产 SLA 压在这上面——适合"丢了不致命"的通知场景。

⚠️ 协议被微信官方限制风险:Web 微信协议长期处于"灰色"状态,微信随时可能封禁或限制。生产化部署前考虑替代品(企业微信、微信客服、公众号模板消息)。

⚠️ 不要用于"接收账号、密码、token"等敏感消息:FormData content 是明文 POST 到 RECVD_MSG_API,中间链路过长(浏览器扫码 → 服务器 → webhook → 你的服务),假设其中任一节点被攻破即泄漏。

⚠️ Node 版本钉死 >= 18.14.1,否则 npm install 会失败(issue #227)。npx 用户注意本地 Node 版本,Docker 用户不用管。

⚠️ pnpm 强制:包管理器已迁移,源码构建用 npm 装不上或运行报错。

⚠️ to 字段的语义陷阱:isRoom=false 时 to 是个人昵称(支持 {alias: '备注名'});isRoom=true 时是群名(不支持 alias)。群名和个人昵称可能撞名,所以需要 isRoom 显式区分。

⚠️ v1 和 v2 接口并存:/webhook/msg 是 v1(本地文件),/webhook/msg/v2 是 v2(JSON + URL 解析 + 群发)。新代码一律用 v2;v1 见 docs/legacy-api.md,仅作迁移参考。

⚠️ API 鉴权 token 只在 URL query 里:URL 会进入日志、Prometheus、access log,不要用 token 当"主密钥"——一旦泄漏请立刻重启换 token。

⚠️ 掉线后重新登录需要扫码:容器化部署时,Docker 不会自动开 GUI,需要走 /login?token=... URL 在能访问微信扫码的设备上登录。

与同类对比

项目	协议	稳定性	部署难度	适用
danni-cool/wechatbot-webhook(本文)	Web 微信	⚠️ 两天一掉线	极低(npx / Docker)	个人通知 / demo
企业微信自建应用	企业微信 API	✅ 高	中(企业认证)	公司场景
微信公众号模板消息	公众号	✅ 高	高(服务号 + 微信认证)	推送通知
Server 酱 / WxPusher	第三方聚合	中(依赖第三方)	极低	极简通知
itchat / itchat-uos	Web 微信 Python	⚠️ 同类风险	低	Python 栈
wechaty	多协议抽象	中(模块化)	中	长跑 Agent / 客服
直接调微信小程序云函数	小程序	✅ 高	高(需开发小程序)	高频正式业务

核心判断:个人 toy / 临时通知 → 选 wechatbot-webhook(本项目);公司业务 → 必须走企业微信;长期客服机器人 → wechaty + 付费 UOS 协议。

一句话推荐结论

个人 / 内部工具,想 5 分钟把 webhook 接到个人微信 → 用它,接受"两天一掉线";严肃业务承载 → 别用它,走企业微信或 wechaty + UOS。

---

进阶:接入模式与生产化决策

1. 三种典型接入模式

模式 A:单向通知型(80% 用户)

你的服务 / cron / 监控
       ↓ HTTP POST
   webhook/msg/v2
       ↓
   微信用户收到消息

代码最简,只要一个 curl 就能跑。适合告警、通知、提醒。

模式 B:双向对话型(LLM 应用)

微信用户发消息 → wechatbot-webhook
                      ↓ POST RECVD_MSG_API
                你的服务(LLM / 业务逻辑)
                      ↓ 响应
                wechatbot-webhook → webhook/msg/v2 → 微信用户

需要部署一个能处理 FormData 的 HTTP 服务端点。最常见的坑:RECVD_MSG_API 返回后,业务侧要主动调用 webhook/msg/v2 发回消息,两段链路独立,没有内建 request-response 关联。

模式 C:群机器人型(关键词触发)

群成员 @机器人 / 关键词
       ↓
   wechatbot-webhook
       ↓
   RECVD_MSG_API(只处理特定消息)
       ↓
   webhook/msg/v2(只发到触发群)

适合内部群工具(天气预报、翻译、问答机器人)。

2. n8n 接入示意

n8n 是项目 README 主推的对接工具。HTTP Request 节点配置:

Method: POST
URL: http://wechatbot-host:3001/webhook/msg/v2?token=YOUR_TOKEN
Body (JSON):
{
  "to": "{{ $json.recipient }}",
  "data": { "content": "{{ $json.message }}" }
}

反向:Trigger 节点接收 RECVD_MSG_API 的 FormData,后续节点按 type 字段路由。

3. 部署架构建议

单机 docker-compose(个人 / 小团队):

services:
  wxbot:
    image: dannicool/docker-wechatbot-webhook
    ports:
      - "3001:3001"
    volumes:
      - ./logs:/app/log
    environment:
      - LOGIN_API_TOKEN=your-secret-token
      - LOG_LEVEL=info
    restart: unless-stopped

Nginx 反代 + HTTPS(暴露到公网,给远程 webhook 调用):

server {
  listen 443 ssl;
  server_name wxbot.example.com;

  ssl_certificate     /etc/letsencrypt/live/wxbot.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/wxbot.example.com/privkey.pem;

  location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

多账号(团队 / 多微信分流):

每个微信号独立跑一个容器,改映射端口 + 独立 token。不要共享 token,否则任何一端 token 泄漏都会污染全局。

4. 安全姿态

风险	缓解
Token 进入日志	token 只放环境变量,不要塞 URL 路径;日志/审计前先 mask
Webhook 被恶意调用	nginx 层限速 + fail2ban;webhook/msg/v2 内部鉴权已启用,但应用层要再加一道
RECVD_MSG_API 被探测	反代上加 basic auth + IP 白名单
容器挂掉无人值守	restart: unless-stopped + Uptime 监控容器本身
微信协议被封	准备 Plan B(企业微信 / 公众号 / Telegram),不要单点
敏感消息(密码/token)泄漏	绝对不要让机器人接收,项目没做端到端加密

5. 掉线运维手册

按 README 描述,~48h 一次掉线,自动化运维建议:

1. 掉线检测:项目主动 POST system_event_logout 到 RECVD_MSG_API;业务侧监听此事件 → 触发告警。
2. 重新登录:/login?token=... URL 需要在能访问微信扫码的设备上打开;远程重启后无法自愈。
3. session 持久化:-v ~/wxBot_logs:/app/log 已经把 session 持久化到宿主机,容器重启不丢失;但微信主动踢下线后 session 失效,需要重新扫码。
4. 降级策略:掉线期间业务侧走邮件 / Telegram / 短信兜底,不要让用户面对"机器人离线"硬错误。

6. 与 Coze / Dify 等 Agent 平台对接

Coze 内置 webhook 节点,Dify 有 HTTP 节点,都支持 webhook/msg/v2。典型用法:

• Coze 工作流结尾 → HTTP POST → wechatbot-webhook → 用户
• 用户在微信发消息 → RECVD_MSG_API → 转发到 Dify 的 chatbot API → Dify 响应 → webhook/msg/v2 → 用户

Coze / Dify 适合做"业务逻辑层",wechatbot-webhook 适合做"消息通道层",各司其职。

7. 故障排查清单

现象	检查
启动后找不到登录 URL	docker logs -f wxBotWebhook,检查 token 是否输出
扫码后报"登录失败"	检查 DISABLE_AUTO_LOGIN、清理 /app/log 后重启
发消息返回 success: false	检查 to 字段(昵称 / 群名是否一致)、isRoom 设置
RECVD_MSG_API 没收到消息	检查环境变量是否注入、容器日志看 POST 状态码
节点版本报错	node -v 必须 ≥ 18.14.1
掉线频繁	减发送频率(协议风控)、换账号、不要在同 IP 跑多个 bot

8. 升级与维护

项目仍在迭代,但因为协议限制,版本更新主要在 docker image tag,代码层面不会有大重构。升级流程:

docker pull dannicool/docker-wechatbot-webhook:latest
docker-compose down
docker-compose -p wx_bot_webhook up -d
docker logs -f wxBotWebhook   # 确认正常启动

⚠️ 升级前先看 release notes,有些版本会改 API 路径(/webhook/msg/v1 → /v2)。token 格式也可能变。

---

决策清单:什么时候用 / 不用

✅ 用: - 个人 toy / 临时通知 / demo - 内部工具通知(监控告警 / 任务完成) - AIGC 应用 PoC(可接受掉线) - 学习 webhook 双向模式 - 多通道备份的一个节点

❌ 不用: - 严肃业务承载(电商客服 / 支付通知 / 医疗) - 高频双向对话(>100 条/小时,协议风控风险) - 涉及敏感数据(token / 密码 / 个人隐私) - 企业合规要求严格(协议灰色) - 需要长期 SLA 承诺的场景

---

主要来源 - 仓库 README:https://github.com/danni-cool/wechatbot-webhook - 接收消息 API spec:docs/recvdApi.example.md - v1 legacy API:docs/legacy-api.md - Docker Hub:dannicool/docker-wechatbot-webhook - npm 包:wechatbot-webhook(npx wechatbot-webhook) - 关键 issue:Web 协议风险#142(企业微信不支持)、Node 版本#227 - 协议:web(main 分支,生产可用) / windows(WIP 分支,不可用) - 当前 release tag:latest(对应 web 协议,Docker Hub)