NanoBot 作为一款由香港大学数据科学实验室开发的超轻量级 AI 助手框架，以仅 4000 行代码实现了传统 AI 助手框架 99% 的核心功能，成为开发者研究和定制个人 AI 助手的理想选择。本文将系统讲解 NanoBot 的环境搭建流程，帮助你快速从源码层面掌握这一高效工具。

前期准备工作

在开始 NanoBot 环境搭建前，需确保开发环境满足以下基础运行条件：

• 操作系统兼容性：兼容 Linux、macOS 系统，Windows 用户建议通过 WSL（Windows Subsystem for Linux）环境运行
• Python 环境要求：需安装 Python 3.8 及以上版本以确保依赖包兼容性
• 硬件资源配置：建议配置至少 4GB 内存及 1GB 可用磁盘空间以保障基础运行
• 可选扩展组件：Node.js 18 + 版本（用于 WhatsApp 消息通道集成）、vLLM（本地大模型部署支持）、Docker（容器化部署环境）

针对 Windows 系统用户，建议优先安装 Python 3.12 版本，可通过 python.org 官方渠道获取安装包，按默认配置完成基础安装。

安装过程

PyPi 快速安装方案

采用 PyPi 仓库进行快速部署的命令如下：

bash

pip install nanobot-ai

该安装方式会自动处理所有依赖项，包括 AI 模型交互库、工具调用框架等核心组件。

源码开发环境配置

如需进行二次开发或源码研究，推荐采用源码编译安装方式：

bash

git clone https://github.com/HKUDS/nanobot.git cd nanobot python -m venv venv source venv/bin/activate # Linux/macOS环境激活虚拟环境 venv\Scripts\activate # Windows环境激活虚拟环境 pip install -e .详细来源

uv 现代化安装方式

针对追求依赖安装效率的开发者，可使用 uv 包管理工具：

bash

pip install uv uv tool install nanobot-ai

uv 工具相比传统 pip 在依赖解析速度上有显著提升，平均可减少 60% 的安装时间。

核心命令解析

完成安装后，系统将提供nanobot核心命令，包含以下关键子命令：

onboard：初始化配置向导

bash

nanobot onboard

执行该命令将在用户主目录创建.nanobot配置目录，包含：

• config.json：系统核心配置文件
• workspace/：工具操作的沙箱目录（提供文件操作安全边界）
• 模板文件集合（AGENTS.md 代理定义模板、SOUL.md 人格配置模板等）

首次执行时若检测到已存在配置文件，系统会提示是否覆盖，建议选择保留原有配置（输入 N）以防止 API 密钥等敏感信息丢失。

agent：交互式对话模式

bash

nanobot agent -m "你的问题"

这是最直接的人机交互方式，系统将加载当前配置和工作空间，启动交互式对话循环。

gateway：多平台接入服务

bash

nanobot gateway

启动多平台网关服务，支持 Telegram、飞书、Discord 等即时通讯平台接入，默认服务监听地址为 0.0.0.0:18790。

配置文件深度解析

配置文件~/.nanobot/config.json作为系统核心配置中心，主要包含三个功能模块：

agents 配置模块

定义 AI 代理的基础行为参数：

json

"agents": { "defaults": { "workspace": "~/.nanobot/workspace", "model": "gemini-3-pro-preview", "provider": "auto", "maxTokens": 8192, "temperature": 0.7 } }

providers 配置模块

存储各 AI 模型服务提供商的认证信息：

json

"providers": { "openrouter": { "apiKey": "sk-or-v1-你的密钥" }, "gemini": { "apiKey": "YOUR_API_KEY" }, "vllm": { "apiKey": "dummy", "apiBase": "http://localhost:8000/v1" } }

gateway 配置模块

设置多平台接入服务的网络参数：

json详细来源

"gateway": { "host": "0.0.0.0", "port": 18790 }

调试验证环节

完成安装后，建议首先执行环境状态检查：

bash

nanobot status

若命令返回系统配置信息和服务运行状态，则表明基础环境部署成功。

进行基础功能验证：详细来源

bash

nanobot agent -m "你能做什么？"

若 AI 返回功能清单列表，说明系统已具备完整交互能力。

常见问题及避坑技巧

API 密钥配置错误

• 症状表现：命令执行后无响应或返回 401/403 认证错误
• 解决方案：检查 API 密钥是否存在多余空格或字符，确认模型名称与提供商配置匹配

配置文件覆盖风险

• 潜在问题：重复执行nanobot onboard时选择覆盖会导致现有配置丢失
• 处理建议：始终选择保留旧配置（N），系统会自动合并新增配置字段

模型访问权限限制

• 常见问题：部分高级模型需要申请特殊访问权限
• 替代方案：可使用 wellapi.ai 等 API 中转服务获取测试额度进行功能验证

Windows 路径解析问题

• 故障现象：Windows 环境下出现路径找不到或权限错误
• 解决方法：推荐使用 WSL 环境，或确保路径中不包含中文及特殊符号

扩展功能与应用场景

NanoBot 提供丰富的功能扩展机制：

• 多通道集成：支持 Telegram、Discord、飞书等主流通讯平台接入
• 技能系统：通过 skills 目录结构扩展工具调用能力
• 本地模型部署：配合 vLLM 服务运行 Qwen2.5 等开源大模型
• 任务调度：实现定时提醒、自动报告生成等自动化工作流

典型应用场景包括：个人知识管理系统、代码开发辅助工具、自动化办公流程、实时信息监控平台等详细来源

总结与展望

NanoBot 凭借精简的代码架构、清晰的模块设计和便捷的部署流程，为 AI 助手开发提供了优质的学习与实践平台。通过本文介绍的配置步骤，你已具备从源码层面探索和定制 AI 助手的基础能力。

后续可深入研究其 Agent 循环机制、记忆管理模块和工具调用系统，逐步构建符合个人需求的智能助手。无论是作为开发学习项目还是实际应用工具，NanoBot 都展现出了 "小而美" 的独特价值。