nonebot-plugin-grok-bot

✨ 通过 MCP Server 与 Webhook 将聊天接入 Grok Bot ✨

📖 介绍

把 NoneBot2 接入 Grok Bot：

• 发送：插件在 NoneBot 自身的 FastAPI 上挂载一个 MCP Server（Streamable HTTP），Grok Bot 通过它发送消息，支持图文混排、QQ 内置表情和本地表情包（基于 savepic）。
• 接收：收到的消息按会话路由，POST 到对应 Grok Bot Routine 的 Webhook。

💿 安装

nb plugin install nonebot-plugin-grok-bot

uv add nonebot-plugin-grok-bot

pip install nonebot-plugin-grok-bot

pdm add nonebot-plugin-grok-bot

poetry add nonebot-plugin-grok-bot

plugins = ["nonebot_plugin_grok_bot"]

如需使用本地表情包，请安装 savepic 可选依赖（例如 pip install "nonebot-plugin-grok-bot[savepic]"），并按 savepic 的说明完成配置。

⚙️ 配置

驱动器需要同时具备 ASGI 和 HTTP 客户端，例如：

DRIVER=~fastapi+~httpx+~aiohttp

通过 Tailscale 暴露 MCP 端点

NoneBot 保持监听 127.0.0.1，由 Tailscale 只转发 MCP 路径（不要把整个端口暴露出去，否则 OneBot 的连接端点也会一起暴露）：

# 仅 tailnet 内可访问（Grok Bot 所在机器需加入同一 tailnet）
tailscale serve --bg --set-path /grok_bot http://127.0.0.1:8080/grok_bot

# 或：公网可访问（需在 tailnet ACL 中为该节点开启 funnel）
tailscale funnel --bg --set-path /grok_bot http://127.0.0.1:8080/grok_bot

# 查看 / 撤销
tailscale serve status
tailscale serve reset

需要在 Tailscale 管理后台开启 MagicDNS 与 HTTPS 证书。之后在 .env.prod 中把域名加入 GROK_BOT_MCP_ALLOWED_HOSTS，并在 Grok Bot 中添加 MCP 连接器：

• URL：https://mybox.tail1234.ts.net/grok_bot/mcp
• Secret：Authorization: Bearer <GROK_BOT_MCP_TOKEN>

在 nonebot2 项目的.env文件中添加下表中的必填配置

白名单

• 私聊只接受 Master 和 GROK_BOT_ALLOWED_USERS。
• 群聊只接受 GROK_BOT_ALLOWED_GROUPS。

白名单外的消息不记录、不推送，MCP 也不能向其发送。

路由

会话标识为 group:<群号>、private:<QQ号>、channel:<guild>/<channel>。路由按顺序匹配（fnmatch），首个命中的生效；未命中的会话不推送。

[
  {
    "name": "master",
    "sessions": ["private:*"],
    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
    "webhook_key": "crsr_xxx",
    "master_trigger": "always"
  },
  {
    "name": "groups",
    "sessions": ["group:*"],
    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
    "webhook_key": "crsr_xxx",
    "flush_interval": 300,
    "flush_size": 30,
    "max_pending": 100
  }
]

推送时机：

• Master 的消息：按路由的 master_trigger 决定是否立即推送（并带上该会话中尚未推送的消息）。
  • always：Master 任何发言都推送，适合私聊和特殊群。
  • to_me（默认）：仅 @bot、回复 bot 或私聊时推送，群里普通发言不推送。
  • never：Master 也不触发。
• 其他人的消息：先积压，满 flush_size 条或第一条积压消息之后过了 flush_interval 秒时推送；两者都不设置时，只作为上下文等 Master 触发。
• bot 自己发出的消息：只记入上下文，不触发推送。

🎉 使用

Webhook 推送格式

{
  "route": "groups",
  "trigger": "master",
  "session": "group:123456",
  "session_name": "某某群",
  "messages": [
    {
      "session": "group:123456",
      "session_name": "某某群",
      "message_id": "1001",
      "time": "2026-10-10T18:00:00+08:00",
      "sender": {"user_id": "10000", "nickname": "Yan", "group_role": "member", "is_master": true, "is_self": false},
      "to_me": false,
      "segments": [
        {"type": "text", "text": "看看这个"},
        {"type": "image", "url": "https://multimedia.nt.qq.com.cn/download?appid=1407&fileid=…&rkey=…", "sticker": false},
        {"type": "emoji", "id": "14", "name": "微笑"},
        {"type": "forward", "id": "7391..."},
        {"type": "file", "id": "/abc-123", "name": "report.pdf", "size": "20480", "url": null}
      ]
    }
  ]
}

trigger 为 master / size / interval。sender.is_master 表示是否为 Master（Bot 主人，由配置指定）；sender.group_role 是群内身份（owner 群主 / admin 管理员 / member 成员，私聊为 null），两者互不相关。session_name 为群名（OneBot get_group_info，首次收到该群消息时获取并缓存）或私聊对象昵称。引用消息以 {"type": "reply", "message_id", "sender", "segments"} 出现在消息开头，附带被引用消息的发送者与内容（只展开一层）。合并转发（聊天记录）只给出 id，需要时通过 MCP get_forward_message 查看；收到的文件通常不带下载链接（url 为 null），需要时通过 MCP get_file 换取。图片直接给原始链接，插件不缓存。QQ 图片链接里的 rkey 会过期，通过 MCP get_image(url) 查看或在 send_message 中转发时，插件会自动调用 get_rkey 重新签发（需要 NapCat / LLOneBot 等支持该扩展 API 的实现）。

MCP 工具

send_message / send_file 中的 url（以及本地表情包）均由 NoneBot 下载或读取后以 base64:// 交给协议端，因此 url 只需 NoneBot 能访问即可——可以使用 tailnet 等内网地址（如 http://atri.tail9c544d.ts.net:8000/report.pdf），无需公网暴露，也不依赖协议端（如 Docker 中的 NapCat）的网络、DNS 与文件系统。

开发

uv sync
uv run pytest
uv run python bot.py