Codex config.toml 配置实战指南基于 2026-07-07 Codex 桌面应用实际配置逐项说明每个配置项的作用、触发场景和验证方法。目录文章目录Codex config.toml 配置实战指南目录一、引言二、配置文件概览2.1 文件位置与格式2.2 当前配置结构三、全局配置项详解3.1 模型与推理配置3.2 网络搜索与个性化四、Feature Flags 详解4.1 当前状态总览4.2 multi_agent子 Agent 协作4.3 hooks生命周期钩子4.4 shell_snapshotShell 快照加速4.5 fast_mode快速模式4.6 undoGit Ghost 撤销4.7 personality个性化控件4.8 appsChatGPT Apps/Connectors4.9 memories跨会话记忆4.10 computer_use计算机控制4.11 goals目标管理4.12 js_replJS REPL五、MCP 服务器配置5.1 当前配置的 MCP 服务器5.2 安全风险提醒5.2.1 brave-search 缺 API Key5.2.2 飞书 app-secret 明文5.2.3 生产环境数据库密码六、配置速查表6.1 快速定位问题6.2 常用命令七、验证清单7.1 Feature Flags 验证7.2 全局配置验证7.3 MCP 服务器验证八、总结与建议8.1 配置状态总结8.2 下一步建议九、附录附录 A配置文件优先级附录 B相关文件位置附录 C术语表一、引言Codex 桌面应用的配置文件~/.codex/config.toml控制着 Agent 的核心行为。本文档记录当前环境的完整配置状态帮助快速定位问题、理解能力边界。适用场景排查某个功能为什么没生效新增配置项前确认影响范围向同事解释 Codex 的工作机制预期收获读完本文档你能快速定位任意配置项的作用和验证方法理解 Feature Flags 如何影响 Agent 的工具集知道哪些配置是被动生效、哪些需要主动触发二、配置文件概览2.1 文件位置与格式~/.codex/config.toml格式TOMLTom’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.browseropenai-bundled] ... # 功能开关11 个 [features] multi_agent true ...三、全局配置项详解3.1 模型与推理配置配置项当前值作用何时触发model_providercustom指定模型提供商每次会话启动时modelqwen3.7-max默认模型新会话自动使用model_reasoning_efforthigh推理力度low/medium/high/xhigh模型支持推理时disable_response_storagetrue禁止存储响应内容隐私敏感场景验证方法# 检查当前生效的模型codex--version# 或在会话中输入 /model 查看[!NOTE]model_reasoning_effort high会消耗更多 token复杂任务建议保持 high。如果代理不支持 reasoning 参数会被忽略不会报错。3.2 网络搜索与个性化配置项当前值作用触发场景web_searchcached网络搜索模式Codex 需要查询外部信息时personalityfriendly交流风格所有会话自动应用web_search 三种模式对比模式数据源风险适用场景cachedOpenAI 维护的缓存索引低减少外部注入推荐日常使用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-developmentskill 时使用dispatching-parallel-agentsskill 时遇到复杂任务需要拆分时典型场景用户实现一个用户登录功能包括前端表单、后端接口、数据库设计。 Codex 主 Agent → spawn_agent(前端表单, task_description) → spawn_agent(后端接口, task_description) → spawn_agent(数据库设计, task_description) → wait_agent(所有子 Agent) → 汇总结果验证方法重启 Codex 后在会话中请求一个多文件任务观察是否有多个子 Agent 并行工作或在终端输入/tools查看工具列表应包含spawn_agent4.3 hooks生命周期钩子作用在工具调用前后、会话启动时执行自定义脚本。当前已配置的钩子插件事件作用claude-memPreToolUse工具调用前检查claude-memPostToolUse工具调用后记录claude-memSessionStart会话启动时加载记忆claude-memUserPromptSubmit用户提交 prompt 时处理claude-memStop会话结束时保存superpowersSessionStart加载 superpowers 指令验证方法# 查看已信任的钩子grep-A5\[hooks.state\]~/.codex/config.toml[!TIP]钩子脚本需要被信任后才会执行。使用/hooks命令可以查看、审查、信任钩子。4.4 shell_snapshotShell 快照加速作用首次执行某个命令时快照 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 undoGit Ghost 撤销作用每次编辑文件前做一次 git ghost 快照支持回滚到任意历史状态。何时触发在会话中说撤销刚才的改动在会话中说回滚到上一个版本Codex 检测到改坏了主动建议回滚工作原理是否编辑文件前创建 git ghost 快照执行编辑用户满意?继续从 ghost 快照恢复验证方法让 Codex 修改一个文件说撤销刚才的改动观察文件是否恢复到修改前[!WARNING]Ghost 快照不会出现在git log中。重启 Codex 后之前的快照会丢失。4.7 personality个性化控件作用启用个性化交流风格根据personality friendly调整输出。何时触发所有会话自动应用。验证方法对比personality none时的输出风格差异。4.8 appsChatGPT Apps/Connectors作用启用 ChatGPT Apps 和 Connectors 支持使 Figma、Canva 等插件的工具可用。何时触发使用 Figma 插件时使用 Canva 插件时使用任何需要 App 集成能力的插件时当前依赖 apps 的插件插件作用figmaopenai-api-curatedFigma 设计文件操作claude-memclaude-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_replJS REPL当前值false关闭作用启用 JavaScript REPL 工具可以交互式执行 JS 代码。为何关闭当前工作流主要使用 Python/JavaJS REPL 不是必需。如需启用改为true并重启。五、MCP 服务器配置5.1 当前配置的 MCP 服务器服务器用途是否必需node_replNode.js REPL内置保留brave-searchBrave 网络搜索缺 API Key可能无法使用chrome-devtoolsChrome 开发者工具调试 Web 应用时需要context7开发者文档查询有用feishu飞书集成有用filesystem文件系统操作有用githubGitHub 集成有用mall_prod生产环境 MySQL有用mysql-kkd-prod另一个生产 MySQL有用mysql_dev开发环境 MySQL有用redis-local本地 Redis有用redis-prod生产 Redis有用sequential-thinking顺序思考工具有用utoolsuTools 集成有用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.toml5.2.2 飞书 app-secret 明文问题[mcp_servers.feishu] args [ -y, larksuiteoapi/lark-mcp, mcp, --app-id, cli_a9256761dd389cc6, --app-secret, zBuX1x7MhvsGKgiKg2hTVh0E4w7uFsWo, # ← 明文 ]风险虽然 config.toml 不进 git但如果被其他人看到或备份到云端会泄露。解决方案使用环境变量# 1. 设置环境变量exportFEISHU_APP_SECRETzBuX1x7MhvsGKgiKg2hTVh0E4w7uFsWo# 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 trueFigma 工具不可用apps未启用/tools查看添加apps true无法撤销改动undo未启用测试撤销功能添加undo true新会话没有历史上下文memories未启用问历史问题添加memories true网络搜索结果质量差web_search模式问题测试搜索改为cached或live命令执行慢shell_snapshot未启用对比执行时间添加shell_snapshot true6.2 常用命令# 查看当前配置cat~/.codex/config.toml# 备份配置cp~/.codex/config.toml ~/.codex/config.toml.bak# 查看已启用的功能grep-A20\[features\]~/.codex/config.toml# 查看已信任的钩子grep-A10\[hooks.state\]~/.codex/config.toml# 查看 MCP 服务器列表grep\[mcp_servers~/.codex/config.toml# 查看插件列表grep\[plugins~/.codex/config.toml七、验证清单重启 Codex 后逐项验证7.1 Feature Flags 验证#功能验证方法预期结果状态1multi_agent请求多文件任务多个子 Agent 并行工作⬜2hooks启动会话claude-mem 钩子自动加载⬜3shell_snapshot连续执行相同命令第二次明显更快⬜4fast_mode简单任务响应速度正常⬜5undo修改文件后说撤销文件恢复原状⬜6personality观察交流风格友好、有温度⬜7apps使用 Figma 插件Figma 工具可用⬜8memories新会话问历史问题能回忆起历史信息⬜9computer_use请求控制桌面应用能操作桌面⬜10goals使用 /goal 命令目标跟踪功能可用⬜7.2 全局配置验证#配置项验证方法预期结果状态1web_search请求搜索网络信息使用缓存索引⬜2personality观察输出风格友好风格⬜3model新会话自动选择qwen3.7-max⬜4model_reasoning_effort复杂推理任务使用 high 力度⬜7.3 MCP 服务器验证#服务器验证方法预期结果状态1brave-search请求 Brave 搜索可能失败缺 API Key⬜2github请求查询 GitHub正常工作⬜3mysql_dev请求查询开发库正常工作⬜4redis-local请求查询本地 Redis正常工作⬜5feishu请求操作飞书正常工作⬜八、总结与建议8.1 配置状态总结✅ 已正确配置11 个 Feature Flags 全部启用除 js_repl 合理关闭全局配置项完整model、web_search、personality17 个 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/或project/.codex/钩子配置rules/*.rules~/.codex/rules/命令规则memories/~/.codex/记忆文件AGENTS.md~/.codex/或仓库根项目指导附录 C术语表术语含义Feature Flag功能开关控制特定能力的启用/禁用MCPModel Context Protocol模型上下文协议连接外部工具的标准Hook生命周期钩子在特定事件触发时执行自定义脚本Ghost SnapshotGit 幽灵快照不写入 git log 的临时快照Subagent子 Agent由主 Agent 派生的并行执行单元Apps/ConnectorsChatGPT 应用和连接器提供插件能力文档版本基于 2026-07-07 实际配置整理Codex 桌面应用版本 26.623.141536。