設定優先順序與故障排除

返回 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