只用约 4000 行 Python，我把 AI 助理装进了自己的电脑：nanobot 保姆级上手指南（含架构图 + 实战）

文章目录

• • 为什么我要自己养一个「AI 助理」？
  • 一、nanobot 到底是个什么？一句话讲清楚
  • 二、架构篇：一个小循环，撑起整个系统
  • • 2.1 整体架构：核心只有一个循环
    • 2.2 两个"主角"的分工：AgentLoop vs AgentRunner
    • 2.3 一条消息的完整旅程（时序图）
  • 三、核心概念篇：配置、工作区、记忆
  • • 3.1 配置 vs 工作区：一切都是文件
    • 3.2 记忆：它为什么会"记得你"？
  • 四、5 分钟上手：把 nanobot 跑起来
  • • 4.1 安装
    • 4.2 配置模型
    • 4.3 检查配置
    • 4.4 收到第一句回复
  • 五、关键能力实战
  • • 5.1 换个模型 / 接本地模型
    • 5.2 接入聊天渠道（以 Telegram 为例）
    • 5.3 用 MCP 给它接外部工具
    • 5.4 定时任务与"心跳"
    • 5.5 子 Agent 与"自我检查"
    • 5.6 联网、图像、Shell 与安全
  • 六、进阶：把它当成"库"或"服务"
  • • 6.1 Python SDK：一句话跑一个 Agent
    • 6.2 OpenAI 兼容 API：让别的程序也来用
    • 6.3 自定义技能（Skills）
  • 七、常见问题 FAQ
  • 八、最佳实践 & 避坑清单
  • 九、总结

为什么我要自己养一个「AI 助理」？

先说个我踩过的坑。

一开始我想省事，直接上了某个「全家桶」Agent 框架。结果光是搞懂它的目录结构就花了两天，装依赖装到怀疑人生，最后连"Hello World"都没跑通——一个环环相扣的编排层，牵一发动全身。当时我就在想：我只是想要一个能帮我读读文档、查查资料、盯着定时任务的小助手，至于这么复杂吗？

直到我遇到nanobot。

它是香港大学数据智能实验室（HKUDS）开源的一个超轻量、可自托管的个人 AI Agent 框架，用 Python 写。它最打动我的一点是：核心逻辑被刻意做得又小又能通读，社区普遍称其核心代码只有大约 4000 行。你可以把它理解成「Agent 界的极简主义」——不追求功能堆到天花板，而是保证你能一眼看穿它在干什么。

更重要的是，它把真正实用的东西全都备齐了：

• 一个能直接用的WebUI 工作台，也可以是终端聊天；
• 10 多种聊天渠道（Telegram、Discord、Slack、飞书、微信、钉钉、WhatsApp、QQ、Signal、邮件等）任你接；
• 工具系统（文件读写、Shell 命令、联网搜索、图像生成、子 Agent……）；
• 长期记忆+定时自动化；
• 原生支持