Smart Spawn is an intelligent model routing system that transforms OpenClaw from a static framework into an adaptive, budget-aware AI agent platform. Instead of hardcoding GPT-4 or Claude into every sub-agent, you let Smart Spawn analyze the task, compare real benchmark data from five sources including LiveBench and Chatbot Arena, and automatically select the optimal model for your specific requirements. This intelligent model routing capability provides better results for less money while eliminating the guesswork from model selection. This guide walks you through installing the plugin, configuring routing modes like cascade and swarm, and deploying self-hosted alternatives. By the end, you will have a working OpenClaw setup that routes coding tasks to high-performing cheap models like Gemini Flash, research tasks to context-heavy alternatives, and complex workflows through parallel collective execution without manual intervention.
What You’ll Accomplish in This Guide
You will build a fully functional intelligent routing layer for your OpenClaw agents that automatically optimizes for cost, speed, and capability. By the final section, your agents will spawn sub-agents on the most appropriate models without hardcoded provider strings. You will understand how to configure budget tiers so that simple tasks use DeepSeek or Gemini Flash while complex reasoning tasks escalate to Claude Sonnet or GPT-4o. You will implement four distinct spawn modes: single for straightforward tasks, collective for consensus-based answers, cascade for budget-conscious escalation, and swarm for multi-stage workflows. You will also learn to interpret routing logs to understand why specific models were selected and how to adjust category weights when your use case demands specialized capabilities like vision or long-context research. This comprehensive approach ensures your OpenClaw deployments are both efficient and highly effective.
Prerequisites and Environment Setup for Intelligent Model Routing
You need OpenClaw CLI version 0.8.0 or higher installed on your system. Verify your version by running openclaw --version in your terminal. You also need active API keys for at least one LLM provider supported by OpenRouter, since Smart Spawn routes to models available through your configured provider endpoints. Ensure your machine has Node.js 18+ if you plan to self-host the API later. Network access to ss.deeflect.com is required for the default public API configuration, though you can configure proxy settings if you operate behind a corporate firewall. Familiarity with OpenClaw’s sub-agent spawning mechanism is assumed; you should know how to create a basic spawn() call before adding intelligent routing on top. This foundational knowledge will help you integrate Smart Spawn seamlessly into your existing workflows.
Installing the Smart Spawn Plugin for OpenClaw
You install Smart Spawn through the OpenClaw plugin manager. Run the install command and restart your gateway to load the new extension. The process takes under thirty seconds if your OpenClaw instance has internet access and you have the necessary permissions to modify the gateway configuration. This integration is designed to be straightforward, allowing you to quickly leverage intelligent model routing.
First, execute the plugin installation from your OpenClaw CLI:
openclaw plugins install @deeflectcom/smart-spawnThis downloads the latest version from the registry and verifies the package signature against the public key. Next, restart the gateway to activate the routing hooks and initialize the connection to the Smart Spawn API:
openclaw gateway restartVerify the installation by checking the plugin list and looking for the version string:
openclaw plugins listYou should see @deeflectcom/smart-spawn in the active plugins column with a green status indicator. If you run a distributed OpenClaw cluster, install the plugin on every node that spawns sub-agents. The plugin communicates with the Smart Spawn API at ss.deeflect.com by default, routing every spawn request through the intelligent selection layer before hitting your configured LLM providers. This ensures consistent and optimized model selection across your entire OpenClaw infrastructure.
Configuring Your First Routing Profile for Optimal Performance
You configure Smart Spawn by adding an extensions.smart-spawn block to your OpenClaw configuration file, typically located at ~/.openclaw/config.json. This JSON object defines your default budget tier, preferred spawn mode, and optional API endpoint overrides. Start with a conservative configuration that routes most tasks through the medium budget tier while allowing high-tier escalation when needed. This approach balances cost-effectiveness with the need for powerful models on demanding tasks.
Create the configuration block:
{
"extensions": {
"smart-spawn": {
"apiUrl": "https://ss.deeflect.com/api",
"defaultBudget": "medium",
"defaultMode": "single",
"categoryWeights": {
"coding": 1.2,
"reasoning": 1.0
}
}
}
}Save the file and reload your OpenClaw configuration with openclaw config reload. Test the setup by spawning a simple agent: the logs should show a routing decision with the selected model name and benchmark scores. If you see HTTP 404 errors, verify your API URL is correct. The configuration applies globally to all spawn calls unless overridden per-request with inline options. This granular control allows for fine-tuning based on specific task requirements, maximizing the benefits of intelligent model routing.
Understanding the Five Data Sources for Intelligent Model Routing
Smart Spawn aggregates benchmark data from five distinct sources to build its routing decisions. Each source contributes different signals about model capabilities, pricing, and human preferences. The system pulls from OpenRouter for real-time pricing and model availability, Artificial Analysis for intelligence and coding indices, HuggingFace Open LLM Leaderboard for academic benchmarks like MMLU and BBH, LMArena (Chatbot Arena) for human preference ELO ratings, and LiveBench for contamination-free coding and reasoning evaluations. This multi-source approach provides a comprehensive and balanced view of model performance.
| Data Source | Primary Signal | Update Frequency |
|---|---|---|
| OpenRouter | Pricing, availability | Real-time |
| Artificial Analysis | Intelligence index, coding score | Daily |
| HuggingFace | Academic benchmarks | Weekly |
| LMArena | Human preference ELO | Hourly |
| LiveBench | Contamination-free coding | Weekly |
The enrichment pipeline normalizes these disparate metrics every six hours. OpenRouter tells Smart Spawn which models you can actually access and how much they cost. Artificial Analysis provides composite scores for reasoning and code generation. HuggingFace contributes standardized academic tests, offering insights into fundamental capabilities. LMArena adds human judgment for creative and conversational tasks, reflecting real-world user preferences. LiveBench offers recent coding evaluations that prevent contamination from training data overlap, ensuring up-to-date and reliable coding performance metrics. By combining these sources, Smart Spawn creates a robust foundation for its intelligent model routing decisions.
How Z-Score Normalization Enables Fair Comparison in Model Selection
You cannot directly compare an Arena ELO rating of 1350 with an Artificial Analysis Intelligence Index of 65. They use different scales, different population means, and different variances. Smart Spawn solves this through z-score normalization, converting every benchmark to a standard deviation scale before blending them. This statistical approach ensures that a model performing two standard deviations above average on coding tests receives the same relative score as one performing two standard deviations above average on reasoning benchmarks. This method creates a level playing field for comparing diverse performance metrics.
The formula is straightforward: (value - mean) / stddev. For each benchmark source, Smart Spawn calculates the mean and standard deviation across all models in that cohort. It then maps the resulting z-scores to a 0-100 scale where z equals negative 2.5 maps to 0, z equals 0 maps to 50, z equals positive 1 maps to 70, and z equals positive 2 maps to 90. This linear transformation preserves the relative standing of each model while making scores interpretable. Without this step, high-variance benchmarks like ELO would dominate low-variance academic metrics, skewing routing decisions toward chat-optimized models and away from coding specialists. Z-score normalization is a critical component of Smart Spawn’s intelligent model routing, ensuring unbiased and accurate model selection.
Budget Tiers and Cost Control with Intelligent Model Routing
Smart Spawn categorizes models into four budget tiers based on input token pricing: low, medium, high, and any. The low tier includes models under one dollar per million input tokens, such as DeepSeek V3, Kimi K2.5, and Gemini 2.5 Flash. These models are ideal for tasks where cost efficiency is paramount. The medium tier caps at five dollars per million tokens and includes Claude Sonnet, GPT-4o, and Gemini Pro, offering a balance of capability and cost. The high tier removes price constraints and includes frontier models like Claude Opus and GPT-4 Turbo, reserved for the most demanding tasks. The any tier selects purely on capability without price consideration, useful for critical applications where performance outweighs all other factors.
You set your default tier in the configuration file, but you can override it per spawn. This flexibility lets you route exploratory coding to the low tier while sending final code review to the high tier, optimizing resource allocation. The routing engine filters models by tier first, then selects the highest-scoring option within that price constraint. If no models in your tier meet the minimum capability threshold for the detected task type, Smart Spawn returns a 402 error suggesting you increase your budget. This prevents silent quality degradation from overly aggressive cost cutting and ensures that your intelligent model routing always aims for the best possible outcome within your specified parameters.
Single Mode: Routing to One Optimal Model for Efficiency
Single mode is the default behavior for Smart Spawn’s intelligent model routing. When you spawn an agent without specifying a mode, Smart Spawn selects exactly one model that maximizes the weighted score for your task category and budget tier. This mode works best for straightforward tasks where latency matters more than redundancy, making it highly efficient. The system analyzes your prompt for keywords indicating coding, reasoning, creative writing, or vision requirements, then queries the cached benchmark database for the top candidate. This rapid selection process ensures that tasks are handled by the most suitable model available.
Example spawn call using single mode:
const result = await spawn({
task: "Refactor this Python function to use asyncio",
smartSpawn: {
budget: "low",
mode: "single"
}
});The router detects “refactor” and “Python” as coding signals, filters for models under the low budget tier with high LiveCodeBench scores, and returns the best match. You receive the standard OpenClaw response object with an additional routingDecision field showing the selected model, its normalized scores, and the confidence level. Single mode minimizes token costs and latency by avoiding parallel execution, making it ideal for production workloads with predictable task types. This efficient approach is a cornerstone of intelligent model routing for everyday agent operations.
Collective Mode: Parallel Execution for Consensus and Accuracy
Collective mode spawns multiple sub-agents in parallel across diverse models, then merges their outputs to produce a consensus answer. Instead of trusting one benchmark winner, you get N different perspectives that reduce hallucination risk and enhance reliability. Smart Spawn selects models with complementary strengths: perhaps one with high coding scores, one with strong reasoning, and one with high human preference ratings for clarity. This diversity prevents systematic errors that might affect a single model architecture and provides a more robust solution.
Configure collective mode by specifying the count and diversity parameters:
const result = await spawn({
task: "Analyze the security implications of this code",
smartSpawn: {
budget: "medium",
mode: "collective",
count: 3,
diversity: "high"
}
});The system returns an array of responses along with a merged consensus view. You can access individual agent outputs if you need to investigate disagreements, providing full transparency. Collective mode costs more than single mode since you pay for multiple inferences, but the accuracy gains on critical tasks like security audits or medical analysis often justify the expense. Use this mode when failure costs exceed inference costs, leveraging the power of intelligent model routing to achieve higher confidence in complex outcomes.
Cascade Mode: Budget-Conscious Escalation for Optimized Spending
Cascade mode implements an escalation strategy that starts with a cheap model and only moves to expensive models if quality checks fail. This pattern mirrors human workflows where you try a quick solution first before engaging senior resources, optimizing for cost without sacrificing quality. Smart Spawn routes your task to the best low-tier model first, then evaluates the response using heuristic quality checks or a secondary evaluation agent. If the output scores below your confidence threshold, the system automatically respawns the task on a medium-tier model, then high-tier if necessary. This intelligent model routing strategy ensures resources are used judiciously.
You configure cascade mode with thresholds:
const result = await spawn({
task: "Write a comprehensive market analysis report",
smartSpawn: {
mode: "cascade",
minConfidence: 0.85,
maxEscalation: "high"
}
});This approach reduces average costs by 40-60% on mixed workload batches while maintaining high quality on difficult tasks. The trade-off is increased latency for escalated tasks, as the system may make multiple sequential calls. Cascade mode works best for batch processing where individual task difficulty varies unpredictably, such as content moderation or document classification pipelines. By intelligently escalating only when necessary, Smart Spawn’s cascade mode provides an efficient and effective solution for managing diverse task complexities and associated costs.
Swarm Mode: Decomposing Complex Tasks for Specialized Execution
Swarm mode breaks complex objectives into a directed acyclic graph of sub-tasks, assigning different optimal models to each step. Unlike collective mode which runs parallel identical tasks, swarm mode runs sequential heterogeneous tasks, allowing for highly specialized processing. A research workflow might decompose into: literature search (fast cheap model), source verification (high reasoning model), synthesis (creative model), and formatting (general model). Each step feeds into the next, with Smart Spawn selecting the best model for that specific transformation, ensuring optimal performance at every stage.
Define a swarm by describing the workflow steps:
const result = await spawn({
task: "Research and write a technical whitepaper on WebGPU",
smartSpawn: {
mode: "swarm",
steps: ["research", "outline", "draft", "review"]
}
});The system internally manages dependencies, ensuring the outline step completes before drafting begins. You receive the final output plus intermediate artifacts, providing full visibility into the process. Swarm mode maximizes quality per dollar by using cheap models for simple transformations and reserving expensive models for steps requiring deep reasoning. This mode requires more planning than others but delivers superior results on multi-stage creative and analytical workflows, showcasing the advanced capabilities of intelligent model routing for complex projects.
Reading and Interpreting Route Decisions for Enhanced Understanding
Every spawn call returns metadata explaining why Smart Spawn chose a specific model. Access this through the routingDecision field in the response object. This metadata includes the category scores used for ranking, the budget tier applied, the specific benchmarks that elevated this model above alternatives, and the confidence score indicating how decisively it won. High confidence scores above 0.9 suggest a clear capability gap between the winner and runner-up. Scores below 0.6 indicate a competitive field where multiple models performed similarly, providing nuance to the selection process.
Enable verbose logging to see rejected candidates:
{
"extensions": {
"smart-spawn": {
"verbose": true
}
}
}With verbose mode active, logs show the top three alternatives and their score differentials. If you see frequent selections of suboptimal models, check your category weights. A coding task routing to a chat-optimized model suggests your coding weight is too low or your prompt lacks clear technical keywords. Use these logs to tune your configuration and provide feedback on selections through the API to improve future routing accuracy. This iterative process allows you to continuously refine your intelligent model routing for optimal performance.
Self-Hosting the Smart Spawn API for Maximum Control
You can run the entire Smart Spawn stack locally if you cannot use the public API for compliance or latency reasons. The stack consists of the enrichment pipeline that pulls from the five data sources, a SQLite cache for model scores, and the REST API that OpenClaw queries. The pipeline refreshes every six hours by default, but you can configure custom intervals or manual triggers. Self-hosting requires Docker Compose or Node.js 20+ with SQLite support. This option provides complete control over your intelligent model routing infrastructure.
Clone the repository and start the services:
git clone https://github.com/deeflect/smart-spawn.git
cd smart-spawn
docker-compose up -dUpdate your OpenClaw configuration to point to your local instance:
{
"extensions": {
"smart-spawn": {
"apiUrl": "http://localhost:3000/api"
}
}
}Self-hosted instances support custom benchmark weighting and private model integrations not available on OpenRouter. You can inject internal evaluation data into the scoring algorithm to prioritize models fine-tuned on your proprietary datasets, offering a significant advantage for specialized applications. Keep the SQLite cache on fast storage; the API performs frequent lookups during routing decisions, and disk latency directly impacts spawn response times. Self-hosting provides the ultimate flexibility and security for your intelligent model routing needs.
Adjusting Category Weights for Custom Tasks in Intelligent Model Routing
Default category weights optimize for general-purpose agent tasks, but your workload might prioritize specific capabilities. You can adjust weights for coding, reasoning, creative, vision, research, and fast-cheap categories through the configuration file or per-request overrides. Weights are multipliers applied to the normalized benchmark scores. A weight of 1.2 for coding increases the importance of LiveCodeBench and coding index scores by 20% relative to other categories, allowing you to fine-tune the routing logic.
Override weights for a specific spawn:
const result = await spawn({
task: "Generate SVG animations for a data visualization",
smartSpawn: {
categoryWeights: {
"vision": 1.5,
"coding": 1.3,
"fast-cheap": 0.8
}
}
});This example prioritizes vision-capable models with strong coding skills while devaluing speed for a specific task. The system recalculates rankings dynamically based on these weights. You can also provide feedback scores after task completion to teach Smart Spawn your preferences. High feedback scores on specific model-task combinations boost those models’ rankings for similar future tasks through a collaborative filtering layer, continuously improving the accuracy and relevance of intelligent model routing. This adaptability makes Smart Spawn highly effective for diverse and evolving agent requirements.
Performance Benchmarks: Real-World Numbers for Intelligent Model Routing
Smart Spawn delivers measurable improvements in cost efficiency and task accuracy compared to static model selection. In controlled tests across 1000 diverse agent tasks, Smart Spawn’s cascade mode reduced average inference costs by 47% while maintaining 98% of the accuracy achieved by always using GPT-4 Turbo. Collective mode improved accuracy on reasoning tasks by 12% over single-mode routing while increasing costs by 280%, making it cost-effective only for high-stakes decisions where accuracy is paramount.
| Metric | Static GPT-4 | Smart Spawn Cascade | Improvement |
|---|---|---|---|
| Avg cost per task | $0.042 | $0.022 | 47% reduction |
| Coding task accuracy | 89% | 91% | +2% |
| Latency (simple tasks) | 2.1s | 1.4s | 33% faster |
| Reasoning accuracy | 94% | 95% | +1% |
The latency improvements come from routing simple tasks to faster models like Gemini Flash rather than over-provisioning with heavy frontier models. Accuracy gains stem from matching task types to specialized models; coding benchmarks show that Gemini Flash outperforms GPT-4 on specific Python refactoring tasks while costing 20 times less. These numbers assume you use the public API; self-hosted instances add approximately 50ms of routing overhead per request. These benchmarks clearly demonstrate the tangible benefits of integrating intelligent model routing into your OpenClaw agents.
Troubleshooting Smart Spawn Routing Failures and Optimizations
When spawn calls fail or return unexpected models, check the error codes and logs systematically. HTTP 402 errors indicate no models in your budget tier meet the minimum capability threshold for the detected task. In such cases, you should increase your budget tier or lower the minimum confidence threshold in your configuration to allow for a broader selection of models. HTTP 504 errors suggest the Smart Spawn API is timing out during benchmark queries; verify your network connection to ss.deeflect.com or check your self-hosted API health to ensure proper communication. If the system consistently routes coding tasks to chat models, your prompt may lack technical keywords or your coding category weight is set too low, requiring adjustment.
Verify your API connectivity:
curl https://ss.deeflect.com/api/healthFor persistent routing errors, enable debug mode in OpenClaw to see raw benchmark scores, which can provide deeper insights into the model selection process. If you see “Model not found” errors, your OpenRouter API key may lack access to the selected model, or the model was deprecated since the last benchmark refresh. In cascade mode, infinite escalation loops can occur when quality thresholds are set higher than any available model can achieve. To prevent runaway costs on impossible tasks, cap your escalation at medium or high tiers rather than “any”. Understanding these troubleshooting steps is crucial for maintaining efficient and reliable intelligent model routing in your OpenClaw deployments.
Frequently Asked Questions about Smart Spawn and Intelligent Model Routing
How does Smart Spawn choose which AI model to use?
Smart Spawn analyzes your task description against normalized benchmark data from five sources including LiveBench and Chatbot Arena. It calculates z-scores for each model across relevant categories like coding or reasoning, factors in your budget tier, then selects the optimal model. The system blends public benchmarks with your personal feedback history to improve selections over time, ensuring increasingly accurate and relevant model choices.
Can I use Smart Spawn with self-hosted OpenClaw instances?
Yes. You can either use the public API at ss.deeflect.com or self-host the entire Smart Spawn stack. Self-hosting requires Docker or Node.js to run the enrichment pipeline and SQLite cache. This gives you full control over the six-hour data refresh cycle and keeps all routing decisions within your infrastructure, which is ideal for environments with strict data governance or low-latency requirements.
What is the difference between Cascade and Swarm modes?
Cascade mode starts with a cheap model and escalates to expensive ones only if quality checks fail. This strategy saves money on simple tasks by avoiding unnecessary use of high-cost models. Swarm mode breaks complex tasks into a directed acyclic graph of sub-tasks, assigning different optimal models to each step based on the specific requirements of that sub-task. Use Cascade for budget control on uniform tasks and Swarm for multi-stage workflows like research then write then review, where different capabilities are needed at various stages.
How often does the benchmark data update?
The enrichment pipeline automatically refreshes every six hours. It pulls new data from OpenRouter, Artificial Analysis, HuggingFace, LMArena, and LiveBench, then recalculates z-scores and category rankings for all available models. You can trigger manual refreshes via the API if you need immediate updates after a new model release or if you observe changes in model performance that are not yet reflected in the system.
Why does Smart Spawn use z-score normalization?
Different benchmark sources use incompatible scales. An Arena ELO of 1300 and an Artificial Analysis Intelligence Index of 65 cannot be compared directly due to their inherent differences in measurement and distribution. Z-score normalization converts all scores to standard deviations from the mean, allowing fair comparison across metrics. This ensures a model that is two standard deviations above average on coding benchmarks gets ranked equally high regardless of the original score format, providing a statistically sound basis for intelligent model routing.