MagicPush 魔法推送

Appearance

元宝Bot 推送渠道配置指南# ​

本教程将指导你如何在 MagicPush（魔法推送）中配置元宝Bot 推送渠道，实现向微信私聊或群聊发送消息。

概述# ​

什么是元宝Bot 推送？# ​

元宝Bot 是腾讯推出的 AI Bot 平台，可以通过 WebSocket 连接，向微信用户或群组主动推送消息。

⚠️ 重要：元宝Bot 需要在元宝 App 中创建 Bot，并完成握手绑定后才能使用。

特点说明
推送目标微信个人（私聊）/ 微信群聊
鉴权方式AppKey + AppSecret（在元宝中创建 Bot 获取）
配置复杂度中，需要完成握手绑定
消息格式text（纯文本，Markdown 部分支持）
发送目标可选私聊或群聊

前置条件# ​

  • 已安装元宝 App（在微信中搜索「元宝」）
  • 在元宝中创建了 Bot 并获取 AppKey 和 AppSecret
  • 已部署并登录 MagicPush 管理后台#

第一步：在元宝中创建 Bot 并获取配置信息# ​

1.1 创建元宝 Bot# ​

  1. 打开元宝 App
  2. 进入 「Bot 管理」 或类似入口
  3. 点击 「创建 Bot」
  4. 填写 Bot 信息：
    • Bot 名称：如 MagicPush 通知
    • 描述：可选
  5. 创建成功后，会显示 AppKey 和 AppSecret#

🔐 重要：AppKey 和 AppSecret 是敏感凭证，请妥善保管。

1.2 获取 AppKey 和 AppSecret# ​

在 Bot 详情页可以找到：

配置项说明示例值
AppKeyBot 的应用 IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AppSecretBot 的密钥xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡 提示：AppSecret 只显示一次，请立即复制保存。如果遗忘需要重新生成。

1.3 选择发送目标（私聊 / 群聊）# ​

元宝Bot 支持两种发送目标：

模式说明需要额外配置
私聊（默认）向个人微信发送私聊消息需要完成握手绑定（获取 toUserId）
群聊向微信群发送群消息需要在群中 @Bot 发送一条消息（获取 groupCode）

第二步：完成握手绑定# ​

⚠️ 关键步骤：元宝Bot 渠道的 getConfigFields() 返回空数组，说明配置不是在网页表单中完成的，而是需要在元宝 App 中与 Bot 对话来完成握手绑定。

2.1 私聊模式绑定# ​

  1. 打开微信，搜索并打开你的 元宝 Bot
  2. 给 Bot 发送任意一条消息（如「绑定」）
  3. 系统会自动完成握手，并将你的 toUserId 写入 MagicPush 数据库#

✅ 绑定成功后，MagicPush 的渠道配置中会自动填充 toUserId。

2.2 群聊模式绑定# ​

  1. 将你的元宝 Bot 添加到微信群中
  2. 在群聊中 @你的 Bot 并发送任意一条消息
  3. 系统会自动获取群号（groupCode），并写入 MagicPush 数据库#

✅ 绑定成功后，MagicPush 的渠道配置中会自动填充 groupCode。

第三步：在 MagicPush 中添加渠道# ​

3.1 进入渠道管理# ​

  1. 登录 MagicPush 管理后台（默认地址 http://<服务器IP>:3000）
  2. 点击左侧导航 「渠道管理」
  3. 点击右上角 「+ 绑定渠道」 按钮#

3.2 选择渠道类型# ​

在弹出的对话框中，从渠道类型下拉列表中选择 「元宝Bot」。

3.3 填写配置信息# ​

根据第一步获取的信息，填写以下配置字段：

字段说明示例
AppKey在元宝中创建 Bot 后获得的 AppIDxxxxxxxx-xxxx-xxxx-...
AppSecret在元宝中创建 Bot 后获得的 AppSecretxxxxxxxxxxxxxxxx...
发送目标私聊（默认）或群聊私聊（默认） 或 群聊

💡 配置完成后，需要完成握手绑定（参考第二步）：

  • 如果选择私聊：请在元宝 App 中给 Bot 发一条消息
  • 如果选择群聊：请在群中 @Bot 发一条消息#

填写完成后，给渠道起一个易于辨识的名称（如「元宝Bot 私聊推送」），点击 「保存」。

3.4 测试连通性# ​

渠道创建成功后，在渠道卡片右侧的下拉菜单中，点击 「测试」 按钮。

  • ✅ 如果微信（私聊或群聊）收到测试消息，说明配置成功
  • ❌ 如果测试失败，请参考下方常见问题排查#

第四步：使用推送# ​

4.1 通过 API 推送# ​

创建渠道后，可以通过 MagicPush 的标准 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": "text"
  }'

📌 元宝Bot 只支持 text 类型消息。如果发送 markdown 或 html 类型，Markdown 会做基本清理后以纯文本发送。

4.2 指定发送目标（调用方控制）# ​

在 API 调用时，可以通过 target 参数显式指定发送目标：

json
{
  "title": "群聊告警",
  "content": "服务器 CPU 超过 90%",
  "type": "text",
  "target": "group"
}
target 值说明
private（默认）向个人发送私聊消息
group向微信群发送群消息

💡 如果调用时指定了 target，会覆盖渠道配置中的 sendTarget 设置。

技术细节# ​

WebSocket 连接管理# ​

MagicPush 通过 WebSocket 与元宝 Bot 平台保持长连接：

  1. 初始化：填写 AppKey + AppSecret 后，MagicPush 自动发起 WebSocket 连接
  2. 重连：如果连接断开，MagicPush 会自动重连（指数退避策略）
  3. 状态检查：发送前会检查 client.getState() === 'connected'#

握手绑定机制# ​

模式触发方式系统自动填充的字段
私聊用户给 Bot 发一条消息config.toUserId
群聊用户在群中 @Bot 发一条消息config.groupCode

💡 绑定信息存储在 MagicPush 数据库的渠道 config 字段中，无需手动填写。

消息格式处理# ​

原始 type处理方式
text直接发送
markdown保留基础 Markdown，做必要清理
html自动转换为纯文本

常见问题# ​

Q: 测试消息显示「尚未完成握手绑定」？# ​

原因：没有给 Bot 发送消息完成握手。

解决：

  1. 打开微信，搜索并打开你的元宝 Bot
  2. 给 Bot 发送任意一条消息
  3. 系统会自动完成握手绑定
  4. 重新点击测试

Q: 测试消息显示「未配置群号」？# ​

原因：群聊模式需要先 @Bot 发送一条消息来绑定群号。

解决：

  1. 将 Bot 添加到微信群中
  2. 在群中 @Bot 发送一条任意消息
  3. 系统会自动绑定群号
  4. 重新点击测试

Q: 发送消息返回「元宝 Bot WS 连接未就绪」？# ​

原因：WebSocket 连接尚未建立，或连接已断开。

解决：

  1. 检查 AppKey 和 AppSecret 是否填写正确
  2. 检查 MagicPush 服务器能否访问元宝 Bot WebSocket 地址
  3. 查看 MagicPush 日志，确认是否有连接错误
  4. 等待 10-30 秒，让系统自动重连

Q: 如何切换私聊和群聊模式？# ​

解决：

  1. 在 MagicPush 管理后台，编辑该渠道
  2. 修改 「发送目标」 字段（私聊 / 群聊）
  3. 根据新模式，重新完成握手绑定（私聊：给 Bot 发消息；群聊：在群中 @Bot 发消息）
  4. 保存后重新测试

Q: 元宝 App 是什么？如何创建 Bot？# ​

解决：

  1. 在微信中搜索 「元宝」 并打开
  2. 进入 Bot 管理界面（参考元宝 App 内指引）
  3. 创建 Bot 后获取 AppKey 和 AppSecret
  4. 参考 元宝 Bot 创建文档

Q: 与「微信龙虾机器人」渠道有什么区别？# ​

对比项微信龙虾机器人元宝Bot（本渠道）
底层协议ClawBot（第三方）元宝官方 Bot
握手方式ClawBot 桌面客户端微信对话（给 Bot 发消息）
推送限制10 条/窗口，需用户互动取决于元宝 Bot 平台限制
推荐场景个人微信推送元宝 Bot 生态

参考资源# ​

基于 MIT 许可证开源

© 2026 magiccode1412. All rights reserved.