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