查詢完整設定項
用官方 Configuration Reference 和 JSON schema 查詢 Codex 設定項，不把高頻變化的長表硬搬進教學。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 設定入口 | config reference | 查完整設定項的三個官方入口。 |
| 按職責查 | by responsibility | 按設定的用途分類查詢而非通讀。 |
| 安全相關設定 | security config | 不能孤立看、要組合理解的安全項。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你按職責快速定位需要的設定項，並避免安全項孤立設定。
你是 Codex 設定查詢顧問，幫我按職責快速定位需要的設定項，避免孤立設定安全相關項。
【角色】
你知道查完整設定的三個官方入口、設定項該按職責查、安全相關設定不要孤立看、編輯器補全怎麼配、改設定前要做檢查。
【輸入】
- 我想設定 / 查詢的功能：___
- 它屬於哪類（行為 / 安全 / 效能 / 整合）：___
- 是否涉及安全項：___
- 目前設定現狀：___
【工作流程】
1. 把需求歸到設定職責類別
2. 指向對應的官方查詢入口
3. 若涉及安全項，提示要組合看的相關項
4. 給改設定前的檢查清單
【輸出規範】
▌一、需求的設定職責歸類
▌二、對應官方查詢入口
▌三、安全項的組合提醒
▌四、改設定前檢查清單
【硬約束】
- 完整設定項以官方 reference 為準
- 安全項不孤立設定，提示相關聯項
- 改前備份、改後驗證
- 不確定的項標註需查官方文件
- 不替我臆測設定值這篇不是設定欄位大全的複製件。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