Codex config.toml配置实战手册

Codex 桌面应用实际配置，逐项说明每个配置项的作用、触发场景和验证方法。

一、引言

Codex 桌面应用的配置文件 ~/.codex/config.toml 控制着 Agent 的核心行为。本文档记录当前环境的完整配置状态，帮助快速定位问题、理解能力边界。

适用场景：

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

预期收获： 读完本文档，你能：

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

二、配置文件概览

2.1 文件位置与格式

~/.codex/config.toml

• 格式： TOML（Tom’s Obvious, Minimal Language）
• 优先级： 项目级 > 用户级 > 系统级（详见附录 A）
• 生效方式： 大部分配置需重启 Codex 应用后生效

2.2 当前配置结构

# 全局配置
model_provider = "custom"
model = "qwen3.7-max"
web_search = "cached"
personality = "friendly"
# 模型提供商
[model_providers.custom]
...
# MCP 服务器（17 个）
[mcp_servers.node_repl]
[mcp_servers.brave-search]
...
# 插件（14 个）
[plugins."browser@openai-bundled"]
...
# 功能开关（11 个）
[features]
multi_agent = true
...

三、全局配置项详解

3.1 模型与推理配置

验证方法：

# 检查当前生效的模型
codex --version
# 或在会话中输入 /model 查看

[!NOTE]
model_reasoning_effort = "high" 会消耗更多 token，复杂任务建议保持 high。如果代&理不支持 reasoning 参数，会被忽略，不会报错。

3.2 网络搜索与个性化

web_search 三种模式对比：

personality 三种风格：

四、Feature Flags 详解

Feature Flags 是 Codex 的能力开关，控制哪些工具和机制可用。

4.1 当前状态总览

[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.2 multi_agent（子 Agent 协作）

作用： 启用 spawn_agent、wait_agent、close_agent 三个工具，允许 Codex 派生子 Agent 并行执行任务。

何时触发：

• 使用 subagent-driven-development skill 时
• 使用 dispatching-parallel-agents skill 时
• 遇到复杂任务需要拆分时

典型场景：

用户：实现一个用户登录功能，包括前端表单、后端接口、数据库设计。

Codex 主 Agent：
  → spawn_agent("前端表单", task_description)
  → spawn_agent("后端接口", task_description)
  → spawn_agent("数据库设计", task_description)
  → wait_agent(所有子 Agent)
  → 汇总结果

验证方法：

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

4.3 hooks（生命周期钩子）

作用： 在工具调用前后、会话启动时执行自定义脚本。

当前已配置的钩子：

验证方法：

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

[!TIP]
钩子脚本需要被信任后才会执行。使用 /hooks 命令可以查看、审查、信任钩子。

4.4 shell_snapshot（Shell 快照加速）

作用： 首次执行某个命令时快照 shell 环境，后续相同命令直接复用，启动更快。

何时触发： 自动触发，无感。

性能提升示例：

第一次执行 ls -la：
  - 初始化 shell 环境：~200ms
  - 执行命令：~50ms
  - 总计：~250ms

第二次执行 ls -la：
  - 复用快照：~10ms
  - 执行命令：~50ms
  - 总计：~60ms（提速 4x）

验证方法：

• 无直接验证方式，但命令响应速度会明显提升
• 可通过对比重启前后的命令执行时间感知

4.5 fast_mode（快速模式）

作用： 使用 service_tier = "fast" 的模型层，响应更快、成本更低。

何时触发： 自动触发，适用于简单任务。

[!NOTE]
如果当前代&理不支持该参数，会被忽略。复杂推理任务仍会使用 model_reasoning_effort 配置的力度。

4.6 undo（Git Ghost 撤销）

作用： 每次编辑文件前做一次 git ghost 快照，支持回滚到任意历史状态。

何时触发：

• 在会话中说"撤销刚才的改动"
• 在会话中说"回滚到上一个版本"
• Codex 检测到改坏了，主动建议回滚

工作原理：

验证方法：

1. 让 Codex 修改一个文件
2. 说"撤销刚才的改动"
3. 观察文件是否恢复到修改前

[!WARNING]
Ghost 快照不会出现在 git log 中。重启 Codex 后，之前的快照会丢失。

4.7 personality（个性化控件）

作用： 启用个性化交流风格，根据 personality = "friendly" 调整输出。

何时触发： 所有会话自动应用。

验证方法： 对比 personality = "none" 时的输出风格差异。

4.8 apps（ChatGPT Apps/Connectors）

作用： 启用 ChatGPT Apps 和 Connectors 支持，使 Figma、Canva 等插件的工具可用。

何时触发：

• 使用 Figma 插件时
• 使用 Canva 插件时
• 使用任何需要 App 集成能力的插件时

当前依赖 apps 的插件：

验证方法：

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

4.9 memories（跨会话记忆）

作用： 从历史会话中提取有用的上下文（技术栈、项目规范、踩过的坑），在新会话中自动注入。

何时触发：

• 后台异步工作，不需要手动操作
• 新会话启动时自动加载相关记忆

记忆内容示例：

技术栈偏好：
- 用户喜欢用 Spring Boot + MyBatis
- 数据库偏好 MySQL 8.0
- 前端使用 Vue 3 + Element Plus

项目规范：
- commit message 使用 Conventional Commits
- 代码风格遵循 Google Java Style
- 测试覆盖率要求 ≥ 80%

踩过的坑：
- Redis 连接池默认大小不够，建议 10+
- MyBatis 的 resultMap 映射容易漏字段

验证方法：

1. 新开一个会话
2. 问 Codex “你还记得我之前项目的技术栈吗？”
3. 观察是否能回忆起历史信息

[!IMPORTANT]
记忆是异步生成的，不是每个会话结束都会更新。敏感信息会被自动脱敏。可以通过 /memories 控制当前会话是否使用/生成记忆。

4.10 computer_use（计算机控制）

作用： 允许 Codex 操作 macOS/Windows 桌面应用，包括看屏幕、点击、输入。

何时触发：

• 测试桌面应用时
• 操作没有 API/插件的数据源时
• 复现 GUI 相关的 bug 时

验证方法：

1. 在会话中请求"打开计算器应用"
2. 观察 Codex 是否能控制桌面

[!CAUTION]
需要授予屏幕录制和辅助功能权限。建议保持任务范围窄，避免误操作。

4.11 goals（目标管理）

作用： 启用目标跟踪功能，可以设定目标并追踪进度。

何时触发：

• 使用 /goal 命令时
• Codex 判断需要跟踪长期任务时

4.12 js_repl（JS REPL）

当前值： false（关闭）

作用： 启用 JavaScript REPL 工具，可以交互式执行 JS 代码。

为何关闭： 当前工作流主要使用 Python/Java，JS REPL 不是必需。如需启用，改为 true 并重启。

五、MCP 服务器配置

5.1 当前配置的 MCP 服务器

5.2 安全风险提醒

5.2.1 brave-search 缺 API Key

问题：

[mcp_servers.brave-search]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
# 缺少 env 配置

影响： Brave 搜索工具无法正常工作。

解决方案（二选一）：

方案 A：添加 API Key

[mcp_servers.brave-search]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
[mcp_servers.brave-search.env]
BRAVE_API_KEY = "your-api-key-here"

方案 B：删除该 MCP 服务器（推荐，因为已有 web_search = "cached"）

# 删除 brave-search 相关配置
sed -i '/[mcp_servers.brave-search]/,/^$/d' ~/.codex/config.toml

5.2.2 飞书 app-secret 明文

问题：

[mcp_servers.feishu]
args = [
    "-y",
    "@larksuiteoapi/lark-mcp",
    "mcp",
    "--app-id",
    "cli_a9256761dd389cc6",
    "--app-secret",
    "zBuX1x7MhvsGKgiKg2hTVh0E4w7uFsWo",  # ← 明文
]

风险： 虽然 config.toml 不进 git，但如果被其他人看到或备份到云端，会泄露。

解决方案： 使用环境变量

# 1. 设置环境变量
export FEISHU_APP_SECRET="zBuX1x7MhvsGKgiKg2hTVh0E4w7uFsWo"
# 2. 修改配置
[mcp_servers.feishu]
args = [
    "-y",
    "@larksuiteoapi/lark-mcp",
    "mcp",
    "--app-id",
    "cli_a9256761dd389cc6",
    "--app-secret",
    "${FEISHU_APP_SECRET}",  # ← 引用环境变量
]

[!NOTE]
环境变量注入需要在 [shell_environment_policy] 中配置，当前未配置此项，需要额外处理。

5.2.3 生产环境数据库密码

问题： 多个 MySQL MCP 服务器配置了生产环境密码明文。

[mcp_servers.mall_prod.env]
MYSQL_PASS = "Mall123!@#"  # ← 生产密码

[mcp_servers.mysql-kkd-prod.env]
MYSQL_PASS = "Abc123!@#"   # ← 生产密码

风险： 同上，泄露风险。

解决方案： 同飞书，使用环境变量或密钥管理工具。

六、配置速查表

6.1 快速定位问题

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 验证

7.2 全局配置验证

7.3 MCP 服务器验证

八、总结与建议

8.1 配置状态总结

✅ 已正确配置：

• 11 个 Feature Flags 全部启用（除 js_repl 合理关闭）
• 全局配置项完整（model、web_search、personality）
• 17 个 MCP 服务器配置（16 个可用）

⚠️ 需要处理：

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

8.2 下一步建议

优先级 1（安全）：

• 处理飞书 app-secret 明文问题
• 处理生产数据库密码明文问题

优先级 2（清理）：

• 删除 brave-search MCP 服务器（或补全 API Key）

优先级 3（优化）：

• 定期验证 memories 功能是否正常工作
• 测试 undo 功能是否符合预期

九、附录

附录 A：配置文件优先级

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

附录 B：相关文件位置

附录 C：术语表