在 Ubuntu 上从源码安装 Nanobot：轻量级 AI 助手完整指南

文章目录

- [1. 引言](#1. 引言)
- [2. 环境准备](#2. 环境准备)
- - [2.1 系统要求](#2.1 系统要求)
  - [2.2 安装基础依赖](#2.2 安装基础依赖)
- [3. 从源码安装 Nanobot](#3. 从源码安装 Nanobot)
- [4. 初始化配置](#4. 初始化配置)
- [5. 配置 AI 模型](#5. 配置 AI 模型)
- - [5.1 获取 DeepSeek API Key](#5.1 获取 DeepSeek API Key)
  - [5.2 编辑配置文件](#5.2 编辑配置文件)
  - [5.3 关键参数解释](#5.3 关键参数解释)
- [6. 配置飞书渠道](#6. 配置飞书渠道)
- - [6.1 创建飞书应用](#6.1 创建飞书应用)
  - [6.2 配置权限](#6.2 配置权限)
  - [6.3 配置长连接事件](#6.3 配置长连接事件)
  - [6.4 修改 Nanobot 配置](#6.4 修改 Nanobot 配置)
- [7. 启动 Nanobot 网关](#7. 启动 Nanobot 网关)
- - [7.1 前台运行（测试）](#7.1 前台运行（测试）)
  - [7.2 后台运行（生产）](#7.2 后台运行（生产）)
  - [7.3 配置 systemd 服务（开机自启）](#7.3 配置 systemd 服务（开机自启）)
- [8. 测试飞书机器人](#8. 测试飞书机器人)
- [9. 高级配置：为小说创作定制工作区](#9. 高级配置：为小说创作定制工作区)
- - [9.1 创建小说目录](#9.1 创建小说目录)
  - [9.2 创建角色卡](#9.2 创建角色卡)
  - [9.3 修改 AGENTS.md 定义写作风格](#9.3 修改 AGENTS.md 定义写作风格)
- [10. 常见问题与解决](#10. 常见问题与解决)
- [11. 结语](#11. 结语)

1. 引言

Nanobot 是香港大学数据科学实验室开源的超轻量 AI 智能体框架，核心代码仅约 4000 行，却保留了多渠道接入、Agent 循环、工具系统、持久化记忆等核心能力。它能在 1GB 内存的服务器上流畅运行，是个人开发者的理想选择。本文将从零开始，指导你在 Ubuntu 服务器上通过源码编译安装 Nanobot，并接入飞书，打造一个专属的轻量 AI 助手。

2. 环境准备

2.1 系统要求

Ubuntu 20.04 / 22.04 / 24.04
Python 3.10 或更高版本（推荐 3.12+）
内存：至少 1GB（Nanobot 本身占用 < 50MB）
网络：能访问 GitHub 和 PyPI，以及飞书 API

2.2 安装基础依赖

bash 复制代码

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-venv python3-pip git curl wget

如果你的系统 Python 版本低于 3.10，可以通过 deadsnakes PPA 安装 Python 3.12：

bash 复制代码

sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev -y

验证 Python 版本：

bash 复制代码

python3 --version   # 应为 3.10 以上

3. 从源码安装 Nanobot

推荐使用 虚拟环境 进行源码安装，避免污染系统环境。

bash 复制代码

# 创建虚拟环境
python3 -m venv ~/nanobot-env
source ~/nanobot-env/bin/activate

# 升级 pip
pip install --upgrade pip

# 克隆 Nanobot 源码
git clone https://github.com/HKUDS/nanobot.git
cd nanobot

# 以可编辑模式安装（便于后续更新）
pip install -e .

# 验证安装
nanobot --version

安装说明：

pip install -e . 会在当前目录下以"可编辑"模式安装，源码修改后无需重新安装即可生效，非常适合开发和调试。
如果不需要可编辑模式，也可以直接 pip install .，但后续更新需要重新安装。
安装完成后，nanobot 命令已加入虚拟环境的 PATH。

4. 初始化配置

运行初始化命令创建默认配置和工作区：

bash 复制代码

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 编辑配置文件

bash 复制代码

nano ~/.nanobot/config.json

将内容修改为：

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.apiKey`	DeepSeek API 密钥	必填
`providers.deepseek.apiBase`	API 端点	默认即可
`agents.defaults.model`	使用的模型名	`deepseek/deepseek-chat`
`maxTokens`	单次回答最大 token 数	8192（适合长文本）
`temperature`	随机性（0~1）	0.7（创作类）或 0.3（严谨任务）
`maxToolIterations`	工具调用最大迭代次数	10（防止死循环）
`tools.restrictToWorkspace`	限制文件操作在工作区内	强烈建议 true

6. 配置飞书渠道

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 中添加飞书配置：

json 复制代码

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxx",           // 你的 App ID
      "appSecret": "xxxxxxxx",         // 你的 App Secret
      "allowFrom": [],                 // 允许的用户ID，空数组表示允许所有人
      "groupPolicy": "mention",        // 群聊回复策略：mention（需@）或 allowlist（白名单）
      "replyToMessage": false,         // 是否引用回复
      "reactEmoji": "THUMBSUP"         // 收到消息自动添加的表情（可选）
    }
  }
}

关键参数解释：

allowFrom：白名单，填入飞书用户 ID（如 ou_xxxx）可限制仅特定用户与机器人对话。空数组则所有人都能用。
groupPolicy：群聊时机器人如何响应。mention 表示只在被 @ 时回复；allowlist 表示群内所有人发送都回复（慎用）。
replyToMessage：回复时是否引用用户原消息。一般设为 false 避免刷屏。
reactEmoji：收到消息时自动给消息点个表情，可选值如 THUMBSUP。

7. 启动 Nanobot 网关

7.1 前台运行（测试）

bash 复制代码

nanobot gateway --verbose

如果看到类似日志：

复制代码

connected to wss://msg-frontier.feishu.cn/ws/v2?...

说明长连接成功。此时在飞书给机器人发消息，它应该会回复。

7.2 后台运行（生产）

bash 复制代码

nohup nanobot gateway &

7.3 配置 systemd 服务（开机自启）

创建服务文件：

bash 复制代码

mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/nanobot-gateway.service

填入：

ini 复制代码

[Unit]
Description=Nanobot Gateway
After=network.target

[Service]
Type=simple
ExecStart=/home/你的用户名/nanobot-env/bin/nanobot gateway
Restart=always
RestartSec=10
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/home/你的用户名/.nanobot

[Install]
WantedBy=default.target

启用并启动：

bash 复制代码

systemctl --user daemon-reload
systemctl --user enable --now nanobot-gateway

查看状态：

bash 复制代码

systemctl --user status nanobot-gateway

8. 测试飞书机器人

在飞书客户端搜索并添加你的机器人
发送消息 ping 或 你好
观察机器人回复

如果只回表情但没有文字，请检查：

飞书应用是否拥有 im:message:send_as_bot 权限（并已重新发布）
模型 API Key 是否有效（用 nanobot agent -m "test" 测试）

9. 高级配置：为小说创作定制工作区

如果你要用 Nanobot 辅助写小说，可以定制工作区结构和 AI 角色。

9.1 创建小说目录

bash 复制代码

cd ~/.nanobot/workspace
mkdir -p novel/{_worlds,_shared,小说A}

9.2 创建角色卡

bash 复制代码

nano novel/_shared/角色.md

示例内容：

markdown 复制代码

# 艾伦
- 年龄：17
- 身份：魔法学院学生
- 性格：冲动但善良
- 能力：火系魔法（火球术、火焰护盾）

9.3 修改 AGENTS.md 定义写作风格

bash 复制代码

nano AGENTS.md

写入：

markdown 复制代码

# 你是小说创作助手
- 单章字数：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-dev`

11. 结语

现在你已经成功在 Ubuntu 上从源码编译安装了 Nanobot，并接入了飞书。相比 pip install 直接安装，源码方式让你能随时获取最新特性，并便于二次开发。Nanobot 的轻量设计使其特别适合个人开发者长期运行，你还可以进一步探索它的技能系统、定时任务、MCP 协议等高级功能，打造真正属于你的智能助手。

如果在部署中遇到任何问题，欢迎在评论区交流！

附录：常用命令速查

bash 复制代码

# 激活虚拟环境
source ~/nanobot-env/bin/activate

# 更新 Nanobot（源码目录内）
cd ~/nanobot
git pull
pip install -e .   # 重新安装以应用更新

# 测试 Agent
nanobot agent -m "你好"

# 启动网关
nanobot gateway --verbose

# 查看服务状态
systemctl --user status nanobot-gateway

# 查看日志
journalctl --user -u nanobot-gateway -f