别再用 Codex 默认配置了！深度优化 Codex 工作流的进阶配置指南

摘要：Codex 的 config.toml 字段已突破 90 余个，绝大多数用户却仍停留在”毛坯版”默认配置上。本文系统梳理 Codex 配置文件结构、优先级、Profile 分模式、沙箱审批策略、第三方模型接入以及可视化配置工具，帮你把 Codex 真正改造成贴合个人工作流的 AI 编程助手。无论你是想用 DeepSeek、QCode.cc 这类第三方网关降本，还是想在规划阶段调用顶级模型、执行阶段切到便宜模型提效，读完这篇都能少走弯路。

一、为什么你必须抛弃 Codex 默认配置

随着 Codex 功能迭代提速，配置文件字段数量也在持续膨胀，目前不完全统计已超过 90 余个。手动维护这些 TOML 文件确实繁琐，但全用默认配置意味着你用的只是”毛坯版”的 Codex，而不是真正为你的工作流量身定制的 AI 编程助手。

合理的配置能带来的优化空间巨大：你可以针对不同工作流切换不同推理模式；可以让规划阶段调用顶级模型做决策、执行阶段切换到更快更便宜的开源模型降低成本；可以精细控制沙箱边界和审批策略；还可以接入 DeepSeek、QCode.cc 等第三方模型接口绕开官方额度限制。这一进一出，效率和开销都能同时优化。

二、Codex 配置文件位置与目录结构

Codex 的本地状态默认都放在 CODEX_HOME 下，默认路径是 ~/.codex。这个目录里常见文件包括：

~/.codex/
├── config.toml                  # 全局默认配置
├── auth.json                    # 登录/认证状态
├── history.jsonl                # 历史记录
├── logs / caches                # 日志缓存
├── deep-review.config.toml      # Profile 配置档案
└── sessions/                    # 会话回放

全局配置路径：~/.codex/config.toml，如果没有可以手动创建 mkdir -p ~/.codex && zed ~/.codex/config.toml。这是你日常用得最多的配置文件。

项目级配置路径：在项目根目录下放 .codex/config.toml。例如 /Users/x/Desktop/next-demo/.codex/config.toml。项目级配置只有在该项目被 Codex 信任之后才会加载，这是出于安全考虑。

系统级配置：在 Unix 系统上是 /etc/codex/config.toml，企业环境下管理员可通过 requirements.toml 强制施加约束。

三、配置优先级：从高到低的加载顺序

Codex 按以下顺序解析配置值，前面会覆盖后面：

1. CLI 标志和 --config 覆盖（最高优先级）
2. 项目配置文件 .codex/config.toml：从项目根目录一路遍历到当前工作目录，越靠近当前目录的优先级越高；仅可信项目生效
3. Profile 配置档案 ~/.codex/profile-name.config.toml，通过 --profile profile-name 选择
4. 用户级配置 ~/.codex/config.toml
5. 系统级配置 /etc/codex/config.toml（Unix）
6. 内置默认值（最低优先级）

需要注意几个安全限制：项目级配置不能覆盖机器本地的 provider、认证、通知、profile 选择或 telemetry 路由键。openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url、otel 这些键出现在项目本地配置中会被 Codex 忽略，应放在用户级配置中。如果项目被标记为不可信，Codex 会跳过项目作用域下的 .codex/ 层，包括项目本地配置、钩子和规则。

四、推荐的基础配置：直接抄作业

以下是作者推荐的稳妥基础配置，可作为 ~/.codex/config.toml 的起点：

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "high"

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

[sandbox_workspace_write]
network_access = true
writable_roots = [
  "/Users/x/Desktop"
]

字段解读：

• model = "gpt-5.5"：设置默认模型。
• model_reasoning_effort = "high"：推理强度，可选 low/medium/high，越高越准但越慢。
• approval_policy = "on-request"：危险操作、权限升级时再问。官方推荐交互使用 on-request，on-failure 已弃用。
• sandbox_mode = "workspace-write"：Codex 可写当前工作区，但不是完全放开系统权限。可选 read-only/workspace-write/danger-full-access。

五、想少确认一点：自动模式配置

如果你希望 Codex 自主跑、不打扰你，最简单的配置如下：

model = "gpt-5.5"
model_reasoning_effort = "high"

approval_policy = "never"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = [
  "/Users/pan/Desktop"
]

approval_policy = "never" 表示非交互场景下不再弹审批。但要意识到风险：这相当于把”刹车”交给 AI 自己掌控，建议只在你完全可控的可写根路径下使用。

如果你想要更精细的控制，Codex 还支持细粒度审批策略：

approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = true,
  skill_approval = true
} }

这样可以保留其他交互提示的同时，让某些提示类别自动允许或自动拒绝。

六、Profile 配置档案：多模式切换的高级玩法

如果你有多个开发场景，比如”日常开发””深度审查””AI 测试””本地模型”，可以用 Profile 配置档案来切换。

关键变化：官方现在要求 Profile 用单独文件，例如 ~/.codex/deep-review.config.toml，不要再写老式的 [profiles.xxx]。

深度审查模式示例：

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

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

使用方式：

codex --profile deep-review
codex exec --profile deep-review "review this change"

这就是文章开头提到的”规划阶段调用顶级模型做决策，执行阶段切换到更快更便宜的开源模型降低成本”的实现思路：你可以为每个场景定义不同的 model 和 model_reasoning_effort，按需切换。

七、接入第三方模型：Codex 国内畅用方案

对于国内用户来说，接入第三方模型网关是降本和稳定性的关键。Codex 通过 model_providers 配置支持任意 OpenAI 兼容接口。

示例：接入 QCode.cc 服务：

# ~/.codex/config.toml

model_provider = "crs"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"

配套的 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

把 cr_xxxxxxxxxx 替换为你的 QCode.cc API 密钥（以 cr_ 开头）。

示例：接入 DeepSeek：

model_provider = "omnimodel"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
requires_openai_auth = true
personality = "pragmatic"

[model_providers.omnimodel]
name = "omnimodel"
base_url = "https://omnimodel.pro/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

重要提醒：Codex 0.81.0 及以上版本默认走 /v1/responses 接口，而 DeepSeek 官方没有这个接口。如果你直接配置 DeepSeek 后遇到 /responses、404、接口不存在等报错，可以优先使用 https://api.claw-cn.org/v1 这类兼容接口，或者确保配置文件里选择的是 chat / OpenAI Compatible。

base_url 必须带 /v1，不能多不能少；wire_api 当前唯一可用值是 "responses"，不要填 "chat"。

八、不想折腾配置文件？图形化工具推荐

对于小白用户或想快速切换多个 Provider 的玩家，手动改 TOML 容易出错。社区已经涌现出一批图形化配置工具：

• CCSwitch：统一管理 Claude Code、Codex、Gemini CLI 等 AI 编程工具的模型配置，界面里填好 API 地址、API Key、模型名称，点击启用、重启 Codex 即可。
• Codex++：图形化管理工具，一键搞定中转配置，支持插件功能，适合主要用 Codex 桌面 App 的用户。本质上是帮你更方便地写入配置。
• Codex Mate：本地优先的 AI 开发工具集统一控制面板，集成 Web UI（http://localhost:3737），可一站式管理 Codex、Claude Code、OpenClaw 的配置和会话历史。
• opencodex：Codex Desktop 的本地网关，启动后自动修补 ~/.codex/config.toml，配备 Web 控制台（http://localhost:8765/dashboard），中英文一键切换，图形化管理 API Key 和接口地址。

九、安全与信任：项目级配置的边界

项目级配置只在受信任的项目中加载。不受信任的项目会跳过 .codex/ 层级，直接使用用户配置。

你可以通过 projects 表来声明哪些路径被信任：

[projects."/Users/yourname"]
trust_level = "trusted"

[projects."/Users/yourname/.codex"]
trust_level = "trusted"

设为 trusted 后 Codex 在该目录里不再每次都问”是否信任此项目”。Windows 路径写法是 [projects."C:/Users/yourname"]（用正斜杠或转义反斜杠）。

在企业环境中，管理员还可以通过 requirements.toml 强制施加约束，比如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access"，约束可用的 web_search 模式，定义网络访问白名单，甚至强制 deny-read 规则保护 ~/.ssh、/**/*.env 等敏感路径。

十、高级配置：MCP、Hooks、遥测、记忆系统

Codex 的进阶能力远不止模型切换，还包括：

• MCP Server 接入：注册 chrome-devtools、node_repl、pascal 等工具，让 Codex 接入浏览器控制、Node REPL 执行环境等能力。
• 生命周期 Hooks：通过 hooks.json 或内联 [hooks] 配置，在 Codex 执行流程的特定阶段触发自定义脚本。
• OpenTelemetry 遥测：通过 otel 配置将运行数据上报到可观测性平台。
• 通知系统：notify 配置可在长任务完成后通知用户。
• 记忆系统：Codex 支持 memories 配置，可以把历史会话提取为记忆，注入到后续会话中。可控字段包括 generate_memories、use_memories、max_raw_memories_for_consolidation、max_unused_days 等。
• AGENTS.md：项目根目录下的规则文件，给代理补充行为约束，比如输出风格、命令输出截断规则、代码注释要求。可以理解成”这个目录对代理的本地使用手册”。

十一、配置实战经验：三要三不要

最后总结几条实战经验：

• 要用环境变量管理敏感信息（API Key、代理密码），不要硬编码在 config.toml 里。见过有人把 config.toml 提交到 Git 仓库，结果 API Key 泄露，被刷了几百美元。
• 要在修改配置后重启 Codex 服务，不要以为热加载生效。Codex 目前不支持配置热更新，改完必须重新启动进程。
• 要保留一份默认配置备份，不要直接覆盖。习惯把原始 config.toml 重命名为 config.toml.default，改坏了能快速恢复。

如果遇到”模型不响应”或”连接超时”，先检查 [proxy] 块和 no_proxy 字段——内网地址（如 localhost,127.0.0.1,.local）不走代理能避免本地服务冲突。其次是 model_providers 里的 api_key 和 base_url，确保它们和你的 API 提供商一致。模型名写错反而少见，因为 Codex 会给出明确的错误提示。

结语

Codex 真正的潜能藏在那些被你忽略的配置字段里。从基础的模型选择、审批策略，到 Profile 多模式切换、第三方网关接入、MCP 工具集成、记忆系统，每一项配置都是把你和 AI 的协作打磨得更顺滑的杠杆。如果你觉得手动编辑 TOML 仍然繁琐，可以试试作者推荐的可视化 Codex 配置网站（https://codexapp.cc ），一键下载规范配置文件，直接拿到 ~/.codex/ 目录就能用。