Codex 桌面应用的配置，说复杂也复杂，说简单也简单。核心就一个文件 ~/.codex/config.toml，它决定了 Agent 能做什么、怎么做事。今天就把这份配置掰开揉碎了讲清楚，每个选项的作用、在什么场景下触发、以及怎么验证它确实生效了。
一、引言
如果说 Codex 是一台精密的机器，那 config.toml 就是它的控制面板。本文档记录了当前环境下的完整配置状态，目的很纯粹：帮你在遇到问题时快速定位，搞清楚某个功能为什么没反应，或者新增配置前确认影响范围。
适用场景：
- 排查某个功能"为什么没生效"
- 新增配置项前确认影响范围
- 向同事解释 Codex 的工作机制
读完本文，你能做到：
- 快速定位任意配置项的作用和验证方法
- 理解 Feature Flags 如何影响 Agent 的工具集
- 知道哪些配置是"被动生效"、哪些需要"主动触发"
二、配置文件概览
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 网络搜索与个性化
web_search: 当前值为 "cached"，这是网络搜索模式。三种模式各有优劣：
- cached: 使用 OpenAI 维护的缓存索引，风险低，推荐日常使用。
- live: 实时网络获取，风险中等，可能注入广告，适合需要最新信息时。
- disabled: 关闭搜索工具，纯本地任务时使用。
personality: 当前值为 "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 安全风险提醒
bra ve-search 缺 API Key： 这是一个比较明显的问题。配置中没有提供 API Key，导致 Bra ve 搜索工具无法正常工作。解决方案有两个：要么补全 API Key，要么直接删除这个 MCP 服务器。考虑到已经有 web_search = "cached" 提供搜索能力，推荐删除。
飞书 app-secret 明文： 配置文件中直接写明了 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 应用和连接器。
