设定优先顺序与故障排除

返回 Codex 教学总目录

目标与准备

这个练习的检查器只认识本篇的 web_search，不是 Codex 完整 schema，也不会读其他设定或连网。它通过只代表这个档案的语法与指定键符合练习，不能证明 Codex 已载入、组织允许或其他工具行为已改变。把验证范围先讲清楚，才不会拿一个成功讯息替所有层级背书。

步骤一：建立离线样本与检查器

建立新的 codex-config-checks，使用编辑器开启，在根目录新增 check_config.py。下面是完整程式：它只打开命令列指定的档案，显示错误位置或本篇键的结果，不列印整份私人设定。这次检查的都是你另外建立的虚构样本，不要传入有密码的正式档案来截图。

from pathlib import Path
import sys
import tomllib

if len(sys.argv) != 2:
    raise SystemExit("Usage: check_config.py SAMPLE.toml")
path = Path(sys.argv[1])
try:
    with path.open("rb") as stream:
        data = tomllib.load(stream)
except (OSError, tomllib.TOMLDecodeError) as exc:
    print(f"FAIL: {exc}")
    raise SystemExit(1)
if "web_search" not in data:
    print("FAIL: missing top-level web_search; inspect table placement")
    raise SystemExit(1)
value = data["web_search"]
if not isinstance(value, str) or value not in {"disabled", "cached", "indexed", "live"}:
    print("FAIL: unsupported web_search value for this exercise")
    raise SystemExit(1)
print(f"PASS: sample syntax and web_search={value}; Codex loading is not verified")

先新增 good.toml，内容如下。这是正确起点，用来确认检查器和 Python 本身能执行。不要先用坏样本测试工具，否则看到错误时无法分辨是工具缺失还是故障题目。档案和程式都存成 UTF-8，确认副档名不是 .txt。

web_search = "disabled"

Windows 在练习目录的 PowerShell 执行第一行；macOS／Linux 在 Terminal 执行第二行，择自己的系统即可。预期显示 PASS，并明确写 Codex loading is not verified。若出现 No module named tomllib，先查 Python 版本；tomllib 从 Python 3.11 才加入，不是缺少某个 Codex 插件。

py -3 check_config.py good.toml

python3 check_config.py good.toml

先用退出码确认你看到的是哪次结果

每次执行后，立即在同一个终端机查看退出码：Windows PowerShell 用 $LASTEXITCODE，macOS／Linux 用 echo $?。中间不要再跑另一个程式，否则读到的是后一个命令的结果。good.toml 预期为 0，四份未修的故障样本各为 1；将每份另存为 fixed-quote.toml、fixed-duplicate.toml、fixed-scope.toml、fixed-value.toml 再修正，四份修正版都应为 0，原始故障档保留。

步骤二：诊断四种不同失败

将下一段存成 broken-quote.toml。它缺少结束引号，TOML 解析应失败。把执行命令最后的 good.toml 换成此档名；错误可能指向行尾或下一个字元，不一定直接说「少引号」。先从指出的位置往前看这一行，补上半形引号，再执行一次确认通过。保留原错误内容与修正后副本便于比较。

web_search = "disabled

broken-duplicate.toml 则有两个相同顶层键。它不是「最后一行赢」；同一份 TOML 重复定义同一个键应报错。先决定这份样本只保留 disabled，再删掉重复那行，确认通过。跨档案的优先顺序与单档内重复键是两个不同问题，不能把它们混用。

web_search = "disabled"
web_search = "live"

broken-scope.toml 的 TOML 语法本身有效，但 web_search 被放进 features 表格，变成另一个完整键路径。检查器会指出缺少顶层键；Codex 对错位置或错型别的设定也可能报错，不能把解析通过当成设定可用。本例应将 web_search 放到任何表格标头之前，且不保留这段为了练习加上的 features 内容。

[features]
web_search = "disabled"

broken-value.toml 用了看似合理但本设定不接受的 off。它是合法 TOML 字串，却不是官方 web_search 选项。改成 disabled 后再检查；不要因为别的软体用 on/off，就自行翻译设定值。模型名称、推理选项也必须核对帐号和当前版本，但不要拿本篇小检查器验证那些不同设定。

web_search = "off"

PASS 没有涵盖哪些内容

再看一个检查器的界线：下列样本同样会显示 PASS，因为 web_search 符合本篇检查，extra_practice_key 并未被检查。将它另存 limits.toml 只供离线测试，不放进 .codex。这不代表 Codex 接受额外键，也不代表完整 schema 已通过；你要能在纪录中指出本程式根本没有验证的部分。

web_search = "disabled"
extra_practice_key = "not checked by this exercise"

步骤三：语法正确但没有生效时

先回设定入门的真实练习专案，不把故障样本当启动设定。用新 CLI 工作阶段的 /debug-config 看载入路径、是否启用与要求来源。把你编辑的路径和实际载入路径逐字比较；再核对是否从另一个子目录启动、启动命令是否带 --search、-c 或 --profile。只改一项再重启，不同时更换模型、登入、沙盒与工具版本。

这张表整理的是一般值的合并，组织 requirements.toml 的强制限制仍需另外遵守。若专案层被标为未信任而略过，先确认来源再处理信任，不要改名或搬档来避开限制。若 Windows 能生效而 WSL 不行，先查你用的是哪个 codex 与哪个家目录；两个环境可有各自设定与登入，不能用档案名称相同推定内容相同。

修正、还原与交付纪录

真正要改设定时，先备份那份确定会载入的档案，只修改已定位的键。保持原来的帐号、供应者及其他设定，不贴上整包范例取代整份档案。重启后核对诊断与本机标记；若无法证明有效值，写「尚未确认」，保留原因。出现新问题就把该键或档案还原，再核对已回到先前状态，不需要清空整个 .codex。

Symptom: record the actual error or unchanged setting.
File and layer: record the relevant path and whether it loaded.
Diagnosis: syntax / key scope / unsupported value / precedence / trust / policy.
Minimal change: record exactly one repaired cause.
Validation: distinguish sample parser checks from actual client diagnostics.
Restoration: record the backup or original value and the result after restarting.

完成后应有一份通过的起点、四份能说明原因的故障样本，以及各自修正后通过的副本。另能用真实工作阶段分清「档案没载入」和「载入但被覆写」，并知道何时仍缺乏证据。本篇 Python 样本以离线解析验证，Codex 的有效层级则依官方诊断流程确认；模型、MCP 或权限的问题再连到相应专篇，不用这个单键检查器替它们下结论。

返回 Codex 教学总目录

阅读完整文字说明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教程
• Codex