手把手教你用nanobot搭建QQ聊天机器人：从配置到对话

1. 环境准备与快速部署

想要搭建一个属于自己的QQ聊天机器人吗？nanobot让这件事变得异常简单。这个超轻量级的AI助手框架只需要约4000行代码，就能提供强大的对话能力，比同类方案代码量少了99%。

首先，你需要准备一个合适的运行环境。nanobot支持多种部署方式，推荐使用CSDN星图镜像广场提供的预置镜像，这样能省去复杂的环境配置步骤。

系统要求：

• Linux系统（推荐Ubuntu 20.04+）
• Python 3.9+
• 至少8GB内存
• 支持CUDA的GPU（可选，但推荐用于更好的性能）

如果你选择手动安装，可以使用以下命令快速部署：

# 使用pip安装nanobot
pip install nanobot-ai

# 或者使用uv进行安装（推荐）
uv tool install nanobot-ai

不过对于大多数用户来说，直接使用预置镜像是更简单的方式。镜像已经内置了vllm部署的Qwen3-4B-Instruct-2507模型，开箱即用。

2. 基础概念快速入门

在开始配置QQ机器人之前，我们先简单了解几个核心概念：

nanobot是一个超轻量级的个人AI助手框架，它的设计理念是"小而美"。虽然代码量只有约4000行，但提供了完整的AI对话能力。

Qwen3-4B模型是阿里云开源的大语言模型，4B参数规模在保证效果的同时，对硬件要求相对友好。这个模型已经预置在镜像中，无需额外下载。

Chainlit是一个用于构建对话界面的Python库，nanobot使用它来提供Web交互界面。

消息总线是nanobot的核心机制，它负责在不同的通道（如QQ、Telegram等）和AI核心之间传递消息，确保各个组件相互独立又能够协同工作。

理解这些基本概念后，我们就能更好地进行后续的配置了。

3. 验证模型部署状态

在配置QQ机器人之前，我们需要先确认模型服务已经正常启动。这是确保后续步骤顺利进行的关键。

通过WebShell连接到你的实例，运行以下命令检查模型服务状态：

cat /root/workspace/llm.log

如果看到类似下面的输出，说明模型部署成功：

INFO:llm_service:Model loaded successfully
INFO:llm_service:Qwen3-4B-Instruct-2507 ready for inference

如果发现服务没有正常启动，可以尝试重新启动服务：

# 重启模型服务
cd /root/workspace
python -m llm_service

等待几分钟让模型加载完成。大型语言模型的加载需要一些时间，请耐心等待。

验证服务正常后，我们还可以通过Chainlit测试基础对话功能：

# 启动Chainlit界面
chainlit run app.py

在Web界面中输入测试问题，如"你好"，如果能够得到正常回复，说明整个系统运行正常。

4. 配置QQ机器人通道

现在来到最关键的步骤——配置QQ机器人。nanobot支持多种聊天平台，QQ是其中比较常用的一种。

4.1 注册QQ开放平台账号

首先访问QQ开放平台（https://q.qq.com/#/apps），注册个人或企业开发者账号。这个过程是免费的，按照页面提示完成注册即可。

注册成功后，进入开发者后台，点击"创建应用"，选择"机器人"类型。填写应用基本信息，如名称、描述等。这些信息后续可以修改，所以不用太过纠结。

4.2 获取AppID和AppSecret

创建应用后，在"开发管理"页面可以找到两个关键信息：AppID和AppSecret。这两个参数相当于机器人的身份证和密码，后续配置中需要用到。

重要提示：AppSecret是敏感信息，不要泄露给他人。如果怀疑泄露，可以在平台重新生成。

4.3 修改nanobot配置文件

有了AppID和AppSecret后，我们需要修改nanobot的配置文件来启用QQ通道：

# 打开配置文件
vim /root/.nanobot/config.json

找到channels配置部分，添加或修改QQ通道配置：

{
  "channels": {
    "qq": {
      "enabled": true,
      "appId": "你的AppID",
      "secret": "你的AppSecret", 
      "allowFrom": []
    }
  }
}

这里的allowFrom字段用于限制可以访问机器人的QQ号列表。如果留空，表示允许所有人访问。如果需要限制，可以填入特定的QQ号。

保存配置文件后，不需要重启模型服务，配置会自动生效。

5. 启动网关服务并测试

配置完成后，我们需要启动nanobot的网关服务来处理QQ消息。

5.1 启动网关服务

在终端中运行以下命令：

nanobot gateway

如果一切正常，你会看到类似下面的输出：

INFO:gateway:Starting gateway service...
INFO:gateway:QQ channel enabled
INFO:gateway:Gateway started on port 8080

这表示网关服务已经成功启动，正在监听QQ平台的消息。

5.2 测试QQ机器人

现在打开QQ，找到你创建的机器人账号（需要在QQ开放平台先配置好机器人的QQ号），发送一条测试消息：

你好，你是谁？

如果配置正确，你应该很快收到机器人的回复：

我是基于nanobot和Qwen3模型打造的智能助手，可以帮你解答问题、处理任务。有什么我可以帮助你的吗？

你也可以尝试一些更复杂的问题：

使用nvidia-smi看一下显卡配置

机器人会调用系统工具来查看显卡信息并返回结果。

5.3 常见问题解决

如果机器人没有响应，可以检查以下几个方面：

1. 网络连接：确保服务器可以正常访问外网，QQAPI需要对外通信
2. 配置信息：确认AppID和AppSecret填写正确，没有多余空格
3. 服务状态：检查网关服务是否正常运行，端口是否被占用
4. 权限设置：在QQ开放平台确认机器人权限配置正确

6. 高级功能与个性化定制

基础功能配置完成后，你还可以进一步定制你的QQ机器人。

6.1 添加自定义技能

nanobot支持技能系统，你可以为机器人添加特定领域的专业知识。技能文件使用Markdown格式，放在指定目录即可自动加载。

创建自定义技能文件：

# 创建技能目录
mkdir -p /root/.nanobot/workspace/skills

# 创建技能文件
vim /root/.nanobot/workspace/skills/my_skill.md

技能文件内容示例：

---
description: "我的自定义技能"
requires: {"bins": ["curl"]}
---

# 天气查询技能

这个技能可以查询指定城市的天气情况。

使用示例：查询北京的天气

6.2 配置多模型支持

除了预置的Qwen3模型，你还可以配置其他模型提供商：

{
  "providers": {
    "openrouter": {
      "enabled": true,
      "apiKey": "你的OpenRouter密钥"
    },
    "openai": {
      "enabled": false,
      "apiKey": "你的OpenAI密钥"
    }
  }
}

6.3 设置访问权限

通过配置文件可以精细控制机器人的访问权限：

{
  "channels": {
    "qq": {
      "allowFrom": ["123456789", "987654321"],
      "blockedFrom": ["111111111"],
      "rateLimit": 10
    }
  }
}

这样只有指定的QQ号可以访问机器人，并且限制了请求频率。

7. 总结回顾

通过本教程，我们完整地走过了用nanobot搭建QQ聊天机器人的全过程。从环境准备、模型验证，到QQ平台注册、配置修改，最后启动服务并测试。

关键步骤回顾：

1. 使用预置镜像或手动安装nanobot
2. 验证模型服务正常启动
3. 注册QQ开放平台并创建机器人应用
4. 修改配置文件启用QQ通道
5. 启动网关服务并测试对话功能

nanobot的优势在于其轻量化和模块化设计，让个人开发者也能轻松构建功能完善的AI助手。无论是用于学习研究还是实际应用，都是一个很好的选择。

现在你已经拥有了一个属于自己的QQ智能助手，可以继续探索更多高级功能，如添加自定义工具、集成其他聊天平台、优化对话体验等。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。