参考：Codex 配置基础、Codex 高级配置
1. 配置文件在哪
Codex 的用户配置默认在 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml）。
配置优先级（高 → 低）：
- CLI 参数（
--model、--config 等） - 项目配置
.codex/config.toml（仅 trusted 项目生效） - Profile 文件
~/.codex/<profile>.config.toml（通过 --profile 激活） - 用户配置
~/.codex/config.toml - 系统配置
/etc/codex/config.toml
安全边界： 项目级 .codex/config.toml 不能 修改 model_provider、model_providers、认证相关项。克隆的仓库无法悄悄把你的请求转发到第三方 endpoint，Provider 定义必须写在用户级配置里。
2. 自定义模型 Provider
Codex 通过 [model_providers.<id>] 定义第三方 endpoint。顶层两个键决定实际调用：
model — 模型 IDmodel_provider — 使用哪个 Provider
2.1 最小配置
1
2
3
4
5
6
7
| model = "your-model-id"
model_provider = "custom"
[model_providers.custom]
name = "Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"
|
base_url — API 地址，必填env_key — 从环境变量读取 API Key，推荐方式wire_api — 默认 "responses"，目前只支持 Responses API，可省略
设置 API Key：
1
| export CUSTOM_API_KEY="sk-..."
|
2.2 wire_api 注意事项
2026 年起 Codex 只走 OpenAI Responses API，不再支持 wire_api = "chat"。
如果 endpoint 只有 Chat Completions（很多自建网关、旧版 Ollama），直接配会 404 或空流。需要在中间加一层转换网关，例如 LiteLLM、OpenRouter 的 Responses 兼容面。
2.3 内置 OpenAI 改代理地址
只是给官方 OpenAI Provider 换 base URL，不需要新建 Provider：
1
2
| openai_base_url = "https://us.api.openai.com/v1"
model = "gpt-5.5"
|
不能 创建 [model_providers.openai]，openai、ollama、lmstudio 是保留 ID。
3. 常见 Provider 配置
3.1 OpenRouter
一个 Key 访问多种模型：
1
2
3
4
5
6
7
| model = "anthropic/claude-sonnet-4.6"
model_provider = "openrouter"
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
|
1
| export OPENROUTER_API_KEY="sk-or-v1-..."
|
3.2 Azure OpenAI
Azure 通过 api-version 查询参数做版本控制：
1
2
3
4
5
6
7
8
| model = "gpt-5.5"
model_provider = "azure"
[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
|
model 填 Azure 上的 deployment name，不是模型系列名。
3.3 本地 Ollama
1
2
3
4
5
6
| model = "qwen3.5-coder"
model_provider = "local-ollama"
[model_providers.local-ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
|
本地启动：
1
2
| ollama pull qwen3.5-coder
codex --oss
|
--oss 走本地开源 Provider 流程；也可在配置里设 oss_provider = "ollama"。
3.4 DeepSeek
1
2
3
4
5
6
7
| model = "deepseek-chat"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
|
若 endpoint 不接受 Responses API，同样需要通过网关转发。
3.5 企业内网网关
静态 Header + 环境变量 Key：
1
2
3
4
5
6
7
8
| model = "internal-coder"
model_provider = "gateway"
[model_providers.gateway]
name = "Internal LLM Gateway"
base_url = "https://llm-gateway.internal.example.com/v1"
env_key = "INTERNAL_LLM_KEY"
http_headers = { "X-Team" = "platform" }
|
短效 Token 用 command 认证（不能与 env_key 同时使用）：
1
2
3
4
5
| [model_providers.gateway.auth]
command = "get-llm-token"
args = ["--scope", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000
|
4. Profile：按场景切换模型
Profile 是独立的 overlay 配置文件，命名规则：~/.codex/<profile>.config.toml。
1
2
3
4
5
6
7
8
| # ~/.codex/deepseek.config.toml
model = "deepseek-chat"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
|
1
2
3
4
5
6
7
| # ~/.codex/local.config.toml
model = "qwen3.5-coder"
model_provider = "local-ollama"
[model_providers.local-ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
|
切换使用：
1
2
3
| codex --profile deepseek "批量重命名 userId 为 user_id"
codex --profile local --oss "解释这个模块"
codex exec --profile deepseek "review this change"
|
Profile 文件只写与默认配置不同的项即可。Provider 定义可以放在 Profile 里，也可以全部放在 config.toml，Profile 只改 model 和 model_provider。
注意： 旧版 profile = "xxx" 和 [profiles.xxx] 写法已废弃，改用 --profile + 独立文件。
5. 模型行为调优
在 config.toml 里调整推理和输出：
1
2
3
4
| model = "gpt-5.5"
model_reasoning_effort = "medium" # low / medium / high / xhigh
model_verbosity = "low" # 缩短回复，仅 Responses API 生效
model_reasoning_summary = "none" # 关闭推理摘要
|
单次覆盖，不必改文件：
1
2
3
| codex --model gpt-5.5
codex --config model_reasoning_effort='"xhigh"' "review 这个 PR"
codex --config sandbox_workspace_write.network_access=true "跑集成测试"
|
6. MCP 与 AGENTS.md
6.1 接入 MCP Server
在 config.toml 里声明 MCP，Codex 启动时自动拉起：
1
2
3
| [mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]
|
带环境变量的 MCP：
1
2
3
4
| [mcp_servers.morph]
command = "npx"
args = ["-y", "@morphllm/morphmcp"]
env = { "MORPH_API_KEY" = "your-key" }
|
单次禁用某个 MCP：
1
| codex --config mcp_servers.codegraph.enabled=false
|
6.2 AGENTS.md
~/.codex/AGENTS.md 是全局项目指引，Codex 进入仓库时会读取。适合放跨项目的通用规则，例如：
1
2
3
4
| ## CodeGraph
在存在 `.codegraph/` 目录的仓库里，理解代码结构时优先用 CodeGraph MCP，
不要先用 grep 扫全库。
|
项目级指引放在仓库根目录的 AGENTS.md，Codex 从工作目录向上查找项目根（默认以 .git 为标记）。
7. 项目信任与沙箱
标记 trusted 项目后，Codex 才会加载项目内的 .codex/config.toml、hooks、rules：
1
2
| [projects."/Users/me/Code/my-repo"]
trust_level = "trusted"
|
沙箱相关常用项：
1
2
3
4
5
6
| approval_policy = "on-request" # untrusted / on-request / never
sandbox_mode = "workspace-write" # 仅写工作区
[sandbox_workspace_write]
network_access = false # 默认禁网，需要时改为 true
writable_roots = ["/Users/me/.pyenv/shims"]
|
需要完全放开（仅在已隔离环境使用）：
1
| sandbox_mode = "danger-full-access"
|
8. 使用技巧
8.1 日常开发
- 大任务用 Profile 分流：日常写代码走 OpenAI 默认配置；批量重构、文档生成切
--profile deepseek 省成本 - 开始实现前清上下文：复杂任务开新 session，把设计文档、计划文件当作结构化上下文，不必把全部聊天历史塞进去
- 项目级
.codex/config.toml 放团队共识：MCP、沙箱策略、排除路径等，Provider 和 Key 仍放用户级
8.2 CLI 技巧
1
2
3
4
5
6
7
8
| # 非交互执行，适合脚本和 CI
codex exec "fix the failing tests"
# 查看当前读到的配置
cat ~/.codex/config.toml
# 指定 CODEX_HOME（多账号隔离）
CODEX_HOME=~/.codex-work codex
|
8.3 排错 checklist
| 现象 | 常见原因 |
|---|
| 启动即 404 / 空流 | endpoint 不支持 Responses API |
| Key 无效 | env_key 对应的环境变量未 export |
| 项目 MCP 不生效 | 项目未标记 trusted |
| Profile 不生效 | 仍在用废弃的 profile = "xxx" 写法 |
| 本地模型不编辑文件 | 模型不支持 tool calling |
8.4 与 Cursor 的分工
Codex CLI 适合终端内长任务、脚本化执行（codex exec）、企业内网网关场景。Cursor 适合 IDE 内联编辑、多文件 diff 可视化。两者可以共用 MCP 配置思路，但配置文件路径不同（Codex 用 ~/.codex/config.toml，Cursor 用 ~/.cursor/mcp.json）。
9. 完整示例
一个兼顾默认 OpenAI、便宜模型、本地模型的用户级配置：
1
2
3
4
5
6
7
8
9
10
| # ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
[projects."/Users/me/Code"]
trust_level = "trusted"
[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]
|
1
2
3
4
5
6
7
8
| # ~/.codex/deepseek.config.toml
model = "deepseek-chat"
model_provider = "deepseek"
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"
|
日常使用：
1
2
3
| codex # 默认 gpt-5.5
codex --profile deepseek # 切 DeepSeek
codex exec --profile deepseek "生成 CHANGELOG"
|
