nanobot

环境要求

• Python 3.11 或更高版本
• 源码安装需要 Git 与 Bun（PyPI 安装不需要）
• 如需 pip 安装，建议使用虚拟环境以避免 externally-managed-environment 报错
• 首次运行需要准备可用的模型提供商凭据（API Key）

安装与启动步骤

1. 1一键安装

   macOS / Linux 下执行官方安装脚本，默认从 PyPI 安装或升级 nanobot-ai，并尽量避免系统级 pip 安装。

   curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

   复制

2. 2Windows 安装

   Windows 用户在 PowerShell 中执行官方安装脚本，效果与 macOS/Linux 安装脚本一致。

   irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

   复制

3. 3用 uv 安装

   已安装 uv 的用户可用它安装稳定版；也可用 pipx install nanobot-ai 或 python -m pip install nanobot-ai 替代。

   uv tool install nanobot-ai

   复制

4. 4从源码安装

   想体验最新特性时克隆仓库并以可编辑模式安装。Windows 请改用 .venv\Scripts\Activate.ps1 激活虚拟环境。

   git clone https://github.com/HKUDS/nanobot.git
   cd nanobot
   python -m venv .venv
   source .venv/bin/activate
   python -m pip install -e .

   复制

5. 5验证安装

   确认命令行客户端已就绪。若提示命令不存在，说明 nanobot 不在 PATH，需用安装它的工具方式调用。

   nanobot --version

   复制

6. 6启动 WebUI

   推荐的首次运行方式，会自动创建配置与工作区、启动本地网关并打开浏览器，首次访问无需先配置模型。

   nanobot webui

   复制

7. 7配置模型

   在浏览器里打开 Settings → Models，选择提供商、凭据与模型，然后新建话题发送 Hello! 验证连通性。

8. 8后台常驻

   希望关闭终端后仍保持在线时使用。请先通过 nanobot webui 完成首次模型配置，再切到后台模式。

   nanobot gateway --background

   复制

关键配置

如何确认成功

执行 nanobot --version 能输出版本号；运行 nanobot webui 后打开 http://127.0.0.1:8765，发送 Hello! 收到正常回复即成功。

常见问题

注意事项

• 首次运行的 WebUI 默认只绑定 localhost，不会暴露到局域网。
• 源码安装需要额外安装 Git 和 Bun，且 git pull --ff-only 后如依赖有变需重跑 python -m pip install -e .。
• 安装器支持 --dry-run 预览安装计划，也可以先打开 scripts/install.sh 或 scripts/install.ps1 检查脚本内容。
• 终端客户端中可用 / 查看命令、/sessions 切换会话、@ 提及应用或 MCP 服务，用 Ctrl+V 或 Alt+V 粘贴图片。