設定基礎

Codex 從多個位置讀取設定。你的個人預設設定儲存在 ~/.codex/config.toml 中，也可以通過 .codex/config.toml 檔案新增專案級覆蓋設定。出於安全考慮，Codex 僅在你信任專案時載入專案的 .codex/ 設定層。

Codex 設定檔

Codex 將使用者級設定儲存在 ~/.codex/config.toml。要將設定限定於特定專案或子資料夾，請在儲存庫中新增 .codex/config.toml 檔案。

要從 Codex IDE 擴充套件開啟設定檔，請選擇右上角的齒輪圖示，然後選擇 Codex 設定 > 開啟 config.toml。

CLI 和 IDE 擴充套件共用相同的設定層。你可以用它們來：

• 設定預設模型和供應商。
• 設定審批策略和沙箱設定。
• 設定 MCP server。

設定優先順序

要求用於約束行為；設定值用於提供預設值。通過 Work Cloud 存取本機電腦時，遵循以下要求：

• 跨策略： 優先順序較高的策略優先於優先順序較低的策略，即使後者更具體也是如此。
• 同一策略內： 特定作業系統的環境覆蓋設定優先於適用於所有作業系統的環境覆蓋設定，最後是 Global。
• 本機執行： MDM 和舊版受管裝置要求的優先順序高於 Agent Security。裝置的系統要求檔案的優先順序低於 Agent Security。
• Work Cloud： Work 雲容器保留現有的 Work Cloud 策略。對於具有本機存取權限的 Work 和 dots，啟用受管策略後，受支援的 Global 策略約束共享的雲端編排器；適用的本機執行要求約束所連線的電腦。

某些要求具有特定欄位的合併規則。有關策略作用域和執行時限制，請參閱受管設定；有關 Work 相容性，請參閱設定參考。

Codex 按以下順序解析設定值（優先順序從高到低）：

1. CLI 標誌和 --config 覆蓋設定
2. 專案設定檔：.codex/config.toml，按專案根目錄到當前工作目錄的順序排列（距離最近的優先；僅適用於受信任專案）
3. 通過 --profile profile-name 選擇的設定檔檔案（~/.codex/profile-name.config.toml）
4. 使用者設定：~/.codex/config.toml
5. 雲端管理的 config.toml 預設設定（如果已為登入的工作區下發）
6. 系統設定（如果存在）：Unix 上的 /etc/codex/config.toml
7. 內建預設設定

利用這一優先順序，在 config.toml 中設定共用的預設值，讓設定檔只包含存在差異的值。

雲端管理的設定和系統設定可以定義外掛市場，並設定 是否預設啟用外掛。這些設定獨立於強制執行的 requirements.toml 策略。請參閱設定外掛市場和預設設定。

如果你將專案標記為不受信任，Codex 會跳過專案範圍內的 .codex/ 設定層，包括專案本機設定、鉤子和規則。使用者設定和系統設定仍會載入，包括使用者級/全域鉤子和規則。

有關通過 -c/--config 進行一次性覆蓋的說明（包括 TOML 引號規則），請參閱高階設定。

常用設定選項

以下是一些最常調整的選項：

預設模型

選擇 Codex 在 CLI 和 IDE 中預設使用的模型。

model = "gpt-6.1-sol"

審批提示

控制 Codex 何時在執行生成的命令之前暫停並請求核准。

approval_policy = "on-request"

有關 on-request 和 never 的行為差異，請參閱不顯示審批提示的執行方式和常見沙箱與審批組合。如果現有設定使用 approval_policy = "untrusted"，請參閱從已停用的 untrusted 審批策略遷移。

沙箱級別

調整 Codex 執行命令時對檔案系統和網路的存取權限。

sandbox_mode = "workspace-write"

有關各模式的具體行為（包括受保護的 .git、.agents、.codex 和 .aws 路徑以及網路預設設定），請參閱沙箱與審批、可寫根目錄中的受保護路徑和網路存取。

權限設定檔

Codex 還支援命名的權限設定檔，用於複用檔案系統和 網路策略。內建設定檔包括 :read-only、:workspace 和 :danger-full-access。自定義設定檔使用 [permissions.<name>] 表和 匹配的 default_permissions 值。請參閱權限。

Windows 沙箱模式

在 Windows 上，如果裝置和策略支援，請優先使用 MXC。將舊版實現設定為後備方案：

[windows]
sandbox = "elevated" # Legacy fallback

[features]
prefer_mxc = true

僅在無法進行提權設定且組織策略允許時，才使用 unelevated。有關相容性限制和推出控制選項，請參閱 Windows 沙箱指南。

網頁搜尋模式

Codex 預設在本機聊天中啟用網頁搜尋，並從網頁搜尋快取中提供結果。該快取是由 OpenAI 維護的網頁結果索引，因此快取模式傳回預先索引的結果，而不是抓取即時頁面。這可減少接觸任意即時內容中提示詞注入的機會。請將網頁結果視為不可信內容。如果你使用 --yolo 或其他完全存取權限的沙箱設定，網頁搜尋預設提供即時結果。使用 web_search 選擇模式：

• "cached"（預設）從網頁搜尋快取中提供結果。
• "indexed" 僅在搜尋索引允許請求通過時才允許存取外部網頁。
• "live" 從網頁取得最新資料（與 --search 相同）。
• "disabled" 關閉網頁搜尋工具。

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

推理強度

在模型支援時，調整其推理強度。

model_reasoning_effort = "medium"

溝通風格

要省略內建的個性指令，請設定：

personality = "none"

這會從模型的內建指令中移除 Personality 部分。 它不會更改顯式自定義的基礎指令。舊版的 friendly 和 pragmatic 值不再用於選擇風格。Codex 也不再提供 /personality 命令。

TUI 按鍵對映

在 tui.keymap 下自定義終端快捷鍵。部分輸入框操作會回退到匹配的 tui.keymap.global 按鍵繫結；如果支援特定上下文的繫結，則優先使用該繫結。空列表會解除該操作的按鍵繫結。

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

命令環境

控制 Codex 向啟動的命令傳遞哪些環境變數。使用 按變數名設定的過濾器，僅保留所需變數：

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

ignore_default_excludes 預設為 true，這會跳過自動過濾， 不再過濾名稱包含 KEY、SECRET 或 TOKEN 的變數。將其設為 false 即可啟用該自動過濾功能。有關排除規則、優先順序和 舊版設定，請參閱 Shell 環境 策略。

日誌目錄

覆蓋 Codex 寫入本機日誌檔案的位置。顯式設定 log_dir 還會 在該目錄中啟用需主動開啟的純文本 TUI 日誌 codex-tui.log。

log_dir = "/absolute/path/to/codex-logs"

對於單次執行，你也可以通過 CLI 設定：

codex -c log_dir=./.codex-log

功能開關

使用 config.toml 中的 [features] 表開啟或關閉可選功能和實驗性功能。

常用功能開關

有關生命週期鉤子的設定，請參閱鉤子。

啟用功能

• 在 config.toml 中，將 feature_name = true 新增到 [features] 下。
• 在 CLI 中執行 codex --enable feature_name。
• 要啟用多個功能，請執行 codex --enable feature_a --enable feature_b。
• 要停用某個功能，請在 config.toml 中將該鍵設為 false。