数字旗手

数字化、智能化、智能体化

0%

跟着🐈NanoBot学AI个人助理设计和开发1：一键装机！

Posted on Edited on In Disqus:

前言

最近在看OpenClaw这个当今最火的AI个人助理，想通过OpenClaw来研究下这种个人智能助理的设计和开发原理。但是发现OpenClaw太“重”了，动不动就是几十万行代码，层层封装，想从源码层面理解它的运行逻辑（它还是typescript语言），或者想自己魔改加个小功能，往往要翻半天文档。

直到我遇到了 nanobot。

它给我的第一感觉就是“干净”。核心代码只有 4000 行左右（大概只有OpenClaw 的 1%），但麻雀虽小，五脏俱全。它去掉了很多复杂的抽象，保留了 Agent 最核心的能力。

nanobot 内置了非常丰富的渠道支持。你可以把它接入 Telegram、Discord、Slack，甚至是国内的飞书、钉钉、QQ 和微信（通过 Mochat）。我现在把它挂在飞书上，平时想查个资料、翻译段文本，或者只是单纯想找个“人”聊聊代码思路，随时掏出手机就能发消息，它会像一个真正的助理一样回复你。

那么就从nanobot源码开始学习AI个人助理吧。

0在这里

一键装机

在运行nanobot之前，需要先初始化一下：

1
nanobot onboard

当在终端输入 nanobot onboard 后，系统会执行 nanobot/cli/commands.py 中的 onboard 函数。这个函数的主要作用是初始化 nanobot 的运行环境，具体做了以下四件事：

检查并创建配置文件

  • 位置：~/.nanobot/config.json
  • 动作：
    • 首先检查该文件是否存在。如果存在，会询问你是否覆盖。
    • 如果不存在（或确认覆盖），它会创建一个默认的 Config 对象并保存。
    • 这个文件是你后续配置 API Key（如 OpenAI、Anthropic）的地方。

创建工作区目录

  • 位置：默认为 ~/.nanobot/workspace（具体路径由 get_workspace_path() 决定）。
  • 动作：确保这个目录存在，如果不存在则创建它。这个目录是 nanobot 的“大脑”和“手脚”，它在这里读写文件、存储记忆。

生成模板文件 (Bootstrap)

它会在你的工作区里自动生成一些基础的 Markdown 文件，用来定义 nanobot 的行为和记忆：

  • AGENTS.md:
    • 作用：Agent 的“员工手册”。定义了它作为一个 AI 助手的基本准则（比如要友善、准确、行动前要解释）。
    • 提示词是：
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      ""# Agent Instructions

      You are a helpful AI assistant. Be concise, accurate, and friendly.

      ## Guidelines

      - Always explain what you're doing before taking actions
      - Ask for clarification when the request is ambiguous
      - Use tools to help accomplish tasks
      - Remember important information in memory/MEMORY.md; past events are logged in memory/HISTORY.md
      """
  • SOUL.md:
    • 作用：Agent 的“人设”。定义了它的性格（乐于助人、好奇）、价值观（隐私优先、透明）。
    • 提示词是：
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      """# Soul

      I am nanobot, a lightweight AI assistant.

      ## Personality

      - Helpful and friendly
      - Concise and to the point
      - Curious and eager to learn

      ## Values

      - Accuracy over speed
      - User privacy and safety
      - Transparency in actions
      """
  • USER.md:
    • 作用：Agent 对你的认知。这里记录了你的偏好（语言、时区、沟通风格）。
    • 提示词是：
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      """# User

      Information about the user goes here.

      ## Preferences

      - Communication style: (casual/formal)
      - Timezone: (your timezone)
      - Language: (your preferred language)
      """
  • memory/MEMORY.md:
    • 作用：长期记忆。用来存储那些需要跨会话记住的重要信息。
    • 提示词是：
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      """# Long-term Memory

      This file stores important information that should persist across sessions.

      ## User Information

      (Important facts about the user)

      ## Preferences

      (User preferences learned over time)

      ## Important Notes

      (Things to remember)
      """
  • memory/HISTORY.md:
    • 作用：历史记录。用来记录过去的事件（初始化为空）。
    • 提示词默认为空。
  • skills/:
    • 作用：技能目录。预留给未来存放自定义技能的地方。

打印后续指引

最后，它会在终端输出一个“下一步”指南，告诉你：

  1. 去 ~/.nanobot/config.json 填入你的 API Key。
  2. 如何开始第一次对话（nanobot agent -m "Hello!"）。
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    ✓ Created config at /root/.nanobot/config.json
    ✓ Created workspace at /root/.nanobot/workspace
      Created AGENTS.md
      Created SOUL.md
      Created USER.md
      Created memory/MEMORY.md

    🐈 nanobot is ready!

    Next steps:
      1. Add your API key to ~/.nanobot/config.json
         Get one at: https://openrouter.ai/keys
      2. Chat: nanobot agent -m "Hello!"

    Want Telegram/WhatsApp? See: https://github.com/HKUDS/nanobot#-chat-apps

总结

nanobot onboard 就是一个一键装机命令。它帮你铺好了路，建好了房（目录结构），写好了家规（模板文件），你只需要拿着钥匙（API Key）住进去（配置一下）就可以开始了。

配置

完成 onboard 之后，你的环境已经准备好了，接下来只需要把“钥匙”交给 nanobot。你需要编辑配置文件 ~/.nanobot/config.json。

配置模型供应商

需要至少配置一个 AI 提供商，就两个参数：apiBase和apiKey：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxxxxxxx" 
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

注意：agents.defaults.model 决定了 nanobot 默认用哪个模型。你可以随时通过命令行参数 -m 覆盖它。

配置保存后，在终端运行以下命令来测试：

1
2
3
4
5
# 检查状态，看看 Key 是否被识别
nanobot status

# 试着聊一句
nanobot agent -m "你好，介绍一下你自己"

如果它回复了你，恭喜！你的 nanobot 已经正式上岗了。🎉

配置飞书频道

上面的运行方式只能“聊一句”，nanobot真正的交互方式是通过各种通讯工具与它进行对话，这里使用飞书作为案例搞一下。

配置飞书（Feishu）需要两个步骤：先在飞书开放平台创建一个机器人应用，然后把凭证填入 nanobot 的配置文件。

nanobot 使用飞书的WebSocket 长连接模式，这意味着你不需要公网 IP，也不需要内网穿透，直接在本地电脑运行即可。

第一步：创建飞书机器人

  1. 登录 飞书开放平台。
  2. 点击 创建企业自建应用，填写名称（比如 “Nanobot”）和描述。
  3. 添加机器人能力：
    • 进入左侧菜单 添加应用能力 -> 机器人，点击添加。
  4. 配置权限：
    • 进入 权限管理，搜索并添加以下权限：
      • im:message (获取与发送单聊、群组消息)
      • im:message.group_at_msg (获取群组中 @机器人的消息)
      • im:message.p2p_msg (获取用户发给机器人的单聊消息)
    • 注意：添加权限后，需要发布版本才能生效。
  5. 配置事件订阅（注意！这一步先不要做，等到把ID和secret配置给nanob，然后启动gateway后再设置）：
    • 进入 事件订阅。
    • 订阅方式：选择 长连接模式（这一步很关键！）。
    • 添加事件：搜索并添加 im.message.receive_v1 (接收消息)。
  6. 获取凭证：
    • 进入 凭证与基础信息。
    • 复制 App ID 和 App Secret。
  7. 发布应用：
    • 进入 版本管理与发布，创建并发布一个版本（如果不发布，机器人无法被外部搜到）。

第二步：配置 nanobot

打开配置文件 ~/.nanobot/config.json，在 channels 下添加 feishu 配置：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxx", 
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "encryptKey": "",
      "verificationToken": "",
      "allowFrom": []
    }
  }
}
  • appId: 填入你刚才复制的 App ID。
  • appSecret: 填入你刚才复制的 App Secret。
  • encryptKey 和 verificationToken: 在长连接模式下通常留空即可。
  • allowFrom: 如果你想限制只有特定用户能跟机器人聊天，可以在这里填入用户的 open_id。留空 [] 表示允许所有人。

第三步：启动

配置完成后，启动网关模式：

1
nanobot gateway

现在，打开飞书 App，搜索你的机器人名字，给它发一条消息，它应该就会回复你了！🎉

如果它回复了你，恭喜！你的 nanobot 已经正式上岗了。🎉

后台运行

nanobot gateway 命令本身是一个前台进程，它没有内置 --daemon 参数来自动转入后台。

如果你想让它在后台长期运行，有几种标准的方法：

使用 nohup (最简单)

这是最传统的后台运行方式，即使你退出了 SSH 终端，它也会继续运行。

1
2
# 启动并把日志输出到 nanobot.log
nohup nanobot gateway > nanobot.log 2>&1 &
  • 查看日志：tail -f nanobot.log
  • 停止：你需要先找到进程 ID，然后 kill 掉。
    1
    2
    ps aux | grep nanobot
    kill <PID>

使用 Docker (生产环境推荐)

如果你想要更稳定的部署，用 Docker 跑是最省心的，它自带重启策略。

1
2
3
4
5
6
docker run -d \
  --name nanobot \
  --restart always \
  -v ~/.nanobot:/root/.nanobot \
  -p 18790:18790 \
  nanobot gateway
  • -d: 后台运行 (Detach)
  • --restart always: 如果挂了或者重启电脑，自动重新启动

使用 systemd (Linux 服务器推荐)

如果你是在 Linux 服务器上部署，可以把它注册成系统服务。

创建一个文件 /etc/systemd/system/nanobot.service：

1
2
3
4
5
6
7
8
9
10
11
12
13
[Unit]
Description=Nanobot AI Gateway
After=network.target

[Service]
Type=simple
User=your_username
ExecStart=/path/to/your/python/bin/nanobot gateway
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

然后启用：

1
2
sudo systemctl enable nanobot
sudo systemctl start nanobot

这一章先到这吧，未完待续。