Use z.ai open models with crystl

This tutorial takes you from a new z.ai account to a Claude Code shard running on z.ai’s hosted GLM models. You do not need a local GPU.

z.ai hosts the model and receives everything Claude Code sends. Your Anthropic key is not involved: crystl gives the shard the z.ai URL and the z.ai key stored in your Keychain.

Affiliate disclosure: The signup link below gives you 10% off. crystl may receive a referral benefit if you subscribe through it.

1. Create a z.ai account and choose a plan

Open the GLM Coding Plan with 10% off and register or sign in.
Choose a plan for the amount of work you expect to run. Check z.ai’s current plan and concurrency guidance before paying, especially if you plan to run several shards at once.
Complete the subscription. The GLM Coding Plan is for supported coding tools, including Claude Code, rather than general API use.

The plan renews automatically. z.ai says subscription purchases are non-refundable, so check the billing period and current limits before confirming.

2. Create the right API key

After subscribing, open your plan page and create a key:

Individual plan: Individual Coding Plan → Plan Overview.
Team plan: Team Coding Plan → My Plan. Use the Team Plan key for Team Plan quota; z.ai says it is not interchangeable with its other API keys.

Copy the key once. Do not paste it into a shell profile, project file, or Claude Code settings. crystl stores it in your macOS Keychain.

3. Add z.ai to crystl

Open Settings → agents → providers & keys, scroll to the open-model connections, and add this slot:

Field	Value
Label	`z-ai`
Kind	anthropic-compatible
Base URL	`https://api.z.ai/api/anthropic`
As seen from remote	leave empty
Key	your z.ai Coding Plan key
Context window	`200000`
Enabled	on

Save the slot. The default aliases supply ANTHROPIC_BASE_URL and the matching auth variables to each new shard.

The context window field is optional, and it is worth filling in. z.ai maps the Claude model names Claude Code shows to GLM models from your plan, and GLM-4.7 has a 200K context window. Claude Code sees only the Claude name, so it assumes that model’s much larger window. crystl uses the number you record here to warn you when an endpoint is too small for the work you are about to start. Leave it blank and there is nothing to warn from.

You can skip z.ai’s Coding Tool Helper, install script, and manual edits to ~/.claude/settings.json for this setup. Those methods configure the same URL and key globally; crystl supplies them to the shard instead.

4. Check the connection

Run:

crystl status

Look for the z-ai slot and a reachable result. A 401 or 403 still counts as reachable because the service answered; if requests then fail, check that you used the Coding Plan key and copied it completely.

5. Start Claude Code on z.ai

Saving the endpoint also created an agent named after it: claude@z-ai. Open a new shard and type that instead of claude:

claude@z-ai

Claude Code starts and runs on z.ai.

Plain claude in the same shard still runs hosted Claude. The two sit side by side, so you can move one task onto an open model without moving all of them.

If Claude Code asks whether to use the API key, choose Yes. z.ai maps the model names Claude Code shows to the GLM models supplied by your plan, so the Claude-style name in the interface does not mean requests are going to Anthropic.

To run a specific size, add --size:

claude@z-ai --size small

The sizes are the models you set on the endpoint. Change them any time in Settings → providers & keys, on Settings → agents → agents, or from the command line:

crystl endpoint set --label z-ai --small glm-4.5-air --standard glm-4.6

To start a background worker on z.ai instead of typing into a shard:

crystl shard create --gem myapp --agent claude@z-ai --size standard \
  --prompt "inspect this project and suggest the best first task"

crystl shard create is a Guild control command. Typing claude@z-ai into a shard is not.

6. Verify the shard

Type claude@z-ai in a new shard and give Claude Code a small real task. If it answers and can inspect the project, the setup is complete.

To check the wiring without starting an agent:

crystl endpoint list

The z-ai entry should show your URL, key stored, and agent claude@z-ai.

Troubleshooting

claude@z-ai: command not found: the shard was already open when you saved the endpoint — open a new one. If it still happens, the endpoint has no start command: crystl endpoint list shows agent none, and crystl endpoint set --label z-ai --agent claude fixes it.

“claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set”: expected, and nothing is wrong. The auth source it means is the z.ai key crystl gave the session — the thing that makes it z.ai. Claude Code turns off claude.ai connectors whenever a session authenticates with a key instead of your login, and it says so once at startup. Leave it alone. Unsetting the variable to silence the warning is what actually breaks the setup, and the session would go back to Anthropic.

Claude Code starts but behaves like hosted Claude: you typed claude, not claude@z-ai. Plain claude stays on Anthropic unless you turn on also run plain claude here in the endpoint’s settings.

You want every claude to go to z.ai: turn on also run plain claude here, then open a new shard. Turning it back off returns plain claude to Anthropic. claude@z-ai keeps working either way.

Your own settings win: if your shell profile or ~/.claude/settings.json already sets ANTHROPIC_BASE_URL, that value beats crystl’s. Remove the old global z.ai or Anthropic override, then open a new shard.

The connection answers but Claude Code rejects the key: confirm the key came from your Individual or Team Coding Plan page, not a general z.ai API key. Team Plan keys are separate.

You hit a limit while several shards are running: z.ai ties concurrency to the plan tier. Reduce the number of simultaneous z.ai shards or review its current plan guidance.

Claude Code stops mid-task and says it reached its context window limit: the session filled up the 200K window. Claude Code compacts a long conversation automatically, but it sizes that against the window it believes its own model has, which on z.ai is a much larger number than the model actually provides. So the session can run past the real limit before it decides to compact.

Keep sessions on a hosted open model shorter than you would on Anthropic. Run /compact yourself before a long task, start a fresh shard for a new piece of work rather than continuing one, and prefer several small tasks over one sweeping one. Work that reads a large part of a codebase in a single session is the usual trigger.