admin/skill-lib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: refactor sgclaw around zeroclaw compat runtime

Browse Source
This commit is contained in:
zyl
2026-03-26 16:23:31 +08:00
parent bca5b75801
commit ff0771a83f
1059 changed files with 409460 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
third_party/zeroclaw/docs/setup-guides/README.md vendored Normal file
View File

@@ -0,0 +1,34 @@
# Getting Started Docs
For first-time setup and quick orientation.
## Start Path
1. Main overview and quick start: [../../README.md](../../README.md)
2. One-click setup and dual bootstrap mode: [one-click-bootstrap.md](one-click-bootstrap.md)
3. Update or uninstall on macOS: [macos-update-uninstall.md](macos-update-uninstall.md)
4. Find commands by tasks: [../reference/cli/commands-reference.md](../reference/cli/commands-reference.md)
## Choose Your Path
| Scenario | Command |
|----------|---------|
| I have an API key, want fastest setup | `zeroclaw onboard --api-key sk-... --provider openrouter` |
| I want guided prompts | `zeroclaw onboard` |
| Config exists, just fix channels | `zeroclaw onboard --channels-only` |
| Config exists, I intentionally want full overwrite | `zeroclaw onboard --force` |
| Using subscription auth | See [Subscription Auth](../../README.md#subscription-auth-openai-codex--claude-code) |
## Onboarding and Validation
- Quick onboarding: `zeroclaw onboard --api-key "sk-..." --provider openrouter`
- Guided onboarding: `zeroclaw onboard`
- Existing config protection: reruns require explicit confirmation (or `--force` in non-interactive flows)
- Ollama cloud models (`:cloud`) require a remote `api_url` and API key (for example `api_url = "https://ollama.com"`).
- Validate environment: `zeroclaw status` + `zeroclaw doctor`
## Next
- Runtime operations: [../ops/README.md](../ops/README.md)
- Reference catalogs: [../reference/README.md](../reference/README.md)
- macOS lifecycle tasks: [macos-update-uninstall.md](macos-update-uninstall.md)

29
third_party/zeroclaw/docs/setup-guides/README.vi.md vendored Normal file
View File

@@ -0,0 +1,29 @@
# Tài liệu Bắt đầu
Dành cho cài đặt lần đầu và làm quen nhanh.
## Lộ trình bắt đầu
1. Tổng quan và khởi động nhanh: [../../README.vi.md](../../README.vi.md)
2. Cài đặt một lệnh và chế độ bootstrap kép: [one-click-bootstrap.md](one-click-bootstrap.md)
3. Tìm lệnh theo tác vụ: [../reference/cli/commands-reference.md](../reference/cli/commands-reference.md)
## Chọn hướng đi
| Tình huống | Lệnh |
|----------|---------|
| Có API key, muốn cài nhanh nhất | `zeroclaw onboard --api-key sk-... --provider openrouter` |
| Muốn được hướng dẫn từng bước | `zeroclaw onboard` |
| Đã có config, chỉ cần sửa kênh | `zeroclaw onboard --channels-only` |
| Dùng xác thực subscription | Xem [Subscription Auth](../../README.vi.md#subscription-auth-openai-codex--claude-code) |
## Thiết lập và kiểm tra
- Thiết lập nhanh: `zeroclaw onboard --api-key "sk-..." --provider openrouter`
- Thiết lập hướng dẫn: `zeroclaw onboard`
- Kiểm tra môi trường: `zeroclaw status` + `zeroclaw doctor`
## Tiếp theo
- Vận hành runtime: [../ops/README.md](../ops/README.md)
- Tra cứu tham khảo: [../reference/README.md](../reference/README.md)

112
third_party/zeroclaw/docs/setup-guides/macos-update-uninstall.md vendored Normal file
View File

@@ -0,0 +1,112 @@
# macOS Update and Uninstall Guide
This page documents supported update and uninstall procedures for ZeroClaw on macOS (OS X).
Last verified: **February 22, 2026**.
## 1) Check current install method
```bash
which zeroclaw
zeroclaw --version
```
Typical locations:
- Homebrew: `/opt/homebrew/bin/zeroclaw` (Apple Silicon) or `/usr/local/bin/zeroclaw` (Intel)
- Cargo/bootstrap/manual: `~/.cargo/bin/zeroclaw`
If both exist, your shell `PATH` order decides which one runs.
## 2) Update on macOS
### A) Homebrew install
```bash
brew update
brew upgrade zeroclaw
zeroclaw --version
```
### B) Clone + bootstrap install
From your local repository checkout:
```bash
git pull --ff-only
./install.sh --prefer-prebuilt
zeroclaw --version
```
If you want source-only update:
```bash
git pull --ff-only
cargo install --path . --force --locked
zeroclaw --version
```
### C) Manual prebuilt binary install
Re-run your download/install flow with the latest release asset, then verify:
```bash
zeroclaw --version
```
## 3) Uninstall on macOS
### A) Stop and remove background service first
This prevents the daemon from continuing to run after binary removal.
```bash
zeroclaw service stop || true
zeroclaw service uninstall || true
```
Service artifacts removed by `service uninstall`:
- `~/Library/LaunchAgents/com.zeroclaw.daemon.plist`
### B) Remove the binary by install method
Homebrew:
```bash
brew uninstall zeroclaw
```
Cargo/bootstrap/manual (`~/.cargo/bin/zeroclaw`):
```bash
cargo uninstall zeroclaw || true
rm -f ~/.cargo/bin/zeroclaw
```
### C) Optional: remove local runtime data
Only run this if you want a full cleanup of config, auth profiles, logs, and workspace state.
```bash
rm -rf ~/.zeroclaw
```
## 4) Verify uninstall completed
```bash
command -v zeroclaw || echo "zeroclaw binary not found"
pgrep -fl zeroclaw || echo "No running zeroclaw process"
```
If `pgrep` still finds a process, stop it manually and re-check:
```bash
pkill -f zeroclaw
```
## Related docs
- [One-Click Bootstrap](one-click-bootstrap.md)
- [Commands Reference](../reference/cli/commands-reference.md)
- [Troubleshooting](../ops/troubleshooting.md)

63
third_party/zeroclaw/docs/setup-guides/mattermost-setup.md vendored Normal file
View File

@@ -0,0 +1,63 @@
# Mattermost Integration Guide
ZeroClaw supports native integration with Mattermost via its REST API v4. This integration is ideal for self-hosted, private, or air-gapped environments where sovereign communication is a requirement.
## Prerequisites
1. **Mattermost Server**: A running Mattermost instance (self-hosted or cloud).
2. **Bot Account**:
- Go to **Main Menu > Integrations > Bot Accounts**.
- Click **Add Bot Account**.
- Set a username (e.g., `zeroclaw-bot`).
- Enable **post:all** and **channel:read** permissions (or appropriate scopes).
- Save the **Access Token**.
3. **Channel ID**:
- Open the Mattermost channel you want the bot to monitor.
- Click the channel header and select **View Info**.
- Copy the **ID** (e.g., `7j8k9l...`).
## Configuration
Add the following to your `config.toml` under the `[channels_config]` section:
```toml
[channels_config.mattermost]
url = "https://mm.your-domain.com"
bot_token = "your-bot-access-token"
channel_id = "your-channel-id"
allowed_users = ["user-id-1", "user-id-2"]
thread_replies = true
mention_only = true
```
### Configuration Fields
| Field | Description |
|---|---|
| `url` | The base URL of your Mattermost server. |
| `bot_token` | The Personal Access Token for the bot account. |
| `channel_id` | (Optional) The ID of the channel to listen to. Required for `listen` mode. |
| `allowed_users` | (Optional) A list of Mattermost User IDs permitted to interact with the bot. Use `["*"]` to allow everyone. |
| `thread_replies` | (Optional) Whether top-level user messages should be answered in a thread. Default: `true`. Existing thread replies always remain in-thread. |
| `mention_only` | (Optional) When `true`, only messages that explicitly mention the bot username (for example `@zeroclaw-bot`) are processed. Default: `false`. |
## Threaded Conversations
ZeroClaw supports Mattermost threads in both modes:
- If a user sends a message in an existing thread, ZeroClaw always replies within that same thread.
- If `thread_replies = true` (default), top-level messages are answered by threading on that post.
- If `thread_replies = false`, top-level messages are answered at channel root level.
## Mention-Only Mode
When `mention_only = true`, ZeroClaw applies an extra filter after `allowed_users` authorization:
- Messages without an explicit bot mention are ignored.
- Messages with `@bot_username` are processed.
- The `@bot_username` token is stripped before sending content to the model.
This mode is useful in busy shared channels to reduce unnecessary model calls.
## Security Note
Mattermost integration is designed for **sovereign communication**. By hosting your own Mattermost server, your agent's communication history remains entirely within your own infrastructure, avoiding third-party cloud logging.

78
third_party/zeroclaw/docs/setup-guides/nextcloud-talk-setup.md vendored Normal file
View File

@@ -0,0 +1,78 @@
# Nextcloud Talk Setup
This guide covers native Nextcloud Talk integration for ZeroClaw.
## 1. What this integration does
- Receives inbound Talk bot webhook events via `POST /nextcloud-talk`.
- Verifies webhook signatures (HMAC-SHA256) when a secret is configured.
- Sends bot replies back to Talk rooms via Nextcloud OCS API.
## 2. Configuration
Add this section in `~/.zeroclaw/config.toml`:
```toml
[channels_config.nextcloud_talk]
base_url = "https://cloud.example.com"
app_token = "nextcloud-talk-app-token"
webhook_secret = "optional-webhook-secret"
allowed_users = ["*"]
```
Field reference:
- `base_url`: Nextcloud base URL.
- `app_token`: Bot app token used as `Authorization: Bearer <token>` for OCS send API.
- `webhook_secret`: Shared secret for verifying `X-Nextcloud-Talk-Signature`.
- `allowed_users`: Allowed Nextcloud actor IDs (`[]` denies all, `"*"` allows all).
Environment override:
- `ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET` overrides `webhook_secret` when set.
## 3. Gateway endpoint
Run the daemon or gateway and expose the webhook endpoint:
```bash
zeroclaw daemon
# or
zeroclaw gateway --host 127.0.0.1 --port 3000
```
Configure your Nextcloud Talk bot webhook URL to:
- `https://<your-public-url>/nextcloud-talk`
## 4. Signature verification contract
When `webhook_secret` is configured, ZeroClaw verifies:
- header `X-Nextcloud-Talk-Random`
- header `X-Nextcloud-Talk-Signature`
Verification formula:
- `hex(hmac_sha256(secret, random + raw_request_body))`
If verification fails, the gateway returns `401 Unauthorized`.
## 5. Message routing behavior
- ZeroClaw ignores bot-originated webhook events (`actorType = bots`).
- ZeroClaw ignores non-message/system events.
- Reply routing uses the Talk room token from the webhook payload.
## 6. Quick validation checklist
1. Set `allowed_users = ["*"]` for first-time validation.
2. Send a test message in the target Talk room.
3. Confirm ZeroClaw receives and replies in the same room.
4. Tighten `allowed_users` to explicit actor IDs.
## 7. Troubleshooting
- `404 Nextcloud Talk not configured`: missing `[channels_config.nextcloud_talk]`.
- `401 Invalid signature`: mismatch in `webhook_secret`, random header, or raw-body signing.
- No reply but webhook `200`: event filtered (bot/system/non-allowed user/non-message payload).

229
third_party/zeroclaw/docs/setup-guides/one-click-bootstrap.md vendored Normal file
View File

@@ -0,0 +1,229 @@
# One-Click Bootstrap
This page defines the fastest supported path to install and initialize ZeroClaw.
Last verified: **February 20, 2026**.
## Option 0: Homebrew (macOS/Linuxbrew)
```bash
brew install zeroclaw
```
## Option A (Recommended): Clone + local script
```bash
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh
```
What it does by default:
1. `cargo build --release --locked`
2. `cargo install --path . --force --locked`
### Resource preflight and pre-built flow
Source builds typically require at least:
- **2 GB RAM + swap**
- **6 GB free disk**
When resources are constrained, bootstrap now attempts a pre-built binary first.
```bash
./install.sh --prefer-prebuilt
```
To require binary-only installation and fail if no compatible release asset exists:
```bash
./install.sh --prebuilt-only
```
To bypass pre-built flow and force source compilation:
```bash
./install.sh --force-source-build
```
## Dual-mode bootstrap
Default behavior is **app-only** (build/install ZeroClaw) and expects existing Rust toolchain.
For fresh machines, enable environment bootstrap explicitly:
```bash
./install.sh --install-system-deps --install-rust
```
Notes:
- `--install-system-deps` installs compiler/build prerequisites (may require `sudo`).
- `--install-rust` installs Rust via `rustup` when missing.
- `--prefer-prebuilt` tries release binary download first, then falls back to source build.
- `--prebuilt-only` disables source fallback.
- `--force-source-build` disables pre-built flow entirely.
## Option B: Remote one-liner
```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
```
For high-security environments, prefer Option A so you can review the script before execution.
If you run Option B outside a repository checkout, the install script automatically clones a temporary workspace, builds, installs, and then cleans it up.
## Optional onboarding modes
### Containerized onboarding (Docker)
```bash
./install.sh --docker
```
This builds a local ZeroClaw image and launches onboarding inside a container while
persisting config/workspace to `./.zeroclaw-docker`.
Container CLI defaults to `docker`. If Docker CLI is unavailable and `podman` exists,
the installer auto-falls back to `podman`. You can also set `ZEROCLAW_CONTAINER_CLI`
explicitly (for example: `ZEROCLAW_CONTAINER_CLI=podman ./install.sh --docker`).
For Podman, the installer runs with `--userns keep-id` and `:Z` volume labels so
workspace/config mounts remain writable inside the container.
If you add `--skip-build`, the installer skips local image build. It first tries the local
Docker tag (`ZEROCLAW_DOCKER_IMAGE`, default: `zeroclaw-bootstrap:local`); if missing,
it pulls `ghcr.io/zeroclaw-labs/zeroclaw:latest` and tags it locally before running.
### Stopping and restarting a Docker/Podman container
After `./install.sh --docker` finishes, the container exits. Your config and workspace
are persisted in the data directory (default: `./.zeroclaw-docker`, or `~/.zeroclaw-docker`
when bootstrapping via `curl | bash`). You can override this path with `ZEROCLAW_DOCKER_DATA_DIR`.
**Do not re-run `install.sh`** to restart -- it will rebuild the image and re-run onboarding.
Instead, start a new container from the existing image and mount the persisted data directory.
#### Using the repository docker-compose.yml
The simplest way to run ZeroClaw long-term in Docker/Podman is with the provided
`docker-compose.yml` at the repository root. It uses a named volume (`zeroclaw-data`)
and sets `restart: unless-stopped` so the container survives reboots.
```bash
# Start (detached)
docker compose up -d
# Stop
docker compose down
# Restart after stopping
docker compose up -d
```
Replace `docker` with `podman` if you use Podman.
#### Manual container run (using install.sh data directory)
If you installed via `./install.sh --docker` and want to reuse the `.zeroclaw-docker`
data directory without compose:
```bash
# Docker
docker run -d --name zeroclaw \
--restart unless-stopped \
-v "$PWD/.zeroclaw-docker/.zeroclaw:/zeroclaw-data/.zeroclaw" \
-v "$PWD/.zeroclaw-docker/workspace:/zeroclaw-data/workspace" \
-e HOME=/zeroclaw-data \
-e ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace \
-p 42617:42617 \
zeroclaw-bootstrap:local \
gateway
# Podman (add --userns keep-id and :Z volume labels)
podman run -d --name zeroclaw \
--restart unless-stopped \
--userns keep-id \
--user "$(id -u):$(id -g)" \
-v "$PWD/.zeroclaw-docker/.zeroclaw:/zeroclaw-data/.zeroclaw:Z" \
-v "$PWD/.zeroclaw-docker/workspace:/zeroclaw-data/workspace:Z" \
-e HOME=/zeroclaw-data \
-e ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace \
-p 42617:42617 \
zeroclaw-bootstrap:local \
gateway
```
#### Common lifecycle commands
```bash
# Stop the container (preserves data)
docker stop zeroclaw
# Start a stopped container (config and workspace are intact)
docker start zeroclaw
# View logs
docker logs -f zeroclaw
# Remove the container (data in volumes/.zeroclaw-docker is preserved)
docker rm zeroclaw
# Check health
docker exec zeroclaw zeroclaw status
```
#### Environment variables
When running manually, pass provider configuration as environment variables
or ensure they are already saved in the persisted `config.toml`:
```bash
docker run -d --name zeroclaw \
-e API_KEY="sk-..." \
-e PROVIDER="openrouter" \
-v "$PWD/.zeroclaw-docker/.zeroclaw:/zeroclaw-data/.zeroclaw" \
-v "$PWD/.zeroclaw-docker/workspace:/zeroclaw-data/workspace" \
-p 42617:42617 \
zeroclaw-bootstrap:local \
gateway
```
If you already ran `onboard` during the initial install, your API key and provider are
saved in `.zeroclaw-docker/.zeroclaw/config.toml` and do not need to be passed again.
### Quick onboarding (non-interactive)
```bash
./install.sh --api-key "sk-..." --provider openrouter
```
Or with environment variables:
```bash
ZEROCLAW_API_KEY="sk-..." ZEROCLAW_PROVIDER="openrouter" ./install.sh
```
## Useful flags
- `--install-system-deps`
- `--install-rust`
- `--skip-build` (in `--docker` mode: use local image if present, otherwise pull `ghcr.io/zeroclaw-labs/zeroclaw:latest`)
- `--skip-install`
- `--provider <id>`
See all options:
```bash
./install.sh --help
```
## Related docs
- [README.md](../README.md)
- [commands-reference.md](../reference/cli/commands-reference.md)
- [providers-reference.md](../reference/api/providers-reference.md)
- [channels-reference.md](../reference/api/channels-reference.md)

7
third_party/zeroclaw/docs/setup-guides/one-click-bootstrap.vi.md vendored Normal file
View File

@@ -0,0 +1,7 @@
# Vietnamese One-Click Bootstrap (Moved)
Canonical page:
- [i18n/vi/one-click-bootstrap.md](../i18n/vi/one-click-bootstrap.md)
Compatibility shim only.

110
third_party/zeroclaw/docs/setup-guides/windows-setup.md vendored Normal file
View File

@@ -0,0 +1,110 @@
# Windows Setup Guide
This guide covers building and installing ZeroClaw on Windows.
## Quick Start
### Option A: One-click setup script
From the repository root:
```cmd
setup.bat
```
The script auto-detects your environment and walks you through installation.
You can also pass flags to skip the interactive menu:
| Flag | Description |
|------|-------------|
| `--prebuilt` | Download pre-compiled binary (fastest) |
| `--minimal` | Build with default features only |
| `--standard` | Build with Matrix + Lark/Feishu + Postgres |
| `--full` | Build with all features |
### Option B: Scoop (package manager)
```powershell
scoop bucket add zeroclaw https://github.com/zeroclaw-labs/scoop-zeroclaw
scoop install zeroclaw
```
### Option C: Manual build
```cmd
rustup target add x86_64-pc-windows-msvc
cargo build --release --locked --features channel-matrix,channel-lark --target x86_64-pc-windows-msvc
copy target\x86_64-pc-windows-msvc\release\zeroclaw.exe %USERPROFILE%\.zeroclaw\bin\
```
## Prerequisites
| Requirement | Required? | Notes |
|-------------|-----------|-------|
| Git | Yes | [git-scm.com/download/win](https://git-scm.com/download/win) |
| Rust 1.87+ | Yes | Auto-installed by `setup.bat` if missing |
| Visual Studio Build Tools | Yes (source builds) | C++ workload required for MSVC linker |
| Node.js | No | Only needed to build the web dashboard from source |
### Installing Visual Studio Build Tools
If you don't have Visual Studio installed, install the Build Tools:
1. Download from [visualstudio.microsoft.com/visual-cpp-build-tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
2. Select the **"Desktop development with C++"** workload
3. Install and restart your terminal
Alternatively, if you have Visual Studio 2019+ installed with the C++ workload, you're already set.
## Feature Flags
ZeroClaw uses Cargo feature flags to control which integrations are compiled in:
| Feature | Description | Default? |
|---------|-------------|----------|
| `channel-lark` | Lark/Feishu messaging | Yes |
| `channel-nostr` | Nostr protocol | Yes |
| `observability-prometheus` | Prometheus metrics | Yes |
| `skill-creation` | Auto skill creation | Yes |
| `channel-matrix` | Matrix protocol | No |
| `browser-native` | Headless browser | No |
| `hardware` | USB device support | No |
| `rag-pdf` | PDF extraction for RAG | No |
| `observability-otel` | OpenTelemetry | No |
To build with specific features:
```cmd
cargo build --release --locked --features channel-matrix,channel-lark --target x86_64-pc-windows-msvc
```
## Post-Installation
1. **Restart your terminal** for PATH changes to take effect
2. **Initialize ZeroClaw:**
```cmd
zeroclaw init
```
3. **Configure your API key** in `%USERPROFILE%\.zeroclaw\config.toml`
## Troubleshooting
### Build fails with linker errors
Install Visual Studio Build Tools with the C++ workload. The MSVC linker is required.
### `cargo build` runs out of memory
Source builds need at least 2 GB free RAM. Use `setup.bat --prebuilt` to download a pre-compiled binary instead.
### Feishu/Lark not available
Feishu and Lark are the same platform. Build with the `channel-lark` feature:
```cmd
cargo build --release --locked --features channel-lark --target x86_64-pc-windows-msvc
```
### Web dashboard missing
The web dashboard requires Node.js and npm at build time. Install Node.js and rebuild, or use the pre-built binary which includes the dashboard.

142
third_party/zeroclaw/docs/setup-guides/zai-glm-setup.md vendored Normal file
View File

@@ -0,0 +1,142 @@
# 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 [`../contributing/custom-providers.md`](../contributing/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](../contributing/custom-providers.md)
- [Contributing Guide](../../CONTRIBUTING.md)