> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/HKUDS/nanobot) · [上游 README](https://github.com/HKUDS/nanobot/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

🐈 **nanobot** 是一款开源、超轻量的个人 AI 智能体（agent），你可以真正拥有它。它将智能体核心保持小巧且可读，同时提供适用于真实长期工作的实用组件：WebUI、聊天渠道、工具、记忆、MCP、模型路由、自动化与部署。 ## 从这里开始 | 你想要... | 前往 | |---|---| | 无需终端/配置背景即可安装 nanobot | [零基础入门](./docs/start-without-technical-background.md) | | 快速安装并获得一条 CLI 回复 | [安装](#-安装) 与 [快速开始](#-快速开始) | | 打开内置浏览器 UI | [WebUI](#-webui) | | 连接 Telegram、Discord、WeChat、Slack、Email、Mattermost 或其他聊天应用 | [聊天应用](./docs/chat-apps.md) | | 配置提供商、回退模型、Langfuse、MCP、Web 工具或安全设置 | [文档](./docs/README.md) 与 [配置](./docs/configuration.md) | | 理解或扩展内部实现 | [架构](./docs/architecture.md) 与 [开发](./docs/development.md) | ## nanobot 能做什么？ nanobot 是一个可自托管的个人 AI 智能体运行时。它可以： - 在浏览器 WebUI 或终端中运行 - 连接 Telegram、Discord、Slack、WeChat、Email、Mattermost 及其他聊天应用 - 使用文件、shell、Web 搜索、Web 抓取、MCP、cron、图像生成和子智能体（subagents）等工具 - 通过 Dream 保留会话历史与长期记忆 - 运行长期目标与定时自动化 - 提供 Python SDK 与 OpenAI 兼容 API，便于集成 - 部署为长期运行的本地或服务端智能体网关 ## 最新版本 **v0.2.2 - Durability Release** 亮点： - 分段式 WebUI 对话记录 - Python SDK 运行时控制 - 自动化管理 - 搜索/STT 提供商改进 - 网关/会话/提供商可靠性提升 [查看完整更新日志](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2) ## 开源合作伙伴

## 近期更新 - **2026-06-21** Python SDK 运行时控制、可选 Keenable 密钥、更简洁的运行钩子。 - **2026-06-20** Telegram 富文本消息、更安全的 SDK 并发、更顺畅的快速开始。 - **2026-06-19** Firecrawl 应用、OpenAI 图像编辑、更安全的会话删除。 - **2026-06-18** 飞书恢复、Keenable 搜索、Mistral 优化、工作区感知的 git。 - **2026-06-17** 默认空闲自动压缩、更清晰的 `/dream`、macOS 安装器修复。更早的更新请见[发布归档](./docs/release-archive.md)或 [GitHub releases](https://github.com/HKUDS/nanobot/releases). ## 💡 为什么选择 nanobot - **持久化工作流**：目标、记忆、工具与聊天上下文可在长期工作中持续保留。 - **聊天原生触达**：WebUI、API、Telegram、飞书、Slack、Discord、Teams、邮件与 Mattermost。 - **模型自由**：OpenAI 兼容 API、本地 LLM、图像生成、搜索与回退模型。 - **小巧核心**：内部实现可读，内置 MCP、记忆、部署与自动化。 - **拥有你的技术栈**：无需庞大平台，即可检查、定制、自托管与扩展。 ## 📦 安装 > [!IMPORTANT] > 若你需要最新功能与实验特性，请从源码安装。 > > 若你追求最稳定的日常使用体验，请通过 PyPI 安装或使用 `uv`。请选择**一种**安装方式：前置条件：Python 3.11 或更高版本。仅源码安装需要 Git；仅在你开发 WebUI 本身时才需要 Node.js/Bun。若终端、API 密钥或配置文件对你而言尚不熟悉，请使用[零基础入门](./docs/start-without-technical-background.md)中的引导式教程，而非本精简 README 路径。 **一键安装** macOS / Linux： ```bash curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh ``` Windows PowerShell： ```powershell irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex ``` 默认命令会从 PyPI 安装或升级 `nanobot-ai`，然后启动 `nanobot onboard --wizard`。它通过使用活动虚拟环境、`uv`、`pipx`，或 `~/.nanobot/venv` 下的托管 venv，避免系统级 pip 安装。若快速开始已完成，请跳过下方手动初始化/配置步骤，直接进入**打开 WebUI**。若要在不更改环境的情况下预览计划，请传入 `--dry-run`；当你想预览 main 分支安装时，可将其与 `--dev` 组合使用。 ```bash curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run ``` ```powershell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run ``` 若要安装当前的 `main` 分支，请传入 `--dev`： ```bash curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev ``` ```powershell & ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev ``` 若你想先查看脚本，可打开 [`scripts/install.sh`](./scripts/install.sh) 或 [`scripts/install.ps1`](./scripts/install.ps1)。 **使用 `uv` 安装** ```bash uv tool install nanobot-ai ``` **使用 pip 从 PyPI 安装** ```bash python -m pip install nanobot-ai ``` 若在 macOS 或 Linux 上 pip 报告 `externally-managed-environment`，请使用一键安装器、`uv tool install nanobot-ai`、`pipx install nanobot-ai`，或在虚拟环境中安装。 **从源码安装** ```bash git clone https://github.com/HKUDS/nanobot.git cd nanobot python -m pip install -e . ``` 验证安装： ```bash nanobot --version ``` ## 🚀 快速开始 **1. 初始化** 若一键设置已启动向导并在其中完成快速开始，可跳过此步骤。 ```bash nanobot onboard ``` 若你偏好交互式设置，请使用 `nanobot onboard --wizard`。 **2. 配置**（`~/.nanobot/config.json`）若你已在向导中配置好提供商（provider）和模型设置，可跳过此步骤。 `nanobot onboard` 会创建 `~/.nanobot/config.json` 和 `~/.nanobot/workspace/`。请在配置文件中配置这 **两部分**。将以下代码块添加或合并到现有文件中，而不是替换整个文件。下方示例使用通用的 OpenAI 兼容 `custom` 提供商，以便精简路径不会推荐某一托管服务。提供商示例是配方（recipe），而非排名或背书。可复制粘贴的提供商专属设置见 [Provider Cookbook](./docs/provider-cookbook.md)。 *设置你的 API 密钥*： ```json { "providers": { "custom": { "apiKey": "your-api-key", "apiBase": "https://api.example.com/v1" } } } ``` *设置模型预设并设为活动状态*： ```json { "modelPresets": { "primary": { "label": "Primary", "provider": "custom", "model": "model-id-from-your-provider", "maxTokens": 8192, "contextWindowTokens": 200000, "temperature": 0.1 } }, "agents": { "defaults": { "modelPreset": "primary" } } } ``` 直接配置 `agents.defaults.provider` 和 `agents.defaults.model` 对现有配置仍然有效，但命名预设是推荐路径，因为它们还支持 `/model` 切换和 `fallbackModels`。对于其他提供商，配置结构相同： | 替换项 | 位置 | |---|---| | Provider config key | `providers.` | | API key | `providers..apiKey` | | Preset provider name | `modelPresets.primary.provider` | | Model ID | `modelPresets.primary.model` | | Endpoint URL, only when needed | `providers..apiBase` | **3. 打开 WebUI** 启动浏览器工作台： ```bash nanobot webui ``` `nanobot webui` 会在需要时准备本地 WebSocket 通道，启动 gateway，并打开 `http://127.0.0.1:8765`。默认将首次运行的 WebUI 绑定到 `127.0.0.1`，因此不会暴露到你的局域网（LAN）。不想一直开着终端？使用 `nanobot webui --background`，然后用 `nanobot gateway status`、`logs`、`restart` 和 `stop` 管理 gateway。若需手动或仅终端设置，可测试一条 CLI 消息： ```bash nanobot status nanobot agent -m "Hello!" ``` 在 `nanobot status` 中，大多数提供商显示 `not set` 是正常的。活动预设的提供商应已配置，且 `Config` 与 `Workspace` 应显示勾选标记。若上述步骤正常，可启动交互式聊天： ```bash nanobot agent ``` 需要 `PATH`、API 密钥、提供商/模型匹配或 JSON 错误方面的帮助？请参阅更完整的 [Install and Quick Start](./docs/quick-start.md) 与 [Troubleshooting](./docs/troubleshooting.md)。 - 想要可粘贴的提供商设置？见 [Provider Cookbook](./docs/provider-cookbook.md) - 想了解提供商/模型匹配？见 [Providers and Models](./docs/providers.md) - 需要网页搜索、MCP、安全设置或更多配置选项？见 [Configuration](./docs/configuration.md) - 想在本地运行？见 [Ollama](./docs/providers.md#ollama)、[vLLM or another local OpenAI-compatible server](./docs/providers.md#vllm-or-other-local-openai-compatible-server)，以及完整的 [provider reference](./docs/configuration.md#providers)。 - 想在 Telegram、Discord、WeChat 或 Feishu 等聊天应用中使用 nanobot？见 [Chat Apps](./docs/chat-apps.md) - 需要 Docker 或 Linux 服务部署？见 [Deployment](./docs/deployment.md) ## 🌐 WebUI WebUI **内置于已发布的 wheel 包中** — 无需额外构建步骤。它是用于聊天会话、工作区控制、Apps、Skills、Automations 和设置的浏览器工作台。完整用户指南见 [`docs/webui.md`](./docs/webui.md)。

nanobot webui preview

**打开方式** ```bash nanobot webui ``` 该命令在确认后启用本地 WebSocket 通道，启动 gateway，并打开 [`http://127.0.0.1:8765`](http://127.0.0.1:8765). 若要从局域网中的另一台设备打开，见 [WebUI docs -> LAN access](./docs/webui.md#lan-access)。 WebUI 默认由 WebSocket 通道在端口 `8765` 上提供服务。gateway 的 `18790` 端口用于健康检查端点，而非浏览器 UI。 > [!TIP] > 正在开发 WebUI 本身？请参阅 [`webui/README.md`](./webui/README.md) 了解源码树、Vite 开发服务器、构建与测试工作流。 ## 🏗️ 架构

nanobot architecture

🐈 nanobot 通过围绕一个精简的 agent 循环来保持轻量：消息从聊天应用进入，LLM 决定何时需要工具，memory 或 skills 仅作为上下文按需拉入，而不是变成沉重的编排层。这使核心路径清晰易读、易于扩展，同时仍允许你添加 channels、tools、memory 和部署选项，而不会把系统变成单体应用。 ## ✨ 功能

📈 24/7 Real-Time Market Analysis	🚀 Full-Stack Software Engineer	📅 Smart Daily Routine Manager	📚 Personal Knowledge Assistant

Discovery • Insights • Trends	Develop • Deploy • Scale	Schedule • Automate • Organize	Learn • Memory • Reasoning

## 📚 文档浏览 [repo docs](./docs/README.md) 获取最新功能与 GitHub 开发版信息，或访问 [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) 查看稳定版文档。 - 使用面向任务的指南：[Guides](./docs/guides/README.md) - 无技术背景入门：[Start Without Technical Background](./docs/start-without-technical-background.md) - 从零开始并具备开发者基础：[Install and Quick Start](./docs/quick-start.md) - 理解运行时模型：[Concepts](./docs/concepts.md) - 阅读源码级概览：[Architecture](./docs/architecture.md) - 选择提供商/模型：[Providers and Models](./docs/providers.md) - 复制提供商设置配方：[Provider Cookbook](./docs/provider-cookbook.md) - 调试设置与运行时故障：[Troubleshooting](./docs/troubleshooting.md) - 用熟悉的聊天应用与 nanobot 对话：[Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) · [Chat Apps](./docs/chat-apps.md) - 调度或触发 agent 工作：[Automations](./docs/automations.md) - 配置提供商、网页搜索、MCP 与运行时行为：[Configuration](./docs/configuration.md) - 将 nanobot 与本地工具和自动化集成：[OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md) - 使用 Docker 或作为 Linux 服务运行 nanobot：[Deployment](./docs/deployment.md) ## 🤝 贡献与路线图欢迎提交 PR！代码库刻意保持小巧且易读。🤗 ### 贡献流程有关环境搭建、代码审查与贡献指南，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 **路线图** — 选择一项并 [提交 PR](https://github.com/HKUDS/nanobot/pulls)! - **多模态（Multi-modal）** — 看见与听见（图像、语音、视频） - **长期记忆（Long-term memory）** — 永不遗忘重要上下文 - **更强的推理（Better reasoning）** — 多步规划与反思 - **更多集成** — 日历等 - **自我改进（Self-improvement）** — 从反馈与错误中学习 ## 联系方式本项目由 [Xubin Ren](https://github.com/re-bin) 发起，作为一项个人开源项目，并仍以个人身份、利用个人资源进行维护，同时得到开源社区的贡献。如有问题、想法或合作意向，欢迎联系 [xubinrencs@gmail.com](mailto:xubinrencs@gmail.com)。 ### 贡献者

## ⭐ Star 历史

感谢访问 ✨ nanobot！