TOML、JSON、YAML、INI 配置文件格式总结
本文总结了 TOML 的含义，并对 TOML、JSON、YAML、INI 这几种常见配置/数据文件格式进行对比，帮助理解它们的相似处、区别和适用场景。
1. TOML 是什么？
TOML是一种配置文件格式，文件后缀通常是：
.toml它的全称是：
Tom's Obvious, Minimal Language可以翻译为：
Tom 的直观、极简语言
这里的Tom指 TOML 的作者；Obvious, Minimal Language表示它的设计目标是：
| 单词 | 含义 | 解释 |
|---|---|---|
| Obvious | 直观 | 人一眼能看懂配置内容 |
| Minimal | 极简 | 语法尽量简单，不搞复杂规则 |
| Language | 语言 | 一种用于表达配置的文本格式 |
所以 TOML 的核心思想是：
让配置文件既适合人手动编辑，也适合程序读取。
例如 Codex 的配置文件：
~/.codex/config.toml就是一个 TOML 文件。
2. TOML 文件主要用来做什么？
TOML 通常用于软件配置，例如：
model = "gpt-5.4" model_reasoning_effort = "high"含义是：
model 这个配置项的值是 "gpt-5.4" model_reasoning_effort 这个配置项的值是 "high"常见使用场景包括：
Python 项目配置：pyproject.toml Rust 项目配置：Cargo.toml Codex 配置：~/.codex/config.toml 工具/服务配置文件 Agent / MCP 工具配置3. TOML 基本语法
3.1 键值对
model = "gpt-5.4" enabled = true timeout = 30| 写法 | 类型 | 含义 |
|---|---|---|
"gpt-5.4" | 字符串 | 文本内容 |
true/false | 布尔值 | 开启或关闭 |
30 | 数字 | 数值配置 |
3.2 表 / 配置分组
TOML 用方括号表示配置分组：
[projects."/workspace"] trust_level = "trusted"可以理解为：
projects 下面有一个 "/workspace" 项目配置 这个项目的 trust_level 是 trusted对应 JSON 结构大致是：
{"projects":{"/workspace":{"trust_level":"trusted"}}}3.3 数组
TOML 使用方括号表示数组：
args = ["-y", "@upstash/context7-mcp"] env_vars = ["CONTEXT7_API_KEY"]类似 Python 里的列表：
["-y","@upstash/context7-mcp"]3.4 注释
TOML 使用#写注释：
# 这是注释，不会被程序读取 model = "gpt-5.4"4. Codex MCP 配置中的 TOML 示例
在 Codex 中，一个 MCP Server 可以这样配置：
[mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] env_vars = ["CONTEXT7_API_KEY"] enabled = true含义是：
配置一个名为 context7 的 MCP server 启动命令是 npx 启动参数是 ["-y", "@upstash/context7-mcp"] 把 CONTEXT7_API_KEY 环境变量传给它 启用这个 MCP server如果配置 arxiv MCP，可以类似这样写：
[mcp_servers.arxiv-mcp-server] command = "npx" args = ["-y", "@langgpt/arxiv-mcp-server@latest"] env_vars = ["SILICONFLOW_API_KEY"] enabled = true [mcp_servers.arxiv-mcp-server.env] WORK_DIR = "/workspace/arxiv-mcp-server"5. TOML 编辑时的常见注意事项
5.1 不要重复定义同一个表
错误示例：
[mcp_servers.context7] command = "npx" [mcp_servers.context7] enabled = true这是错误的，因为[mcp_servers.context7]出现了两次。
正确写法：
[mcp_servers.context7] command = "npx" enabled = true5.2 字符串要加引号
正确：
model = "gpt-5.4"错误：
model = gpt-5.45.3 数组要用方括号
正确：
args = ["-y", "@upstash/context7-mcp"]6. JSON、YAML、INI、TOML 的相似处
这几种格式本质上都属于：
用来保存配置数据或结构化数据的文本格式。
它们经常用于：
软件配置 项目配置 工具参数 服务启动配置 环境配置 API 配置 MCP / Agent 配置它们都可以表达类似的信息，例如：
模型名称 是否启用某个功能 路径 端口 参数列表 环境变量 嵌套配置例如，要表达下面这组信息：
model = gpt-5.4 enabled = true args = ["-y", "context7"]可以分别用 JSON、YAML、INI、TOML 表示。
7. JSON
7.1 JSON 是什么？
JSON全称是：
JavaScript Object Notation它最初来自 JavaScript，但现在已经成为非常通用的数据交换格式。
示例：
{"model":"gpt-5.4","enabled":true,"args":["-y","@upstash/context7-mcp"]}7.2 JSON 的特点
JSON 更适合：
程序之间传输数据 API 返回结果 Web 前后端通信 机器读取优点：
标准化程度高 几乎所有编程语言都支持 结构严谨 适合机器解析缺点：
不能写注释 括号、引号、逗号比较多 人工手动编辑配置不够舒服 最后一个元素不能多写逗号8. YAML
8.1 YAML 是什么？
YAML 是一种常用于配置文件的格式，尤其常见于 DevOps 和云原生场景。
典型场景包括：
Docker Compose Kubernetes GitHub Actions Ansible CI/CD 配置示例：
model:gpt-5.4enabled:trueargs:--y-"@upstash/context7-mcp"8.2 YAML 的特点
YAML 更适合：
复杂配置 多层级配置 DevOps / 云原生配置 CI/CD 工作流配置优点：
可读性强 支持注释 比 JSON 少很多括号 适合写复杂层级结构缺点：
非常依赖缩进 缩进错误容易导致配置错误 语法规则比看起来复杂 字符串、布尔值、数字的解析有时容易混淆例如：
enabled:true和：
enabled:"true"含义可能不同：前者是布尔值，后者是字符串。
9. INI
9.1 INI 是什么？
INI 是一种很早期、很简单的配置文件格式，Windows 和很多传统软件都使用过。
示例：
model = gpt-5.4 enabled = true [context7] command = npx9.2 INI 的特点
INI 更适合：
简单配置 传统软件配置 没有复杂嵌套的场景优点：
极其简单 人很容易读 适合简单 key-value 配置缺点：
标准不够统一 不擅长表达数组、对象和复杂嵌套 不同程序对 INI 的解析规则可能不同例如表达数组时，INI 没有统一标准：
args = -y,@upstash/context7-mcp这就需要程序自己决定如何解析。
10. TOML
10.1 TOML 的定位
TOML 可以理解为介于 INI 和 YAML 之间：
比 INI 表达能力更强 比 YAML 更简单、更不容易因为缩进出错 比 JSON 更适合人手写配置示例：
model = "gpt-5.4" enabled = true args = ["-y", "@upstash/context7-mcp"] [mcp_servers.context7] command = "npx" enabled = true10.2 TOML 的特点
TOML 更适合：
项目配置 工具配置 人工维护的配置文件 需要清晰数据类型的配置典型例子：
Cargo.toml Rust 项目配置 pyproject.toml Python 项目配置 config.toml Codex 配置优点：
比 JSON 更适合人工编辑 比 YAML 更不容易因为缩进出错 比 INI 更能表达数组、布尔值、数字、嵌套结构 支持注释 类型比较明确缺点：
表达特别复杂的数据结构时不如 YAML 灵活 table 重复定义容易报错 语法比 INI 稍复杂11. 四种格式对比表
| 格式 | 全称 | 主要用途 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|---|---|
| JSON | JavaScript Object Notation | 数据交换、API | 标准化强，机器友好，语言支持广泛 | 不能写注释，人工编辑麻烦 | API、Web、程序间数据传输 |
| YAML | YAML Ain’t Markup Language | 复杂配置、DevOps | 可读性强，支持注释，适合复杂层级 | 缩进敏感，规则复杂，容易踩坑 | Kubernetes、Docker Compose、CI/CD |
| INI | Initialization File | 简单配置 | 极简、容易读写 | 标准不统一，不适合复杂结构 | 传统软件、简单配置 |
| TOML | Tom’s Obvious, Minimal Language | 项目/工具配置 | 清晰、支持注释、类型明确，适合手写 | 复杂结构能力中等，重复表会报错 | Codex、Python、Rust、工具配置 |
12. 同一个 MCP 配置的四种写法对比
下面用同一个 MCP server 配置作为例子，对比四种格式。
12.1 JSON
{"mcp_servers":{"context7":{"command":"npx","args":["-y","@upstash/context7-mcp"],"enabled":true}}}特点：结构严谨，但括号和引号多。
12.2 YAML
mcp_servers:context7:command:npxargs:--y-"@upstash/context7-mcp"enabled:true特点：看起来简洁，但高度依赖缩进。
12.3 INI
[mcp_servers.context7] command = npx args = -y,@upstash/context7-mcp enabled = true特点：简单，但数组表达不标准，依赖程序自己解析。
12.4 TOML
[mcp_servers.context7] command = "npx" args = ["-y", "@upstash/context7-mcp"] enabled = true特点：清晰、支持数组和布尔值，适合人工手动维护配置。
13. 最简单的记忆方式
JSON：给机器看的数据格式，常用于 API 和数据交换。 YAML：给复杂系统写配置，常用于 DevOps，但缩进容易出错。 INI：最简单的老式配置格式，适合简单 key-value。 TOML：给人手写、给程序读取的现代配置格式。对于 Codex MCP 场景，可以这样理解：
Codex 使用 TOML，是因为它既需要人能手动编辑， 又需要表达 MCP server、启动命令、参数、环境变量、项目路径等结构。14. 选择建议
| 你的需求 | 推荐格式 |
|---|---|
| API 返回数据、程序间传输 | JSON |
| Kubernetes、Docker、CI/CD 等复杂配置 | YAML |
| 非常简单的软件配置 | INI |
| 项目配置、工具配置、Codex MCP 配置 | TOML |
15. 总结
TOML、JSON、YAML、INI 都是文本格式，都可以用来描述配置或结构化数据。
它们的核心区别在于：
JSON 更偏机器读写； YAML 更偏复杂配置； INI 更偏简单配置； TOML 更偏现代项目配置和人工可维护配置。在你的 Codex 场景中，~/.codex/config.toml用 TOML 是比较合适的，因为它既清晰，又能表达 MCP 工具所需的复杂配置，例如：
工具名称 启动命令 启动参数 是否启用 环境变量 工作目录 项目路径信任配置