: 首页; 看点啥; 插画图片

首页看点啥 Codex config.toml配置实战手册

Codex config.toml配置实战手册

2026-07-18 0

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

一、引言

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

适用场景：

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

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

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

二、配置文件概览

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)
  → 汇总结果

验证方法：

重启 Codex 后，在会话中请求一个多文件任务
观察是否有多个子 Agent 并行工作
或在终端输入 /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 检测到改坏了，主动建议回滚

工作原理：

验证方法：

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

[!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`	跨会话记忆（部分功能）

验证方法：

在会话中请求使用 Figma
观察是否有 Figma 相关工具可用
或输入 /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 映射容易漏字段

验证方法：

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

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

4.10 computer_use（计算机控制）

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

何时触发：

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

验证方法：

在会话中请求"打开计算器应用"
观察 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 应用和连接器，提供插件能力

喜欢(0)

OpenAI降价75%：奥特曼称是被DeepSeek逼的？

Codex三种任务调度模式实战指南：串行:并行:SDD