設定基礎

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

Codex 設定檔

Codex 會把使用者級設定儲存在 ~/.codex/config.toml。如果你想讓某些設定只作用於特定專案或子目錄，可以在儲存庫中新增 .codex/config.toml。

如果你想從 Codex IDE 擴充套件中直接開啟設定檔，請點選右上角的齒輪圖示，然後選擇 Codex Settings > Open config.toml（Codex 設定 > 開啟 config.toml）。

CLI 和 IDE 擴充套件共享同一套設定層。你可以用它們統一設定：

• 預設模型與提供方
• 審批策略與沙箱設定
• MCP servers

設定優先順序

Codex 會按以下順序解析設定值，優先順序從高到低依次為：

1. CLI flag 與 --config 覆蓋

2. 專案級設定檔 .codex/config.toml

   Codex 會從專案根目錄一路遍歷到當前工作目錄，越接近當前目錄的檔案優先順序越高；僅可信專案會載入這一層。

3. 通過 --profile profile-name 選擇的設定檔檔案，即 ~/.codex/profile-name.config.toml

4. 使用者級設定 ~/.codex/config.toml

5. 系統級設定（如果存在），例如 Unix 上的 /etc/codex/config.toml

6. 內建預設值

可以利用這一優先順序規則：把共享預設值放在 config.toml 中，把設定檔檔案聚焦在那些真正有差異的設定上。

如果你把某個專案標記為不可信，Codex 會跳過專案作用域下的 .codex/ 設定層，包括專案本機設定、鉤子和規則。使用者級和系統級設定仍會載入，其中也包括使用者 / 全域鉤子和規則。

關於通過 -c / --config 執行一次性覆蓋的細節，包括 TOML 引號規則，參見 高階設定。

常見設定項

下面是最常被修改的一組設定項：

預設模型

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

model = "gpt-5.6"

審批提示

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

approval_policy = "on-request"

關於 untrusted、on-request 和 never 三種模式的行為差異，參見在不彈出審批提示的情況下執行和常見的沙箱與審批組合。

沙箱級別

調整 Codex 在執行命令時能夠獲得多少檔案系統與網路存取權限。

sandbox_mode = "workspace-write"

關於不同模式的具體行為，包括受保護的 .git / .codex 路徑與預設網路存取行為，參見沙箱與審批、可寫根目錄中的受保護路徑和網路存取。

權限設定檔

Codex 也支援命名權限設定檔，用來復用檔案系統和網路策略。內建設定檔包括 :read-only、:workspace 和 :danger-full-access。自定義設定檔使用 [permissions.<name>] 表，並配套設定同名 default_permissions。參見權限。

Windows 沙箱模式

如果你在 Windows 原生環境中執行 Codex，可在 windows 表中把原生沙箱模式設定為 elevated。只有在你沒有管理員權限，或者 elevated 模式初始化失敗時，才建議使用 unelevated。

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

Web 搜尋模式

Codex 預設會為本機聊天啟用 Web 搜尋，並從 Web 搜尋快取返回結果。這個快取是 OpenAI 維護的網頁索引，因此 cached 模式返回的是預先索引好的結果，而不是即時抓取頁面。這樣能降低暴露在任意即時網頁提示詞注入下的風險，但你仍然應該把 Web 結果視為不可信輸入。如果你使用 --yolo 或其他完全存取沙箱設定，Web 搜尋會預設切換為 live 結果。你可以通過 web_search 選擇模式：

• "cached"（預設）：使用 Web 搜尋快取，不存取外部網路。
• "indexed"：只有搜尋索引放行請求時，才允許存取外部 Web。
• "live"：抓取最新資料，與 CLI 的 --search 等價。
• "disabled"：關閉 Web 搜尋工具。

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）的模型設定預設溝通風格。

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

你也可以在活動會話裡通過 /personality 覆蓋這個設定；如果你使用 App Server API，也可以按對話執行緒 / 會話輪次級別覆蓋。

TUI 快捷鍵對映

可以在 tui.keymap 下自定義終端快捷鍵。部分 composer 動作會回退到匹配的 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] 表來切換可選功能和實驗效能力。

常用功能開關

生命週期 hook 設定請參見 Hooks。

啟用功能開關

• 在 config.toml 裡新增：

  [features]
  feature_name = true

• 使用 CLI：

  codex --enable feature_name

• 一次啟用多個功能：

  codex --enable feature_a --enable feature_b

• 若要停用，把 config.toml 中對應項設為 false。

來源：</zh-TW/docs/config-file/config-basic> 更新時間：2026-07-10（UTC）