nonebot-plugin-grok-bot

把 NoneBot2 接入 Grok Bot：

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

安装

uv add nonebot-plugin-grok-bot            # 基础
uv add "nonebot-plugin-grok-bot[savepic]" # 启用本地表情包

驱动器需要同时具备 ASGI 和 HTTP 客户端，例如 DRIVER=~fastapi+~httpx+~aiohttp。

配置

Grok Bot 只能访问公网或 Tailscale 网络内的地址，HOST 需要绑定到对应网卡（例如 Tailscale IP 或 0.0.0.0）。

白名单

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

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

路由

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

[
  {
    "name": "owner",
    "sessions": ["private:*"],
    "webhook_url": "https://api2.cursor.sh/automations/webhook/<routine-id>",
    "webhook_key": "crsr_xxx",
    "owner_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
  }
]

推送时机：

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

Webhook Payload

{
  "route": "groups",
  "trigger": "owner",
  "session": "group:123456",
  "messages": [
    {
      "session": "group:123456",
      "message_id": "1001",
      "time": "2026-10-10T18:00:00+08:00",
      "sender": {"user_id": "10000", "nickname": "Yan", "is_owner": 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": "微笑"}
      ]
    }
  ]
}

trigger 为 owner / size / interval。图片直接给原始链接，插件不缓存。QQ 图片链接里的 rkey 会过期，通过 MCP get_image(url) 查看或在 send_message 中转发时，插件会自动调用 get_rkey 重新签发（需要 NapCat / LLOneBot 等支持该扩展 API 的实现）。

MCP 工具

开发

uv sync
uv run pytest
uv run python bot.py