Skip to content

TOML 与编辑器 ​

只用 WebUI?这页可以跳过

Neo-MoFox 的所有配置都能在 WebUI 的表单里点几下改好,不需要碰任何文件。这一页是「直接改配置文件」的地基——如果你是纯 WebUI 用户,可以放心跳过,等哪天想手动改文件了再回来看也不迟。

接下来的几篇——核心配置要点、人设指南、进阶模型配置、插件配置怎么改——都绕不开同一件事:和 .toml 配置文件打交道。这一页就把 TOML 怎么写一次讲清——从最基本的规则,到三引号多行字符串——最后再说说用什么软件改最省心。后面的配置教程不再重复解释语法,遇到看不懂的写法,直接跳回这一页就行。

TOML 是什么 ​

TOML 是一种人和机器都容易读的配置文件格式,Neo-MoFox 的所有配置文件(都住在 config/ 目录)都用它。语法简单到看一个例子就能学会:

toml
# 井号开头的是注释,写给人看的,Bot 不会执行

nickname = "小狐狸"            # 一行一个设置:左边是名字,右边是值

[personality]                  # 方括号是「节」,把相关的设置归成组
personality_core = "温柔"      # 从这行到下一个节出现为止,都属于这个节

[[api_providers]]              # 双方括号表示「列表」,同样的段可以写好几份
name = "SiliconFlow"

全部规则就这四条:

写法名字意思
名字 = 值键值对一行一项设置;文字类的值要用双引号包起来
# 注释注释给你自己看的备注,程序直接忽略
[节名]节把一组相关设置归在一起,自动生成的配置文件已经分好组了
[[名字]]数组节同一段配置可以重复写多次,比如同时接多家模型服务商

值不止文字一种 ​

名字 = 值 右边的「值」,常见的是这几类:

类型写法示例配置里的常见用处
文字(字符串)"小狐狸"昵称、提示词、路径,必须包双引号
整数8095端口、上限、数量
小数0.5概率、权重(如回复概率 reply_at_rate = 0.5)
开关(布尔值)true / falseenabled = false 关闭功能;只能全小写
列表(数组)["111111", "222222"]群白名单、用户名单、关键词
小组(内联表){ enabled = true }偶尔见到,照葫芦画瓢改里面的值即可

几条容易翻车的细节:

  • true / false 必须全小写,写成 True 会直接报错。
  • 名单类字段只有一项也要写成列表:group_list = ["111111"];留空就写 []。
  • 列表里的文字每一项各自带引号,项与项之间用英文逗号。
  • 列表长了可以跨行写,还能顺便给每一项加注释:
toml
[features]
group_list = [
  "111111111",   # 测试群
  "222222222",   # 主群
]

节与数组节,展开说说 ​

上面表格把 [节] 和 [[数组节]] 一笔带过,这里补充两个细节:

toml
# 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]] 就是一家:
toml
[[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 = "它的密钥"

自动生成的配置文件已经把节排好版,通常你只需要在现有节里改值,不用自己新建节。

多行文本:三引号字符串 ​

普通字符串有条铁律:一行一个值,中间不能换行。可提示词、使用说明这类内容天生就是好几行——人设里的大段性格描写就是典型。这时候用三引号 """ 把整段文字包起来:

toml
[plugin]
welcome = "欢迎进群!"      # 单行文本:老老实实一行写完

usage_notice = """          # 多行文本:三引号开头,随后换行
使用说明:
1. 发 /帮助 看看我都能干什么
2. 直接 @ 我就能聊天
"""                         # 三个引号收尾,习惯上单独占一行

三引号里有三条和直觉不太一样的规则,记住就不会踩坑:

  1. 开头 """ 后面的那个换行不算内容——所以正文从下一行开始写,开头不会多出空行。
  2. 中间想写什么写什么:换行原样保留;# 在这里就是普通文字、不再是注释;双引号 " 直接写、不用加反斜杠(只要别一口气连出三个)。
  3. 收尾 """ 之前的最后一个换行算内容——上面例子的值结尾其实带着一个换行,正常现象,不用纠结。

最常见的翻车:忘了收尾

只写了开头的 """ 没写收尾,后面整个文件都会被当成这段文字,报错行号会飘到离谱的地方。看到「莫名其妙的行报错」,先回头检查最近的多行文本有没有闭合;反过来,也别在正文中间随手插一行 """——那就等于提前收尾了。

不想被「转义」搅和?

在 """ 里写 \n 会被解释成换行、写 \\ 才是一个真的反斜杠——这个机制叫转义。如果填的内容里有真实反斜杠(比如 Windows 路径 C:\Users\xxx),想原样保留就改用三个单引号 ''':里面的所有字符原封不动,\n 就是字面上的「反斜杠加 n」:

toml
[plugin]
path_note = '''
路径示例:C:\Users\你的用户名\Documents
第二行的 \n 不会变成换行,原样保留
'''

「开头换行不算、结尾换行算」这两条规则,三单引号和三双引号完全一样。这套写法不稀奇:人设指南里的 personality_core 等字段,全都是三引号字符串。

新手最容易踩的三个坑

  1. 文字忘了加引号:nickname = 小狐狸 会报错,要写 nickname = "小狐狸"。
  2. 同一个名字写了两遍:TOML 不允许重复——同一个节里写两个相同字段、或同一个节名声明两次,启动时会直接报错。另一种「明明改了却没生效」则是改错了文件或改错了节——改之前先确认位置没找错。
  3. 动了标点:"、[、]、[[ 这些符号都是格式的一部分,别随手删;只有注释里明确说「删掉这行」的才整行删。

改错了也不用慌:最坏的情况就是启动报错。报错大多是英文,看不懂很正常——把报错信息和对应的配置文件一起扔给 AI(任意 AI 助手都行),让它告诉你哪里写错了、该怎么改,这一招对新手非常好使。

用什么编辑器改 ​

配置文件本质上是文本文件,用记事本也能打开改——但记事本不认识 TOML:没有颜色区分、写错了也不提醒,还容易把文件编码存错(中文一变乱码,配置就废了)。所以记事本只建议应急用,日常改配置推荐 VS Code:免费、全平台,装一个插件后能高亮 TOML、自动标出写错的地方。

  1. 到 code.visualstudio.com 下载安装。
  2. 点左侧「扩展」图标,搜索 Even Better TOML,点安装。
  3. 用它打开 config/ 里的任意配置文件:节和值按颜色区分,语法错误会画红色波浪线,鼠标悬停在字段上还能看到提示——对新手非常友好。

改完先别急着重启:多看看下面的问题

VS Code 窗口左下角有「⊗」和「⚠」两个小图标,点开(或按 Ctrl+Shift+M,菜单里叫「查看 → 问题」)就是底部的问题面板。写错的地方都会列在这里,点一条就能直接跳到出问题的那一行。把这里列出的问题清干净了,再去重启 Bot——很多报错根本走不到启动那一步,编辑器就已经帮你拦下来了。

编辑器不影响配置内容

编辑器只决定你「看得清不清楚、有没有纠错提醒」,配置文件本身怎么写、怎么生效不受影响。已经用惯了别的编辑器的话,继续用也没问题。

下一步 ​

贡献者

The avatar of contributor named as minecraft1024a minecraft1024a

页面历史

Released under the GPL-3.0 License.