文档 · 快速上手 · 文档打不开？

简介

NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架，它基于 Python 的类型注解和异步特性，能够为你的需求实现提供便捷灵活的支持。

特色

• 异步优先：基于 Python 的异步特性，即使是非常大量的消息，也能吞吐自如

• 易于开发：配合 NB-CLI 脚手架，代码编写上手简单，没有过多的冗余代码，可以让开发者专注于业务逻辑

• 生而可靠：100% 类型注解覆盖，配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 (编辑器支持)

• 社区丰富：社区用户众多，直接和间接用户超过十万人，每天都有大量的活跃用户 (社区资源)

• 海纳百川：一个框架，支持多个聊天软件平台，可自定义通信协议

  协议名称	状态	注释
  OneBot（仓库，协议）	✅	支持 QQ、TG、微信公众号、KOOK 等平台
  Telegram（仓库，协议）	✅
  飞书（仓库，协议）	✅
  GitHub（仓库，协议）	✅	GitHub APP & OAuth APP
  QQ（仓库，协议）	✅	QQ 官方接口调整较多
  Console（仓库）	✅	控制台交互
  Red（仓库，协议）	✅	QQNT 协议
  Satori（仓库，协议）	✅	支持 Onebot、TG、飞书、微信公众号、Koishi 等
  Discord（仓库，协议）	✅	Discord Bot 协议
  DoDo（仓库，协议）	✅	DoDo Bot 协议
  Kritor（仓库，协议）	✅	Kritor (OnebotX) 协议，QQNT 机器人接口标准
  Mirai（仓库，协议）	✅	QQ 协议
  Milky（仓库，协议）	✅	QQNT 机器人应用接口标准
  钉钉（仓库，协议）	🤗	寻找 Maintainer（暂不可用）
  开黑啦（仓库，协议）	↗️	由社区贡献
  Ntchat（仓库）	↗️	微信协议，由社区贡献
  MineCraft（仓库）	↗️	由社区贡献
  Walle-Q（仓库）	↗️	QQ 协议，由社区贡献
  Villa（仓库）	❌	米游社大别野 Bot 协议，官方已下线
  Rocket.Chat（仓库，协议）	↗️	Rocket.Chat Bot 协议，由社区贡献
  Tailchat（仓库，协议）	↗️	Tailchat 开放平台 Bot 协议，由社区贡献
  Mail（仓库）	↗️	邮件收发协议，由社区贡献
  黑盒语音（仓库，协议）	↗️	黑盒语音机器人协议，由社区贡献
  微信公众平台（仓库，协议）	↗️	微信公众平台协议，由社区贡献
  Gewechat（仓库，协议）	❌	Gewechat 微信协议，Gewechat不再维护及可用
  EFChat（仓库，协议）	↗️	恒五聊平台协议，由社区贡献
  VoceChat （仓库，协议）	↗️	VoceChat 平台协议，由社区贡献
  B站直播间（仓库，Web API 协议，开放平台协议）	↗️	B站直播间（Web API/开放平台）协议，由社区贡献

• 坚实后盾：支持多种 web 框架，可自定义替换、组合

  驱动框架	类型
  FastAPI	服务端
  Quart（异步 Flask）	服务端
  aiohttp	客户端
  httpx	客户端
  websockets	客户端

更多：概览

什么不是 NoneBot2

NoneBot2 并不是某个特定平台或协议的具体实现，它仅负责与现有的协议适配器进行通信，并处理接收到的事件。因此，“NoneBot 是否支持某平台的某某功能？”这类问题与 NoneBot2 无关。请查阅相应平台的功能文档，或联系该平台的协议适配开发者以获取答案。

NoneBot2 也并非 NoneBot1 的替代品。事实上，这两个版本目前都在积极维护中。不过，如果你希望尝试新功能，或者需要支持更多平台，那么可以考虑使用 NoneBot2。

NoneBot2 和 NoneBot1 的区别，就像 VisualStudio Code 和 VisualStudio 一样

即刻开始

完整 文档可以在 这里 查看。

懒得看文档？下面是快速安装指南：

1. 安装 pipx

   python -m pip install --user pipx
   python -m pipx ensurepath
   

2. 安装脚手架

   pipx install nb-cli
   

3. 使用脚手架创建项目

   nb create
   

4. 运行项目

   nb run
   

社区资源

常见问题

• 常见问题解答(FAQ)
• 论坛(Discussion)

教程/实际项目/经验分享

• awesome-nonebot

插件

此外，NoneBot2 还提供了丰富的官方及第三方现成插件供用户使用：

• NoneBot-Plugin-Docs：可将离线文档集成到本地项目中（再也不用担心文档打不开啦！）

  在项目目录下执行：

  nb plugin install nonebot_plugin_docs
  

  或者尝试以下镜像：

  • 文档镜像(中国境内)

• 其他插件请查看 商店

许可证

NoneBot 采用 MIT 许可证进行开源

本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于适销性、特定用途适用性及非侵权性的担保。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论其是基于合同、侵权行为或其他原因而产生，且与本软件或其使用有关。

贡献

请参考 贡献指南

鸣谢

赞助者

感谢以下产品对 NoneBot 项目提供的赞助：

         

    

感谢以下赞助者对 NoneBot 项目提供的资金支持：

开发者

感谢以下开发者对 NoneBot2 作出的贡献：

NoneBot2 快速上手指南

NoneBot2 是一个现代、跨平台、可扩展的 Python 异步机器人框架。本指南将帮助你快速搭建环境并运行第一个机器人。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Windows, macOS 或 Linux
• Python 版本：3.10 或更高版本
• 包管理工具：pip (通常随 Python 安装) 或 uv/poetry
• 推荐编辑器：VS Code 或 PyCharm (配合类型检查插件体验更佳)

提示：国内用户建议使用国内镜像源加速依赖下载，后续安装命令已默认配置清华源。

安装步骤

推荐使用官方提供的命令行工具 nb-cli 来初始化项目，它会自动处理依赖和配置文件。

1. 安装 nb-cli

打开终端，执行以下命令安装脚手架工具（使用清华镜像源）：

pip install nb-cli -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 创建新项目

使用 nb 命令创建一个新的 NoneBot2 项目：

nb create

按照终端提示操作：

1. 输入项目名称（例如：my-bot）。
2. 选择适配器（推荐新手选择 OneBot V11 以对接 QQ 等平台，或 Console 进行本地测试）。
3. 确认创建。

3. 进入项目目录

cd my-bot

4. 安装项目依赖

在项目目录下运行以下命令安装核心库及所选适配器：

nb run

首次运行时，nb-cli 会自动检测并安装 pyproject.toml 中定义的依赖。

基本使用

下面演示如何编写一个简单的指令插件，当用户发送 /hello 时，机器人回复"Hello, World!"。

1. 创建插件文件

在项目根目录下的 src/plugins 文件夹中，新建一个文件 hello.py。

2. 编写代码

在 hello.py 中输入以下代码：

from nonebot import on_command
from nonebot.adapters import Message
from nonebot.params import CommandArg

# 创建一个匹配 "/hello" 命令的处理器
hello_cmd = on_command("hello", priority=5, block=True)

@hello_cmd.handle()
async def handle_hello(args: Message = CommandArg()):
    # 获取命令参数（可选）
    arg_str = args.extract_plain_text()
    
    if arg_str:
        await hello_cmd.finish(f"Hello, {arg_str}!")
    else:
        await hello_cmd.finish("Hello, World!")

3. 配置连接 (以 OneBot V11 为例)

如果你选择了 OneBot 适配器，需要配置机器人连接信息。 打开项目根目录下的 .env 文件，填入你的机器人配置（以下为示例，需替换为实际数据）：

# .env 文件内容
HOST=127.0.0.1
PORT=8080
ONEBOT_ACCESS_TOKEN=your_token_here

注意：如果你使用的是反向 WebSocket 连接，请在对应的聊天软件客户端（如 go-cqhttp 或 Lagrange）中配置连接地址为 ws://127.0.0.1:8080/onebot/v11/ws。

4. 运行机器人

在项目根目录下执行以下命令启动机器人：

nb run

如果看到类似 Running NoneBot... 的日志且无报错，说明启动成功。现在尝试在聊天窗口发送 /hello，机器人将会回复你。

---

更多高级用法（如事件监听、权限控制、定时任务等），请访问 NoneBot2 官方文档。