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

Open a new Claude Code shard in the desktop app and choose the z-ai slot, or use the CLI:

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

crystl shard create is a Guild control command. Starting the same shard from the desktop app is not gated.

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.

6. Verify the shard

Inside the new shard, run:

echo $ANTHROPIC_BASE_URL

It should print:

https://api.z.ai/api/anthropic

Then give Claude Code a small real task. If it answers and can inspect the project, the setup is complete.

Troubleshooting

The variable is empty: the shard was already open when you saved the slot, the slot is disabled, or it has the wrong kind. Open a new shard after fixing it.

The variable points somewhere else: your shell profile or ~/.claude/settings.json already sets ANTHROPIC_BASE_URL. Your own export wins over crystl’s value. 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.