Hermes Agent with GLM: use Z.AI models with the right key and the right endpoint

The provider name, its aliases and the key variables

In Hermes the provider id is zai, shown as “Z.AI / GLM” in the model picker. Four other spellings are accepted for the same provider: glm, z-ai, z.ai and zhipu. Any of them in a command or in config.yaml lands on zai.

Hermes accepts three variable names for the API key. Set just one, because Hermes can pool all the aliases that have a value:

1. GLM_API_KEY, the name Hermes’s own example file uses;
2. ZAI_API_KEY, documented as an alias;
3. Z_AI_API_KEY, also an alias.

One more variable, GLM_BASE_URL, overrides the web address Hermes sends requests to; the next sections explain when you want that. Hermes does not read variables named after Zhipu or BigModel, so a guide that tells you to set ZHIPU_API_KEY is describing a different tool. Keys belong in ~/.hermes/.env. When the same name is set both there and in your shell, Hermes prefers the file, so a deliberate edit is not overridden by an old export.

Hermes can also reach GLM through other providers, for example OpenRouter, which lists the models as z-ai/glm-5.3 and similar. That is a different route with a different key and different billing, and it is not what this page covers.

Set it up on your own machine

If Hermes is not installed yet, start with how to install Hermes Agent. Then the interactive route is:

hermes model

Choose “Z.AI / GLM”, paste the key, pick an endpoint when asked, then pick a model. The picker offers the four official endpoints below plus a custom proxy address. If you choose a different one from the current one, Hermes saves it as GLM_BASE_URL in your .env.

To do it by hand, put the key in the environment file and name the provider:

hermes config set GLM_API_KEY your-key-here
hermes chat --provider zai --model glm-5.3

For a permanent default, set the model section of config.yaml:

model:
  provider: zai
  default: glm-5.3

Inside a chat you can switch with /model zai:glm-5.3. The model name is the one Z.AI uses, written in lower case with a dot, for example glm-5.3 or glm-5.3-flash.

Which endpoint Hermes uses, and how it picks

Z.AI serves the same models from more than one base address, and which one works depends on the kind of key you hold and where the account was opened. Hermes knows four:

• Global, pay-as-you-go: https://api.z.ai/api/paas/v4. This is also the default.
• China, pay-as-you-go: https://open.bigmodel.cn/api/paas/v4.
• Global, GLM Coding Plan: https://api.z.ai/api/coding/paas/v4.
• China, GLM Coding Plan: https://open.bigmodel.cn/api/coding/paas/v4.

You usually do not choose. When GLM_BASE_URL is not set, Hermes sends a one-token test request to all four at once with your key, and uses the first endpoint in the order above that answers successfully. It remembers the winner in its auth store, tied to a fingerprint of the key, so later starts skip the test. If no endpoint accepts the key, it falls back to the global default and does not try again for five minutes.

A value in GLM_BASE_URL skips this test. Hermes can also use model.base_url from config.yaml when the configured provider is zai, and the model picker saves it there. If requests go to the wrong endpoint, check both settings, and update them together when you change the kind of key.

The Hermes source says why the detection exists: Z.AI bills the general and coding products, and the global and China sites, separately, and a key used on the wrong one is refused with an insufficient-balance style error.

GLM models Hermes knows, context length and tool calling

The list Hermes shows for the zai provider is: glm-5.3, glm-5.3-flash, glm-5.2, glm-5.1, glm-5, glm-5v-turbo, glm-5-turbo, glm-4.7, glm-4.5 and glm-4.5-flash. A name that is not on the list can still be typed in. If the live model list from the endpoint does not include it, Hermes accepts any name it finds in that built-in list, with a note.

Context lengths in Hermes’s built-in table, in tokens:

• glm-5.3 and glm-5.3-flash: 1,310,720;
• glm-5.2: 1,048,576;
• glm-5.1, glm-5, glm-4.7 and glm-4.6: 204,800;
• glm-5-turbo, glm-5v-turbo and glm-4.7-flash: 202,752, which is also the figure for any other GLM name Hermes does not recognise.

Z.AI’s page for GLM-5.3 describes a 1M-token context window and up to 128K tokens of output, with text-only input; GLM-5.3-Flash takes images, video and files as well and has the same 1M-token window. These figures differ. Hermes can use cached metadata, models.dev or its built-in table, and it does not normally ask Z.AI directly for the window. If you see context errors, set context_length in the model section of config.yaml to a value Z.AI documents.

Z.AI’s page says GLM-5.3 always runs with reasoning on, lists the levels low, high and max, and says a request that tries to switch reasoning off is rejected. Hermes also accepts medium for this model, and it already accounts for the rest. For GLM-4.5 and later it translates its own reasoning setting into the GLM thinking fields, and for GLM-5.3 it sends low instead of “off”.

Tool calling is what an agent depends on, and Z.AI documents it for its chat API: you pass a list of tools, the model answers with the calls it wants, and Z.AI’s page says the tool-choice setting only supports its automatic mode. For the product’s own limits, read the function-calling page at docs.z.ai.

Coding Plan or pay-as-you-go: the key decides the billing

Z.AI sells pay-as-you-go API access, charged against an account balance or a usage bundle, and the GLM Coding Plan, a subscription with usage limits that reset every five hours and every week. They use different kinds of key. Z.AI’s notice on key management says that from 16 October 2026 new keys are created separately for the standard API, the Individual Plan and the Team Plan, and that the key type fixes how a call is billed. A standard key used inside a coding tool does not touch your plan quota, even if you subscribe. Older keys outside Team Plan projects, on an account that has ever held a plan, are classed as “Compatible” and keep their old behaviour: on the coding address they use plan quota, on the standard address they use your balance or usage bundles. Older keys in Team Plan projects count as Team Plan keys.

Is a plan key allowed in an agent like Hermes? Z.AI’s rule is that the Coding Plan may be used only inside the tools and product environments on its supported list, and that use elsewhere may have the benefits restricted. On the date above, that list names Hermes Agent among the general-purpose agent tools, and says those are served on a best-effort basis, so some requests may be rate limited under heavy load. Because that list is what decides, read it yourself before you rely on a plan key; Z.AI can change it.

Two practical details from the same pages. All plans list GLM-5.3 and GLM-5.3-Flash as the supported models, and Z.AI says requests for GLM-5.2 or GLM-5.1 are routed to GLM-5.3, and GLM-4.7 to GLM-5.3-Flash. And when the plan quota runs out, calls from supported tools do not fall back to your balance; you wait for the next reset. For the OpenAI Chat Completions protocol Hermes uses here, Z.AI documents the coding/paas/v4 address listed earlier.

Common errors and what they usually mean

Z.AI returns an HTTP status plus its own numeric code. From its error list, read on 2 November 2026:

• 401 with 1000, 1001 or 1003. Authentication failed, no key was received, or the token expired. Check the variable name from the first section, that the whole key was copied, and that no stray space or quote sits in .env.
• 429 with 1113. Insufficient balance or no resource package. Check the key type and the endpoint. Standard keys use your account balance or usage bundles, even inside coding tools. Older Compatible keys use the balance at the standard address and plan quota at the coding address. Check GLM_BASE_URL and the key’s type in Z.AI’s console.
• 429 with 1302 or 1305. A rate limit, or the service being busy. Wait and retry, and reduce how many things run at once.
• 429 with 1308, 1310, 1316 or 1317. A usage limit was reached for the five-hour or weekly window. The message says when it resets.
• 429 with 1309 or 1311. Code 1309 means the plan has expired: renew it, or use a standard key for pay-as-you-go access. Code 1311 means the plan does not include that model: switch to one it lists.
• 400 with 1211. Unknown model. Use the exact lower-case name.

If Hermes keeps trying the wrong endpoint, check both GLM_BASE_URL and model.base_url. A failed detection is remembered for five minutes in the running process, so after fixing the settings, wait or restart. For a comparison with another provider that has similar setup steps, see Hermes Agent with DeepSeek.

GLM on ReadyHermes

On ReadyHermes you do not install anything or edit .env. The assistant runs on our servers and stays on, and you give it your own Z.AI key in the Model key panel. The panel is open during the free trial and on paid plans, and a key added in the trial stays when you choose a plan. To use it:

1. Open the Model key panel and choose Z.AI in the provider list, which is labelled “GLM models”.
2. Paste your key. You can load the model list from Z.AI, or type the model name yourself, for example glm-5.3.
3. Choose “Check and switch”. ReadyHermes first sends one small test message with your key, so a typo cannot leave the assistant silent, and changes nothing if the test fails. Switching restarts the assistant, which takes about a minute.

Two things differ from running Hermes yourself. First, the Z.AI entry in the panel sends requests to the pay-as-you-go address, https://api.z.ai/api/paas/v4. ReadyHermes does not use Hermes’s four-endpoint detection: the platform stores your key, the address and the model name in Hermes’s custom provider slot. An older Compatible key used through the Z.AI entry draws on account balance or usage bundles rather than plan quota. For Coding Plan access, the coding address can go in the panel’s Other endpoint option, which requires an https address on port 443 with a public hostname; the key and model must then pass the test message. Whether Z.AI’s plan rules accept a hosted agent is Z.AI’s decision, and we have not tested that route. Second, we have not verified how GLM-specific reasoning settings behave through that custom slot.

Common refusals show up in plain words in the panel: the provider did not accept the key, the account has no credit left, the provider is rate limiting the key, or the model is not offered to it. The panel shows only a masked preview of the key; the full key is stored in your assistant’s configuration so it can authenticate requests. For the wider picture of hosting, see managed Hermes Agent hosting, and self-hosting versus managed hosting if you are still deciding where to run it.