首页 › LLM大语言模型 › Codex专栏 › Codex 安装与配置 › 配置文件 config.toml

配置文件 config.toml

配置文件放在哪里​

通常位于：~/.codex/config.toml​

​

💡

项目长期规则建议写到仓库内的 AGENTS.md，个人偏好放到本机 config.toml。​

​

最小配置示例​

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

​

代码块​

JSON

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，适合新仓库分析。​

常见配置项按用途理解​

推荐 profiles​

只读学习​

适合打开陌生仓库、生成项目地图、梳理测试命令。​

​

代码块​

YAML

[profiles.readonly]​

sandbox_mode = "read-only"​

approval_policy = "on-request"​

​

任务示例：​

​

代码块​

Bash

codex --profile readonly​

​

​

代码块​

Plain Text

请只读分析当前仓库。不要修改文件，不要运行会写入文件的命令。​

​

日常编码​

适合修测试、补文档、小范围实现。​

​

代码块​

YAML

[profiles.coding]​

sandbox_mode = "workspace-write"​

approval_policy = "on-request"​

​

任务示例：​

​

代码块​

Plain Text

请修复这个失败测试。修改范围限制在 `src/parser` 和对应测试文件，修复后运行 `pnpm test parser`。​

​

审查与发布前检查​

适合 PR review、发布前风险扫描、diff 总结。​

​

代码块​

YAML

[profiles.review]​

sandbox_mode = "read-only"​

approval_policy = "on-request"​

​

任务示例：​

​

代码块​

Plain Text

请 review 当前 diff，优先指出 bug、回归风险和缺失测试。不要修改文件。​

​

配置变更的验证方法​

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

​

代码块​

Plain Text

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

​

再检查：​

•

Codex 是否能正确读取当前目录。​

•

是否会在执行命令前解释意图。​

•

是否遵守只读或工作区写入边界。​

•

是否按预期触发审批。​

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

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

这个工具主要同步这些位置里的 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 不存在的问题。​

​

代码块​

YAML

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

codex-provider status​

​

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

​

代码块​

YAML

codex-provider sync​

​

常用命令含义：​

​

​

能力边界​

它只处理“历史会话可见性”相关 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 配置​

排障清单​

​

​