查询完整配置项
用官方 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