# Use z.ai open models with crystl

> Create a z.ai GLM Coding Plan account, generate an API key, connect its hosted open models to crystl, and start a Claude Code shard.

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

1. [Open the GLM Coding Plan with 10% off](https://z.ai/subscribe?ic=JSELHPQMKK) and register or sign in.
2. Choose a plan for the amount of work you expect to run. Check z.ai's current [plan and concurrency guidance](https://docs.z.ai/devpack/usage-policy) before paying, especially if you plan to run several shards at once.
3. 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:

```bash
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:

```bash
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:

```bash
echo $ANTHROPIC_BASE_URL
```

It should print:

```text
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.

## Other setup tutorials

- [Ollama](/docs/open-models-ollama/): a local runtime you drive from the command line.
- [LM Studio](/docs/open-models-lm-studio/): a graphical local runtime with an Anthropic-compatible server.
- [vLLM](/docs/open-models-vllm/): high-throughput serving on a Linux GPU machine.
- [llama.cpp](/docs/open-models-llama-cpp/): a small native server with direct control over quantization.

## Related

- [Open Models](/docs/open-models/) for self-hosted and managed options, agent-specific behavior, and privacy boundaries.
- [Cut model costs with hosted open models](/docs/scenario-cut-model-costs/) for deciding which work belongs on a lower-cost model.
- [API Key Storage](/docs/api-keys/) for how crystl stores and injects credentials.

---
Source: https://crystl.dev/docs/open-models-zai/