[AI/Agent] Nnanobot(HKUDS)：约 4000 行 Python 打造的超轻量自托管【个人 AI 智能体框架】

0 序

定位：nanobot 是香港大学-数据智能实验室（HKUDS）开源的“超轻量级 OpenClaw”——用约 4,000 行 Python 代码复刻 OpenClaw 约 90% 的核心 Agent 能力，代码量减少约 99%，支持 WebUI/终端/聊天应用多前端、多模型供应商、MCP 工具、长期记忆与定时自动化，MIT 协议完全自托管。

调研时间：2026-09-08；数据采集：GitHub API + 官方文档（docs/）+ 公开技术报道。

先上部署效果: WEB-UI

也支持 CLI 等交互形式

1 概述

产品介绍

产品定位：超轻量（Ultra-Lightweight）、开源、自托管的个人 AI 智能体框架（Personal AI Agent Framework），以 Python 编写，核心 Agent 代码仅约 4,000 行。

Nano : [英译] n. 毫微、纳

诞生的背景与原因：

2025–2026 年 OpenClaw（Clawdbot）成为现象级个人 AI 助手项目，但代码量膨胀至 43 万行以上，理解、审计、部署门槛极高（推荐较高内存、冷启动 8–12 秒）。

2026 年初 OpenClaw 被曝出多项安全问题：六周内披露 82 个漏洞（含 CVSS 9.0+ 的 Critical 级 CVE）、社区技能市场 ClawHub 被审计出大量恶意/含缺陷技能、API Key 明文存储等。

HKUDS 团队由此提出“极简哲学”：Agent 不需要 43 万行代码才能工作——用最小、可读的核心实现最核心能力，让研究者“一个下午读完”、让用户“真正拥有并掌控自己的 Agent 栈”。

解决的核心问题：

AI Agent 框架过于臃肿，导致“想研究读不懂、想部署跑不动、想审计不放心”；

本地/自托管部署门槛高、资源占用大；

个人用户对数据主权、可审计性、安全性的诉求无法被重型框架满足。

URLs：

项	链接
GitHub 仓库	https://github.com/HKUDS/nanobot
官方文档（稳定版）	https://nanobot.wiki
PyPI 包	`nanobot-ai`（`pip install nanobot-ai`）
所属组织	https://github.com/HKUDS（香港大学数据智能实验室，旗下另有 LightRAG、AutoAgent、MiniRAG 等）

发展历程

关键里程碑时间线

来源：GitHub Releases API + 公开报道

时间	事件
2026-02-01	仓库创建（`2026-02-01T07:16:15Z`，GitHub API）
2026-02-02	v0.1.x 系列正式发布；发布一个月 Star 从 0 飙到约 32K
2026-02-13/14	v0.1.3.post7 前后加入 MCP（Model Context Protocol）支持
2026-02-18~03-27	v0.1.4 系列密集迭代：流式输出、新增 LLM 供应商、心跳机制重设计、Prompt 缓存优化（v0.1.4.post2 合并 32 个 PR）
2026-03-12	公开报道时点：32K Star / 5.3K Fork
2026-04-06~04-29	v0.1.5 系列发布
2026-05-04	公开报道时点：41.1K Star（HyperAI）
2026-05-16	v0.2.0 发布
2026-06-01 / 06-23	v0.2.1、v0.2.2 发布
2026-07-08	公开对比文章时点：43.9K Star
2026-07-25	v0.3.0 “The Agency Release”：单版本合并 260 个 PR、38 位新贡献者；新增 inline 子代理、会话级模型切换、`/goal` 长任务、引导式 WebUI 首次设置、配置热加载、Neonize WhatsApp、Mattermost、Grok OAuth、Parallel Search 等，并强化安全边界
2026-09-08（本次采集）	47,870 Star / 8,450 Fork / 769 open issues / 4,298 commits，仍保持高频更新（README 与 WebUI 当日仍在提交）

版本发布序列（GitHub Releases API）：

v0.1.3.post4（02-04）→ post5（02-07）→ post6（02-10）→ post7（02-13）→ v0.1.4（02-18）→ post1（02-21）→ post2（02-24）→ post3（02-28）→ post4（03-08）→ post5（03-16）→ post6（03-27）→ v0.1.5（04-06）→ post1（04-14）→ post2（04-21）→ post3（04-29）→ v0.2.0（05-16） → v0.2.1（06-01）→ v0.2.2（06-23）→ v0.3.0（07-25）。

主要功能

nanobot 是一个自托管的个人 AI Agent 运行时，当前（v0.3.0+）核心能力包括：

多前端入口

WebUI：随 pip 包内置发布，浏览器工作台，支持多主题会话（topic）、临时对话、模型/工作区切换、工具调用与文件 diff 可视化、Apps/Skills/Automations 管理；默认 http://127.0.0.1:8765。
终端 TUI：nanobot 命令进入原生终端客户端（TypeScript 实现，随发布包校验下载）。
聊天应用：接入 TG、Discord、Slack、WeChat（微信）、飞书（Feishu）、Email、Mattermost、QQ、WhatsApp（Neonize）、钉钉（DingTalk）、Matrix 等。
OpenAI 兼容 API（nanobot serve，/v1/chat/completions）与 Python SDK，供外部程序集成。

Agent 能力

工具调用：文件读写/编辑/patch、shell 执行（可配置沙箱）、Web 搜索与抓取（带 SSRF 检查）、MCP servers、cron 定时任务、图像生成、子代理（inline subagents）、运行时自检。
模型自由：支持 11+ 供应商——OpenAI、Anthropic Claude、Mistral、DeepSeek、Qwen（通义千问）、Kimi（Moonshot）、MiniMax、Azure OpenAI、VolcEngine（火山引擎）、DashScope、OpenRouter、AWS Bedrock、Ollama、vLLM/任意 OpenAI 兼容端点，以及 OpenAI Codex、GitHub Copilot 等 OAuth 通道；支持模型路由、模型预设（modelPresets）、fallback 回退；基于 LiteLLM，理论上兼容其全部供应商。
记忆系统：会话历史（JSONL）+ 长期记忆（MEMORY.md）+ Dream 两阶段记忆整合任务（定期把历史会话消化为长期记忆），另支持每日日记（journal）。
长任务与自动化：/goal 显式长任务、cron 定时任务、heartbeat 心跳任务（读取 HEARTBEAT.md 执行活动任务）、本地触发器 /trigger。
上下文管理：自动上下文压缩（microcompaction）、prompt caching（Anthropic 优化）、思考模式（Thinking Mode）。
多代理协调：inline subagents 可在当前任务内委派子代理，多会话/多工作区隔离。

核心优势

极致轻量：核心 Agent 约 4,000 行 Python（可用 core_agent_lines.sh 随时审计行数），对比 OpenClaw 43 万+ 行减少约 99%；公开评测称冷启动约 0.8 秒（对比 OpenClaw 8–12 秒）、内存占用约 100MB 量级。
可读、可审计：架构围绕一个小的 Agent Loop 展开，无重型编排层；代码小 → 攻击面小，可“一个下午读完”，MIT 协议可自由修改。
模型无关、亚太友好：原生支持通义千问/Kimi/DeepSeek/火山引擎等国内供应商，以及飞书/钉钉/QQ/微信等国内平台，国内用户上手成本低。
MCP 优先：基于标准 MCP 协议扩展工具，可复用整个 MCP 生态（浏览器操控、文件系统、数据库、搜索等），配置兼容 Claude Desktop / Cursor。
自托管与数据主权：可完全离线运行（本地 vLLM/Ollama），数据不出设备；支持 Docker/Render 一键部署。
社区与迭代速度：约半年从 0 到 4.8 万 Star、4,298 commits、单版本合并 260 个 PR；活跃的 Discord/X/微信/飞书社区。
学术背书：HKUDS（港大数据智能实验室）出品，与 LightRAG 等同门项目方法论成熟。

主要短板

以下为截至 2026-09 的综合评估（部分短板已随版本迭代缓解，标注说明）。

无原生伴侣应用：没有 macOS/iOS/Android 原生 App、无 always-on 语音唤醒（需依赖聊天应用或 WebUI 浏览器访问）。※ 2026-03 的报道即指出此点，至今未变。
技能/插件生态相对小：不像 OpenClaw 拥有庞大的 ClawHub 社区技能市场，扩展主要依赖 MCP 生态与本地 skills/ 目录。
无企业级功能：不具备 RBAC、审计日志、SSO 等企业级管理能力（v0.3.0 后安全边界强化，但仍定位“个人”级）。
功能深度边界：超轻量设计意味着部分重型功能（复杂浏览器操控、语音、大规模技能编排）不如 OpenClaw 开箱即用，需通过 MCP 补齐。
文档早期不完善：2026-02/03 时文档覆盖不足；※ 现已大幅改善（docs/ 目录 20+ 篇任务导向文档、nanobot.wiki 稳定版文档），但仍处于快速演进期。
年轻项目风险：2026-02 创建，历史不足一年；版本迭代快、命令与配置接口可能变动，长期稳定性有待验证。

局限性

定位边界：为“个人/单机”场景设计，默认单实例架构；多实例需手动配置（multiple-instances.md），不适合大规模团队协作平台。
记忆实现：长期记忆基于 Markdown 纯文本文件（MEMORY.md + history.jsonl），不依赖向量数据库；在超大规模知识库场景下，检索效率与容量不及专用 RAG/向量方案（HKUDS 同门的 LightRAG 可作为补充方案）。
移动端体验：无原生 App，移动端依赖聊天平台客户端或移动浏览器 WebUI。
安全依赖配置：shell 工具、远程 API/WebUI 绑定等需使用者正确配置（如远程绑定必须配 token、渠道访问控制 allowFrom）；配置不当仍有风险面。
LLM 依赖：多数能力依赖外部 LLM API；本地模型需自行部署 vLLM/Ollama 等服务并调优。

适用场景

研究与教学：学习 AI Agent 架构的最佳范本（Agent Loop、记忆、技能、消息总线四大模块清晰可读）；国内已有“通过 Nanobot 源码学习 OpenClaw 架构”系列文章。
开发者个人助手：自托管、可完全掌控的编码/日程/知识助手。
隐私敏感场景：本地离线部署，数据不出设备。
国内生态用户：需要接入飞书、钉钉、QQ、微信，或使用通义千问/Kimi/DeepSeek/火山引擎等国内模型的场景。
常驻自动化：24/7 运行 cron 定时任务、heartbeat 主动任务、实时行情分析、全栈开发辅助等长时任务。
快速原型/教学演示：几行命令即可拉起带 WebUI 的可用 Agent。

项目	语言	规模/形态	核心卖点	Star（约）
nanobot（本文）	Python	~4,000 行核心	多 LLM、MCP、可读性	43.9K（2026-07）/ 47.9K（2026-09）
OpenClaw（Clawdbot）	TypeScript	43 万+ 行	全功能、伴侣 App、ClawHub 生态	更高（现象级项目）
ZeroClaw	Rust	二进制约 6.6 MB	高性能 + 安全 + 硬件	~31.8K
NanoClaw	TypeScript	~3K LOC	容器隔离、14+ 平台	~29.7K
NullClaw	Zig	二进制 678 KB	最小足迹、19 个渠道	~7.6K

发展趋势

Star / Fork 趋势（多时点快照，来源见数据标注）：

时点	Star（约）	Fork（约）	来源
2026-02-02	0（发布）	0	GitHub 创建时间
2026-03-12	32,000	5,300	掘金公开报道
2026-05-04	41,100	—	HyperAI 报道
2026-07-08	43,900	—	clawdocs.org 对比文章
2026-08-30	42,100	7,400	CSDN 报道（文章时点）
2026-09-08	47,870	8,450	GitHub API（本次采集）

趋势特征：

爆发期（02–03月）：发布一个月从 0 到 32K Star，现象级增长，属 2026 上半年 GitHub 热门项目（“Github 一周热点”常客）。
平稳期（04–08月）：增速放缓至平台期（约 41–44K 区间波动），社区从“围观”转向“深度使用与贡献”。
再增长（07月 v0.3.0 后）：发布“The Agency Release”后关注度回升，2026-09-08 达 47.9K。
社区活跃度：4,298 commits、Fork 8.45K、open issues 769，合并 PR 数量大（v0.3.0 单版本 260 PR）；官方维护者与 38+ 社区新贡献者共同推进。

开源社区趋势判断：Star 增速从爆发期回落至稳健增长，但 PR/贡献者/功能迭代保持高强度，说明项目已从“现象级新星”过渡为可持续的、社区共建的成熟个人 Agent 运行时。

总结：nanobot 正从“OpenClaw 的极简平替/学习样本”演进为具备多代理协调、运营级部署与安全边界的完整个人 Agent 平台，未来看点在于生态（技能/MCP 市场）与企服能力的补全。

2 工作原理与架构

概念术语

术语	含义
Agent Loop（智能体循环）	面向渠道的回合编排：接收消息 → 选择会话/工作区 → 构建上下文 → 调 Provider → 执行工具 → 发布回复
Agent Runner	面向模型的循环：发送消息、处理流式 delta 与推理块、执行工具调用、回填结果、直到产出最终答案或达到运行限制
MessageBus（消息总线）	消息事件与队列的中枢，统一 `InboundMessage` / `OutboundMessage`
Channel（渠道）	外部平台接入适配层（CLI、WebUI/WebSocket、TG、Discord、飞书……），将平台消息翻译为内部事件
Provider（供应商）	LLM 后端抽象（OpenRouter、Anthropic、OpenAI、Bedrock、Ollama、vLLM 及任意 OpenAI 兼容端点）
Tool（工具）	模型可调用的能力：文件、shell、Web、MCP、cron、图像生成、子代理等
Memory（记忆）	工作区长期记忆（`MEMORY.md`、`history.jsonl`）与会话历史（JSONL）
Dream	周期性记忆整合任务：读取累计历史，提炼写入长期记忆
Session（会话）	按会话键隔离的对话历史，独立上下文的单位
Workspace（工作区）	Agent 的状态目录：记忆、技能、cron、产物；分为 agent workspace（身份/记忆）与 project workspace（项目上下文）
Gateway（网关）	常驻进程：连接启用的渠道、启动 cron/Dream/heartbeat 系统任务、提供健康端点
MCP（Model Context Protocol）	模型上下文协议，Agent 接入外部工具服务器的标准接口
Agent Plugin	可安装能力包，可捆绑 skills + MCP servers + CLI App 适配
Skill（技能）	按需加载的工作流指导（`skills/` 目录或 `$skill-name` 触发）
Heartbeat	心跳任务：读取 `HEARTBEAT.md` 中的 Active Tasks 并执行，结果推送到最近活跃会话
Cron	定时任务服务（工作区作用域），用户提醒/自动化

架构与运行原理

核心数据流

flowchart LR A[Channel CLI / WebUI / 聊天应用] --> B[MessageBus InboundMessage] B --> C[AgentLoop 会话·工作区·上下文] C --> D[AgentRunner Provider/Tool 循环] D --> E[Provider LLM 后端] E --> D D --> F[Tools 文件·shell·Web·MCP·cron] F --> D D --> C C --> G[MessageBus OutboundMessage] G --> A C -.读写.-> H[Session/Memory/Hooks/Skills/Templates]

一次完整回合（官方 concepts.md 定义）：

渠道收到用户消息并发布到消息总线；
Agent Loop 选定会话键，从项目工作区（AGENTS.md）、Agent 档案（SOUL.md/USER.md）、记忆、近期消息、渠道元数据与运行配置构建上下文；
Provider 收到模型请求；
若模型请求工具，Runner 执行工具并把结果回填给模型；
最终回复写入会话并通过原渠道返回。

核心模块职责与源码映射（docs/architecture.md）：

区域	关键文件
消息事件与队列	`nanobot/bus/events.py`、`nanobot/bus/queue.py`
回合编排	`nanobot/agent/loop.py`
Provider/工具对话循环	`nanobot/agent/runner.py`
上下文构建	`nanobot/agent/context.py`
会话存储与压缩	`nanobot/session/manager.py`
长期记忆与 Dream	`nanobot/agent/memory.py`
Provider 注册表	`nanobot/providers/registry.py`
渠道基类/管理	`nanobot/channels/base.py`、`nanobot/channels/manager.py`
配置 Schema	`nanobot/config/schema.py`、`loader.py`、`paths.py`
工具	`nanobot/agent/tools/{shell,filesystem,web,mcp,cron,image_generation,self}.py`
安全	`nanobot/security/`（workspace_access、workspace_policy、network）

关键设计要点：

AgentLoop 与 AgentRunner 分离：Loop 负责“渠道侧”问题（路由、会话、工作区、hooks、出站投递）；Runner 负责“模型侧”问题（Provider 调用、工具调用、流式、迭代限制）。排查问题按此分流。
MCP 生命周期由应用层持有：MCP 连接是应用级基础设施——组合根创建 MCPProvider、与 AgentLoop 共享 ToolRegistry、connect() 后使用、关闭时保证 aclose()；Loop 不管理该生命周期。
轻量化哲学：一切围绕小的 Agent Loop——消息来自聊天应用，LLM 决定何时用工具，记忆/技能按需作为上下文拉取，而非做成重型编排层。
Provider 自动选择：显式 provider/preset → 注册表关键字 → API Key 前缀与 base URL 推断 → 本地 provider 回退 → 网关回退。

配置、工作区与记忆

默认路径（docs/concepts.md）：

路径	用途
`~/.nanobot/config.json`	实例配置：providers、modelPresets、channels、tools、gateway、API
`~/.nanobot/workspace/`	Agent 工作区：memory、skills、cron、产物
`~/.nanobot/sessions/<workspace-id>/*.jsonl`	会话历史（在工作区之外，随 workspace 迁移保持）
`<workspace>/memory/MEMORY.md`	长期记忆
`<workspace>/memory/history.jsonl`	Dream 整合源历史
`<workspace>/SOUL.md`、`USER.md`	Agent 身份档案与用户档案
`<workspace>/HEARTBEAT.md`	心跳任务清单（`## Active Tasks`）

双记忆结构：

Sessions：近期对话回放（JSONL，进入上下文）。
Memory：长期事实与整合历史（Markdown 纯文本，LLM 直接读取即“回忆”）。
Dream：周期性整合任务，把累计历史消化为长期记忆，使有用上下文超越短期会话回放存活；由运行时在 gateway 启动时按配置注册。

Agent Workspace vs Project Workspace：配置工作区承载 Agent 身份/记忆/技能；WebUI 会话可另选项目工作区（读项目 AGENTS.md、shell 与相对路径以项目为边界），二者解耦，不因选项目而迁移 Agent 身份。

安全边界

官方将安全视为功能行为的一部分，关键边界（docs/architecture.md）：

边界	机制
工作区作用域	`workspace_access.py` / `workspace_policy.py`，工具仅获得项目边界内能力，跨根访问只读且显式
Shell 沙箱	`tools/shell.py` 可配置沙箱；v0.3.0 修复了链式命令绕过 allowlist 的问题
网络/SSRF	`security/network.py` + `tools/web.py`，SSRF 检查锁定已验证 DNS
凭据	PTH（提示注入）防护；凭据从 MCP URL 脱敏；官方建议环境变量引用而非明文 API Key
远程暴露	远程绑定 API/WebUI 必须提供对应 token；本地回环走引导式短期 token 流程
渠道访问控制	`allowFrom`、配对（pairing）、WebSocket token

扩展点

扩展	方式
Provider	在 `providers/registry.py` 加 `ProviderSpec` + `config/schema.py` 加字段；多数托管服务走通用 OpenAI 兼容实现
Channel	自包含包导出 `ChannelPlugin`，遵循 `channel-package-guide.md`
Tool	`agent/tools/` 下实现或暴露插件入口点
Agent Plugin	`<workspace>/plugins/` v1 包，可捆绑 skills + MCP servers + CLI App 适配
MCP	`tools.mcpServers` 配置，或随 Agent Plugin 捆绑
Skill	`<workspace>/skills/`、Agent Plugin 捆绑或内置 `nanobot/skills/`
CLI App	加入 CLI Apps 目录，安装器管理可执行文件生命周期

3 使用指南

安装部署

环境要求：Python ≥ 3.11；源码安装还需 Git 与 Bun（用于运行与版本匹配的 TUI）。

Windows（PowerShell）

# 一键安装（官方脚本，从 PyPI 安装 nanobot-ai 并启动）
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
# 预览计划（不改环境）
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run

macOS / Linux

# 一键安装
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
# 预览计划
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run

pip / uv（跨平台）

uv tool install nanobot-ai      # 推荐

# 从 PyPI 安装稳定发布版
python -m pip install nanobot-ai

# 若报 externally-managed-environment：用 uv/pipx 或虚拟环境

源码安装（最新特性 / 开发 / 推荐）

安装

git clone https://github.com/HKUDS/nanobot.git
cd nanobot

## `python`：调用 Python 解释器；
## `python -m xxx`：从 Python 包 / 模块里找 `xxx` 并运行（`-m` = module）
## `venv`：Python 标准库自带的虚拟环境模块
## `.venv`：创建出的环境目录名（惯例命名，可自定义）
python -m venv .venv 或者像笔者: conda activate python-3.13
# macOS/Linux: source .venv/bin/activate ；Windows: .venv\Scripts\Activate.ps1

# 升级 pip 到支持 PEP 660 的版本
python -m pip install --upgrade pip
# 查验版本，python >= 3.11
python -m pip --version

# 用当前 Python 环境的 pip 来安装 / 以可编辑模式安装当前项目（源码） 
## -m pip : 调用当前环境（虚拟环境）的 pip
## `install -e`：`--editable` 可编辑模式 —— 不把代码复制进 site-packages，而是建链接指向当前目
## - `.`：指当前目录（nanobot 源码根目录），pip 读取其中的 `pyproject.toml` 完成安装
## 作用：装的是源码最新特性，改代码即时生效无需重装；对应 README 中 "源码安装 / 开发" 路径，`git pull` 更新源码后如依赖有变需重跑此命令
python -m pip install -e . -i https://mirrors.aliyun.com/pypi/simple/

# 验证
nanobot --version

使用

(python-3.13) PS F:\Codes-Minor\Github\nanobot> nanobot --version
🐈 nanobot v0.3.0
(python-3.13) PS F:\Codes-Minor\Github\nanobot> nanobot -m "Hello!"
Agent cannot start: No provider is configured for model 'anthropic/claude-opus-4-5'.
Complete provider/model setup:
  WebUI: run nanobot webui --config "C:\Users\xxx\.nanobot\config.json", then open Settings → Models
  CLI:   run nanobot onboard --wizard --config "C:\Users\xxx\.nanobot\config.json"
  Check: nanobot status --config "C:\Users\xxx\.nanobot\config.json"
  

创建并配置 `C:\Users\xxx\.nanobot\config.json` 后:

(python-3.13) PS F:\Codes-Minor\Github\nanobot> nanobot status --config "C:\Users\xxx\.nanobot\config.json"
Using config: C:\Users\xxx\.nanobot\config.json
🐈 nanobot Status

Config: C:\Users\xxx\.nanobot\config.json ✓
Workspace: C:\Users\xxx\.nanobot\workspace ✗
Model: deepseek-ai/DeepSeek-V4-Flash (preset: primary)
Agent: ✓ provider/model configuration is ready
Custom: not set
Azure OpenAI: not set
AWS Bedrock: not set
OpenRouter: not set
OrcaRouter: not set
Eden AI: not set
OpenCode Zen: not set
OpenCode Zen: not set
OpenCode Go: not set
Hugging Face: not set
Skywork: not set
AiHubMix: not set
SiliconFlow: ✓
Novita AI: not set
VolcEngine: not set
VolcEngine Coding Plan: not set
BytePlus: not set
BytePlus Coding Plan: not set
Anthropic: not set
OpenAI: not set
OpenAI Codex: ✓ (OAuth)
xAI Grok: ✓ (OAuth)
Github Copilot: ✓ (OAuth)
DeepSeek: not set
Gemini: not set
Zhipu AI: not set
DashScope: not set
ModelScope: not set
Moonshot: not set
Kimi Coding: not set
MiniMax: not set
MiniMax (Anthropic): not set
Mistral: not set
Step Fun: not set
Xiaomi MIMO: not set
LongCat: not set
Ant Ling: not set
vLLM: not set
Ollama: not set
LM Studio: not set
Atomic Chat: not set
OpenVINO Model Server: not set
NVIDIA NIM: not set
Groq: not set
AssemblyAI: not set
Qianfan: not set

Next: nanobot agent -m "Hello!"
Status does not call the model or verify network access and credentials.
(python-3.13) PS F:\Codes-Minor\Github\nanobot> nanobot agent -m "Hello!"
  Created AGENTS.md
  Created HEARTBEAT.md
  Created SOUL.md
  Created USER.md
  Created memory\MEMORY.md
  Created prompts\README.md
  Created memory\history.jsonl
2026-09-08 16:36:10 | INFO  | - | Git store initialized at C:\Users\xxx\.nanobot\workspace

🐈 nanobot
✻ The user just said "Hello!
✻ ".
✻ This is a simple greeting.
✻ I should respond warmly and briefly.
Hi there! 👋 I'm nanobot, your personal assistant. What can I help you with today?
(python-3.13) PS F:\Codes-Minor\Github\nanobot>

Docker / 云部署

仓库自带 Dockerfile、docker-compose.yml（含安全加固版 docker-compose.bwrap.yml）、render.yaml（Render 一键部署 Blueprint，需 ANTHROPIC_API_KEY 与私有 NANOBOT_WEB_TOKEN，持久磁盘需付费服务）。
自托管详见官方 docs/deployment.md（Docker、Linux systemd、macOS LaunchAgent）。

快速开始（关键操作）

# 1) 浏览器工作台（推荐首次运行：引导式设置 Provider/模型）
nanobot webui            # 默认打开 http://127.0.0.1:8765

# 2) 首次三步：Settings → Models 选 Provider/凭据/模型 → 新会话发 Hello! 验证

# 3) 终端交互 / 一次性问答 / 常驻网关
nanobot                  # 终端客户端
nanobot status --config "C:\Users\xxx\.nanobot\config.json"
nanobot agent            # 兼容形式的终端 Agent
nanobot -m "Hello!"      # 一次性问答（脚本/自动化）
nanobot gateway --background   # 后台常驻（保留渠道与自动化）
nanobot gateway status | logs | restart | stop

WebUI 要点：支持主题式会话、临时对话（不入历史/记忆）、查看推理/工具调用/文件 diff/产物、切换模型与工作区；首次运行默认只绑定 localhost，不暴露局域网。

聊天应用接入（示例目标）：nanobot onboard/WebUI 中配置渠道凭据，支持 TG、Discord、Slack、WeChat、飞书、Email、Mattermost、QQ、WhatsApp（nanobot plugins enable whatsapp + nanobot channels login whatsapp）、钉钉、Matrix 等。

MCP 配置示例（config.json，兼容 Claude Desktop/Cursor 格式）：

{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      }
    }
  }
}

常用命令速查：onboard（初始化）、webui、agent、gateway、serve（OpenAI 兼容 API）、trigger（触发本地触发器）、plugins / channels（管理扩展与渠道）。

Z FAQ for Nanobot

Q: nanobot 和 OpenClaw 到底怎么选？

A：想要全功能 + 原生 App + 庞大技能市场、不介意复杂度与资源占用 → OpenClaw（建议 Docker 隔离并关注安全风险）；想要极轻量、可读可审计、隐私敏感、资源受限、或需要飞书/钉钉/QQ/微信与国内模型 → nanobot。nanobot 定位是“精华版平替”而非“阉割版”，约 90% 核心能力、约 1% 代码量。

Q: 支持哪些大模型？能否完全离线？

A：支持 11+ 供应商（OpenAI、Anthropic、DeepSeek、Qwen、Kimi、MiniMax、Azure、火山引擎、DashScope、OpenRouter、Ollama、vLLM 及任意 OpenAI 兼容端点等），底层 LiteLLM。可以完全离线：部署本地 vLLM/Ollama，把 provider 指向本地端点，数据不出设备。

Q: 怎么接入飞书 / 微信 / 钉钉 / QQ？

A：在 nanobot onboard 或 WebUI 渠道设置中配置对应渠道凭据即可；官方文档 docs/chat-apps.md 提供分渠道接入指南。飞书/钉钉/QQ/微信均有原生渠道适配。

Q: MCP 工具怎么配置？

A：在 config.json 的 tools.mcpServers 中声明服务器（command+args，兼容 Claude Desktop/Cursor 格式），或用 nanobot plugins 安装捆绑 MCP 服务器的 Agent Plugin。MCP 连接由应用层管理，重启/关闭生命周期自动处理。

Q: Windows 下 pip 报 `externally-managed-environment` 怎么办？

A：这是系统 Python 的外部托管保护。改用官方一键脚本（install.ps1）、uv tool install nanobot-ai、pipx install nanobot-ai，或在虚拟环境中安装。

Q: nanobot 的数据存在哪里？隐私如何保障？

A：默认 ~/.nanobot/（config.json、workspace、sessions）。可完全离线运行；代码量小、可审计，无社区技能市场带来的供应链风险；shell/网络/工作区访问均有安全边界，远程暴露必须配 token。敏感场景建议本地模型 + 限制渠道访问（allowFrom）。

Q: 如何让 nanobot 后台 24 小时运行？

A：nanobot gateway --background 将共享网关提升为后台常驻模式，保留渠道、cron、Dream、heartbeat；首次先 nanobot webui 完成模型配置。正式服务化参考 docs/deployment.md（Linux systemd / Docker / macOS LaunchAgent）。

Q: 同一份配置可以开多个机器人实例吗？

A：可以。用 --config / --workspace 指定不同配置文件与工作区即可运行多实例；docs/multiple-instances.md 提供多实例说明，workspace 通过 .nanobot/workspace-id 保持会话命名空间隔离。

Q: 自定义Skills如何安装？`~/.agents/skills`的Skill识别不了，如何解决？*

nanobot 的 skill-creator 技能文档明确写了：自定义技能必须放在nanobot的工作区(~/.nanobot/workspace/)的 skills/ 下才能被自动发现。

复制到工作区：把 ~/.agents/skills/<skill>/ 整体复制到 C:/Users/Johnny/.nanobot/workspace/skills/。
做符号链接：在 workspace/skills/ 下对目标技能建立 junction/symlink（Windows 上可用 mklink /J），这样内容仍留在 ~/.agents/skills，但 nanobot 能按约定路径读到。⚠️ 注意：技能打包（package_skill.py）会因为有 symlink 而校验失败，运行时读取则没问题。
用 ClawHub 官方安装：npx --yes clawhub@latest install <slug> --workdir ~/.nanobot/workspace，它会装到正确位置。

Y 推荐文献

NanoBot

nanobot - GitHub 官方仓库（README / Releases / Issues）

nanobot 官方文档（稳定版） - nanobot.wiki

nanobot Architecture（源码级架构映射） - GitHub docs

nanobot Concepts（产品级心智模型） - GitHub docs

https://nanobot.wiki/cn/docs/0.3.0/use-nanobot/configuration (config.json)

X 参考文献

posted @ 2026-09-08 17:01 数据知音阅读(41) 评论(0) 收藏举报

刷新页面返回顶部

[AI/Agent] Nnanobot(HKUDS)：约 4000 行 Python 打造的超轻量自托管【个人 AI 智能体框架】

0 序

1 概述

产品介绍

发展历程

主要功能

核心优势

主要短板

局限性

适用场景

同类竞品

发展趋势

2 工作原理与架构

概念术语

架构与运行原理

核心数据流

配置、工作区与记忆

安全边界

扩展点

3 使用指南

安装部署

Windows（PowerShell）

macOS / Linux

pip / uv（跨平台）

源码安装（最新特性 / 开发 / 推荐）

Docker / 云部署

快速开始（关键操作）

Z FAQ for Nanobot

Q: nanobot 和 OpenClaw 到底怎么选？

Q: 支持哪些大模型？能否完全离线？

Q: 怎么接入飞书 / 微信 / 钉钉 / QQ？

Q: MCP 工具怎么配置？

Q: Windows 下 pip 报 `externally-managed-environment` 怎么办？

Q: nanobot 的数据存在哪里？隐私如何保障？

Q: 如何让 nanobot 后台 24 小时运行？

Q: 同一份配置可以开多个机器人实例吗？

Q: 自定义Skills如何安装？`~/.agents/skills`的Skill识别不了，如何解决？*

Y 推荐文献

X 参考文献

公告

[AI/Agent] Nnanobot(HKUDS)：约 4000 行 Python 打造的超轻量自托管【个人 AI 智能体框架】

0 序

1 概述

产品介绍

发展历程

主要功能

核心优势

主要短板

局限性

适用场景

同类竞品

发展趋势

2 工作原理与架构

概念术语

架构与运行原理

核心数据流

配置、工作区与记忆

安全边界

扩展点

3 使用指南

安装部署

Windows（PowerShell）

macOS / Linux

pip / uv（跨平台）

源码安装（最新特性 / 开发 / 推荐）

Docker / 云部署

快速开始（关键操作）

Z FAQ for Nanobot

Q: nanobot 和 OpenClaw 到底怎么选？

Q: 支持哪些大模型？能否完全离线？

Q: 怎么接入飞书 / 微信 / 钉钉 / QQ？

Q: MCP 工具怎么配置？

Q: Windows 下 pip 报 externally-managed-environment 怎么办？

Q: nanobot 的数据存在哪里？隐私如何保障？

Q: 如何让 nanobot 后台 24 小时运行？

Q: 同一份配置可以开多个机器人实例吗？

Q: 自定义Skills如何安装？~/.agents/skills的Skill识别不了，如何解决？*

Y 推荐文献

X 参考文献

公告

Q: Windows 下 pip 报 `externally-managed-environment` 怎么办？

Q: 自定义Skills如何安装？`~/.agents/skills`的Skill识别不了，如何解决？*