Omniroute Integration

---
name: omniroute-integration
description: Use when 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
category: core
---

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
```bash
# 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`:

```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():
```typescript
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**:
```bash
# 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
```json
{
  "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
```bash
# With authentication (any string works for development)
curl -s -H "Authorization: Bearer any-string" http://localhost:20128/api/v1/health | jq .
```

### List Available Providers
```bash
curl -s -H "Authorization: Bearer any-string" http://localhost:20128/api/v1/providers | jq .
```

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

### Check MCP Server Availability
```bash
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