文章目录1. 引言2. 环境准备2.1 系统要求2.2 安装基础依赖3. 从源码安装 Nanobot4. 初始化配置5. 配置 AI 模型5.1 获取 DeepSeek API Key5.2 编辑配置文件5.3 关键参数解释6. 配置飞书渠道6.1 创建飞书应用6.2 配置权限6.3 配置长连接事件6.4 修改 Nanobot 配置7. 启动 Nanobot 网关7.1 前台运行测试7.2 后台运行生产7.3 配置 systemd 服务开机自启8. 测试飞书机器人9. 高级配置为小说创作定制工作区9.1 创建小说目录9.2 创建角色卡9.3 修改 AGENTS.md 定义写作风格10. 常见问题与解决11. 结语1. 引言Nanobot 是香港大学数据科学实验室开源的超轻量 AI 智能体框架核心代码仅约4000 行却保留了多渠道接入、Agent 循环、工具系统、持久化记忆等核心能力。它能在 1GB 内存的服务器上流畅运行是个人开发者的理想选择。本文将从零开始指导你在 Ubuntu 服务器上通过源码编译安装 Nanobot并接入飞书打造一个专属的轻量 AI 助手。2. 环境准备2.1 系统要求Ubuntu 20.04 / 22.04 / 24.04Python 3.10 或更高版本推荐 3.12内存至少 1GBNanobot 本身占用 50MB网络能访问 GitHub 和 PyPI以及飞书 API2.2 安装基础依赖sudoaptupdatesudoaptupgrade-ysudoaptinstall-ypython3 python3-venv python3-pipgitcurlwget如果你的系统 Python 版本低于 3.10可以通过 deadsnakes PPA 安装 Python 3.12sudoadd-apt-repository ppa:deadsnakes/ppa-ysudoaptupdatesudoaptinstallpython3.12 python3.12-venv python3.12-dev-y验证 Python 版本python3--version# 应为 3.10 以上3. 从源码安装 Nanobot推荐使用虚拟环境进行源码安装避免污染系统环境。# 创建虚拟环境python3-mvenv ~/nanobot-envsource~/nanobot-env/bin/activate# 升级 pippipinstall--upgradepip# 克隆 Nanobot 源码gitclone https://github.com/HKUDS/nanobot.gitcdnanobot# 以可编辑模式安装便于后续更新pipinstall-e.# 验证安装nanobot--version安装说明pip install -e .会在当前目录下以“可编辑”模式安装源码修改后无需重新安装即可生效非常适合开发和调试。如果不需要可编辑模式也可以直接pip install .但后续更新需要重新安装。安装完成后nanobot命令已加入虚拟环境的 PATH。4. 初始化配置运行初始化命令创建默认配置和工作区nanobot onboard此命令会在~/.nanobot/目录下生成config.json- 主配置文件workspace/- 工作区目录AGENTS.md- AI 角色定义SOUL.md- AI 性格描述USER.md- 用户偏好memory/MEMORY.md- 长期记忆5. 配置 AI 模型Nanobot 支持多种 AI 模型提供商。以DeepSeek API为例价格低中文友好。5.1 获取 DeepSeek API Key访问 DeepSeek 开放平台注册后创建 API Key。5.2 编辑配置文件nano~/.nanobot/config.json将内容修改为{providers:{deepseek:{apiKey:你的DeepSeek_API_Key,apiBase:https://api.deepseek.com/v1}},agents:{defaults:{workspace:~/.nanobot/workspace,model:deepseek/deepseek-chat,maxTokens:8192,temperature:0.7,maxToolIterations:10}},tools:{restrictToWorkspace:true}}5.3 关键参数解释参数含义推荐值providers.deepseek.apiKeyDeepSeek API 密钥必填providers.deepseek.apiBaseAPI 端点默认即可agents.defaults.model使用的模型名deepseek/deepseek-chatmaxTokens单次回答最大 token 数8192适合长文本temperature随机性0~10.7创作类或 0.3严谨任务maxToolIterations工具调用最大迭代次数10防止死循环tools.restrictToWorkspace限制文件操作在工作区内强烈建议 true6. 配置飞书渠道6.1 创建飞书应用登录 飞书开放平台点击「创建企业自建应用」名称如“Nanobot助手”进入应用后在「添加应用能力」中启用「机器人」记录App ID和App Secret凭证与基础信息6.2 配置权限在「权限管理」中添加以下权限im:message– 发送消息im:message.p2p_msg:readonly– 接收单聊消息im:message:send_as_bot– 以机器人身份发送权限添加后需要重新发布应用版本才能生效。6.3 配置长连接事件在「事件与回调」中选择「使用长连接接收事件」千万不要选 Webhook点击「添加事件」搜索并添加im.message.receive_v1接收消息6.4 修改 Nanobot 配置编辑~/.nanobot/config.json在channels中添加飞书配置{channels:{feishu:{enabled:true,appId:cli_xxxxxx,// 你的 App IDappSecret:xxxxxxxx,// 你的 App SecretallowFrom:[],// 允许的用户ID空数组表示允许所有人groupPolicy:mention,// 群聊回复策略mention需或 allowlist白名单replyToMessage:false,// 是否引用回复reactEmoji:THUMBSUP// 收到消息自动添加的表情可选}}}关键参数解释allowFrom白名单填入飞书用户 ID如ou_xxxx可限制仅特定用户与机器人对话。空数组则所有人都能用。groupPolicy群聊时机器人如何响应。mention表示只在被 时回复allowlist表示群内所有人发送都回复慎用。replyToMessage回复时是否引用用户原消息。一般设为false避免刷屏。reactEmoji收到消息时自动给消息点个表情可选值如THUMBSUP。7. 启动 Nanobot 网关7.1 前台运行测试nanobot gateway--verbose如果看到类似日志connected to wss://msg-frontier.feishu.cn/ws/v2?...说明长连接成功。此时在飞书给机器人发消息它应该会回复。7.2 后台运行生产nohupnanobot gateway7.3 配置 systemd 服务开机自启创建服务文件mkdir-p~/.config/systemd/usernano~/.config/systemd/user/nanobot-gateway.service填入[Unit] DescriptionNanobot Gateway Afternetwork.target [Service] Typesimple ExecStart/home/你的用户名/nanobot-env/bin/nanobot gateway Restartalways RestartSec10 NoNewPrivilegesyes ProtectSystemstrict ReadWritePaths/home/你的用户名/.nanobot [Install] WantedBydefault.target启用并启动systemctl--userdaemon-reload systemctl--userenable--nownanobot-gateway查看状态systemctl--userstatus nanobot-gateway8. 测试飞书机器人在飞书客户端搜索并添加你的机器人发送消息ping或你好观察机器人回复如果只回表情但没有文字请检查飞书应用是否拥有im:message:send_as_bot权限并已重新发布模型 API Key 是否有效用nanobot agent -m test测试9. 高级配置为小说创作定制工作区如果你要用 Nanobot 辅助写小说可以定制工作区结构和 AI 角色。9.1 创建小说目录cd~/.nanobot/workspacemkdir-pnovel/{_worlds,_shared,小说A}9.2 创建角色卡nanonovel/_shared/角色.md示例内容# 艾伦 - 年龄17 - 身份魔法学院学生 - 性格冲动但善良 - 能力火系魔法火球术、火焰护盾9.3 修改 AGENTS.md 定义写作风格nanoAGENTS.md写入# 你是小说创作助手 - 单章字数2000-2500字 - 文风轻快幽默短句为主 - 开篇第一句话必须有悬念这样AI 在创作时会自动遵守这些规范。10. 常见问题与解决问题原因解决nanobot: command not found未激活虚拟环境或 PATH 问题确保虚拟环境已激活source ~/nanobot-env/bin/activate飞书收到消息但不回复缺少发送权限或模型配置错误检查im:message:send_as_bot权限用nanobot agent -m hi测试模型长连接建立失败飞书后台未选择“长连接”必须选“使用长连接接收事件”并先重启网关日志显示403错误API Key 无效或权限不足验证 API Key检查飞书权限是否已发布只回表情没有文字模型返回空或allowFrom限制检查allowFrom查看nanobot gateway --verbose日志源码安装时pip install -e .报错缺少编译工具或依赖安装build-essential和 Python 开发头文件sudo apt install build-essential python3-dev11. 结语现在你已经成功在 Ubuntu 上从源码编译安装了 Nanobot并接入了飞书。相比pip install直接安装源码方式让你能随时获取最新特性并便于二次开发。Nanobot 的轻量设计使其特别适合个人开发者长期运行你还可以进一步探索它的技能系统、定时任务、MCP 协议等高级功能打造真正属于你的智能助手。如果在部署中遇到任何问题欢迎在评论区交流附录常用命令速查# 激活虚拟环境source~/nanobot-env/bin/activate# 更新 Nanobot源码目录内cd~/nanobotgitpull pipinstall-e.# 重新安装以应用更新# 测试 Agentnanobot agent-m你好# 启动网关nanobot gateway--verbose# 查看服务状态systemctl--userstatus nanobot-gateway# 查看日志journalctl--user-unanobot-gateway-f