ZeroAPI — Subscription-Based Model Routing

Route incoming tasks to the optimal AI model across available providers. OpenClaw handles all API connections — this skill defines the classification and delegation logic. Classify each task by type and delegate to the appropriate agent/model.

First-Time Setup

When this skill is first loaded, determine the user's available providers:

• Ask: "Which AI subscriptions do you have?" (Claude Max 5x/20x, ChatGPT Plus/Pro, Gemini Advanced, Kimi)
• Map subscriptions to available tiers (see table below)
• Disable tiers for missing providers — those decision steps get skipped
• Confirm the active configuration with the user

To verify providers are actually working after setup, ask the user to run:

openclaw models status

For full provider configuration details, consult references/provider-config.md (in the same directory as this SKILL.md).

Model Tiers

• GPQA (science): Gemini Pro 0.908, Opus 0.769, Codex 0.738*
• Coding (SWE-bench): Codex 49.3*, Opus 43.3, Gemini Pro 35.1
• Math (AIME '25): Codex 99.0*, Gemini Flash 97.0, Opus 54.0
• IFBench (instruction following): Gemini Flash 0.780, Opus 0.639, Codex 0.590*
• TAU-2 (agentic tool use): Kimi K2.5 0.959, Codex 0.811*, Opus 0.780

Decision Algorithm

Walk through these 9 steps IN ORDER for every incoming task. The FIRST match wins. If a required model is unavailable, skip that step and continue to the next.

Estimating token count for Step 1: Count characters in the input and divide by 4. 100k tokens ≈ 400,000 characters. If the user pastes a large file, codebase, or says "analyze this entire repo," assume it exceeds 100k.

Disambiguation Examples

When a task matches multiple steps:

• "Analyze this 200-page PDF and write a Python parser for it" -- Step 1 wins (context size), route to RESEARCH. Then delegate code writing to CODE as a follow-up.
• "Quickly solve this integral" -- Step 2 wins over Step 5 (math trumps speed).
• "Generate a JSON schema for this API" -- Step 8 wins (structured output, not code writing).
• "Review this code and refactor the authentication module" -- Step 4 wins for review, then Step 3 for the refactor (delegate to CODE).

When NOT to Route

Do NOT route away from the current model when:

• User explicitly requests a model. "Use Opus for this" or "don't delegate this" — always respect direct instructions.
• Security-sensitive tasks. If the task involves credentials, private keys, secrets, or personally identifiable data, keep it on the main agent. Do not send sensitive content to sub-agents.
• Debugging a specific model. If the user is testing or comparing model behavior, route to the model they specify.
• Mid-conversation continuity. In a multi-turn conversation where the user asks a quick follow-up, do not switch models just because the follow-up is "simple." Stay on the current model for context continuity unless the user explicitly asks to delegate.

Conflict Resolution

When multiple steps seem to match, resolve with these priority rules:

• Judgment trumps speed. If the task has ambiguity, nuance, or risk — stay on Opus.
• Specialist trumps generalist. If a model has a standout benchmark for the exact task type, prefer it.
• Code writing -- Codex. Code review -- Opus. Different models for writing vs judging.
• Context overflow -- Gemini. Only Gemini models handle 1M context.
• TTFT matters for interactive tasks. Flash-Lite (0.23s), Kimi (1.65s), and Opus (1.76s) respond fast. Codex (20s) and Pro (29.59s) are slow to start — don't use them for quick back-and-forth.
• When truly tied -- Opus. Highest general intelligence, lowest risk of subtle errors.

Sub-Agent Delegation

Use OpenClaw's agent system to delegate:

/agent <agent-id> <instruction>

• You send /agent codex — OpenClaw spawns the sub-agent with that instruction.
• The sub-agent runs in its own workspace and returns a text response.
• Sub-agents do NOT share your conversation context or workspace files. Pass ALL necessary context in the instruction.

Examples

/agent codex Write a Python function that parses RFC 3339 timestamps with timezone support. Return only the code.

/agent gemini-researcher Analyze the differences between SQLite WAL mode and journal mode. Include benchmarks and a recommendation.

/agent gemini-fast Convert the following list into a markdown table with columns: Name, Role, Status.

/agent kimi-orchestrator Coordinate: (1) gemini-researcher gathers data on X, (2) codex writes a parser, (3) report results.

Error Handling and Retries

• Timeout (no response within 60s): Retry once on same model. If it fails again, fall to next fallback.
• Auth error (401/403): Do NOT retry — fall to next fallback immediately and tell user to re-authenticate. See references/oauth-setup.md.
• Rate limit (429): Wait 30 seconds, retry once. If still limited, fall to next fallback.
• Partial/garbage response: Retry once. If still broken, fall to next fallback.
• Model unavailable: Skip that tier entirely and continue.

When a fallback is triggered, briefly inform the user:

"Codex is unavailable, routing to Opus instead."

Multi-Turn Conversation Routing

• Stay on the same model for follow-up messages in the same topic. Context continuity matters more than optimal model selection.
• Re-route only when the task type clearly changes. Example: user discusses architecture (Opus) -- then says "now write the implementation" -- delegate code writing to Codex.

• Summarize the relevant context from the current conversation.
• Pass that summary as part of the delegation instruction.
• Continue on the original model (Opus) with awareness of what the sub-agent produced.

Workspace Isolation

• Sub-agents cannot read your files — paste content into the instruction.
• Sub-agents cannot write to your workspace — output comes back as text.
• Sub-agents share nothing with each other — complete isolation by design.

Collaboration Patterns

Fallback Chains

When a model is unavailable or rate-limited, fall through in reliability order.

Full Stack (4 providers)

Claude + Gemini (2 providers)

Claude + Codex (2 providers)

Claude Only (1 provider)

Provider Setup

For auth setup, OAuth flows (including headless VPS), and multi-device safety details, consult references/oauth-setup.md (in the same directory as this SKILL.md).

For provider configuration (openclaw.json, per-agent models.json, Google Gemini workarounds), consult references/provider-config.md.

Quick reference:

Troubleshooting

For detailed troubleshooting, consult references/troubleshooting.md (in the same directory as this SKILL.md). Common issues:

• "No API provider registered for api: undefined" -- Missing api field in provider config
• "API key not valid" with Gemini subscription -- Wrong API type; use google-gemini-cli not google-generative-ai
• Model shows missing -- Model ID mismatch; gemini-2.5-flash-lite (no -preview suffix)
• Codex 401 Unauthorized -- Token expired; re-run OAuth flow via references/oauth-setup.md
• Sub-agent "Unknown model" -- Provider missing from sub-agent's auth-profile

Cost Summary

References