Codex 自定义模型配置与使用技巧

参考：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 — 模型 ID
model_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"