配置文件 config.toml¶

config.toml 用来保存 Codex CLI 的本地默认行为。你可以把它理解为“个人驾驶舱”：模型、审批、沙盒、profiles、MCP 服务等偏好都可以在这里集中管理。

最后核对

官方资料最后核对日期：2026-05-27。本文参考 Codex config basic、Codex config advanced、Codex config reference 与 openai/codex config docs。

配置文件放在哪里¶

通常位于：

~/.codex/config.toml

项目长期规则建议写到仓库内的 AGENTS.md，个人偏好放到本机 config.toml。这样团队成员能共享项目规则，又能保留自己的 CLI 使用习惯。

截图占位

请补充本机 ~/.codex/config.toml 文件位置截图，注意遮挡敏感路径和 token。建议文件：docs/.vuepress/public/screenshots/config/02-config-location.png。

最小配置示例¶

下面是一个学习用示例，实际字段请以官方 config reference 和当前 CLI 版本为准：

model = "gpt-5.1-codex-max"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.readonly]
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.build]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

这个示例表达三件事：

默认允许在当前工作区写文件。
高风险命令仍需要审批。
额外保留一个只读 profile，适合新仓库分析。

常见配置项按用途理解¶

用途	你要决定什么	建议
模型	速度、成本、推理深度的取舍	用默认配置起步，复杂任务再临时调整
沙盒	Codex 能读写哪些位置	新手先只读或工作区写入
审批	哪些命令需要你确认	涉及网络、删除、安装、发布时保留审批
profiles	不同任务使用不同组合	准备 readonly、coding、review 三类 profile
MCP	接入外部工具和知识源	只接可信服务，明确权限范围
环境	传递必要变量或隔离敏感变量	凭据用最小权限，避免写进教程截图

配置变更的验证方法¶

每次改完配置，不要直接上复杂任务。用一个短任务验证：

请告诉我当前工作区、审批策略和你准备采用的验证方式。不要修改文件。

再检查：

Codex 是否能正确读取当前目录。
是否会在执行命令前解释意图。
是否遵守只读或工作区写入边界。
是否按预期触发审批。

截图占位

请补充切换 profile 后的状态截图。建议文件：docs/.vuepress/public/screenshots/config/03-profile-status.png。

切换 provider 后历史会话不可见怎么办¶

有些用户在修改根级 model_provider 后，会发现旧会话在 Codex Desktop 或 CLI 的 /resume 里突然不可见。常见原因不是会话文件丢失，而是 ~/.codex 里的会话 metadata、SQLite 状态和项目路径缓存仍停留在旧 provider。

第三方社区工具

下面介绍的是社区项目 Dailin521/codex-provider-sync，不是 OpenAI 官方工具。社区资料最后核对日期：2026-05-29。使用前请先备份 ~/.codex，并确认你理解它会修改本机 Codex 状态文件。

这个工具主要同步这些位置里的 provider / 可见性 metadata：

~/.codex/sessions
~/.codex/archived_sessions
~/.codex/state_5.sqlite
.codex-global-state.json 中的项目根路径缓存

先做两个判断：

如果 CLI /resume 能看到旧会话，但 Desktop 项目侧仍为空，可能是 Codex Desktop 最近 50 条会话的首屏显示限制，不一定是 provider metadata 问题。
如果最近刚切换过 model_provider，并且多个入口都找不到旧会话，再考虑使用同步工具。

Windows GUI 流程¶

Windows 用户可以优先使用上游 Release 里的图形界面版本：

打开 codex-provider-sync Releases，下载 CodexProviderSync.exe。
双击运行后，先确认顶部 Codex Home 路径指向你的 .codex 目录。
点击 Refresh，查看当前 provider、rollout、SQLite 和项目可见性诊断。
在 provider 列表里选择目标 Provider。
如果希望同时改写 config.toml 根级 model_provider，再勾选右侧对应选项。
点击 Execute 执行同步。
如果结果不符合预期，用 Restore Backup 从工具生成的备份目录恢复。

GUI 会默认保留最近几份由本工具创建的备份。若 state_5.sqlite 被占用，先关闭 Codex、Codex App 或 app-server 后再重试。

macOS 或 CLI 流程¶

CLI 版本需要 Node.js 24+。如果你使用 Node 20/22，可能会遇到 node:sqlite 不存在的问题。

npm install -g git+https://github.com/Dailin521/codex-provider-sync.git
codex-provider status

建议先只运行 status，确认它看到的 provider、rollout、SQLite 和项目可见性诊断符合预期。确认后再选择操作：

codex-provider sync
codex-provider sync --provider openai
codex-provider switch <provider-id>
codex-provider restore <backup-dir>

常用命令含义：

命令	作用
`codex-provider status`	只检查当前 provider、rollout、SQLite 和项目可见性，不执行同步
`codex-provider sync`	不切换登录状态，只把历史会话 metadata 同步到当前 provider
`codex-provider sync --provider openai`	指定目标 provider 后同步 metadata
`codex-provider switch <provider-id>`	修改 `config.toml` 根级 `model_provider`，然后执行同步
`codex-provider restore <backup-dir>`	从备份恢复，适合结果不符合预期时回滚

能力边界¶

它只处理“历史会话可见性”相关 metadata，不是账号切换器，也不是认证修复工具：

不处理登录、认证、auth.json 或第三方切号工具。
不修改消息历史、会话标题和对话内容。
不修改 updated_at，也不会通过改变历史排序绕过 Desktop 最近 50 条限制。
含 encrypted_content 的旧会话跨 provider 或 account 后，通常只能恢复列表可见性；继续对话或 compact 仍可能报 invalid_encrypted_content。

上游说明请看 README 和 GUI 中文说明。如果你只是想稳定使用 Codex，优先理解本页前面的 config.toml 配置方式；遇到 provider 切换后的历史会话不可见，再把这个工具作为排障选项。

团队配置建议¶

适合进仓库的内容：

AGENTS.md
推荐测试命令
代码风格和目录说明
PR 模板
文档截图规范

适合留在个人机器的内容：

默认模型偏好
本地路径
token、密钥、私有服务地址
个人 MCP 服务
私有 automation 配置

排障清单¶

现象	检查
配置没生效	文件路径、TOML 语法、CLI 版本、启动时是否选择 profile
Codex 权限超出预期	检查 `sandbox_mode` 和 `approval_policy`
某个命令一直被拒绝	检查沙盒限制、网络权限和组织策略
MCP 无法连接	检查服务命令、环境变量、端口、认证方式
切换 provider 后旧会话不可见	先判断是否是 Desktop 最近 50 条显示限制，再检查 provider metadata 是否需要同步
团队成员行为不一致	把项目共同规则写进 `AGENTS.md`

配置文件 config.toml¶

配置文件放在哪里¶

最小配置示例¶

常见配置项按用途理解¶

推荐 profiles¶

只读学习¶

日常编码¶

审查与发布前检查¶