-🐈 **nanobot** is an open-source, ultra-lightweight personal AI agent you can truly own. It keeps the agent core small and readable while giving you the practical pieces for real long-running work: WebUI, chat channels, tools, memory, MCP, model routing, automation, and deployment.
+🐈 **nanobot** 是一款开源、超轻量的个人 AI 智能体(agent),你可以真正拥有它。它将智能体核心保持小巧且可读,同时提供适用于真实长期工作的实用组件:WebUI、聊天渠道、工具、记忆、MCP、模型路由、自动化与部署。
-## Start Here
+## 从这里开始
-| You want to... | Go to |
+| 你想要... | 前往 |
|---|---|
-| Install nanobot with no terminal/config background | [Start Without Technical Background](./docs/start-without-technical-background.md) |
-| Install quickly and get one CLI reply | [Install](#-install) and [Quick Start](#-quick-start) |
-| Open the bundled browser UI | [WebUI](#-webui) |
-| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [Chat Apps](./docs/chat-apps.md) |
-| Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) |
-| Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) |
+| 无需终端/配置背景即可安装 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) |
-## What can nanobot do?
+## nanobot 能做什么?
-nanobot is a self-hosted personal AI agent runtime. It can:
+nanobot 是一个可自托管的个人 AI 智能体运行时。它可以:
-- run in a browser WebUI or terminal
-- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, and other chat apps
-- use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents
-- keep session history and long-term memory through Dream
-- run long-horizon goals and scheduled automations
-- expose a Python SDK and OpenAI-compatible API for integrations
-- deploy as a long-running local or server-side agent gateway
+- 在浏览器 WebUI 或终端中运行
+- 连接 Telegram、Discord、Slack、WeChat、Email、Mattermost 及其他聊天应用
+- 使用文件、shell、Web 搜索、Web 抓取、MCP、cron、图像生成和子智能体(subagents)等工具
+- 通过 Dream 保留会话历史与长期记忆
+- 运行长期目标与定时自动化
+- 提供 Python SDK 与 OpenAI 兼容 API,便于集成
+- 部署为长期运行的本地或服务端智能体网关
-## Latest Release
+## 最新版本
**v0.2.2 - Durability Release**
-Highlights:
+亮点:
-- Segmented WebUI transcripts
-- Python SDK runtime controls
-- Automation management
-- Search/STT provider improvements
-- Gateway/session/provider reliability
+- 分段式 WebUI 对话记录
+- Python SDK 运行时控制
+- 自动化管理
+- 搜索/STT 提供商改进
+- 网关/会话/提供商可靠性提升
-[See full changelog](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2)
+[查看完整更新日志](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2)
-## Open Source Partners
+## 开源合作伙伴
-## Recent Updates
+## 近期更新
-- **2026-06-21** Python SDK runtime controls, optional Keenable key, cleaner run hooks.
-- **2026-06-20** Telegram rich messages, safer SDK concurrency, smoother Quick Start.
-- **2026-06-19** Firecrawl app, OpenAI image edits, safer session deletion.
-- **2026-06-18** Feishu recovery, Keenable search, Mistral polish, workspace-aware git.
-- **2026-06-17** Default idle auto-compact, clearer `/dream`, macOS installer fixes.
+- **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 安装器修复。
-For older updates, see the [release archive](./docs/release-archive.md) or [GitHub releases](https://github.com/HKUDS/nanobot/releases).
+更早的更新请见[发布归档](./docs/release-archive.md)或 [GitHub releases](https://github.com/HKUDS/nanobot/releases).
-## 💡 Why nanobot
+## 💡 为什么选择 nanobot
-- **Persistent workflows**: goals, memory, tools, and chat context survive long-running work.
-- **Chat-native reach**: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, and Mattermost.
-- **Model freedom**: OpenAI-compatible APIs, local LLMs, image generation, search, and fallbacks.
-- **Small core**: readable internals with MCP, memory, deployment, and automation built in.
-- **Own your stack**: inspect, customize, self-host, and extend without a giant platform.
+- **持久化工作流**:目标、记忆、工具与聊天上下文可在长期工作中持续保留。
+- **聊天原生触达**:WebUI、API、Telegram、飞书、Slack、Discord、Teams、邮件与 Mattermost。
+- **模型自由**:OpenAI 兼容 API、本地 LLM、图像生成、搜索与回退模型。
+- **小巧核心**:内部实现可读,内置 MCP、记忆、部署与自动化。
+- **拥有你的技术栈**:无需庞大平台,即可检查、定制、自托管与扩展。
-## 📦 Install
+## 📦 安装
> [!IMPORTANT]
-> If you want the newest features and experiments, install from source.
+> 若你需要最新功能与实验特性,请从源码安装。
>
-> If you want the most stable day-to-day experience, install from PyPI or with `uv`.
+> 若你追求最稳定的日常使用体验,请通过 PyPI 安装或使用 `uv`。
-Pick **one** install method:
+请选择**一种**安装方式:
-Prerequisites: Python 3.11 or newer. Git is only needed for a source install; Node.js/Bun are only needed if you are developing the WebUI itself.
+前置条件:Python 3.11 或更高版本。仅源码安装需要 Git;仅在你开发 WebUI 本身时才需要 Node.js/Bun。
-If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in [Start Without Technical Background](./docs/start-without-technical-background.md) instead of this compact README path.
+若终端、API 密钥或配置文件对你而言尚不熟悉,请使用[零基础入门](./docs/start-without-technical-background.md)中的引导式教程,而非本精简 README 路径。
-**One-command setup**
+**一键安装**
-macOS / Linux:
+macOS / Linux:
```bash
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh
```
-Windows PowerShell:
+Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex
```
-The default command installs or upgrades `nanobot-ai` from PyPI, then starts `nanobot onboard --wizard`. It avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. If Quick Start finishes, skip the manual initialize/configure steps below and go straight to **Open the WebUI**.
+默认命令会从 PyPI 安装或升级 `nanobot-ai`,然后启动 `nanobot onboard --wizard`。它通过使用活动虚拟环境、`uv`、`pipx`,或 `~/.nanobot/venv` 下的托管 venv,避免系统级 pip 安装。若快速开始已完成,请跳过下方手动初始化/配置步骤,直接进入**打开 WebUI**。
-To preview the plan without changing your environment, pass `--dry-run`; combine it with `--dev` when you want to preview the main-branch install.
+若要在不更改环境的情况下预览计划,请传入 `--dry-run`;当你想预览 main 分支安装时,可将其与 `--dev` 组合使用。
```bash
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
@@ -137,7 +143,7 @@ curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run
```
-To install the current `main` branch instead, pass `--dev`:
+若要安装当前的 `main` 分支,请传入 `--dev`:
```bash
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev
@@ -147,23 +153,23 @@ curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev
```
-If you prefer to inspect the script first, open [`scripts/install.sh`](./scripts/install.sh) or [`scripts/install.ps1`](./scripts/install.ps1).
+若你想先查看脚本,可打开 [`scripts/install.sh`](./scripts/install.sh) 或 [`scripts/install.ps1`](./scripts/install.ps1)。
-**Install with `uv`**
+**使用 `uv` 安装**
```bash
uv tool install nanobot-ai
```
-**Install from PyPI with pip**
+**使用 pip 从 PyPI 安装**
```bash
python -m pip install nanobot-ai
```
-If pip reports `externally-managed-environment` on macOS or Linux, use the one-command installer, `uv tool install nanobot-ai`, `pipx install nanobot-ai`, or install inside a virtual environment.
+若在 macOS 或 Linux 上 pip 报告 `externally-managed-environment`,请使用一键安装器、`uv tool install nanobot-ai`、`pipx install nanobot-ai`,或在虚拟环境中安装。
-**Install from source**
+**从源码安装**
```bash
git clone https://github.com/HKUDS/nanobot.git
@@ -171,33 +177,33 @@ cd nanobot
python -m pip install -e .
```
-Verify the install:
+验证安装:
```bash
nanobot --version
```
-## 🚀 Quick Start
+## 🚀 快速开始
-**1. Initialize**
+**1. 初始化**
-Skip this step if the one-command setup already started the wizard and Quick Start finished there.
+若一键设置已启动向导并在其中完成快速开始,可跳过此步骤。
```bash
nanobot onboard
```
-Use `nanobot onboard --wizard` if you prefer an interactive setup.
+若你偏好交互式设置,请使用 `nanobot onboard --wizard`。
-**2. Configure** (`~/.nanobot/config.json`)
+**2. 配置**(`~/.nanobot/config.json`)
-Skip this step if you already configured provider and model settings in the wizard.
+若你已在向导中配置好提供商(provider)和模型设置,可跳过此步骤。
-`nanobot onboard` creates `~/.nanobot/config.json` and `~/.nanobot/workspace/`. Configure these **two parts** in the config file. Add or merge the following blocks into the existing file instead of replacing the whole file.
+`nanobot onboard` 会创建 `~/.nanobot/config.json` 和 `~/.nanobot/workspace/`。请在配置文件中配置这 **两部分**。将以下代码块添加或合并到现有文件中,而不是替换整个文件。
-The example below uses a generic OpenAI-compatible `custom` provider so the compact path does not recommend one hosted service. Provider examples are recipes, not rankings or endorsements. For copyable provider-specific setup, see [Provider Cookbook](./docs/provider-cookbook.md).
+下方示例使用通用的 OpenAI 兼容 `custom` 提供商,以便精简路径不会推荐某一托管服务。提供商示例是配方(recipe),而非排名或背书。可复制粘贴的提供商专属设置见 [Provider Cookbook](./docs/provider-cookbook.md)。
-*Set your API key*:
+*设置你的 API 密钥*:
```json
{
@@ -210,7 +216,7 @@ The example below uses a generic OpenAI-compatible `custom` provider so the comp
}
```
-*Set a model preset and make it active*:
+*设置模型预设并设为活动状态*:
```json
{
@@ -232,11 +238,11 @@ The example below uses a generic OpenAI-compatible `custom` provider so the comp
}
```
-Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but named presets are the recommended path because they also power `/model` switching and `fallbackModels`.
+直接配置 `agents.defaults.provider` 和 `agents.defaults.model` 对现有配置仍然有效,但命名预设是推荐路径,因为它们还支持 `/model` 切换和 `fallbackModels`。
-For another provider, the same config shape still applies:
+对于其他提供商,配置结构相同:
-| Replace | Where |
+| 替换项 | 位置 |
|---|---|
| Provider config key | `providers.` |
| API key | `providers..apiKey` |
@@ -244,70 +250,70 @@ For another provider, the same config shape still applies:
| Model ID | `modelPresets.primary.model` |
| Endpoint URL, only when needed | `providers..apiBase` |
-**3. Open the WebUI**
+**3. 打开 WebUI**
-Start the browser workbench:
+启动浏览器工作台:
```bash
nanobot webui
```
-`nanobot webui` prepares the local WebSocket channel if needed, starts the gateway, and opens `http://127.0.0.1:8765`. It binds the first-run WebUI to `127.0.0.1` by default, so it is not exposed to your LAN. Prefer not to keep a terminal open? Use `nanobot webui --background`, then manage the gateway with `nanobot gateway status`, `logs`, `restart`, and `stop`.
+`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。
-For manual or terminal-only setup, test one CLI message:
+若需手动或仅终端设置,可测试一条 CLI 消息:
```bash
nanobot status
nanobot agent -m "Hello!"
```
-In `nanobot status`, it is normal for most providers to say `not set`. The active preset's provider should be configured, and `Config` plus `Workspace` should show check marks.
+在 `nanobot status` 中,大多数提供商显示 `not set` 是正常的。活动预设的提供商应已配置,且 `Config` 与 `Workspace` 应显示勾选标记。
-If that works, start an interactive chat:
+若上述步骤正常,可启动交互式聊天:
```bash
nanobot agent
```
-Need help with `PATH`, API keys, provider/model matching, or JSON errors? See the fuller [Install and Quick Start](./docs/quick-start.md) and [Troubleshooting](./docs/troubleshooting.md).
+需要 `PATH`、API 密钥、提供商/模型匹配或 JSON 错误方面的帮助?请参阅更完整的 [Install and Quick Start](./docs/quick-start.md) 与 [Troubleshooting](./docs/troubleshooting.md)。
-- Want a pasteable provider setup? See [Provider Cookbook](./docs/provider-cookbook.md)
-- Want to understand provider/model matching? See [Providers and Models](./docs/providers.md)
-- Want web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md)
-- Want to run locally? See [Ollama](./docs/providers.md#ollama), [vLLM or another local OpenAI-compatible server](./docs/providers.md#vllm-or-other-local-openai-compatible-server), and the full [provider reference](./docs/configuration.md#providers).
-- Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md)
-- Want Docker or Linux service deployment? See [Deployment](./docs/deployment.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
-The WebUI ships **inside the published wheel** — no extra build step. It is the browser workbench for chat sessions, workspace controls, Apps, Skills, Automations, and settings. For the full user guide, see [`docs/webui.md`](./docs/webui.md).
+WebUI **内置于已发布的 wheel 包中** — 无需额外构建步骤。它是用于聊天会话、工作区控制、Apps、Skills、Automations 和设置的浏览器工作台。完整用户指南见 [`docs/webui.md`](./docs/webui.md)。
-**Open it**
+**打开方式**
```bash
nanobot webui
```
-The command enables the local WebSocket channel after confirmation, starts the gateway, and opens [`http://127.0.0.1:8765`](http://127.0.0.1:8765). To open it from another device on your LAN, see [WebUI docs -> LAN access](./docs/webui.md#lan-access).
+该命令在确认后启用本地 WebSocket 通道,启动 gateway,并打开 [`http://127.0.0.1:8765`](http://127.0.0.1:8765). 若要从局域网中的另一台设备打开,见 [WebUI docs -> LAN access](./docs/webui.md#lan-access)。
-The WebUI is served by the WebSocket channel on port `8765` by default. The gateway's `18790` port is for the health endpoint, not the browser UI.
+WebUI 默认由 WebSocket 通道在端口 `8765` 上提供服务。gateway 的 `18790` 端口用于健康检查端点,而非浏览器 UI。
> [!TIP]
-> Working on the WebUI itself? Check out [`webui/README.md`](./webui/README.md) for the source-tree, Vite dev server, build, and test workflow.
+> 正在开发 WebUI 本身?请参阅 [`webui/README.md`](./webui/README.md) 了解源码树、Vite 开发服务器、构建与测试工作流。
-## 🏗️ Architecture
+## 🏗️ 架构
-🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.
+🐈 nanobot 通过围绕一个精简的 agent 循环来保持轻量:消息从聊天应用进入,LLM 决定何时需要工具,memory 或 skills 仅作为上下文按需拉入,而不是变成沉重的编排层。这使核心路径清晰易读、易于扩展,同时仍允许你添加 channels、tools、memory 和部署选项,而不会把系统变成单体应用。
-## ✨ Features
+## ✨ 功能
@@ -330,52 +336,52 @@ The WebUI is served by the WebSocket channel on port `8765` by default. The gate
-## 📚 Docs
+## 📚 文档
-Browse the [repo docs](./docs/README.md) for the latest features and GitHub development version, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release documentation.
+浏览 [repo docs](./docs/README.md) 获取最新功能与 GitHub 开发版信息,或访问 [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) 查看稳定版文档。
-- Use task-oriented guides: [Guides](./docs/guides/README.md)
-- Start with no technical background: [Start Without Technical Background](./docs/start-without-technical-background.md)
-- Start from zero with developer basics: [Install and Quick Start](./docs/quick-start.md)
-- Understand the runtime model: [Concepts](./docs/concepts.md)
-- Read the source-level map: [Architecture](./docs/architecture.md)
-- Choose a provider/model: [Providers and Models](./docs/providers.md)
-- Copy provider setup recipes: [Provider Cookbook](./docs/provider-cookbook.md)
-- Debug setup and runtime failures: [Troubleshooting](./docs/troubleshooting.md)
-- Talk to your nanobot with familiar chat apps: [Chat App AI Agent](./docs/guides/chat-app-ai-agent.md) · [Chat Apps](./docs/chat-apps.md)
-- Schedule or trigger agent work: [Automations](./docs/automations.md)
-- Configure providers, web search, MCP, and runtime behavior: [Configuration](./docs/configuration.md)
-- Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md)
-- Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md)
+- 使用面向任务的指南:[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)
-## 🤝 Contribute & Roadmap
+## 🤝 贡献与路线图
-PRs welcome! The codebase is intentionally small and readable. 🤗
+欢迎提交 PR!代码库刻意保持小巧且易读。🤗
-### Contribution Flow
+### 贡献流程
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, review, and contribution guidelines.
+有关环境搭建、代码审查与贡献指南,请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
-**Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)!
+**路线图** — 选择一项并 [提交 PR](https://github.com/HKUDS/nanobot/pulls)!
-- **Multi-modal** — See and hear (images, voice, video)
-- **Long-term memory** — Never forget important context
-- **Better reasoning** — Multi-step planning and reflection
-- **More integrations** — Calendar and more
-- **Self-improvement** — Learn from feedback and mistakes
+- **多模态(Multi-modal)** — 看见与听见(图像、语音、视频)
+- **长期记忆(Long-term memory)** — 永不遗忘重要上下文
+- **更强的推理(Better reasoning)** — 多步规划与反思
+- **更多集成** — 日历等
+- **自我改进(Self-improvement)** — 从反馈与错误中学习
-## Contact
+## 联系方式
-This project was started by [Xubin Ren](https://github.com/re-bin) as a personal open-source project and continues to be maintained in an individual capacity using personal resources, with contributions from the open-source community. Feel free to contact [xubinrencs@gmail.com](mailto:xubinrencs@gmail.com) for questions, ideas, or collaboration.
+本项目由 [Xubin Ren](https://github.com/re-bin) 发起,作为一项个人开源项目,并仍以个人身份、利用个人资源进行维护,同时得到开源社区的贡献。如有问题、想法或合作意向,欢迎联系 [xubinrencs@gmail.com](mailto:xubinrencs@gmail.com)。
-### Contributors
+### 贡献者
-## ⭐ Star History
+## ⭐ Star 历史