Skip to content

新手名词小课堂 ​

欢迎来到小课堂!这一页是整个文档站的术语字典:把你会遇到的「奇怪黑话」一次讲明白。

每个词条只有几句话:先说这东西是什么,再打个生活比方,最后告诉你在 Neo-MoFox 里长什么样、你会在哪碰到它。

怎么用这一页

不用背,也不用一口气读完。建议先通读一遍混个脸熟,之后读文档遇到不懂的词,再回来查就行。还没看过 Neo-MoFox 是什么?先去 「Neo-MoFox 是什么」 看看。

目录(点词条直达)

基础中的基础:Python · 终端与命令行 · 目录与路径

设置相关:配置文件 · TOML · 依赖 · 包管理器 uv · 环境变量

联网与钥匙:API Key · 端口 · 反向 WebSocket

Neo-MoFox 角色:协议端 · 适配器 · 插件 · WebUI

版本与容器:分支(main 与 dev) · Docker 与镜像

Python ​

一门编程语言——Neo-MoFox 这个程序,整个就是用它写出来的。就像一栋楼是用砖头砌的,Neo-MoFox 是用 Python「砌」的。你不需要会写它,就像住楼不需要会砌砖。你唯一可能碰到它的场合,是教程让你安装「Python 3.11 或更高版本」——而且如果用启动器或 Docker 部署,这一步会自动完成。

终端与命令行 ​

一个能打字给电脑下指令的小窗口:你输入一行命令,按回车,电脑照做。平时用鼠标点点点像「在餐厅点菜」,命令行则是直接进后厨跟师傅说「来一份红烧肉」——更直接,也更高效。Windows 上它叫 PowerShell(点开始菜单,搜「PowerShell」或「终端」);macOS 上叫终端(在启动台或「应用程序 → 实用工具」里);Linux 上一般按 Ctrl + Alt + T 就能打开。文档里标注 bash 的命令块给 macOS / Linux 用,标注 powershell 的给 Windows 用。

目录与路径 ​

目录就是文件夹,路径就是文件在电脑里的「住址」。比如 config/core.toml 读作:「当前文件夹里,config 文件夹下,名叫 core.toml 的文件」——就像「幸福小区 3 号楼 502 室」。在 Neo-MoFox 里,装好后你会看到几个固定文件夹:

text

Neo-MoFox/
├── config/    ← 设置单都在这(见「配置文件」词条)
├── plugins/   ← 插件的家
├── data/      ← 机器人的记忆、数据库
└── logs/      ← 运行日志,出问题排查时主要看这里

平时你打交道最多的是 config/ 和 plugins/ 这两个。

配置文件 ​

记录各种设置的文本文件,相当于机器人的「设置单」——用记事本就能打开改,改哪行、行为就变哪样。在 Neo-MoFox 里,它们都住在 config/ 目录:core.toml 是主配置(性格、行为开关都在这);model.toml 是模型配置(用哪家大模型、API Key 填这里);mcp.toml 管外部工具接入(见 MCP 指南);每个插件还有自己的小本本,放在 config/plugins/<插件名>/config.toml。好消息是:首次启动时会自动生成,你不用从零手写。想改设置见 核心配置指南。

TOML ​

配置文件用的一种书写格式,规则简单到只有「名字 = 值」;文字类的值要包上双引号。在 Neo-MoFox 里,所有配置文件都以 .toml 结尾,改完保存、重启机器人就生效。具体怎么写(注释、节、列表、多行文本),见 TOML 与编辑器。

依赖 ​

程序运行时借用的「别人写好的现成零件」。你开餐馆不必自己种菜养牛——Neo-MoFox 也一样,它用到了几十个现成零件(网页服务、数据库支持等),安装时工具会自动帮你下载装好,插件需要的零件默认也会自动补齐。正常情况下你完全感觉不到它的存在,只在报错提到「缺依赖」时才需要关心(跟着 常见问题 处理即可)。

包管理器 uv ​

帮你自动下载、管理「依赖」的工具,作用类似手机上的应用商店——说一声要什么,它把零件配齐。在 Neo-MoFox 里,官方的启动命令 uv run main.py 就是它在干活:先把依赖备齐,再把机器人跑起来;插件装零件时默认也用它。想手动部署的见 命令行部署指南。

API Key ​

大模型服务商发给你的一串密码。机器人每次「思考」都要调用大模型,而大模型按用量收费——Key 就是记在你账上的会员卡号。就像一张充过值的公交卡:卡号加密码谁拿到谁就能刷你的钱。在 Neo-MoFox 里,它填在 config/model.toml 里,详见 模型配置指南。

Key 千万要保密

不要发到群里、不要发朋友圈截图、不要发给「帮你远程安装的网友」。Key 泄露 = 把钱包递给别人。

端口 ​

一台电脑上不同服务的「门牌号」(0 到 65535 之间的数字)。IP 地址像小区地址,端口是里面每户的门牌——同一栋楼里,网页服务住 8000,另一个服务可以住 8095。在 Neo-MoFox 里你会常见到:8000(网页后台和接口用)、8095(反向 WebSocket,协议端来连接时用);用 Docker 方案时 SnowLuma 还会用到 3000、3001、5099、6081。个别带网页界面的插件也可能开自己的端口(比如 8005),具体以该插件的说明为准。

教程里说「端口被占用」,意思就是这个门牌被别人先挂走了。

反向 WebSocket ​

两个程序之间通话的一种线路。「反向」指的是方向反过来:由协议端主动来连 Neo-MoFox,而不是 Neo-MoFox 出去找协议端。打个比方:正向是你出门找店家办事;反向是店家直接把分店开到你家楼下,你不用动。在 Neo-MoFox 里这是默认方式——适配器守在 8095 端口「等电话」,你只需在协议端(比如 SnowLuma)的设置里填上机器人的地址(本机是 ws://127.0.0.1:8095,Docker 方案是 ws://mofox-bot:8095,以对应教程给的为准)。

协议端 ​

替机器人登录 QQ、收发消息的工具。QQ 官方没有给聊天机器人开正式入口,所以需要这么一个「代为进出」的角色。打个比方:机器人不自己拿手机,雇了个 24 小时盯着手机的秘书——消息来了递进来,要回复的发出去。在 Neo-MoFox 体系里,常用的协议端是 SnowLuma 和 NapCat,它们都遵循 OneBot v11 这个「通用插座标准」,所以核心自带的适配器能即插即用;Docker 方案里,协议端和机器人本体会作为两个搭档一起启动。

适配器 ​

QQ 世界和机器人大脑之间的翻译官。两边的「话」格式不一样:QQ 那边说的是自己的方言,核心只听得懂自己的普通话,适配器负责双向同声传译。在 Neo-MoFox 里,QQ 的适配器叫 onebot_adapter,是随框架自带的一个插件,在 plugins/ 目录里能找到它。除了翻译,它还顺手管几件小事:群聊/私聊的黑白名单、回复时自动 @ 人、处理「戳一戳」等。

插件 ​

可以自由装卸的功能扩展包。机器人出厂只带基本能力,装一个插件就等于给它加一个新器官——像给手机装 App。在 Neo-MoFox 里,插件都放在 plugins/ 文件夹里;框架把功能拆成 11 种「组件」,比如动作(action)、工具(tool)、指令(command)、适配器(adapter)等,一个插件可以同时包含好几种。框架自带插件市场,社区插件像逛商店一样挑挑点点就能装;下载来的插件包后缀是 .mfp,放进 plugins/ 目录即可使用。详见 插件入门 和 内置插件一览。

WebUI ​

网页版的管理后台:在浏览器里点按钮、填表格就能改设置,不用手动碰配置文件。打个比方:配置文件是后台机房里的配电箱,WebUI 就是前台那块触屏。在 Neo-MoFox 里要注意:框架本体不带网页后台,官方 WebUI(MoFox-Core-Webui)是独立项目,需要单独安装;装好后它通过 8000 端口跟核心沟通——所以如果在核心配置里把 HTTP 路由关了,WebUI 就连不上了。详见 WebUI 指南。

环境变量 ​

提前塞给程序的「便签设置」——不用改配置文件,就能传过去的临时开关或参数。像出门前在门口贴张便签「记得带伞」:程序一睁眼先看便签再干活。在 Neo-MoFox 里最常见于 Docker 方案:MOFOX_ACCEPT_STARTUP_AGREEMENTS=1 相当于提前替机器人勾好「我已阅读并同意用户协议」;SnowLuma 容器则需要你设置 SNOWLUMA_VNC_PASSWORD,作为远程桌面(noVNC)的访问密码。这些便签通常写在 docker-compose.yml 里,部署教程会让你原样照抄,照做即可。

不用 Docker、在终端里临时设置一个长这样(Windows 用 PowerShell):

powershell

$env:MOFOX_ACCEPT_STARTUP_AGREEMENTS = "1"

macOS / Linux 用 bash:

bash

export MOFOX_ACCEPT_STARTUP_AGREEMENTS=1

设置完再启动程序,它就能看到这张「便签」了。

分支(main 与 dev) ​

同一个软件的两条「产品线」:main 是稳定版,功能成熟、优先求稳;dev 是开发版,新功能最先出现,但可能带着没修完的小毛病。就像游戏的正式服和体验服。在 Neo-MoFox 里,下载源码或选 Docker 镜像时会遇到这个选择——新手闭眼选 main;想尝鲜、愿意帮忙测 bug 再考虑 dev。更新与切换见 更新指南。

Docker 与镜像 ​

Docker 是一种把「软件 + 它需要的整套环境」打包在一起运行的技术;镜像(image)是打包好的成品,运行起来的那份叫容器。打个比方:镜像像一整套带家具的精装样板间图纸,容器是照着盖好的房子——不管你家的「地基」(电脑系统)是什么样,住进去都一个样。在 Neo-MoFox 里,官方提供 docker-compose.yml,一条命令同时拉起两个容器:SnowLuma(协议端)和 Neo-MoFox 本体——不用自己装 Python 和一堆依赖,是环境问题最少的一种装法。见 Docker 部署指南。

Bot ​

就是「机器人」的简称——你要养的那只 AI 小狐狸本狐。注意区分:Bot 指运行中的机器人程序整体,而下面词条里的实例,是你同时养好几只 Bot 时的「每一只」。

LLM ​

Large Language Model,大语言模型,就是驱动 Bot 思考的「云端大脑」。Bot 自己不会思考,它把你说的内容发给 LLM 服务商,拿回回复再发给你——所以在 model.toml 里填的 API Key,就是使用这个大脑的「电费卡」。

实例 ​

一只独立运行的 Bot,包括它的程序、配置、数据和 QQ 账号。启动器、安卓 App 里可以同时管理多个实例——就像一个鱼缸里养多条鱼,每条有自己的名字和性格,互不干扰。新手一般一个实例就够了。

NapCat ​

目前最流行的 QQ 协议端之一,基于 QQ 官方客户端改造,让机器人能收发 QQ 消息。它本身不是 Neo-MoFox 的一部分,需要单独安装,然后通过反向 WebSocket 和 Neo-MoFox「握手」。NapCat 与 SnowLuma 的仓库均已归档,启动器不再提供一键下载,协议端需要自己找来源准备。见 启动器部署指南 与 QQ 登录步骤。

SnowLuma ​

另一个 QQ 协议端,自带网页管理界面(浏览器打开 5099 端口即可操作),Docker 部署方式里打包的协议端就是它。角色和 NapCat 一样:替机器人进出 QQ。该项目的 GitHub 仓库已归档,Docker 镜像仍可用,但桌面端需要自己寻找安装包,再在启动器的「修改实例信息」里指定平台路径。

OneBot ​

协议端和机器人主体之间「说话」的标准规范(常用的是 OneBot 11 版本)。有了统一标准,NapCat、SnowLuma 这些不同的协议端,都能通过 Neo-MoFox 内置的 onebot_adapter 适配器接上来——就像所有手机都用同一个 USB-C 口充电。

MCP ​

Model Context Protocol,模型上下文协议——给 AI 接外部工具的「万能插座」。插上文件管理、网页抓取等 MCP 服务后,Bot 就多了对应的能力。配置写在 config/mcp.toml,详见 MCP 接入指南。

Tool ​

工具:Bot 能执行的一个个具体动作,比如「搜网页」「读文件」。插件和 MCP 服务都会给 Bot 添加工具,工具多了 Bot 本事就大。

VLM ​

Vision Language Model,视觉语言模型——「长眼睛」的大模型,能看懂图片。Neo-MoFox 用它来识别你发的表情包和图片(model.toml 里的 vlm 任务)。

Embedding ​

把一段文字变成一串数字(向量)的技术,数字越相近代表意思越相近。Neo-MoFox 靠它在庞大的记忆库里快速找到「和你现在说的话最相关的回忆」(model.toml 里的 embedding 任务)。

Token ​

大模型计费和处理文本的最小单位,约等于半个到一个汉字(英文约四分之三个单词)。你的 API Key 账单上按 Token 数量扣费;WebUI 的「LLM 指标」页能看到消耗统计。

热重载 ​

不重启程序、直接读取并应用新配置的能力。WebUI 保存大多数配置后会自动热重载;但少数「底层」配置(比如端口号)依然需要重启才生效。

EULA ​

End User License Agreement,最终用户许可协议——首次启动时让你点「同意」的那份合同,说明了使用本软件的权利和义务。全文见本站的协议页面。

APK ​

Android Package,安卓安装包,后缀 .apk。相当于 Windows 上的 .exe——下载后点开安装即可(手机会提示「允许安装未知来源应用」)。

rootfs 与 proot ​

rootfs 指一套完整的 Linux 系统文件(安卓 App 里内置的是 Debian 13);proot 是一种不用 root 权限就能运行这套系统的技术。两者合起来,让 Neo-MoFox 安卓 App 不依赖 Termux、不要求刷机,手机上直接跑起完整版 Bot。

看完了吗?其实你已经赢过大多数人了

一个词都不用背——忘了就回来查,这一页就是干这个用的。心里有底了,就去 挑一种安装方式,开始打造属于你的那只小狐狸吧。

贡献者

The avatar of contributor named as minecraft1024a minecraft1024a
The avatar of contributor named as ikun-1145141 ikun-1145141

页面历史

Released under the GPL-3.0 License.