Codex config.toml 进阶指南

本指南面向使用 Codex CLI 做日常研发、代码审查和运维开发的用户，解释 ~/.codex/config.toml 中真正影响模型、Provider、权限、会话与 Token 的设置。

内容按 Codex CLI 0.146.0 核对。Codex 更新较快，升级后请重新运行文末的严格校验。 首次安装请先阅读 Codex 安装与配置。

不要把 API Key、Bearer Token 或其他密钥直接写进 config.toml、项目仓库或命令历史。

一份质量优先的完整配置

下面的模板适合个人研发机器。它默认使用高推理强度，同时保留按需审批：

model_provider = "icodeeasy"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
cli_auth_credentials_store = "file"

approval_policy = "on-request"
sandbox_mode = "danger-full-access"
personality = "pragmatic"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

推荐让 Codex 生成并管理 ~/.codex/auth.json。环境变量只用于通过标准输入完成一次导入：

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

https://jp.icodeeasy.cc 和 https://sg.icodeeasy.cc 是备用访问域名。主域名连接不佳时， 只需替换 base_url，不要同时修改 Provider ID。

配置位置与优先级

用户级配置默认位于：

~/.codex/config.toml

Codex 配置优先级从高到低为：

1. 命令行参数与 -c / --config 临时覆盖；
2. 受信任项目中的 .codex/config.toml；
3. 通过 --profile 选择的 ~/.codex/<name>.config.toml；
4. 用户级 ~/.codex/config.toml；
5. 系统级配置；
6. Codex 默认值。

单次任务可以临时提高推理强度，而不修改文件：

codex -c 'model_reasoning_effort="xhigh"'

TOML table 陷阱

顶层键应放在第一个 [table] 之前：

model = "gpt-5.6-sol"
web_search = "live"

[model_providers.icodeeasy]
name = "I Code Easy"

一旦进入 [model_providers.icodeeasy]，后续键都属于该 table，直到出现下一个 table。 把 model 写在它后面，不再表示顶层模型配置。

模型与推理强度

model

model = "gpt-5.6-sol"

model 是发给当前 Provider 的模型标识。模型选择器中能看到某个名称，不等于当前 Provider 一定支持它。验证模型时应实际检查文本生成、工具调用、流式结束事件与 usage， 不能只看 HTTP 200。

model_reasoning_effort

model_reasoning_effort = "xhigh"

质量优先的研发机器可以默认 xhigh，再通过 Profile 为轻量任务主动降级。只有模型目录和 Provider 都确认支持时，才使用 max 或 ultra。提高推理强度 通常会增加响应时间与 reasoning token，但不能解决长会话反复携带历史上下文的问题。

plan_mode_reasoning_effort

plan_mode_reasoning_effort = "xhigh"

该字段只覆盖 Plan 模式。保留它可以让方案设计与执行使用一致的推理深度；删除时使用 Codex 的 Plan 模式默认值。

不要随意硬编码上下文窗口

model_context_window 和 model_auto_compact_token_limit 可以覆盖模型元数据，但经过 自定义 Provider 时，模型可能有不同的映射和限制。除非已经验证实际上限，否则使用 Codex 模型目录的默认值更稳妥。

Provider：ID、显示名和 Base URL

model_provider = "icodeeasy"

[model_providers.icodeeasy]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

这些字段承担不同职责：

name 只是显示名称

把 name = "OpenAI" 改成 name = "I Code Easy"，收益是 /status 更准确，不会让人 误以为当前是 OpenAI 直连。它不会改变模型质量、性能、认证、缓存、计费或历史会话。

Provider ID 是持久化兼容接口

icodeeasy 是 Provider ID。Codex 会把它保存到 session 元数据中，因此不要为了美观 随意重命名。只改 name 是安全的；删除或更改 Provider ID 后，旧 session 通常仍能在 列表里看到，但恢复时可能报错：

failed to load configuration: Model provider `icodeeasy` not found

确实需要换 ID 时，应保留旧定义作为兼容别名：

model_provider = "new_provider"

[model_providers.new_provider]
name = "I Code Easy"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

# 用于恢复历史 session。
[model_providers.icodeeasy]
name = "I Code Easy (legacy)"
base_url = "https://api.icodeeasy.cc"
wire_api = "responses"
requires_openai_auth = true

不要批量修改 Codex 的 session JSONL 或状态数据库；保留旧 ID 通常更简单可靠。

认证与密钥

requires_openai_auth = true 表示 Provider 使用 Codex 的 OpenAI 认证存储，可以使用 API Key 或 ChatGPT 登录。本站推荐文件凭据模式：

cli_auth_credentials_store = "file"

它会把登录凭据保存在 ~/.codex/auth.json。不要手工填写 JSON，也不要把 Key 长期写入 .bashrc、.zshrc 或 Windows 用户环境变量。首次登录和轮换 Key 都使用：

read -s OPENAI_API_KEY
printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status

这套分工很明确：

auth.json 是明文凭据缓存，必须像密码一样保护。Linux/macOS 建议执行 chmod 600 ~/.codex/config.toml ~/.codex/auth.json；不要提交 Git、放进公开备份或发给他人。 更换 Key 时重新运行登录命令，退出并删除缓存使用 codex logout。

相较长期环境变量，文件凭据不依赖 shell、tmux、IDE 或后台进程是否继承环境，日常研发 通常更稳定。它只改善凭据发现的一致性，不会改善网关网络、限流或模型兼容性。

认证存储方式不会改变历史 Session 的可见性。Session 恢复主要依赖本地状态和 Provider ID； 不要为了切换认证方式重命名 Provider ID。

/status 显示下面内容属于正常状态：

Account: API key configured (run codex login to use ChatGPT)

它表示当前使用 API Key，而不是 ChatGPT 登录，并不表示认证失败。env_key 与 requires_openai_auth = true 同时存在时，env_key 不负责选择凭据，建议不要重复配置。

权限与审批是两个维度

approval_policy = "on-request"
sandbox_mode = "danger-full-access"

• sandbox_mode 决定命令在技术上可以访问哪些文件和网络；
• approval_policy 决定 Codex 何时请求用户确认。

danger-full-access + on-request 不等于 --yolo。专用研发机器也不代表所有输入可信： 新克隆的仓库、依赖脚本、网页内容、项目 hooks 和 MCP 返回值仍可能存在风险。

陌生项目可临时收紧权限：

codex -s workspace-write

项目信任、Web Search 与 MCP

项目信任

[projects."/absolute/path/to/repository"]
trust_level = "trusted"

信任项目后，Codex 才会加载项目范围的 .codex/config.toml、hooks 和 rules。它不会 自动把 sandbox 改为 danger-full-access。只信任由自己控制的具体仓库，不要为了方便 信任包含大量无关项目的宽泛父目录。

Web Search

web_search = "live"

研发工作常需核对最新文档和版本，live 很有价值，但网页是外部不可信输入，不应把 网页中的命令当作可以直接执行的本地指令。

MCP

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
enabled = true
required = false
startup_timeout_sec = 10
tool_timeout_sec = 60

只有在任务缺少该 MCP 就无法继续时，才设置 required = true；否则 MCP 初始化失败会 阻止新建或恢复 thread。

用 Profile 分离质量与速度

Codex 0.134.0 之后，Profile 使用独立文件，只需写与主配置不同的字段。

快速任务：

# ~/.codex/quick.config.toml
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

codex --profile quick

陌生仓库只读检查：

# ~/.codex/readonly.config.toml
approval_policy = "never"
sandbox_mode = "read-only"
web_search = "cached"

codex --profile readonly

Provider ID 等影响历史 session 的基础字段应留在主配置中，不要在不同 Profile 间 随意更名。

如何阅读 /status

Model:              gpt-5.6-sol (reasoning xhigh, summaries auto)
Model provider:     I Code Easy - https://api.icodeeasy.cc
Permissions:        Custom (danger-full-access, Ask for approval)
Account:            API key configured
Token usage:        708K total (679K input + 28.9K output)
Context window:     51% left (132K used / 258K)
Limits:             not available for this account

• Model provider：名称来自 name，实际目的地看 base_url。
• Permissions: Custom：表示权限组合不是简单预设，以括号里的 sandbox 和审批策略为准。
• Limits: not available：Codex 无法读取当前认证方式的 ChatGPT 限额，不表示无限额度。
• Session：可用于 codex resume <session-id> 恢复会话。

Token Usage、缓存与 Context Window

累计 Token 不等于上下文窗口

每轮请求都会携带当前有效上下文，所以长 session 的累计输入可以远大于模型窗口。 连续十轮各发送约 100K 上下文，累计输入可以接近 1M，但单轮仍只有约 100K。

Codex 0.146.0 的 /status 把 cached input 从显示的 input 中扣除：

displayed input = input_tokens - cached_input_tokens
displayed total = displayed input + output_tokens

会话结束时会拆分显示：

Token usage: total=... input=... (+ ... cached) output=... (reasoning ...)

reasoning 已包含在 output 中，不应再加一次。缓存输入仍是输入 Token，是否优惠以及 如何计费取决于实际上游计费规则。

为什么 132K / 258K 会显示 51% left

Context window: 51% left (132K used / 258K)

Codex 0.146.0 不直接计算 1 - 132 / 258，而是从已用量和总窗口两边各扣除约 12K 固定基线，再估算用户可控制部分的剩余比例：

effective window = 258K - 12K
effective used   = 132K - 12K
remaining       = (effective window - effective used) / effective window
                ≈ 51%

这部分基线用于系统提示、固定工具说明以及 compact 空间。因此百分比和括号数字回答的是 略有不同的问题。

什么时候 compact

在一个开发阶段完成、调查输出已经归纳，或者上下文余量明显下降时使用 /compact。 如果后续任务与当前任务无关，使用 /new 更干净。累计 cached token 很大本身不是必须 compact 的理由。

Session 保存与恢复

codex resume <session-id>
codex resume --last
codex resume --all

默认选择器与 --last 会考虑当前工作目录；--all 用于跨目录查找。恢复会话会恢复 历史消息和 session 元数据，但不会复活已经退出的 shell 进程。文件、Git 和外部服务 状态始终以机器当前状态为准。

无效字段与严格校验

以下历史字段不应继续放在 Codex 0.146.0 配置中：

disable_response_storage = true
preferred_auth_method = "apikey"

普通启动可能忽略未知字段，让人误以为设置已经生效。该版本对非 Azure Responses 请求 已经使用 store = false，不由 disable_response_storage 控制；隐私仍取决于网关、 访问日志、本地 session 和其他工具的真实策略。

Linux / macOS 严格验证：

codex --strict-config mcp-server </dev/null
codex doctor --summary --ascii

第一条命令拒绝未知配置键，读取 EOF 后立即退出；第二条检查安装、认证、MCP、状态库和 Provider 连通性。Windows PowerShell 可以运行：

"" | codex --strict-config mcp-server
codex doctor --summary --ascii

进入 Codex 后，再用 /status 确认模型、推理强度、Provider URL、权限和上下文余量， 用 /debug-config 查看实际配置覆盖来源。修改 Provider 定义后，至少恢复一条旧 session 做兼容性验证。

参考资料

• Codex Authentication
• Codex Configuration Reference
• Codex Advanced Configuration
• Codex CLI command reference
• Codex custom instructions with AGENTS.md

本页于 2026-08-03 按 Codex CLI 0.146.0 与 OpenAI 官方资料核对。