查詢完整配置項
用官方 Configuration Reference 和 JSON schema 查詢 Codex 配置項，不把高頻變化的長表硬搬進教程。
這篇不是配置欄位大全的複製件。Codex 配置項變化很快，完整欄位以官方 Configuration Reference 和 config-schema.json 為準；本頁只講怎麼查、怎麼分層、哪些配置改錯會直接影響安全。
Codex 的配置入口主要圍繞兩個檔案：使用者級 ~/.codex/config.toml 和受信任專案裡的 .codex/config.toml。官方說明裡有一個關鍵前提：專案級配置只會在你信任該專案後載入。也就是說，配置不是“哪裡有檔案就一定生效”，而是和專案信任狀態繫結。
flowchart TB
Need[你要改行為] --> Scope{先判斷作用域}
Scope --> User[使用者級<br/>~/.codex/config.toml]
Scope --> Project[專案級<br/>.codex/config.toml]
Project --> Trust[只在 trusted project 後載入]
User --> Risk{是否影響安全}
Trust --> Risk
Risk --> Safe[普通偏好<br/>主題 / 通知 / file_opener]
Risk --> Guard[安全邊界<br/>sandbox / approval / network / permissions]
Guard --> Docs[先查官方安全頁和 schema]
Safe --> Schema[查 config-schema.json]先查這三個官方入口
Configuration Reference
完整欄位、型別和說明以官方配置參考為準。
Config basics
先看配置檔案放哪裡、如何生效、如何寫最小配置。
Advanced Config
再看 profile、project-scoped config、sandbox、approval 和高階覆蓋。
config-schema.json
編輯器補全和機器校驗用官方 JSON schema，不手抄欄位表。
配置項應該按職責查
不要從長表第一行掃到最後一行。先判斷你要改的是哪一類行為：
- 模型和 provider：
model、review_model、model_provider、model_providers.*、openai_base_url。 - 沙箱和審批：
sandbox_mode、approval_policy、sandbox_workspace_write.*、default_permissions、permissions.*。 - 專案規則：
project_root_markers、project_doc_max_bytes、project_doc_fallback_filenames。 - MCP：
mcp_servers.*、OAuth、headers、tool allow / deny list、timeout。 - Skills、apps、connectors：
skills.config、apps.*、tool_suggest.*。 - TUI 和體驗：
tui.*、file_opener、notify、personality、service_tier。 - 記憶、subagents、後臺狀態：
memories.*、agents.*、sqlite_home、history.*。 - 監控：
otel.*、analytics.enabled、feedback.enabled。 - 企業約束：
requirements.toml和 managed configuration。
安全相關配置不要孤立看
approval_policy、sandbox_mode、sandbox_workspace_write.network_access 不能只看欄位說明。它們共同決定 Codex 能不能寫檔案、能不能訪問網路、什麼時候停下來讓你確認。
官方安全頁把這條線拆成兩層：
sandbox_mode決定 Codex 技術上能做什麼，例如能寫哪裡、能不能訪問網路。approval_policy決定 Codex 什麼時候必須先問你，例如越過 sandbox、訪問網路或執行不受信任命令。
預設更穩的理解是：本地 CLI / IDE extension 依賴 OS sandbox；Cloud 執行在 OpenAI 管理的隔離容器裡；網路預設關閉，除非你顯式啟用。
# 保守本地自动化基线：能在工作区内执行，但越界要问
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# 只有明确需要联网命令时才开启
[sandbox_workspace_write]
network_access = falsedanger-full-access 或 --yolo 不是“高階模式”，而是取消 sandbox 和 approval 的高風險模式。只有在你信任儲存庫、任務和執行環境時才考慮，並且要先準備好 Git 回復點。
編輯器補全怎麼配
官方提供 config-schema.json。在 VS Code、Cursor 或支援 TOML schema 的編輯器裡，可以把下面這行放到 config.toml 頂部，讓編輯器直接按官方 schema 做補全和診斷：
#:schema https://developers.openai.com/codex/config-schema.json這比複製教程裡的欄位表更可靠。欄位新增、棄用、改名時，schema 和官方參考頁才是事實源。
改配置前的檢查清單
- 先判斷作用域：這是個人預設行為，還是隻應該屬於當前專案。
- 先查官方 reference：確認欄位名、型別、預設值和是否棄用。
- 安全欄位必須同時查 Agent approvals & security。
- 不把 API key、token、workspace id 等敏感資訊硬寫進配置示例。
- 改完執行
/status或/debug-config，確認實際生效層級。 - 團隊環境優先用 managed configuration 或
requirements.toml約束風險欄位。
官方資料
- Configuration Reference：https://developers.openai.com/codex/config-reference
- Config basics：https://developers.openai.com/codex/config-basic
- Advanced Config：https://developers.openai.com/codex/config-advanced
- Agent approvals & security：https://developers.openai.com/codex/agent-approvals-security
- Managed configuration：https://developers.openai.com/codex/enterprise/managed-configuration