Configuration precedence and diagnosis

Back to the Codex learning hub

Goal and preparation

The checker understands only this lesson's web_search setting, not the complete Codex schema. It reads no other settings and makes no network request. A pass establishes syntax and the selected key in that file, not client loading, organization permission or other tools' behavior. Keep that boundary clear when interpreting success.

Step 1: Create offline samples and a checker

Create codex-config-checks and root check_config.py using the complete program below. It opens only the named file and reports syntax location or this one key, not the entire configuration. Use the isolated samples you create here rather than a real credential-bearing file for screenshots.

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")

First create good.toml below. This valid baseline establishes that Python and the checker run before you diagnose a broken sample. Otherwise you cannot separate a missing tool from the intended failure. Save both files as UTF-8 with their actual extensions, not .txt.

web_search = "disabled"

Run the Windows line in PowerShell or the macOS/Linux line in Terminal from the lab. Expect PASS and the explicit loading limitation. No module named tomllib means you should check Python: tomllib was added in 3.11, and is not a missing Codex plugin.

py -3 check_config.py good.toml

python3 check_config.py good.toml

Use the exit code to identify the result

Immediately after each run, inspect its exit code in the same terminal: $LASTEXITCODE in Windows PowerShell, echo $? on macOS/Linux. Do not run another program first. Expect 0 for good.toml and 1 for each of the four original faults. Save repaired copies as fixed-quote.toml, fixed-duplicate.toml, fixed-scope.toml and fixed-value.toml; expect 0 for each while preserving the faulty originals.

Step 2: Diagnose four distinct failures

Save broken-quote.toml below. Its missing closing quote should fail TOML parsing. Substitute its filename in the checker command. The location may point at line end or a following character, not literally say “missing quote.” Inspect backward along the named line, add the straight closing quote and rerun. Retain the original error sample and repaired copy for comparison.

web_search = "disabled

broken-duplicate.toml defines the same top-level key twice. This is not last-line-wins: a duplicate definition in one TOML file is invalid. Keep the intended disabled value, remove the duplicate and rerun. Cross-file precedence and same-file duplicate keys are different mechanisms.

web_search = "disabled"
web_search = "live"

broken-scope.toml is valid TOML, but the table header places web_search inside features. The checker reports a missing top-level key. Codex may also reject a wrong location/type; parsing alone does not make it a supported setting. Move web_search before any table header and remove the features content added solely for this exercise.

[features]
web_search = "disabled"

broken-value.toml uses the plausible but unsupported off value. It is a valid TOML string, not a documented web_search mode. Replace it with disabled and rerun; do not translate configuration values because another program uses on/off. Other settings such as models and reasoning need their own current account/version checks, not this narrow checker.

web_search = "off"

What PASS does not cover

One boundary case: the sample below also prints PASS because web_search passes this exercise and extra_practice_key is not checked. Save it as limits.toml for offline testing only, outside .codex. This does not establish that Codex accepts the extra key or that its full schema passes. Identify the unchecked part in your record.

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

Step 3: When valid syntax still has no effect

Return to the real project from configuration basics, keeping broken samples out of startup settings. In a fresh CLI session use /debug-config to inspect paths, enabled layers and requirements. Compare the edited path with the loaded path, check the working subdirectory and launch overrides such as --search, -c or --profile. Change one factor and restart, rather than changing model, login, sandbox and tools together.

The table describes ordinary value merging; enforced requirements.toml constraints still apply separately. For skipped untrusted layers, verify origin and handle trust normally, without renaming or moving files to bypass restrictions. For Windows/WSL disagreement, identify the executable and home directory: each environment can have separate configuration and authentication despite matching filenames.

Repair, restore and record

Before a real repair, back up the file confirmed to load and edit only the identified key. Preserve authentication, provider and unrelated settings rather than replacing the entire file with an example bundle. Restart and check diagnostics plus the local marker. If the effective value cannot be established, record that uncertainty and why. Revert the targeted key/file if a new issue appears; do not clear all of .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.

Finish with a passing baseline, four diagnosed failures and passing repaired copies. In a real session, distinguish an unloaded file from an overridden loaded value and recognize insufficient evidence. The Python samples receive offline parsing checks; effective Codex layers use the documented diagnostics. Model, MCP and permission problems need their corresponding lessons, not conclusions from this one-key checker.

Back to the Codex learning hub

Read the full description

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

• AI tools
• Tutorials
• Codex