config.toml 配置教程

返回 Codex 教学总目录

目标与准备

AGENTS.md 告诉代理如何工作，config.toml 则设定应用选项。把「使用哪个模型」写进一段普通 Markdown，不等于已更改预设模型；同样地，在 config.toml 留一段没有注解符号的中文要求，可能让 TOML 无法解析。先用一项低影响设定学会正确位置与还原，再逐步增加真正需要的选项。

先分清使用者设定与专案设定

使用者设定预设是使用者目录下的 .codex/config.toml；若启动环境已有 CODEX_HOME，先确认实际指向哪里。专案设定则是储存库内的 .codex/config.toml，只在该专案被信任时载入。两个档案同名，但影响范围不同。本次只建立练习专案的档案，不需要搬走帐号验证、改使用者设定或更动系统环境变数。

步骤 1：先留下原本状态

建立新的 codex-config-lab，用编辑器开启，新增 note.txt 写入下方一行。从整合终端机确认位置：PowerShell 用 Get-Location，macOS／Linux 用 pwd；在确认全新练习资料夹后执行 git init，让专案根目录明确。先不要建立 .codex/config.toml。若同名资料夹已是别人的专案，换新的练习位置，不能为了照步骤重设它。

CONFIG-LAB-01

在系统终端机输入 codex --cd .。若出现专案信任选择，先核对就是自己刚建立的材料，再依画面处理。进入互动 CLI 后，分别输入下面两个斜线指令；它们不是 PowerShell 命令。/debug-config 用来看设定层及启用状态，/status 用来核对任务环境。记录相关层的路径与状态即可，不将完整私人设定输出贴到公开教学。

/debug-config

/status

看不到 /debug-config 时先输入 / 查看该版选单，再用 /exit 回系统终端机，以 codex --version 记版本；依官方安装来源更新后，重新启动 CLI 再查。不要臆造另一个同名 shell 指令。若版本或组织环境没有足够诊断资讯，就把有效值标成尚未确认，不能只靠模型说「已设定」就算完成。保存起始纪录后用 /exit 退出。

步骤 2：新增一项可还原设定

在编辑器的专案档案清单新增 .codex 资料夹，再建立 config.toml。检查路径确实为 codex-config-lab/.codex/config.toml，不是专案根目录的 config.toml 或 config.toml.txt。如果档案已存在，先复制到自己能辨认的备份位置并记下原值，只修改同一个顶层 web_search，不重复新增相同键。全新练习档可以直接使用下方完整内容。

# Practice setting: disable the built-in web search tool.
web_search = "disabled"

键名和值的拼字保持原样；字串要用半形引号，# 后面是注解。这是一个顶层键，不能不加判断就贴在 [features] 或其他表格段落下面；TOML 的表格标头会改变后续键的位置。不要把网页显示的程式码外框反引号一起贴进档案，存成 UTF-8 纯文字后再检查一次。

步骤 3：重新启动并确认生效来源

仍在练习根目录，用 codex --cd . 开新工作阶段，不使用 --search、-c 或 --profile 等额外选项，以免混入另一个实验。再看 /debug-config，确认专案层是否列出且启用；若显示因未信任被略过，先核对专案来源，再按正常信任流程处理。诊断资料的层级顺序可能由低到高显示，要看标签与启用状态，不能只把第一列当成赢家。

将有效设定或可用工具资讯与本档案比对，并送出下面的本机读取要求。预期 note.txt 正确回报 CONFIG-LAB-01，没有为这项任务执行网页搜寻；若介面提供 web_search 有效值，应为 disabled。单次没有搜寻只证明那次没用，不能单独证明设定成功，所以需保留设定层的诊断依据。

Read note.txt from this practice project and report its exact line. Do not edit files, browse websites or call external services. If you cannot verify an effective setting from available diagnostics, say so rather than inferring it from the file alone.

这个开关只关闭内建网页搜寻工具，不能用来证明所有网路都被封锁。Shell、浏览器、MCP 与外部服务还有自己的权限和设定；需要控制这些范围时读权限与沙盒。本例不开新服务、不做网路测试，也不为了证明搜寻关闭而绕到其他工具上网。

同一句「没有搜寻」，可能代表三种情况

判读例题：甲只有看到 config.toml 写 disabled；乙另有诊断显示该专案层因未信任而略过；丙看到该层已启用且有效值为 disabled。三者这次都没有搜寻。甲的有效值仍未知；乙要先解决载入来源，不能称此专案档已生效；丙才有这个设定的诊断证据，仍不能推论所有网路工具都被封锁。记录「档案内容／层是否载入／有效值／本次行为」四栏，缺证据的栏位留未确认。

步骤 4：还原并留下短纪录

退出 CLI 后，若原本没有此档案，把本次新建的 config.toml 移到专案设定目录以外的备份位置；若原本有档案，只还原 web_search 的旧值或移除这次新增的那一个键，保留其他设定。重新开新工作阶段，确认专案这项覆写已不再生效，note.txt 仍未改动。还原后的实际搜寻模式取决于其余设定，不一定回到某个你猜测的预设值。

File changed: codex-config-lab/.codex/config.toml
Original state: record whether the file/key existed.
Requested change: web_search = disabled
Loaded layer: record observed path and enabled/skipped state.
Effective value: record verified value, or unverified.
Local read: record actual note.txt result.
Restoration: record the restored file/key state and fresh-session check.

常见问题与下一步

不能启动时，先看错误指到哪份 TOML、哪一行，检查引号、重复键与表格位置；能启动但值没变时，查档案路径、专案信任、启动参数和较近的子目录设定；编辑器与 CLI 不同时，查它们是否在相同 OS、使用者与工作目录，尤其 Windows 和 WSL 不共享同一个使用者家目录。这些问题需要逐一查来源，重装程式通常不是第一个判断。

组织强制要求与一般预设不同，不能靠专案键覆写被禁止的值。模型、推理深度与额度另看模型选择，不要从网路抄一份整包设定把现有供应者与登入流程换掉。完成本篇应有起始、启用、还原三份纪录，并能指出哪些项目仍未确认；接著到设定故障排除实际诊断错误档案。本文入口与设定依官方文件查证，档案语法可独立验证，不能把语法正确当成每台机器都已载入。

返回 Codex 教学总目录

阅读完整文字说明

User config to Project config to CLI override

• AI 工具
• 教程
• Codex