omniroute-integration

name	omniroute-integration
description	Integrate with OmniRoute AI Router for multi-provider LLM routing, MCP server access, and A2A agent-to-agent orchestration. Use when integrateing with omniroute ai router for multi-provider llm routing, mcp.
domain	core
author	oyi77
license	Apache-2.0
subdomain	core-platform
tags	["ai-agent","infrastructure","integration","memory","omniroute","self-improvement"]
version	1.0.0

persona: name: "Sam Altman" title: "The AI Infrastructure Expert - Master of LLM Routing" expertise: ['LLM Routing', 'AI Infrastructure', 'API Design', 'Model Orchestration'] philosophy: "The best AI is the one that just works, seamlessly." credentials: ['CEO of OpenAI', 'Former Y Combinator president', 'Led GPT development'] principles: ['Route to best model', 'Fall back gracefully', 'Optimize for cost and quality', 'Monitor everything']

OmniRoute Integration Skill

This skill provides guidance on integrating OmniRoute AI Router with Opencode for enhanced LLM capabilities.

Overview

OmniRoute is a unified AI proxy/router that routes any LLM through one endpoint with multi-provider support (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.) featuring:

• MCP Server (16+ tools for agent control)
• A2A v0.3 Protocol (Agent-to-Agent orchestration)
• Multi-provider routing with intelligent load balancing
• Provider health monitoring and circuit breaker patterns
• Cost tracking and usage analytics
• Security features including prompt injection detection
• API Key Management with model-level permissions
• OAuth Token Management for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, iFlow

Anti-Rationalization Table

Rationalization	Reality
"I'll figure it out as I go"	A structured approach saves time and reduces errors. Follow the workflow in this skill rather than improvising.
"I already know this topic"	Familiarity breeds shortcuts. Use the checklist to verify you haven't missed critical steps.
"This doesn't apply to my situation"	The patterns here generalize across contexts. Adapt, don't skip — the underlying principles hold.
"One more tool will fix it"	Adding complexity rarely solves process gaps. Master the core workflow first.

When to Use

Trigger phrases:

• "omniroute integration"
• "Integrate with OmniRoute AI Router for multi-provider LLM routing, MCP server ac"

Use this skill when:

• You want to route LLM requests through multiple providers for reliability
• You need access to OmniRoute's MCP server for agent control
• You want to leverage A2A protocol for multi-agent workflows
• You need intelligent load balancing and failover between LLM providers
• You want to monitor provider health and costs
• You're building agentic workflows that benefit from multi-provider access

Quick Reference

Endpoint/Method	Description
GET /status	Check service health and availability
POST /execute	Run the primary operation
GET /results	Retrieve operation results
DELETE /cache	Clear cached data

Service Management

# Start OmniRoute service
sudo systemctl start omniroute

# Stop OmniRoute service
sudo systemctl stop omniroute

# Check service status
sudo systemctl status omniroute

# View logs
sudo journalctl -u omniroute -f

API Endpoints

OmniRoute runs on port 20128 by default:

Base URL: http://localhost:20128 API Version: v1 (/api/v1/*) Authentication: Bearer token (any string works for development)

• OpenAI-compatible: http://localhost:20128/v1 (use with any API key string)
• Provider Management: GET/POST/PUT/DELETE http://localhost:20128/api/v1/providers/
• Combos: GET/POST http://localhost:20128/api/v1/combos/
• Usage Analytics: GET http://localhost:20128/api/v1/usage/
• Cost Tracking: GET http://localhost:20128/api/v1/costs/
• Health Checks: GET http://localhost:20128/api/v1/health/
• Registered Keys API: POST http://localhost:20128/api/v1/registered-keys

MCP Server

OmniRoute provides an MCP (Model Context Protocol) server with 16 tools:

Transports:

• stdio: Local IDE integration (Claude Desktop, Cursor, VS Code)
• SSE: /api/mcp/sse
• Streamable HTTP: /api/mcp/stream

Tools Available:

1. get_health - System health status
2. list_combos - Available provider combinations
3. get_combo_metrics - Combo performance metrics
4. switch_combo - Switch active provider combo
5. check_quota - Check provider quota/usage
6. route_request - Route request through optimal provider
7. cost_report - Generate cost reports
8. list_models_catalog - Available models across providers
9. simulate_route - Simulate routing decision
10. set_budget_guard - Configure budget limits
11. set_resilience_profile - Configure retry/failover behavior
12. test_combo - Test provider combo connectivity
13. get_provider_metrics - Individual provider performance
14. best_combo_for_task - Recommend optimal combo for task type
15. explain_route - Explain routing decision rationale
16. get_session_snapshot - Get current session state

A2A Protocol

OmniRoute implements Agent-to-Agent v0.3 protocol:

Endpoints:

• Agent Card: GET /.well-known/agent.json
• Message Send: POST /api/a2a/tasks
• Message Stream: POST /api/a2a/tasks/[id]/stream
• Task Get: GET /api/a2a/tasks/[id]
• Task Cancel: POST /api/a2a/tasks/[id]/cancel

Skills:

• smart-routing - Intelligent LLM provider selection
• quota-management - Provider quota monitoring and alerts

Integration with Opencode

• Connects with existing toolchain via standard interfaces
• Supports webhook-based event notifications
• Compatible with CI/CD pipelines for automated workflows
• Provides structured output for downstream consumption

Configure as Default Model

Add to /home/openclaw/.opencode/config.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "omniroute": {
      "type": "remote", 
      "url": "http://localhost:20128/v1",
      "enabled": true
    }
  },
  "model": {
    "provider": "omniroute",
    "default": "auto/best-chat"
  }
}

Agent Model Configuration

For each agent type, configure the optimal combo:

Agent Type	Recommended Combo	Use Case
Default	best-chat	General conversation
Coding	best-coding	Code generation, refactoring
Fast	best-fast	Quick lookups, small fixes
Reasoning	best-reasoning	Complex logic, debugging
Vision	best-vision	Image understanding
Free	best-free	Budget-constrained tasks

Sub-Agent Configuration

For sub-agents via task():

task(
  category="executor",
  model="auto/best-coding",  // or any combo name
  load_skills=[],
  prompt="..."
)

As an LLM Provider

Configure Opencode to use OmniRoute as an OpenAI-compatible endpoint:

• Base URL: http://localhost:20128
• API Key: Not required (OmniRoute handles auth internally)
• Models: Use any model available through OmniRoute's provider network

Available Combos

OmniRoute provides these pre-configured combos for common use cases:

Auto-Combos (intelligent routing):

• best-chat - Best general chat models
• best-coding - Best coding models
• best-fast - Fastest low-latency models
• best-reasoning - Best reasoning/thinking models
• best-vision - Best vision multimodal models
• best-free - Best free tier models

Provider-Specific Combos:

• antigravity - Antigravity models
• kilocode - KiloCode models
• kiro - Kiro models
• github - GitHub Copilot models
• openai - OpenAI models
• ollamacloud - Ollama Cloud models
• nanobanana - NanoBanana image models
• xai - xAI Grok models
• kimi-coding - Kimi Coding models
• glm - GLM models
• zai - ZAI models
• nvidia - NVIDIA models
• openrouter - OpenRouter models
• siliconflow - SiliconFlow models
• opencode-zen - OpenCode Zen models
• opencode-go - OpenCode Go models
• cloudflare-ai - Cloudflare AI models

Usage:

# Use auto combo
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "auto/best-chat", "messages": [{"role": "user", "content": "Hello"}]}'

# Use provider combo
curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "provider/kilocode", "messages": [{"role": "user", "content": "Write code"}]}'

Using MCP Server in Opencode

Opencode can connect to OmniRoute's MCP server for enhanced agent capabilities:

1. Configure MCP client to connect to http://localhost:20128/mcp/stream
2. Use the 16 available tools for:
   • Dynamic provider switching based on performance
   • Cost-aware model selection
   • Health-aware routing
   • Usage monitoring and alerting

Using A2A for Multi-Agent Workflows

Leverage OmniRoute's A2A implementation:

1. Register Opencode agents as A2A agents
2. Use smart-routing skill for optimal LLM selection
3. Implement quota management to prevent provider overuse
4. Chain multiple agents with specialized capabilities

Configuration Files

{
  "enabled": true,
  "autoRun": false,
  "timeout": 30000,
  "retries": 3
}

Set environment variables as needed for authentication and endpoints.

Environment Variables

Key environment variables in /home/openclaw/omniroute-src/start-omniroute.sh:

• PORT=20128 - Service port
• DATA_DIR=/home/openclaw/.config/omniroute - Data directory
• JWT_SECRET - Authentication secret
• Provider-specific OAuth credentials

Data Directory Structure

• /home/openclaw/.config/omniroute/storage.sqlite - Main database (provider connections, combos, usage logs)
• /home/openclaw/.omniroute/ - Alternative data directory location
• /home/openclaw/.omniroute/patches/ - OpenClaw patches (25 active)
• /home/openclaw/.omniroute/db_backups/ - Automatic database backups

Verification

This section covers verification for the omniroute-integration skill. Key operations include input validation, core processing, and output verification. Refer to the skill overview for detailed usage instructions.

Check Service Health

# With authentication (any string works for development)
curl -s -H "Authorization: Bearer any-string" http://localhost:20128/api/v1/health | jq .

List Available Providers

curl -s -H "Authorization: Bearer any-string" http://localhost:20128/api/v1/providers | jq .

Test OpenAI-Compatible Endpoint

# Use with Cursor, Cline, Claude Desktop, Codex, etc.
# Base URL: http://localhost:20128/v1
# API Key: any-string

Check MCP Server Availability

curl -s http://localhost:20128/.well-known/agent.json | jq .

Troubleshooting

Symptom	Cause	Fix
Operation times out	Network or service issue	Check connectivity and retry
Permission denied	Missing credentials	Verify API keys and access tokens
Invalid output	Input format mismatch	Validate input against expected schema

Service Won't Start

1. Check logs: sudo journalctl -u omniroute -f
2. Verify Node.js version: node -v (should be v22.22.x)
3. Check port availability: sudo lsof -i :20128
4. Verify database integrity: Check /home/openclaw/.omniroute/storage.sqlite

API Returns 404 or Auth Error

1. Verify service is running: sudo systemctl status omniroute
2. Use correct endpoint: /api/v1/ (not /api/)
3. Add auth header: -H "Authorization: Bearer any-string"
4. Check dashboard at: http://localhost:20128/dashboard

Authentication Required (AUTH_001)

• Version 3.3.x requires API key authentication
• Use /v1 endpoint for OpenAI-compatible API (accepts any API key string)
• For /api/v1/* endpoints, add -H "Authorization: Bearer your-key"

Database Issues

1. Check backup directory: /home/openclaw/.omniroute/db_backups/
2. Restore from backup if needed
3. Verify file permissions on storage.sqlite

Best Practices

1. Provider Configuration: Configure multiple providers for redundancy
2. Health Monitoring: Regularly check /api/health endpoint
3. Cost Awareness: Use cost tracking APIs to monitor usage
4. Load Balancing: Leverage combo configurations for intelligent routing
5. Security: Keep JWT_SECRET and provider credentials secure
6. Updates: Regularly pull updates and run database migrations
7. Backups: Monitor automatic backups in /home/openclaw/.omniroute/db_backups/

When NOT to Use

• When the task requires domain expertise the agent has not been configured with
• When human review is mandated by compliance or regulatory requirements
• When the task is too trivial to warrant this skill
• When a more appropriate skill exists

Common Rationalizations

Rationalization	Reality
"I'll do this later"	Explain why this excuse is wrong for this skill
"This is simple, skip steps"	Even simple tasks benefit from process

Red Flags

• Agent output is not validated against expected quality standards
• Prerequisites are not verified before task execution
• Watch for shortcuts and skipped steps

Related Skills

• using-superpowers - Always invoke this first
• dev-browser - For testing web interfaces
• git-master - For version control of configurations
• automation/n8n - For workflow integration with A2A
• mckinsey-research - For strategic provider evaluation

---

Remember: Always check if OmniRoute service is running before attempting to use its features. The integration provides powerful multi-provider LLM capabilities that can significantly enhance Opencode's agent capabilities.

Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality