From 402d8f0a32af42bcd725d92085a32c4f0a56dc55 Mon Sep 17 00:00:00 2001
From: adisusilayasa <3523adisusilayasa@gmail.com>
Date: Wed, 18 Feb 2026 13:50:03 +0800
Subject: [PATCH] docs: add Z.AI GLM coding plan setup guide

- Add comprehensive documentation for Z.AI GLM models
- Include curl examples for testing Z.AI API
- Document available models and troubleshooting
- Update .env.example with Z.AI configuration

Z.AI provides GLM models (glm-4.5, glm-4.6, glm-4.7, glm-5) through
the OpenAI-compatible endpoint at api.z.ai/api/coding/paas/v4.

Existing tests verify:
- zai_base_url() returns correct URLs for global/CN variants
- create_provider('zai', key) successfully creates provider
- Regional alias predicates cover all variants
---
 .env.example          |  13 ++++
 docs/zai-glm-setup.md | 135 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+)
 create mode 100644 docs/zai-glm-setup.md

diff --git a/.env.example b/.env.example
index 7a2c253..2519de3 100644
--- a/.env.example
+++ b/.env.example
@@ -68,3 +68,16 @@ PROVIDER=openrouter
 # ── Docker Compose ───────────────────────────────────────────
 # Host port mapping (used by docker-compose.yml)
 # HOST_PORT=3000
+
+# ── Z.AI GLM Coding Plan ───────────────────────────────────────
+# Z.AI provides GLM models (glm-4.5, glm-4.6, glm-4.7, glm-5).
+# API key format: id.secret (e.g., abc123.xyz789)
+# 
+# Usage:
+#   zeroclaw onboard --provider zai --api-key YOUR_ZAI_API_KEY
+#
+# Or set the environment variable:
+# ZAI_API_KEY=your-id.secret
+#
+# Available models: glm-4.5, glm-4.5-air, glm-4.6, glm-4.7, glm-5
+# See docs/zai-glm-setup.md for detailed configuration.
diff --git a/docs/zai-glm-setup.md b/docs/zai-glm-setup.md
new file mode 100644
index 0000000..c0410a1
--- /dev/null
+++ b/docs/zai-glm-setup.md
@@ -0,0 +1,135 @@
+# Z.AI GLM Coding Plan Setup
+
+ZeroClaw supports Z.AI's GLM models through multiple endpoints. This guide covers the recommended configuration.
+
+## Overview
+
+Z.AI provides GLM models through two API styles:
+
+| Endpoint | API Style | Provider String |
+|----------|-----------|-----------------|
+| `/api/coding/paas/v4` | OpenAI-compatible | `zai` |
+| `/api/anthropic` | Anthropic-compatible | `anthropic-custom:https://api.z.ai/api/anthropic` |
+
+## 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-4.7"
+default_temperature = 0.7
+```
+
+## Available Models
+
+| Model | Description |
+|-------|-------------|
+| `glm-4.5` | Stable release |
+| `glm-4.5-air` | Lightweight version |
+| `glm-4.6` | Improved reasoning |
+| `glm-4.7` | Current recommended |
+| `glm-5` | Latest |
+
+## 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-4.7",
+    "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
+
+# Or use the provider-specific variable
+# The key format is: id.secret (e.g., abc123.xyz789)
+```
+
+## Troubleshooting
+
+### Rate Limiting
+
+**Symptom:** `rate_limited` errors
+
+**Solution:**
+- Wait and retry
+- Check your Z.AI plan limits
+- Try `glm-4.7` instead of `glm-5` (more stable availability)
+
+### 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)
+- [Contributing Guide](../CONTRIBUTING.md)