TOML 与编辑器
只用 WebUI?这页可以跳过
Neo-MoFox 的所有配置都能在 WebUI 的表单里点几下改好,不需要碰任何文件。这一页是「直接改配置文件」的地基——如果你是纯 WebUI 用户,可以放心跳过,等哪天想手动改文件了再回来看也不迟。
接下来的几篇——核心配置要点、人设指南、进阶模型配置、插件配置怎么改——都绕不开同一件事:和 .toml 配置文件打交道。这一页就把 TOML 怎么写一次讲清——从最基本的规则,到三引号多行字符串——最后再说说用什么软件改最省心。后面的配置教程不再重复解释语法,遇到看不懂的写法,直接跳回这一页就行。
TOML 是什么
TOML 是一种人和机器都容易读的配置文件格式,Neo-MoFox 的所有配置文件(都住在 config/ 目录)都用它。语法简单到看一个例子就能学会:
# 井号开头的是注释,写给人看的,Bot 不会执行
nickname = "小狐狸" # 一行一个设置:左边是名字,右边是值
[personality] # 方括号是「节」,把相关的设置归成组
personality_core = "温柔" # 从这行到下一个节出现为止,都属于这个节
[[api_providers]] # 双方括号表示「列表」,同样的段可以写好几份
name = "SiliconFlow"全部规则就这四条:
| 写法 | 名字 | 意思 |
|---|---|---|
名字 = 值 | 键值对 | 一行一项设置;文字类的值要用双引号包起来 |
# 注释 | 注释 | 给你自己看的备注,程序直接忽略 |
[节名] | 节 | 把一组相关设置归在一起,自动生成的配置文件已经分好组了 |
[[名字]] | 数组节 | 同一段配置可以重复写多次,比如同时接多家模型服务商 |
值不止文字一种
名字 = 值 右边的「值」,常见的是这几类:
| 类型 | 写法示例 | 配置里的常见用处 |
|---|---|---|
| 文字(字符串) | "小狐狸" | 昵称、提示词、路径,必须包双引号 |
| 整数 | 8095 | 端口、上限、数量 |
| 小数 | 0.5 | 概率、权重(如回复概率 reply_at_rate = 0.5) |
| 开关(布尔值) | true / false | enabled = false 关闭功能;只能全小写 |
| 列表(数组) | ["111111", "222222"] | 群白名单、用户名单、关键词 |
| 小组(内联表) | { enabled = true } | 偶尔见到,照葫芦画瓢改里面的值即可 |
几条容易翻车的细节:
true/false必须全小写,写成True会直接报错。- 名单类字段只有一项也要写成列表:
group_list = ["111111"];留空就写[]。 - 列表里的文字每一项各自带引号,项与项之间用英文逗号。
- 列表长了可以跨行写,还能顺便给每一项加注释:
[features]
group_list = [
"111111111", # 测试群
"222222222", # 主群
]节与数组节,展开说说
上面表格把 [节] 和 [[数组节]] 一笔带过,这里补充两个细节:
# config/plugins/onebot_adapter/config.toml(节选)
[bot] # 一行 [名字] 开启一个节,下面的行都归它
qq_id = "123456789"
qq_nickname = "小狐狸"
[onebot_server] # 新节开始:从这里往下,直到再出现 [ 为止
port = 8095- 节能一层套一层:
[server.limits]表示limits是server的子分组,读作「server 里的 limits」。 [[名字]](双方括号)是数组节:同一段配置要写好几份时用——比如model.toml里同时接多家模型服务商,每个[[api_providers]]就是一家:
[[api_providers]]
name = "SiliconFlow"
base_url = "https://api.siliconflow.cn/v1"
api_key = "your-siliconflow-api-key-here"
[[api_providers]]
name = "另一家服务商"
base_url = "https://它的接口地址/v1"
api_key = "它的密钥"自动生成的配置文件已经把节排好版,通常你只需要在现有节里改值,不用自己新建节。
多行文本:三引号字符串
普通字符串有条铁律:一行一个值,中间不能换行。可提示词、使用说明这类内容天生就是好几行——人设里的大段性格描写就是典型。这时候用三引号 """ 把整段文字包起来:
[plugin]
welcome = "欢迎进群!" # 单行文本:老老实实一行写完
usage_notice = """ # 多行文本:三引号开头,随后换行
使用说明:
1. 发 /帮助 看看我都能干什么
2. 直接 @ 我就能聊天
""" # 三个引号收尾,习惯上单独占一行三引号里有三条和直觉不太一样的规则,记住就不会踩坑:
- 开头
"""后面的那个换行不算内容——所以正文从下一行开始写,开头不会多出空行。 - 中间想写什么写什么:换行原样保留;
#在这里就是普通文字、不再是注释;双引号"直接写、不用加反斜杠(只要别一口气连出三个)。 - 收尾
"""之前的最后一个换行算内容——上面例子的值结尾其实带着一个换行,正常现象,不用纠结。
最常见的翻车:忘了收尾
只写了开头的 """ 没写收尾,后面整个文件都会被当成这段文字,报错行号会飘到离谱的地方。看到「莫名其妙的行报错」,先回头检查最近的多行文本有没有闭合;反过来,也别在正文中间随手插一行 """——那就等于提前收尾了。
不想被「转义」搅和?
在 """ 里写 \n 会被解释成换行、写 \\ 才是一个真的反斜杠——这个机制叫转义。如果填的内容里有真实反斜杠(比如 Windows 路径 C:\Users\xxx),想原样保留就改用三个单引号 ''':里面的所有字符原封不动,\n 就是字面上的「反斜杠加 n」:
[plugin]
path_note = '''
路径示例:C:\Users\你的用户名\Documents
第二行的 \n 不会变成换行,原样保留
'''「开头换行不算、结尾换行算」这两条规则,三单引号和三双引号完全一样。这套写法不稀奇:人设指南里的 personality_core 等字段,全都是三引号字符串。
新手最容易踩的三个坑
- 文字忘了加引号:
nickname = 小狐狸会报错,要写nickname = "小狐狸"。 - 同一个名字写了两遍:TOML 不允许重复——同一个节里写两个相同字段、或同一个节名声明两次,启动时会直接报错。另一种「明明改了却没生效」则是改错了文件或改错了节——改之前先确认位置没找错。
- 动了标点:
"、[、]、[[这些符号都是格式的一部分,别随手删;只有注释里明确说「删掉这行」的才整行删。
改错了也不用慌:最坏的情况就是启动报错。报错大多是英文,看不懂很正常——把报错信息和对应的配置文件一起扔给 AI(任意 AI 助手都行),让它告诉你哪里写错了、该怎么改,这一招对新手非常好使。
用什么编辑器改
配置文件本质上是文本文件,用记事本也能打开改——但记事本不认识 TOML:没有颜色区分、写错了也不提醒,还容易把文件编码存错(中文一变乱码,配置就废了)。所以记事本只建议应急用,日常改配置推荐 VS Code:免费、全平台,装一个插件后能高亮 TOML、自动标出写错的地方。
- 到 code.visualstudio.com 下载安装。
- 点左侧「扩展」图标,搜索 Even Better TOML,点安装。
- 用它打开
config/里的任意配置文件:节和值按颜色区分,语法错误会画红色波浪线,鼠标悬停在字段上还能看到提示——对新手非常友好。
改完先别急着重启:多看看下面的问题
VS Code 窗口左下角有「⊗」和「⚠」两个小图标,点开(或按 Ctrl+Shift+M,菜单里叫「查看 → 问题」)就是底部的问题面板。写错的地方都会列在这里,点一条就能直接跳到出问题的那一行。把这里列出的问题清干净了,再去重启 Bot——很多报错根本走不到启动那一步,编辑器就已经帮你拦下来了。
编辑器不影响配置内容
编辑器只决定你「看得清不清楚、有没有纠错提醒」,配置文件本身怎么写、怎么生效不受影响。已经用惯了别的编辑器的话,继续用也没问题。
