Codex 会从多个位置读取配置。个人默认值放在 ~/.codex/config.toml，仓库内可以放 .codex/config.toml。项目配置只有在该项目被信任时才会加载，这条限制也覆盖项目里的 hooks 和 rules。
本文内容核对到 2026 年 8 月。配置键、默认值和设置入口可能变化，动手前应以当前配置参考为准。
先选对配置范围
一项设置对所有仓库都适用，就写进用户配置。只服务某个项目的 MCP、sandbox 或 hook，放进仓库的 .codex/config.toml 更容易跟项目一起审查。临时试一次的值优先用 CLI 参数，避免把实验设置留成长期默认。
CLI 和 IDE 扩展共享同一套配置层。IDE 里可以从右上角齿轮进入 Codex Settings，再打开 config.toml。桌面端、CLI 与 IDE 对 MCP 配置也能共用，具体能力仍会受到当前客户端、使用入口和管理员策略限制。
记住覆盖顺序
官方文档给出的优先级从高到低依次是 CLI flags 与 --config、项目配置、--profile 选中的配置文件、用户配置、系统配置和内置默认值。项目配置还会从仓库根目录向当前工作目录逐层加载，离当前目录更近的值优先。
这套顺序很适合排查“明明改了却没生效”。先看启动命令有没有临时覆盖，再确认当前目录属于哪个项目层级，随后检查 profile。项目被标为不信任时，仓库里的 .codex/ 配置不会参与计算。
嵌套仓库尤其容易发生覆盖。假设根目录和子目录都放了 .codex/config.toml，从子目录启动时，两层都会被读取，同名键由更近的一层决定。换回根目录启动，子目录配置就不会参与。排错时记录 pwd，再沿当前目录向上列出每个 .codex/config.toml，比反复修改用户配置更快。
系统配置位于 Unix 的 /etc/codex/config.toml，常用于机器默认值。组织还可能通过受管要求限制允许的 sandbox、批准策略和 MCP 范围。个人配置的优先级较高，不代表它能越过管理员强制约束。遇到值被拒绝时，应检查要求文件和工作区政策。
从最小配置开始
Codex 目前同时提供 permission profiles 和旧版 sandbox 设置。两套机制不能写进同一份生效配置。任何已加载的配置或命令行参数出现 sandbox_mode，Codex 就会使用旧版机制，不再采用 default_permissions。
下面的用户配置采用 permission profiles，让命令默认在工作区范围内运行，并在需要额外许可时请求批准。
approval_policy = "on-request"
default_permissions = ":workspace"
已有环境若继续使用 sandbox_mode = "workspace-write"，应删除 default_permissions 和 [permissions]。准备迁移到 permission profiles 时，则要先移除 sandbox_mode、[sandbox_workspace_write] 和 --sandbox 参数。不要把两套示例拼在一起。
需要为某个绝对路径记录信任状态时，可以在用户配置中加入项目表。
[projects."/absolute/path/to/project"]
trust_level = "trusted"
不要一次复制整份示例配置。先加入眼下确实需要的键，启动一个新会话，确认行为后再扩展。配置参考页会列出每个键的类型和可选值，拼写或类型没有依据时先查参考页。
修改配置时保留一个小差异更容易撤回。先复制现有文件到受控备份位置，再只改一个设置。新会话里验证模型、sandbox 或 MCP 是否按预期加载，失败就回看 TOML 表头位置。TOML 中同一个键放错表，语法仍可能成立，含义却已经变了。
密钥留在环境变量里
config.toml 可能进入备份或被项目提交。MCP 需要令牌时，配置里保存环境变量名，令牌值留在受控环境中。项目配置提交前运行 git diff，确认没有账号、访问令牌和本机私有路径混进去。
团队要提交项目配置时，先让另一位成员在干净工作树打开它。对方能在信任提示后加载相同设置，说明路径和层级足够清楚。若配置依赖某台机器的绝对路径，把那一项留在用户配置，并在项目文档写出需要的环境变量名。
需要两套常用配置时，可以建立 profile 文件，例如只读审查和日常开发各一份，再用 codex --profile <name> 选择。profile 只记录差异项，公共默认值继续留在用户配置，后续排错会简单很多。
速查：文件位置与优先加载
| 位置 | 用途 |
|---|---|
~/.codex/config.toml | 用户级默认（Windows 多为 %USERPROFILE%\.codex\config.toml） |
仓库内 .codex/config.toml | 项目级覆盖；需项目受信任才会加载 |
$CODEX_HOME/<name>.config.toml | 配置 profile，用 --profile name 选用 |
概念上的优先级从高到低：CLI / --config → --profile → 项目 .codex/config.toml → 用户级 → 系统级与内置默认。
项目级不要乱写的键（官方可能忽略，以当前文档为准）：model_provider / model_providers、部分 base URL、notify、profile / profiles。中转与 API provider 请写在用户级，详见 第三方 API / 中转。
和 AGENTS.md 相关的常用键：
project_doc_max_bytes = 32768
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
完整模板与验收命令见：AGENTS.md 指南。改崩配置时先恢复备份，再对照 常见排查。