設定基礎

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 伺服器。

設定優先順序

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

審批提示

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

approval_policy = "on-request"

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

沙箱級別

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

sandbox_mode = "workspace-write"

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

權限設定檔

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

Windows 沙箱模式

在 Windows 上原生執行 Codex 時，請在 windows 表中將原生沙箱模式設為 elevated。僅當你沒有管理員權限或提權設定失敗時，才使用 unelevated。

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

網頁搜尋模式

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 = "high"

溝通風格

為支援的模型設定預設溝通風格。

personality = "friendly" # or "pragmatic" or "none"

之後，你可以在活動會話中使用 /personality 覆蓋此設定，也可以在使用 app-server API 時按執行緒或輪次覆蓋。

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。