參考配置樣例

config.toml 是 Codex 的長期偏好檔案。它適合放模型預設值、沙箱、審批、MCP、profile 和少量 UI 行為。

配置樣例不是推薦你照抄。模型名、provider、feature flags 和許可權策略都應按當前官方文件、組織要求和專案風險決定。

Config basics

先理解配置載入位置、優先順序和 trust 邊界。

Config reference

完整 key 去參考頁查，不要複製巨型配置。

Sandbox boundaries

配置最重要的是許可權邊界，而不是功能堆疊。

解決什麼

flowchart LR
    Need["repeated behavior"] --> Config["config.toml"]
    Config --> Session["consistent sessions"]
    Session --> Verify["status / small task"]

配置檔案解決的是“每次開啟 Codex 都希望行為一致”的問題：

預設用哪個模型。
預設是否能改檔案。
什麼時候需要批准命令。
專案級規則和個人習慣如何分開。
哪些 MCP 或工具預設可用。

不要把配置檔案當成“功能大全”。配置越多，排查越難。

最小起點

先從最小可解釋配置開始：

model = "your-current-codex-model"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

含義：

model：預設模型。寫入前查官方 Models 或組織模型策略。
approval_policy = "on-request"：越過邊界時詢問。
sandbox_mode = "workspace-write"：允許在工作區內讀寫，仍保留邊界。

這比 danger-full-access 更適合真實專案，也比純 read-only 更適合日常開發。

配置放哪裡

使用者級 ~/.codex/config.toml：

個人預設模型。
個人 UI 偏好。
個人常用 MCP。
不依賴某個儲存庫的習慣。

專案級 .codex/config.toml：

當前儲存庫的預設 sandbox。
當前儲存庫需要的 MCP。
當前儲存庫特定 profile。
團隊希望共享的行為。

命令列引數和 --config 只適合一次性覆蓋，不適合長期偏好。

先管安全邊界

配置裡最重要的是兩類：

sandbox_mode：Codex 能訪問和修改哪裡。
approval_policy：Codex 什麼時候停下來問你。

常見組合：

保守分析：read-only + on-request。
日常開發：workspace-write + on-request。
高風險全開：danger-full-access + never。

新手不要把高風險全開寫進預設配置。只有在一次性、可信、可回復的自動化環境中，才考慮這種組合。

Profile 切場景

如果有多個固定場景，用 profile，不要反覆改同一份配置。

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

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

這樣可以把只讀審查和動手開發分開。最常見的問題就是在該只讀的時候用了動手模式。

不急著配置的項

這些配置官方支援，但新手不必急著寫：

自定義 model provider。
複雜網路許可權 profile。
OTEL / telemetry。
hooks。
自動審批 reviewer。
大量 MCP server。
自定義 compaction prompt。

等遇到真實問題，再加對應配置。配置應該來自痛點，不應該來自“看起來專業”。

怎麼判斷生效

改完配置後，用 /status 或啟動後的狀態資訊確認：

當前模型是否符合預期。
sandbox 是否是你想要的模式。
approval policy 是否生效。
專案級配置是否被載入。

再用小任務驗證：讀檔案、改一個測試檔案、執行 git status。看它是否在該問你的時候問你，在不該越界時保持邊界。

常見坑

整份複製配置樣例，結果不知道哪個鍵影響行為。
把個人偏好寫進專案級配置，汙染團隊儲存庫。
專案級配置寫好後忘記 trust project，導致它沒載入。
預設使用 danger-full-access。
配了 MCP 或 provider，卻沒有配置憑據來源。
把金鑰、token 或 auth 檔案路徑寫進可提交配置。