Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions external_plugins/free-guide/.zcode-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"name": "free-guide",
"description": "Complete community guide to running ZCode on a free stack: quota-safe fallback chain from the Z.ai plan through free cloud providers to an unlimited local GPU model, plus three companion skills (key setup, automatic model fallback, token/quota tracking). Read docs-guide.md first.",
"description_i18n": {
"en": "Complete community guide to running ZCode on a free stack: quota-safe fallback chain from the Z.ai plan through free cloud providers to an unlimited local GPU model, plus three companion skills (key setup, automatic model fallback, token/quota tracking). Read docs-guide.md first.",
"zh-CN": "完整的 ZCode 免费方案社区指南:从 Z.ai 套餐到免费云供应商再到本地 GPU 无限量模型的额度安全回退链,并附带三个配套技能(密钥接入、模型自动回退、用量/额度统计)。请先阅读 docs-guide.md。"
},
"version": "1.0.0",
"author": {
"name": "Tejas Lowanshi",
"url": "https://github.com/Tejs2005"
},
"category": "guides",
"keywords": [
"free-tier",
"fallback-chain",
"openrouter",
"gemini",
"local-model",
"quota",
"guide"
]
}
12 changes: 12 additions & 0 deletions external_plugins/free-guide/README-FIRST.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# 📦 ZCode-FREE-GUIDE — read this first

**You received:** `MAKE-ZCODE-FREE.md` (the full guide) + `skills/` (3 ready-made AI skills).

**Do in this order:**
1. Read `MAKE-ZCODE-FREE.md` top to bottom once.
2. Install the router + grab your own free keys (Part 1 + Part 4). **Never reuse someone else's keys.**
3. Add the local model so you can never be cut off (Part 1E).
4. Turn ON model-chain fallback (Part 1 — critical, it's off by default).
5. Wire it into ZCode (Part 2), install the skills (Part 5), do the security checklist (Part 6).

Build time: ~30 minutes. Everything in the guide was tested working on 2026-10-07 on Fedora 44.
61 changes: 61 additions & 0 deletions external_plugins/free-guide/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# free-guide

[中文文档](./README_CN.md)

Community guide plugin for the ZCode plugins marketplace: everything needed to run ZCode
on a **free stack** — tested end-to-end on Fedora 44 by Tejas Lowanshi & ZCode (2026-10-07).

## What it gives you

A quota-safe fallback chain, so a session never hard-stops when a cloud quota dies:

```
ZCode (default: Z.ai plan)
│ if quota dies, falls to…
▼
CCR Router (local, 127.0.0.1:3456)
├─ GPT models (ChatGPT/Codex account login — no key needed)
├─ Claude models (via OmniRoute: GitHub Copilot + Kiro pools)
├─ Gemini 3.x (Google AI Studio key — FREE, no card)
├─ Nemotron/Gemma (OpenRouter key — FREE models)
└─ qwen2.5-coder:7b (LOCAL on your own GPU — unlimited)
```

## Files

- **`docs-guide.md`** — the complete setup guide (read this first)
- **`skills/free-api-key-setup/`** — wire any new API key into ZCode correctly
- **`skills/auto-model-fallback/`** — auto-switch to the next provider on quota/auth errors
- **`skills/token-counter/`** — track how much of each provider's quota you have burned
- **`README-FIRST.txt`** — one-page quick start

## Skills overview

| Skill | Trigger | What it does |
| --- | --- | --- |
| `free-api-key-setup` | you hand the agent a new API key | Provider schema, key-prefix table, `api.type` gotchas; never echoes the key |
| `auto-model-fallback` | model errors (429/401/404/5xx) | Classifies and walks the fallback chain; optional claude-code-router for true auto-switching |
| `token-counter` | "how much quota left" | Live usage where the provider exposes an API, documented caps where it doesn't; exits 1 at warn threshold |

## Disclaimer

Free tiers and model lineups change often — the guide was accurate for October 2026 and
notes which specifics to re-check (e.g. DeepSeek `:free` was already gone, `gemini-2.5-pro`
retired for new users). Provider caps live inside the skills so they can be updated
without touching the guide.

## Install

Inside ZCode: Plugin Marketplace → search **free-guide** → install. Or test from source:

```bash
git clone https://github.com/zai-org/zcode-plugins
cd zcode-plugins
pnpm install --frozen-lockfile && pnpm build
# add dist/local-marketplace via Plugin Marketplace → New
```

## Author

Built by **Tejas Lowanshi** ([@Tejs2005](https://github.com/Tejs2005)) with ZCode, as the
"send this to anyone" bundle for the free AI stack. Apache-2.0 like the rest of this repo.
45 changes: 45 additions & 0 deletions external_plugins/free-guide/README_CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# free-guide

[English](./README.md)

ZCode 插件市场的社区指南插件:在**免费方案**上运行 ZCode 所需的一切——由 Tejas Lowanshi
与 ZCode 于 2026-10-07 在 Fedora 44 上端到端实测。

## 它能带给你什么

一条额度安全回退链,云额度用完时会话不会硬中断:

```
ZCode(默认:Z.ai 套餐)
│ 额度用尽时回退到…
▼
CCR Router(本地,127.0.0.1:3456)
├─ GPT 模型 (ChatGPT/Codex 账号登录 — 无需密钥)
├─ Claude 模型 (经 OmniRoute:GitHub Copilot + Kiro 池)
├─ Gemini 3.x (Google AI Studio 密钥 — 免费,无需信用卡)
├─ Nemotron/Gemma (OpenRouter 密钥 — 免费模型)
└─ qwen2.5-coder:7b(本地 GPU — 无限量,永远不会用完)
```

## 文件说明

- **`docs-guide.md`** — 完整安装指南(请先阅读)
- **`skills/free-api-key-setup/`** — 把新 API 密钥正确接入 ZCode
- **`skills/auto-model-fallback/`** — 额度/鉴权报错时自动切换到下一个供应商
- **`skills/token-counter/`** — 统计各供应商额度已用多少
- **`README-FIRST.txt`** — 一页快速上手

## 免责声明

免费额度和模型阵容经常变化——本指南在 2026 年 10 月是准确的,并标注了需要复核的细节
(例如 DeepSeek `:free` 已下线、`gemini-2.5-pro` 对新用户已退役)。供应商额度上限
放在各技能内部,便于在不改动指南的情况下更新。

## 安装

ZCode 内:插件市场 → 搜索 **free-guide** → 安装。

## 作者

由 **Tejas Lowanshi** 与 ZCode 共同构建,作为"发给任何人"的免费 AI 方案包。
许可证与本仓库一致(Apache-2.0)。
173 changes: 173 additions & 0 deletions external_plugins/free-guide/docs-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
# 🆓 MAKE ZCODE FREE — Complete Setup Guide

*Built by Tejas & ZCode on 2026-10-07. Tested end-to-end on Fedora 44. Send this file + the `skills/` folder to anyone and they can replicate the whole setup.*

---

## What you end up with

```
ZCode (default: Z.ai plan — "me")
│ if quota dies, ZCode falls to…
▼
CCR Router (local, 127.0.0.1:3456)
├─ GPT models (ChatGPT/Codex account login — no key needed)
├─ Claude models (via OmniRoute: GitHub Copilot + Kiro pools)
├─ Gemini 3.x (Google AI Studio key — FREE, no card)
├─ Nemotron/Gemma (OpenRouter key — FREE models)
└─ qwen2.5-coder:7b (LOCAL on your own GPU — unlimited, can never run out)
```

**The promise:** you never hard-stop. If every cloud quota dies, the router silently drops to the model running on your own GPU.

---

## PART 1 — Install the router (CCR)

```bash
npm config set prefix ~/.local
npm install -g @musistudio/claude-code-router
ccr ui
```

- Management UI opens at **http://127.0.0.1:3458**
- The API gateway runs at **http://127.0.0.1:3456**
- ⚠️ After a reboot you must run `ccr ui` again (autostart not configured).

### Provider A: ChatGPT/Codex (big GPT models, no API key)
In the UI → Providers → connect your **ChatGPT account** (Codex login). You get: `gpt-6-luna`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-reserve`.

### Provider B: Google Gemini (FREE — best free cloud tier)
1. Go to **https://aistudio.google.com** → sign in with Google → "Get API key" → create. No credit card.
2. CCR UI → Providers → add custom provider:
- Type/base: `https://generativelanguage.googleapis.com/v1beta/openai` (OpenAI-compatible)
- Paste your key. Models: `gemini-3.5-flash`, `gemini-3.8-flash`, `gemini-3.1-pro-preview`
- Note: `gemini-2.5-pro` is retired for new users (404). Some pro models are paid-tier only.

### Provider C: OpenRouter (free models)
1. **https://openrouter.ai/keys** → sign in → Create key (real keys start `sk-or-v1-`).
2. CCR provider: base `https://openrouter.ai/api/v1`, paste key.
3. Best free models (lineup as of Oct 2026 — DeepSeek `:free` is GONE): `nvidia/nemotron-3-super-120b-a12b:free`, `nvidia/nemotron-3-ultra-550b-a55b:free`, `google/gemma-4-31b-it:free`.

### Provider D: Groq (optional — fast, free)
Key from **https://console.groq.com/keys** (`gsk_...`). Base `https://api.groq.com/openai/v1`. Models: `openai/gpt-oss-120b`, `qwen/qwen3.8-27b`.
⚠️ **Known bug:** this CCR build can hang forever on Groq requests (even though the key works — verify directly first). If a test hangs, keep Groq OUT of the fallback chain until CCR updates.

### Provider E: Local unlimited fallback (the "never stop" guarantee)
```bash
# Fedora: ollama may already be installed; if not:
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b # ~4.7GB, fits an 8GB GPU (RTX 3070 etc.)
```
CCR UI → Providers → add:
- Base: `http://127.0.0.1:11434/v1` (OpenAI-compatible), API key: literally `ollama`
- Model: `qwen2.5-coder:7b`
Facts: warm answers in ~0.2–2s; first call after ~5 min idle takes ~60s (model reloads into VRAM).

### Turn ON auto-fallback (critical!)
CCR UI → Routing → fallback:
- Mode: **model-chain**
- Chain (order = preference): `gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-reserve, kr/claude-sonnet-4.5, gh/claude-sonnet-5, gemini-3.5-flash, gemini-3.8-flash, nvidia/nemotron-3-super-120b-a12b:free, qwen2.5-coder:7b`
- Retry: 1

Without this, the router name is a lie — default mode is **off** and failures just error at you.

---

## PART 2 — Wire it into ZCode

Edit `~/.zcode/v2/provider_config.json` (make a backup first!). Add a provider rule:

```json
{
"providerId": "ccr-router",
"providerName": "CCR Router (auto-fallback)",
"enabled": true,
"config": {
"access": { "type": "api-key", "apiKey": "<the local-gateway key>" },
"api": { "type": "anthropic-messages", "baseUrl": "http://127.0.0.1:3456" },
"personalModelIds": ["gpt-6-luna", "gemini-3.5-flash", "kr/claude-sonnet-4.5", "..."]
}
}
```

- The gateway key lives in CCR's UI (API Keys page → "Local Gateway" key, starts `sk-ccr-`). Never share it.
- In `providerOrder`, put your main plan **first** and `ccr-router` **second**.
- Restart ZCode after edits. Pick "CCR Router" models in the session model picker when you want them.

---

## PART 3 — Bonus: OmniRoute (real Claude, free pools)

OmniRoute pools community/subscription accounts and serves an OpenAI-compatible API on **http://localhost:20128**. Your GitHub Copilot + Kiro logins unlock actual **Claude** models.

```bash
npx --legacy-peer-deps omniroute@latest # starts server + dashboard on 20128
```

Dashboard: `http://localhost:20128/home`. Log in, connect GitHub (Copilot) and other accounts, create an API key.

**Old Claude Code flow (still works):**
```bash
# terminal 1
sudo npx --legacy-peer-deps omniroute@latest
# terminal 2
export CLAUDE_CONFIG_DIR="$HOME/.claude-omniroute"
export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="<your omniroute key>"
export ANTHROPIC_API_KEY=""
export ANTHROPIC_MODEL="<model alias>"
claude
```

**Wire OmniRoute into CCR/ZCode too:** add provider with base `http://127.0.0.1:20128/v1` + your omniroute key. Working models (tested): `kr/claude-sonnet-4.5` ✅, `kr/claude-haiku-4.5` ✅, `kr/deepseek-3.2` ✅, `gh/gpt-4.1` ✅, `gh/claude-sonnet-5` (rate-limited often).

**Reality check on "free Claude":** pools run on free-tier accounts that *cool down* (HTTP 429) when quota runs out. Opus/Fable-class models are gated behind paid Copilot tiers. It works, but expect pauses.

---

## PART 4 — The keys you actually need (all free)

| Key | Where | Cost |
|---|---|---|
| Google Gemini | aistudio.google.com | FREE, no card |
| OpenRouter | openrouter.ai/keys | FREE |
| Groq (optional) | console.groq.com/keys | FREE |
| Ollama local | no key at all | FREE forever |
| ChatGPT/Codex | your own login | your plan |

**Rule: everyone makes their OWN keys. Never send keys to each other — store each key in its own file in `~/Desktop/API-KEYS/` (chmod 600) with a note about status/expiry.** Dead keys we burned so we don't again: AIML API key (valid auth, zero funds), AWS Bedrock key (revoked; the long `bedrock-api-key-...` ones are 12-hour temporary tokens — always dead later), OpenRouter keys starting `sk-a4d4c...` (that was actually a local proxy token, not OpenRouter).

---

## PART 5 — Install the skills (in this folder)

Copy the `skills/` folder into `~/.agents/skills/` on the new machine:

```bash
cp -r skills/* ~/.agents/skills/
```

- **free-api-key-setup** — what to do when you get a new API key (wire it correctly, key-format cheatsheet)
- **auto-model-fallback** — what to do when a model dies (classify error → walk the chain)
- **token-counter** — run `scripts/token-usage.py` to check per-provider quota status (exits 1 when a threshold is hit → time to fall back)

---

## PART 6 — Security checklist (do not skip)

- [ ] OmniRoute dashboard: **change the default password** (`CHANGEME`) — Dashboard → Settings → Security. It listens on 0.0.0.0 by default = visible to your whole Wi-Fi network.
- [ ] Never paste API keys into chats, screenshots, or repos. Keep them in `~/Desktop/API-KEYS/` (600 perms).
- [ ] The CCR gateway key (`sk-ccr-...`) stays on your machine only.

---

## Troubleshooting — lessons we paid for

1. **"Hi" takes 1m54s** → not the router. Giant continued-session context (282K tokens) re-read cold every message (Codex backend has no prompt caching via CCR). **Fix: start fresh chats when things feel slow.**
2. **Router answers but model errors** → fallback mode was `off`. Set model-chain (Part 1).
3. **Groq hangs through CCR** (but direct API works) → known incompatibility in this CCR build; keep it out of the chain, test after CCR updates.
4. **AIML/OpenRouter-style aggregators** → a valid key with zero balance returns 403 "out of funds" on every model. Check billing first.
5. **gemini-2.5-pro 404** → retired for new accounts; use 3.x.
6. **Local model slow first message** → 60s VRAM reload after idle. Normal.
7. **Where to look when slow/broken** → CCR logs every request: `~/.claude-code-router/app-data/usage.sqlite` (table `usage_events`: model, provider, status, duration, tokens). `sqlite3` CLI isn't installed on Fedora by default — use `python3 -c "import sqlite3..."`.
80 changes: 80 additions & 0 deletions external_plugins/free-guide/skills/auto-model-fallback/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
name: auto-model-fallback
description: Automatically recover when the active ZCode model breaks — rate limits, dead keys, provider outages, removed models. Use when Tejas says a model isn't working, requests fail, "switch model", or when tool calls start erroring with model/provider errors. Covers the zero-software playbook and the claude-code-router auto-failover setup.
---

# Auto Model Fallback

Goal: a broken model should never stall Tejas for more than one message.

## Level 1 — In-session recovery playbook (no extra software)

When model errors appear, classify then act:

| Error pattern | Meaning | Action |
|---|---|---|
| 429 / rate_limit / quota | Free tier exhausted | Don't retry more than once — switch model |
| 401 / invalid api key | Key dead or rotated | Re-wire key (see free-api-key-setup skill), else switch |
| 404 / model not found | Model id removed/renamed | Pick another id from same provider |
| 5xx / overloaded / timeout ×2 | Provider outage | Switch provider, note outage in memory |
| Empty/garbage replies | Model unusable for coding | Switch to a stronger fallback |

**Switch procedure:**
1. Read `~/.zcode/v2/provider_config.json` — list `enabled: true` providers and
their `personalModelIds` / `modelOrder`.
2. Walk this fallback chain (first ALIVE wins):
`zai plan (GLM-5.3-Flash, PRIMARY — Tejas wants to stay on this)` →
`ccr-router provider (auto-falls through: gpt-5.6-terra → gpt-5.6-luna → gpt-5.5 → gpt-reserve → qwen2.5-coder:7b LOCAL via ollama 127.0.0.1:11434, unlimited)`
(openrouter key stored is wrong format, groq/gemini/mistral have no keys yet — chain grows as Tejas adds providers; keep this list updated).
3. Tell Tejas exactly what to pick in the model picker (one tap), or flip
`enabled` flags / model ids per the free-api-key-setup skill and have him
restart the session.
4. After recovery, record in memory: which provider broke, the error, the date.
If the same provider dies 3× in a week, recommend Level 2.

## Level 2 — True automatic switching: claude-code-router (recommended)

Proven pattern (37k★, musistudio/claude-code-router): ONE stable local endpoint
that hides many providers behind it with **retries, key rotation, and ordered
fallback models**. Model breakage becomes invisible — the router silently
serves the next working model.

Install (Fedora, Node 22 present):
```bash
npm install -g @musistudio/claude-code-router
ccr ui # management UI at http://127.0.0.1:3458, gateway at http://127.0.0.1:3456
```
Setup:
1. In the UI → Providers → add each free provider + API key (OpenRouter,
Groq, Gemini, Mistral — it speaks their protocols natively).
2. Routing → set the fallback chain (primary → fallbacks, ordered).
3. ZCode side: add ONE custom provider entry per the free-api-key-setup skill:
`api: { "type": "anthropic-messages", "baseUrl": "http://127.0.0.1:3456" }`,
any apiKey (CCR accepts configured client keys), model ids matching what
the router exposes.
4. Auto-start at login (user systemd unit or KDE autostart .desktop running
`ccr start`); health check: `curl -s http://127.0.0.1:3456/ >/dev/null && echo alive`.

Result: Tejas stays on ONE model entry forever; failures route automatically.

## Level 2 alternative — LiteLLM proxy (OpenAI-compatible chains)

For pure OpenAI-format providers, `litellm --config config.yaml` with:
```yaml
router_settings:
fallbacks:
- primary-model: ["fallback-1", "fallback-2"]
rate_limit_error_fallbacks: # triggers on 429
- primary-model: ["fallback-1"]
```
Point the ZCode provider's baseUrl at the local LiteLLM port
(`http://0.0.0.0:4000/v1`, api type `openai-chat`).

## Hygiene

- Keys only ever go into `provider_config.json` / router config — never chat,
memory, or git.
- Free tiers 429 a lot: the chain exists for that, don't fight a throttled
provider with retries.
- After any failover that required manual work, update this skill's chain and
note the outage in memory.
Loading