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

参考：Codex 配置基础、Codex 高级配置

Codex 走 OpenAI Responses API。接自定义网关时，用 [model_providers.<id>] 定义 endpoint，顶层 model 和 model_provider 决定实际调用。

1. 配置文件在哪

用户配置默认在 ~/.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

安全边界： 项目级配置不能修改 model_provider、认证相关项。Provider 定义必须写在用户级配置里。

2. 接入网关

字段	作用
`model`	模型 ID
`model_provider`	使用哪个 Provider
`[model_providers.<id>].base_url`	网关地址
`[model_providers.<id>].env_key`	从环境变量读取 API Key

2.1 最小配置

1
2
3
4
5
6
7
8
model = "zhipu/glm5.2"
model_provider = "llmapi"

[model_providers.llmapi]
name = "llmapi"
base_url = "https://api.xxx.com/v1"
wire_api = "responses"
env_key = "LLMAPI_KEY"

1
export LLMAPI_KEY=your-token

wire_api — 默认 "responses"，目前只支持 Responses API
env_key — 从环境变量读 Key，推荐方式

博文示例中的 api.xxx.com、your-token 均为占位符，请替换为自己的值，切勿将真实 Key 提交到公开仓库。

2.2 网关注意事项

2026 年起 Codex 只走 OpenAI Responses API，不支持 wire_api = "chat"
endpoint 只有 Chat Completions 时会 404 或空流，需网关提供 Responses 兼容面（如 LiteLLM）
模型 ID 以网关文档为准

2.3 内置 OpenAI 改代理地址

只给官方 OpenAI 换 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. 多模型配置

Codex 用 Profile 按场景切换模型，命名规则：~/.codex/<profile>.config.toml。

3.1 默认 + Profile

1
2
3
4
5
6
7
8
9
# ~/.codex/config.toml
model = "zhipu/glm5.2"
model_provider = "llmapi"

[model_providers.llmapi]
name = "llmapi"
base_url = "https://api.xxx.com/v1"
wire_api = "responses"
env_key = "LLMAPI_KEY"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# ~/.codex/glm.config.toml
model = "zhipu/glm5.2"
model_provider = "llmapi"

# ~/.codex/deepseek-v4-pro.config.toml
model = "deepseek/deepseek-v4-pro"
model_provider = "llmapi"

# ~/.codex/deepseek-v4-flash.config.toml
model = "deepseek/deepseek-v4-flash"
model_provider = "llmapi"

Profile	模型	用途
默认	GLM 5.2	日常使用
`deepseek-v4-pro`	DeepSeek V4 Pro	重度编码
`deepseek-v4-flash`	DeepSeek V4 Flash	快速、省成本

Profile 文件只写与默认不同的项即可，Provider 定义放在 config.toml 里共用。

1
2
3
4
codex                                    # 默认 GLM 5.2
codex --profile deepseek-v4-pro          # 切 Pro
codex --profile deepseek-v4-flash        # 切 Flash
codex exec --profile deepseek-v4-pro "review this change"

注意： 旧版 profile = "xxx" 和 [profiles.xxx] 写法已废弃，改用 --profile + 独立文件。

3.2 单次覆盖

1
2
codex --model deepseek/deepseek-v4-pro
codex --config model_reasoning_effort='"xhigh"' "review 这个 PR"

4. 模型行为调优

1
2
3
model_reasoning_effort = "medium"   # low / medium / high / xhigh
model_verbosity = "low"            # 缩短回复
model_reasoning_summary = "none"   # 关闭推理摘要

5. MCP 与沙箱

5.1 MCP Server

1
2
3
[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]

~/.codex/AGENTS.md 放跨项目通用规则；仓库根目录 AGENTS.md 放项目级指引。

5.2 项目信任与沙箱

1
2
3
4
5
6
7
8
[projects."/Users/me/Code/my-repo"]
trust_level = "trusted"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

6. 使用技巧

6.1 日常开发

日常默认 GLM 5.2，重度编码用 --profile deepseek-v4-pro
codex exec 适合脚本和 CI 非交互执行

6.2 排错 checklist

现象	常见原因
404 / 空流	endpoint 不支持 Responses API
Key 无效	`LLMAPI_KEY` 未 export
Profile 不生效	仍在用废弃的 `[profiles.xxx]` 写法
项目 MCP 不生效	项目未标记 `trusted`
本地模型不编辑文件	模型不支持 tool calling

7. 完整示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# ~/.codex/config.toml
model = "zhipu/glm5.2"
model_provider = "llmapi"
model_reasoning_effort = "medium"

[model_providers.llmapi]
name = "llmapi"
base_url = "https://api.xxx.com/v1"
wire_api = "responses"
env_key = "LLMAPI_KEY"

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]

1
2
3
# ~/.codex/deepseek-v4-pro.config.toml
model = "deepseek/deepseek-v4-pro"
model_provider = "llmapi"

1
2
3
# ~/.codex/deepseek-v4-flash.config.toml
model = "deepseek/deepseek-v4-flash"
model_provider = "llmapi"

1
2
3
4
export LLMAPI_KEY=your-token
codex                              # GLM 5.2
codex --profile deepseek-v4-pro    # Pro
codex exec --profile deepseek-v4-flash "生成 CHANGELOG"

8. 其他 Provider

以下场景需单独配置 Provider，写法见 Codex 官方文档：

Provider	要点
OpenRouter	`base_url = "https://openrouter.ai/api/v1"`，一个 Key 访问多模型
Azure OpenAI	`query_params = { api-version = "..." }`，`model` 填 deployment name
Ollama 本地	`base_url = "http://localhost:11434/v1"`，配合 `codex --oss`
DeepSeek 直连	`base_url = "https://api.deepseek.com"`，需确认 Responses 兼容