Neo-MoFox Windows 部署指南

概述

本指南将引导你在 Windows 环境下完成 Neo-MoFox 的部署流程。

本教程覆盖从环境准备到成功运行的每一个步骤。

第一章：准备工作

在正式开始部署之前，我们需要先搭建好稳固的地基。请确保你的系统中已正确安装并配置了以下软件。

1.1 系统要求

操作系统: Windows 10 或 Windows 11

1.2 软件三件套：Python、Git 与 uv

这三款软件是部署流程的核心工具，缺一不可。

1.2.1 Python (版本 >= 3.11)

Python 是 Neo-MoFox 运行的编程语言环境。

下载: 前往 Python 官方网站下载最新版本的 Python 安装程序。请确保下载的版本号 大于等于 3.11。
安装 (关键步骤):
- 运行下载好的安装程序。
- 在安装界面的最下方，务必勾选 Add Python to PATH 选项。
- 点击 Install Now，等待安装完成。
验证:
- 按下 Win + R 键，输入 cmd 并回车，打开命令提示符。
- 输入以下命令并回车：
  shell
```
python --version
```
- 如果屏幕上显示出你安装的 Python 版本号（如 Python 3.11.4），则证明安装成功。

1.2.2 Git

Git 是一个版本控制工具，我们用它来从 GitHub 上获取 Neo-MoFox 的项目代码。

下载: 前往 Git 官方网站下载适用于 Windows 的安装程序。
安装: 运行安装程序。安装过程中会弹出多个选项，对于初学者，保持所有选项默认，一路点击 Next 即可。
验证:
- 同样在命令提示符中，输入以下命令并回车：
  shell
```
git --version
```
- 如果显示出 Git 的版本号（如 git version 2.41.0.windows.1），则证明安装成功。

1.2.3 uv (推荐的 Python 包管理器)

uv 是一个速度极快的 Python 包管理器，Neo-MoFox 使用它来管理项目依赖。

安装:
- 在命令提示符中，输入以下命令并回车：
  shell
```
pip install uv
```
验证:
- 输入以下命令并回车：
  shell
```
uv --version
```
- 如果显示出 uv 的版本号，则证明安装成功。

1.3 Napcat QQ 客户端

Napcat QQ 是一个 QQ 客户端，也是 Neo-MoFox 与 QQ 平台沟通的桥梁。

在继续下一步之前，请务必参考 NapCatQQ 官方文档，完成客户端的安装、配置，并确保你的 QQ 账号能够成功登录。这是整个部署流程的重要前置条件。

第二章：获取核心 — 克隆项目

万事俱备，现在将 Neo-MoFox 的核心代码下载到你的电脑中。“君”入瓮——将 Neo-MoFox 的核心代码下载到你的电脑中。

2.1 创建'机器人的家' (图形化操作)

首先，我们需要为机器人创建一个专属的“家”。

打开文件资源管理器：点击任务栏上的黄色文件夹图标，或者按下 Win + E 快捷键。
选择位置：在左侧导航栏选择一个空间充裕的磁盘，比如 D: 盘或 E: 盘。
新建文件夹：在空白处点击鼠标右键，选择 新建 -> 文件夹。
命名文件夹：将新文件夹命名为 Neo-MoFox_Deployment。

⚠️ 重要提示: 为了避免未来可能出现的奇怪问题，请确保文件夹的完整路径中不包含任何中文、空格或特殊字符。例如，D:\Neo-MoFox_Deployment 是一个好路径，但 D:\我的机器人 1号 则不推荐。

2.2 下载项目代码

现在，我们需要在这个“机器人的家”里打开命令行，来执行代码下载命令。

快速打开命令行:
- 双击进入你刚刚创建的 Neo-MoFox_Deployment 文件夹。
- 点击文件资源管理器顶部的地址栏。
- 删除地址栏里原来的路径，输入 cmd，然后按下回车键。
- 这时，一个黑色的命令提示符窗口会弹出，并且它的路径已经自动定位到了你的“机器人的家”里。
执行克隆命令:
- 在弹出的命令提示符窗口中，粘贴并执行以下命令：

官方地址备用地址1备用地址2

shell

git clone https://github.com/MoFox-Studio/Neo-MoFox.git

shell

git clone https://kgithub.com/MoFox-Studio/Neo-MoFox.git

shell

git clone https://xget.xi-xu.me/gh/MoFox-Studio/Neo-MoFox.git

🌐 网络小贴士: 如果你发现下载速度极慢或连接失败,这通常是由于网络问题。可以尝试使用备用镜像地址。

执行命令后，Git 会开始下载项目文件。当进度条走完，命令行界面不再滚动时，就代表克隆完成了。

此时，回到你的文件资源管理器，会发现 Neo-MoFox_Deployment 文件夹里多出了一个名为 Neo-MoFox 的新文件夹。恭喜，你已经成功获取了项目代码！

第三章：安装依赖

进入项目目录:
shell
```
cd Neo-MoFox
```
安装依赖:
shell
```
uv sync
```
uv sync 会自动创建虚拟环境并安装所有依赖。
等待下载安装完成即可。

依赖安装失败？ 通常是网络问题，重试一次。持续失败请尝试切换网络或使用代理。

第四章：首次启动——生成配置文件

在开始配置之前，我们需要先运行一次程序，让 Neo-MoFox 自动生成所有必需的配置文件。这是部署流程中的重要一步，因为配置文件需要程序首次运行时自动创建。

4.1 生成插件配置文件

Neo-MoFox 拥有强大的插件管理系统。在我们第一次启动程序时，它会自动检测所有内置插件，并为它们创建默认的配置文件。

首次启动:
- 确保你的命令行终端当前目录在 Neo-MoFox 文件夹中。
- 确保你当前的目录是 Neo-MoFox 文件夹。
- 执行以下命令，来启动一次 Neo-MoFox：
  shell
```
uv run main.py
```
- 程序启动后，你会看到大量的日志信息在屏幕上滚动。当日志滚动停止，并且没有新的信息出现时，说明程序已经完成了初始化工作，并且生成了所有的配置文件。
生成配置并关闭:
- 当你看到 config 文件夹被创建，这次启动的主要目的——生成配置文件——就已经达成了。如果程序还在运行，请在命令行窗口中，按下 Ctrl + C 来关闭程序。程序会进行"优雅关闭"，请稍等片刻直至其完全退出。

第五章：核心配置——让机器人"认识"你

现在配置文件已经生成，我们可以开始修改它们，赋予机器人身份和智慧。

🔧 编辑器推荐: 为了避免不必要的格式或编码错误，强烈建议使用专业的代码编辑器来修改配置文件，例如带有even better toml 插件的 Visual Studio Code、Notepad++ 或 Sublime Text。请™不要使用 Windows 自带的"记事本"。

在本章，我们只修改两个最核心的文件，以保证机器人能顺利启动并响应。

5.1 `core.toml`：机器人的“身份”

这个文件定义了机器人的基本身份信息和主人。

修改内容 (至少修改以下一项):
- 用编辑器打开 config/core.toml 文件。
- 主人 QQ 号: 找到 [permissions] 配置节下的 owner_list，将其配置为你的 QQ 号。
  ⚠️ 格式注意: 请严格按照 ['platform:user_id', ...] 的格式填写，注意英文引号。
  toml
```
[permissions]
# Bot所有者列表，格式：['platform:user_id', ...]
# 值类型：list, 默认值：[]
owner_list = []
```

5.2 `model.toml`：机器人的“大脑”

这个文件用于配置机器人使用的大语言模型（LLM），是机器人能否思考和回答问题的关键。

修改内容 (关键步骤):
- 为了让机器人能够开口说话，你必须至少配置一个可用的大语言模型服务。
- 我们已经为您准备了一份专门的快速上手指南，请点击并参照以下链接完成模型配置：
  - 模型配置快速上手指南
- 对于初次部署的用户，只需完成上述快速上手指南中的步骤即可。更详细和高级的模型配置方法，可以在机器人成功运行后，再参考模型配置进阶指南.

第六章：连接世界 — OneBot 适配器配置

现在，机器人已经有了身份和大脑，还需要连接到 QQ 平台才能收发消息。通过配置 OneBot 适配器插件（onebot_adapter）来完成。

6.1 启用并配置插件

经过第四章的首次启动，所有内置插件的默认配置文件都已经被自动创建好了。

找到配置文件:
- 现在，请打开 Neo-MoFox/config/plugins/ 文件夹。你会发现里面出现了很多以插件名命名的文件夹。
- 这说明 Neo-MoFox 的所有内置插件的配置文件都在这里生成了，方便你未来探索和开启更多功能。
- 我们当前的目标是找到 onebot_adapter 文件夹，进入后用你的代码编辑器打开 config.toml 文件。
启用插件:
- 在打开的 config.toml 文件中，找到 [plugin] 配置节，确认 enabled 为 true（默认已开启）。
  toml
```
[plugin]
# 是否启用 onebot 适配器
# 值类型：bool, 默认值：true
enabled = true  # 默认已开启
```

6.2 配置连接参数

这是整个部署流程中关键的一步，目的是让 Neo-MoFox (服务端) 与 Napcat QQ (客户端) 能够互相通信。我们将分别配置两端，并确保它们的信息完全一致。

第一部分：配置 Neo-MoFox 监听端口 * 找到 [onebot_server] 配置节的 port 小节，这里定义了 Neo-MoFox 将在哪个端口上“监听”来自 Napcat 客户端的连接请求。
toml
```
# OneBot WebSocket 服务器配置
[onebot_server]
# ws 连接模式: reverse/direct
# 值类型：str, 默认值："reverse"
mode = "reverse"

# OneBot WebSocket 服务地址
# 值类型：str, 默认值："localhost"
host = "localhost"

# OneBot WebSocket 服务端口
# 值类型：int, 默认值：8095
port = 8095
```
- 请记下这个 port 值 (默认为 8095)。除非 8095 端口已被其他程序占用，否则我们推荐保持默认设置。如果需要修改，请确保选择一个未被占用的端口。
第二部分：配置 Napcat 客户端连接地址
- 现在，回到 Napcat QQ 客户端，我们将告诉它去连接 Neo-MoFox 正在监听的端口。
- 步骤一：新建 Websocket 客户端
  - 在 Napcat 客户端中，点击左侧菜单的"网络配置"。
  - 在右侧选择 Websocket客户端 标签页，然后点击"新建"按钮。
- 步骤二：填写反向 WebSocket 地址
  - 在弹出的配置窗口中，将 URL 填写为 ws://127.0.0.1:8095。
  - 核心要点：此处的端口号 (8095) 必须与你在第一部分中 Neo-MoFox 配置文件里看到的 port 值完全一致。如果两边不一致，通信将百分之百失败。
  - 填写完毕后，点击"保存"。

完成以上步骤，机器人的“神经系统”就已经成功搭建。它现在知道了该如何与 QQ 世界进行通信。

第七章：正式启动

所有准备工作和配置都已完成，现在，是时候唤醒你的机器人了！

7.1 启动顺序

请严格按照以下顺序来启动各个组件。

第一步：启动并登录 Napcat QQ
- 打开你已经安装好的 Napcat QQ 客户端。
- 确保你的机器人 QQ 账号已经成功登录，并且客户端处于正常运行状态。
第二步：运行 Neo-MoFox
- 回到你的命令行终端窗口。
- 检查一件事:
  1. 确认当前路径在 Neo-MoFox 文件夹内。
- 执行最终的启动命令：
  shell
```
uv run main.py # 启动 Neo-MoFox 主程序
```

⚠️ 重要提示: 这个命令行窗口就是机器人的生命,请不要关闭它，最小化即可。一旦关闭，机器人就会下线。如果需要关闭机器人，请在这个窗口中按下 Ctrl + C，程序会进行优雅关闭。以后的启动流程也是一样的，先启动 Napcat QQ 客户端，确保它在线，再启动 Neo-MoFox。

7.2 观察日志，判断成功

程序运行后，日志会开始在命令行窗口中滚动。学会看日志，是判断机器人状态的关键。

当你看到类似以下几条关键信息时，就代表你的机器人已经成功启动并连接到了 QQ 平台：

log

[14:29:12] plugin_manager | INFO | 插件管理器初始化完成
[14:29:12] plugin_manager | INFO | ✅ 插件 'default_chatter' 的组件注册完成
[14:29:12] plugin_manager | INFO | ✅ 插件加载成功: default_chatter v1.0.0
  ✓ 已加载插件: default_chatter (#1)
[14:29:12] plugin_manager | INFO | ✅ 插件 'onebot_adapter' 的组件注册完成
[14:29:12] plugin_manager | INFO | ✅ 插件加载成功: onebot_adapter v2.0.0
  ✓ 已加载插件: onebot_adapter (#2)
[14:29:13] adapter_manager | INFO | 适配器启动成功: onebot_adapter:adapter:onebot_adapter
[14:29:13] adapter_manager | INFO | 适配器启动完成: 成功 1/1
[14:29:13] router_manager | INFO | 发现 1 个 Router，开始挂载...
[14:29:13] router_manager | INFO | Router 管理器初始化完成
[14:29:13] router_manager | INFO | 插件 default_chatter 的 Router 挂载完成: 0/0
[14:29:13] router_manager | INFO | 插件 onebot_adapter 的 Router 挂载完成: 0/0
[14:29:13] router_manager | INFO | 所有插件 Router 挂载完成: plugins=2, mounted_routers=0
[14:29:13] router_manager | INFO | ✅ 所有 Router 挂载完成
[14:29:13] event_manager | INFO | 开始构建事件订阅映射...
[14:29:13] event_manager | INFO | 事件管理器初始化完成
[14:29:13] event_manager | INFO | 订阅映射表构建完成，共处理 2 个 事件处理器
[14:29:13] event_manager | INFO | ✅ 事件订阅映射构建完成
[14:29:13] 流循环 | INFO | StreamLoopManager 已启动
[14:29:13] 消息分发 | INFO | StreamLoopManager 已随插件加载完成而启动
╭────────────────────────────────────────────────────── Success ───────────────────────────────────────────────────────╮
│  ✅ Bot 初始化成功，加载了 2 个插件                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
[19:58:46] [OneBot 适配器] 客户端已连接: ('127.0.0.1', 38207)
[19:58:46] [OneBot 适配器] Bot xxxxxxx(botQQ号) 连接成功

💡 日志解读:
看到 [19:58:46] [OneBot 适配器] Bot xxxxxxx(botQQ号) 连接成功 是最关键的一步，它标志着机器人与 QQ 的“神经连接”已打通。

7.3 测试机器人

现在，打开你的 QQ，向你的机器人账号发送一条消息，或者在一个它所在的群里 @它。

如果它回复了你，那么……

恭喜你，部署成功！你的第一个 AI Bot 已经正式诞生！

第八章：故障排除

当机器人没有按照预期工作时，请不要灰心。99% 的问题都可以通过仔细检查配置和日志来解决。

Q1: 启动成功，但日志里迟迟没有 `Napcat client connected` 信息？

这通常意味着 Neo-MoFox 和 Napcat QQ 客户端之间的“神经”没有接上。请按以下步骤排查：

检查 Napcat QQ: 确保 Napcat QQ 客户端本身已成功登录并处于在线状态。
检查端口号: 这是最常见的原因。请再次核对 config/plugins/onebot_adapter/config.toml 文件中 [onebot_server] 下的 port 值，是否与你 Napcat QQ 客户端里设置的反向 WebSocket 端口完全一致。
检查防火墙: 确保 Windows 防火墙或任何第三方杀毒软件没有阻止 Neo-MoFox 的网络连接。可以尝试暂时关闭防火墙进行测试。
检查 IP 地址: 确保 config.toml 中的 host (localhost) 和 Napcat 中的 IP (127.0.0.1) 是匹配的。通常保持默认即可。

Q2: 机器人成功连接，但在 QQ 里 @它或私聊它，它不回复？

这通常是配置问题或模型服务问题。

检查 Napcat QQ: 确保 Napcat QQ 客户端本身已成功登录并处于在线状态。
检查模型配置: 确认 config/model.toml 里的 API Key 是有效且可用的。可以检查一下你的模型服务商后台，看看 Key 是否填错、账户是否欠费。
检查白名单: 检查 config/plugins/onebot_adapter/config.toml 文件中 [features] 部分的 group_list 和 private_list。如果你开启了白名单，请确保你测试的群聊或私聊已经被加了进去。
查看日志: 观察机器人后台的命令行窗口。当你给机器人发消息时，看看日志是否刷新。如果有 ERROR 级别的红色错误信息，通常能定位到问题所在。

Q3: 日志里出现关于 `API KEY`、`authentication` 或 `401` 的错误？

这个错误非常明确，就是你的大语言模型配置出了问题。

请打开 config/model.toml 文件，仔细检查你配置的 api_key 和 base_url 是否有误。
登录你的模型服务商网站，检查 Key 是否被禁用、账户是否到期或欠费。

Q4: 我修改了配置文件，但好像没有生效？

Neo-MoFox 在启动时会加载所有配置文件。如果你在机器人运行中修改了配置，需要重启才能生效。

请在命令行窗口中，按下 Ctrl + C 关闭机器人。
待程序完全退出后，再重新执行 uv run main.py 命令来启动机器人。

结语：你的冒险才刚刚开始

至此，你已经成功走完了 Neo-MoFox 的部署全程，并拥有了一个属于自己的、能够思考和对话的 AI 伙伴。恭喜你！

但这仅仅是一个开始。本指南带你完成的，是让机器人“活过来”的最小化配置。Neo-MoFox 的真正魅力，在于其强大的可塑性和扩展性。你可以像搭乐高一样，通过调整配置文件，来塑造它的性格、学习它的表达、开启或关闭它的各项功能（如画图、Web搜索、记忆系统等）。

当你想进一步探索时，我们推荐你阅读以下文档：

机器人人格详细配置指南: 深入了解如何塑造机器人的性格、说话风格和行为模式。
模型配置进阶指南: 学习如何配置多个模型、本地模型以及更复杂的调用策略。
插件系统: Neo-MoFox 的所有功能都由插件实现。你可以通过 config/plugins/ 目录下的配置文件，来探索和启用更多有趣的内置功能。

如果你在探索的路上遇到了任何无法解决的难题，欢迎通过项目的 GitHub Issues 或社区与其他开发者交流。

现在，去和你的新伙伴聊天吧！

贡献者

minecraft1024a

ikun-11451

ikun两年半

micraft1024a

Windpicker-owo

xiaoxi68

subiz

页面历史

最后编辑于 1 天前

查看完整历史

Neo-MoFox Windows 部署指南 ​

概述 ​

第一章：准备工作 ​

1.1 系统要求 ​

1.2 软件三件套：Python、Git 与 uv ​

1.2.1 Python (版本 >= 3.11) ​

1.2.2 Git ​

1.2.3 uv (推荐的 Python 包管理器) ​

1.3 Napcat QQ 客户端 ​

第二章：获取核心 — 克隆项目 ​

2.1 创建'机器人的家' (图形化操作) ​

2.2 下载项目代码 ​

第三章：安装依赖 ​

第四章：首次启动——生成配置文件 ​

4.1 生成插件配置文件 ​

第五章：核心配置——让机器人"认识"你 ​

5.1 core.toml：机器人的“身份” ​

5.2 model.toml：机器人的“大脑” ​

第六章：连接世界 — OneBot 适配器配置 ​

6.1 启用并配置插件 ​

6.2 配置连接参数 ​

第七章：正式启动 ​

7.1 启动顺序 ​

7.2 观察日志，判断成功 ​

7.3 测试机器人 ​

第八章：故障排除 ​

结语：你的冒险才刚刚开始 ​

贡献者

页面历史

Neo-MoFox Windows 部署指南

概述

第一章：准备工作

1.1 系统要求

1.2 软件三件套：Python、Git 与 uv

1.2.1 Python (版本 >= 3.11)

1.2.2 Git

1.2.3 uv (推荐的 Python 包管理器)

1.3 Napcat QQ 客户端

第二章：获取核心 — 克隆项目

2.1 创建'机器人的家' (图形化操作)

2.2 下载项目代码

第三章：安装依赖

第四章：首次启动——生成配置文件

4.1 生成插件配置文件

第五章：核心配置——让机器人"认识"你

5.1 `core.toml`：机器人的“身份”

5.2 `model.toml`：机器人的“大脑”

第六章：连接世界 — OneBot 适配器配置

6.1 启用并配置插件

6.2 配置连接参数

第七章：正式启动

7.1 启动顺序

7.2 观察日志，判断成功

7.3 测试机器人

第八章：故障排除

结语：你的冒险才刚刚开始