Codex 高级配置：多配置档、模型与提供商

这篇适合谁

适合已经在用 Codex、想管理几套不同设置的读者：比如一个专门做深度审查的配置档，换一个模型提供商，接入本地模型，或者收紧审批。读完，你能把配置拆成多个 profile，为单次运行做临时覆盖，添加自定义提供商，并弄清项目配置和用户配置之间的关系。

配置放在哪里

Codex 把本地状态存在 CODEX_HOME 下，默认是 ~/.codex。主配置文件是 config.toml。使用文件方式保存凭据时会有 auth.json^[1]。认证细节和完整的配置项，请以官方页面为准^[1]。

Profile：切换不同的设置

Profile 是一个有名字的配置层。运行 --profile profile-name 时，Codex 先加载 ~/.codex/config.toml，再叠加 ~/.codex/profile-name.config.toml^[1]。名字可以包含字母、数字、连字符和下划线。每个 profile 单独写成一个文件，顶层直接写配置项，不要写成 [profiles.profile-name] 表^[1]。Profile 位于用户基础配置之上、项目和命令行配置之下，所以只需要写和基础配置不同的值^[1]。

下面是一个深度审查用的 profile 示例。示例使用的模型需要账号有访问权限，没有的话换成你能用的模型^[1]。

# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

运行方式如下^[1]：

codex --profile deep-review
codex exec --profile deep-review "review this change"

从 Codex 0.134.0 起，--profile 不再读取 config.toml 里的 [profiles.profile-name]，顶层的 profile = "profile-name" 选择器也不再支持。旧的 profile 表要移到 profile 文件里，然后删掉原来的表和选择器^[1]。

单次运行的临时覆盖

只为一次运行改设置时，有专门参数的优先用专门参数，比如 --model。其他任意键用 -c 或 --config。这些值按 TOML 解析，解析不了的会被当作字符串^[1]。嵌套的键可以用点号写，比如 mcp_servers.context7.enabled=false^[1]。

项目配置与信任

Codex 还会读取仓库里的 .codex/config.toml。它从项目根目录一路走到当前目录，把途经的每个文件都加载进来^[1]。项目配置只在项目被信任时生效。在未信任的项目里，Codex 会忽略 .codex/ 下的各层配置，包括项目级钩子和规则^[1]。

有些键只能写在用户配置里。项目文件中的 model_provider、model_providers、notify、profile、profiles、otel、openai_base_url 和 chatgpt_base_url 会被忽略，启动时还会给出警告^[1]。默认情况下，含有 .git 的目录被视为项目根目录；project_root_markers 可以改变用哪些标记判断^[1]。

接入自定义模型提供商

提供商定义了基础 URL、wire API、认证方式以及可选的请求头。自定义提供商需要一个唯一的 ID，openai、ollama、lmstudio 等内置 ID 已被保留^[1]。把提供商写成表，再让 model_provider 指向其中一个^[1]：

model = "gpt-6.1-sol"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

env_key 指定保存提供商密钥的环境变量名^[1]。想改内置 openai 提供商的基础 URL，应设置 openai_base_url，而不是新建 [model_providers.openai]，因为内置 ID 不能被覆盖^[1]。

model_verbosity 只对使用 Responses API 的提供商生效，Chat Completions 类提供商会忽略它^[1]。

用 `--oss` 跑本地模型

运行 codex --oss 时，Codex 会连接 Ollama 或 LM Studio 这类本地提供商。单次运行可以用 --local-provider 指定，也可以用 oss_provider 设置默认值^[1]。两者都没设时，交互式 CLI 会让你选择，而 codex exec 会直接报错退出^[1]。

审批与沙箱

审批策略决定 Codex 什么时候暂停，沙箱决定文件和网络访问范围。下面的示例把 approval_policy 设为 on-request，审批交给用户处理，并使用 workspace-write^[1]：

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for Auto-review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

approval_policy 可以取 on-request、never，或一个 granular 表。Codex 和 ChatGPT Work 已不再支持 "untrusted"^[1]。设置 approvals_reviewer = "auto_review" 后，符合条件的审批请求会交给 Auto-review 处理^[1]。

在 workspace-write 模式下，某些环境会把 .git/、.agents/、.codex/ 和 .aws/ 保持为只读。所以 git commit 这类命令在沙箱外运行时，仍可能需要审批^[1]。下面这张表里的 network_access 用来开启出站网络访问^[1]：

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

sandbox_mode = "danger-full-access" 会完全关闭沙箱。官方说明只应在你的环境本身已经隔离了进程时使用^[1]。

什么时候用 `--oss`

如果你想用本地模型而不是云端接口，可以用 --oss。它会连接 Ollama 或 LM Studio 这类本地提供商。想固定使用某一个，就在配置里写 oss_provider；否则每次都要在运行时指定，而在 codex exec 里不指定会直接报错^[1]。

配置叠加的顺序

配置由几层组成。用户的 config.toml 是基础；--profile 指定的 profile 文件叠加在它上面；项目里的 .codex/config.toml 和命令行参数又在 profile 之上^[1]。所以 profile 只需要写和基础配置不同的部分，而命令行上的 --config 会压过下层的同名键^[1]。

配置不生效时的排查

先看项目是否被信任。不可信的项目会忽略 .codex/ 下的所有层^[1]。再看键放在哪里。model_provider、profile、notify 这类键写进项目文件会被忽略，启动时还会给出警告，应该移到 ~/.codex/config.toml 里^[1]。最后看 profile 的写法。如果还在用 [profiles.profile-name] 表，0.134.0 之后不再读取它，需要迁移到单独的 profile 文件^[1]。

把几类设置组合起来

实际使用时，可以把设置分层放置。profile 适合放一组成套的偏好，比如模型、推理强度和审批策略；提供商的定义放在用户配置里，因为项目文件不能修改它；沙箱的细节则放在能看清楚的地方，方便审查^[1]。同一个仓库里，团队共享的项目配置只放不涉及密钥和提供商的设置，个人偏好留给 profile 和命令行参数^[1]。