高階配置怎麼讀

Codex 的高階配置不是“把所有 key 背下來”。更可靠的做法是先分清三件事：

哪些配置影響當前會話的行為。
哪些配置會進入專案或團隊層。
哪些配置會放大安全風險。

完整 key、預設值和實驗狀態以官方 Configuration Reference 為準。本頁只負責建立閱讀順序和落地邊界。

不要把高階配置頁當成靜態手冊長期複製。模型名、feature flag、provider 引數、hook 事件和團隊配置都可能變化；教程裡只保留穩定判斷方法，具體欄位回到官方參考頁核驗。

配置參考

檢視 Codex config.toml 的完整欄位、型別和預設行為。

高階配置

檢視 profiles、project config、hooks、providers 等高階能力的官方說明。

自定義能力

理解 instructions、rules、skills、subagents 和 hooks 的分工。

高階配置的四層

先按“作用範圍”讀配置，比按字母順序讀 key 更穩。

flowchart TB
    User["User 層<br/>CODEX_HOME/config.toml"]
    Project["Project 層<br/>repo 內 .codex/config.toml"]
    Runtime["Runtime 覆蓋<br/>CLI flags / -c overrides"]
    Team["Team / System 層<br/>組織預設值、共享規則、skills"]
    Session["本次 Codex session"]

    Team --> Session
    User --> Session
    Project --> Session
    Runtime --> Session

    Project -. "只在 trusted project 載入" .-> Session
    Runtime -. "隻影響本次 invocation" .-> Session

這四層的判斷方式：

User 層適合個人長期偏好，例如預設審批策略、常用 provider、歷史記錄策略。
Project 層適合專案規則，例如 repo 內的 instructions、hooks、project-scoped defaults。
Runtime 覆蓋適合臨時實驗，例如本次換模型、本次改 sandbox、本次停用某個 feature。
Team / System 層適合組織統一規則，例如共享預設配置、團隊 skills、企業管理要求。

配置越靠近當前任務，越適合表達“本次怎麼跑”；配置越靠近團隊層，越應該表達“所有人都必須遵守什麼”。

用 profiles 管“工作模式”

Profiles 是命名配置組，適合把常用工作模式固化下來，例如輕量問答、深度審查、只讀診斷、自動化執行。

model = "your-default-model"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

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

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

啟動時選擇：

codex --profile readonly

Profile 的價值不是省幾行配置，而是降低誤操作機率。比如“只讀診斷”和“可改檔案執行”不應該靠臨場記憶區分，應該變成兩個明確的 profile。

用 `-c` 做一次性覆蓋

命令列的 -c / --config 適合臨時覆蓋配置。它不應該替代長期配置檔案。

codex -c approval_policy='"on-request"'
codex -c sandbox_mode='"read-only"'
codex -c model_reasoning_effort='"high"'

使用時注意三點：

值按 TOML 解析，字串通常需要顯式引號。
Nested key 可以用點號寫法。
臨時覆蓋適合實驗，不適合團隊規則。

把 -c 當成“本次調參”，把 config.toml 當成“長期預設值”，把專案 .codex/ 當成“這個 repo 的約束”。

Project config 要先看 trust

Codex 可以讀取專案內的 .codex/config.toml。這讓專案可以宣告自己的規則，但也帶來安全邊界問題。

repo/
  .codex/
    config.toml
    hooks.json
  AGENTS.md

Project config 的關鍵原則：

只在專案受信任時載入 project-scoped config。
越靠近當前目錄的 project config 越具體。
相對路徑會相對包含該配置的 .codex/ 目錄解析。
不要在公開儲存庫寫入個人 token、私有 endpoint、機器路徑。

專案層適合放團隊共同約束，不適合放個人偏好。個人偏好應留在 CODEX_HOME/config.toml。

Providers 先區分“改 OpenAI endpoint”還是“新增 provider”

很多人把 provider 配置寫複雜，是因為沒有先區分目標。

如果只是讓內建 OpenAI provider 走代理、router 或特定區域 endpoint，通常優先配置 OpenAI base URL，而不是新建 provider。

openai_base_url = "https://example.internal/v1"

如果你確實要接入額外模型服務，再定義 model_providers.<id>：

model_provider = "proxy"

[model_providers.proxy]
name = "Internal OpenAI-compatible proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"

Provider 配置的風險點：

base_url 會改變請求去向，必須確認資料邊界。
env_key 只引用環境變數名，不要把金鑰寫進配置。
自定義 header 可能洩露內部資訊，公開儲存庫要避擴音交。
企業或團隊環境應優先使用組織批准的 endpoint。

Hooks 是自動化，不是裝飾

Hooks 會在 Codex 生命週期的特定事件上執行命令。它們適合做檢查、記錄、策略判斷，但不適合塞入不透明的大型流程。

[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/usr/local/bin/check-codex-command"
timeout = 30

寫 hooks 前先問四個問題：

這個 hook 是否必須自動執行。
失敗時是否會阻斷關鍵流程。
輸出是否會暴露敏感路徑、token 或使用者資料。
團隊成員是否能快速理解它為什麼存在。

Hooks 一旦進入 project 層，就會影響所有使用該 repo 的人。規則越強，說明文件越要清楚。

Rules、instructions、skills、subagents 的分工

高階配置經常和自定義能力混在一起。可以用下面這張圖判斷職責：

flowchart LR
    Goal["任務目標"] --> Instructions["Instructions / AGENTS.md<br/>告訴 Codex 怎麼做"]
    Instructions --> Tools["Tools / MCP / shell<br/>讓 Codex 能行動"]
    Instructions --> Skills["Skills<br/>複用穩定流程"]
    Instructions --> Subagents["Subagents<br/>拆分角色或並行任務"]
    Tools --> Verification["驗證結果"]
    Skills --> Verification
    Subagents --> Verification

選擇方式：

穩定規則寫進 instructions。
高頻流程沉澱為 skill。
需要不同角色或並行處理時使用 subagents。
涉及工具呼叫前後的硬性策略時考慮 hooks。
隻影響一次任務的偏好用命令列覆蓋。

不要把所有東西都塞進一個配置檔案。可維護性來自邊界清楚，而不是欄位數量多。

安全檢查清單

改高階配置前，至少檢查這些點：

是否把金鑰、token、內部 URL 寫進了 repo。
是否把 sandbox 或 approval 調得過鬆。
是否讓 project hooks 在未充分說明的情況下自動執行。
是否把個人機器路徑寫成團隊預設值。
是否複製了會隨版本變化的模型、價格、限制或 feature flag 列表。
是否能用官方 Configuration Reference 解釋每個關鍵欄位。

配置變更的驗收方式

高階配置改完以後，不要只看 Codex 能不能啟動。商業專案要驗證三件事：只讀模式是否真的不能寫檔案，常規實現模式是否只能修改預期 workspace，自動化模式是否不會請求人工輸入。只要這三件事沒有驗過，配置就還停留在“看起來能用”的階段。

團隊還應保留一份最小回復路徑。配置變更如果影響 provider、hooks、sandbox、approval 或 project config，必須知道怎樣退回上一版預設值。這樣即使某個 hook 寫錯、某個 provider endpoint 不通，團隊也能快速恢復工作，而不是讓所有 agent 會話同時失敗。