設定 Codex 基礎選項

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
設定優先順序	config precedence	多來源設定衝突時誰生效。
Profile	設定檔	一組打包的設定，按場景切換。
一次性覆蓋	one-off override	用命令列臨時覆蓋某項設定。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你配好 Codex 基礎選項，先改對最該改的幾項。

你是 Codex 基礎設定顧問，幫我配好基礎選項，新手先改對最該改的幾項，別一上來全調。

【角色】
你清楚設定從哪裡來、優先順序怎麼理解、新手先改哪些項、Profile 怎麼用、怎麼做一次性覆蓋。

【輸入】
- 我的使用場景（日常開發 / 只讀審查 / 自動化）：___
- 我最想調整的行為：___
- 是否需要多場景切換：___
- 我的經驗水平：___

【工作流程】
1. 說明設定來源和優先順序
2. 給新手最該先改的幾項
3. 若需多場景，用 Profile 打包
4. 給一次性覆蓋的用法

【輸出規範】
▌一、設定來源與優先順序
▌二、最該先改的幾項 + 建議值
▌三、Profile 設計（若需多場景）
▌四、一次性覆蓋用法

【硬約束】
- 新手只改最關鍵幾項，不全量調
- 安全相關項（sandbox / approval）單獨慎調
- 給的設定可直接用
- 不確定的設定項標註需查官方文件
- 改前提醒備份現有設定

Codex 設定不是“偏好設定合集”，而是模型、許可權、工具、網路和團隊治理的控制面。新手只需要先掌握載入順序和安全邊界。

不要複製一整份別人機器上的 config.toml。先寫最小設定，再按任務增加模型、許可權、MCP、環境變數和 profile。

Config basics

官方基礎設定入口，確認載入位置和優先順序。

Advanced config

需要 profile、-c 覆蓋和 provider 時再讀高階設定。

Config reference

查完整 key 時看參考頁，不把完整表格塞進基礎教學。

設定從哪裡來

使用者級設定位於：

~/.codex/config.toml

專案級設定位於：

.codex/config.toml

CLI 和 IDE extension 共享同一套設定層。IDE 裡可以從設定入口開啟 config.toml，CLI 則直接讀 CODEX_HOME 下的設定。

專案級 .codex/ 只有在你 trust the project 後才載入。未信任專案會跳過專案本地 config、hooks 和 rules，但使用者級、系統級設定仍會載入。

優先順序怎麼理解

flowchart TD
    Flags["CLI flags / --config"] --> Profile["--profile values"]
    Profile --> Project["trusted .codex/config.toml"]
    Project --> User["~/.codex/config.toml"]
    User --> System["/etc/codex/config.toml"]
    System --> BuiltIn["built-in defaults"]

越上層優先順序越高：

CLI flags 和 --config 覆蓋項。
--profile <name> 選中的 profile 值。
受信任專案裡的 .codex/config.toml，越靠近目前目錄越優先。
使用者設定 ~/.codex/config.toml。
系統設定，例如 Unix 上的 /etc/codex/config.toml。
內建預設值。

這個順序決定了設定寫在哪裡：

個人長期偏好寫使用者級。
專案約定寫專案級。
臨時實驗用 CLI flag 或 --config。
團隊受控機器用系統級或 managed configuration。

新手先改哪些項

先改穩定、低風險、影響清楚的項。

模型

模型名變化快，不要把教學裡的示例當成長期推薦。寫設定前查官方 Models 或組織內部模型目錄。

model = "your-current-codex-model"

如果團隊有統一模型策略，把預設值放在使用者級或系統級，不要在每個專案裡散落一份。

審批策略

approval_policy 決定 Codex 什麼時候暫停並向你請求確認。

approval_policy = "on-request"

新手預設保留可審批路徑。只有隔離 CI、一次性審查或受管理環境裡，才考慮更激進的策略。

沙箱

sandbox_mode 控制檔案系統和網路訪問。

sandbox_mode = "workspace-write"

基礎原則：

讀程式碼、審查 diff、寫報告：只讀。
修改儲存庫內檔案：workspace-write。
訪問網路或系統路徑：明確任務、明確驗證、明確隔離。
全許可權：只放在你能重建的臨時環境裡。

MCP 和外部工具

MCP server 是外部上下文和外部動作入口。先啟用必要工具，再逐個驗證：

server 能啟動。
超時合理。
token 不進儲存庫。
工具輸出被當作不可信輸入。
寫入型工具有審批或環境隔離。

命令環境

用 shell_environment_policy 控制命令能拿到哪些環境變數。

[shell_environment_policy]
include_only = ["PATH", "HOME"]

不要預設把所有環境變數轉發給模型生成的命令，尤其是雲服務 key、資料庫地址和私有 token。

Profile 怎麼用

Profile 適合儲存“同一個人不同任務”的設定組合。例如：

只讀審查。
本地小修復。
深度 review。
隔離 CI 自動化。

不要為每篇教學、每個目錄都建 profile。profile 數量越多，越難判斷目前會話到底用了什麼策略。

示意寫法：

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.local-fix]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

臨時執行：

codex --profile readonly

一次性覆蓋

短期實驗優先用 CLI flag。沒有專門 flag 時，用 -c 或 --config 覆蓋任意 key：

codex --config sandbox_workspace_write.network_access=true

注意 --config 的值按 TOML 解析，不是 JSON。字串和陣列需要正確引用；寫不準時先在一次性命令裡驗證，不要直接寫進全域設定。

基礎設定驗收

目前會話能說清用了哪一層設定。
專案未信任時不會載入專案 .codex/。
sandbox 和 approval 符合任務風險。
模型名來自官方或組織目前策略，不來自舊教學複製。
MCP token、API key、訪問權杖沒有寫進儲存庫。
命令環境沒有預設洩露全部環境變數。
臨時 --config 覆蓋沒有汙染長期設定。

設定越基礎，越要少寫。最小設定跑穩後，再把真實重複需求沉澱進去。

設定 Codex 基礎選項

Config basics

Advanced config

Config reference

本頁目錄