[Python] nanobot：仅4000行Python代码的轻量级个人AI助手，替代Clawdbot

项目简介

nanobot 是一款受 Clawdbot 启发的超轻量级个人AI助手。

仅用约 4,000 行代码即可实现核心智能体功能——比 Clawdbot 的 43 万+ 行代码小 99%。

主要特点

超轻量级：仅约 4,000 行代码——比 Clawdbot 小 99%，但包含核心功能。
为研究准备：代码清晰、可读，便于理解、修改和扩展，适合研究用途。
极速：极小的资源占用意味着更快的启动速度、更低的资源消耗和更快的迭代周期。
易于使用：一键部署，开箱即用。

架构

功能特性

24/7 实时市场分析	全栈软件工程师	智能日常事务管理	个人知识助手
发现 • 洞察 • 趋势	开发 • 部署 • 扩展	计划 • 自动化 • 组织	学习 • 记忆 • 推理

安装

从 PyPi 安装

pip install nanobot-ai

从源码安装（推荐用于开发）

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

使用 uv 安装

uv venv
source .venv/bin/activate
uv pip install nanobot-ai

快速开始

[!TIP]
在 ~/.nanobot/config.json 中设置你的 API 密钥。 获取 API 密钥：OpenRouter（用于大语言模型）· Brave Search（可选，用于网络搜索） 你也可以将模型切换为 minimax/minimax-m2 以降低成本。

1. 初始化

nanobot onboard

2. 配置 (~/.nanobot/config.json)

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "webSearch": {
    "apiKey": "BSA-xxx"
  }
}

3. 开始聊天

nanobot agent -m "2+2等于几？"

就这样！2分钟内你就拥有了一个可用的AI助手。

本地模型 (vLLM)

使用 vLLM 或任何兼容 OpenAI 的服务器，运行你本地的模型。

1. 启动 vLLM 服务器

vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000

2. 配置 (~/.nanobot/config.json)

{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}

3. 聊天

nanobot agent -m "你好，来自我的本地LLM！"

[!TIP]
对于不需要身份验证的本地服务器，apiKey 可以是任意非空字符串。

聊天应用

随时随地通过 Telegram 或 WhatsApp 与你的 nanobot 交谈。

渠道	设置难度
Telegram	简单（仅需令牌）
WhatsApp	中等（扫描二维码）

Telegram（推荐）

1. 创建机器人

• 打开 Telegram，搜索 @BotFather
• 发送 /newbot，按照提示操作
• 复制令牌

2. 配置

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "你的机器人令牌",
      "allowFrom": ["你的用户ID"]
    }
  }
}

在 Telegram 上使用 @userinfobot 获取你的用户 ID。

3. 运行

nanobot gateway

WhatsApp

需要 Node.js ≥18。

1. 链接设备

nanobot channels login
# 使用 WhatsApp 扫描二维码：设置 -> 已链接的设备

2. 配置

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}

3. 运行（两个终端）

# 终端 1
nanobot channels login

# 终端 2
nanobot gateway

配置

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC...",
      "allowFrom": ["123456789"]
    },
    "whatsapp": {
      "enabled": false
    }
  },
  "tools": {
    "web": {
      "search": {
        "apiKey": "BSA..."
      }
    }
  }
}

CLI 参考

命令	描述
nanobot onboard	初始化配置和工作区
nanobot agent -m "..."	与助手进行对话
nanobot agent	进入交互式聊天模式
nanobot gateway	启动网关
nanobot status	显示状态
nanobot channels login	链接 WhatsApp（扫描二维码）
nanobot channels status	显示渠道状态

计划任务 (Cron)

# 添加任务
nanobot cron add --name "daily" --message "早上好！" --cron "0 9 * * *"
nanobot cron add --name "hourly" --message "检查状态" --every 3600

# 列出任务
nanobot cron list

# 移除任务
nanobot cron remove <job_id>

项目结构

nanobot/
├── agent/          # 核心智能体逻辑
│   ├── loop.py     #   智能体循环（LLM ↔ 工具执行）
│   ├── context.py  #   提示词构建器
│   ├── memory.py   #   持久化记忆
│   ├── skills.py   #   技能加载器
│   ├── subagent.py #   后台任务执行
│   └── tools/      #   内置工具（包括衍生）
├── skills/         # 内置技能（github、天气、tmux...）
├── channels/       # WhatsApp 集成
├── bus/            # 消息路由
├── cron/           # 计划任务
├── heartbeat/      # 主动唤醒
├── providers/      # LLM 提供商（OpenRouter 等）
├── session/        # 对话会话管理
├── config/         # 配置管理
└── cli/            # 命令行接口

项目地址

完整的代码和文档可以在 GitHub 上找到。

总结

Nanobot 项目为想要一个轻量级、可定制个人AI助手的开发者提供了一个绝佳的起点。它用 Python 实现了核心的智能体循环、记忆和工具调用功能，代码精简且结构清晰，非常适合学习和二次开发。无论是想快速部署一个AI助手，还是想深入了解智能体（Agent）的工作原理，这个仅4000行的 开源实战 项目都值得一试。对这类轻量级工具和AI应用开发感兴趣的开发者，欢迎到 云栈社区 交流更多想法。