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 模型与推理配置

配置项	当前值	作用	何时触发
model_provider	"custom"	指定模型提供商	每次会话启动时
model	"qwen3.7-max"	默认模型	新会话自动使用
model_reasoning_effort	"high"	推理力度（low/medium/high/xhigh）	模型支持推理时
disable_response_storage	true	禁止存储响应内容	隐私敏感场景

验证方法：

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

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

3.2 网络搜索与个性化

配置项	当前值	作用	触发场景
web_search	"cached"	网络搜索模式	Codex 需要查询外部信息时
personality	"friendly"	交流风格	所有会话自动应用

web_search 三种模式对比：

模式	数据源	风险	适用场景
cached	OpenAI 维护的缓存索引	低，减少外部注入	推荐日常使用
live	实时网络获取	中，可能注入广告/无关内容	需要最新信息时
disabled	关闭搜索工具	无	纯本地任务

personality 三种风格：

风格	特点	示例
friendly	友好、温暖，有温度	“我来帮你看看这个配置…”
pragmatic	务实、简洁，直奔主题	“配置项作用是 X，验证方法 Y。”
"none"	禁用个性化，纯工具	“作用：X。验证：Y。”

四、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（生命周期钩子）

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

当前已配置的钩子：

插件	事件	作用
claude-mem	PreToolUse	工具调用前检查
claude-mem	PostToolUse	工具调用后记录
claude-mem	SessionStart	会话启动时加载记忆
claude-mem	UserPromptSubmit	用户提交 prompt 时处理
claude-mem	Stop	会话结束时保存
superpowers	SessionStart	加载 superpowers 指令

验证方法：

# 查看已信任的钩子
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 的插件：

插件	作用
figma@openai-api-curated	Figma 设计文件操作
claude-mem@claude-mem-local	跨会话记忆（部分功能）

验证方法：

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 服务器

服务器	用途	是否必需
node_repl	Node.js REPL	内置，保留
brave-search	Brave 网络搜索	缺 API Key，可能无法使用
chrome-devtools	Chrome 开发者工具	调试 Web 应用时需要
context7	开发者文档查询	有用
feishu	飞书集成	有用
filesystem	文件系统操作	有用
github	GitHub 集成	有用
mall_prod	生产环境 MySQL	有用
mysql-kkd-prod	另一个生产 MySQL	有用
mysql_dev	开发环境 MySQL	有用
redis-local	本地 Redis	有用
redis-prod	生产 Redis	有用
sequential-thinking	顺序思考工具	有用
utools	uTools 集成	有用
wechat-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 快速定位问题

现象	可能原因	验证方法	解决方案
子 Agent 工具不可用	multi_agent 未启用	/tools 查看	添加 multi_agent = true
Figma 工具不可用	apps 未启用	/tools 查看	添加 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 验证

#	功能	验证方法	预期结果	状态
1	multi_agent	请求多文件任务	多个子 Agent 并行工作	⬜
2	hooks	启动会话	claude-mem 钩子自动加载	⬜
3	shell_snapshot	连续执行相同命令	第二次明显更快	⬜
4	fast_mode	简单任务	响应速度正常	⬜
5	undo	修改文件后说"撤销"	文件恢复原状	⬜
6	personality	观察交流风格	友好、有温度	⬜
7	apps	使用 Figma 插件	Figma 工具可用	⬜
8	memories	新会话问历史问题	能回忆起历史信息	⬜
9	computer_use	请求控制桌面应用	能操作桌面	⬜
10	goals	使用 /goal 命令	目标跟踪功能可用	⬜

7.2 全局配置验证

#	配置项	验证方法	预期结果	状态
1	web_search	请求搜索网络信息	使用缓存索引	⬜
2	personality	观察输出风格	友好风格	⬜
3	model	新会话自动选择	qwen3.7-max	⬜
4	model_reasoning_effort	复杂推理任务	使用 high 力度	⬜

7.3 MCP 服务器验证

#	服务器	验证方法	预期结果	状态
1	brave-search	请求 Brave 搜索	可能失败（缺 API Key）	⬜
2	github	请求查询 GitHub	正常工作	⬜
3	mysql_dev	请求查询开发库	正常工作	⬜
4	redis-local	请求查询本地 Redis	正常工作	⬜
5	feishu	请求操作飞书	正常工作	⬜

八、总结与建议

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：相关文件位置

文件	位置	作用
config.toml	~/.codex/	用户级配置
auth.json	~/.codex/	凭证存储
history.jsonl	~/.codex/	历史记录
hooks.json	~/.codex/ 或 /.codex/	钩子配置
rules/*.rules	~/.codex/rules/	命令规则
memories/	~/.codex/	记忆文件
AGENTS.md	~/.codex/ 或仓库根	项目指导

附录 C：术语表

术语	含义
Feature Flag	功能开关，控制特定能力的启用/禁用
MCP	Model Context Protocol，模型上下文协议，连接外部工具的标准
Hook	生命周期钩子，在特定事件触发时执行自定义脚本
Ghost Snapshot	Git 幽灵快照，不写入 git log 的临时快照
Subagent	子 Agent，由主 Agent 派生的并行执行单元
Apps/Connectors	ChatGPT 应用和连接器，提供插件能力