References: Codex Configuration Basics, Codex Advanced Configuration

Codex uses the OpenAI Responses API. When connecting to a custom gateway, define the endpoint with [model_providers.<id>], and the top-level model and model_provider determine the actual call.

1. Where the Configuration File Lives

The user configuration is at ~/.codex/config.toml by default (on Windows, %USERPROFILE%\.codex\config.toml).

Configuration precedence (high → low):

1. CLI arguments (--model, --config, etc.)
2. Project configuration .codex/config.toml (only takes effect for trusted projects)
3. Profile file ~/.codex/<profile>.config.toml (activated via --profile)
4. User configuration ~/.codex/config.toml
5. System configuration /etc/codex/config.toml

Security boundary: Project-level configuration cannot modify model_provider or authentication-related entries. Provider definitions must be written in the user-level configuration.

2. Connecting to a Gateway

2.1 Minimal Configuration

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 — defaults to "responses"; currently only the Responses API is supported
• env_key — reads the Key from an environment variable; the recommended approach

The api.xxx.com and your-token in this post’s examples are placeholders; replace them with your own values, and never commit a real Key to a public repository.

2.2 Gateway Caveats

• Since 2026, Codex only uses the OpenAI Responses API and does not support wire_api = "chat"
• If the endpoint only offers Chat Completions, you will get a 404 or an empty stream; the gateway must expose a Responses-compatible surface (such as LiteLLM)
• Model IDs are subject to the gateway’s documentation

2.3 Changing the Base URL for the Built-in OpenAI

To swap the base URL for official OpenAI only, there is no need to create a new Provider:

1
2

openai_base_url = "https://us.api.openai.com/v1"
model = "gpt-5.5"

You cannot create [model_providers.openai]; openai, ollama, and lmstudio are reserved IDs.

3. Multi-Model Configuration

Codex uses Profiles to switch models by scenario, with the naming rule ~/.codex/<profile>.config.toml.

3.1 Default + 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"

A Profile file only needs the entries that differ from the default; the Provider definition lives in config.toml and is shared.

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"

Note: The old profile = "xxx" and [profiles.xxx] syntax is deprecated; use --profile plus a separate file instead.

3.2 One-Off Overrides

1
2

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

4. Tuning Model Behavior

1
2
3

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

5. MCP and Sandbox

5.1 MCP Server

1
2
3

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

~/.codex/AGENTS.md holds cross-project general rules; AGENTS.md at the repository root holds project-level guidance.

5.2 Project Trust and Sandbox

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. Usage Tips

6.1 Everyday Development

• Default to GLM 5.2 day to day, and use --profile deepseek-v4-pro for heavy coding
• codex exec suits non-interactive execution in scripts and CI

6.2 Troubleshooting Checklist

7. Complete Example

 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. Other Providers

The following scenarios require configuring a Provider separately; see the official Codex documentation for the syntax: