Installing ZCode takes minutes and works from the first run, because it comes with a built-in provider. The problem appears when your key belongs to a gateway that serves several model families: the built-in card fixes the address, protocol, and model list, and none of the three matches your endpoint. The card will never recognize it, no matter how many times you edit it.
The way out is a custom provider. The form has six fields, but only four decide whether the connection works, and the hard part isn’t filling them in but knowing where each value comes from.
Context: two objects the interface doesn’t connect
In settings, a provider is a set of connection parameters plus a list of models. A conversation is just a pointer to one of those providers. They’re on different screens and don’t sync automatically: creating a provider doesn’t change any open conversation.
That separation explains the two most common failures. One is typing the address with the path included while leaving the default format. The other is having everything right and still sending requests with the old provider, because the conversation didn’t switch groups. The second one produces no error message, which is why it’s harder to spot.
What I tested and with what
Everything that follows comes from a single machine running Windows 11, the October 2026 client version, and a single gateway. The installation and interface steps were observed directly; the context limits, speed, and model variants are what the publisher lists in their catalog, not my own measurements.
| Element | Value used |
|---|---|
| Operating system | Windows 11 |
| Client | ZCode desktop, October 2026 interface |
| Example model | glm-5.3 |
| Fields that matter | Base URL, API format, API key, model ID |
The client is downloaded from https://zcode.z.ai/ for Windows, macOS, and Linux.
Step 1: installation and two screens
On first opening, two screens appear. The first asks for your workspace, with twelve options; the answer only affects how the client writes its suggestions. Bottom left is「跳过」(skip). The second offers to connect an account: the dropdown points to the built-in service and below it is a field for its key, which isn’t yours. At the bottom, 「暂时跳过」(skip for now).
Neither one is configuration. Providers are added later, in the same settings window, so there’s no need to go back.
Step 2: the key
ZCode stores a token from the gateway, not the account password. In the provider console you create the token, give it a recognizable name, and copy it right then: most consoles show the full value only once.
Limits, expiration, and per-model permissions live in the console. The client just carries the key in each request. Billing is usually by usage, and the terms in force are the ones listed in the console the day you check them.
The example uses Crazyrouter; the mapping of the four fields is the same for any compatible gateway.
Step 3: create the provider
In settings, the left column separates general options (常规, 外观, 模型设置 or model settings, 浏览器控制 and others) from the Agent block, with memory, sub-agents, plugins, MCP servers, skills, commands, and hooks.
Inside「模型设置」press「新增供应商」(add provider) at the top right. The panel has two halves: at the top the built-in cards, which only ask for a key; below, in「其他」, a list of common providers whose first item is「创建自定义供应商」(create custom provider).
The difference is who defines the connection parameters. The card brings them fixed; the custom provider asks for them. Any external gateway or your own server goes through here.
Step 4: the four fields
The form asks for name, activation switch, Base URL, API format, API key, and model list.
Name: just a label in the list. Something like「团队网关」avoids confusion when choosing a model in the conversation.
Base URL: the gateway root, without path.
https://api.crazyrouter.com
No /v1 or /messages. The address and protocol are separate fields, and the path is decided by the format selector. Adding it by hand is the most direct route to a 404.
API format: the option that contains /v1/messages. It decides both the request route and how to read the response, so it must match what the gateway exposes. An error here returns 400 or 404, never 401: the request is rejected before validating the key. Also /v1/messages and /v1/chat/completions are different structures; a correct address doesn’t make up for the wrong format.
API key: the token from step 2. The eye icon helps you check it: a space at the start or a cut-off end gives 401 and looks like an invalid key. The key is saved locally and shouldn’t end up in a chat or screenshot.
Model list: press「+ 新增模型」and paste the ID. One line is enough to start; the rest share address and key. Each line has its own switch: a disabled model doesn’t appear in the selector.
Before leaving, check that the provider’s switch is on. An unsaved form creates nothing, and that’s another reason why “the settings didn’t apply.”
Step 5: models and verification
IDs are copied, not typed. In the console catalog, searching for glm gives ten results out of 170 models. Each card has the details link and a copy icon to the right; use that icon and don’t change the capitalization.
The same address + key pair can serve multiple models: the pair picks the gateway, the ID picks the model within it. Adding a second model doesn’t need another key or another provider.
After saving, open a new conversation, first choose the provider group and then the model, and send a short instruction. If there’s a response, the model name appears bottom right of the input box next to the reasoning level.
The main trap: the configuration is right, the model responds, but the request still goes out with the old provider because the open conversation didn’t switch. You have to change the group in the lower selector; only then does the request carry your key.
Errors and what they mean
-
404: almost always a path added to the Base URL. Leave just the domain.
-
400 or 404: format incompatible with the gateway. Check
/v1/messages, not the address. -
401: key with a space, cut off, or expired.
-
Model doesn’t appear: provider switch, line switch, or unsaved form. If all three are right, exit settings and go back in to reload the list.
-
Model works but with the old key: the conversation didn’t switch groups.
It’s worth remembering that the three codes cover three different causes but distributed in a non-obvious way: two codes share two errors and only one is announced clearly.
Models
The glm family names follow a grammar: version and suffix. flash is the budget tier, flashx its fast version (around 200 tokens/s), v is vision, ocr is document analysis, and legal is legal.
-
glm-5.3: top tier for complex development, 1M context and 128K output. -
glm-5.3-flash: multimodal and cheaper, also 1M/128K. -
glm-5.3-flashx: fast variant, around 200 tokens/s. -
glm-5.3-flashx-legal: contracts, regulatory search. -
glm-5.2: previous generation, if you don’t want to touch a workflow that already works. -
glm-ocr: images up to 10MB, PDFs up to 50MB, up to 100 pages. -
glm-5v-turbo: old multimodal, limits per spec.
The old IDs glm-5.1, glm-5, glm-5-turbo, and glm-3-turbo still work, but they’re earlier generations. glm-5.3 always reasons and uses three levels (low, high, max); that text next to the model name is the active level.
Limits of this experience
I didn’t test macOS or Linux, so the menu hierarchy might vary. I also didn’t verify multiple gateways at once: the relationship between error codes and causes could differ with another provider. The context numbers and speeds are what the publisher lists on the date indicated, not an independent measurement, and both the IDs and context windows change with versions.
Discussion
Is a custom provider worth it if you only use one service? Probably not: the built-in cards have fewer fields and fewer places to go wrong. It makes sense when a single key needs to cover multiple models and changing models shouldn’t mean changing credentials.
The practical takeaway is that configuration doesn’t finish when you save the form, but when you switch the conversation’s group. That’s the only step that, if skipped, shows no error.