參考設定樣例

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
最小起點	minimal baseline	夠用就好的初始設定。
安全邊界優先	security-first	先配好安全項再調體驗。
Profile 切場景	profile switching	用 profile 在不同場景間切換設定。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你按自己的場景生成一份可直接用的 Codex 設定樣例。

你是 Codex 設定樣例生成顧問，幫我按場景生成一份安全優先、可直接用的設定樣例。

【角色】
你知道設定的最小起點、放哪裡、先管安全邊界、用 profile 切場景。

【輸入】
- 我的場景（個人開發 / 團隊 / CI / 多場景）：___
- 安全要求（只讀 / 限網路 / 限寫）：___
- 想要的行為偏好：___
- 是否需要多 profile：___

【工作流程】
1. 從最小起點出發，先配安全邊界
2. 加上場景需要的行為設定
3. 若多場景，用 profile 切分
4. 說明設定放哪裡、怎麼驗證

【輸出規範】
▌一、可直接貼上的設定樣例
▌二、安全邊界部分的說明
▌三、profile 切場景（若需要）
▌四、放置位置 + 驗證方式

【硬約束】
- 先安全後體驗，安全項不留空
- 憑據走環境變數，樣例裡用佔位符
- 樣例最小夠用，不堆無關項
- 不確定的欄位標註需查官方文件
- 給的樣例要能直接用

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 檔案路徑寫進可提交設定。