跳至主要內容

配置文件 config.toml

AgentFlow约 1932 字大约 6 分钟

配置文件 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接入外部工具和知识源只接可信服务，明确权限范围
环境传递必要变量或隔离敏感变量凭据用最小权限，避免写进教程截图

推荐 profiles

只读学习

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

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

任务示例：

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

日常编码

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

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

任务示例：

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

审查与发布前检查

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

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

任务示例：

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

配置变更的验证方法

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

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

再检查：

  • 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 里的图形界面版本：

  1. 打开 codex-provider-sync Releases，下载 CodexProviderSync.exe。
  2. 双击运行后，先确认顶部 Codex Home 路径指向你的 .codex 目录。
  3. 点击 Refresh，查看当前 provider、rollout、SQLite 和项目可见性诊断。
  4. 在 provider 列表里选择目标 Provider。
  5. 如果希望同时改写 config.toml 根级 model_provider，再勾选右侧对应选项。
  6. 点击 Execute 执行同步。
  7. 如果结果不符合预期，用 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

官方资料延伸

MIT Licensed | Copyright © 2026 AgentFlow
Copyright © 2026 AgentFlow