OpenAI Codex 系列篇二config.toml 配置系统详解——模型、Profiles 与功能开关上一篇〉OpenAI Codex 完全上手指南》我们跑通了安装、登录和第一次对话。但默认行为未必合你口味想换模型、想少点审批弹窗、想让 CI 里无人值守跑 Codex——这些全都指向同一个答案config.toml。这是系列的第二篇我们把 Codex 的配置系统一次讲透配置放哪、谁优先、每个常用配置项怎么写最后给你一份可以直接抄走的完整模板。一、配置文件放在哪两级结构Codex 的配置是 TOML 格式分两个层级级别路径适用场景用户级~/.codex/config.toml个人默认值所有项目共用项目级.codex/config.toml随仓库共享给团队的项目约定两个细节值得注意项目级配置可以放在仓库根目录也可以放在子目录多级目录时就近优先项目级配置只在受信项目里才会加载。不被信任的仓库会直接跳过.codex/层级——这个设计是防身的别人提交进仓库的配置文件不能替你悄悄开权限。在 IDE 插件里找配置文件点齿轮图标 → Codex Settings → Open config.toml。二、六层优先级配置不生效时的排查地图同一个配置项可能同时出现在多个地方Codex 按下面的顺序决定最终生效值从高到低CLI 标志和--config命令行临时覆盖只对本次会话生效Profile通过--profile 名称激活的场景预设项目配置距工作目录最近的优先仅受信项目生效用户配置~/.codex/config.toml系统配置/etc/codex/config.tomlUnix管理员下发内置默认值什么都没配时的出厂行为所以排查配置不生效的思路就一句话先想想它是不是被更具体、更靠上的一层覆盖了。比如你在项目里写了sandbox_mode read-only但命令行里带了--sandbox workspace-write赢的一定是命令行。三、模型设置换模型、调推理强度最常改的一组配置五项全覆盖配置项说明model使用的模型如gpt-5-codexmodel_provider模型提供商默认openaimodel_context_window可用的上下文 Token 数model_reasoning_effort推理强度从minimal到xhighmodel_reasoning_summary推理摘要详细程度auto/concise/detailed/nonemodel gpt-5-codex model_context_window 200000 # 上下文 Token 上限 model_reasoning_effort high # 简单任务调低复杂任务拉满 model_reasoning_summary concise # 想看详细推理过程改 detailed四、沙箱与审批安全的三道闸门Codex 的安全模型由两个维度组成。沙箱模式sandbox_mode决定文件系统能碰什么read-only只读最安全workspace-write可写工作区日常推荐danger-full-access完全放开慎用审批策略approval_policy决定什么事要问你untrusted不可信操作都要审批on-request模型按需请求审批never从不询问配 CI 用沙箱还能继续微调sandbox_mode workspace-write [sandbox_workspace_write] writable_roots [/tmp/build-output] # 额外允许写入的目录 network_access true # 是否允许出站网络访问我的建议平时workspace-writeon-request跑批处理/CI 时再考虑never且永远不要在danger-full-access下关审批。五、功能开关 [features]提前解锁实验能力一些还没默认放开的能力统一收在[features]表里功能说明shell_tool默认 Shell 命令工具稳定默认开启web_search网络搜索disabled/cached/livemulti_agent多智能体协作工具实验性unified_exec带 PTY 支持的执行工具Betaapply_patch_freeform暴露自由格式 Patch 工具[features] web_search live # 让 Codex 能联网查资料 multi_agent true # 复杂任务拆给多个子智能体六、MCP 服务器给 Codex 接外部工具MCP 是 Codex 连接外部工具的标准协议系列第四篇会专门展开配置写法分两类。STDIO 服务器本地进程最常见[mcp_servers.my-server] command npx args [-y, modelcontextprotocol/server-filesystem, /path] env { API_KEY ... } cwd /working/dir startup_timeout_sec 30HTTP 服务器远程[mcp_servers.my-http-server] url https://mcp.example.com/server bearer_token_env_var MY_TOKEN_ENV每个服务器还有通用选项enabled总开关、required启动失败是否终止 Codex、enabled_tools/disabled_tools工具黑白名单、tool_timeout_sec单次调用超时。七、Shell 环境与界面细节环境变量隔离是很多人忽略的安全点默认继承给 Shell 命令的变量集可以精细控制[shell_environment_policy] inherit core # all 全继承 | core 核心变量 | none 不继承 set { MY_VAR value }机器上有 API Key、云凭证这类敏感变量时别用inherit all。界面行为也有一些可调项配置项说明personality沟通风格none/friendly/pragmatictui.animations终端界面动画开关tui.notifications通知行为控制file_opener引用跳转用的编辑器vscode/cursor/windsurf等allow_login_shell开启 login-shell 语义八、历史记录与上下文压缩长会话必看的三项配置项说明history.persistence对话记录save-all全部保存或none不保存model_auto_compact_token_limit上下文自动压缩的触发阈值compact_prompt覆盖默认的压缩提示词history.persistence save-all model_auto_compact_token_limit 100000 # 快到上下文上限前自动压缩九、Profile一套配置多个场景Profile 解决的是日常一套配置、CI 另一套配置的切换问题。在配置文件里定义多个命名 Profile运行时指名调用[profiles.ci] approval_policy never sandbox_mode workspace-write model gpt-5.1-codexcodex--profileci执行代码审查关键特性Profile 中写了的项覆盖默认值没写的项继续用全局配置——所以只写差异部分就行。你可以为日常开发“CI 无人值守”只读审计各准备一个 Profile一条命令切换。十、企业管控requirements.toml 只能收紧不能放宽团队/企业管理员可以用requirements.toml/etc/codex/requirements.toml或组织级分发锁定安全敏感设置allowed_approval_policies [on-request, untrusted] allowed_sandbox_modes [read-only, workspace-write] allowed_web_search_modes [disabled, cached]注意它的方向性只能收紧权限不能放宽——管理员无法用它给你多开权限只能限制。个人config.toml再怎么写也越不过这条线。十一、拿来即用一份完整配置模板把上面所有内容拼起来这是一份可直接抄走再改的模板# ~/.codex/config.toml # ── 顶层键必须写在所有 [表] 之前── model gpt-5-codex model_reasoning_effort high model_reasoning_summary concise sandbox_mode workspace-write approval_policy on-request history.persistence save-all file_opener vscode personality pragmatic # ── 各个配置表 ── [sandbox_workspace_write] network_access true [features] web_search live [shell_environment_policy] inherit core [profiles.ci] approval_policy never sandbox_mode workspace-write [profiles.audit] sandbox_mode read-only approval_policy untrusted一个容易踩的 TOML 坑顶层键必须写在所有[表]头之前。TOML 规定表头之后的裸键都属于那个表——把model ...写到[features]下面它就不是模型配置了轻则静默失效重则启动报错。十二、写在最后配置系统是 Codex 从能用到好用的分水岭三个最值得先做的动作把个人默认值写进~/.codex/config.toml模型 审批策略给 CI 准备一个approval_policy never的 Profile在敏感机器上把shell_environment_policy.inherit改成core。下一篇我们讲AGENTS.md 记忆工程——怎么让 Codex 记住你的项目约定不用每次重复交代。系列目录篇一OpenAI Codex 完全上手指南篇二config.toml 配置系统详解本篇篇三AGENTS.md 记忆工程——让 AI 记住你的项目篇四MCP 与 Skills——给 Codex 装上工具箱篇五CI/CD 深度——无人值守的自动化工作流篇六Codex App 体验——桌面端能打吗 
长河君 · 2026/10/14 19:24:59 · 阅读 1.2k OpenAI Codex 系列篇二：config.toml 配置系统详解——模型、Profiles 与功能开关
OpenAI Codex 系列篇二config.toml 配置系统详解——模型、Profiles 与功能开关上一篇〉OpenAI Codex 完全上手指南》我们跑通了安装、登录和第一次对话。但默认行为未必合你口味想换模型、想少点审批弹窗、想让 CI 里无人值守跑 Codex——这些全都指向同一个答案config.toml。这是系列的第二篇我们把 Codex 的配置系统一次讲透配置放哪、谁优先、每个常用配置项怎么写最后给你一份可以直接抄走的完整模板。一、配置文件放在哪两级结构Codex 的配置是 TOML 格式分两个层级级别路径适用场景用户级~/.codex/config.toml个人默认值所有项目共用项目级.codex/config.toml随仓库共享给团队的项目约定两个细节值得注意项目级配置可以放在仓库根目录也可以放在子目录多级目录时就近优先项目级配置只在受信项目里才会加载。不被信任的仓库会直接跳过.codex/层级——这个设计是防身的别人提交进仓库的配置文件不能替你悄悄开权限。在 IDE 插件里找配置文件点齿轮图标 → Codex Settings → Open config.toml。二、六层优先级配置不生效时的排查地图同一个配置项可能同时出现在多个地方Codex 按下面的顺序决定最终生效值从高到低CLI 标志和--config命令行临时覆盖只对本次会话生效Profile通过--profile 名称激活的场景预设项目配置距工作目录最近的优先仅受信项目生效用户配置~/.codex/config.toml系统配置/etc/codex/config.tomlUnix管理员下发内置默认值什么都没配时的出厂行为所以排查配置不生效的思路就一句话先想想它是不是被更具体、更靠上的一层覆盖了。比如你在项目里写了sandbox_mode read-only但命令行里带了--sandbox workspace-write赢的一定是命令行。三、模型设置换模型、调推理强度最常改的一组配置五项全覆盖配置项说明model使用的模型如gpt-5-codexmodel_provider模型提供商默认openaimodel_context_window可用的上下文 Token 数model_reasoning_effort推理强度从minimal到xhighmodel_reasoning_summary推理摘要详细程度auto/concise/detailed/nonemodel gpt-5-codex model_context_window 200000 # 上下文 Token 上限 model_reasoning_effort high # 简单任务调低复杂任务拉满 model_reasoning_summary concise # 想看详细推理过程改 detailed四、沙箱与审批安全的三道闸门Codex 的安全模型由两个维度组成。沙箱模式sandbox_mode决定文件系统能碰什么read-only只读最安全workspace-write可写工作区日常推荐danger-full-access完全放开慎用审批策略approval_policy决定什么事要问你untrusted不可信操作都要审批on-request模型按需请求审批never从不询问配 CI 用沙箱还能继续微调sandbox_mode workspace-write [sandbox_workspace_write] writable_roots [/tmp/build-output] # 额外允许写入的目录 network_access true # 是否允许出站网络访问我的建议平时workspace-writeon-request跑批处理/CI 时再考虑never且永远不要在danger-full-access下关审批。五、功能开关 [features]提前解锁实验能力一些还没默认放开的能力统一收在[features]表里功能说明shell_tool默认 Shell 命令工具稳定默认开启web_search网络搜索disabled/cached/livemulti_agent多智能体协作工具实验性unified_exec带 PTY 支持的执行工具Betaapply_patch_freeform暴露自由格式 Patch 工具[features] web_search live # 让 Codex 能联网查资料 multi_agent true # 复杂任务拆给多个子智能体六、MCP 服务器给 Codex 接外部工具MCP 是 Codex 连接外部工具的标准协议系列第四篇会专门展开配置写法分两类。STDIO 服务器本地进程最常见[mcp_servers.my-server] command npx args [-y, modelcontextprotocol/server-filesystem, /path] env { API_KEY ... } cwd /working/dir startup_timeout_sec 30HTTP 服务器远程[mcp_servers.my-http-server] url https://mcp.example.com/server bearer_token_env_var MY_TOKEN_ENV每个服务器还有通用选项enabled总开关、required启动失败是否终止 Codex、enabled_tools/disabled_tools工具黑白名单、tool_timeout_sec单次调用超时。七、Shell 环境与界面细节环境变量隔离是很多人忽略的安全点默认继承给 Shell 命令的变量集可以精细控制[shell_environment_policy] inherit core # all 全继承 | core 核心变量 | none 不继承 set { MY_VAR value }机器上有 API Key、云凭证这类敏感变量时别用inherit all。界面行为也有一些可调项配置项说明personality沟通风格none/friendly/pragmatictui.animations终端界面动画开关tui.notifications通知行为控制file_opener引用跳转用的编辑器vscode/cursor/windsurf等allow_login_shell开启 login-shell 语义八、历史记录与上下文压缩长会话必看的三项配置项说明history.persistence对话记录save-all全部保存或none不保存model_auto_compact_token_limit上下文自动压缩的触发阈值compact_prompt覆盖默认的压缩提示词history.persistence save-all model_auto_compact_token_limit 100000 # 快到上下文上限前自动压缩九、Profile一套配置多个场景Profile 解决的是日常一套配置、CI 另一套配置的切换问题。在配置文件里定义多个命名 Profile运行时指名调用[profiles.ci] approval_policy never sandbox_mode workspace-write model gpt-5.1-codexcodex--profileci执行代码审查关键特性Profile 中写了的项覆盖默认值没写的项继续用全局配置——所以只写差异部分就行。你可以为日常开发“CI 无人值守”只读审计各准备一个 Profile一条命令切换。十、企业管控requirements.toml 只能收紧不能放宽团队/企业管理员可以用requirements.toml/etc/codex/requirements.toml或组织级分发锁定安全敏感设置allowed_approval_policies [on-request, untrusted] allowed_sandbox_modes [read-only, workspace-write] allowed_web_search_modes [disabled, cached]注意它的方向性只能收紧权限不能放宽——管理员无法用它给你多开权限只能限制。个人config.toml再怎么写也越不过这条线。十一、拿来即用一份完整配置模板把上面所有内容拼起来这是一份可直接抄走再改的模板# ~/.codex/config.toml # ── 顶层键必须写在所有 [表] 之前── model gpt-5-codex model_reasoning_effort high model_reasoning_summary concise sandbox_mode workspace-write approval_policy on-request history.persistence save-all file_opener vscode personality pragmatic # ── 各个配置表 ── [sandbox_workspace_write] network_access true [features] web_search live [shell_environment_policy] inherit core [profiles.ci] approval_policy never sandbox_mode workspace-write [profiles.audit] sandbox_mode read-only approval_policy untrusted一个容易踩的 TOML 坑顶层键必须写在所有[表]头之前。TOML 规定表头之后的裸键都属于那个表——把model ...写到[features]下面它就不是模型配置了轻则静默失效重则启动报错。十二、写在最后配置系统是 Codex 从能用到好用的分水岭三个最值得先做的动作把个人默认值写进~/.codex/config.toml模型 审批策略给 CI 准备一个approval_policy never的 Profile在敏感机器上把shell_environment_policy.inherit改成core。下一篇我们讲AGENTS.md 记忆工程——怎么让 Codex 记住你的项目约定不用每次重复交代。系列目录篇一OpenAI Codex 完全上手指南篇二config.toml 配置系统详解本篇篇三AGENTS.md 记忆工程——让 AI 记住你的项目篇四MCP 与 Skills——给 Codex 装上工具箱篇五CI/CD 深度——无人值守的自动化工作流篇六Codex App 体验——桌面端能打吗