hkuds--nanobot/README.md at b4e00535906d7c845923ce82099bc75b451c6505

wehub/hkuds--nanobot

Fork 0

Files

T

wehub-resource-sync b4e0053590

Test Suite / test (push) Has been cancelled

Details

Test Suite / webui (push) Has been cancelled

Details

docs: make Chinese README the default

2026-07-13 10:52:14 +00:00

19 KiB

Raw Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

🐈 nanobot 是一款开源、超轻量的个人 AI 智能体（agent），你可以真正拥有它。它将智能体核心保持小巧且可读，同时提供适用于真实长期工作的实用组件：WebUI、聊天渠道、工具、记忆、MCP、模型路由、自动化与部署。

从这里开始

你想要...	前往
无需终端/配置背景即可安装 nanobot	零基础入门
快速安装并获得一条 CLI 回复	安装与快速开始
打开内置浏览器 UI	WebUI
连接 Telegram、Discord、WeChat、Slack、Email、Mattermost 或其他聊天应用	聊天应用
配置提供商、回退模型、Langfuse、MCP、Web 工具或安全设置	文档与配置
理解或扩展内部实现	架构与开发

nanobot 能做什么？

nanobot 是一个可自托管的个人 AI 智能体运行时。它可以：

在浏览器 WebUI 或终端中运行
连接 Telegram、Discord、Slack、WeChat、Email、Mattermost 及其他聊天应用
使用文件、shell、Web 搜索、Web 抓取、MCP、cron、图像生成和子智能体（subagents）等工具
通过 Dream 保留会话历史与长期记忆
运行长期目标与定时自动化
提供 Python SDK 与 OpenAI 兼容 API，便于集成
部署为长期运行的本地或服务端智能体网关

开源合作伙伴

近期更新

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 安装器修复。

更早的更新请见发布归档或 GitHub 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 密钥或配置文件对你而言尚不熟悉，请使用零基础入门中的引导式教程，而非本精简 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。

若要在不更改环境的情况下预览计划，请传入 --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.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，或在虚拟环境中安装。

从源码安装

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

验证安装：

nanobot --version

🚀 快速开始

1. 初始化

若一键设置已启动向导并在其中完成快速开始，可跳过此步骤。

nanobot onboard

若你偏好交互式设置，请使用 nanobot onboard --wizard。

2. 配置（~/.nanobot/config.json）

若你已在向导中配置好提供商（provider）和模型设置，可跳过此步骤。

nanobot onboard 会创建 ~/.nanobot/config.json 和 ~/.nanobot/workspace/。请在配置文件中配置这 两部分。将以下代码块添加或合并到现有文件中，而不是替换整个文件。

下方示例使用通用的 OpenAI 兼容 custom 提供商，以便精简路径不会推荐某一托管服务。提供商示例是配方（recipe），而非排名或背书。可复制粘贴的提供商专属设置见 Provider Cookbook。

设置你的 API 密钥：

{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

设置模型预设并设为活动状态：

{
  "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.<provider>`
API key	`providers.<provider>.apiKey`
Preset provider name	`modelPresets.primary.provider`
Model ID	`modelPresets.primary.model`
Endpoint URL, only when needed	`providers.<provider>.apiBase`

3. 打开 WebUI

启动浏览器工作台：

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 消息：

nanobot status
nanobot agent -m "Hello!"

在 nanobot status 中，大多数提供商显示 not set 是正常的。活动预设的提供商应已配置，且 Config 与 Workspace 应显示勾选标记。

若上述步骤正常，可启动交互式聊天：

nanobot agent

需要 PATH、API 密钥、提供商/模型匹配或 JSON 错误方面的帮助？请参阅更完整的 Install and Quick Start 与 Troubleshooting。

想要可粘贴的提供商设置？见 Provider Cookbook
想了解提供商/模型匹配？见 Providers and Models
需要网页搜索、MCP、安全设置或更多配置选项？见 Configuration
想在本地运行？见 Ollama、vLLM or another local OpenAI-compatible server，以及完整的 provider reference。
想在 Telegram、Discord、WeChat 或 Feishu 等聊天应用中使用 nanobot？见 Chat Apps
需要 Docker 或 Linux 服务部署？见 Deployment

🌐 WebUI

WebUI 内置于已发布的 wheel 包中 — 无需额外构建步骤。它是用于聊天会话、工作区控制、Apps、Skills、Automations 和设置的浏览器工作台。完整用户指南见 docs/webui.md。

打开方式

nanobot webui

该命令在确认后启用本地 WebSocket 通道，启动 gateway，并打开 http://127.0.0.1:8765. 若要从局域网中的另一台设备打开，见 WebUI docs -> LAN access。

WebUI 默认由 WebSocket 通道在端口 8765 上提供服务。gateway 的 18790 端口用于健康检查端点，而非浏览器 UI。

Tip

正在开发 WebUI 本身？请参阅 webui/README.md 了解源码树、Vite 开发服务器、构建与测试工作流。

🏗️ 架构

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