Codex config.toml 配置：文件放哪里、谁优先、哪些示例才安全

Codex config.toml 最先要解决的不是“复制哪段配置”，而是“这个设置应该归谁管”。个人默认值放在 ~/.codex/config.toml，可信仓库策略放在 .codex/config.toml，只试一次的模型或权限变化用命令行覆盖，重复使用的 CLI 模式再放进 profile。

不要把 API key、bearer token 或 auth.json 写进共享项目配置。OpenAI 的 Codex 配置、MCP、认证和沙盒文档已按 2026 年 4 月 21 日重新核对；下面的 CLI 命令也按本机 codex-cli 0.121.0 的帮助输出确认过。

先决定配置层，而不是先打开文件

如果你还没分清 ChatGPT 订阅和 API key 该走哪条路线，先看 Codex API key 与订阅区别。如果问题其实是额度或限制，看 Codex 使用限制指南。

优先级：冲突时到底谁赢

当前 Codex 配置优先级从强到弱是：

所以“我改了 config.toml 但没生效”通常不是 Codex 忽略文件，而是别的层级正在赢。先查当前命令有没有 alias、--config 或 --profile，再查当前目录和项目 trust 状态。

个人配置：只放跟你有关的默认值

个人配置适合放模型、审批策略、沙盒偏好和本机凭据存储方式。保持短小比复制完整模板更稳：

toml
#:schema https://developers.openai.com/codex/config-schema.json

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
allow_login_shell = false
cli_auth_credentials_store = "keyring"

这段意思很明确：默认用当前 Codex 模型，普通工作允许写工作区，高风险动作仍要确认，登录 shell 默认关闭，认证凭据尽量交给系统 keyring。它没有把 token 写死，也没有给整台机器开全权限。

项目配置：写共享策略，不写私人状态

项目配置应该保守。它可以告诉 Codex 这个仓库的规则、默认沙盒和项目专用说明，但不应该保存你的私密路由、账号 token 或本机路径。

toml

#:schema https://developers.openai.com/codex/config-schema.json

approval_policy = "untrusted"
sandbox_mode = "workspace-write"
allow_login_shell = false

developer_instructions = """
Follow this repository's AGENTS.md.
Keep generated assets in the documented publish paths.
Do not commit credentials, auth state, or provider tokens.
"""

尤其不要把 danger-full-access 和 approval_policy = "never" 当成共享默认值。danger-full-access 会关闭沙盒；如果再不提示确认，就等于把高信任自动化放进仓库策略。只有在隔离、可丢弃、明确授权的环境里，这类设置才有意义。

MCP、模型和 provider：示例要短，密钥要间接

配置 MCP 时，先用 helper：

bash
codex mcp add docs --env DOCS_TOKEN="$DOCS_TOKEN" -- node ./mcp/docs-server.mjs
codex mcp get docs --json

直接写 TOML 时，secret 也要通过环境变量进来：

toml
[mcp_servers.docs]
command = "node"
args = ["./mcp/docs-server.mjs"]
env_vars = ["DOCS_TOKEN"]
startup_timeout_sec = 10
tool_timeout_sec = 60
required = true

模型默认值也一样：稳定长期使用再写进文件，只试一次就用命令。

bash
codex --model gpt-5.4-mini
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true

openai_base_url 可以让内置 OpenAI provider 走代理、网关或特定 endpoint，但这只是请求路由，不等于自动改变订阅、API 计费或 workspace 政策。

沙盒、审批和 profile

日常本地开发通常从 workspace-write + on-request 开始：Codex 能改当前工作区，但高风险动作仍会停下来确认。代码审查或只读排查可以用 read-only。共享项目里要谨慎使用宽权限。

Profile 适合重复使用的 CLI 预设：

toml
[profiles.review]
model = "gpt-5.4"
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.local_edit]
model = "gpt-5.4-mini"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

然后执行：

bash
codex --profile review

注意：OpenAI 当前把 profiles 标为 experimental，并说明 IDE extension 不支持它。也就是说，profile 是 CLI 便利功能，不是所有 Codex 表面的通用策略。

配置没生效时按这个顺序查

如果你的问题是桌面控制、浏览器权限或应用交互，不要把它全塞进 config.toml。那是另一条权限路径，可以看 Codex Computer Use 指南。

FAQ

Codex 配置文件到底在哪？

用户配置默认是 ~/.codex/config.toml。可信项目可以有 .codex/config.toml。系统级默认可以是 /etc/codex/config.toml。

API key 应该写进 config.toml 吗？

不要写进共享项目配置。API key、bearer token 和 auth.json 应该放在环境变量、系统凭据存储或其它私密 secret 管理位置。

为什么项目里的 .codex/config.toml 没生效？

先查项目是否 trusted，再查当前目录、是否有更近的项目配置、是否选了 profile，以及命令里是否有 --config 或 flag 覆盖。

什么时候用 --config？

临时实验、一次性模型、临时沙盒变化、嵌套 key 测试都适合 --config。如果这个值变成长期习惯，再移到用户配置或 profile。

danger-full-access 可以用吗？

可以，但只应出现在已经隔离、可丢弃、明确需要宽权限的环境里。普通个人仓库或共享项目不应该把它当默认值。

官方 schema 在哪里？

当前 schema 是 https://developers.openai.com/codex/config-schema.json。支 持 schema hint 的编辑器可以在 TOML 顶部加入 #:schema https://developers.openai.com/codex/config-schema.json。