v2.3.0 — Cross-Provider Fallbacks & LLM-Friendly Docs

What's New in v2.3.0

Cross-Provider Fallback Chains (CRITICAL fix)

Previous versions used same-provider fallbacks for sub-agents. If a provider went down, agents with only same-provider fallbacks had zero working models.

All configs now use cross-provider chains spanning 2-3 different providers:

Agent	Before (broken)	After (resilient)
codex	Opus only	Opus → Pro → Kimi
gemini-researcher	Flash only (same provider!)	Flash → Opus → Codex
gemini-fast	Pro only (same provider!)	Pro → Opus → Codex
kimi-orchestrator	Opus only	K2 Think → Pro → Opus

Affected files: SKILL.md, references/provider-config.md, examples/full-stack/openclaw.json, examples/claude-gemini/openclaw.json

LLM-Friendly README Rewrite

Complete README restructure optimized for both humans and AI agents:

• Repository file index with descriptions — agents know exactly which file to read
• "For AI agents" callout — start with SKILL.md, read references on demand
• Cross-provider fallback table — all 5 agents with provider labels
• 4 providers / 6 tiers / 5 agents architecture clearly documented
• Structured troubleshooting index — 7 common issues with quick fixes
• Quick start flow — copy config → Gemini models.json → auth → verify

Token Storage Architecture Documentation

New section in references/oauth-setup.md explaining the 3-location token storage problem:

Location	Purpose	Auto-Updated?
credentials/oauth.json	Initial onboard	Only on first onboard
models.providers.*.apiKey	Runtime API calls	By auto-refresh
agents/*/auth-profiles.json	Per-agent tokens	By auto-refresh

Includes a post-renewal sync script for manual OAuth flows.

4 New Troubleshooting Entries

Based on real production issues from VPS audit (Feb 2026):

1. Token desync — Token works for some agents but not others after manual renewal
2. systemd ExecStartPre — || true doesn't work; use - prefix
3. bootstrapMaxChars truncation — MEMORY.md silently truncated; configure bootstrapMaxChars (v2026.2.14+)
4. Config schema rejection — Unrecognized keys invalidate entire config (Zod strict mode)

Other Changes

• Compatibility note: core routing requires v2026.2.6+, bootstrap budget config requires v2026.2.14+
• Fallback table in SKILL.md now shows all 4 fallback columns with cross-provider emphasis
• Version bumped to 2.3.0 across SKILL.md and benchmarks.json

---

Full Changelog: v2.2.0...v2.3.0

v2.2.0 — Progressive Disclosure Restructure

What Changed

SKILL.md restructured following Anthropic's Complete Guide to Building Skills for Claude and OpenClaw skill docs. Core routing logic stays in SKILL.md; heavy reference material moves to references/.

Token Efficiency

• SKILL.md: 4,185 → 2,302 words (-45%)
• Agents now load only core routing logic into context
• Provider config, OAuth flows, and troubleshooting loaded on demand

New: references/ directory

• provider-config.md — Full openclaw.json setup, per-agent models.json, Google Gemini workarounds
• oauth-setup.md — OAuth flows for headless VPS (3 scenarios: OpenClaw agent, Claude Code SSH, Codex CLI), Codex multi-device safety test results (Feb 2026)
• troubleshooting.md — 5 common error messages with causes and fixes

Frontmatter Improvements

• Trigger phrases added to description: "use Codex for this", "delegate to Gemini", "route to the best model"
• Negative triggers: "Do NOT use for single-model conversations or general chat"
• compatibility field: Requires OpenClaw 2026.2.6+
• metadata.openclaw.requires: anyBins gating for both OpenClaw and Claude Code environments

README Updates

• 4 installation paths: shared (~/.openclaw/skills), workspace, Claude Code (~/.claude/skills), extraDirs
• "What's Inside" section documents the references/ structure

No Breaking Changes

• All routing logic, decision algorithm, fallback chains, and delegation syntax unchanged
• Existing OpenClaw configs continue to work
• Skill is backward compatible with v2.1.x

v2.1.1

Fixes

• Reverted Flash-Lite model ID back to gemini-2.5-flash-lite (without -preview). The -preview suffix added in v2.1.0 was incorrect — it was deprecated Aug 2025. Verified across 7 independent sources.
• Corrected Flash-Lite benchmarks: speed 645→495 tok/s, TTFT 0.18→0.23s, intelligence 38.2→21.6 (Artificial Analysis API v4 data)
• Flash-Lite no longer recommended for heartbeats — use Flash instead (IFBench 0.780 vs ~0.21)

Auth Documentation

• Rewrote Provider Setup section for agent-first perspective
• Added Codex OAuth multi-device safety test results (4/4 passed, Feb 2026)
• Added 3 OAuth flow scenarios: OpenClaw agent, Claude Code SSH, generic agents
• Added auth status monitoring commands

Security

• Added .gitignore entries for secrets (.env, *.key, *.pem, credentials)
• Added Gitleaks GitHub Actions workflow for automated secret scanning

Published to ClawHub.

v2.1.0 — Flash-Lite model ID fix

Note: The model ID change in this release was later reverted in v2.1.1. The correct ID is gemini-2.5-flash-lite (without -preview). See v2.1.1 release notes.

Original changes:

• Changed gemini-2.5-flash-lite → gemini-2.5-flash-lite-preview (based on OpenClaw commit 89686ed)
• OpenClaw's normalizeGoogleModelId() only normalizes Gemini 3 model IDs, not Gemini 2.5

This change was incorrect — the -preview suffix was deprecated in Aug 2025. Reverted in v2.1.1.

v2.0.0

Initial release of ZeroAPI — subscription-based model routing for OpenClaw.

Features

• 6-model routing across 4 providers: Anthropic (Opus 4.6), OpenAI (GPT-5.3 Codex), Google (Gemini 3 Pro/Flash/Flash-Lite), Moonshot (Kimi K2.5)
• 9-step decision algorithm with signal-keyword matching
• Benchmark-driven task classification (Artificial Analysis API v4)
• Automatic fallback chains per provider combination
• Sub-agent delegation via /agent syntax
• Collaboration patterns: pipeline, parallel, adversarial, orchestrated
• Error handling with retry + fallback logic
• Multi-turn conversation routing with context continuity
• 4 ready-to-use config examples: claude-only, claude-codex, claude-gemini, full-stack

Cost

Works with Claude Max 5x ($100/mo) up to full 4-provider stack ($250-430/mo). Zero per-token API cost.