杂谈

其他

零基础教程：Windows 部署 nanobot，5 分钟拥有私人 AI 助理

发表于 2026年03月04日阅读 7 评论 0

大家好，我是何三，独立开发者

项目简介

nanobot 是一个超轻量级的个人 AI 助手框架，核心代码仅约 4000 行，却功能强大。它支持多种聊天平台（微信、飞书、钉钉、Telegram 等）和主流大语言模型，特别适合个人和小型团队快速部署使用。

特点： - 🪶 超轻量：核心代码仅 ~4000 行 - ⚡ 快速部署：5 分钟即可完成配置 - 💬 多平台支持：微信、飞书、钉钉、Telegram、Discord 等 - 🤖 模型丰富：支持 Qwen、Kimi、DeepSeek、GLM 等国产主流模型 - 🔧 易于扩展：支持 MCP 协议、自定义工具、技能系统

支持的模型

nanobot 通过 LiteLLM 统一接口，支持以下主流模型提供商：

国产模型（重点推荐）

提供商	配置字段	典型模型	API 申请地址
通义千问 (Qwen)	`dashscope`	qwen-max, qwen-plus, qwen-turbo	阿里云百炼
Kimi (月之暗面)	`moonshot`	kimi-k2.5, kimi-dev	Moonshot AI
深度求索 (DeepSeek)	`deepseek`	deepseek-chat, deepseek-coder	DeepSeek
智谱 AI (GLM)	`zhipu`	glm-4, glm-4-flash, glm-4-air	智谱 AI 开放平台
MiniMax	`minimax`	MiniMax-M2.1, abab6.5	MiniMax
火山引擎	`volcengine`	Doubao 系列	火山引擎
硅基流动	`siliconflow`	多种开源模型	SiliconFlow

国际模型

提供商	配置字段	典型模型
Anthropic	`anthropic`	claude-opus-4-5, claude-sonnet-4-0
OpenAI	`openai`	gpt-4o, gpt-4-turbo, gpt-3.5-turbo
Google	`gemini`	gemini-2.0-flash, gemini-pro
OpenRouter	`openrouter`	聚合多家模型

本地部署

vLLM：支持本地部署的开源模型（Llama、Qwen 等）
自定义：任何 OpenAI 兼容的 API 接口

环境准备

1. Python 环境

要求：Python 3.11 或更高版本

检查 Python 版本

打开 PowerShell（按 Win + X，选择"Windows PowerShell"），输入：

python --version

如果显示 Python 3.11.x 或更高版本，跳过此步。否则需要安装：

安装 Python 3.11+

访问 Python 官网
下载 Python 3.11 或 3.12 的 Windows 安装包
重要：安装时勾选 "Add Python to PATH"
点击 "Install Now"

验证安装

重新打开 PowerShell，输入：

python --version
pip --version

确保两个命令都能正常输出版本号。

2. 获取 API Key

根据你想使用的模型，提前申请对应的 API Key：

通义千问：登录阿里云百炼 → API-KEY 管理 → 创建新密钥
Kimi：登录 Moonshot 开放平台 → 个人中心 → API Key
DeepSeek：登录 DeepSeek 平台 → API Keys
智谱 AI：登录智谱 AI 开放平台 → API Key 管理

建议：将 API Key 保存在记事本中，后续配置会用到。

安装步骤

方法一：从 PyPI 安装（推荐，最简单）

步骤 1：创建安装目录（可选）

为了便于管理，建议在用户目录下创建专门文件夹：

# 在用户主目录创建 nanobot 文件夹
mkdir $HOME\nanobot
cd $HOME\nanobot

步骤 2：安装 nanobot

pip install nanobot-ai

等待安装完成，看到 Successfully installed nanobot-ai 表示成功。

步骤 3：验证安装

nanobot --version

应输出版本号，如 nanobot 0.1.4.post3。

方法二：从源码安装（适合开发者）

如果你想使用最新功能或参与开发：

步骤 1：安装 Git（如果未安装）

从 Git 官网下载并安装 Git。

步骤 2：克隆项目

# 创建开发目录
mkdir $HOME\projects
cd $HOME\projects

# 克隆项目
git clone https://github.com/HKUDS/nanobot.git
cd nanobot

步骤 3：创建虚拟环境（推荐）

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
.\.venv\Scripts\Activate.ps1

激活后，命令行前面会出现 (.venv) 标识。

步骤 4：安装依赖

# 开发模式安装
pip install -e .

步骤 5：验证安装

nanobot --version

配置详解

1. 初始化配置

运行以下命令，nanobot 会自动创建配置文件目录：

nanobot onboard

这个命令会： - 创建 ~/.nanobot/ 目录 - 生成默认配置文件 config.json - 创建工作空间目录

2. 编辑配置文件

配置文件位于：C:\Users\你的用户名\.nanobot\config.json

打开配置文件

方法 1：使用记事本

notepad $HOME\.nanobot\config.json

方法 2：使用 VS Code（推荐）

如果安装了 VS Code：

code $HOME\.nanobot\config.json

3. 配置模板

模板 A：使用通义千问（Qwen）

{
  "providers": {
    "dashscope": {
      "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "qwen-max",
      "provider": "dashscope"
    }
  },
  "channels": {
    "telegram": {
      "enabled": false
    }
  }
}

说明： - 将 apiKey 替换为你的阿里云百炼 API Key - model 可选值：qwen-max、qwen-plus、qwen-turbo、qwen-long 等

模板 B：使用 Kimi

{
  "providers": {
    "moonshot": {
      "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "apiBase": "https://api.moonshot.cn/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "kimi-k2.5",
      "provider": "moonshot"
    }
  }
}

说明： - 将 apiKey 替换为你的 Moonshot API Key - apiBase 国内使用 https://api.moonshot.cn/v1，国际使用 https://api.moonshot.ai/v1 - model 可选值：kimi-k2.5、kimi-dev、kimi-mid 等

模板 C：使用 DeepSeek

{
  "providers": {
    "deepseek": {
      "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "deepseek-chat",
      "provider": "deepseek"
    }
  }
}

说明： - 将 apiKey 替换为你的 DeepSeek API Key - model 可选值：deepseek-chat（对话）、deepseek-coder（代码）

模板 D：使用智谱 AI（GLM）

{
  "providers": {
    "zhipu": {
      "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "glm-4",
      "provider": "zhipu"
    }
  }
}

说明： - 将 apiKey 替换为你的智谱 AI API Key - model 可选值：glm-4、glm-4-flash、glm-4-air、glm-4-flashx 等

模板 E：使用火山引擎（Doubao）

{
  "providers": {
    "volcengine": {
      "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "doubao-pro-32k",
      "provider": "volcengine"
    }
  }
}

说明： - 将 apiKey 替换为你的火山引擎 API Key - 需要在火山引擎控制台创建 endpoint

模板 F：使用 OpenRouter（聚合平台，推荐新手）

OpenRouter 是一个模型聚合平台，一个 API Key 可以使用多家模型：

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  }
}

说明： - 访问 OpenRouter 创建 API Key - model 可选值非常多，如 anthropic/claude-3-5-sonnet、meta-llama/llama-3-70b-instruct 等 - 格式：提供商/模型名

模板 G：使用本地 vLLM 部署

{
  "providers": {
    "vllm": {
      "apiKey": "EMPTY",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "Qwen/Qwen2.5-72B-Instruct",
      "provider": "vllm"
    }
  }
}

说明： - 需要先部署 vLLM 服务 - apiBase 填写你的 vLLM 服务地址

4. 完整配置示例

这是一个包含多个提供商的完整配置：

{
  "agents": {
    "defaults": {
      "workspace": "~/.nanobot/workspace",
      "model": "qwen-max",
      "provider": "dashscope",
      "max_tokens": 8192,
      "temperature": 0.1,
      "max_tool_iterations": 40,
      "memory_window": 100
    }
  },
  "providers": {
    "dashscope": {
      "apiKey": "sk-xxxxxxxxxxxxxxxx"
    },
    "deepseek": {
      "apiKey": "sk-xxxxxxxxxxxxxxxx"
    },
    "zhipu": {
      "apiKey": "xxxxxxxxxxxxxxxx"
    },
    "moonshot": {
      "apiKey": "sk-xxxxxxxxxxxxxxxx",
      "apiBase": "https://api.moonshot.cn/v1"
    }
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "token": "",
      "allow_from": ["your_user_id"]
    },
    "feishu": {
      "enabled": false,
      "app_id": "",
      "app_secret": ""
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "",
      "client_secret": ""
    }
  },
  "tools": {
    "web": {
      "search": {
        "api_key": "",
        "max_results": 5
      }
    },
    "exec": {
      "timeout": 60
    },
    "restrict_to_workspace": false
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790,
    "heartbeat": {
      "enabled": true,
      "interval_s": 1800
    }
  }
}

启动与测试

1. CLI 命令行模式（最简单）

启动 Agent

nanobot agent

启动后会进入交互式对话界面，你可以直接输入问题。

测试示例

你好，请介绍一下自己

帮我写一个 Python 函数，计算斐波那契数列

分析一下最近的人工智能发展趋势

退出对话

输入以下任一命令退出： - exit - quit - /exit - /quit

2. Gateway 网关模式（连接聊天平台）

如果你想让 nanobot 连接到 Telegram、飞书、钉钉等聊天平台：

步骤 1：配置聊天平台

以 Telegram 为例，在 config.json 中添加：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["your_user_id"]
    }
  }
}

获取 Telegram Bot Token： 1. 在 Telegram 中搜索 @BotFather 2. 发送 /newbot 创建机器人 3. 按提示设置名称，获得 Token 4. 发送 /myid 获取你的用户 ID

步骤 2：启动网关

nanobot gateway

启动后，nanobot 会连接到 Telegram，你可以通过 Telegram 与机器人对话。

3. 测试不同模型

测试 Qwen

确保配置文件中设置：

{
  "agents": {
    "defaults": {
      "model": "qwen-max",
      "provider": "dashscope"
    }
  }
}

运行：

nanobot agent

输入测试问题：

请用中文写一首关于春天的诗

测试 Kimi

修改配置：

{
  "agents": {
    "defaults": {
      "model": "kimi-k2.5",
      "provider": "moonshot"
    }
  }
}

运行并测试：

总结这篇文章的核心观点：https://example.com/article

（Kimi 擅长长文本处理）

测试 DeepSeek

修改配置：

{
  "agents": {
    "defaults": {
      "model": "deepseek-chat",
      "provider": "deepseek"
    }
  }
}

运行并测试：

写一个快速排序的 Python 实现，并添加详细注释

（DeepSeek 在代码方面表现优秀）

测试 GLM

修改配置：

{
  "agents": {
    "defaults": {
      "model": "glm-4",
      "provider": "zhipu"
    }
  }
}

运行并测试：

解释一下量子计算的基本原理

4. 查看状态

nanobot status

会显示当前配置状态、API Key 配置情况等。

5. 使用 Web 搜索功能（可选）

如果需要联网搜索，配置 Brave Search API：

获取 API Key：访问 Brave Search API
修改配置：

{
  "tools": {
    "web": {
      "search": {
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      }
    }
  }
}

测试：

搜索一下最近的人工智能新闻

常见问题

Q1: `nanobot` 命令找不到

原因： Python 的 Scripts 目录不在 PATH 环境变量中

解决方案：

方法 1（临时）：

$env:Path += ";C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\Scripts"

方法 2（永久）： 1. 右键"此电脑" → "属性" → "高级系统设置" 2. 点击"环境变量" 3. 在"系统变量"中找到 Path，点击"编辑" 4. 添加：C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\Scripts 5. 重启 PowerShell

Q2: 安装时出现权限错误

错误信息： PermissionError: [WinError 5] 拒绝访问

解决方案：

方法 1：使用用户模式安装

pip install --user nanobot-ai

方法 2：以管理员身份运行 PowerShell 1. 按 Win + X 2. 选择"Windows PowerShell (管理员)" 3. 重新运行安装命令

方法 3：使用虚拟环境（推荐）

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install nanobot-ai

Q3: API Key 无效

错误信息： 401 Unauthorized 或 API key not valid

检查清单： - ✅ API Key 是否复制完整（没有多余空格） - ✅ API Key 是否已激活（部分平台需要手动激活） - ✅ 账户是否有余额或免费额度 - ✅ 配置的 provider 字段是否与 API Key 匹配 - ✅ apiBase 是否正确（特别是 Kimi 有国内/国际之分）

调试方法：

在配置文件中临时添加详细日志（如果支持），或尝试用 curl 测试：

# 测试 DeepSeek API
curl https://api.deepseek.com/v1/models `
  -H "Authorization: Bearer sk-你的 APIKey"

Q4: 模型名称错误

错误信息： model not found 或 invalid model

解决方案：

检查模型名称拼写是否正确
确认该模型在你的账户中可用
查看平台文档确认模型名称格式

常见模型名称： - 通义千问：qwen-max、qwen-plus、qwen-turbo - Kimi：kimi-k2.5、kimi-dev - DeepSeek：deepseek-chat、deepseek-coder - GLM：glm-4、glm-4-flash

Q5: 网络连接超时

错误信息： Connection timeout 或 Network error

解决方案：

检查网络：确保能正常访问互联网
配置代理（如果需要）：

{
  "channels": {
    "telegram": {
      "proxy": "http://127.0.0.1:7890"
    }
  },
  "tools": {
    "web": {
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

使用国内镜像：部分平台提供国内 API 端点

Q6: 虚拟环境激活失败

错误信息： 无法加载文件，因为在此系统上禁止运行脚本

解决方案：

这是 PowerShell 执行策略限制，运行以下命令：

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认，然后重新激活虚拟环境。

Q7: 依赖冲突

错误信息： 各种 Requirement already satisfied 或版本冲突

解决方案：

方法 1：升级 pip 和依赖

python -m pip install --upgrade pip
pip install --upgrade nanobot-ai

方法 2：使用干净虚拟环境

# 删除旧虚拟环境
rmdir -Recurse -Force .venv

# 创建新的
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install nanobot-ai

Q8: 配置文件格式错误

错误信息： Validation error 或 JSON decode error

解决方案：

使用 JSON 验证工具检查格式
确保使用双引号 " 而不是单引号 '
确保最后一个元素后面没有逗号
检查括号是否匹配

在线工具： JSON Validator

Q9: 内存不足

问题： 运行大型模型时系统卡顿

解决方案：

降低 max_tokens 配置：

{
  "agents": {
    "defaults": {
      "max_tokens": 4096
    }
  }
}

使用更小的模型变体（如 glm-4-flash 而不是 glm-4）
关闭其他占用内存的程序

Q10: 如何切换模型？

方法 1： 修改配置文件后重启

方法 2： 临时指定（如果 CLI 支持）

nanobot agent --model qwen-max

方法 3： 使用环境变量（部分平台支持）

$env:NANOBOT_MODEL="qwen-max"
nanobot agent

进阶使用

1. 多模型切换

在配置文件中配置多个提供商，根据需要修改 agents.defaults.model 和 provider。

2. 自定义工作空间

{
  "agents": {
    "defaults": {
      "workspace": "D:\\nanobot\\workspace"
    }
  }
}

3. 启用工具调用

nanobot 支持文件操作、Shell 命令、Web 搜索等工具：

{
  "tools": {
    "exec": {
      "timeout": 120,
      "path_append": ""
    },
    "restrict_to_workspace": true
  }
}

4. 使用 MCP 协议

nanobot 支持 Model Context Protocol (MCP)，可以连接外部工具和服务：

{
  "tools": {
    "mcp_servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\YourName"]
      }
    }
  }
}

获取帮助

官方文档：GitHub Repository
问题反馈：GitHub Issues
社区讨论：
飞书群：查看 COMMUNICATION.md
Discord：Discord Community

总结

恭喜你完成 nanobot 的部署！现在你可以：

✅ 使用 CLI 与 AI 助手对话
✅ 连接聊天平台（Telegram、飞书等）
✅ 切换不同的国产大模型
✅ 使用文件操作、Web 搜索等工具
✅ 开发自定义技能

下一步建议： 1. 尝试不同的模型，找到最适合你的 2. 配置聊天平台，随时随地与 AI 对话 3. 探索工具调用功能，让 AI 帮你执行任务 4. 查看技能系统，扩展 AI 能力

祝你使用愉快！🎉

版权声明：如无特殊说明，文章均为何三笔记原创，转载请注明出处

本文链接：https://www.h3blog.com/article/694/

项目简介
支持的模型
环境准备
- 1. Python 环境
- 2. 获取 API Key
安装步骤
- 方法一：从 PyPI 安装（推荐，最简单）
- 方法二：从源码安装（适合开发者）
配置详解
启动与测试
常见问题
进阶使用
获取帮助
总结

零基础教程：Windows 部署 nanobot，5 分钟拥有私人 AI 助理

项目简介

支持的模型

国产模型（重点推荐）

国际模型

本地部署

环境准备

1. Python 环境

检查 Python 版本

安装 Python 3.11+

验证安装

2. 获取 API Key

安装步骤

方法一：从 PyPI 安装（推荐，最简单）

步骤 1：创建安装目录（可选）

步骤 2：安装 nanobot

步骤 3：验证安装

方法二：从源码安装（适合开发者）

步骤 1：安装 Git（如果未安装）

步骤 2：克隆项目

步骤 3：创建虚拟环境（推荐）

步骤 4：安装依赖

步骤 5：验证安装

配置详解

1. 初始化配置

2. 编辑配置文件

打开配置文件

3. 配置模板

模板 A：使用通义千问（Qwen）

模板 B：使用 Kimi

模板 C：使用 DeepSeek

模板 D：使用智谱 AI（GLM）

模板 E：使用火山引擎（Doubao）

模板 F：使用 OpenRouter（聚合平台，推荐新手）

模板 G：使用本地 vLLM 部署

4. 完整配置示例

启动与测试

1. CLI 命令行模式（最简单）

启动 Agent

测试示例

退出对话

2. Gateway 网关模式（连接聊天平台）

步骤 1：配置聊天平台

步骤 2：启动网关

3. 测试不同模型

测试 Qwen

测试 Kimi

测试 DeepSeek

测试 GLM

4. 查看状态

5. 使用 Web 搜索功能（可选）

常见问题

Q1: nanobot 命令找不到

Q2: 安装时出现权限错误

Q3: API Key 无效

Q4: 模型名称错误

Q5: 网络连接超时

Q6: 虚拟环境激活失败

Q7: 依赖冲突

Q8: 配置文件格式错误

Q9: 内存不足

Q10: 如何切换模型？

进阶使用

1. 多模型切换

2. 自定义工作空间

3. 启用工具调用

4. 使用 MCP 协议

获取帮助

总结

Q1: `nanobot` 命令找不到