1. Ubuntu 源码装 Nanobot 到底解决什么问题Nanobot 是一个用 Python 写的轻量级 AI 助手框架核心代码量不大跑起来内存占用很低一台 1GB 内存的 Ubuntu 小机器就能长期挂着。它能做什么简单说它把「大模型对话 工具调用 多渠道接入」这套东西打包成一个可以自己部署的服务你可以把它接到飞书、Telegram 这类聊天工具上也可以直接在命令行里跟它对话。适合谁适合想在自己服务器上跑一个私有 AI 助手、又不想被重型框架拖垮的个人开发者或者想拿它当二次开发底座的人。那为什么强调「从源码安装」因为 pip 直接装虽然快但你拿到的是发布版本想改一行代码、想跟最新提交、想调试工具系统都得重新打包。源码安装用pip install -e .这种可编辑模式改完代码立刻生效对调试和二次开发友好得多。这篇就按 Ubuntu 环境从依赖准备一路走到启动验证中间用 TaoToken 的统一 Key 通道把模型调用跑通让你在本地得到一个真正能用的 AI 助手实例。我试过在一台 2 核 2G 的 Ubuntu 22.04 上完整走一遍全程大概十几分钟坑主要集中在 Python 版本和虚拟环境激活这两块后面会逐个说。你跟着做的时候命令可以直接复制但路径里的用户名记得换成你自己的。先明确一下整体链路Ubuntu 装依赖 → 建虚拟环境 → 拉源码 → 可编辑安装 → 初始化配置 → 填模型通道 → 启动网关 → 发消息验证。每一步都有可复制的命令配置片段也会给全。2. TaoToken 前置准备与统一 Key 接入思路在动手装 Nanobot 之前先把模型通道这块理清楚。Nanobot 本身不绑定某一家模型它通过配置里的providers字段去调 API。传统做法是每换一个模型就去对应平台注册、拿 Key、改配置模型一多Key 管理就乱。TaoToken 的思路是提供一个统一的 API 通道你用同一个 Key 就能调用多种模型配置里只改模型名不用反复换 Key 和 Base URL。TaoToken 是什么它是一个面向开发者的模型调用聚合入口提供统一的 API Key 和兼容 OpenAI 格式的接口。能做什么你可以在 Nanobot 里把apiBase指向它的接口地址把apiKey填成你在控制台生成的 Key然后模型名按它的命名规则填就能跑通对话。适合谁适合手上有多个模型、又不想在每个平台单独维护密钥的开发者也适合刚开始搭 AI 助手、想先用一个通道把流程跑通再慢慢换模型的人。接入前你需要准备两样东西一个 TaoToken 的 API Key以及确认你要用的模型 ID。Key 在控制台的 API Keys 页面生成模型 ID 在文档里能查到。这两个信息后面会填进~/.nanobot/config.json。这里要提醒一句TaoToken 是正规的 API 调用通道配置时 Base URL 用https://taotoken.net/api不要自己拼奇怪的路径。Key 属于敏感信息别提交到 Git 仓库也别贴在公开的地方。如果你只是想先验证流程用最小配置跑通一次对话就够了后面再按需加渠道。前置准备清单Ubuntu 20.04 及以上、Python 3.10推荐 3.12、能访问外网拉源码和调 API、一个 TaoToken API Key、一个你想用的模型 ID。这些齐了就可以进入安装环节。3. 可复制配置依赖、源码与 config.json 片段这一节是全文的核心操作区命令和配置都给全你按顺序执行即可。先装基础依赖sudo apt update sudo apt upgrade -y sudo apt install -y python3 python3-venv python3-pip git curl wget build-essential python3-dev如果你的系统 Python 低于 3.10用 deadsnakes PPA 装 3.12sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt update sudo apt install python3.12 python3.12-venv python3.12-dev -y python3 --version确认版本在 3.10 以上后建虚拟环境并拉源码。虚拟环境的作用是把 Nanobot 的依赖和系统 Python 隔开避免污染系统环境python3 -m venv ~/nanobot-env source ~/nanobot-env/bin/activate pip install --upgrade pip git clone https://github.com/HKUDS/nanobot.git cd nanobot pip install -e . nanobot --versionpip install -e .是可编辑安装源码改动后不用重装就生效。装完nanobot命令就在虚拟环境的 PATH 里了。接着初始化配置nanobot onboard这会在~/.nanobot/下生成config.json、workspace/目录以及AGENTS.md、SOUL.md、USER.md、memory/MEMORY.md等文件。然后编辑主配置nano ~/.nanobot/config.json把内容改成下面这样注意apiBase指向 TaoToken 的接口地址apiKey换成你自己的模型名按文档填{ providers: { taotoken: { apiKey: 你的TaoToken_API_Key, apiBase: https://taotoken.net/api } }, agents: { defaults: { workspace: ~/.nanobot/workspace, model: taotoken/你的模型ID, maxTokens: 8192, temperature: 0.7, maxToolIterations: 10 } }, tools: { restrictToWorkspace: true } }关键参数对照一下参数含义建议值providers.taotoken.apiKeyTaoToken 控制台生成的 Key必填providers.taotoken.apiBase统一接口地址https://taotoken.net/apiagents.defaults.model模型 ID前缀对应 providertaotoken/你的模型IDmaxTokens单次回答最大 token8192temperature随机性创作 0.7严谨任务 0.3maxToolIterations工具调用最大轮数10防死循环tools.restrictToWorkspace限制文件操作在工作区true配置里model字段的前缀要和providers里的键名一致这里都是taotoken别写错。改完保存退出配置这一步就完成了。4. 验证请求命令行对话与网关启动配置填好后先别急着接渠道用命令行直接验证模型通道是否通。在虚拟环境激活状态下执行nanobot agent -m 你好用一句话介绍你自己如果配置正确你会看到模型返回一段文字。这一步能过说明 TaoToken 的 Key、Base URL、模型 ID 三者都对上了。如果这里就报错先别往下走回到第 5 节排查。命令行通了之后启动网关。网关是 Nanobot 对外提供服务的进程前台跑方便看日志nanobot gateway --verbose看到类似connected to ...的日志说明网关起来了。这时候你可以另开一个终端再发一条测试消息确认服务在响应。如果只是想本地验证命令行那一步其实已经证明链路通了网关更多是给渠道接入用的。要长期跑用 systemd 托管先建服务文件mkdir -p ~/.config/systemd/user nano ~/.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 --user daemon-reload systemctl --user enable --now nanobot-gateway systemctl --user status nanobot-gateway看日志用journalctl --user -u nanobot-gateway -f到这里一个能响应命令行、能后台常驻的 Nanobot 实例就跑起来了。成功的结果是nanobot agent -m能拿到模型回复systemctl --user status显示 active (running)。5. 本篇常见错排查401、local proxy failed 与 reading choices装和配的过程中报错基本集中在几个地方逐个对照。401 Unauthorized最常见。原因通常是 Key 填错、Key 失效或者apiBase写成了带多余路径的地址。检查~/.nanobot/config.json里apiKey有没有多余空格apiBase是不是https://taotoken.net/api。改完重启网关systemctl --user restart nanobot-gateway。local proxy failed / connection refused这类报错一般是网络层没通或者本机有奇怪的代理设置干扰。先确认服务器能正常访问外网再检查环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY有的话清掉再试。Nanobot 走的是标准 HTTPS 请求不需要额外代理配置。reading choices 相关报错这通常意味着返回体结构不符合预期多半是模型 ID 填错或者apiBase指向的接口不兼容 OpenAI 格式。确认model字段用的是 TaoToken 文档里给的模型 ID前缀和 provider 键名一致。OAuth / 认证类报错如果你在配置里混用了需要 OAuth 的渠道或者 Key 类型不对会看到认证失败。Nanobot 的模型调用用的是 API Key不是 OAuth 流程别把渠道认证和模型认证搞混。nanobot: command not found虚拟环境没激活。执行source ~/nanobot-env/bin/activate再试。systemd 服务里用的是绝对路径所以服务能跑但终端找不到命令是正常的。pip install -e . 报错缺编译工具装build-essential和python3-dev前面依赖那步已经包含如果跳过了补上。飞书收到消息只回表情没文字检查模型通道是否通用nanobot agent -m test验证以及渠道权限是否配全。模型不通时机器人可能只完成了表情回应。排查顺序建议先命令行验证模型 → 再验证网关启动 → 最后查渠道。这样能把问题范围快速缩小到某一层。6. 长期使用与 CTA把通道固定下来跑通之后日常维护其实很轻。更新源码就在源码目录里git pull然后pip install -e .重装一次改配置改~/.nanobot/config.json后重启服务看日志用journalctl --user -u nanobot-gateway -f。工作区里的AGENTS.md可以定义助手的行为规范比如写作风格、回复长度改完即时生效。如果你打算长期用这套东西做编码辅助或者 Agent 类任务建议把模型通道固定成 TaoToken 的统一 Key这样以后换模型只改model字段不用动 Key 和 Base URL。需要生成或管理 Key 就去控制台接入细节看文档想先试试模型效果可以直接在模型对话页面聊几句。生成和管理 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档与参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite在线验证模型效果https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码与 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后留一个实用习惯把~/.nanobot/config.json里的 Key 用环境变量注入而不是硬编码在文件里。Nanobot 支持从环境读取你可以在 systemd 服务里加EnvironmentTAOTOKEN_API_KEYxxx配置文件里引用变量。这样即使配置文件被误传Key 也不会直接泄露。装完之后先跑一周观察内存和日志再决定要不要加渠道和定时任务。