Codex 配置
Codex config.toml 无法保存或显示只读，应该怎样处理
Codex 的用户级配置通常位于 ~/.codex/config.toml，Windows 一般对应 C:\Users\你的用户名\.codex\config.toml。如果文件无法保存，应先判断是文件只读属性、目录权限、编辑器权限、进程占用，还是项目级 .codex/config.toml 覆盖了用户配置。不要一开始就删除整个 .codex 目录。
更新时间：2026-06-26
适用对象：Codex 用户
配置文件在哪里
用户级配置：
~/.codex/config.toml
Windows：
C:\Users\<用户名>\.codex\config.toml
macOS 和 Linux：
/home/<用户名>/.codex/config.toml
或
/Users/<用户名>/.codex/config.toml
项目级配置：
<项目根目录>/.codex/config.toml
Codex App、IDE 扩展和 CLI 使用相同的配置层。
配置优先级
从高到低通常是：
- CLI 参数
- 项目目录下更接近当前工作目录的 .codex/config.toml
- 指定 Profile
- 用户级 ~/.codex/config.toml
- 系统配置
- 默认值
因此，“修改了用户配置但没有生效”不一定是保存失败，也可能是项目配置或 CLI 参数覆盖。
Windows 第一步：检查只读属性
PowerShell：
$path = "$env:USERPROFILE\.codex\config.toml"
Get-Item $path | Format-List FullName,Attributes,IsReadOnly
取消只读：
Set-ItemProperty -Path $path -Name IsReadOnly -Value $false
或：
attrib -R "$env:USERPROFILE\.codex\config.toml"
第二步：检查目录权限
icacls "$env:USERPROFILE\.codex"
确认当前账户至少拥有读取、写入、修改权限。必要时备份后赋予当前用户修改权限：
icacls "$env:USERPROFILE\.codex" /grant "$env:USERNAME:(OI)(CI)M" /T
企业受管设备不要绕过管理员策略。
第三步：排除编辑器问题
- 关闭正在打开 config.toml 的所有编辑器
- 退出 Codex App、IDE 扩展和相关终端
- 使用记事本或 VS Code 单独打开
- 修改一行注释并保存
- 重新打开确认是否写入
测试命令：
Add-Content "$env:USERPROFILE\.codex\config.toml" "# write-test"
测试完成后删除该注释。
第四步：检查文件所有者
(Get-Acl "$env:USERPROFILE\.codex\config.toml").Owner
如果所有者是管理员、SYSTEM 或另一个账户，可能需要在管理员确认后调整所有者。
第五步：检查项目配置覆盖
Get-ChildItem -Path . -Filter config.toml -Recurse -Force |
Where-Object { $_.FullName -match "\\.codex\\" }
如果存在项目/.codex/config.toml，检查是否定义了与用户配置相同的键。
一个安全的基础示例
# 用户级基础配置
approval_policy = "on-request"
# 项目文档发现设置
project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
不要推荐 approval_policy = "never" 或 sandbox_mode = "danger-full-access"，除非完整解释安全风险。
修改后不生效怎么办
- 是否修改了正确的用户目录
- CODEX_HOME 是否被设置到其他路径
- 是否存在项目级配置覆盖
- 是否使用了 CLI 临时参数
- 项目是否被标记为不受信任
- 是否重新启动 Codex
- TOML 语法是否正确
检查 CODEX_HOME：
PowerShell: $env:CODEX_HOME
macOS/Linux: echo "$CODEX_HOME"
TOML 常见错误
错误：approval_policy = on-request
正确：approval_policy = "on-request"
错误：project_doc_fallback_filenames = "TEAM_GUIDE.md"
正确：project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
恢复方法
如果修改后 Codex 无法启动：
Move-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.broken"
再把备份恢复：
Copy-Item "$env:USERPROFILE\.codex\config.toml.backup" "$env:USERPROFILE\.codex\config.toml"
最终检查清单
- 找到正确的 config.toml
- 已建立备份
- 文件不是只读
- 当前账户有修改权限
- CODEX_HOME 路径正确
- 没有项目配置覆盖
- TOML 语法正确
- Codex 已重新启动
- 修改后功能已验证
FAQ
- Q：Codex config.toml 在哪里？
A：用户级通常在 ~/.codex/config.toml，项目级在项目根目录的 .codex/config.toml。 - Q：修改后不生效？
A：检查项目配置覆盖、CLI 参数、CODEX_HOME 环境变量和 TOML 语法。 - Q：无法保存？
A：先查只读属性和目录权限，不要直接删 .codex 目录。