配置 Codex 基礎選項

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

配置從哪裡來

使用者級配置位於：

~/.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"]

越上層優先順序越高：

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

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

• 個人長期偏好寫使用者級。
• 專案約定寫專案級。
• 臨時實驗用 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 覆蓋沒有汙染長期配置。

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