OneBot v11 内置适配器配置指南

概述

欢迎使用 MoFox_Bot 内置的 OneBot v11 (Napcat) 适配器。

将适配器“内置”于主程序中，是官方最为推荐的最佳实践。它就像是为机器人配备了一个“官方翻译耳机”，无需任何外部转接，直接就能与 Napcat QQ 客户端进行稳定、高效的沟通。

使用内置适配器的优势:

部署简化：仅需下载和运行 MoFox_Bot 主项目。
操作便捷：只需管理单个进程。
配置统一：所有相关设置均在主项目的配置文件中完成。

本指南将专注于指导你如何配置并启用这个强大的内置连接器。

前置条件

在开始本章之前，我们假定你已经基本完成了 MoFox_Bot 的主程序部署，至少包括：

成功安装了 Python 环境和项目依赖 (requirements.txt)。
完成了 .env, bot_config.toml, model_config.toml 三个核心文件的基础配置。
已经安装并成功登录了 Napcat QQ 客户端。

如果你对上述步骤还不熟悉，请务必先返回，并严格参照主部署指南完成准备工作。

第一步：生成插件配置文件

MoFox_Bot 设计得非常“聪明”，它会在第一次启动时，自动检测所有内置的插件，并为它们创建默认的配置文件。

首次启动:
- 打开你的命令行终端，并激活 Python 虚拟环境 (你应该能看到 (.venv) 这样的标记)。
- 确保你当前的目录位于 MoFox_Bot 项目的根目录。
- 执行以下命令，来启动一次 MoFox_Bot：
  bash
```
uv run python bot.py
```
- 程序启动后，你会看到大量的日志信息。当日志滚动停止，并且没有新的信息出现时，说明程序已经完成了初始化工作。
💡 第一次启动就失败了怎么办？ 如果程序在启动过程中直接报错并退出了，99% 的可能性是你的核心配置 (.env, bot_config.toml, model_config.toml) 有误。请回头仔细检查。
生成配置并关闭:
- 当程序稳定运行后，我们生成配置文件的目的就已经达成。现在，请在命令行窗口中，按下 Ctrl + C 来关闭程序。

第二步：启用并配置插件

经过上一步，所有内置插件的默认配置文件都已经被自动创建好了。现在，我们来正式配置它。

找到配置文件:
- 请打开以下路径的文件： config/plugins/napcat_adapter_plugin/config.toml
启用插件 (关键):
- 用你的代码编辑器打开该文件，找到 [plugin] 配置节，将 enabled 的值从 false 修改为 true。这是开启适配器的总开关。
  toml
```
[plugin]
enabled = true # <--- 就是这里，把它改成 true
```
配置 Napcat 连接 (核心):
- 在同一个文件中，向下找到 [napcat_server] 配置节。
- 这里的 port 值（默认为 8095）必须与你在 Napcat QQ 客户端的 OneBot v11 设置中，添加的反向 WebSocket 地址中的端口号完全一致。
- 请仔细核对，如果不一致，请修改此处的 port 值。
举个例子: 如果你在 Napcat 客户端中设置的反向 WS 地址是 ws://127.0.0.1:12345，那么这里的 port 就应该被修改为 12345。
检查内部服务连接:
- 继续向下，找到 [maibot_server] 配置节。
- 这里的 port 值（默认为 8000）需要与你在 MoFox_Bot 根目录下的 .env 文件中设置的 PORT 值保持一致。通常情况下，你不需要修改它。

第三步：启动与验证

所有配置都已完成，现在，让我们正式启动，见证奇迹。

启动顺序 (非常重要)
- 第一步：启动并登录 Napcat QQ
  - 打开你已经安装好的 Napcat QQ 客户端，并确保机器人 QQ 账号成功登录。
- 第二步：运行 MoFox_Bot
  - 回到你的命令行终端窗口（确保虚拟环境已激活，且位于项目根目录）。
  - 执行最终的启动命令：
    bash
```
uv run python bot.py
```

观察日志，判断成功

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

log

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
napcat_adapter - INFO - 正在启动 adapter，连接模式: reverse
napcat_adapter - INFO - WebSocket server is listening on localhost:8095
napcat_adapter - INFO - Napcat client connected from ...
napcat_adapter - INFO - MaiBot router连接已建立
main - INFO - MoFox_Bot 初始化完成

看到 Napcat client connected 是成功的关键标志！

测试机器人
- 现在，打开你的 QQ，向你的机器人账号发送一条消息。如果它回复了你，那么…… 恭喜你，配置成功！

故障排除

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

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

检查 Napcat QQ: 确保 Napcat QQ 客户端本身已成功登录并处于在线状态。
检查端口号: 这是最常见的原因。请再次核对 config/plugins/napcat_adapter_plugin/config.toml 文件中 [napcat_server] 下的 port 值，是否与你 Napcat QQ 客户端里设置的反向 WebSocket 端口完全一致。
检查防火墙: 确保防火墙或安全组没有阻止相应的端口。
检查 IP 地址: 确保 config.toml 中的 host (localhost) 和 Napcat 中的 IP (127.0.0.1) 是匹配的。

Q2: 机器人成功连接，但在 QQ 里不回复？

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

检查 Napcat QQ: 确保 Napcat QQ 客户端本身已成功登录并处于在线状态,以及有没有连接上内置的适配器。
检查白名单: 检查 config/plugins/napcat_adapter_plugin/config.toml 文件中 [features] 部分的 group_list 和 private_list。如果你开启了白名单，请确保你测试的群聊或私聊已经被加了进去。
查看日志: 观察机器人后台的命令行窗口。当你给机器人发消息时，看看日志是否刷新，是否有 ERROR 级别的红色错误信息。

贡献者

minecraft1024a

页面历史

最后编辑于 3 天前

查看完整历史

OneBot v11 内置适配器配置指南 ​

概述 ​

前置条件 ​

第一步：生成插件配置文件 ​

第二步：启用并配置插件 ​

第三步：启动与验证 ​

故障排除 ​

贡献者