Neo-MoFox 是什么?
Neo-MoFox 是一个开源的 AI 聊天机器人框架。 你把它装在电脑、服务器或兼容的安卓设备上,接入 QQ,再配置大模型服务,就能拥有一个按你设定的性格与大家聊天的 Bot。
「框架」可以理解为一套搭建机器人的工具:它负责接收消息、管理人设和记忆、调用模型与插件,再把回复送回聊天平台。你平时做的是安装、填写设置和管理它;日常使用不要求你会写代码。

装好之后,能用它做什么
| 你想做的事 | 对应能力 | 接下来读哪里 |
|---|---|---|
| 让它用自己的名字、性格和语气聊天 | 人格设定:写清角色背景、说话习惯和与你的关系 | 人设指南 |
| 在后续对话里参考之前的重要信息 | 记忆插件:保存、检索记忆和短期便签,需要配置相应模型任务 | 内置插件说明 |
| 识别图片或语音消息 | 分别使用看图模型和语音识别模型 | 进阶模型配置 |
| 发表情包、解析链接或添加其他功能 | 内置插件与社区插件;不同插件有各自的安装条件 | 插件入门 |
| 用浏览器管理设置、插件与日志 | 单独安装 WebUI 管理面板 | WebUI 安装与使用 |
这些能力需要对应的配置、模型或插件。建议先让 Bot 能收发普通文字,再逐项开启你需要的功能,排查问题也更容易。
装好接入 QQ 之后,大概就是这样的效果:Bot 按设定的人设用口语聊天,气氛到了还会发自己的表情包。

一条消息是怎么变成回复的
QQ 接入通常由下面几部分配合完成:协议端接收消息,适配器转换消息格式,核心组织模型请求,再把生成的回复送回 QQ。
| 名称 | 负责什么 | 你会在哪里遇到它 |
|---|---|---|
| 你和 Bot 实际聊天的地方 | 好友私聊或群聊 | |
| 协议端,如 SnowLuma、NapCat | 登录机器人的 QQ 号,收发 QQ 消息 | 部署教程的 QQ 登录、连接设置步骤 |
适配器,如 onebot_adapter | 在协议端与 Neo-MoFox 之间转换消息格式 | 适配器配置、WebSocket 地址与端口 |
| Neo-MoFox 核心 | 结合人设、消息上下文、记忆与工具组织对话 | 主程序、配置文件与插件 |
| 大模型 API | 根据请求生成回复,或完成看图、语音识别等任务 | 模型服务商、API Key 与模型配置 |
例如,你在 QQ 里发来一条消息:协议端收到后交给适配器,核心按当前配置组织请求,大模型返回结果,核心再经适配器和协议端把回复发出来。
所以「程序启动了」「QQ 登录了」「模型连接成功了」是三件不同的事。 第一次部署时,教程会分别带你检查它们;某一步成功,不代表其余步骤已经完成。
开始前准备这几样
| 要准备的东西 | 用途与检查方式 |
|---|---|
| 一台能运行 Bot 的设备 | 电脑、Linux 服务器或符合要求的安卓设备。设备关闭或休眠时,Bot 也无法保持在线;先按 部署选择 核对平台要求 |
| 机器人的 QQ 号 | 用它登录协议端。建议使用专门的小号 |
| 你自己的 QQ 号 | 设置为主人账号,用来执行管理操作;不要与机器人的号码混填 |
| 大模型服务的 API Key | 让 Bot 能调用模型。还要确认模型可用、账户有额度;密钥不要发到群里或贴到公开截图中 |
| 能访问下载站与模型服务的网络 | 安装时要下载程序和依赖,运行时要访问模型服务 |
QQ 接入提醒
QQ 接入使用第三方协议端,可能受到平台风控影响。请使用专门的机器人账号,并遵守平台规则。
框架本身开源免费。大模型服务通常按用量收费,服务器等设备也可能有费用,具体取决于你的选择。刚开始可以先小范围测试,再决定让它在哪些群里运行。
先跑起来,再慢慢调整
第一次部署的目标很简单:用你的主人账号给 Bot 发一条消息,并收到正常回复。 达成这个目标之后,再写人设、装插件和调整模型。
- 选路线:去 部署方式怎么选,按手上的设备和操作习惯选一种。
- 跟完一篇部署教程:安装、填模型配置、设主人、接入 QQ,按顺序完成;不用同时照抄几种部署方式。
- 验证能聊天:确认主程序正常、QQ 在线、模型请求成功,再开始调整功能。
- 按需要往下读:人设指南、插件入门、备份与日志。
遇到问题时,先从哪里查?
先看部署教程最后的排查部分,再去 常见问题 FAQ 对照现象。提问时带上使用的部署方式、卡住的步骤、相关报错与已经尝试过的操作,能更快定位问题。
如果发现的是文档错误或过时步骤,在对应页面点击顶栏的虫子图标报告问题,页面信息会自动附上。
