# 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

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

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

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

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

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

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

## 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/