142 lines
2.9 KiB
Markdown
142 lines
2.9 KiB
Markdown
# Z.AI GLM Setup
|
|
|
|
ZeroClaw supports Z.AI's GLM models through OpenAI-compatible endpoints.
|
|
This guide covers practical setup options that match current ZeroClaw provider behavior.
|
|
|
|
## Overview
|
|
|
|
ZeroClaw supports these Z.AI aliases and endpoints out of the box:
|
|
|
|
| Alias | Endpoint | Notes |
|
|
|-------|----------|-------|
|
|
| `zai` | `https://api.z.ai/api/coding/paas/v4` | Global endpoint |
|
|
| `zai-cn` | `https://open.bigmodel.cn/api/paas/v4` | China endpoint |
|
|
|
|
If you need a custom base URL, see `docs/custom-providers.md`.
|
|
|
|
## Setup
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
zeroclaw onboard \
|
|
--provider "zai" \
|
|
--api-key "YOUR_ZAI_API_KEY"
|
|
```
|
|
|
|
### Manual Configuration
|
|
|
|
Edit `~/.zeroclaw/config.toml`:
|
|
|
|
```toml
|
|
api_key = "YOUR_ZAI_API_KEY"
|
|
default_provider = "zai"
|
|
default_model = "glm-5"
|
|
default_temperature = 0.7
|
|
```
|
|
|
|
## Available Models
|
|
|
|
| Model | Description |
|
|
|-------|-------------|
|
|
| `glm-5` | Default in onboarding; strongest reasoning |
|
|
| `glm-4.7` | Strong general-purpose quality |
|
|
| `glm-4.6` | Balanced baseline |
|
|
| `glm-4.5-air` | Lower-latency option |
|
|
|
|
Model availability can vary by account/region, so use the `/models` API when in doubt.
|
|
|
|
## Verify Setup
|
|
|
|
### Test with curl
|
|
|
|
```bash
|
|
# Test OpenAI-compatible endpoint
|
|
curl -X POST "https://api.z.ai/api/coding/paas/v4/chat/completions" \
|
|
-H "Authorization: Bearer YOUR_ZAI_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"model": "glm-5",
|
|
"messages": [{"role": "user", "content": "Hello"}]
|
|
}'
|
|
```
|
|
|
|
Expected response:
|
|
```json
|
|
{
|
|
"choices": [{
|
|
"message": {
|
|
"content": "Hello! How can I help you today?",
|
|
"role": "assistant"
|
|
}
|
|
}]
|
|
}
|
|
```
|
|
|
|
### Test with ZeroClaw CLI
|
|
|
|
```bash
|
|
# Test agent directly
|
|
echo "Hello" | zeroclaw agent
|
|
|
|
# Check status
|
|
zeroclaw status
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Add to your `.env` file:
|
|
|
|
```bash
|
|
# Z.AI API Key
|
|
ZAI_API_KEY=your-id.secret
|
|
|
|
# Optional generic key (used by many providers)
|
|
# API_KEY=your-id.secret
|
|
```
|
|
|
|
The key format is `id.secret` (for example: `abc123.xyz789`).
|
|
|
|
## Troubleshooting
|
|
|
|
### Rate Limiting
|
|
|
|
**Symptom:** `rate_limited` errors
|
|
|
|
**Solution:**
|
|
- Wait and retry
|
|
- Check your Z.AI plan limits
|
|
- Try `glm-4.5-air` for lower latency and higher quota tolerance
|
|
|
|
### Authentication Errors
|
|
|
|
**Symptom:** 401 or 403 errors
|
|
|
|
**Solution:**
|
|
- Verify your API key format is `id.secret`
|
|
- Check the key hasn't expired
|
|
- Ensure no extra whitespace in the key
|
|
|
|
### Model Not Found
|
|
|
|
**Symptom:** Model not available error
|
|
|
|
**Solution:**
|
|
- List available models:
|
|
```bash
|
|
curl -s "https://api.z.ai/api/coding/paas/v4/models" \
|
|
-H "Authorization: Bearer YOUR_ZAI_API_KEY" | jq '.data[].id'
|
|
```
|
|
|
|
## Getting an API Key
|
|
|
|
1. Go to [Z.AI](https://z.ai)
|
|
2. Sign up for a Coding Plan
|
|
3. Generate an API key from the dashboard
|
|
4. Key format: `id.secret` (e.g., `abc123.xyz789`)
|
|
|
|
## Related Documentation
|
|
|
|
- [ZeroClaw README](../README.md)
|
|
- [Custom Provider Endpoints](./custom-providers.md)
|
|
- [Contributing Guide](../CONTRIBUTING.md)
|