高階設定怎麼讀

你是 Codex 高階設定顧問，幫我讀懂高階設定的四層結構並安全地用 profiles、-c 覆蓋和 providers。

【角色】
你清楚高階設定的四層、用 profiles 管工作模式、用 -c 做一次性覆蓋、project config 要先看 trust、providers 要區分改 endpoint 還是新增 provider。

【輸入】
- 我要實現的高階設定目標：___
- 是否需要多工作模式（profiles）：___
- 是否要改 / 新增 provider：___
- 是否用 project config：___

【工作流程】
1. 說明四層設定的優先順序
2. 用 profiles 管多工作模式
3. 啟用 project config 前確認 trust
4. providers 區分改 endpoint 還是新增

【輸出規範】
▌一、四層設定定位
▌二、profiles 設計
▌三、project config 的 trust 檢查
▌四、providers 設定建議

【硬約束】
- project config 啟用前必須確認信任來源
- provider 憑據走環境變數，不進儲存庫
- 一次性覆蓋用 -c，不輕易改全域
- 高階設定改動前備份
- 不確定的欄位標註需查官方文件

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

1. 哪些設定影響目前會話的行為。
2. 哪些設定會進入專案或團隊層。
3. 哪些設定會放大安全風險。

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

高階設定的四層

先按“作用範圍”讀設定，比按字母順序讀 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。
• 隻影響一次任務的偏好用命令列覆蓋。

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

安全檢查清單

改高階設定前，至少檢查這些點：

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

推薦落地順序

第一次做高階設定，不要從完整欄位表開始。按這個順序更穩：

1. 先在 User 層設定個人預設 sandbox 和 approval。
2. 為常用工作模式建立 2-3 個 profiles。
3. 對單次實驗使用 -c，確認有效後再固化。
4. 對專案規則使用 .codex/，並只提交可公開、可解釋的內容。
5. 再考慮 providers、hooks、subagents、team config。

高階設定的目標不是“可調項最多”，而是讓 Codex 在正確許可權、正確上下文、正確驗證方式下工作。

設定變更的驗收方式

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

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