微信龙虾机器人推送渠道配置指南
本教程将指导你如何在 MagicPush（魔法推送）中配置微信龙虾机器人推送渠道，实现向个人微信推送消息。
概述
什么是微信龙虾机器人？
微信龙虾机器人（ClawBot）是一款可以让个人微信接收推送消息的工具。通过桌面客户端配置后，可以调用 API 向个人微信发送消息。
⚠️ 重要限制： 微信龙虾机器人有主动推送限制：
- Bot 连续主动发送 10 条消息后，需要用户主动发一条消息才能继续推送
- 自用户上次主动发消息起 24 小时后，也需要用户主动发消息才能继续推送 MagicPush 会自动追踪额度并在接近限制时提醒你。
| 特点 | 说明 |
|---|---|
| 推送目标 | 个人微信（通过 ClawBot 桌面客户端） |
| 鉴权方式 | Token + toUserId（通过 ClawBot 客户端配置） |
| 配置复杂度 | 低，通过桌面客户端完成握手绑定 |
| 消息格式 | text、markdown（微信龙虾机器人已支持） |
| 频率限制 | 10 条/窗口，24 小时窗口 |
前置条件
- 已安装并运行 微信 ClawBot 桌面客户端
- 已部署并登录 MagicPush 管理后台
第一步：通过 ClawBot 桌面客户端完成配置
1.1 安装并登录 ClawBot 桌面客户端
- 下载并安装 微信 ClawBot 桌面客户端（请参考官方获取方式）
- 打开客户端，使用微信扫码登录
1.2 获取 Token 和 toUserId
📌 配置方式说明： 微信龙虾机器人渠道的
getConfigFields()返回空数组，说明其配置不是在 MagicPush 网页表单中填写的，而是通过 ClawBot 桌面客户端 进行握手绑定后自动写入数据库的。
绑定流程：
- 在 ClawBot 桌面客户端中，找到 「MagicPush 集成」 或类似配置入口
- 配置 MagicPush 的服务器地址
- 完成握手绑定后，客户端的 Token 和你的 toUserId 会自动保存到 MagicPush 的渠道配置中
💡 如果你是直接修改数据库或配置文件来填写配置，需要填写：
配置项 说明 来源 tokenClawBot 的 API Token ClawBot 桌面客户端 toUserId推送目标用户 ID ClawBot 桌面客户端 baseUrlClawBot API 地址（可选，默认 https://ilinkai.weixin.qq.com）客户端配置 contextToken上下文 Token（可选） 客户端配置
第二步：在 MagicPush 中添加渠道
2.1 进入渠道管理
- 登录 MagicPush 管理后台（默认地址
http://<服务器IP>:3000） - 点击左侧导航 「渠道管理」
- 点击右上角 「+ 绑定渠道」 按钮
2.2 选择渠道类型
在弹出的对话框中，从渠道类型下拉列表中选择 「微信龙虾机器人」。
2.3 完成握手绑定
由于该渠道的配置是通过 ClawBot 桌面客户端完成的：
- 创建渠道后，打开 ClawBot 桌面客户端
- 在客户端中找到 「渠道绑定」 或 「MagicPush 绑定」 功能
- 输入 MagicPush 的服务器地址和渠道 ID
- 完成握手绑定（客户端会自动将 Token 和 toUserId 写入 MagicPush）
2.4 测试连通性
渠道配置完成后，在渠道卡片右侧的下拉菜单中，点击 「测试」 按钮。
- ✅ 如果个人微信收到「这是一条来自魔法推送的测试消息」，说明配置成功
- ❌ 如果测试失败，请参考下方常见问题排查
💡 额度提醒：测试消息也计入 10 条/窗口的限制。接近限制时，MagicPush 会在消息末尾自动追加提醒。
第三步：使用推送
3.1 通过 API 推送
bash
curl -X POST http://<服务器IP>:3000/api/push/<渠道ID> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <你的API Token>" \
-d '{
"title": "系统告警",
"content": "服务器 CPU 使用率超过 90%，请及时处理",
"type": "markdown"
}'支持的消息类型（type 参数）：
| type 值 | 说明 |
|---|---|
text | 纯文本消息（默认） |
markdown | Markdown 格式消息（微信龙虾机器人已支持） |
html | HTML 格式（MagicPush 会自动转换为纯文本） |
技术细节
主动推送限制与自动提醒
微信龙虾机器人的限制：
| 限制类型 | 数值 | 说明 |
|---|---|---|
| 连续主动推送 | 10 条/窗口 | 超过后需用户主动发消息 |
| 时间窗口 | 24 小时 | 超期后需用户主动发消息 |
MagicPush 自动追踪并提醒：
- 计数：每次主动推送后，
sendCount自动 +1（写入数据库） - 提醒阈值：达到 9 条时，消息末尾自动追加提醒
- 时间提醒：距离 24 小时窗口过期不足 10 分钟时，也追加提醒
提醒文本示例：
[提示] 回复任意消息以保持机器人推送畅通（已发送 9/10 条）
（窗口剩余约 15 分钟，回复任意消息可重置）如何重置额度？
让用户（你）主动给机器人发一条任意消息，即可重置：
- 连续推送计数（
sendCount→ 0） - 24 小时窗口（重新开始计时）
常见问题
Q: 发送消息失败，提示「需要用户主动发消息」？
原因：触发了主动推送限制（10 条/窗口 或 24 小时窗口过期）。
解决：
- 打开微信，给机器人（ClawBot）主动发一条任意消息
- MagicPush 会自动重置计数和窗口时间
- 重新发送消息
Q: 测试消息成功，但实际推送失败？
原因：可能 contextToken 过期，或网络无法连接 ClawBot 服务。
解决：
- 在 ClawBot 桌面客户端中重新登录或刷新 Token
- 确认 MagicPush 服务器可以访问 ClawBot API 地址（
baseUrl） - 检查 ClawBot 客户端是否在线
Q: 如何查看当前已使用的推送额度？
解决：
- 直接查看 MagicPush 数据库中该渠道的
config.sendCount字段 - 或在 ClawBot 桌面客户端中查看额度状态
Q: Markdown 消息格式不正确？
原因：微信龙虾机器人已支持 Markdown，但支持的元素有限。
解决：
- 使用基础 Markdown 语法（加粗、标题、引用等）
- 不支持的元素（图片、表格）不会渲染
- 可以先使用
text类型测试
Q: 24 小时窗口是如何计算的？
回答：
- 从用户最后一次主动发消息的时间开始计算
- 如果用户在 24 小时内没有主动发消息，窗口过期
- 过期后需要用户主动发一条消息来重置窗口
Q: 为什么我的配置表单中没有字段？
原因：微信龙虾机器人渠道的 getConfigFields() 返回空数组，配置是通过 ClawBot 桌面客户端 握手绑定后自动写入的。
解决：
- 确保 ClawBot 桌面客户端已安装并登录
- 在客户端中完成与 MagicPush 的绑定流程
- 如果无法使用客户端，可以手动修改数据库中渠道的
config字段
参考资源
- 微信 ClawBot 官方文档（请替换为实际链接）
- MagicPush GitHub 仓库