nanobot 本地部署指南：支持多通道（Web/CLI/QQ）统一调度
1. 项目简介
nanobot 是一款超轻量级的个人人工智能助手，灵感来源于 OpenClaw 项目。这个工具最大的特点是代码量极小，只需要约 4000 行代码就能提供核心的代理功能，相比类似功能的 Clawdbot 项目（需要 43 万行代码）小了 99%。
nanobot 内置了 vllm 部署的 Qwen3-4B-Instruct-2507 模型，使用 chainlit 作为推理界面。最吸引人的是，它支持多种使用方式：可以通过网页界面聊天，可以用命令行交互，还能接入 QQ 机器人，实现统一的消息调度和处理。
无论你是想本地部署一个私人 AI 助手，还是希望为团队搭建一个智能问答系统，nanobot 都是一个非常轻量且实用的选择。
2. 环境准备与快速部署
2.1 系统要求
在开始部署之前，请确保你的系统满足以下基本要求：
- 操作系统：Linux（推荐 Ubuntu 20.04+ 或 CentOS 7+）
- Python 版本：3.8 或更高版本
- 显卡：至少 8GB 显存的 NVIDIA 显卡（用于运行 4B 参数模型）
- 内存：建议 16GB 或以上
- 存储空间：至少 20GB 可用空间
2.2 一键部署步骤
nanobot 的部署过程相当简单，只需要几个命令就能完成：
# 克隆项目仓库
git clone https://github.com/sonhhxg/nanobot.git
cd nanobot
# 创建 Python 虚拟环境
python -m venv venv
source venv/bin/activate
# 安装依赖包
pip install -r requirements.txt
# 启动模型服务
python serve_model.py
部署完成后，模型服务会自动在后台运行。整个过程通常需要 10-20 分钟，具体时间取决于你的网络速度和硬件性能。
3. 验证部署状态
3.1 检查模型服务
部署完成后，首先需要确认模型服务是否正常运行。打开终端，输入以下命令：
cat /root/workspace/llm.log
如果看到类似下面的输出，说明模型部署成功：
Model loaded successfully
vLLM engine initialized
Ready for inference
这个日志文件记录了模型加载和初始化的全过程，如果遇到问题，可以在这里找到详细的错误信息。
3.2 测试 chainlit 界面
nanobot 默认使用 chainlit 提供网页聊天界面。在浏览器中访问 http://localhost:8000，你应该能看到一个简洁的聊天界面。
在输入框中尝试提问，比如：'你能做什么？'或者'介绍一下你自己'。如果一切正常，你会看到模型生成的回复。
4. 基本功能使用
4.1 网页聊天界面
chainlit 提供的网页界面是最简单的使用方式。界面分为三个主要部分：
- 左侧边栏：显示聊天历史记录
- 主聊天区域：显示当前对话内容
- 底部输入框：用于输入问题
你可以在这里进行各种问答，比如技术问题咨询、代码编写帮助、文档生成等。
4.2 命令行交互
除了网页界面，nanobot 也支持命令行方式使用：
# 启动命令行交互模式
python cli_client.py
# 或者直接通过 curl 调用 API
curl -X POST "http://localhost:8000/api/chat" \
-H "Content-Type: application/json" \
-d '{"message": "使用 nvidia-smi 看一下显卡配置"}'
命令行方式特别适合集成到脚本中，或者需要批量处理问答的场景。
4.3 实际使用示例
让我们尝试一个实际的技术问题。在聊天界面中输入：
使用 nvidia-smi 看一下显卡配置
nanobot 会理解你的意图，并尝试执行相应的命令来获取显卡信息。返回结果可能类似：
根据当前环境，显卡配置如下：
GPU 0: NVIDIA GeForce RTX 4090, 显存：24GB
驱动程序版本：535.86.05
CUDA 版本：12.2
这表明 nanobot 不仅能够理解自然语言指令，还能执行相应的系统命令并返回结果。
5. 接入 QQ 机器人扩展
5.1 注册 QQ 开放平台
要让 nanobot 支持 QQ 聊天机器人，首先需要注册 QQ 开放平台账号：
- 访问 QQ 开放平台官网：https://q.qq.com/#/apps
- 点击'注册'，选择个人或企业开发者类型
- 完成实名认证和邮箱验证
注册过程完全免费，个人开发者也能正常使用。
5.2 创建机器人应用
注册成功后，按照以下步骤创建机器人：
- 在控制台点击'创建应用'
- 选择'机器人'应用类型
- 填写应用基本信息：名称、描述、图标等
- 提交审核（通常几分钟就能通过）
创建完成后，记下分配给你的 AppID 和 AppSecret，后面配置时需要用到。
5.3 配置 nanobot 支持 QQ 通道
现在需要修改 nanobot 的配置文件来启用 QQ 支持：
vim /root/.nanobot/config.json
在配置文件中找到或添加 QQ 通道配置：
{
"channels": {
"qq": {
"enabled": true,
"appId": "你的 AppID",
"secret": "你的 AppSecret",
"allowFrom": ["允许的 QQ 号或群号"]
}
}
}
保存文件后，需要重启服务使配置生效。
5.4 启动网关服务
QQ 机器人的消息需要通过网关服务转发给 nanobot。启动网关服务：
nanobot gateway
如果启动成功，你会看到类似下面的输出：
Gateway service started on port 8080
QQ channel enabled
Ready to receive messages
这个网关服务负责接收 QQ 平台的消息，转发给 nanobot 处理，然后再把回复发送回 QQ。
5.5 测试 QQ 机器人
现在你可以打开 QQ，向配置好的机器人发送消息了。尝试问一些技术问题：
帮我写一个 Python 爬虫代码
或者执行系统命令：
查看当前服务器状态
机器人会像在网页界面中一样智能地回答你的问题。
6. 多通道统一调度
nanobot 最强大的功能之一是支持多通道统一调度。这意味着无论用户从哪个渠道发送消息（网页、命令行、QQ），nanobot 都能统一处理并保持对话上下文。
6.1 消息路由机制
nanobot 内部有一个智能的消息路由系统：
# 简化的消息处理流程
def handle_message(message, channel_type):
# 统一预处理所有消息
processed_msg = preprocess_message(message)
# 根据消息内容选择处理方式
if is_system_command(processed_msg):
response = execute_system_command(processed_msg)
else:
# 调用 AI 模型生成回复
response = generate_response(processed_msg)
# 根据渠道类型格式化回复
formatted_response = format_for_channel(response, channel_type)
return formatted_response
这种设计确保了不同渠道的用户体验一致性。
6.2 会话状态管理
nanobot 会为每个用户会话维护独立的状态：
- 网页会话：基于浏览器 cookie
- CLI 会话：基于终端进程 ID
- QQ 会话：基于 QQ 用户/群 ID
这样就能实现连续的对话，模型能够记住之前的对话上下文，提供更连贯的体验。
7. 常见问题与解决方法
7.1 模型加载失败
如果模型服务启动失败，首先检查：
# 检查显存是否足够
nvidia-smi
# 检查依赖包是否完整
pip list | grep vllm
确保显存至少 8GB，并且所有依赖包都已正确安装。
7.2 QQ 机器人无法连接
如果 QQ 机器人无法正常工作：
- 检查 AppID 和 AppSecret 是否正确
- 确认网络防火墙允许出站连接
- 查看网关服务日志：
tail -f gateway.log
7.3 响应速度慢
如果感觉响应速度较慢，可以尝试：
# 调整模型参数优化速度
python serve_model.py --max_num_seqs 4 --tensor_parallel_size 1
或者考虑使用量化版本的模型来减少显存占用和提高速度。
8. 总结
通过本指南，你应该已经成功部署了 nanobot，并配置好了多通道支持。这个超轻量级的 AI 助手虽然代码量很小，但功能相当强大：
主要优势：
- 部署简单，几行命令就能完成
- 支持多种使用方式：网页、命令行、QQ
- 统一的消息调度和处理机制
- 极低的资源占用，适合个人使用
适用场景：
- 个人技术助手：帮助解决编程问题
- 团队协作工具：通过 QQ 群提供技术支持
- 自动化脚本：集成到 CI/CD 流程中
- 学习研究：了解 AI 助手的工作原理
无论你是开发者、技术爱好者还是团队负责人，nanobot 都能提供一个简单而强大的 AI 助手解决方案。它的轻量级设计使得部署和维护都非常简单，而多通道支持则让使用更加灵活方便。
