Codex config.toml配置实战指南

Codex 桌面应用的配置，说复杂也复杂，说简单也简单。核心就一个文件 ~/.codex/config.toml，它决定了 Agent 能做什么、怎么做事。今天就把这份配置掰开揉碎了讲清楚，每个选项的作用、在什么场景下触发、以及怎么验证它确实生效了。

一、引言

如果说 Codex 是一台精密的机器，那 config.toml 就是它的控制面板。本文档记录了当前环境下的完整配置状态，目的很纯粹：帮你在遇到问题时快速定位，搞清楚某个功能为什么没反应，或者新增配置前确认影响范围。

• 排查某个功能"为什么没生效"
• 新增配置项前确认影响范围
• 向同事解释 Codex 的工作机制

1. 快速定位任意配置项的作用和验证方法
2. 理解 Feature Flags 如何影响 Agent 的工具集
3. 知道哪些配置是"被动生效"、哪些需要"主动触发"

二、配置文件概览

2.1 文件位置与格式

配置文件位置很明确：~/.codex/config.toml。格式是 TOML，一种对人类友好的配置语言。优先级方面，项目级配置 > 用户级 > 系统级，具体层级关系在附录 A 有详细说明。大部分配置修改后需要重启 Codex 应用才能生效，这一点要注意。

2.2 当前配置结构

整体结构大概长这样：全局配置在最前面，然后是模型提供商、MCP 服务器（目前有 17 个）、插件（14 个），最后是功能开关（11 个）。每个部分各司其职，下面逐一拆解。

三、全局配置项详解

3.1 模型与推理配置

先说几个最关键的：

• model_provider:
  当前值为 "custom"，这个配置在每次会话启动时生效，决定了模型从哪里来。

• model:
  当前为 "qwen3.7-max"，新会话自动使用这个模型。

• model_reasoning_effort:
  设置为 "high"，控制推理的力度，从 low 到 xhigh 可选。复杂任务建议保持 high，但要注意会消耗更多 token。如果模型不支持这个参数，配置会被忽略，不会报错。

• disable_response_storage:
  设置为 true，禁止存储响应内容，主要用于隐私敏感场景。

在终端输入 codex --version 或者在会话中输入 /model 查看当前生效的模型。

3.2 网络搜索与个性化

当前值为 "cached"，这是网络搜索模式。三种模式各有优劣：

• cached:
  使用 OpenAI 维护的缓存索引，风险低，推荐日常使用。

• live:
  实时网络获取，风险中等，可能注入广告，适合需要最新信息时。

• disabled:
  关闭搜索工具，纯本地任务时使用。

当前值为 "friendly"，控制交流风格。三种风格可选：friendly（友好温暖）、pragmatic（务实简洁）、"none"（纯工具风格）。所有会话自动应用该配置。

四、Feature Flags 详解

Feature Flags 是 Codex 的能力开关，直接决定了哪些工具和机制可用。当前配置如下：

[features]
computer_use = true      # 计算机控制
js_repl = false          # JS REPL（关闭）
goals = true             # 目标管理
multi_agent = true       # 子 Agent 协作
hooks = true             # 生命周期钩子
shell_snapshot = true    # Shell 快照加速
fast_mode = true         # 快速模式
undo = true              # Git Ghost 撤销
personality = true       # 个性化控件
apps = true              # ChatGPT Apps/Connectors
memories = true          # 跨会话记忆

下面挑几个重点展开说说。

4.1 multi_agent（子 Agent 协作）

这个开关启用后，Codex 可以使用 spawn_agent、wait_agent、close_agent 三个工具，派生子 Agent 并行执行任务。典型场景是使用 subagent-driven-development 或 dispatching-parallel-agents 技能时，或者遇到复杂任务需要拆分。比如用户说"实现一个用户登录功能"，主 Agent 会拆分成前端表单、后端接口、数据库设计三个子任务并行处理，最后汇总结果。

重启 Codex 后，在会话中请求一个多文件任务，观察是否有多个子 Agent 并行工作。或者在终端输入 /tools 查看工具列表中是否包含 spawn_agent。

4.2 hooks（生命周期钩子）

钩子允许在工具调用前后、会话启动时执行自定义脚本。当前已配置的钩子主要来自 claude-mem 和 superpowers，覆盖了工具调用前检查、工具调用后记录、会话启动时加载记忆等场景。

使用 grep -A 5 "[hooks.state]" ~/.codex/config.toml 查看已信任的钩子。需要说明的是，钩子脚本需要被信任后才会执行，使用 /hooks 命令可以管理。

4.3 shell_snapshot（Shell 快照加速）

这个功能的设计很巧妙：首次执行某个命令时快照 shell 环境，后续相同命令直接复用，启动速度能提升 4 倍左右。举个例子，第一次执行 ls -la 需要约 250ms，第二次复用快照后只需要约 60ms。整个过程自动触发，无感运行。

没有直接验证方式，但可以通过对比重启前后的命令执行时间来感知速度提升。

4.4 fast_mode（快速模式）

使用 service_tier = "fast" 的模型层，响应更快、成本更低。自动触发，适用于简单任务。如果当前模型不支持该参数，会被忽略，复杂推理任务仍会使用 model_reasoning_effort 配置的力度。

4.5 undo（Git Ghost 撤销）

每次编辑文件前做一次 git ghost 快照，支持回滚到任意历史状态。在会话中说"撤销刚才的改动"或"回滚到上一个版本"就能触发。工作原理是创建一个不写入 git log 的临时快照，所以重启 Codex 后之前的快照会丢失。

让 Codex 修改一个文件，然后说"撤销刚才的改动"，观察文件是否恢复。

4.6 personality（个性化控件）

启用个性化交流风格，根据 personality = "friendly" 调整输出。所有会话自动应用，验证方法就是对比 personality = "none" 时的输出风格差异。

4.7 apps（ChatGPT Apps/Connectors）

启用 ChatGPT Apps 和 Connectors 支持，使 Figma、Canva 等插件的工具可用。当前依赖 apps 的插件包括 figma@openai-api-curated 和 claude-mem@claude-mem-local（部分功能）。

在会话中请求使用 Figma，观察是否有相关工具可用，或者输入 /tools 查看工具列表。

4.8 memories（跨会话记忆）

从历史会话中提取有用的上下文，在新会话中自动注入。后台异步工作，不需要手动操作。记忆内容可以包括技术栈偏好、项目规范、踩过的坑等。比如"用户喜欢用 Spring Boot + MyBatis"、"commit message 使用 Conventional Commits"、"Redis 连接池默认大小不够，建议 10+"。

新开一个会话，问 Codex "你还记得我之前项目的技术栈吗？"，观察是否能回忆起历史信息。需要注意的是，记忆是异步生成的，不是每个会话结束都会更新，敏感信息会被自动脱敏。可以通过 /memories 控制当前会话是否使用/生成记忆。

4.9 computer_use（计算机控制）

允许 Codex 操作 macOS/Windows 桌面应用，包括看屏幕、点击、输入。触发场景包括测试桌面应用、操作没有 API/插件的数据源、复现 GUI 相关的 bug。

在会话中请求"打开计算器应用"，观察 Codex 是否能控制桌面。需要提前授予屏幕录制和辅助功能权限，建议保持任务范围窄，避免误操作。

4.10 goals（目标管理）

启用目标跟踪功能，使用 /goal 命令或 Codex 判断需要跟踪长期任务时触发。

4.11 js_repl（JS REPL）

当前值为 false，关闭状态。因为当前工作流主要使用 Python/Ja va，JS REPL 不是必需。如需启用，改为 true 并重启。

五、MCP 服务器配置

5.1 当前配置的 MCP 服务器

目前配置了 15 个 MCP 服务器，覆盖了 Node.js 环境、网络搜索、Chrome 调试、文档查询、飞书集成、文件系统、GitHub、数据库、Redis、顺序思考工具、uTools 集成、微信集成等。大部分服务器都配置了所需的环境变量，但有几个需要注意的安全问题。

5.2 安全风险提醒

这是一个比较明显的问题。配置中没有提供 API Key，导致 Bra ve 搜索工具无法正常工作。解决方案有两个：要么补全 API Key，要么直接删除这个 MCP 服务器。考虑到已经有 web_search = "cached" 提供搜索能力，推荐删除。

配置文件中直接写明了 app-secret，虽然 config.toml 不进 git，但如果被其他人看到或备份到云端，存在泄露风险。建议使用环境变量代替，但需要注意环境变量注入需要在 [shell_environment_policy] 中配置，当前未配置此项，需要额外处理。

多个 MySQL MCP 服务器配置了生产环境密码明文，同样的风险。建议使用环境变量或密钥管理工具。

六、配置速查表

6.1 快速定位问题

遇到问题别慌，先看这里：

• 子 Agent 工具不可用 → 检查 multi_agent 是否启用 → 添加 multi_agent = true
• Figma 工具不可用 → 检查 apps 是否启用 → 添加 apps = true
• 无法撤销改动 → 检查 undo 是否启用 → 添加 undo = true
• 新会话没有历史上下文 → 检查 memories 是否启用 → 添加 memories = true
• 网络搜索结果质量差 → 检查 web_search 模式 → 改为 "cached" 或 "live"
• 命令执行慢 → 检查 shell_snapshot 是否启用 → 添加 shell_snapshot = true

6.2 常用命令

平时维护用的几个命令：

# 查看当前配置
cat ~/.codex/config.toml

# 备份配置
cp ~/.codex/config.toml ~/.codex/config.toml.bak

# 查看已启用的功能
grep -A 20 "[features]" ~/.codex/config.toml

# 查看已信任的钩子
grep -A 10 "[hooks.state]" ~/.codex/config.toml

# 查看 MCP 服务器列表
grep "[mcp_servers" ~/.codex/config.toml

# 查看插件列表
grep "[plugins" ~/.codex/config.toml

七、验证清单

重启 Codex 后，建议逐项验证配置是否生效。这里列出完整的验证清单，方便对照检查。

7.1 Feature Flags 验证

每个功能开关都有对应的验证方法，比如 multi_agent 通过请求多文件任务验证，undo 通过修改文件后说"撤销"验证，memories 通过新会话问历史问题验证。具体验证方法和预期结果在表格中都有详细说明。

7.2 全局配置验证

确认 web_search 使用缓存索引、personality 显示友好风格、model 正确选择 qwen3.7-max、model_reasoning_effort 使用 high 力度。

7.3 MCP 服务器验证

重点验证 bra ve-search 可能失败（缺 API Key），github、mysql_dev、redis-local、feishu 等应该正常工作。

八、总结与建议

8.1 配置状态总结

当前配置整体状态不错：11 个 Feature Flags 全部启用（除了 js_repl 合理关闭），全局配置项完整，17 个 MCP 服务器配置了 16 个可用。但有几个需要处理的问题：

• bra ve-search 缺 API Key（建议删除或补全）
• 飞书 app-secret 明文（建议改为环境变量）
• 生产数据库密码明文（建议改为环境变量）

8.2 下一步建议

优先级排序：安全第一，处理飞书和数据库的明文密码问题；然后是清理，删除或补全 bra ve-search；最后是优化，定期验证 memories 和 undo 功能是否正常工作。

九、附录

附录 A：配置文件优先级

从高到低：CLI 标志和 --config 覆盖 > 项目配置文件 .codex/config.toml > Profile 文件 ~/.codex/profile-name.config.toml > 用户配置 ~/.codex/config.toml > 系统配置 /etc/codex/config.toml > 内置默认值。

附录 B：相关文件位置

几个关键文件的位置：config.toml 在 ~/.codex/，auth.json 凭证存储也在同一目录，history.jsonl 历史记录，hooks.json 钩子配置，rules/*.rules 命令规则，memories/ 记忆文件，AGENTS.md 项目指导。

附录 C：术语表

几个关键术语：Feature Flag 是功能开关，MCP 是模型上下文协议，Hook 是生命周期钩子，Ghost Snapshot 是 Git 幽灵快照，Subagent 是子 Agent，Apps/Connectors 是 ChatGPT 应用和连接器。