HKUDS/nanobot

🐈 **nanobot** 是一个开源、超轻量级的个人 AI 代理，你可以真正拥有它。它保持了代理核心的精简和可读性，同时为你提供了进行实际长期工作所需的实用组件：WebUI、聊天渠道、工具、记忆、MCP、模型路由、自动化和部署。 ## 从这里开始 | 你想要... | 前往 | |---|---| | 在没有终端/配置基础的情况下安装 nanobot | [无技术背景入门](./docs/start-without-technical-background.md) | | 快速安装并获得一次 CLI 回复 | [安装](#-install) 和 [快速开始](#-quick-start) | | 打开内置的浏览器 UI | [WebUI](#-webui) | | 连接 Telegram、Discord、微信、Slack、电子邮件、Mattermost 或其他聊天应用 | [聊天应用](./docs/chat-apps.md) | | 配置 provider、fallback model、Langfuse、MCP、web 工具或安全性 | [文档](./docs/README.md) 和 [配置](./docs/configuration.md) | | 了解或扩展内部实现 | [架构](./docs/architecture.md) 和 [开发](./docs/development.md) | ## nanobot 能做什么？ nanobot 是一个自托管的个人 AI 代理 runtime。它可以： - 在浏览器 WebUI 或终端中运行 - 连接到 Telegram、Discord、Slack、微信、电子邮件、Mattermost 和其他聊天应用 - 使用文件、shell、web 搜索、web 抓取、MCP、cron、图像生成和 subagent 等工具 - 通过 Dream 保留会话历史和长期记忆 - 运行长周期目标和定时自动化任务 - 暴露 Python SDK 和兼容 OpenAI 的 API 用于集成 - 部署为长期运行的本地或服务端 agent gateway ## 最新发布 **v0.2.2 - 持久性发布** 亮点： - 分段的 WebUI 记录 - Python SDK runtime 控制 - 自动化管理 - 搜索/STT provider 改进 - Gateway/session/provider 可靠性 [查看完整 changelog](https://github.com/HKUDS/nanobot/releases/tag/v0.2.2) ## 开源合作伙伴

## 近期更新 - **2026-07-12** 显式 `/goal` 激活，更安全的 runtime 和工作区访问。 - **2026-07-11** 语法高亮预览和 diff，排队的 prompt，更安全的编辑。 - **2026-07-10** 稳定的 model routing，多行 CLI 输入，新的自动化指南。 - **2026-07-09** 实时文件编辑 diff，更安全的 localhost 设置，Matrix 图像修复。 - **2026-07-08** 更安全的 WebUI/API 设置，引导刷新，响应式 prompt 栏。 如需了解较早的更新，请参阅 [发布归档](./docs/release-archive.md) 或 [GitHub 发布](https://github.com/HKUDS/nanobot/releases)。 ## 💡 为什么选择 nanobot - **持久的工作流**：目标、记忆、工具和聊天上下文在长期运行的工作中依然保留。 - **原生聊天触达**：WebUI、API、Telegram、飞书、Slack、Discord、Teams、电子邮件和 Mattermost。 - **模型自由**：兼容 OpenAI 的 API、本地 LLM、图像生成、搜索和 fallback。 - **精简核心**：可读的内部实现，内置 MCP、记忆、部署和自动化。 - **掌控你的技术栈**：无需庞大的平台即可检查、自定义、自托管和扩展。 ## 📦 安装 选择**一种**安装方式： 前置条件：Python 3.11 或更高版本。Git 仅在源码安装时需要。已发布的包已包含 WebUI；当前的源码安装需要 `bun` 或 `npm` 来构建它。 如果你对终端、API 密钥或配置文件感到陌生，请使用 [无技术背景入门](./docs/start-without-technical-background.md) 中的引导式零基础指南，而不是这个简化的 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 onboard --wizard`。它通过使用活动的虚拟环境、`uv`、`pipx` 或 `~/.nanobot/venv` 下的托管 venv，来避免系统级的 pip 安装。如果快速开始已完成，请跳过下面的手动初始化/配置步骤，直接前往 **打开 WebUI**。安装程序还会打印它用来运行 nanobot 的确切命令；如果 `nanobot` 不在 `PATH` 中，请在下面复用该完整命令。 要在不更改环境的情况下预览计划，请传入 `--dry-run`；当你想要预览 main 分支安装时，请将其与 `--dev` 结合使用。 ``` 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 ``` 如果需要安装当前的 `main` 分支，请传入 `--dev`： ``` curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev ``` ``` & ([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` 安装** ``` 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`，或在虚拟环境中安装。 **从源码安装** 必须安装 `bun` 或 `npm`。在激活的虚拟环境中运行： ``` git clone https://github.com/HKUDS/nanobot.git cd nanobot python -m pip install . ``` 验证安装： ``` nanobot --version ``` 如果 `nanobot` 不在 `PATH` 中，请通过安装它的方法来调用它：复用推荐安装程序的命令，使用 `uv tool run --from nanobot-ai nanobot ...` 或 `pipx run --spec nanobot-ai nanobot ...`，或者使用安装了该包的环境中的 Python 可执行文件。 ## 🚀 快速开始 **1. 初始化** 如果一键设置已经启动了向导并在那里完成了快速开始，请跳过此步骤。 ``` nanobot onboard ``` 如果你更喜欢交互式设置，请使用 `nanobot onboard --wizard`。 **2. 配置** (`~/.nanobot/config.json`) 如果你已经在向导中配置了 provider 和模型设置，请跳过此步骤。 `nanobot onboard` 会创建 `~/.nanobot/config.json` 和 `~/.nanobot/workspace/`。在配置文件中配置这**两个部分**。将以下代码块添加或合并到现有文件中，而不是替换整个文件。 下面的示例使用了通用的兼容 OpenAI 的 `custom` provider，因此该精简路径不会推荐特定的托管服务。Provider 示例仅为操作指南，并不代表排名或背书。有关可复制粘贴的特定 provider 设置，请参阅 [Provider 指南](./docs/provider-cookbook.md)。 *设置你的 API 密钥*： ``` { "providers": { "custom": { "apiKey": "your-api-key", "apiBase": "https://api.example.com/v1" } } } ``` *设置一个 model preset 并将其激活*： ``` { "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` 对于现有配置仍然有效，但推荐使用命名 preset，因为它们还支持 `/model` 切换和 `fallbackModels`。 对于其他 provider，相同的配置结构依然适用： | 替换 | 位置 | |---|---| | Provider 配置键 | `providers.` | | API 密钥 | `providers..apiKey` | | Preset provider 名称 | `modelPresets.primary.provider` | | 模型 ID | `modelPresets.primary.model` | | Endpoint URL（仅在需要时） | `providers..apiBase` | **3. 打开 WebUI** 稳定兼容的路径是： ``` nanobot gateway ``` 保持终端打开并访问 `http://127.0.0.1:8765`。当前的源码版本还提供了 `nanobot webui`，它会在需要时准备本地 WebSocket 渠道，启动 gateway 并自动打开浏览器。首次运行 WebUI 默认绑定到 `127.0.0.1`，因此它不会暴露给你的局域网。不想一直开着终端？可以使用 `nanobot gateway --background`，然后使用 `nanobot gateway status`、`logs`、`restart` 和 `stop` 来管理它。 对于手动或仅使用终端的设置，请测试一条 CLI 消息： ``` nanobot status nanobot agent -m "Hello!" ``` 在 `nanobot status` 中，大多数 provider 显示 `not set` 是正常的。激活的 preset 的 provider 应该已配置，并且 `Config` 和 `Workspace` 应该显示勾号。 如果一切正常，开始交互式聊天： ``` nanobot agent ``` 在 `PATH`、API 密钥、provider/model 匹配或 JSON 错误方面需要帮助？请参阅更详细的 [安装和快速开始](./docs/quick-start.md) 和 [故障排除](./docs/troubleshooting.md)。 - 想要可直接粘贴的 provider 设置？请参阅 [Provider 指南](./docs/provider-cookbook.md) - 想了解 provider/model 匹配？请参阅 [Provider 和模型](./docs/providers.md) - 需要 web 搜索、MCP、安全设置或更多配置选项？请参阅 [配置](./docs/configuration.md) - 想在本地运行？请参阅 [Ollama](./docs/providers.md#ollama)、[vLLM 或其他兼容 OpenAI 的本地服务器](./docs/providers.md#vllm-or-other-local-openai-compatible-server)，以及完整的 [provider 参考](./docs/configuration.md#providers)。 - 想在 Telegram、Discord、微信或飞书等聊天应用中运行 nanobot？请参阅 [聊天应用](./docs/chat-apps.md) - 需要 Docker 或 Linux 服务部署？请参阅 [部署](./docs/deployment.md) ## 🌐 WebUI WebUI **内置在已发布的 wheel 包中** —— 无需额外的构建步骤。它是用于聊天会话、工作区控制、Apps、Skills、Automations 和设置的浏览器工作台。有关完整的用户指南，请参阅 [`docs/webui.md`](./docs/webui.md)。

**打开它** ``` nanobot webui ``` 在当前的源码版本上，该命令会在确认后启用本地 WebSocket 渠道，启动 gateway，并打开 [`http://127.0.0.1:8765`](http://127.0.0.1:8765)。如果你安装的稳定版本不包含 `nanobot webui`，请运行 `nanobot gateway` 并手动打开该地址。要从局域网中的其他设备打开它，请参阅 [WebUI 文档 -> 局域网访问](./docs/webui.md#lan-access)。 WebUI 默认由端口 `8765` 上的 WebSocket 渠道提供服务。Gateway 的 `18790` 端口用于健康检查 endpoint，而不是浏览器 UI。 ## 🏗️ 架构

🐈 nanobot 通过将一切围绕一个小型 agent 循环来保持轻量级：消息从聊天应用传入，LLM 决定何时需要工具，而记忆或技能仅作为上下文被引入，而不是成为沉重的编排层。这使得核心路径保持可读且易于扩展，同时仍允许你添加渠道、工具、记忆和部署选项，而不会使系统变成一个庞大的单体架构。 ## ✨ 功能

📈 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

## 📚 文档 浏览 [仓库文档](./docs/README.md) 以获取最新功能和 GitHub 开发版本，或访问 [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) 获取稳定版本文档。 - 使用面向任务的指南：[指南](./docs/guides/README.md) - 零技术背景起步：[无技术背景入门](./docs/start-without-technical-background.md) - 从零开始掌握开发者基础：[安装和快速开始](./docs/quick-start.md) - 了解 runtime 模型：[概念](./docs/concepts.md) - 阅读源码级映射：[架构](./docs/architecture.md) - 选择 provider/model：[Provider 和模型](./docs/providers.md) - 复制 provider 设置指南：[Provider 指南](./docs/provider-cookbook.md) - 调试设置和 runtime 故障：[故障排除](./docs/troubleshooting.md) - 使用熟悉的聊天应用与你的 nanobot 交流：[聊天应用 AI Agent](./docs/guides/chat-app-ai-agent.md) · [聊天应用](./docs/chat-apps.md) - 安排或触发 agent 工作：[自动化](./docs/automations.md) - 配置 provider、web 搜索、MCP 和 runtime 行为：[配置](./docs/configuration.md) - 将 nanobot 与本地工具和自动化集成：[兼容 OpenAI 的 API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md) - 使用 Docker 或作为 Linux 服务运行 nanobot：[部署](./docs/deployment.md) ## 🤝 贡献与路线图 欢迎提交 PR！代码库特意保持得非常精简和易读。🤗 ### 贡献流程 **路线图** — 选择一个条目并[提交 PR](https://github.com/HKUDS/nanobot/pulls)！ - **Multi-modal** — 视听感知（图像、语音、视频） - **长期记忆** — 永不忘记重要上下文 - **更好的推理** —步规划和反思 - **更多集成** — 日历等 - **自我改进** — 从反馈和错误中学习 ## 联系方式

标签：AI智能体, Python, 工具集成, 无后门, 逆向工具