Neo-MoFox

Appearance

Neo-MoFox Linux 部署指南 ​

概述 ​

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

本指南将引导您在 Linux 环境下，使用项目OneBot 适配器插件完成 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 --break-system-packages
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

  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 克隆项目 ​

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

  • 在终端中，粘贴并执行以下命令：
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 的新文件夹。恭喜，你已经成功获取了项目代码！

第三章：安装依赖 ​

shell
cd Neo-MoFox
uv sync

uv sync 会自动创建虚拟环境并安装所有依赖。

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

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

4.1 生成配置文件 ​

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

  1. 首次启动:

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

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

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

6.1 启用并配置插件 ​

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

  1. 找到配置文件:

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

  2. 启用插件:

    • 在打开的 config.toml 文件中，找到 [plugin] 配置节，确认 enabled 为 true（默认已开启）。
      toml
      [plugin]
# 是否启用 Napcat 适配器
# 值类型：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 客户端

    • 步骤二：填写反向 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 | ✅ 插件 '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 的“神经连接”已打通。

恭喜你，部署成功！

第八章：故障排除 ​

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

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

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

  1. 检查 Napcat QQ: 确保 Napcat QQ 客户端本身已成功登录并处于在线状态。
  2. 检查端口号: 这是最常见的原因。请再次核对 config/plugins/onebot_adapter/config.toml 文件中 [onebot_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/onebot_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 micraft1024a micraft1024a
The avatar of contributor named as Windpicker-owo Windpicker-owo
The avatar of contributor named as ikun-1145141 ikun-1145141
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