配置 Codex 基础选项

Codex 配置不是“偏好设置合集”，而是模型、权限、工具、网络和团队治理的控制面。新手只需要先掌握加载顺序和安全边界。

配置从哪里来

用户级配置位于：

~/.codex/config.toml

项目级配置位于：

.codex/config.toml

CLI 和 IDE extension 共享同一套配置层。IDE 里可以从设置入口打开 config.toml，CLI 则直接读 CODEX_HOME 下的配置。

项目级 .codex/ 只有在你 trust the project 后才加载。未信任项目会跳过项目本地 config、hooks 和 rules，但用户级、系统级配置仍会加载。

优先级怎么理解

flowchart TD
    Flags["CLI flags / --config"] --> Profile["--profile values"]
    Profile --> Project["trusted .codex/config.toml"]
    Project --> User["~/.codex/config.toml"]
    User --> System["/etc/codex/config.toml"]
    System --> BuiltIn["built-in defaults"]

越上层优先级越高：

1. CLI flags 和 --config 覆盖项。
2. --profile <name> 选中的 profile 值。
3. 受信任项目里的 .codex/config.toml，越靠近当前目录越优先。
4. 用户配置 ~/.codex/config.toml。
5. 系统配置，例如 Unix 上的 /etc/codex/config.toml。
6. 内置默认值。

这个顺序决定了配置写在哪里：

• 个人长期偏好写用户级。
• 项目约定写项目级。
• 临时实验用 CLI flag 或 --config。
• 团队受控机器用系统级或 managed configuration。

新手先改哪些项

先改稳定、低风险、影响清楚的项。

模型

模型名变化快，不要把教程里的示例当成长期推荐。写配置前查官方 Models 或组织内部模型目录。

model = "your-current-codex-model"

如果团队有统一模型策略，把默认值放在用户级或系统级，不要在每个项目里散落一份。

审批策略

approval_policy 决定 Codex 什么时候暂停并向你请求确认。

approval_policy = "on-request"

新手默认保留可审批路径。只有隔离 CI、一次性审查或受管理环境里，才考虑更激进的策略。

沙箱

sandbox_mode 控制文件系统和网络访问。

sandbox_mode = "workspace-write"

基础原则：

• 读代码、审查 diff、写报告：只读。
• 修改仓库内文件：workspace-write。
• 访问网络或系统路径：明确任务、明确验证、明确隔离。
• 全权限：只放在你能重建的临时环境里。

MCP 和外部工具

MCP server 是外部上下文和外部动作入口。先启用必要工具，再逐个验证：

• server 能启动。
• 超时合理。
• token 不进仓库。
• 工具输出被当作不可信输入。
• 写入型工具有审批或环境隔离。

命令环境

用 shell_environment_policy 控制命令能拿到哪些环境变量。

[shell_environment_policy]
include_only = ["PATH", "HOME"]

不要默认把所有环境变量转发给模型生成的命令，尤其是云服务 key、数据库地址和私有 token。

Profile 怎么用

Profile 适合保存“同一个人不同任务”的配置组合。例如：

• 只读审查。
• 本地小修复。
• 深度 review。
• 隔离 CI 自动化。

不要为每篇教程、每个目录都建 profile。profile 数量越多，越难判断当前会话到底用了什么策略。

示意写法：

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

[profiles.local-fix]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

临时运行：

codex --profile readonly

一次性覆盖

短期实验优先用 CLI flag。没有专门 flag 时，用 -c 或 --config 覆盖任意 key：

codex --config sandbox_workspace_write.network_access=true

注意 --config 的值按 TOML 解析，不是 JSON。字符串和数组需要正确引用；写不准时先在一次性命令里验证，不要直接写进全局配置。

基础配置验收

• 当前会话能说清用了哪一层配置。
• 项目未信任时不会加载项目 .codex/。
• sandbox 和 approval 符合任务风险。
• 模型名来自官方或组织当前策略，不来自旧教程复制。
• MCP token、API key、访问令牌没有写进仓库。
• 命令环境没有默认泄露全部环境变量。
• 临时 --config 覆盖没有污染长期配置。

配置越基础，越要少写。最小配置跑稳后，再把真实重复需求沉淀进去。