Codex config.toml 完整詳解:文件在哪、有哪幾層、常用鍵怎麼寫、profiles 怎麼切換

Codex 的 config.toml 放在哪、有哪些層、誰覆蓋誰?按官方文檔整理:用戶級在 ~/.codex,項目級在 .codex/config.toml,七層優先級,常用鍵和 profiles 的寫法。

NNathaniel bigo··原創首發·AI 輔助撰寫
12 分鐘讀完
資料核對於 2026-11-13 · 依據官方文檔與公開資料整理 Plus 帳號

結論先說

  1. 用戶級配置在 ~/.codex/config.toml(~/.codex 就是 CODEX_HOME,預設位置)。桌面 App、命令行和 IDE 擴展讀的是同一套配置層。
  2. 項目級配置放倉庫裏的 .codex/config.toml,但官方寫明:只有你信任該項目時才會加載。
  3. 優先級從高到低共七層:命令行參數與 --config → 項目配置 → profile 文件 → 用戶配置 → 雲端託管配置 → 系統配置 → 內置預設值。
  4. profiles 是獨立文件:~/.codex/名字.config.toml,用 codex --profile 名字 選擇。官方強調:文件裏直接寫頂層鍵,不要再套 [profiles.名字]。
  5. TOML 規則:根級鍵必須寫在所有表([xxx])之前,否則會讀錯位置。

config.toml 七層優先級:命令行、項目、profile、用戶、雲端託管、系統、內置預設

圖:本站根據 Codex 官方 Config basics 整理的示意圖

本文根據 Codex 官方文檔的 Config basics、Advanced Config、Sample Configuration 和 Configuration Reference 整理,資料核對於 2026-11-13。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。MCP 的配置寫法見 /guides/codex-mcp-config,權限與沙箱的取值見 /guides/codex-permissions-sandbox,本文不重複。

適用於誰

  • 想知道 Codex 的配置文件在哪、能改什麼的人;
  • 全局設定、項目設定、命令行參數衝突,不知道聽誰的人;
  • 想給「日常」「代碼審查」「CI」準備不同配置一鍵切換的人。

一、文件在哪

  • 用戶級: ~/.codex/config.toml。在 Windows 上對應用戶目錄下的 .codex 文件夾。如果在 WSL 裏跑命令行,它用的是 Linux 的家目錄,與 Windows 那份不共用,見 /guides/codex-app-vs-cli-which-better。
  • 項目級: 倉庫裏的 .codex/config.toml。Codex 會從項目根目錄走到當前工作目錄,把沿途每一個 .codex/config.toml 都讀進來,同一個鍵以離你當前目錄最近的那份為準。項目裏相對路徑(比如 model_instructions_file)按這個 .codex 文件夾計算。
  • 系統級: Unix 下是 /etc/codex/config.toml,有才讀。
  • IDE 擴展裏打開: 右上角齒輪 → Codex Settings > Open config.toml。
  • CODEX_HOME 下還有 auth.json(文件方式存憑據時)、history.jsonl(開啟歷史時)和日誌緩存等。

項目配置裏「被忽略」的鍵

出於安全,官方列出了項目裏的 .codex/config.toml 不能改的鍵,Codex 看到會忽略並在啟動時警告:openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel。也就是說,換接口地址、換模型提供方、通知命令這類涉及憑據和外發的設定,只能寫在你自己的用戶級配置裏。

二、誰覆蓋誰:七層優先級

官方給的順序(越靠前越優先):

  1. 命令行參數和 --config 覆蓋;
  2. 項目配置文件(.codex/config.toml,從項目根到當前目錄,越近越優先,僅限信任的項目);
  3. 用 --profile 選的 profile 文件;
  4. 用戶配置 ~/.codex/config.toml;
  5. 為已登入工作區下發的雲端託管配置;
  6. 系統配置;
  7. 內置預設值。

實用做法是官方建議的:共用預設值寫進 config.toml,profile 文件只寫有差別的幾項。如果你的電腦由公司管理,管理員還可以用 requirements.toml 強制限制,比如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access",這類限制不能被你的配置繞開。

項目被標為不信任時,Codex 跳過項目裏的 .codex/ 層,包括配置、鉤子和規則,用戶和系統層照常加載。

三、常用鍵怎麼寫

下面的鍵和寫法都來自官方 Config basics 或示例配置。

toml
model = "gpt-6.1-sol"               # 預設模型(需帳號可用)
model_reasoning_effort = "medium"   # 推理強度
approval_policy = "on-request"      # 何時請求審批,預設值
sandbox_mode = "read-only"          # 沙箱,示例配置裏的預設值
web_search = "cached"               # 聯網搜尋:cached(預設) | indexed | live | disabled
notify = ["python3", "/path/to/notify.py"]   # 回合結束時調用外部程序

幾處細節:

  • model_reasoning_effort 官方寫的是「模型支持時才生效」,可選檔位隨模型而異,換法見 /guides/codex-switch-model-reasoning-effort。
  • web_search 預設 "cached"。官方寫明使用完全訪問沙箱(如 --yolo)時預設變成 live。
  • project_doc_max_bytes 預設 32768,是讀取 AGENTS.md 並放進首輪指令的上限字節數;project_doc_fallback_filenames 可以在沒有 AGENTS.md 時指定備用文件名,讀取規則見 /guides/codex-agents-md-how-it-reads。
  • [history] 表裏的 persistence 預設 save-all,設成 none 就不再儲存本地會話記錄;max_bytes 限制歷史文件大小,超出會刪最舊的。
  • [features] 表用來開關功能,寫法是 功能名 = true;命令行臨時開啟用 codex --enable 功能名。
  • [tui] 表控制終端介面,比如 notifications、status_line、terminal_title。
  • [projects."/絕對路徑"] 下的 trust_level 取 trusted 或 untrusted,決定上面說的項目層加不加載。
  • [shell_environment_policy] 控制轉發給子命令的環境變量。官方寫明 ignore_default_excludes 預設是 true,即不自動過濾名字含 KEY、SECRET、TOKEN 的變量;想要自動過濾要設成 false。

官方的示例配置文件按塊組織:核心模型、推理與詳略、指令覆蓋、通知、審批與沙箱、登入、項目文檔、歷史、介面、聯網搜尋、多 Agent 角色、技能、沙箱表、環境變量策略、功能開關、記憶、模型提供方、應用與連接器、profiles、項目信任、OpenTelemetry、Windows。你可以把它當字典,只複製要用的鍵,不用整份照搬。

四、profiles:一鍵切換整套設定

官方原話大意:用 --profile 名字 時,Codex 先讀 ~/.codex/config.toml,再疊上 ~/.codex/名字.config.toml。名字可以有字母、數字、連字符和下劃線。

例如新建 ~/.codex/deep-review.config.toml:

toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"

使用:

bash
codex --profile deep-review
codex exec --profile deep-review "review this change"

因為 profile 層在項目和命令行之下、用戶配置之上,它只需要寫與基礎配置不同的部分。

舊寫法已失效。 官方寫明從 Codex 0.134.0 起,--profile 不再讀取 config.toml 裏的 [profiles.名字],頂層 profile = "名字" 選擇器也不再支持。如果你照着舊教學寫了這些,要把設定搬到 ~/.codex/名字.config.toml,再刪掉舊錶和舊選擇器。

config.toml 常用鍵速查與 profile 文件命名規則

圖:本站根據 Codex 官方 Config basics 整理的示意圖

五、臨時改一次,不動文件

官方推薦:有專門參數就用專門參數(如 --model),否則用 -c / --config:

bash
codex --model gpt-6.1-sol
codex --config sandbox_workspace_write.network_access=true
codex -c log_dir=./.codex-log

要點:鍵可以用點號表示嵌套;值按 TOML 解析,所以字符串要帶引號(官方示例是 model='"gpt-6.1-sol"'),為了不被 shell 拆開最好整體加引號;解析不了時當字符串處理。

常見問題

Q:改了 config.toml 沒生效?

先看有沒有被更高層覆蓋:命令行參數、項目配置、profile 文件都比它優先;再確認這個鍵是不是被寫在了某個 [表] 的下面,根級鍵要寫在表之前。

Q:項目裏的配置為什麼沒讀?

多半是項目沒被信任,或寫的是上面那些被忽略的鍵。

Q:Codex 額度不夠用,是不是靠改配置能解決?

配置只能改模型和推理強度這類選擇,額度隨套餐,以官方頁面當前顯示為準。需要更高額度可看 ChatGPT Plus 充值說明。

相關教學

參考資料

  • Codex 官方文檔:Config basics — https://learn.chatgpt.com/docs/config-file/config-basic
  • Codex 官方文檔:Advanced Config — https://learn.chatgpt.com/docs/config-file/config-advanced
  • Codex 官方文檔:Sample Configuration — https://learn.chatgpt.com/docs/config-file/config-sample

Nathaniel 的更多內容

  1. 01

    LangGraph 流式輸出(Streaming)詳解:逐字 Token 流、節點進度與自定義事件寫法

    多步智能體如果等全部節點跑完才返回,網頁前端就會白屏乾等十幾秒。本文按 LangGraph 官方文檔講清 updates、messages、custom 與 values 四種 stream_mode 的區別,以及組合訂閱逐字打字機輸出加工具內部實時進度的完整代碼。

    其他 AI 工具0
  2. 02

    LangGraph 持久化與長期記憶怎麼配:Checkpointer、Store 與 PostgreSQL 實戰

    在生產環境跑 LangGraph,單靠 InMemorySaver 一重啟就會丟失全部對話。本文按官方文檔講清線程內短期檢查點(Checkpointer)與跨線程長期記憶(Store)的分工,以及用 langgraph-checkpoint-postgres 對接 PostgreSQL 的完整步驟。

    其他 AI 工具0
  3. 03

    LangGraph 多智能體怎麼寫:Supervisor 主管包與 Subgraph 隔離子圖實戰

    在 LangGraph 裏把單個圖擴展成多智能體協作有兩條官方路線:快速原型用預置包 langgraph-supervisor,大型生產系統用原生子圖(Subgraph)嵌套。本文講清兩種寫法的完整代碼、私有狀態隔離防 Token 膨脹技巧以及檢查點傳播規則。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入審批怎麼寫:interrupt 暫停圖運行與 Command 恢復實戰

    企業之所以選 LangGraph,很大程度看中它能安全掛起等待人工審批(Human-in-the-Loop)。本文按官方最新規範講清 interrupt() 動態暫停、Checkpointer 必備條件、Command(resume=...) 恢復執行,以及防止副作用重複運行的重入規則。

    其他 AI 工具0
  5. 05

    多 Agent 協作平台怎麼選:Dify、釦子(Coze)、n8n 與 LangGraph 多智能體機制對比

    搜「多agent協作平台」時,Dify、釦子、n8n 和 LangGraph 都宣稱支持多智能體,但底層的調度方式完全不同。本文跳過基礎安裝,專門從多 Agent 角色跳轉、子代理工具調用、上下文隔離與私有化部署四個維度幫你一次選準。

    其他 AI 工具0
  6. 06

    企業微信有官方 MCP 和 CLI 嗎:@wecom/cli 安裝初始化、長連接機器人與接入教學

    搜「企業 微信 有 mcp 嗎」不用再東拼西湊民間群機器人腳本了:企業微信官方已推出 @wecom/cli 命令行工具並內置 stdio 模式的 MCP Server。本文按官方開發者文檔講清安裝、智能機器人長連接初始化、業務命令與接入 Claude Code 步驟。

    Claude其他 AI 工具0

同產品的其他教學

  1. 01

    AutoGen 現在怎麼樣了?微軟官方演進路線與 Microsoft Agent Framework 入門

    搜 AutoGen 新教學常被 0.2、0.4、社區分支和 Semantic Kernel 繞暈。按微軟官方文檔,微軟已將 AutoGen 與 Semantic Kernel 兩支團隊合併推出統一的開源框架 Microsoft Agent Framework。本文講清現狀與 Python 快速上手。

    ChatGPT其他 AI 工具0
  2. 02

    多 Agent 的成本為什麼翻倍、怎麼控制:Token 膨脹根源與五項降本措施

    剛把單智能體拆成多 Agent,用量往往暴漲好幾倍。Anthropic 工程報告統計單智能體約為聊天的 4 倍 Token,多智能體可達約 15 倍。本文拆解固定前綴重複加載、歷史搬運、工具鏈定義與緩存失效四大根源,並給出五條實操控費辦法。

    ChatGPTClaude0
  3. 03

    多 Agent 協同開發怎麼落地:「一個寫、一個審」雙代理工作流搭建指南

    多 Agent 協同開發裏投入產出比最高的模式就是「一個寫、一個審」。本文依據 Anthropic 與 OpenAI 官方編碼最佳實踐,講清為什麼同會話自審容易漏問題,以及用只讀子代理、跨模型交叉審查(Claude Code + Codex)和自動化閉環落地的具體方法。

    ClaudeCodex0
  4. 04

    多 Agent 編排模式詳解:編排者-工作者、交接(Handoffs)、並行與評估循環怎麼選

    搜「multi-agent orchestration 中文」會被各家框架的不同術語繞暈。本文對照 Anthropic《Building effective agents》與 OpenAI 智能體指南,把編排者-工作者、去中心化交接、並行分片投票與生成-評估循環四種標準編排拓撲講透。

    ChatGPTClaude0
  5. 05

    多智能體(Multi-Agent)是什麼、什麼時候該用:Anthropic 與 OpenAI 官方判斷標準

    多智能體不是代理越多越聰明。本文依據 Anthropic 研究系統架構文章與 OpenAI 官方智能體指南,講清確定性工作流、單智能體與多智能體的區別,以及哪三類瓶頸才值得上多智能體協同。

    ChatGPTClaude0
  6. 06

    codebase-memory 類 MCP 是什麼、怎麼用:基於語法樹圖譜的本地代碼索引原理與配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一類本地代碼圖譜 MCP 伺服器:用 Tree-sitter 把倉庫解析成函數與調用關係的 SQLite 圖庫,幫編碼助手查調用鏈並省下讀整份文件的額度。

    ClaudeCodex0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~