正文

Codex CLI 是 OpenAI 推出的本地命令行 coding agent，可以直接在你的终端里读取项目、修改文件、运行命令，并辅助完成开发任务。官方 GitHub README 也明确说明，Codex CLI 是一个“runs locally on your computer”的轻量级 coding agent，支持通过安装脚本、npm、Homebrew 或二进制包安装。

不过，很多人第一次用 Codex CLI 时会遇到同一个问题：工具能跑，但体验不稳定。有时它频繁问你要不要批准命令，有时它不能写文件，有时项目配置不生效，有时模型和权限不是你想要的默认值。问题不一定出在 Codex 本身，而是你还没把基础配置理顺。

这篇博客不讲复杂理论，只讲最实用的 6 件事。把它们配好之后，你再用 Codex CLI 做代码审查、修 bug、补测试、重构项目，体验会顺很多。

先找到并理解 config.toml

Codex CLI 的核心配置文件是：

官方文档说明，用户级配置默认放在 ~/.codex/config.toml，项目级配置可以放在仓库里的 .codex/config.toml；但出于安全考虑，Codex 只会在你信任该项目后加载项目级 .codex/ 配置层。

这点非常重要。因为很多人会在项目目录里新建 .codex/config.toml，然后发现“怎么没生效”。原因可能不是写错了，而是项目还没有被 Codex 标记为可信。

你可以把配置分成两类：

建议先从用户级配置开始，不要一上来就在每个项目里放复杂配置。用户级配置稳定之后，再针对大型项目添加项目级配置。

一个最小配置可以这样写：

这三行已经能决定 Codex CLI 的大部分日常行为：用哪个模型、什么时候问你、能不能写项目文件。

~/.codex/config.toml

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

配好默认模型，不要每次手动指定

Codex CLI 支持通过配置文件设置默认模型。官方配置基础文档给出的示例是：

它用于选择 CLI 和 IDE 扩展默认使用的模型。

为什么这件事值得优先配置？因为模型会直接影响三件事：

第一，代码理解能力。大型项目、复杂类型系统、多文件重构，更依赖强推理模型。

第二，响应速度。简单任务不一定需要最强模型，用中等能力模型可能更快。

第三，成本或额度消耗。如果你通过 API key 使用 Codex，模型选择也会影响使用成本。

推荐做法是：日常开发使用一个稳定默认模型；深度审查、架构重构、复杂 debug 再切换高推理配置。

例如：

当你需要更深的代码审查，可以通过 Profile 单独配置高推理模式，而不是把全局默认值调得过重。这样既节省资源，也不会让每个小任务都变慢。

model = "gpt-5.5"

model = "gpt-5.5"
model_reasoning_effort = "medium"

配好审批策略：别让 Codex 既烦人又危险

Codex CLI 的审批策略控制它在运行命令前是否暂停询问。官方文档列出了常见审批策略：untrusted、on-request 和 never。其中，on-request 表示 Codex 默认在沙箱内工作，只有需要越界时才会请求批准；never 表示不会因为审批提示而停下来。

建议大多数开发者使用：

on-request 是一个比较平衡的选择。它不会每一步都打断你，也不会完全放手让 Codex 自己执行所有操作。

但不要把 never 当成默认配置。因为 coding agent 不是普通代码补全工具，它可能会执行 shell 命令、批量改文件、调用测试脚本。如果没有审批边界，出错时影响会更大。

实用建议是：

审批策略不是越宽松越好。真正高效的配置，是让 Codex 在安全范围内尽量自动化，在越界时及时停下来问你。

approval_policy = "on-request"

# 如果你刚开始试用 Codex CLI，或者项目很敏感，可以选择更保守的方式：
approval_policy = "untrusted"

# 如果你在一次性容器、临时目录、无敏感数据的实验环境里跑自动化任务，才考虑：
approval_policy = "never"

配好沙箱模式：决定 Codex 能碰哪里

沙箱模式决定 Codex CLI 能读取、写入和执行到什么程度。官方文档说明，常见沙箱模式包括：read-only、workspace-write 和 danger-full-access。其中 workspace-write 允许 Codex 在当前工作区内读写文件并运行常规本地命令，也是本地开发常用的低摩擦模式；danger-full-access 会移除文件系统和网络边界，应只在你确实希望 Codex 拥有完整访问权限时使用。

推荐默认配置：

这个配置适合大多数日常开发任务，比如：

如果你只是想让 Codex 读代码、解释项目、做审查，不希望它直接改文件，可以使用：

但这个模式不适合普通开发机默认开启。它会削弱沙箱保护，一旦 Codex 执行了错误命令，影响范围可能超出当前项目。

更稳妥的思路是：默认 workspace-write，必要时临时放宽。不要为了少点几次确认，就长期打开全权限。

• 修改代码文件
• 新增测试
• 运行本地测试命令
• 重构项目内模块
• 修复 lint 或类型错误

sandbox_mode = "workspace-write"

# 默认开发：
sandbox_mode = "workspace-write"

# 只读审查：
sandbox_mode = "read-only"

# 隔离容器里明确需要完整访问权限时：
sandbox_mode = "danger-full-access"

配好项目级规则和信任边界

Codex CLI 支持用户级配置，也支持项目级 .codex/config.toml。官方文档说明，配置优先级从高到低大致是：CLI flags 和 --config 覆盖、项目配置、Profile、用户配置、系统配置、内置默认值。

这意味着：如果你在命令行里临时传了参数，它会覆盖配置文件；如果项目里有 .codex/config.toml，它可能覆盖你的用户级默认值；如果你使用了 Profile，也会叠加一层配置。

一个适合团队项目的 .codex/config.toml 可以这样写：

项目级配置适合解决这类问题：

第一，项目需要固定安全边界。比如只允许 Codex 写当前仓库，不允许碰用户目录。

第二，项目需要额外可写目录。比如构建缓存、临时输出目录、测试快照目录。

第三，团队希望统一 Codex 行为。比如所有成员都使用相同审批策略和项目规则。

不过，不建议把所有个人偏好写进项目配置。像默认模型、个人 MCP 服务、通知方式、认证相关配置，更适合放在用户级配置里。官方配置参考也指出，项目级配置不能覆盖一些机器本地 provider、auth、通知、遥测等键；这些应放在用户级配置中。

简单说：项目配置管“这个仓库怎么用 Codex”，用户配置管“我个人怎么用 Codex”。

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

[sandbox_workspace_write]
writable_roots = [
  ".",
  "/tmp"
]

配好 Profile：为不同任务准备不同模式

Profile 是 Codex CLI 里非常实用但容易被忽略的功能。官方高级配置文档说明，Profile 可以保存命名配置层，并通过 --profile profile-name 从 CLI 切换；Profile 文件放在 ~/.codex/profile-name.config.toml，使用顶层配置键，不要再嵌套到 [profiles.profile-name] 下。

这意味着你可以为不同任务准备不同配置，而不是频繁改同一个 config.toml。

比如，日常开发使用默认配置，再为深度审查和自动修复各准备一个 Profile：

深度审查 Profile 很适合做代码审查。它可以提高推理强度，同时用 read-only 限制写入，避免 Codex 在审查时顺手改文件。

使用时运行：

Profile 的好处是清晰。你不用每次都思考“这次要不要开写权限、要不要高推理、要不要更严格审批”。不同任务一个 Profile，打开就用。

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "read-only"

# ~/.codex/fix.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

codex --profile deep-review
codex --profile fix

推荐的一套起步配置

如果你只想快速开始，可以直接参考下面这份配置：

这套配置的思路是：允许 Codex 在当前项目里改代码，但默认不开放网络访问；当它需要越界时，让它询问你。对大多数个人项目和日常开发来说，这是一个比较稳的起点。

需要注意的是，官方沙箱说明里提到，默认权限通常允许 Codex 读取和编辑当前 workspace，并运行常规本地命令；当它要使用互联网或越过 workspace 边界时会请求批准。

所以，你不必一开始就配置得特别复杂。先把模型、审批、沙箱这三个核心项设好，再逐步加入 Profile、项目级配置和 MCP。

# ~/.codex/config.toml

model = "gpt-5.5"
model_reasoning_effort = "medium"

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

[sandbox_workspace_write]
writable_roots = ["."]
network_access = false

常见错误：为什么我的配置不生效？

配置不生效时，通常先检查这 5 点。

第一，文件路径是否正确。用户级配置应放在：

第二，TOML 格式是否正确。字符串要加引号，布尔值不要加引号：

第三，是否被命令行参数覆盖。Codex 的配置优先级中，CLI flags 和 --config 覆盖优先级最高。

第四，项目是否可信。如果项目未被信任，Codex 会跳过项目级 .codex/ 配置层。

第五，Profile 写法是否过时。较新的官方文档说明，Profile 应放在单独的 ~/.codex/profile-name.config.toml 文件中，并用顶层配置键，而不是写在主配置里的 [profiles.name] 表下面。

# 用户级配置路径：
~/.codex/config.toml

model = "gpt-5.5"
network_access = false

FAQ：Codex CLI 配置常见问题

结论：先配边界，再谈效率

Codex CLI 真正好用的关键，不是装完就马上让它大改项目，而是先把边界配清楚。

先设置默认模型，让它稳定使用你想要的能力；再设置审批策略，决定什么时候需要你点头；接着设置沙箱模式，控制它能写哪里、能访问什么；然后用项目配置处理仓库差异；最后用 Profile 区分日常开发、深度审查和自动修复。

一套好的 Codex CLI 配置，应该做到三点：默认安全、日常顺手、需要时可放宽。这样你既能享受 AI coding agent 带来的效率，也不会把项目安全完全交给一次自动执行。

参考来源

相关文章