How to Connect Codex CLI to Zhipu GLM via CCX Gateway
I run a terminal-first workflow: an SSH session to a Linux box, a second Windows machine on the desk, and a habit of living inside whichever coding agent I can drive from the shell. Codex CLI became my default for a while, mostly because it is a small binary that stays out of the way and because its agent loop is happy to edit files, run tests, and read back the failures. The part I never liked was the bill and the geography. On some days the API answered slowly, on others I burned through a monthly allowance in a week of refactoring. So I did the thing a lot of developers in Asia are doing right now: I pointed Codex CLI at Zhipu GLM and put CCX Gateway in the middle, so I could keep the interface I like and swap out the brain behind it.
This is the write-up of that setup, including the two hours I lost to a trailing slash and the twenty minutes I lost to the wrong model name.
A quick note on scope before we start. This is not a benchmark, and I am not going to pretend I ran one. What follows is the exact sequence of decisions I made on Windows, the environment variables that mattered, the errors I actually saw, and the honest set of trade-offs that showed up after a few weeks of daily use. Where a detail depends on the gateway’s current implementation, I say so instead of guessing, because these things change fast and a made-up flag is worse than no flag.
Why bother routing Codex CLI to GLM at all
Three reasons, in the order they mattered to me.
Cost predictability was first. A subscription or a metered frontier API is fine until you start running long agent loops that read ten files before they write one. Those loops are wonderful and they are also expensive, and the cost lands at the worst possible moment, which is in the middle of a sprint. Zhipu GLM gives me a way to keep the same workflow while shifting the bulk of the traffic onto a model family that, in my region, is simply cheaper to run and easier to pay for.
Latency and availability were second. Not raw speed on a benchmark, which I have not measured, but the everyday feeling of “will this request come back.” When the default route hiccups, having a second path through a domestic endpoint means my afternoon does not end because someone’s status page went yellow.
The third reason is the one people underestimate: context. Codex CLI is at its best when it can hold a decent chunk of a repository in view while it traces a call path. GLM’s current generation is friendly to that kind of work, and because the gateway exposes an OpenAI-compatible surface, the CLI does not need to know or care that the model underneath is different. Attaching GLM to Codex CLI is not a downgrade you tolerate. It is a configuration you choose, and the only real cost is that you now own one more moving part.
What CCX Gateway actually does
The cleanest way to think about it: Codex CLI speaks one dialect, Zhipu’s API speaks another, and CCX Gateway is the translator standing between them. You give the CLI a base URL that looks like a normal OpenAI-style endpoint, the gateway authenticates you with your Zhipu credentials, reshapes the request and the streaming response, and hands the answer back in a format the CLI already understands.
That reshaping is the whole point. Without it you would be patching the client, and patches rot. With it, the switch is configuration rather than code, which means you can point the same Codex CLI at GLM today and at something else next month by editing two lines.
Two practical consequences follow. First, the gateway is now part of your critical path: if it is down, so is your agent, and no amount of local configuration will save you. Second, the exact endpoints, request paths, and header names are the gateway’s business, not Codex CLI’s, and they do change. Whatever version of CCX Gateway you install, read its own README for the current endpoint list and treat my values below as a shape rather than gospel. The names of the environment variables are stable in the sense that the CLI reads them; the URLs are the part that drifts.
Before you touch anything: prerequisites
I would not start until all four of these are true.
First, a working Node.js toolchain. Codex CLI ships as an npm package and wants a modern LTS release; if node --version and npm --version both answer without complaint, you are probably fine, and if the install command below fails with a strange error, upgrading to the current LTS is the first thing to try. Some people install through other channels, and if you do, the config that follows is identical because it all lands in the same config file.
Second, a Zhipu account with an API key. Generate it in the console, copy it once, and treat it like a password: it goes in an environment variable or the config file, never in a repository, never in a screenshot. When I rotate mine I make it a point to rotate it everywhere at once, because a stale key in one terminal window produces a 401 that looks exactly like a wrong URL, and you will waste an hour chasing the wrong culprit.
Third, CCX Gateway itself, installed and running. This is the piece I cannot give you exact commands for, because the project distributes its own install flow and its own service management. Follow its documentation for the version you picked, confirm the process is up and listening on whatever port it advertises, and only then move on. I cannot stress this ordering enough: configure the client last, because a client pointing at a gateway that is not running produces a connection-refused error that teaches you nothing.
Fourth, a clean terminal. Environment variables are read when the CLI starts, not when you type, so anything exported after launch is invisible. On Windows I keep two shell profiles around for this reason, and I check them before blaming the tool.
Step 1: install Codex CLI
Install the CLI the way its own documentation tells you to, whether that is a global install or a wrapper you prefer. When it is done, run its version command. If the binary resolves on your PATH and prints something, the client side is healthy and you can close that book for now.
The one thing worth doing here is checking which config file the CLI actually reads, because there are usually two or three candidate locations and the wrong one is silently ignored. Most setups honor a global config in your user directory plus per-project overrides, with environment variables taking precedence over both. I keep the connection details in the global config so every project inherits them, and I override the model per project only when a repository genuinely needs a different one.
Step 2: point the client at the gateway
This is the step that actually matters, and it has exactly three moving parts. In the config file Codex CLI reads, you set a base URL, an API key, and a default model. In practice that means a small block that looks roughly like this, with the comments doing the real explaining:
// ~/.codex/config.toml (location may vary by version)
model = "your-glm-model-name"
model_provider = "ccx"
[model_providers.ccx]
name = "CCX Gateway"
base_url = "http://localhost:<gateway-port>/v1"
env_key = "CCX_API_KEY"
Three things about that block. The base_url must point at the gateway, not at Zhipu directly, and it must include the /v1 segment that OpenAI-compatible clients expect; drop it and you will get 404s that look like authentication failures. The env_key is just the name of the environment variable holding your key, so you still export the secret separately and it stays out of the file. And the model name must be exactly what the gateway expects to pass through, character for character. Do not translate it into a Zhipu-native name and do not guess a friendly alias. When in doubt, ask the gateway what it is serving rather than inventing something plausible.
On Windows, exporting the key looks like setx CCX_API_KEY "your-key" for a persistent variable in a new shell, or set CCX_API_KEY=your-key for the current session only. I use the session form while testing, because forgetting which value is baked into the machine is its own genre of confusion.
If you would rather keep secrets out of the environment entirely, most setups also accept the key directly in the config. It is convenient and it is also one accidental config.toml away from being committed, so I keep it in the environment and add the config path to my global ignore file as a second belt.
Step 3: verify the whole chain before trusting it
Run the CLI’s own status or environment command first. It is the fastest way to see which provider, base URL, and model it thinks it is using, and it settles arguments with yourself faster than any amount of reading configs.
Then ask for something trivial: a one-line explanation, a short translation, a small prompt that does not touch your repository. If you get a sensible answer, the loop is closed and you can point it at real code.
If the answer does not come, do not start editing the model name out of frustration. Work the chain in order. Does the gateway answer on its own, with a plain HTTP client, unrelated to Codex CLI? If not, the problem is the gateway or its port, and everything above it is noise. If the gateway answers but the CLI does not, the problem is in the client config, and the two usual suspects are the base URL and the environment variable.
The most useful debugging trick I have is a single curl call against the same base URL the CLI is using. It removes the agent loop, the streaming, and the tool-calling from the equation and leaves a plain request and a plain error. Half the time the error text names the fix directly.
Errors I hit, and what actually fixed them
A 401 is almost never a wrong key. In my case it was a key that the gateway was not forwarding because the environment variable name in the config and the name in my shell had drifted apart by one character. Print the variable, then print what the config claims, then compare them like a paranoid person.
A 404 on the chat endpoint is the trailing slash problem, or its cousin, the missing /v1. Both produce a URL that is technically valid and points at nothing. Fix the base URL in one place rather than adding slashes in the client.
A model-not-found error is exactly what it sounds like: the string did not match. It also shows up when you set the model in the project config and forget that a global value is still there, so check both files.
Connection refused means the gateway is not running, or not on the port you think. Check with the tool your OS gives you for listing listening sockets before you touch a single line of Codex CLI config.
A hanging request that never times out is usually a proxy. Corporate proxies and VPN clients love to intercept localhost traffic, and a gateway that worked yesterday will mysteriously stop answering today. Try the local address explicitly, or exclude it from the proxy, and see whether the hang turns into a response. On Windows I also check whether an HTTP proxy variable is set globally, because a stale one from a different project will follow you into every new shell.
Finally, a long agent run that dies mid-stream is worth distinguishing from a config error. Sometimes it is the gateway dropping an idle connection and sometimes it is just a long tool loop. Look at the gateway’s own logs before you rewrite your config.
Cost, trade-offs, and who this is for
The trade is straightforward, and you should make it deliberately.
You are trading the newest frontier model for a cheaper, regionally convenient one that is good enough for the work Codex CLI actually does: reading files, proposing edits, running commands, summarising a diff. For that workload the difference in raw talent matters far less than the difference in cost per long session, and the gateway means the switch costs you an afternoon rather than a rewrite.
You are also trading a single vendor for a chain of three: your machine, the gateway, and the model provider. That is real operational surface. It means updates that break, ports that get taken, and a class of bug that only exists because you added a middle layer. If you want a tool that is set-and-forget, the default configuration is a better life. If you want a cheap, fast, locally reachable agent loop that you can point at a different backend by editing two lines, the middle layer earns its keep.
It is a good fit if you write a lot of code through an agent in a region where Zhipu’s endpoints are the fast ones, if your monthly spend is a real line item, or if you want a fallback path ready for the day the primary route misbehaves. It is a worse fit if your work depends on the very top of the frontier, if you cannot run a local service, or if you would rather not debug a proxy at 11pm.
My own verdict after a few weeks is that it stayed, and it stayed for the boring reason: it costs less and it answers. The setup was an afternoon, most of which went to the trailing slash, and the resulting workflow is the one I already had, which is the highest praise I can give a configuration change.
Where to look
Disclosure: this post contains an affiliate link. If you buy through it we may earn a small commission, at no extra cost to you.