首页 / 开源热榜 / nanobot / 使用教程

nanobot 中文教程：先锁工作区和沙箱，再让 Agent 调工具

官方资料核对：2026-09-23 · 文档与源码核对，未安装、配置模型或运行网关

nanobot 是 Python 编写的自托管个人 Agent。它可通过终端、WebUI 和聊天渠道工作，并支持模型路由、记忆、文件、shell、网页、MCP、定时任务和子 Agent。工具多也意味着第一次启动要先收紧权限。

本文不宣称它已有站内搜索热度，只根据当前官方代码、发布说明和配置写教程。

1. v0.3.5 的入口与生命周期

官方在 2026-09-15 发布 v0.3.5，对应提交 1bb712d。该版把原生终端客户端作为默认入口，wheel 内置 TUI 与 WebUI，还调整共享网关的生命周期、远程项目权限、并发配置和健康接口，并加入 macOS Seatbelt 沙箱。

普通 TUI 或 WebUI 退出后，共享网关会按交互客户端生命周期停止。只有 nanobot gateway --background 才让渠道与自动任务长期运行。这个区别关系到费用、定时任务和消息渠道是否仍在工作。

2. 消息如何变成工具动作

聊天渠道和本地客户端先把消息送进异步 MessageBus。AgentLoop 选择会话、工作区、记忆和上下文，AgentRunner 再调用模型与工具。Gateway 同时承担 WebUI、WebSocket、渠道和健康接口。

默认配置目录是 ~/.nanobot，工作区通常是 ~/.nanobot/workspace。模型可以建议文件或 shell 操作，最终权限来自工具配置和操作系统。提示里写“只读”不是安全边界。

3. 先用固定版本安装

python3 --version  # 需要 3.11+
uv tool install "nanobot-ai==0.3.5"
nanobot --version

# 官方也提供远程安装脚本。使用前先下载并查看内容，
# 不要把 curl 输出未经检查直接交给 shell。

wheel 内置 WebUI 与 TUI，首轮不需要额外下载 Bun。令牌不要直接写进可同步或可提交的配置文件，优先使用环境变量或操作系统凭据存储。

4. 工作区限制与系统沙箱是两层

控制	保护范围	不能解决什么
`tools.restrictToWorkspace=true`	限制内置文件工具的路径	不能完整约束 shell 子进程
Linux bwrap	从操作系统层隔离进程、目录与网络	规则过宽仍会暴露宿主资源
macOS Seatbelt	为 exec 命令应用系统沙箱策略	需要逐项测试允许的路径和网络
渠道 allowFrom 或配对	限制谁能向 Agent 发消息	不能替代工具权限与模型审查

在新建的空白测试目录中启用工作区限制，并为 exec 配置 bwrap 或 Seatbelt。先关闭 shell、网页、MCP、定时任务和子 Agent，只保留对话。每开一个工具，都用无敏感数据测试允许和拒绝的操作。

5. 第一次 WebUI 只在本机打开

nanobot webui
# 浏览器默认打开 http://127.0.0.1:8765

# 在 Settings 中选择测试模型和凭据，然后发送：
# Hello!

官方说明首次 WebUI 默认绑定 localhost。一个正常回复说明这次模型、工作区和浏览器网关能连通。它不代表文件、MCP、聊天渠道或定时任务已经验证，也不说明模型输出正确。

6. 模型、搜索与渠道都可能向外发送数据

nanobot 可以接本地模型，也支持多家托管模型。托管模型会收到提示和工具整理出的上下文；网页搜索、图像生成、外部 MCP 和聊天平台还会各自处理查询或消息。对每个服务记录接收的数据、保存时间、费用单位和删除方式。

并发若没有设置正数上限，多个会话、子 Agent 或定时任务可能同时消耗额度与内存。先设置 NANOBOT_MAX_CONCURRENT_REQUESTS、模型侧预算和告警，再开放后台任务。

7. 后台网关要能停、能查日志

nanobot gateway --background
nanobot gateway status
nanobot gateway logs
nanobot gateway stop

切换后台模式前，先在前台完成模型和工具验收。记录进程用户、配置路径、监听地址、日志位置和停止方法。健康接口只反映网关或 WebSocket 通道状态，模型凭据、MCP 与消息渠道需要各自发一个最小请求。

8. 与 OpenClaw 怎么选

相比 OpenClaw，nanobot 更偏向较小的 Python 核心和个人自建，入口集中在 TUI、WebUI 与常见聊天渠道。OpenClaw 是 Node/TypeScript 平台，覆盖更多渠道、原生应用和运维组件。想阅读并修改 Agent 循环时可先看 nanobot；需要多设备客户端和更大的网关能力时，应同时核对 OpenClaw 的部署与安全文档。

9. 当前验证边界

验证状态：本轮核对官方 README、配置说明、pyproject 与 v0.3.5 GitHub Release。没有安装 wheel、运行 TUI/WebUI/网关、配置模型、渠道、MCP 或系统沙箱。

验证边界：未验证安装脚本、模型调用、工具权限、Seatbelt/bwrap 规则、聊天渠道、并发、费用、健康检查或后台生命周期。示例是安全检查顺序，不是本机实测结果。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

适合谁用

适合在个人电脑上学习 Agent 循环、把本地文件与模型接成受控助手、试验 MCP 或少量定时自动化。它不适合在默认权限下读取整个主目录、执行未知 shell、连接生产聊天账号或长期公网运行。第三方模型和搜索服务可能收费并接收提示、文件片段或查询。

采用建议

nanobot 适合想读懂并自建个人 Agent 的 Python 用户。安全起点是锁定 0.3.5、限制工作区、启用操作系统沙箱、只监听本机并逐个开放工具；长期后台运行前还要设置并发上限、费用预算和渠道白名单。

原教程未展开的系统信息

核心功能

多入口个人 Agent
同一网关可服务终端、WebUI、Telegram、Discord、Slack、邮件等入口，并把消息送入 Agent 循环。
本地网关与会话
TUI 或 WebUI 启动共享网关，交互客户端退出后可按需结束；只有显式 background 模式才保持渠道和自动任务持续运行。
访问模式与沙箱
可限制工具只访问工作区，并在 Linux 使用 bwrap、macOS 使用 Seatbelt 隔离 shell；仅有路径检查不等于操作系统沙箱。

技术栈和运行条件

语言

Python >=3.11

interfaces

TUI、WebUI、OpenAI 兼容 API 与多个聊天渠道

agent components

MessageBus、AgentLoop、AgentRunner、sessions、memory、tools、MCP、cron、subagents

sandbox

Linux bwrap 或 macOS Seatbelt 可选；工作区路径限制与操作系统沙箱是两层控制

license

MIT；模型、搜索、聊天平台及 MCP 服务另有条款和费用

常见问题

nanobot 第一次启动前最该改哪个权限？

先确认 tools.restrictToWorkspace=true，再为 exec 工具配置 Linux bwrap 或 macOS Seatbelt。工作区路径限制只管内置文件工具，不能代替对 shell 子进程的操作系统隔离。

关闭终端后，nanobot 的任务还会继续吗？

普通 TUI 或 WebUI 客户端退出后，共享网关会按 v0.3.5 的生命周期规则停止。只有显式运行 nanobot gateway --background，渠道和自动任务才会持续；之后要用 status、logs 和 stop 管理。

使用 nanobot 一定要购买模型 API 吗？

不一定，可以配置受支持的本地模型。使用托管模型、搜索、图像生成或外部 MCP 时，数据处理与费用由对应服务决定；应先设额度、保留费用日志并避免传入敏感内容。

可以把 WebUI 直接开放到公网吗？

首次只使用默认的 127.0.0.1:8765。远程访问需要身份验证、TLS、反向代理、来源限制、速率限制和最小工具权限；聊天渠道还要配置 allowFrom、配对或令牌。

健康检查返回正常就代表模型和 MCP 都可用吗？

不代表。健康接口主要反映网关与 WebSocket 通道状态，不能证明模型凭据、MCP 服务、聊天渠道或工具权限正确。每个集成都要用无敏感数据的最小请求单独验收。