Neo-MoFox

Appearance

Neo-MoFox Linux 部署指南 (内置适配器版) ​

概述 ​

欢迎使用 Neo-MoFox，一个高度可定制化的 AI Bot 框架。

本指南将引导您在 Linux 环境下，使用项目内置的 Napcat 适配器插件完成 Neo-MoFox 的全部署流程。该方式是官方推荐的最佳实践，具有以下优势：

  • 部署简化：仅需下载和运行 Neo-MoFox / Napcat 项目。
  • 操作便捷：只需管理 Neo-MoFox / Napcat 进程。

本教程将覆盖从环境准备到成功运行的每一个步骤，旨在为初学者提供一条清晰、高效的部署路径。

第一章：准备工作——万丈高楼平地起 ​

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

1.1 系统要求 ​

  • 操作系统: 任何主流的 Linux 发行版 (如 Ubuntu, Debian, CentOS)

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

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

1.2.1 Python (版本 >= 3.11) ​

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

  1. 安装:
    • 打开终端，根据你的 Linux 发行版，使用包管理器安装 Python 3.10 或更高版本。
bash
sudo apt update
sudo apt install python3 python3-pip python3-venv
bash
sudo dnf install python3 python3-pip
  1. 验证:
    • 在终端中输入以下命令并回车：
      bash
      python3 --version
    • 如果屏幕上显示出 Python 版本号（如 Python 3.10.6），则证明安装成功。

1.2.2 Git ​

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

  1. 安装:
bash
sudo apt install git
bash
sudo dnf install git
  1. 验证:
    • 在终端中输入以下命令并回车：
      bash
      git --version
    • 如果显示出 Git 的版本号（如 git version 2.34.1），则证明安装成功。

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

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

  1. 安装:

    • 在终端中，输入以下命令并回车：
      bash
      pip3 install uv

  2. 验证:

    • 输入以下命令并回车：
      bash
      uv --version
    • 如果显示出 uv 的版本号，则证明安装成功。

1.3 Napcat QQ 客户端 ​

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

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

第二章：获取核心——请君入瓮 ​

万事俱备，现在我们正式开始请"君"入瓮——将 Neo-MoFox 的核心代码下载到你的电脑中。

2.1 创建你的“机器人基地” ​

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

  1. 打开终端。
  2. 创建并进入文件夹：执行以下命令，这会在你的用户主目录下创建一个名为 Neo-MoFox_Deployment 的文件夹，并进入该目录。
    bash
    cd ~
mkdir Neo-MoFox_Deployment
cd Neo-MoFox_Deployment

⚠️ 重要提示: 为了避免未来可能出现的奇怪问题，请确保文件夹的完整路径中不包含任何中文、空格或特殊字符。

2.2 git clone 神威 ​

现在，我们在这个“基地”里执行代码下载命令。

  • 在终端中，粘贴并执行以下命令：
bash
git clone -b dev --single-branch https://github.com/MoFox-Studio/Neo-MoFox.git
bash
git clone https://kgithub.com/MoFox-Studio/Neo-MoFox.git
bash
git clone https://xget.xi-xu.me/gh/MoFox-Studio/Neo-MoFox.git

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

执行命令后，Git 会开始下载项目文件。当克隆完成后，你的 Neo-MoFox_Deployment 文件夹里会多出一个名为 Neo-MoFox 的新文件夹。恭喜，你已经成功获取了项目代码！

第三章：激活环境——注入灵魂 ​

我们已经有了项目代码，现在需要为它创建一个纯净的生存空间，并注入"灵魂"——安装所有必需的依赖库。

3.1 虚拟环境：干净又卫生 ​

在安装依赖库之前，我们要先创建一个"虚拟环境"。

你可以把它想象成一个专属环境。我们为 Neo-MoFox 项目创建一个独立的、与外界隔离的环境，所有它需要的依赖库都放在这个环境里。这样做的好处是：

  • 避免冲突：不会和你电脑上安装的其他 Python 程序产生冲突。
  • 保持纯净：保证了项目环境的干净和稳定。

3.2 环境的创建和激活 ​

接下来，我们将使用 uv 这个神器来完成环境的创建和激活。

  1. 进入项目目录:

    • 首先，确保你的终端路径在 Neo-MoFox_Deployment 文件夹下。
    • 我们需要进入刚刚克隆下来的 Neo-MoFox 文件夹。执行以下命令：
      bash
      cd Neo-MoFox

  2. 创建虚拟环境:

    • 执行以下命令来创建环境：
      bash
      uv venv
    • 命令执行后，你会发现 Neo-MoFox 文件夹里多出了一个名为 .venv 的新文件夹。这就是Neo-MoFox的"专属环境"。

  3. 激活虚拟环境 (核心步骤):

    • 光有工具箱还不行，我们得把它“打开”，这个动作就叫做“激活”。
    • 执行以下命令来激活环境：
      bash
      source .venv/bin/activate
    • 观察变化！ 成功激活后，你会看到命令行提示符的最前面，多出了一个 (.venv) 的标记。这表示你已经成功进入了 Neo-MoFox 的专属环境。

    TIP

    💡 小贴士: 在后续使用 Neo-MoFox 的过程中，当你安装插件后，如果这些插件需要额外安装 Python 依赖，也必须先激活本章节中创建的虚拟环境，然后在该虚拟环境中执行这些安装命令。

3.3 依赖安装 ​

环境激活好了，现在我们可以开始安装 Neo-MoFox 所需的所有依赖库了。

  • 在已激活虚拟环境的命令行窗口中，执行以下命令：

    bash
    uv sync

  • 命令解析:

    • uv sync: 使用 uv 来将虚拟环境与项目的依赖同步。它会自动读取 pyproject.toml 文件，安装上面列出的所有依赖。

命令执行后，你会看到屏幕上开始飞速滚动各种下载和安装信息。请耐心等待，直到它全部完成，并重新出现可以输入命令的提示符。

💡 依赖安装失败怎么办？ 如果安装过程中出现大量红色错误，不要慌，通常是以下几个原因：

  1. 网络问题：检查你的网络连接。偶尔网络波动可能导致失败。可以尝试重新执行一遍安装命令。
  2. 权限不足：尝试使用 sudo 重新执行安装命令（如果需要的话）。

至此，机器人所需的一切软件依赖都已准备就绪，我们已经为它搭建了一个干净、独立的生存环境。接下来，我们将进入部署流程的下一阶段：首次启动和配置。

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

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

4.1 生成配置文件 ​

Neo-MoFox 拥有强大的配置管理系统。在我们第一次启动程序时，它会创建默认的配置文件以供我们修改。

  1. 首次启动:

    • 确保你的命令行终端已激活虚拟环境 (前面带有 (.venv) 标记)。
    • 确保你当前的目录是 Neo-MoFox 文件夹。
    • 执行以下命令，来启动一次 Neo-MoFox：
      bash
      uv run main.py
    • 程序启动后，你会看到大量的日志信息在屏幕上滚动。当日志滚动停止，并且没有新的信息出现时，说明程序已经完成了初始化工作，并且生成了所有的配置文件。

  2. 生成配置并关闭:

    • 当你看到 config 文件夹被创建，这次启动的主要目的——生成配置文件——就已经达成了。如果程序还在运行，请在命令行窗口中，按下 Ctrl + C 来关闭程序。程序会进行"优雅关闭"，请稍等片刻直至其完全退出。

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

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

🔧 编辑器推荐: 为了避免不必要的格式或编码错误，强烈建议使用专业的代码编辑器来修改配置文件，例如 带有even better toml 插件的 Visual Studio Code、nano 或 vim。请不要使用可能导致格式问题的简单文本编辑器。

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

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

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

  1. 修改内容 (至少修改以下一项):
    • 用编辑器打开 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），是机器人能否思考和回答问题的关键。

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

第六章：连接世界——内置适配器插件配置 ​

现在，机器人的“身份”和“大脑”都有了，但我们还需要让它能够连接到 QQ 平台，让它能够接收和发送消息，我们通过配置官方内置的 Napcat 适配器插件来完成。

6.1 启用并配置插件 ​

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

  1. 找到配置文件:

    • 现在，请打开 Neo-MoFox/config/plugins/ 文件夹。你会发现里面出现了很多以插件名命名的文件夹。
    • 这说明 Neo-MoFox 的所有内置插件的配置文件都在这里生成了，方便你未来探索和开启更多功能。
    • 我们当前的目标是找到 napcat_adapter 文件夹，进入后用你的代码编辑器打开 config.toml 文件。

  2. 启用插件:

    • 在打开的 config.toml 文件中，找到 [plugin] 配置节，将 enabled 的值从 false 修改为 true。这是启动适配器的总开关。
      toml
      [plugin]
# 是否启用 Napcat 适配器
# 值类型：bool, 默认值：true
enabled = true # < 修改这里

6.2 配置连接参数 ​

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

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

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

# Napcat WebSocket 服务端口
# 值类型：int, 默认值：8095
port = 8095
```
    • 请记下这个 port 值 (默认为 8095)。除非 8095 端口已被其他程序占用，否则我们推荐保持默认设置。如果需要修改，请确保选择一个未被占用的端口。

  • 第二部分：配置 Napcat 客户端连接地址

    • 现在，回到 Napcat QQ 客户端，我们将告诉它去连接 Neo-MoFox 正在监听的端口。

    • 步骤一：新建 Websocket 客户端

      • 在 Napcat 客户端中，点击左侧菜单的"网络配置"。
      • 在右侧选择 Websocket客户端 标签页，然后点击"新建"按钮。

      点击新建 Websocket 客户端

    • 步骤二：填写反向 WebSocket 地址

      • 在弹出的配置窗口中，将 URL 填写为 ws://127.0.0.1:8095。
      • 核心要点：此处的端口号 (8095) 必须与你在第一部分中 Neo-MoFox 配置文件里看到的 port 值完全一致。如果两边不一致，通信将百分之百失败。
      • 填写完毕后，点击"保存"。

      配置反向 WebSocket

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

第七章：正式启动！——见证奇迹的时刻 ​

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

7.1 启动顺序 ​

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

  1. 第一步：启动并登录 Napcat QQ

    • 打开你已经安装好的 Napcat QQ 客户端。
    • 确保你的机器人 QQ 账号已经成功登录，并且客户端处于正常运行状态。

  2. 第二步：运行 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 | ✅ 插件 'napcat_adapter' 的组件注册完成
[14:29:12] plugin_manager | INFO | ✅ 插件加载成功: napcat_adapter v2.0.0
  ✓ 已加载插件: napcat_adapter (#2)
[14:29:13] adapter_manager | INFO | 适配器启动成功: napcat_adapter:adapter:napcat_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 | 插件 napcat_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] [Napcat 适配器] Napcat 客户端已连接: ('127.0.0.1', 38207)
[19:58:46] [Napcat 适配器] Bot xxxxxxx(botQQ号) 连接成功

💡 日志解读:

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

恭喜你，部署成功！

第八章：故障排除 ​

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

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

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

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

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

  1. 检查 Napcat QQ: 确保 Napcat QQ 客户端本身已成功登录并处于在线状态。
  2. 检查模型配置: 确认 config/model.toml 里的 API Key 是有效且可用的。可以检查一下你的模型服务商后台，看看 Key 是否填错、账户是否欠费。
  3. 检查白名单: 检查 config/plugins/napcat_adapter/config.toml 文件中 [features] 部分的 group_list 和 private_list。如果你开启了白名单，请确保你测试的群聊或私聊已经被加了进去。
  4. 查看日志: 观察机器人后台的命令行窗口。当你给机器人发消息时，看看日志是否刷新。如果有 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 或社区与其他开发者交流。

现在，去和你的新伙伴聊天吧！祝你玩得开心！

贡献者

The avatar of contributor named as minecraft1024a minecraft1024a
The avatar of contributor named as ikun-11451 ikun-11451
The avatar of contributor named as Pomelo32141 Pomelo32141
The avatar of contributor named as qwertazsxd qwertazsxd
The avatar of contributor named as xiaoxi68 xiaoxi68
The avatar of contributor named as subiz subiz

页面历史

Released under the GPL-3.0 License.

Copyright © 2025 MoFox Studio

新对话
MoFox 助手

下午好。

今天想做点什么？

聊天内容可能会被记录以用于改进服务及其质量，并会遵循我们的隐私政策进行处理。