nanobot 安装与配置

上级索引：00-概览与索引 | 上一篇：01-项目简介 | 下一篇：03-快速上手-WebUI

📋 环境要求

条件	要求
Python 版本	≥ 3.11
操作系统	macOS / Linux / Windows
其他依赖	Git（源码安装）、bun/npm（WebUI 构建，可选）

📦 安装方式

方式一：一键安装脚本（推荐）

bash

# 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

--dry-run 参数可预览安装计划而不实际执行

方式二：uv 安装

bash

uv tool install nanobot-ai

方式三：pip 安装（稳定版）

bash

pip install nanobot-ai

方式四：源码安装（最新特性）

bash

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

验证安装

bash

nanobot --version

⚙️ 首次配置

初始化工作区

bash

nanobot onboard
# 如果 config 较旧，刷新默认字段（保留现有值）：
nanobot onboard --refresh

关键路径

路径	说明
~/.nanobot/config.json	实例配置（providers、channels、tools、gateway 等）
~/.nanobot/workspace/	Agent 工作区（memory、sessions、cron jobs、skills）
<workspace>/sessions/*.jsonl	会话历史（JSONL 格式）
<workspace>/memory/MEMORY.md	长期记忆文件
<workspace>/cron/jobs.json	定时任务存储
<workspace>/SOUL.md	Agent 身份定义文件

配置 AI Provider（config.json 片段）

json

{
  "modelPresets": {
    "primary": {
      "provider": "openrouter",
      "model": "anthropic/claude-opus-4.5"
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

支持的 Provider

Provider Key	说明
openai	OpenAI 官方
anthropic	Claude 系列
openrouter	LLM 路由网关（推荐入门）
azure_openai	Azure 部署
bedrock	AWS Bedrock
ollama / vllm	本地 LLM
xai_grok	Grok（X.ai）
github_copilot	GitHub Copilot OAuth
custom	任意 OpenAI-compatible 端点
stepfun、xiaomi_mimo 等	中国市场特有

多实例运行

bash

# 指定独立的 config + workspace
nanobot onboard --config ./bot-a/config.json --workspace ./bot-a/workspace
nanobot gateway --config ./bot-a/config.json --workspace ./bot-a/workspace

🐛 常见问题

问题	原因	解决方案
nanobot 不在 PATH	uv tool 安装后未添加到 PATH	按提示执行 export PATH=... 或重开终端
externally-managed-environment 报错	pip 受系统保护	改用 uv tool install nanobot-ai 或 pip install --break-system-packages
Windows WebUI 启动失败	缺少 bun/npm	安装 Node.js 后重试，或直接用 CLI 模式

📝 个人笔记

{{待填：安装过程踩坑记录}}

---

🔗 延伸阅读

• 03-快速上手-WebUI
• 04-基础概念
• GitHub 仓库