Run GLM 5.2 in Codex CLI with OpenRouter

Keep your default Codex model intact, add GLM 5.2 as an opt-in profile, and verify routing in OpenRouter logs

Codex CLI gives you the freedom to choose.

GLM 5.2 is the all rage lately. Everyone talks about it and wants to use it, but some folk (myself included) just don’t want to get out of their comfort zone, similar to fellow Codex CLI aficionados who’s become quite nimble with it and its myriad features (e.g. hooks, steering, goals, skills) and don’t necessarily want to switch to a different harness (e.g. OpenCode, Kilo Code) on a whim.

Lucky for us, Codex CLI has always allowed custom/third-party models (e.g. GLM 5.2, Kimi K2.7, MiniMax M3) to be used inside the harness, made even easier with OpenRouter’s BYOK functionality.

And yes, this means your existing configuration and AGENTS.md can be reused with models other than GPT 5.5. Little to no hassle.

[embed]Advanced Configuration - Codex | OpenAI Developers More advanced configuration options for Codex local clientsdevelopers.openai.com

This guide is fairly straightforward, so let’s onto the good bits.

I’ll show how to run GLM 5.2 inside OpenAI Codex CLI through OpenRouter, without replacing your normal Codex default model.

This will be the end result.

The setup uses two files:

~/.codex/config.toml
~/.codex/glm52.config.toml

The main config keeps your usual Codex defaults. The GLM profile is selected only when you run:

codex --profile glm52

This is the cleanest pattern for heavy CLI use. It keeps your default model available through codex, while giving you a separate GLM 5.2 lane for long-context coding work.

No extra configuration to maintain. All your existing configuration (e.g. hooks) are preserved and get invoked as usual.

What this setup gives you

GLM 5.2 is available on OpenRouter as z-ai/glm-5.2. OpenRouter lists it as a Z.ai reasoning model with text input/output, a 1M-token context window, and support for high and xhigh reasoning effort. OpenRouter also notes that xhigh maps to max reasoning for this model.

It’s an agentic coder’s dream come true (for the most part)

Why use OpenRouter?

Codex can talk to custom model providers through a model_providers.<id> block. A provider entry defines the base URL, authentication environment variable, and wire protocol. Codex’s current config reference lists responses as the supported provider wire API.

OpenRouter is useful because it gives you one local provider entry:

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"

After that, model switching is usually just a profile change:

model = "z-ai/glm-5.2"

Any provider that exposes a Codex-compatible Responses API can use the same general pattern. OpenRouter is convenient because it centralises model routing, provider failover, usage visibility, and model flexibility behind one API endpoint.

OpenRouter’s BYOK support (which I mentioned earlier) is also useful. You can add your own upstream provider keys inside OpenRouter, including multiple keys for the same provider. OpenRouter can try prioritised keys first, fall through to other matching keys, or fall back to shared OpenRouter capacity depending on your settings.

The practical architecture is:

Codex CLI
  -> OpenRouter provider
    -> z-ai/glm-5.2
    -> optional BYOK key
    -> OpenRouter logs

Step 1: Set your OpenRouter API key

Create an OpenRouter API key. It normally starts with:

sk-or-

Set it in your shell environment.

macOS, Linux, or WSL with Zsh

echo 'export OPENROUTER_API_KEY="sk-or-your-key-here"' >> ~/.zshrc
source ~/.zshrc

macOS, Linux, or WSL with Bash

echo 'export OPENROUTER_API_KEY="sk-or-your-key-here"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell

setx OPENROUTER_API_KEY "sk-or-your-key-here"

Close and reopen PowerShell after running setx.

Check that the variable is visible:

echo $OPENROUTER_API_KEY

PowerShell:

$env:OPENROUTER_API_KEY

Keep the key out of config.toml. Codex supports env_key so provider secrets can live in environment variables rather than plain config files.

Step 2: Keep your normal Codex defaults in ~/.codex/config.toml

Open your user-level Codex config:

mkdir -p ~/.codex
vi ~/.codex/config.toml

Use this shape:

# ~/.codex/config.toml
# Normal Codex defaults stay here.

model_provider = "openai"
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
stream_idle_timeout_ms = 600000
request_max_retries = 4

Replace gpt-5.5 with your normal Codex model if needed. The important part is that GLM 5.2 is not made global here.

Codex stores user-level configuration at ~/.codex/config.toml. Profile files sit next to it and are selected with --profile profile-name. Project-local .codex/config.toml files cannot override provider keys such as model_provider or model_providers, so the OpenRouter provider block belongs in the user-level file.

Hint: You can register multiple providers, not just OpenRouter. Fireworks supports the Responses API, so it’s okay to be used.

Step 3: Create the GLM 5.2 profile

Create the profile file:

vi ~/.codex/glm52.config.toml

Use this version for a safe daily-driver setup:

# ~/.codex/glm52.config.toml
# GLM 5.2 via OpenRouter.

model_provider = "openrouter"
model = "z-ai/glm-5.2"
model_context_window = 1000000
model_auto_compact_token_limit = 900000
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Codex documents model_context_window as the active model context size and model_auto_compact_token_limit as the threshold that triggers automatic history compaction.

Use xhigh, not max, for reasoning effort. Codex documents the valid reasoning effort values as minimal, low, medium, high, and xhigh; OpenRouter’s GLM 5.2 page says xhigh maps to max reasoning for GLM 5.2.

Power-user profile

For trusted local repos, a less restricted profile can be useful:

# ~/.codex/glm52.config.toml
# GLM 5.2 via OpenRouter.
# Use only where unrestricted local execution is intentional.

model_provider = "openrouter"
model = "z-ai/glm-5.2"
model_context_window = 1000000
model_reasoning_effort = "xhigh"
approval_policy = "never"
sandbox_mode = "danger-full-access"

Codex documents approval_policy = "never" as a mode where Codex does not pause for approval prompts. It also documents danger-full-access as one of the supported sandbox modes for command execution.

Use this profile only when the repo, command surface, and local environment are trusted. The safer default is:

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

Step 4: Run GLM 5.2 in Codex CLI

From a project directory:

cd /path/to/your/project
codex --profile glm52

Start with a read-only prompt:

Summarise this repository. Do not modify files. Do not run install commands.

And summarise it does.

For non-interactive mode:

codex exec --profile glm52 "Identify the project language, test command, and build command. Do not edit files."

And yes, non-interactive mode works fine too.

The default Codex command remains unchanged:

codex

The GLM route is opt-in:

codex --profile glm52

Codex’s config precedence loads selected profile files above user config, so the GLM profile overrides only the active run where --profile glm52 is passed.

Hint: you can create profiles just as easily for a variety of custom models (not just GLM 5.2). Just ensure that the provider supports the Responses API), e.g. DeepSeek V4 Flash (thru OpenRouter):

Yep, THAT DeepSeek.

And you can prompt it just as you would GLM 5.2.

Step 5: Verify routing in OpenRouter logs

Do not rely only on the local Codex UI.

Open:

https://openrouter.ai/logs

OpenRouter’s Codex CLI guide recommends checking the activity dashboard to confirm request routing, token counts, and model usage.

I set up BYOK for both Z.ai and NovitaAI, both GLM 5.2 providers. Notice how OpenRouter simply routes the requests to the providers I’ve hooked in and provides me a unified dashboard?

About the model metadata warning

Codex may print something like:

Model metadata for `z-ai/glm-5.2` not found.
Defaulting to fallback metadata; this can degrade performance and cause issues.

This warning means Codex does not have bundled local metadata for the exact OpenRouter model slug. The profile’s model_context_window = 1000000 gives Codex an explicit context size, which is usually enough for a practical CLI workflow.

Codex also supports model_catalog_json, but it is an advanced path. The config reference describes it as a JSON model catalogue loaded on startup, and notes that profile files can override it. Use it only when you specifically need custom model catalogue behaviour. Otherwise, simply ignore the warnings.

Codex Desktop App constraint

Codex Desktop is available on macOS and Windows, and the normal app flow is to select a project, choose Local, and start a thread.

At the moment, the Desktop app should not be treated as the primary interface for this custom-provider workflow. Current public reports describe a limitation where custom providers work through CLI/TUI config, but Desktop does not expose a fully provider-aware custom model picker. The same report specifically references OpenRouter custom-provider usage with z-ai/glm-5.2.

My recommendation:

The CLI profile path is currently the clean path.

There is, however, the option to use codex-shim in the interim, but that warrants a guide of its own.

[embed]GitHub - sybil-solutions/codex-shim: Local Responses-API shim that exposes Factory BYOK models (and… Local Responses-API shim that exposes Factory BYOK models (and optional ChatGPT GPT-5.5 passthrough) to Codex Desktop…github.com

Subagents are already enabled

No extra feature flag is needed for subagents in current Codex.

You don’t even need this:

[features]
multi_agent = true

Codex’s config reference says features.multi_agent enables tools such as spawn_agent, send_input, resume_agent, wait_agent, and close_agent, and that it is stable and on by default.

The default subagent limits are also already sensible:

[agents]
max_threads = 6
max_depth = 1

agents.max_threads defaults to 6, and agents.max_depth defaults to 1, which allows direct child agents while preventing deeper recursive fan-out.

Custom agents can also inherit settings such as model, model_reasoning_effort, and sandbox_mode from the parent session when those fields are omitted.

A useful verification prompt:

Spawn two explorer agents. Have one inspect the build and test setup, and the other inspect the project architecture. Do not modify files. Wait for both, then summarise.

Every now and then, you’ll see the Codex spawn parallel processes instead of native agents.

(Note: Newer versions of Codex CLI have had regressions wherein custom models don’t have access to the subagent spawning tool, and thus would spawn parallel processes as a substitute. You can follow the issue here.)

Then check OpenRouter Logs. Multiple GLM 5.2 requests usually indicate that subagents were actually spawned.

Final two-file setup

~/.codex/config.toml

# ~/.codex/config.toml
# Normal Codex defaults stay here.

model_provider = "openai"
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
stream_idle_timeout_ms = 600000
request_max_retries = 4

~/.codex/glm52.config.toml

Safe default:

# ~/.codex/glm52.config.toml
# GLM 5.2 via OpenRouter.

model_provider = "openrouter"
model = "z-ai/glm-5.2"
model_context_window = 1000000
model_auto_compact_token_limit = 900000
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Power-user version:

# ~/.codex/glm52.config.toml
# GLM 5.2 via OpenRouter.

model_provider = "openrouter"
model = "z-ai/glm-5.2"
model_context_window = 1000000
model_reasoning_effort = "xhigh"
approval_policy = "never"
sandbox_mode = "danger-full-access"

Run it:

codex --profile glm52

Run a non-interactive task:

codex exec --profile glm52 "Review this repo structure. Do not edit files."

Verify it:

https://openrouter.ai/logs

Troubleshooting

In summary

Use the main config for stable defaults:

~/.codex/config.toml

Use profile files for alternate models:

~/.codex/glm52.config.toml

Use OpenRouter logs as the source of truth:

https://openrouter.ai/logs

The day-to-day command remains:

codex

The GLM 5.2 command is explicit:

codex --profile glm52

That gives you GLM 5.2 when needed, your normal Codex model when not needed, and one OpenRouter provider entry for future model swaps.

And yes, it can pursue long horizon goals too!

Enjoy Codex-ing!

Related reading

[embed]The definitive guide to Codex CLI: from first install to production workflows Everything I've learned from writing 10+ Codex guides, now in one place; with infographics, copy-paste configs, and…ai.sulat.com

[embed]Codex hooks just gave you back complete control over your code. Codex hooks just gave you back complete control over your code. A practical walk-through of exit code 2, the three new…ai.sulat.com

[embed]One orchestrator, four specialists: building a multi-agent code review system with Codex One orchestrator, four specialists: building a multi-agent code review system with Codex How Codex App's subagent…ai.sulat.com