机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

纳米机器人

🐈 纳米机器人 是一个超轻量级、开源、自托管的个人 AI 代理框架，使用 Python 编写。它可以在 WebUI、终端或聊天应用中运行，集成了工具、长期记忆、MCP 集成、模型路由、多代理委派、计划自动化以及兼容 OpenAI 的 API，核心小巧且易读。

从这里开始

你想要...	前往
在没有终端/配置背景的情况下安装纳米机器人	无技术背景开始
快速安装并获取一次 CLI 回复	安装 和 快速开始
打开捆绑的浏览器 UI	WebUI
连接 Telegram、Discord、微信、Slack、电子邮件、Mattermost、Linear 或其他渠道	聊天应用
配置提供者、备用模型、Langfuse、MCP、网络工具或安全设置	文档 和 配置
了解或扩展内部结构	架构 和 开发
部署到云端或保持纳米机器人作为服务运行	部署

纳米机器人能做什么？

纳米机器人是一个自托管的个人 AI 代理运行时。它可以：

• 在浏览器 WebUI 或终端中运行
• 连接到 Telegram、Discord、Slack、微信、电子邮件、Mattermost、Linear 及其他渠道
• 使用文件、Shell、网络搜索、网页抓取、MCP、cron、图像生成和子代理等工具
• 通过 Dream 保持会话历史和长期记忆
• 执行长期目标和计划自动化任务
• 提供 Python SDK 和兼容 OpenAI 的 API 以便集成
• 部署为长期运行的本地或服务器端代理网关

💡 为什么选择纳米机器人

• 持久工作流：目标、记忆、工具和聊天上下文在长期工作中保持有效。
• 聊天原生覆盖：WebUI、API、Telegram、飞书、Slack、Discord、Teams、电子邮件、Mattermost 和 Linear。
• 模型自由：兼容 OpenAI 的 API、本地 LLM、图像生成、搜索和备用方案。
• 小型核心：具有 MCP、记忆、部署和自动化的可读内部结构。
• 掌控你的技术栈：检查、定制、自托管和扩展，无需大型平台。

📦 安装

[！重要]
如果你想使用最新功能和实验，请从源码安装。

如果您想要最稳定的日常体验，请从 PyPI 或使用 uv 安装。

请选择 一种 安装方法：

路线	使用	更新	运行内容
稳定版	安装程序、uv 或 pip	使用相同的包管理工具	一个已发布的 Python/WebUI/TUI 版本
当前源代码	可编辑的 Git 检出	git pull --ff-only 可编辑依赖同步	从该检出运行 Python、WebUI 和 TUI

先决条件：Python 3.11 或更高版本。Git 和 Bun 仅在源代码安装时需要。发布的包包括 WebUI，支持的平台 wheel 还包括本地 TUI。源代码分发安装可以在首次使用时获取带有校验和、版本匹配的 TUI 压缩包—包括其许可证、声明、相应应用源代码、源代码提供和重新链接说明。

如果您对终端、API 密钥或配置文件不熟悉，请使用 无需技术背景即可开始 的指导式零基础教程，而不是使用此简化的 README 路径。

一条命令设置

macOS / Linux：

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

Windows PowerShell：

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

默认命令会从 PyPI 安装或升级 nanobot-ai。在新的本地桌面上，它随后会启动 nanobot webui，让您可以在 设置 → 模型 中配置第一个提供者和模型。SSH、无头模式、现有配置和旧版本路径会保留终端设置向导。安装程序通过使用活动虚拟环境 uv、pipx 或 ~/.nanobot/venv 下的托管 venv 来避免全局 pip 安装。它还会打印用于运行 nanobot 的确切命令；如果 nanobot 不在 PATH 上，请在下面重新使用该完整命令。

如需在不更改环境的情况下预览计划，请传递 --dry-run。

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

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run

如果您希望先检查脚本，请打开 scripts/install.sh 或 scripts/install.ps1 。

使用 uv 安装

uv tool install nanobot-ai

使用 pip 从 PyPI 安装

python -m pip install nanobot-ai

如果在 macOS 或 Linux 上 pip 报告 externally-managed-environment，请使用一键安装程序 uv tool install nanobot-ai、pipx install nanobot-ai，或在虚拟环境中安装。

平台 wheel 包括 WebUI 和原生终端 UI：macOS 13（Apple Silicon 和 Intel）、glibc 2.17 Linux（ARM64 和 x64）以及 Windows x64。x64 运行时需要 SSE4.2。Pip 会选择匹配的 wheel；打开 TUI 不需要单独下载 GitHub 或安装 Bun。在受支持的目标上进行源码分发安装时，可以使用匹配的带校验和的 GitHub release 压缩包。在其他平台上，请使用 nanobot --classic 或 WebUI。

从源码安装

克隆仓库并以可编辑模式安装。由于源码检出会直接运行匹配的 TUI，而不是下载较旧的发行版二进制文件，因此需要 Bun。

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv

在 macOS/Linux 上使用 source .venv/bin/activate 激活它，或在 Windows PowerShell 中使用 .venv\Scripts\Activate.ps1 激活它，然后运行：

python -m pip install -e .

之后，普通命令与稳定安装相同。nanobot 从此检出运行 TUI，而 nanobot webui 会自动重建过时的前端资源。稍后的 git pull --ff-only 会同时更新 Python、TUI 和 WebUI 源；当 Python 依赖发生变化时，重新运行 python -m pip install -e .。贡献者还应阅读 CONTRIBUTING.md 。

验证安装：

nanobot --version

如果 nanobot 不在 PATH 上，通过安装它的方法调用它：重用推荐安装程序的命令，使用 uv tool run --from nanobot-ai nanobot ... 或 pipx run --spec nanobot-ai nanobot ...，或使用 pip 安装该包的环境中的 Python 可执行文件。

🚀 快速开始

在浏览器中打开纳米机器人

nanobot webui

这是推荐的首次运行。启动器会在需要时创建配置和工作区，在确认后安全地启用本地 WebSocket 通道，启动或加入共享本地网关，并打开 http://127.0.0.1:8765 。全新安装可以在模型配置之前打开，因此设置会在浏览器中继续，而不是从 JSON 文件开始。首次运行的 WebUI 默认绑定到 localhost，不会暴露给您的局域网。

您的前三个步骤

1. 打开 设置 → 模型 并选择提供者、凭证和模型。
2. 启动新主题并发送 Hello! 以验证连接。
3. 在项目工作之前，从作曲器中选择预期的工作区和访问模式。

任何正常回复都表示提供者、模型、工作区和浏览器网关正在协同工作。

在关闭终端后保持纳米机器人运行

nanobot gateway --background

这是唯一将共享网关提升到持久后台模式的命令。它会在每次本地TUI和WebUI启动器退出后保持通道和自动化运行。在切换到后台模式之前，请使用 nanobot webui 完成首次模型设置；之后再次打开相同的本地主机 WebUI。

nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop

更喜欢先从网关开始的工作流程吗？

nanobot gateway

这将跳过 WebUI 设置和浏览器打开，然后在当前终端中运行相同的完整网关。如果你来自 OpenClaw 或已经将代理作为长时间运行的服务操作，这是熟悉的入口点。当配置了其通道时，WebUI 仍然可用；在需要时手动打开它。

使用 nanobot gateway --background 可以获得相同的直接入口点，而无需保持终端连接。如需由操作系统自动启动和管理，请参见 部署。

更倾向于完全在终端中工作吗？

nanobot

这会以启动目录作为工作区打开本地终端客户端。它会与 WebUI 共享已保存的对话和本地网关。显式的 nanobot agent 形式仍可用于兼容性。

• 输入 / 以发现命令，/sessions 以切换对话，或 @ 以提及应用、MCP 服务器或已保存的会话。
• 使用 Ctrl+V 或 Alt+V 粘贴剪贴板图片，使用 $ 完成技能引用。
• 使用 /diff 检查文件更改，/context 检查会话上下文，或 /branch 从已完成的回复继续新会话。
• 按 Enter 发送。在纳米机器人工作时，Enter 立即发送，Tab 在当前回复之后发送。按 Shift+Enter 添加换行（在无法区分修改回车键的终端中，Ctrl+J 可用）。
• 使用 /detach 保持当前任务运行，或使用 nanobot gateway --background 启动以让纳米机器人在所有本地客户端退出后保持在线。

每次启动默认都会开始新会话。使用 --session 恢复会话，使用 --workspace 选择其他工作区。有关会话分支、差异、历史记录、快捷方式、网关生命周期及兼容性选项，请参见 CLI 参考。

对于单次请求并立即退出，请使用:

nanobot -m "Hello!"

一次性表单适用于快速检查供应商、Shell 脚本和本地自动化。如果您尚未配置模型，请先运行 nanobot webui 并打开 设置 → 模型。

需要手动 JSON、局域网内的其他设备，或需要供应商/模型匹配的帮助？请继续查看 安装与快速入门、WebUI 或 故障排除。

如果 nanobot 对您有帮助，在 GitHub 上点个星是支持该项目最简单的方式。

• 想要一个可粘贴的供应商设置？请参阅 供应商使用手册。
• 想了解供应商/模型匹配？请参阅 供应商与模型。
• 想要网页搜索、MCP、安全设置或更多配置选项？请参阅 配置。
• 想在本地运行？请参阅 Ollama、vLLM 或其他本地 OpenAI 兼容服务器，以及完整的 供应商参考。
• 想在 Telegram、Discord、微信或飞书等聊天应用中运行 nanobot？请参阅 聊天应用。
• 想使用 Docker 或 Linux 服务部署？请参阅 部署。

☁️ 部署

Render — 一键渲染

从仓库现成的蓝图部署纳米机器人的网关和捆绑的 WebUI：

Render 会要求提供 ANTHROPIC_API_KEY 和私有 NANOBOT_WEB_TOKEN，然后为会话、内存和 WebUI 历史记录提供持久化存储。持久化磁盘需要付费的 Render 服务。

自托管

更喜欢使用自己的基础设施？请按照 部署指南 设置 Docker、Docker Compose、Linux 服务和 macOS LaunchAgent。

🌐 网页界面

WebUI 随已发布的 wheel 内置，无需单独的前端构建。它是浏览器工作台，用于持久主题、临时聊天、可见的代理活动、工作区控制、应用、技能、自动化和设置。使用 nanobot webui 启动它。

下面的截图使用示例对话、说明性令牌数量和暂停计划。

使用方式：

• 为不同的任务和项目保持独立的主题；
• 在对话不应保存到历史记录或记忆时使用临时聊天；
• 检查推理、工具调用、文件编辑、差异、命令输出和生成的产物；
• 在不离开对话的情况下切换模型和工作区；
• 从一个地方配置提供者和聊天频道，连接应用程序，发现技能，并管理自动化。

保持相关工作并排显示

将最多四个对话分组，并排列成列、行、网格，或主窗格加辅助窗格。每个主题保持自己的历史记录。从 @ 菜单中选择另一个主题，或将其拖入撰写区，让代理读取其上下文并在会话间协调工作。

为每个任务选择一个项目、访问模式和模型。附上文档或图片，然后立即发送后续内容或将其排队到下一次响应。探索主题和面板 →

检查工作及其上下文

展开代理活动以查看推理、工具调用和文件更改。切换 设置 → 外观 → 文件编辑显示 为 差异 以显示内联补丁。当提供者报告时，作曲家的上下文指示器显示当前上下文大小、每轮输入令牌以及缓存重用情况。

上下文压缩也出现在对话时间轴中。探索活动和上下文 →

将您的工具引入对话中

使用应用程序连接 MCP 服务器，启用代理插件，并管理本地 CLI 应用适配器。添加预设或自定义服务器，然后使用 @ 附加可用工具。技能提供可重复使用的指令；设置包含模型、语音、图像、网页和聊天频道的配置。

探索应用 → · 发现技能 → · 连接聊天应用 →

让定期任务按计划运行

从应该接收其结果的主题请求自动化。使用 任务 来查看和管理计划，或使用 日历 按日期扫描已完成和即将运行的任务。本地触发器允许脚本按需启动已保存的任务。

保持网关运行以便按计划交付。探索自动化 →

对于应保持在保存的主题历史记录和长期记忆之外的对话，请使用标题中的临时聊天。临时聊天在连接关闭时结束，并在受限模式下使用默认工作区。

有关局域网访问、后台操作、工作区控制和完整功能介绍，请参阅WebUI指南。正在进行前端开发吗？使用 webui/README.md 。

架构

🐈 nanobot 通过将所有操作围绕一个小型代理循环来保持轻量化：消息从聊天应用进入，LLM 决定何时需要工具，内存或技能仅作为上下文被调用，而不是变成一个沉重的编排层。这保持了核心路径的可读性和易扩展性，同时仍然允许你添加通道、工具、内存和部署选项而不会把系统变成一个单一庞大的整体。

文档

浏览 仓库文档 获取最新功能和 GitHub 开发版本，或访问 nanobot.wiki 查看稳定版本文档。

• 使用面向任务的指南：指南
• 无技术背景也可开始：无需技术背景开始
• 从零开始学习开发者基础：安装与快速开始
• 了解运行时模型：概念
• 阅读源代码级别地图：架构
• 选择提供商/模型：提供商和模型
• 复制提供商设置示例：提供商手册
• 调试设置和运行时失败：故障排除
• 通过熟悉的聊天应用与 nanobot 对话：聊天应用 AI 代理 · 聊天应用
• 安排或触发代理工作：自动化
• 配置提供商、网络搜索、MCP 和运行时行为：配置
• 将 nanobot 与本地工具和自动化集成：OpenAI 兼容 API · Python SDK
• 使用 Docker 或作为 Linux 服务运行 nanobot：部署

版本发布

最新版本发布：v0.3.5

v0.3.5 将工作台带到终端，并使跨浏览器、终端和聊天应用的对话更容易继续。

• 在原生终端工作台中使用与 WebUI 相同的网关和已保存对话。
• 最多并排安排四个浏览器对话，提及已保存的会话，或打开临时聊天。
• 检查每轮上下文使用情况和压缩进度，更持久的历史记录和恢复功能。
• 发现技能，连接应用，并通过扩展的 WebUI 流程管理计划工作。

阅读 v0.3.5 版本发布说明和升级说明

最新更新

• 2026-09-19 🔎 可搜索的提供者设置、一致的提供者身份，以及更顺畅的 Linear 入职体验。
• 2026-09-18 ♻️ 对中断工作有更清晰的恢复支持，并支持 Discord 回复上下文。
• 2026-09-16 📦 平台轮子捆绑了版本匹配的本地终端 UI。
• 2026-09-15 🚀 发布了 v0.3.5，包含共享终端工作台、多窗格 WebUI 和可见的上下文连续性。
• 2026-09-07 🔌 WeCom 媒体上传使用 SDK API，CI 会跳过无关作业。

有关早期更新，请参见 发布存档 或 GitHub 发布。

开源合作伙伴

🤝 贡献

使用纳米机器人完成实际任务，报告损坏的部分，然后选择一个重点改进。

• 阅读 CONTRIBUTING.md 了解开发工作流程。
• 浏览 未解决的问题 寻找需要调查的问题。
• 为针对性的修复或集成打开一个 拉取请求 。

维护者

任旭彬

陈永如