Codex config.toml 配置教程：模型、权限、搜索与 Profile

Codex 使用 TOML 配置文件保存长期设置。最常见位置：

~/.codex/config.toml

项目级配置：

<repo>/.codex/config.toml

CLI 与 IDE 扩展共享相同配置层。项目级配置只有在项目被信任时才会加载。

1. 创建用户配置

mkdir -p ~/.codex
$EDITOR ~/.codex/config.toml

一个适合本地开发的基础配置：

model = "gpt-5.6"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

模型目录会更新。若配置中的模型不可用，使用 /model 查看当前账户可选项并更新。

2. 配置优先级

官方配置基础页面给出的核心优先级，从高到低：

CLI 参数和 --config 覆盖；
项目 .codex/config.toml，离当前目录最近的优先；
--profile 选择的 Profile 文件；
用户配置 ~/.codex/config.toml；
Unix 系统配置 /etc/codex/config.toml；
内置默认值。

例如用户配置：

model_reasoning_effort = "medium"

单次运行覆盖：

codex -c model_reasoning_effort="high"

这次运行使用 high，不会修改配置文件。

3. 默认模型

model = "gpt-5.6"

一次性覆盖：

codex --model gpt-5.6

交互界面：

/model

教程网站不应简单写“永远选择某个模型”，应按任务类型说明选择原则。

4. 推理等级

model_reasoning_effort = "high"

5. 批准策略

approval_policy = "on-request"

它决定 Codex在什么情况下暂停并向用户请求批准。

常见策略：

untrusted；
on-request；
never。

never 表示不弹出交互批准，不代表取消沙箱。自动化时如果命令无法在沙箱内运行，任务可能直接失败。

6. 沙箱模式

sandbox_mode = "workspace-write"

常见模式：

read-only：可读取但不写入；
workspace-write：可在工作区和允许的根目录写入；
danger-full-access：取消 Codex 文件系统限制，风险很高。

推荐组合：

代码解释或审查：

approval_policy = "on-request"
sandbox_mode = "read-only"

日常开发：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

不要把 danger-full-access 作为个人电脑默认配置。

7. Web 搜索模式

当前官方配置说明包含：

web_search = "cached"

可选方向包括：

cached：使用预索引缓存结果，默认更安全；
indexed：通过索引门控外部访问；
live：获取最新页面；
disabled：禁用搜索。

需要最新库文档或版本信息时可使用 live 或命令行搜索模式，但外部内容必须视为不可信输入。

8. Shell 环境变量策略

减少把敏感环境变量传给模型生成的命令：

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

项目需要特定变量时，逐项添加，而不是默认暴露完整 Shell 环境。

不要把 Secret 值直接写入项目级配置。自动化 Secrets 应由 CI Secret 管理注入。

9. 日志目录

需要排查 CLI 问题时：

log_dir = "/absolute/path/to/codex-logs"

单次开启：

RUST_LOG=debug codex -c log_dir=./.codex-log

查看日志：

tail -F ./.codex-log/codex-tui.log

日志可能包含文件路径、命令和任务上下文，不能随意公开上传。

10. Feature Flags

在 [features] 中启用或禁用可选能力：

[features]
multi_agent = true
hooks = true
memories = false

命令行启用：

codex --enable multi_agent

禁用：

codex --disable multi_agent

实验功能可能变化，不应在关键生产流程中无评估启用。

11. Windows 配置

原生 Windows 推荐：

[windows]
sandbox = "elevated"

无法使用管理员权限时：

[windows]
sandbox = "unelevated"

WSL2 使用 Linux 沙箱路径，通常需要 bubblewrap。

12. Profile 配置

Codex 新版 Profile 使用独立文件。

基础配置：

~/.codex/config.toml

深度审查 Profile：

~/.codex/deep-review.config.toml

内容：

model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"
web_search = "disabled"

运行：

codex --profile deep-review

自动化 Profile：

# ~/.codex/ci.config.toml
approval_policy = "never"
sandbox_mode = "workspace-write"
web_search = "disabled"

codex exec --profile ci "Run the requested repository checks"

官方高级配置说明提醒：较新的 Codex 版本不再从 config.toml 中读取旧式 [profiles.name] 表，应迁移到独立 Profile 文件。

13. 项目级配置

仓库中创建：

mkdir -p .codex
$EDITOR .codex/config.toml

示例：

model_reasoning_effort = "high"
web_search = "disabled"

项目级配置适合团队共享任务行为，但不适合保存机器本地 provider、认证、通知和遥测等配置。官方配置参考会忽略部分敏感或主机级键在项目配置中的覆盖。

14. 一份推荐个人配置

# ~/.codex/config.toml

model = "gpt-5.6"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"

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

[features]
multi_agent = true
hooks = true
memories = false

根据当前版本和账户能力删除不支持的项。