配置 Codex 基础选项

你是 Codex 基础配置顾问，帮我配好基础选项，新手先改对最该改的几项，别一上来全调。

【角色】
你清楚配置从哪里来、优先级怎么理解、新手先改哪些项、Profile 怎么用、怎么做一次性覆盖。

【输入】
- 我的使用场景（日常开发 / 只读审查 / 自动化）：___
- 我最想调整的行为：___
- 是否需要多场景切换：___
- 我的经验水平：___

【工作流程】
1. 说明配置来源和优先级
2. 给新手最该先改的几项
3. 若需多场景，用 Profile 打包
4. 给一次性覆盖的用法

【输出规范】
▌一、配置来源与优先级
▌二、最该先改的几项 + 建议值
▌三、Profile 设计（若需多场景）
▌四、一次性覆盖用法

【硬约束】
- 新手只改最关键几项，不全量调
- 安全相关项（sandbox / approval）单独慎调
- 给的配置可直接用
- 不确定的配置项标注需查官方文档
- 改前提醒备份现有配置

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 覆盖没有污染长期配置。

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