Codex config.toml配置指南：最小配置、生效检查与常见问题

先判断是否需要配置

默认设置已经能完成任务时，不必先写配置文件。只有在审批、沙箱、推理强度或项目最低边界需要稳定复用时，才把确认过的值写进 config.toml。一次性实验先用命令行参数或 -c 覆盖。

• 不要把 danger-full-access 或 approval_policy = "never" 当作入门默认值。
• 配置控制运行设置，项目规则仍写在 AGENTS.md。
• 配置中不放 API Key、auth.json、代理密码和个人路径。

来源与覆盖顺序

官方当前给出的常见顺序是：命令行参数和 --config 覆盖 → 受信任项目中的 .codex/config.toml（从根目录到当前目录，越近越优先）→ --profile 选择的 Profile → 用户 config.toml → 工作区托管配置 → 系统配置 → 内置默认值。托管要求可能进一步限制本地可用值。

一份保守的最小配置

下面只固定审批、沙箱和推理强度。字段和值以官方 Config basics、Advanced Config 和 Config Reference 为准；模型是否支持某个推理值要按当前入口核对。

# $CODEX_HOME/config.toml
approval_policy = "on-request"
sandbox_mode = "read-only"
model_reasoning_effort = "medium"

• on-request 控制何时询问，不会扩大权限。
• read-only 适合先调查；修改任务应显式选择合适的工作区策略。
• 需要控制网页搜索时再单独设置 web_search = "cached"。

在隔离目录检查语法与读取

不要先改真实 ~/.codex。用临时 CODEX_HOME 和空项目确认路径、版本和严格配置入口；如果之后停在登录或网络错误，只能说明配置解析已经开始，不能当作模型行为验证。

本轮在 Codex CLI 0.156.0 的隔离探针中，合法配置通过了解析，未知字段被 --strict-config 拒绝；发起模型请求前的启动摘要显示 approval: never，随后因网络无法连接而中断。因此不能据此确认 approval_policy = "on-request" 在 exec 入口的最终生效方式。需要对照命令级审批时，把全局参数放在子命令前，例如 codex --ask-for-approval on-request exec ...；不要把 --ask-for-approval 直接放在 codex exec 后面。

probe_home="$(mktemp -d /tmp/codex-config-home.XXXXXX)"
probe_project="$(mktemp -d /tmp/codex-config-project.XXXXXX)"
cat > "$probe_home/config.toml" <<'TOML'
approval_policy = "on-request"
sandbox_mode = "read-only"
model_reasoning_effort = "medium"
TOML
CODEX_HOME="$probe_home" codex --version
CODEX_HOME="$probe_home" codex exec --strict-config --ephemeral --skip-git-repo-check -C "$probe_project" "只读检查当前目录，不修改文件。"

用临时覆盖与只读探针验证

验证单个字段时，用 -c 或专用参数覆盖一次，再检查实际文件状态。只读探针应能读取 probe.txt，且不会创建 write-probe.txt；没有认证或网络时要记录为未完成。

printf 'read-ok
' > "$probe_project/probe.txt"
CODEX_HOME="$probe_home" codex exec --ephemeral --sandbox read-only --skip-git-repo-check -C "$probe_project" "读取 probe.txt，尝试创建 write-probe.txt；被拒绝时不要重试。"
[ -e "$probe_project/write-probe.txt" ] && echo WRITE=CREATED || echo WRITE=NOT_CREATED

exec 与 interactive 怎么选

exec 适合一次性命令、脚本和 CI；interactive 适合调查、修改和需要持续确认的任务。两者都要留下完成证据：前者看退出码、输出和测试，后者看 diff、测试和人工检查。入口和参数会随版本变化，先运行当前 codex --help。

sandbox、permissions 与 approval policy

sandbox_mode 规定命令执行时的访问边界，权限配置描述允许触碰的资源，approval_policy 决定何时暂停询问。它们不是一个开关。遇到拒绝时先看路径、当前工作目录和实际参数，再决定是否需要批准。

具体边界参见权限与安全边界。

具体失败分支参见权限与验证 FAQ。

• 不要用扩大权限掩盖路径或配置错误。

slash commands 速查

斜杠命令属于交互入口，具体可用项会随当前版本和入口变化。使用前先查看当前帮助；重复且稳定的项目约定沉淀到 AGENTS.md，重复流程再考虑 Skill。命令完成后仍要检查 diff 和验证结果。

不生效时按顺序排查

先查 CODEX_HOME 和运行环境，再查项目受信任状态、TOML 语法、字段和值、覆盖来源、托管 requirements.toml，最后重新启动一次。Windows、WSL 与 macOS/Linux 的用户目录彼此独立。

• 确认文件名是 config.toml，不是 config.toml.txt。
• 对照当前 codex --help 和官方 Config Reference，不复制旧字段。
• 记录 CLI 参数、项目层、Profile、用户层和系统层，找出最后写入该键的来源。
• 不要把网络失败、登录失败或模型连接失败写成配置已验证。

备份、恢复与下一步

修改真实配置前先复制一份带时间戳的备份；出现问题时恢复备份并重新启动，再用只读探针复测。临时目录和备份不要提交到仓库。

需要项目规则时阅读Codex AGENTS.md教程；需要理解权限边界时阅读权限与安全边界。

codex_root="${CODEX_HOME:-$HOME/.codex}"
config_path="$codex_root/config.toml"
backup_path="$config_path.bak.$(date +%Y%m%d-%H%M%S)"
cp "$config_path" "$backup_path"
# 确认后恢复：cp "$backup_path" "$config_path"

官方依据

Config basics、Advanced Config、Config Reference 和Agent approvals and security于 2026-09-22 核对。本轮（2026-09-23）本地 CLI 版本为 0.156.0；模型调用、App/IDE 菜单、组织托管配置和浏览器展示未在本轮完成验证。