diff --git a/.dockerignore b/.dockerignore index 5b921cd983..9f7dea5a31 100644 --- a/.dockerignore +++ b/.dockerignore @@ -30,3 +30,40 @@ npm-debug.log* yarn-debug.log* yarn-error.log* .pnpm-debug.log* + +# Test suites +tests +test-results +playwright-report +blob-report + +# Documentation (not needed in container) +docs +*.md +!README.md + +# Electron (separate build) +electron + +# VS Code extension (separate project) +vscode-extension + +# Build artifacts +*.tgz +*.AppImage +*.deb +*.rpm + +# Package manager lock (bun) +bun.lock + +# Agent config +.agents +.gemini + +# Misc +llm.txt +images +clipr +omnirouteCloud +omnirouteSite diff --git a/.gitignore b/.gitignore index d6c986ea27..f32c82f9a5 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,12 @@ omnirouteCloud/ omnirouteSite/ +# Root-level underscore-prefixed directories (private/draft — never commit) +/_*/ + +# Draft features documentation (internal only) +docs/new-features/ + # dependencies node_modules/ /.pnp @@ -88,6 +94,7 @@ docs/* !docs/AUTO-COMBO.md !docs/MCP-SERVER.md !docs/CLI-TOOLS.md +!docs/COVERAGE_PLAN.md # open-sse tests @@ -140,4 +147,10 @@ vscode-extension/ .idea/ # Local OpenCode agent config -.config/ \ No newline at end of file +.config/ + +# Empty/dangling files +typescript + +# Gemini Antigravity agent data +.gemini/ \ No newline at end of file diff --git a/.npmignore b/.npmignore index c11b218d07..bc60215011 100644 --- a/.npmignore +++ b/.npmignore @@ -26,14 +26,19 @@ scripts/ .github/ .husky/ .vscode/ +.agents/ .env* eslint.config.mjs prettier.config.mjs postcss.config.mjs next.config.mjs tsconfig.json +tsconfig.typecheck-core.json +tsconfig.typecheck-noimplicit-core.json playwright.config.ts +vitest.config.ts next-env.d.ts +llm.txt # Docker docker-compose*.yml @@ -41,8 +46,8 @@ Dockerfile .dockerignore # Misc -restart.sh AGENTS.md +bun.lock # Build artifacts (pre-built goes inside app/) .next/ @@ -56,3 +61,9 @@ node_modules/ electron/ app/electron/ app/vscode-extension/ + +# Subprojects +clipr/ +omnirouteCloud/ +omnirouteSite/ +vscode-extension/ diff --git a/AGENTS.md b/AGENTS.md index 37ce9f9573..62d4261222 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,17 +3,20 @@ ## Project Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support -(OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, Cohere, etc.) -with **MCP Server** (16 tools) and **A2A v0.3 Protocol**. +with **60+ providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks, +Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, and many more) +with **MCP Server** (25 tools), **A2A v0.3 Protocol**, and **Electron desktop app**. ## Stack -- **Runtime**: Next.js 16 (App Router), Node.js, ES Modules (`"type": "module"`) -- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`) +- **Runtime**: Next.js 16 (App Router), Node.js ≥18 <24, ES Modules (`"type": "module"`) +- **Language**: TypeScript 5.9 (`src/`) + JavaScript (`open-sse/`, `electron/`) - **Database**: better-sqlite3 (SQLite) — `DATA_DIR` configurable, default `~/.omniroute/` -- **Streaming**: SSE via `open-sse` internal package +- **Streaming**: SSE via `open-sse` internal workspace package - **Styling**: Tailwind CSS v4 - **i18n**: next-intl with 30 languages +- **Desktop**: Electron (cross-platform: Windows, macOS, Linux) +- **Schemas**: Zod v4 for all API / MCP input validation --- @@ -30,11 +33,13 @@ with **MCP Server** (16 tools) and **A2A v0.3 Protocol**. | `npm run typecheck:noimplicit:core` | Strict checking (no implicit any) | | `npm run check` | Run lint + test | | `npm run check:cycles` | Check for circular dependencies | +| `npm run electron:dev` | Run Electron app in dev mode | +| `npm run electron:build` | Build Electron app for current OS | ### Running Tests ```bash -# All tests +# All tests (unit + vitest + ecosystem + e2e) npm run test:all # Single test file (Node.js native test runner — most tests use this) @@ -52,7 +57,13 @@ npm run test:vitest # E2E with Playwright npm run test:e2e -# Coverage (55% min thresholds) +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min thresholds — statements, lines, functions; 60% branches) npm run test:coverage ``` @@ -69,19 +80,19 @@ Always run `prettier --write` on changed files. - **Target**: ES2022 · **Module**: `esnext` · **Resolution**: `bundler` - `strict: false` — prefer explicit types, don't rely on inference -- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/` +- Path aliases: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*` ### ESLint Rules - **Security (error, everywhere)**: `no-eval`, `no-implied-eval`, `no-new-func` - **Relaxed in `open-sse/` and `tests/`**: `@typescript-eslint/no-explicit-any` = warn -- React hooks rules disabled in `open-sse/` +- React hooks rules and `@next/next/no-assign-module-variable` disabled in `open-sse/` and `tests/` ### Naming | Element | Convention | Example | | ------------------- | -------------------------------- | ------------------------------------ | -| Files | kebab-case | `chatCore.ts`, `tokenHealthCheck.ts` | +| Files | camelCase / kebab-case | `chatCore.ts`, `tokenHealthCheck.ts` | | React components | PascalCase | `Dashboard.tsx`, `ProviderCard.tsx` | | Functions/variables | camelCase | `getHealth()`, `switchCombo()` | | Constants | UPPER_SNAKE | `MAX_RETRIES`, `DEFAULT_TIMEOUT` | @@ -113,33 +124,124 @@ Always run `prettier --write` on changed files. ### Data Layer (`src/lib/db/`) -All persistence uses SQLite through domain-specific modules (`core.ts`, `providers.ts`, -`models.ts`, `combos.ts`, `apiKeys.ts`, `settings.ts`, `backup.ts`). +All persistence uses SQLite through domain-specific modules: +`core.ts`, `providers.ts`, `models.ts`, `combos.ts`, `apiKeys.ts`, `settings.ts`, +`backup.ts`, `proxies.ts`, `prompts.ts`, `webhooks.ts`, `detailedLogs.ts`, +`domainState.ts`, `registeredKeys.ts`, `quotaSnapshots.ts`, `modelComboMappings.ts`, +`cliToolState.ts`, `encryption.ts`, `readCache.ts`, `secrets.ts`, `stateReset.ts`. +Schema migrations live in `db/migrations/` and run via `migrationRunner.ts`. `src/lib/localDb.ts` is a **re-export layer only** — never add logic there. ### Request Pipeline (`open-sse/`) `chatCore.ts` → executor → upstream provider. Translations in `open-sse/translator/`. +**Handlers** (`open-sse/handlers/`): `chatCore.ts`, `responsesHandler.ts`, `embeddings.ts`, +`imageGeneration.ts`, `videoGeneration.ts`, `musicGeneration.ts`, `audioSpeech.ts`, +`audioTranscription.ts`, `moderations.ts`, `rerank.ts`, `search.ts`. + **Upstream headers**: merged after default auth; same header name replaces executor value. **T5 intra-family fallback** recomputes headers using only the fallback model id. Forbidden header names: `src/shared/constants/upstreamHeaders.ts` — keep sanitize, Zod schemas, and unit tests aligned when editing. +### Provider Categories + +- **Free** (4): Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI +- **OAuth** (8): Claude Code, Antigravity, Codex, GitHub Copilot, Cursor, Kimi Coding, Kilo Code, Cline +- **API Key** (48+): OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Perplexity, + Together, Fireworks, Cerebras, Cohere, NVIDIA, Nebius, SiliconFlow, Hyperbolic, + HuggingFace, OpenRouter, Vertex AI, Cloudflare AI, Scaleway, AI/ML API, Pollinations, + Puter, Longcat, Alibaba, Kimi, Minimax, Blackbox, Synthetic, Kilo Gateway, + Z.AI, GLM, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, + NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper, Brave, Exa, + Tavily, OpenCode Zen/Go, Bailian Coding Plan, and more. +- **Custom**: OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) prefixes + +Providers are registered in `src/shared/constants/providers.ts` with Zod validation at module load. + +### Executors (`open-sse/executors/`) + +Provider-specific request executors: `base.ts`, `default.ts`, `cursor.ts`, `codex.ts`, +`antigravity.ts`, `github.ts`, `gemini-cli.ts`, `kiro.ts`, `qoder.ts`, `vertex.ts`, +`cloudflare-ai.ts`, `opencode.ts`, `pollinations.ts`, `puter.ts`. + +### Translator (`open-sse/translator/`) + +Translates between API formats (OpenAI-format ↔ Anthropic, Gemini, etc.). +Includes request/response translators with helpers for image handling. + +### Transformer (`open-sse/transformer/`) + +`responsesTransformer.ts` — transforms Responses API format to/from Chat Completions format. + +### Services (`open-sse/services/`) + +36+ service modules including: `combo.ts` (routing engine), `usage.ts`, `tokenRefresh.ts`, +`rateLimitManager.ts`, `accountFallback.ts`, `sessionManager.ts`, `wildcardRouter.ts`, +`autoCombo/`, `intentClassifier.ts`, `taskAwareRouter.ts`, `thinkingBudget.ts`, +`contextManager.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, +`emergencyFallback.ts`, `workflowFSM.ts`, `backgroundTaskDetector.ts`, `ipFilter.ts`, +`signatureCache.ts`, `volumeDetector.ts`, and more. + +### Domain Layer (`src/domain/`) + +Policy engine modules: `policyEngine.ts`, `comboResolver.ts`, `costRules.ts`, +`degradation.ts`, `fallbackPolicy.ts`, `lockoutPolicy.ts`, `modelAvailability.ts`, +`providerExpiration.ts`, `quotaCache.ts`, `responses.ts`, `configAudit.ts`. + ### MCP Server (`open-sse/mcp-server/`) -16 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (9 scopes), Zod schemas. +25 tools, 3 transports (stdio / SSE / Streamable HTTP). Scoped auth (10 scopes), Zod schemas. + +**Core tools** (18): get_health, list_combos, get_combo_metrics, switch_combo, check_quota, +route_request, cost_report, list_models_catalog, simulate_route, set_budget_guard, +set_routing_strategy, set_resilience_profile, test_combo, get_provider_metrics, +best_combo_for_task, explain_route, get_session_snapshot, sync_pricing. + +**Memory tools** (3): memory_search, memory_add, memory_clear. + +**Skill tools** (4): skills_list, skills_enable, skills_execute, skills_executions. ### A2A Server (`src/lib/a2a/`) -JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup. Agent Card at `/.well-known/agent.json`. +JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup( +Agent Card at `/.well-known/agent.json`. +Skills: `quotaManagement.ts`, `smartRouting.ts`. + +### ACP Module (`src/lib/acp/`) + +Agent Communication Protocol registry and manager. + +### Memory System (`src/lib/memory/`) + +Extraction, injection, retrieval, summarization, and store modules for persistent +conversational memory across sessions. + +### Skills System (`src/lib/skills/`) + +Extensible skill framework: registry, executor, sandbox, built-in skills, +custom skill support, interception, and injection. + +### Compliance (`src/lib/compliance/`) + +Policy index for compliance enforcement. + +### MITM Proxy (`src/mitm/`) + +MITM proxy capability with certificate management, DNS handling, and target routing. + +### Middleware (`src/middleware/`) + +Request middleware including `promptInjectionGuard.ts`. ### Adding a New Provider 1. Register in `src/shared/constants/providers.ts` -2. Add executor in `open-sse/executors/` +2. Add executor in `open-sse/executors/` (if custom logic needed) 3. Add translator in `open-sse/translator/` (if non-OpenAI format) 4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` (if OAuth-based) +5. Add models in `open-sse/config/providerRegistry.ts` --- @@ -151,3 +253,6 @@ JSON-RPC 2.0, SSE streaming, Task Manager with TTL cleanup. Agent Card at `/.wel - **No memory leaks** in SSE streams (abort signals, cleanup) - **Rate limit headers** must be parsed correctly - All API inputs validated with **Zod schemas** +- **Provider constants** validated at module load via Zod (`src/shared/validation/providerSchema.ts`) +- **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts` +- **Memory/Skills** are cross-cutting: affect MCP tools, request pipeline, and A2A skills diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c306f5894f..4ccd03bb42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ Thank you for your interest in contributing! This guide covers everything you ne ### Prerequisites -- **Node.js** 20+ (recommended: 22 LTS) +- **Node.js** >= 18 < 24 (recommended: 22 LTS) - **npm** 10+ - **Git** @@ -33,13 +33,13 @@ echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env Key variables for development: -| Variable | Development Default | Description | -| ---------------------- | ----------------------- | ------------------------- | -| `PORT` | `3000` | Server port | -| `NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Base URL for frontend | -| `JWT_SECRET` | (generate above) | JWT signing secret | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `ENABLE_REQUEST_LOGS` | `false` | Enable debug request logs | +| Variable | Development Default | Description | +| ---------------------- | ------------------------ | --------------------- | +| `PORT` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | ### Dashboard Settings @@ -68,8 +68,8 @@ PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev Default URLs: -- **Dashboard**: `http://localhost:3000/dashboard` -- **API**: `http://localhost:3000/v1` +- **Dashboard**: `http://localhost:20128/dashboard` +- **API**: `http://localhost:20128/v1` --- @@ -108,28 +108,35 @@ test: add observability unit tests refactor(db): consolidate rate limit tables ``` -Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`. +Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`. --- ## Running Tests ```bash -# All unit tests -npm test -npm run test:unit +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all -# Specific test suites -npm run test:security # Security tests -npm run test:fixes # Fix verification tests +# Single test file (Node.js native test runner — most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs -# With coverage -npm run test:coverage -npm run coverage:report +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest # E2E tests (requires Playwright) npm run test:e2e +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + # Lint + format check npm run lint npm run check @@ -140,25 +147,29 @@ Coverage notes: - `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` - `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run - `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap -Current test status: **968+ unit tests** covering: +Current test status: **122 unit test files** covering: - Provider translators and format conversion - Rate limiting, circuit breaker, and resilience - Semantic cache, idempotency, progress tracking -- Database operations and schema +- Database operations and schema (21 DB modules) - OAuth flows and authentication -- API endpoint validation +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems --- ## Code Style - **ESLint** — Run `npm run lint` before committing -- **Prettier** — Auto-formatted via `lint-staged` on commit -- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **Prettier** — Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** — All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) - **No `eval()`** — ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` -- **Zod validation** — Use Zod schemas for API input validation +- **Zod validation** — Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE --- @@ -166,40 +177,60 @@ Current test status: **968+ unit tests** covering: ``` src/ # TypeScript (.ts / .tsx) -├── app/ # Next.js App Router -│ ├── (dashboard)/ # Dashboard pages (.tsx) -│ ├── api/ # API routes (.ts) +├── app/ # Next.js 16 App Router +│ ├── (dashboard)/ # Dashboard pages (23 sections) +│ ├── api/ # API routes (51 directories) │ └── login/ # Auth pages (.tsx) -├── domain/ # Domain types and response helpers (.ts) +├── domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) ├── lib/ # Core business logic (.ts) -│ ├── db/ # SQLite database layer -│ ├── oauth/ # OAuth services per provider -│ ├── cacheLayer.ts # LRU cache -│ ├── semanticCache.ts # Semantic response cache -│ ├── idempotencyLayer.ts # Request deduplication -│ └── localDb.ts # Settings facade (LowDB for config, SQLite for domain data) +│ ├── a2a/ # Agent-to-Agent v0.3 protocol server +│ ├── acp/ # Agent Communication Protocol registry +│ ├── compliance/ # Compliance policy engine +│ ├── db/ # SQLite database layer (21 modules + 16 migrations) +│ ├── memory/ # Persistent conversational memory +│ ├── oauth/ # OAuth providers, services, and utilities +│ ├── skills/ # Extensible skill framework +│ ├── usage/ # Usage tracking and cost calculation +│ └── localDb.ts # Re-export layer only — never add logic here +├── middleware/ # Request middleware (promptInjectionGuard) +├── mitm/ # MITM proxy (cert, DNS, target routing) ├── shared/ │ ├── components/ # React components (.tsx) -│ ├── middleware/ # Correlation IDs, etc. -│ ├── utils/ # Circuit breaker, sanitizer, etc. -│ └── validation/ # Zod schemas -└── sse/ # SSE chat handlers (.ts) +│ ├── constants/ # Provider definitions (60+), MCP scopes, routing strategies +│ ├── utils/ # Circuit breaker, sanitizer, auth helpers +│ └── validation/ # Zod v4 schemas +└── sse/ # SSE proxy pipeline -open-sse/ # @omniroute/open-sse workspace (JavaScript) -├── handlers/ # chatCore.js — main request handler -├── services/ # Rate limit, fallback -├── translators/ # Format converters (OpenAI ↔ Claude ↔ Gemini) -└── utils/ # Progress tracker, stream helpers +open-sse/ # @omniroute/open-sse workspace +├── executors/ # 14 provider-specific request executors +├── handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +├── mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +├── services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama) +├── transformer/ # Responses API transformer +└── utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) tests/ -├── unit/ # Node.js test runner (.test.mjs) -└── e2e/ # Playwright tests +├── unit/ # Node.js test runner (122 test files) +├── integration/ # Integration tests +├── e2e/ # Playwright tests +├── security/ # Security tests +├── translator/ # Translator-specific tests +└── load/ # Load tests docs/ # Documentation -├── USER_GUIDE.md # Provider setup, CLI integration -├── API_REFERENCE.md # All endpoints -├── TROUBLESHOOTING.md # Common issues ├── ARCHITECTURE.md # System architecture +├── API_REFERENCE.md # All endpoints +├── USER_GUIDE.md # Provider setup, CLI integration +├── TROUBLESHOOTING.md # Common issues +├── MCP-SERVER.md # MCP server (25 tools) +├── A2A-SERVER.md # A2A agent protocol +├── AUTO-COMBO.md # Auto-combo engine +├── CLI-TOOLS.md # CLI tools integration +├── COVERAGE_PLAN.md # Test coverage improvement plan +├── openapi.yaml # OpenAPI specification └── adr/ # Architecture Decision Records ``` @@ -207,50 +238,25 @@ docs/ # Documentation ## Adding a New Provider -### Step 1: OAuth Service (if using OAuth) +### Step 1: Register Provider Constants -Create `src/lib/oauth/services/your-provider.ts` extending `OAuthService`: +Add to `src/shared/constants/providers.ts` — Zod-validated at module load. -```typescript -import { OAuthService } from "../OAuthService"; +### Step 2: Add Executor (if custom logic needed) -export class YourProviderService extends OAuthService { - constructor() { - super({ - name: "your-provider", - authUrl: "https://provider.com/oauth/authorize", - tokenUrl: "https://provider.com/oauth/token", - clientId: "...", - scopes: ["..."], - }); - } -} -``` +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. -### Step 2: Register Provider +### Step 3: Add Translator (if non-OpenAI format) -Add to `src/lib/oauth/providers.ts`: +Create request/response translators in `open-sse/translator/`. -```typescript -import { YourProviderService } from "./services/your-provider"; -// Add to the providers map -``` +### Step 4: Add OAuth Config (if OAuth-based) -### Step 3: Add Constants +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. -Add provider constants in `src/lib/providerConstants.ts`: +### Step 5: Register Models -- Provider prefix (e.g., `yp/`) -- Default models -- Pricing info - -### Step 4: Add Translator (if non-OpenAI format) - -Create translator in `open-sse/translators/` if the provider uses a custom API format. - -### Step 5: Add Timeout - -Add request timeout configuration in `src/shared/utils/requestTimeout.ts`. +Add model definitions in `open-sse/config/providerRegistry.ts`. ### Step 6: Add Tests @@ -269,6 +275,7 @@ Write unit tests in `tests/unit/` covering at minimum: - [ ] Build succeeds (`npm run build`) - [ ] TypeScript types added for new public functions and interfaces - [ ] No hardcoded secrets or fallback values +- [ ] All inputs validated with Zod schemas - [ ] CHANGELOG updated (if user-facing change) - [ ] Documentation updated (if applicable) @@ -276,16 +283,13 @@ Write unit tests in `tests/unit/` covering at minimum: ## Releasing -When a new GitHub Release is created (e.g. `v0.4.0`), the package is **automatically published to npm** via GitHub Actions: - -```bash -gh release create v0.4.0 --title "v0.4.0" --generate-notes -``` +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. --- ## Getting Help - **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) - **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) - **ADRs**: See `docs/adr/` for architectural decision records diff --git a/README.ar.md b/README.ar.md deleted file mode 100644 index 7543673d2a..0000000000 --- a/README.ar.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (ar) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/ar/README.md)** diff --git a/README.bg.md b/README.bg.md deleted file mode 100644 index ace55dd961..0000000000 --- a/README.bg.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (bg) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/bg/README.md)** diff --git a/README.cs.md b/README.cs.md deleted file mode 100644 index 2ea24f0434..0000000000 --- a/README.cs.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (cs) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/cs/README.md)** diff --git a/README.da.md b/README.da.md deleted file mode 100644 index 5004128080..0000000000 --- a/README.da.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (da) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/da/README.md)** diff --git a/README.fi.md b/README.fi.md deleted file mode 100644 index 72c81e0cb8..0000000000 --- a/README.fi.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (fi) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/fi/README.md)** diff --git a/README.he.md b/README.he.md deleted file mode 100644 index 66366a95e7..0000000000 --- a/README.he.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (he) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/he/README.md)** diff --git a/README.hu.md b/README.hu.md deleted file mode 100644 index 0d1bfec7ab..0000000000 --- a/README.hu.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (hu) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/hu/README.md)** diff --git a/README.id.md b/README.id.md deleted file mode 100644 index 1a2a5e9ac0..0000000000 --- a/README.id.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (id) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/id/README.md)** diff --git a/README.in.md b/README.in.md deleted file mode 100644 index 885c53aa12..0000000000 --- a/README.in.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (in) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/in/README.md)** diff --git a/README.ja.md b/README.ja.md deleted file mode 100644 index 271a24496d..0000000000 --- a/README.ja.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (ja) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/ja/README.md)** diff --git a/README.ko.md b/README.ko.md deleted file mode 100644 index dd32fb014e..0000000000 --- a/README.ko.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (ko) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/ko/README.md)** diff --git a/README.md b/README.md index dbbc474eb8..38139db5ca 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy — one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions • Embeddings • Image Generation • Video • Music • Audio • Reranking • **Web Search** • MCP Server • A2A Protocol • 100% TypeScript** @@ -52,7 +52,7 @@ _Your universal API proxy — one endpoint, 67+ providers, zero downtime. Now wi --- -## 🆕 What's New in v3.0.0 +## 🆕 What's New > **Upgrading from v2.9.5?** — See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -272,7 +272,7 @@ Developers pay $20–200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** — If subscription quota runs out, automatically redirects to API Key → Cheap → Free with zero manual intervention - **Real-Time Quota Tracking** — Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** — Multiple accounts per provider with auto round-robin — when one runs out, switches to the next -- **Custom Combos** — Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** — Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** — Business/Team workspace quota monitoring directly in the dashboard @@ -284,7 +284,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** — A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** — Automatic and transparent: OpenAI ↔ Claude ↔ Gemini ↔ Responses API - **Response Sanitization** — Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** — Converts `developer` → `system` for non-OpenAI providers; `system` → `user` for GLM/ERNIE @@ -370,7 +370,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** — Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** — Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** — Guided 4-step setup for first-time users -- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** — Configure `http://localhost:20128/v1` once, access 60+ providers @@ -512,7 +512,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** — Global prompt applied to all requests - **Thinking Budget Validation** — Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** — Global strategies that determine how requests are distributed +- **9 Routing Strategies** — Global strategies that determine how requests are distributed - **Wildcard Router** — `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** — Toggle combos directly from the dashboard - **Provider Toggle** — Enable/disable all connections for a provider with one click @@ -579,7 +579,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1323,19 +1323,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### 🤖 Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| 🔧 **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| 🔐 **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| 🔧 **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| 🤝 **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| 🧭 **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| 🎚️ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| 🛰️ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| 📋 **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| 🔐 **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| 📡 **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| 📋 **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| 🧪 **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| ⚙️ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### 🧠 Routing & Intelligence @@ -1346,7 +1346,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | 🔄 **Format Translation** | OpenAI ↔ Claude ↔ Gemini ↔ Responses with schema-safe conversions | | 👥 **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | 🔄 **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| 🎨 **Custom Combos** | 6 balancing strategies + fallback chain control | +| 🎨 **Custom Combos** | 9 balancing strategies + fallback chain control | | 🌐 **Wildcard Router** | `provider/*` dynamic routing | | 🧠 **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | 🔀 **Model Aliases** | Built-in + custom model aliasing and migration safety | diff --git a/README.ms.md b/README.ms.md deleted file mode 100644 index c621bd73e0..0000000000 --- a/README.ms.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (ms) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/ms/README.md)** diff --git a/README.nl.md b/README.nl.md deleted file mode 100644 index f7a878e69e..0000000000 --- a/README.nl.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (nl) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/nl/README.md)** diff --git a/README.no.md b/README.no.md deleted file mode 100644 index 1db4066200..0000000000 --- a/README.no.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (no) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/no/README.md)** diff --git a/README.phi.md b/README.phi.md deleted file mode 100644 index 57baa57a4f..0000000000 --- a/README.phi.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (phi) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/phi/README.md)** diff --git a/README.pl.md b/README.pl.md deleted file mode 100644 index 7a2f9c9c70..0000000000 --- a/README.pl.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (pl) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/pl/README.md)** diff --git a/README.pt.md b/README.pt.md deleted file mode 100644 index 8828324fa1..0000000000 --- a/README.pt.md +++ /dev/null @@ -1,2077 +0,0 @@ -# 🚀 OmniRoute — O gateway de IA gratuito - -### Nunca pare de codificar. Roteamento inteligente para **modelos de IA GRATUITOS e de baixo custo** com fallback automático. - -_Seu proxy de API universal — um endpoint, mais de 67 provedores, zero tempo de inatividade. Agora com orquestração de agentes **MCP e A2A**._ - -**Conclusões de bate-papo • Incorporações • Geração de imagens • Vídeo • Música • Áudio • Reclassificação • **Pesquisa na Web** • Servidor MCP • Protocolo A2A • 100% TypeScript** - ---- - -
- -[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) -[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute) -[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) -[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute) -[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE) -[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) -[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - -[🌐 Website](https://omniroute.online) • [🚀 Quick Start](#-quick-start) • [💡 Features](#-key-features) • [📖 Docs](#-documentation) • [💰 Pricing](#-pricing-at-a-glance) • [💬 WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) - -
- -🌐 **Disponível em:** 🇺🇸 [English](README.md) | 🇧🇷 [Português (Brasil)](docs/i18n/pt-BR/README.md) | 🇪🇸 [Español](docs/i18n/es/README.md) | 🇫🇷 [Français](docs/i18n/fr/README.md) | 🇮🇹 [Italiano](docs/i18n/it/README.md) | 🇷🇺 [Русский](docs/i18n/ru/README.md) | 🇨🇳 [中文 (简体)](docs/i18n/zh-CN/README.md) | 🇩🇪 [Deutsch](docs/i18n/de/README.md) | 🇮🇳 [हिन्दी](docs/i18n/in/README.md) | 🇹🇭 [ไทย](docs/i18n/th/README.md) | 🇺🇦 [Українська](docs/i18n/uk-UA/README.md) | 🇸🇦 [العربية](docs/i18n/ar/README.md) | 🇯🇵 [日本語](docs/i18n/ja/README.md) | 🇻🇳 [Tiếng Việt](docs/i18n/vi/README.md) | 🇧🇬 [Български](docs/i18n/bg/README.md) | 🇩🇰 [Dansk](docs/i18n/da/README.md) | 🇫🇮 [Suomi](docs/i18n/fi/README.md) | 🇮🇱 [עברית](docs/i18n/he/README.md) | 🇭🇺 [Magyar](docs/i18n/hu/README.md) | 🇮🇩 [Bahasa Indonesia](docs/i18n/id/README.md) | 🇰🇷 [한국어](docs/i18n/ko/README.md) | 🇲🇾 [Bahasa Melayu](docs/i18n/ms/README.md) | 🇳🇱 [Nederlands](docs/i18n/nl/README.md) | 🇳🇴 [Norsk](docs/i18n/no/README.md) | 🇵🇹 [Português (Portugal)](docs/i18n/pt/README.md) | 🇷🇴 [Română](docs/i18n/ro/README.md) | 🇵🇱 [Polski](docs/i18n/pl/README.md) | 🇸🇰 [Slovenčina](docs/i18n/sk/README.md) | 🇸🇪 [Svenska](docs/i18n/sv/README.md) | 🇵🇭 [Filipino](docs/i18n/phi/README.md) | 🇨🇿 [Čeština](docs/i18n/cs/README.md) - ---- - -## 🆕 O que há de novo na v3.0.0 - -> **Atualizando da v2.9.5?** — Consulte [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) para todas as alterações. - -| Área | Alterar | -| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🔒 **Segurança CodeQL** | Corrigidos mais de 10 alertas CodeQL: redos polinomiais, aleatoriedade insegura, remediação de injeção de shell | -| ✅ **Validação de Rota** | Todas as 176 rotas de API agora validadas com esquemas Zod + `validateBody()` — CI `check:route-validation:t06` passa | -| 🐛 ** Vazamento de tag omniModel ** | Tags internas `` não vazam mais para clientes em respostas de streaming SSE (#585) | -| 🔑 **API de chaves registradas** | Provisionamento automático de chaves de API via `POST /api/v1/registered-keys` com aplicação de cota por provedor/conta, idempotência, armazenamento SHA-256 e relatório opcional de problemas do GitHub | -| 👁️ **Scoped API Key Reveal** 🆕 | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` | -| 🎨 **Ícones de provedor** | Mais de 130 logotipos de provedores via `@lobehub/icons` (SVG) com PNG → cadeia de fallback genérica | -| 🔄 **Sincronização automática do modelo** | Agendador 24h e alternância manual da interface do usuário para sincronizar listas de modelos para provedores integrados e personalizados compatíveis com OpenAI | -| 🌐 **OpenCode Zen/Go** | Dois novos provedores de @kang-heewon via PR #530: nível gratuito + nível de assinatura via `OpencodeExecutor` | -| 🐛 **Gemini CLI OAuth** | Erro acionável quando `GEMINI_OAUTH_CLIENT_SECRET` está faltando no Docker (foi um erro enigmático do Google) | -| 🐛 **Configuração OpenCode** | `saveOpenCodeConfig()` agora grava TOML corretamente em `XDG_CONFIG_HOME` | -| 🐛 **Substituição de modelo fixado** | `body.model` definido corretamente como `pinnedModel` na proteção de cache de contexto | -| 🐛 **Loop Codex/Claude** | `tool_result` blocos agora convertidos em texto para interromper loops infinitos | -| 🐛 **Redirecionamento de login** | O login não congela mais após pular a configuração da senha | -| 🐛 **Caminhos do Windows** | Caminhos MSYS2/Git-Bash (`/c/...`) normalizados para `C:\...` automaticamente | - ---- - -## 🖼️ Painel principal - -
- OmniRoute Dashboard -
- ---- - -## 📸 Visualização do painel - -
-Clique para ver as capturas de tela do painel - -| Página | Captura de tela | -| -------------------- | ------------------------------------------------- | -| **Fornecedores** | ![Providers](docs/screenshots/01-providers.png) | -| **Combos** | ![Combos](docs/screenshots/02-combos.png) | -| **Análise** | ![Analytics](docs/screenshots/03-analytics.png) | -| **Saúde** | ![Health](docs/screenshots/04-health.png) | -| **Tradutor** | ![Translator](docs/screenshots/05-translator.png) | -| **Configurações** | ![Settings](docs/screenshots/06-settings.png) | -| **Ferramentas CLI** | ![CLI Tools](docs/screenshots/07-cli-tools.png) | -| **Registros de uso** | ![Usage](docs/screenshots/08-usage.png) | -| **Pontos finais** | ![Endpoints](docs/screenshots/09-endpoint.png) | - -
- ---- - -### 🤖 Provedor de IA gratuito para seus agentes de codificação favoritos - -_Conecte qualquer ferramenta IDE ou CLI com tecnologia de IA por meio do OmniRoute - gateway de API gratuito para codificação ilimitada._ - - - - - - - - - - - - - - - - -
- - OpenClaw
- OpenClaw -
- ⭐ 205K - 		- - NanoBot
- NanoBot -
- ⭐ 20.9K - 		- - PicoClaw
- PicoClaw -
- ⭐ 14.6K - 		- - ZeroClaw
- ZeroClaw -
- ⭐ 9.9K - 		- - IronClaw
- IronClaw -
- ⭐ 2.1K -
- - OpenCode
- OpenCode -
- ⭐ 106K - 		- - Codex CLI
- Codex CLI -
- ⭐ 60.8K - 		- - Claude Code
- Claude Code -
- ⭐ 67.3K - 		- - Gemini CLI
- Gemini CLI -
- ⭐ 94.7K - 		- - Kilo Code
- Kilo Code -
- ⭐ 15.5K -
- -📡 Todos os agentes se conectam via http://localhost:20128/v1 ou http://cloud.omniroute.online/v1 — uma configuração, modelos ilimitados e cota - ---- - -## 🤔 Por que OmniRoute? - -**Pare de desperdiçar dinheiro e atingir limites:** - -- A cota de assinatura expira sem ser utilizada todos os meses -- Os limites de taxa impedem você de codificar no meio -- APIs caras (US$ 20-50/mês por provedor) -- Troca manual entre provedores - -**OmniRoute resolve isso:** - -- ✅ **Maximize as assinaturas** - Rastreie a cota, use cada bit antes de redefinir -- ✅ **Fullback automático** - Assinatura → Chave de API → Barato → Gratuito, tempo de inatividade zero -- ✅ **Múltiplas contas** - Round-robin entre contas por provedor -- ✅ **Universal** - Funciona com Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, qualquer ferramenta CLI - ---- - -## 📧 Suporte - -> 💬 **Junte-se à nossa comunidade!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) — Obtenha ajuda, compartilhe dicas e fique atualizado. - -- **Site**: [omniroute.online](https://omniroute.online) -- **GitHub**: [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) -- **Problemas**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -- **Contribuindo**: Consulte [CONTRIBUTING.md](CONTRIBUTING.md), abra um PR ou escolha um `good first issue` -- **Projeto Original**: [9router by decolua](https://github.com/decolua/9router) - -### 🐛 Relatando um bug? - -Ao abrir um problema, execute o comando system-info e anexe o arquivo gerado: - -```bash -npm run system-info -``` - -Isso gera um `system-info.txt` com sua versão do Node.js, versão do OmniRoute, detalhes do sistema operacional, ferramentas CLI instaladas (qoder, gemini, claude, codex, antigravity, droid, etc.), status do Docker/PM2 e pacotes do sistema — tudo o que precisamos para reproduzir seu problema rapidamente. Anexe o arquivo diretamente ao seu problema do GitHub. - ---- - -## 🔄 Como funciona - -``` -┌─────────────┐ -│ Your CLI │ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...) -│ Tool │ -└──────┬──────┘ - │ http://localhost:20128/v1 - ↓ -┌─────────────────────────────────────────┐ -│ OmniRoute (Smart Router) │ -│ • Format translation (OpenAI ↔ Claude) │ -│ • Quota tracking + Embeddings + Images │ -│ • Auto token refresh │ -└──────┬──────────────────────────────────┘ - │ - ├─→ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI - │ ↓ quota exhausted - ├─→ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc. - │ ↓ budget limit - ├─→ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M) - │ ↓ budget limit - └─→ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited) - -Result: Never stop coding, minimal cost -``` - ---- - -## 🎯 O que o OmniRoute resolve — 30 pontos reais de dor e casos de uso - -> **Todo desenvolvedor que usa ferramentas de IA enfrenta esses problemas diariamente.** O OmniRoute foi criado para resolver todos eles, desde custos excessivos até bloqueios regionais, desde fluxos quebrados de OAuth até operações de protocolo e observabilidade empresarial. - -
-💸 1. "Eu pago por uma assinatura cara, mas ainda sou interrompido pelos limites" - -Os desenvolvedores pagam US$ 20–200/mês pelo Claude Pro, Codex Pro ou GitHub Copilot. Mesmo pagando, a cota tem um limite máximo – 5h de uso, limites semanais ou limites de taxa por minuto. No meio da sessão de codificação, o provedor para de responder e o desenvolvedor perde fluxo e produtividade. - -**Como o OmniRoute resolve isso:** - -- **Smart 4-Tier Fallback** — Se a cota de assinatura acabar, redireciona automaticamente para API Key → Barato → Gratuito sem intervenção manual -- **Rastreamento de cota em tempo real** — Mostra o consumo de tokens em tempo real com contagem regressiva redefinida (5h, diariamente, semanalmente) -- **Suporte para múltiplas contas** — Várias contas por provedor com round-robin automático — quando uma acabar, muda para a próxima -- **Combos personalizados** — Cadeias alternativas personalizáveis com 6 estratégias de balanceamento (preencher primeiro, round-robin, P2C, aleatório, menos usado, com custo otimizado) -- **Codex Business Quotas** — Monitoramento de cotas de espaço de trabalho de negócios/equipe diretamente no painel - -
- -
-🔌 2. "Preciso usar vários provedores, mas cada um tem uma API diferente" - -OpenAI usa um formato, Claude (Anthropic) usa outro, Gemini ainda outro. Se um desenvolvedor quiser testar modelos de diferentes provedores ou fazer fallback entre eles, ele precisará reconfigurar SDKs, alterar endpoints e lidar com formatos incompatíveis. Provedores personalizados (FriendLI, NIM) possuem endpoints de modelo não padrão. - -**Como o OmniRoute resolve isso:** - -- **Endpoint unificado** — Um único `http://localhost:20128/v1` serve como proxy para todos os mais de 67 provedores -- **Tradução de formato** — Automática e transparente: OpenAI ↔ Claude ↔ Gemini ↔ API de respostas -- **Response Sanitization** — Remove campos não padrão (`x_groq`, `usage_breakdown`, `service_tier`) que quebram o OpenAI SDK v1.83+ -- **Normalização de funções** — Converte `developer` → `system` para provedores não-OpenAI; `system` → `user` para GLM/ERNIE -- **Think Tag Extraction** — Extrai blocos `` de modelos como DeepSeek R1 para `reasoning_content` padronizado -- **Saída estruturada para Gemini** — `json_schema` → `responseMimeType`/`responseSchema` conversão automática -- **`stream` o padrão é `false`** — Alinha-se com a especificação OpenAI, evitando SSE inesperado em SDKs Python/Rust/Go - -
- -
-🌐 3. "Meu provedor de IA bloqueia minha região/país" - -Provedores como OpenAI/Codex bloqueiam o acesso de determinadas regiões geográficas. Os usuários recebem erros como `unsupported_country_region_territory` durante conexões OAuth e API. Isto é especialmente frustrante para desenvolvedores de países em desenvolvimento. - -**Como o OmniRoute resolve isso:** - -- **Configuração de proxy de 3 níveis** — Proxy configurável em 3 níveis: global (todo o tráfego), por provedor (apenas um provedor) e por conexão/chave -- **Selos de proxy codificados por cores** — Indicadores visuais: 🟢 proxy global, 🟡 proxy do provedor, 🔵 proxy de conexão, sempre mostrando o IP -- **Troca de token OAuth por meio de proxy** — O fluxo OAuth também passa pelo proxy, resolvendo `unsupported_country_region_territory` -- **Testes de conexão via proxy** — Os testes de conexão usam o proxy configurado (não há mais bypass direto) -- **Suporte SOCKS5** — Suporte completo ao proxy SOCKS5 para roteamento de saída -- **TLS Fingerprint Spoofing** — Impressão digital TLS semelhante a um navegador via `wreq-js` para ignorar a detecção de bot -- **🔏 CLI Fingerprint Matching** — Reordena cabeçalhos e campos de corpo para corresponder às assinaturas binárias CLI nativas, reduzindo drasticamente o risco de sinalização de conta. O IP do proxy é preservado – você obtém mascaramento de IP furtivo ** e ** simultaneamente - -
- -
-🆓 4. "Quero usar IA para codificação, mas não tenho dinheiro" - -Nem todos podem pagar US$ 20–200/mês por assinaturas de IA. Estudantes, desenvolvedores de países emergentes, amadores e freelancers precisam de acesso a modelos de qualidade a custo zero. - -**Como o OmniRoute resolve isso:** - -- **Provedores de nível gratuito integrados** — Suporte nativo para provedores 100% gratuitos: Qoder (5 modelos ilimitados via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 modelos ilimitados: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID gratuitamente), Gemini CLI (180 mil tokens/mês grátis) -- **Ollama Cloud** — Modelos Ollama hospedados na nuvem em `api.ollama.com` com nível gratuito de "uso leve"; use o prefixo `ollamacloud/` -- **Combos somente gratuitos** — Cadeia `gc/gemini-3-flash → if/kimi-k2-thinking → qw/qwen3-coder-plus` = US$ 0/mês com tempo de inatividade zero -- **NVIDIA NIM Free Access** — ~40 RPM de acesso gratuito para desenvolvedores para sempre a mais de 70 modelos em build.nvidia.com (transição de créditos para limites de taxa pura) -- **Estratégia de Custo Otimizado** — Estratégia de roteamento que escolhe automaticamente o provedor mais barato disponível - -
- -
-🔒 5. "Preciso proteger meu gateway de IA contra acesso não autorizado" - -Ao expor um gateway de IA à rede (LAN, VPS, Docker), qualquer pessoa com o endereço pode consumir os tokens/cota do desenvolvedor. Sem proteção, as APIs ficam vulneráveis ​​ao uso indevido, injeção imediata e abuso. - -**Como o OmniRoute resolve isso:** - -- **Gerenciamento de chaves de API** — Geração, rotação e escopo por provedor com uma página `/dashboard/api-manager` dedicada -- **Permissões em nível de modelo** — Restringir chaves de API a modelos específicos (`openai/*`, padrões curinga), com alternância Permitir tudo/Restringir -- **API Endpoint Protection** — Exija uma chave para `/v1/models` e bloqueie provedores específicos da listagem -- **Auth Guard + Proteção CSRF** — Todas as rotas do painel protegidas com middleware `withAuth` + tokens CSRF -- **Rate Limiter** — Limitação de taxa por IP com janelas configuráveis -- **Filtragem de IP** — Lista de permissões/lista de bloqueio para controle de acesso -- **Prompt Injection Guard** — Sanitização contra padrões de prompt maliciosos -- **Criptografia AES-256-GCM** — Credenciais criptografadas em repouso - -
- -
-🛑 6. "Meu provedor caiu e perdi meu fluxo de codificação" - -Os provedores de IA podem ficar instáveis, retornar erros 5xx ou atingir limites de taxa temporários. Se um desenvolvedor depender de um único provedor, ele será interrompido. Sem disjuntores, tentativas repetidas podem travar o aplicativo. - -**Como o OmniRoute resolve isso:** - -- **Disjuntor por modelo** — Abertura/fechamento automático com limites configuráveis e resfriamento (Fechado/Aberto/Meio-aberto), com escopo definido por modelo para evitar bloqueios em cascata -- **Retirada exponencial** — Atrasos progressivos em novas tentativas -- **Rebanho Anti-Trovão** — Proteção Mutex + semáforo contra tempestades de novas tentativas simultâneas -- **Combo Fallback Chains** — Se o provedor primário falhar, ele cairá automaticamente na cadeia sem intervenção -- **Combo Circuit Breaker** — Desativa automaticamente provedores com falha em uma cadeia de combinação -- **Health Dashboard** — Monitoramento de tempo de atividade, estados de disjuntores, bloqueios, estatísticas de cache, latência p50/p95/p99 - -
- -
-🔧 7. "Configurar cada ferramenta de IA é tedioso e repetitivo" - -Os desenvolvedores usam Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Cada ferramenta precisa de uma configuração diferente (endpoint da API, chave, modelo). Reconfigurar ao trocar de provedor ou modelo é uma perda de tempo. - -**Como o OmniRoute resolve isso:** - -- **CLI Tools Dashboard** — Página dedicada com configuração de um clique para Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline -- **GitHub Copilot Config Generator** — Gera `chatLanguageModels.json` para código VS com seleção de modelo em massa -- **Assistente de integração** — Configuração guiada em 4 etapas para usuários iniciantes -- **Um endpoint, todos os modelos** — Configure `http://localhost:20128/v1` uma vez, acesse mais de 67 provedores - -
- -
-🔑 8. "Gerenciar tokens OAuth de vários provedores é um inferno" - -Claude Code, Codex, Gemini CLI, Copilot — todos usam OAuth 2.0 com tokens expirados. Os desenvolvedores precisam se autenticar novamente constantemente, lidar com `client_secret is missing`, `redirect_uri_mismatch` e falhas em servidores remotos. OAuth em LAN/VPS é particularmente problemático. - -**Como o OmniRoute resolve isso:** - -- **Atualização automática de token** — Os tokens OAuth são atualizados em segundo plano antes da expiração -- **OAuth 2.0 (PKCE) integrado ** — Fluxo automático para Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder -- **OAuth de várias contas** — Várias contas por provedor por meio de extração de token JWT/ID -- **OAuth LAN/Remote Fix** — Detecção de IP privado para `redirect_uri` + modo URL manual para servidores remotos -- **OAuth por trás do Nginx** — Usa `window.location.origin` para compatibilidade de proxy reverso -- **Guia OAuth remoto** — Guia passo a passo para credenciais do Google Cloud em VPS/Docker - -
- -
-📊 9. "Não sei quanto estou gastando ou onde" - -Os desenvolvedores usam vários provedores pagos, mas não têm uma visão unificada dos gastos. Cada provedor possui seu próprio painel de faturamento, mas não há visão consolidada. Custos inesperados podem se acumular. - -**Como o OmniRoute resolve isso:** - -- **Painel de análise de custos** — Acompanhamento de custos por token e gerenciamento de orçamento por provedor -- **Limites de orçamento por nível** — Teto de gastos por nível que aciona substituto automático -- **Configuração de preços por modelo** — Preços configuráveis por modelo -- **Estatísticas de uso por chave de API** — Contagem de solicitações e carimbo de data/hora do último uso por chave -- **Painel de análise** — Cartões de estatísticas, gráfico de uso do modelo, tabela de provedores com taxas de sucesso e latência - -
- -
-🐛 10. "Não consigo diagnosticar erros e problemas em chamadas de IA" - -Quando uma chamada falha, o desenvolvedor não sabe se foi um limite de taxa, um token expirado, um formato errado ou um erro do provedor. Logs fragmentados em diferentes terminais. Sem observabilidade, a depuração é uma tentativa e erro. - -**Como o OmniRoute resolve isso:** - -- **Painel de registros unificados** — 4 guias: registros de solicitação, registros de proxy, registros de auditoria, console -- **Console Log Viewer** — Visualizador em estilo terminal em tempo real com níveis codificados por cores, rolagem automática, pesquisa, filtro -- **SQLite Proxy Logs** — Logs persistentes que sobrevivem às reinicializações do servidor -- **Translator Playground** — 4 modos de depuração: Playground (tradução de formato), Chat Tester (ida e volta), Test Bench (lote), Live Monitor (tempo real) -- **Solicitar telemetria** — latência p50/p95/p99 + rastreamento X-Request-Id -- **Registro baseado em arquivo com rotação** — O interceptador do console captura tudo no log JSON com rotação baseada em tamanho -- **Relatório de informações do sistema** — `npm run system-info` gera `system-info.txt` com seu ambiente completo (versão do nó, versão do OmniRoute, sistema operacional, ferramentas CLI, status do Docker/PM2). Anexe-o ao relatar problemas para triagem instantânea. - -
- -
-🏗️ 11. "Implantar e manter o gateway é complexo" - -Instalar, configurar e manter um proxy de IA em diferentes ambientes (local, VPS, Docker, nuvem) exige muito trabalho. Problemas como caminhos codificados, `EACCES` em diretórios, conflitos de porta e compilações de plataforma cruzada adicionam atrito. - -**Como o OmniRoute resolve isso:** - -- **instalação global npm** — `npm install -g omniroute && omniroute` — concluído -- **Docker Multiplataforma** — AMD64 + ARM64 nativo (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Perfis Docker Compose** — `base` (sem ferramentas CLI) e `cli` (com Claude Code, Codex, OpenClaw) -- **Aplicativo Electron Desktop** — Aplicativo nativo para Windows/macOS/Linux com bandeja do sistema, inicialização automática e modo offline -- **Modo Split-Port** — API e Dashboard em portas separadas para cenários avançados (proxy reverso, rede de contêineres) -- **Cloud Sync** — Sincronização de configuração entre dispositivos via Cloudflare Workers -- **Backups de banco de dados** — Backup, restauração, exportação e importação automática de todas as configurações - -
- -
-🌍 12. "A interface é somente em inglês e minha equipe não fala inglês" - -Equipes em países que não falam inglês, especialmente na América Latina, Ásia e Europa, enfrentam dificuldades com interfaces somente em inglês. As barreiras linguísticas reduzem a adoção e aumentam os erros de configuração. - -**Como o OmniRoute resolve isso:** - -- **Painel i18n — 30 idiomas** — Todas as mais de 500 teclas traduzidas, incluindo árabe, búlgaro, dinamarquês, alemão, espanhol, finlandês, francês, hebraico, hindi, húngaro, indonésio, italiano, japonês, coreano, malaio, holandês, norueguês, polonês, português (PT/BR), romeno, russo, eslovaco, sueco, tailandês, ucraniano, vietnamita, chinês, filipino, inglês -- **Suporte RTL** — Suporte da direita para a esquerda para árabe e hebraico -- **READMEs multilíngues** — 30 traduções completas de documentação -- **Seletor de idioma** — Ícone de globo no cabeçalho para troca em tempo real - -
- -
-🔄 13. "Preciso de mais do que bate-papo - preciso de incorporações, imagens, áudio" - -IA não é apenas conclusão de bate-papo. Os desenvolvedores precisam gerar imagens, transcrever áudio, criar embeddings para RAG, reclassificar documentos e moderar conteúdo. Cada API possui um endpoint e formato diferente. - -**Como o OmniRoute resolve isso:** - -- **Embeddings** — `/v1/embeddings` com 6 provedores e mais de 9 modelos -- **Geração de imagens** — `/v1/images/generations` com 10 provedores e mais de 20 modelos (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Texto para vídeo** — `/v1/videos/generations` — ComfyUI (AnimateDiff, SVD) e SD WebUI -- **Texto para música** — `/v1/music/generations` — ComfyUI (áudio estável aberto, MusicGen) -- **Transcrição de áudio** — `/v1/audio/transcriptions` — Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Conversão de texto em fala** — `/v1/audio/speech` — ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + provedores existentes -- **Moderações** — `/v1/moderations` — Verificações de segurança de conteúdo -- **Reclassificação** — `/v1/rerank` — Reclassificação da relevância do documento -- **API de respostas** — Suporte completo a `/v1/responses` para Codex - -
- -
-🧪 14. "Não tenho como testar e comparar a qualidade entre modelos" - -Os desenvolvedores querem saber qual modelo é melhor para seu caso de uso – código, tradução, raciocínio – mas comparar manualmente é lento. Não existem ferramentas de avaliação integradas. - -**Como o OmniRoute resolve isso:** - -- **Avaliações LLM** — Teste Golden Set com 10 casos pré-carregados cobrindo saudações, matemática, geografia, geração de código, conformidade com JSON, tradução, remarcação, recusa de segurança -- **4 estratégias de correspondência** — `exact`, `contains`, `regex`, `custom` (função JS) -- **Translator Playground Test Bench** — Teste em lote com múltiplas entradas e saídas esperadas, comparação entre fornecedores -- **Testador de bate-papo** — Ida e volta completa com renderização de resposta visual -- **Monitoramento ao vivo** — Transmissão em tempo real de todas as solicitações que passam pelo proxy - -
- -
-📈 15. "Preciso escalar sem perder desempenho" - -À medida que o volume de solicitações aumenta, sem armazenar em cache as mesmas perguntas geram custos duplicados. Sem idempotência, solicitações duplicadas desperdiçam processamento. Os limites de tarifas por provedor devem ser respeitados. - -**Como o OmniRoute resolve isso:** - -- **Cache Semântico** — Cache de duas camadas (assinatura + semântica) reduz custo e latência -- **Idempotência de solicitação** — janela de desduplicação de 5s para solicitações idênticas -- **Detecção de limite de taxa** — RPM por provedor, intervalo mínimo e rastreamento simultâneo máximo -- **Limites de taxa editáveis** — Padrões configuráveis em Configurações → Resiliência com persistência -- **Cache de validação de chave de API** — cache de três camadas para desempenho de produção -- **Health Dashboard com telemetria** — latência p50/p95/p99, estatísticas de cache, tempo de atividade - -
- -
-🤖 16. "Quero controlar o comportamento do modelo globalmente" - -Desenvolvedores que desejam todas as respostas em um idioma específico, com um tom específico ou que desejam limitar os tokens de raciocínio. Configurar isso em cada ferramenta/solicitação é impraticável. - -**Como o OmniRoute resolve isso:** - -- **Injeção de Prompt do Sistema** — Prompt global aplicado a todas as solicitações -- **Thinking Budget Validation** — Controle de alocação de token de raciocínio por solicitação (passthrough, automático, personalizado, adaptativo) -- **6 Estratégias de Roteamento** — Estratégias globais que determinam como as solicitações são distribuídas -- **Wildcard Router** — `provider/*` padrões roteiam dinamicamente para qualquer provedor -- **Combo Habilitar/Desabilitar Alternar** — Alternar combos diretamente do painel -- **Alternância de provedor** — Habilite/desabilite todas as conexões de um provedor com um clique -- **Provedores bloqueados** — Excluir provedores específicos da listagem `/v1/models` - -
- -
-🧰 17. "Preciso de ferramentas MCP como recursos de produto de primeira classe" - -Muitos gateways de IA expõem o MCP apenas como um detalhe de implementação oculto. As equipes precisam de uma camada operacional visível e gerenciável. - -**Como o OmniRoute resolve isso:** - -- MCP aparece na navegação do painel e na guia protocolo de endpoint -- Página dedicada de gerenciamento de MCP com processos, ferramentas, escopos e auditoria -- Início rápido integrado para `omniroute --mcp` e integração de cliente - -
- -
-🧠 18. "Preciso de orquestração A2A com caminhos de tarefa de sincronização + fluxo" - -Os fluxos de trabalho do agente precisam de respostas diretas e execução em streaming de longa duração com controle do ciclo de vida. - -**Como o OmniRoute resolve isso:** - -- Endpoint A2A JSON-RPC (`POST /a2a`) com `message/send` e `message/stream` -- Streaming SSE com propagação de estado terminal -- APIs de ciclo de vida de tarefas para `tasks/get` e `tasks/cancel` - -
- -
-🛰️ 19. "Preciso de integridade real do processo MCP, não de status adivinhado" - -As equipes operacionais precisam saber se o MCP está realmente ativo, e não apenas se uma API está acessível. - -**Como o OmniRoute resolve isso:** - -- Arquivo de pulsação em tempo de execução com PID, carimbos de data/hora, transporte, contagem de ferramentas e modo de escopo -- API de status MCP combinando pulsação + atividade recente -- Cartões de status da interface do usuário para atualização de processo/tempo de atividade/pulsação - -
- -
-📋 20. "Preciso de execução auditável da ferramenta MCP" - -Quando as ferramentas alteram a configuração ou acionam ações operacionais, as equipes precisam de rastreabilidade forense. - -**Como o OmniRoute resolve isso:** - -- Registro de auditoria apoiado por SQLite para chamadas de ferramentas MCP -- Filtros por ferramenta, sucesso/falha, chave de API e paginação -- Tabela de auditoria do painel + endpoints de estatísticas para automação - -
- -
-🔐 21. "Preciso de permissões MCP com escopo definido por integração" - -Clientes diferentes devem ter acesso com privilégios mínimos às categorias de ferramentas. - -**Como o OmniRoute resolve isso:** - -- 9 escopos MCP granulares para acesso controlado à ferramenta -- Aplicação do escopo e visibilidade na UI de gerenciamento do MCP -- Postura padrão segura para ferramentas operacionais - -
- -
-⚙️ 22. "Preciso de controles operacionais sem reimplantar" - -As equipes precisam de mudanças rápidas no tempo de execução durante incidentes ou eventos de custo. - -**Como o OmniRoute resolve isso:** - -- Alternar ativação combinada diretamente do painel MCP -- Aplicar perfis de resiliência de pacotes de políticas predefinidos -- Redefinir o estado do disjuntor no mesmo painel de operações - -
- -
-🔄 23. "Preciso de visibilidade e cancelamento do ciclo de vida da tarefa A2A ao vivo" - -Sem visibilidade do ciclo de vida, os incidentes de tarefas tornam-se difíceis de triagem. - -**Como o OmniRoute resolve isso:** - -- Listagem/filtragem de tarefas por estado/habilidade com paginação -- Detalhamento de metadados de tarefas, eventos e artefatos -- Terminal de cancelamento de tarefa e ação de UI com confirmação - -
- -
-🌊 24. "Preciso de métricas de fluxo ativo para carga A2A" - -Os fluxos de trabalho de streaming exigem insights operacionais sobre simultaneidade e conexões em tempo real. - -**Como o OmniRoute resolve isso:** - -- Contadores de fluxo ativos integrados ao status A2A -- Carimbo de data/hora da última tarefa e contagens por estado -- Cartões de painel A2A para monitoramento de operações em tempo real - -
- -
-🪪 25. "Preciso de descoberta de agente padrão para clientes" - -Clientes e orquestradores externos precisam de metadados legíveis por máquina para integração. - -**Como o OmniRoute resolve isso:** - -- Cartão do Agente exposto em `/.well-known/agent.json` -- Capacidades e habilidades mostradas na UI de gerenciamento -- A API de status A2A inclui metadados de descoberta para automação - -
- -
-🧭 26. "Preciso de descoberta de protocolo na UX do produto" - -Se os usuários não conseguirem descobrir superfícies de protocolo, a adoção e a qualidade do suporte cairão. - -**Como o OmniRoute resolve isso:** - -- Página **Endpoints** consolidada com guias para Proxy, MCP, A2A e API Endpoints -- Alterna o status do serviço inline (Online/Offline) para MCP e A2A -- Links da visão geral para guias de gerenciamento dedicadas - -
- -
-🧪 27. "Preciso de validação de protocolo ponta a ponta com clientes reais" - -Os testes simulados não são suficientes para validar a compatibilidade do protocolo antes do lançamento. - -**Como o OmniRoute resolve isso:** - -- Suíte E2E que inicializa o aplicativo e usa transporte de cliente SDK MCP real -- Testes de cliente A2A para fluxos de descoberta, envio, streaming, obtenção e cancelamento -- Verificação cruzada de afirmações com APIs de auditoria MCP e tarefas A2A - -
- -
-📡 28. "Preciso de observabilidade unificada em todas as interfaces" - -A divisão da observabilidade por protocolo cria pontos cegos e MTTR mais longo. - -**Como o OmniRoute resolve isso:** - -- Painéis/logs/análises unificados em um produto -- Saúde + auditoria + solicitação de telemetria nas camadas OpenAI, MCP e A2A -- APIs operacionais para status e automação - -
- -
-💼 29. "Preciso de um tempo de execução para proxy + ferramentas + orquestração de agente" - -A execução de muitos serviços separados aumenta o custo operacional e os modos de falha. - -**Como o OmniRoute resolve isso:** - -- Proxy compatível com OpenAI, servidor MCP e servidor A2A em uma pilha -- Autenticação compartilhada, resiliência, armazenamento de dados e observabilidade -- Modelo de política consistente em todas as superfícies de interação - -
- -
-🚀 30. "Preciso enviar fluxos de trabalho de agente sem expansão de código cola" - -As equipes perdem velocidade ao unir vários serviços e scripts ad-hoc. - -**Como o OmniRoute resolve isso:** - -- Estratégia unificada de endpoint para clientes e agentes -- UIs de gerenciamento de protocolo integradas e caminhos de validação de fumaça -- Fundações prontas para produção (segurança, registro, resiliência, backup) - -
- -### Exemplos de manuais (casos de uso integrados) - -**Manual A: Maximize a assinatura paga + backup barato** - -```txt -Combo: "maximize-claude" - 1. cc/claude-opus-4-6 - 2. glm/glm-4.7 - 3. if/kimi-k2-thinking - -Monthly cost: $20 + small backup spend -Outcome: higher quality, near-zero interruption -``` - -**Manual B: Pilha de codificação de custo zero** - -```txt -Combo: "free-forever" - 1. gc/gemini-3-flash - 2. if/kimi-k2-thinking - 3. qw/qwen3-coder-plus - -Monthly cost: $0 -Outcome: stable free coding workflow -``` - -**Manual C: cadeia de fallback sempre ativa 24 horas por dia, 7 dias por semana** - -```txt -Combo: "always-on" - 1. cc/claude-opus-4-6 - 2. cx/gpt-5.2-codex - 3. glm/glm-4.7 - 4. minimax/MiniMax-M2.1 - 5. if/kimi-k2-thinking - -Outcome: deep fallback depth for deadline-critical workloads -``` - -**Manual D: Operações de agente com MCP + A2A** - -```txt -1) Start MCP transport (`omniroute --mcp`) for tool-driven operations -2) Run A2A tasks via `message/send` and `message/stream` -3) Observe via /dashboard/endpoint (MCP and A2A tabs) -4) Toggle services via inline status controls -``` - ---- - -## 🆓 Comece de Graça — Custo Zero de Configuração - -> Configure a codificação de IA em minutos por **$0/mês**. Conecte essas contas gratuitas e use o combo **Free Stack** integrado. - -| Etapa | Ação | Provedores desbloqueados | -| ----- | -------------------------------------------------- | ------------------------------------------------------------------ | -| 1 | Conectar **Kiro** (ID do AWS Builder OAuth) | Claude Soneto 4.5, Haiku 4.5 — **ilimitado** | -| 2 | Conecte **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... — **ilimitado** | -| 3 | Conecte **Qwen** (código do dispositivo) | qwen3-coder-plus, qwen3-coder-flash... — **ilimitado** | -| 4 | Conecte **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro — **180K/mês grátis** | -| 5 | `/dashboard/combos` → **Pilha grátis ($0)** modelo | Round-robin todos os provedores gratuitos automaticamente | - -**Aponte qualquer IDE/CLI para:** `http://localhost:20128/v1` · Chave API: `any-string` · Concluído. - -> **Cobertura extra opcional (também gratuita):** Chave de API Groq (30 RPM grátis), NVIDIA NIM (40 RPM grátis, modelos com mais de 70), Cerebras (1 milhão de tok/dia), chave de API LongCat (50 milhões de tokens/dia!), Cloudflare Workers AI (10 mil neurônios/dia, mais de 50 modelos). - -## ⚡ Início rápido - -### 1) Instale e execute - -```bash -npm install -g omniroute -omniroute -``` - -> **usuários pnpm:** Execute `pnpm approve-builds -g` após a instalação para ativar scripts de construção nativos exigidos por `better-sqlite3` e `@swc/core`: -> -> ```bash -> pnpm install -g omniroute -> pnpm approve-builds -g # Select all packages → approve -> omniroute -> ``` - -O painel abre em `http://localhost:20128` e o URL base da API é `http://localhost:20128/v1`. - -| Comando | Descrição | -| ----------------------- | --------------------------------------------------------------- | -| `omniroute` | Iniciar servidor (`PORT=20128`, API e dashboard na mesma porta) | -| `omniroute --port 3000` | Defina a porta canônica/API como 3000 | -| `omniroute --mcp` | Inicie o servidor MCP (transporte stdio) | -| `omniroute --no-open` | Não abra o navegador automaticamente | -| `omniroute --help` | Mostrar ajuda | - -Modo de porta dividida opcional: - -```bash -PORT=20128 DASHBOARD_PORT=20129 omniroute -# API: http://localhost:20128/v1 -# Dashboard: http://localhost:20129 -``` - -### 2) Conecte provedores e crie sua chave API - -1. Abra Dashboard → `Providers` e conecte pelo menos um provedor (OAuth ou chave API). -2. Abra Dashboard → `Endpoints` e crie uma chave API. -3. (Opcional) Abra Dashboard → `Combos` e defina sua cadeia de fallback. - -### 3) Aponte sua ferramenta de codificação para OmniRoute - -```txt -Base URL: http://localhost:20128/v1 -API Key: [copy from Endpoint page] -Model: if/kimi-k2-thinking (or any provider/model prefix) -``` - -Funciona com Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode e SDKs compatíveis com OpenAI. - -### 4) Habilitar e validar protocolos (v2.0) - -**MCP (para operações orientadas por ferramentas):** - -```bash -omniroute --mcp -``` - -Em seguida, conecte seu cliente MCP em `stdio` e teste ferramentas como: - -- `omniroute_get_health` -- `omniroute_list_combos` - -**A2A (para fluxos de trabalho entre agentes):** - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -```bash -curl -X POST http://localhost:20128/a2a \ - -H 'content-type: application/json' \ - -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}' -``` - -### 5) Valide tudo de ponta a ponta (recomendado) - -```bash -npm run test:protocols:e2e -``` - -Este conjunto valida fluxos reais de clientes MCP e A2A em um aplicativo em execução. - -### Alternativa: executar a partir da fonte - -```bash -cp .env.example .env -npm install -PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev -``` - ---- - -## 🐳 Docker - -OmniRoute está disponível como uma imagem pública do Docker em [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute). - -**Execução rápida:** - -```bash -docker run -d \ - --name omniroute \ - --restart unless-stopped \ - -p 20128:20128 \ - -v omniroute-data:/app/data \ - diegosouzapw/omniroute:latest -``` - -**Com arquivo de ambiente:** - -```bash -# Copy and edit .env first -cp .env.example .env - -docker run -d \ - --name omniroute \ - --restart unless-stopped \ - --env-file .env \ - -p 20128:20128 \ - -v omniroute-data:/app/data \ - diegosouzapw/omniroute:latest -``` - -**Usando Docker Compose:** - -```bash -# Base profile (no CLI tools) -docker compose --profile base up -d - -# CLI profile (Claude Code, Codex, OpenClaw built-in) -docker compose --profile cli up -d -``` - -| Imagem | Etiqueta | Tamanho | Descrição | -| ------------------------ | -------- | ------- | --------------------- | -| `diegosouzapw/omniroute` | `latest` | ~250 MB | Última versão estável | -| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Versão atual | - ---- - -## 🖥️ Aplicativo de desktop – off-line e sempre ativo - -> 🆕 **NOVO!** OmniRoute agora está disponível como um **aplicativo de desktop nativo** para Windows, macOS e Linux. - -Execute o OmniRoute como um aplicativo de desktop independente — sem terminal, sem navegador, sem necessidade de internet para modelos locais. O aplicativo baseado em Electron inclui: - -- 🖥️ **Janela Nativa** — Janela de aplicativo dedicada com integração na bandeja do sistema -- 🔄 **Início automático** — Inicie o OmniRoute no login do sistema -- 🔔 **Notificações nativas** — Receba alertas sobre esgotamento de cota ou problemas com o provedor -- ⚡ **Instalação com um clique** — NSIS (Windows), DMG (macOS), AppImage (Linux) -- 🌐 **Modo offline** — Funciona totalmente offline com servidor incluído - -### Início rápido - -```bash -# Development mode -npm run electron:dev - -# Build for your platform -npm run electron:build # Current platform -npm run electron:build:win # Windows (.exe) -npm run electron:build:mac # macOS (.dmg) — x64 & arm64 -npm run electron:build:linux # Linux (.AppImage) -``` - -### Bandeja do sistema - -Quando minimizado, o OmniRoute fica na bandeja do sistema com ações rápidas: - -- Abra o painel -- Alterar porta do servidor -- Sair do aplicativo - -📖 Documentação completa: [**OMNI_TOKEN_153**](electron/README.md) - ---- - -## 💰 Visão geral dos preços - -| Nível | Provedor | Custo | Redefinição de cota | Melhor para | -| ------------------- | ------------------------------------- | -------------------------------------- | ------------------------ | ----------------------------------------------- | -| **💳 ASSINATURA** | Código Claude (Pro) | $ 20/mês | 5h + semanalmente | Já inscrito | -| | Códice (Plus/Pro) | US$ 20-200/mês | 5h + semanalmente | Usuários OpenAI | -| | Gêmeos CLI | **GRÁTIS** | 180 mil/mês + 1 mil/dia | Todos! | -| | Copiloto GitHub | US$ 10-19/mês | Mensalmente | Usuários do GitHub | -| **🔑 CHAVE DE API** | NVIDIA NIM | **GRÁTIS** (desenvolvedor para sempre) | ~40RPM | Mais de 70 modelos abertos | -| | Cérebros | **GRÁTIS** (1 milhão de tok/dia) | 60KTPM/30RPM | O mais rápido do mundo | -| | Groq | **GRÁTIS** (30 RPM) | RPD de 14,4K | Lhama/Gemma ultrarrápida | -| | DeepSeek V3.2 | US$ 0,27/US$ 1,10 por 1 milhão | Nenhum | Melhor raciocínio preço/qualidade | -| | xAI Grok-4 Rápido | **$0,20/$0,50 por 1 milhão** 🆕 | Nenhum | Chamada de ferramenta mais rápida +, ultrabaixa | -| | xAI Grok-4 (padrão) | US$ 0,20/US$ 1,50 por 1 milhão 🆕 | Nenhum | Carro-chefe do raciocínio da xAI | -| | Mistral | Teste grátis + pago | Taxa limitada | IA Europeia | -| | OpenRouter | Pagamento conforme uso | Nenhum | Mais de 100 modelos no total. | -| **💰 BARATO** | GLM-5 (via Z.AI) 🆕 | US$ 0,5/1 milhão | Diariamente 10h | Saída de 128K, o mais novo carro-chefe | -| | GLM-4.7 | US$ 0,6/1 milhão | Diariamente 10h | Backup de orçamento | -| | MiniMax M2.5 🆕 | Entrada de US$ 0,3/1 milhão | Rolamento de 5 horas | Raciocínio + tarefas de agência | -| | MiniMax M2.1 | US$ 0,2/1 milhão | Rolamento de 5 horas | Opção mais barata | -| | Kimi K2.5 (API Moonshot) 🆕 | Pagamento conforme uso | Nenhum | Acesso direto à API Moonshot | -| | Kimi K2 | $ 9 / mês fixo | 10 milhões de tokens/mês | Custo previsível | -| **🆓 GRÁTIS** | Qoder | **$0** | Ilimitado | 5 modelos ilimitados | -| | Qwen | **$0** | Ilimitado | 4 modelos ilimitados | -| | Kiro | **$0** | Ilimitado | Claude Sonnet/Haiku (Construtor AWS) | -| | LongCat Flash Lite 🆕 | **$0** (50 milhões de dólares/dia 🔥) | 1RPS | Maior cota gratuita do planeta | -| | Polinizações AI 🆕 | **$0** (sem necessidade de chave) | 1 necessidade/15s | GPT-5, Claude, DeepSeek, Lhama 4 | -| | IA dos trabalhadores da Cloudflare 🆕 | **$0** (10 mil neurônios/dia) | ~150 resp/dia | Mais de 50 modelos, vantagem global | -| | IA Scaleway 🆕 | **$0** (total de 1 milhão de tokens) | Taxa limitada | UE/GDPR, Qwen3 235B, Llama 70B | - -> 🆕 **Novos modelos adicionados (março de 2026):** Família Grok-4 Fast a US$ 0,20/US$ 0,50/M (comparado em 1143ms — 30% mais rápido que Gemini 2.5 Flash), GLM-5 via Z.AI com saída de 128K, raciocínio MiniMax M2.5, preço atualizado DeepSeek V3.2, Kimi K2.5 via API direta Moonshot. - -**💡 Pilha Combo de $0 — A configuração gratuita completa:** - -``` -# 🆓 Ultimate Free Stack 2026 — 11 Providers, $0 Forever -Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED -Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED -LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥 -Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed -Qwen (qw/) → qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED -Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free API key -Cloudflare AI (cf/) → Llama 70B, Gemma 3, Mistral — 10K Neurons/day -Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU) -Groq (groq/) → Llama/Gemma ultra-fast — 14.4K req/day -NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever -Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day -``` - -**Custo zero. Nunca para de codificar.** Configure isso como um combo OmniRoute e todos os fallbacks acontecem automaticamente - nunca há troca manual. - ---- - ---- - -## 🆓 Modelos gratuitos – O que você realmente obtém - -> Todos os modelos abaixo são **100% gratuitos, sem necessidade de cartão de crédito**. OmniRoute roteia automaticamente entre eles quando uma cota acaba – combine todos eles para um combo inquebrável de $ 0. - -### 🔵 MODELOS CLAUDE (via Kiro — AWS Builder ID) - -| Modelo | Prefixo | Limite | Limite de taxa | -| ------------------- | ------- | ------------- | ------------------------------- | -| `claude-sonnet-4.5` | `kr/` | **Ilimitado** | Nenhum limite diário comunicado | -| `claude-haiku-4.5` | `kr/` | **Ilimitado** | Nenhum limite diário comunicado | -| `claude-opus-4.6` | `kr/` | **Ilimitado** | Último Opus via Kiro | - -### 🟢 MODELOS QODER (OAuth grátis — sem cartão de crédito) - -| Modelo | Prefixo | Limite | Limite de taxa | -| ------------------ | ------- | ------------- | ------------------------------- | -| `kimi-k2-thinking` | `if/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `qwen3-coder-plus` | `if/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `deepseek-r1` | `if/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `minimax-m2.1` | `if/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `kimi-k2` | `if/` | **Ilimitado** | Nenhum limite máximo comunicado | - -### 🟡 MODELOS QWEN (autenticação do código do dispositivo) - -| Modelo | Prefixo | Limite | Limite de taxa | -| ------------------- | ------- | ------------- | ------------------------------- | -| `qwen3-coder-plus` | `qw/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `qwen3-coder-flash` | `qw/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `qwen3-coder-next` | `qw/` | **Ilimitado** | Nenhum limite máximo comunicado | -| `vision-model` | `qw/` | **Ilimitado** | Multimodal (imagens) | - -### 🟣 CLI GEMINI (Google OAuth) - -| Modelo | Prefixo | Limite | Limite de taxa | -| ------------------------ | ------- | -------------------------------- | ------------------ | -| `gemini-3-flash-preview` | `gc/` | **180 mil tok/mês** + 1 mil/dia | Redefinição mensal | -| `gemini-2.5-pro` | `gc/` | 180 mil/mês (pool compartilhado) | Alta qualidade | - -### ⚫ NVIDIA NIM (chave de API gratuita — build.nvidia.com) - -| Nível | Limite Diário | Limite de taxa | Notas | -| ---------------------- | ------------------- | -------------- | --------------------------------------------------------------------------- | -| Grátis (Desenvolvedor) | Sem limite de token | **~40RPM** | Mais de 70 modelos; transição para limites de taxas puras em meados de 2025 | - -Modelos gratuitos populares: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1` - -### ⚪ CEREBRAS (chave de API gratuita — inference.cerebras.ai) - -| Nível | Limite Diário | Limite de taxa | Notas | -| ------ | -------------------------- | -------------- | ----------------------------------------------------------- | -| Grátis | **1 milhão de tokens/dia** | 60KTPM/30RPM | A inferência LLM mais rápida do mundo; reinicia diariamente | - -Disponível gratuitamente: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b` - -### 🔴 GROQ (chave de API gratuita — console.groq.com) - -| Nível | Limite Diário | Limite de taxa | Notas | -| ------ | ---------------- | ----------------- | -------------------------------------------------- | -| Grátis | **RPD de 14,4K** | 30 RPM por modelo | Sem cartão de crédito; 429 no limite, sem cobrança | - -Disponível gratuitamente: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3` - -### 🔴 LONGCAT AI (chave de API gratuita — longcat.chat) 🆕 - -| Modelo | Prefixo | Cota diária gratuita | Notas | -| ----------------------------- | ------- | --------------------------- | -------------------------------------- | -| `LongCat-Flash-Lite` | `lc/` | **50 milhões de tokens** 💥 | Maior cota gratuita de todos os tempos | -| `LongCat-Flash-Chat` | `lc/` | 500 mil tokens | Bate-papo multiturno | -| `LongCat-Flash-Thinking` | `lc/` | 500 mil tokens | Raciocínio / CoT | -| `LongCat-Flash-Thinking-2601` | `lc/` | 500 mil tokens | Versão de janeiro de 2026 | -| `LongCat-Flash-Omni-2603` | `lc/` | 500 mil tokens | Multimodal | - -> 100% gratuito durante a versão beta pública. Inscreva-se em [longcat.chat](https://longcat.chat) com e-mail ou telefone. Reinicia diariamente às 00:00 UTC. - -### 🟢 POLINIZAÇÕES AI (nenhuma chave de API necessária) 🆕 - -| Modelo | Prefixo | Limite de taxa | Provedor por trás | -| ---------- | ------- | ----------------- | -------------------- | -| `openai` | `pol/` | 1 necessidade/15s | GPT-5 | -| `claude` | `pol/` | 1 necessidade/15s | Claude Antrópico | -| `gemini` | `pol/` | 1 necessidade/15s | Google Gêmeos | -| `deepseek` | `pol/` | 1 necessidade/15s | DeepSeek V3 | -| `llama` | `pol/` | 1 necessidade/15s | Batedor Meta Lhama 4 | -| `mistral` | `pol/` | 1 necessidade/15s | IA Mistral | - -> ✨ **Atrito zero:** Sem inscrição, sem chave de API. Adicione o provedor Polinizações com um campo-chave vazio e ele funcionará imediatamente. - -### 🟠 CLOUDFLARE WORKERS AI (chave de API gratuita — cloudflare.com) 🆕 - -| Nível | Neurônios Diários | Uso equivalente | Notas | -| ------ | ----------------- | ------------------------------------------------- | ----------------------------------- | -| Grátis | **10.000** | ~150 LLM resp / áudio 500s / incorporações de 15K | Vantagem global, mais de 50 modelos | - -Modelos gratuitos populares: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (áudio grátis!), `@cf/qwen/qwen2.5-coder-15b-instruct` - -> Requer token de API + ID da conta de [dash.cloudflare.com](https://dash.cloudflare.com). Armazene o ID da conta nas configurações do provedor. - -### 🟣 SCALEWAY AI (1 milhão de tokens grátis — scaleway.com) 🆕 - -| Nível | Cota Grátis | Localização | Notas | -| ------ | ---------------------- | ------------ | ----------------------------------------------------- | -| Grátis | **1 milhão de tokens** | 🇫🇷 Paris, UE | Não é necessário cartão de crédito dentro dos limites | - -Disponível gratuitamente: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324` - -> Compatível com UE/GDPR. Obtenha a chave API em [console.scaleway.com](https://console.scaleway.com). - -> **💡 The Ultimate Free Stack (11 provedores, $ 0 para sempre): ** -> -> ``` -> Kiro (kr/) → Claude Sonnet/Haiku UNLIMITED -> Qoder (if/) → kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED -> LongCat Lite (lc/) → LongCat-Flash-Lite — 50M tokens/day 🔥 -> Pollinations (pol/) → GPT-5, Claude, DeepSeek, Llama 4 — no key needed -> Qwen (qw/) → qwen3-coder models UNLIMITED -> Gemini (gemini/) → Gemini 2.5 Flash — 1,500 req/day free -> Cloudflare AI (cf/) → 50+ models — 10K Neurons/day -> Scaleway (scw/) → Qwen3 235B, Llama 70B — 1M free tokens (EU) -> Groq (groq/) → Llama/Gemma — 14.4K req/day ultra-fast -> NVIDIA NIM (nvidia/) → 70+ open models — 40 RPM forever -> Cerebras (cerebras/) → Llama/Qwen world-fastest — 1M tok/day -> ``` - -## 🎙️ Combo de transcrição grátis - -> Transcreva qualquer áudio/vídeo por **$0** — Deepgram lidera com $200 grátis, AssemblyAI $50 substituto, Groq Whisper como backup de emergência ilimitado. - -| Provedor | Créditos Grátis | Melhor Modelo | Limite de taxa | -| ----------------- | --------------------------- | ---------------------------------------------- | --------------------------------------- | -| 🟢 **Deepgram** | **$200 grátis** (inscrição) | `nova-3` — melhor precisão, mais de 30 idiomas | Sem limite de RPM em créditos gratuitos | -| 🔵 **AssemblyAI** | **$50 grátis** (inscrição) | `universal-3-pro` — capítulos, sentimento, PII | Sem limite de RPM em créditos gratuitos | -| 🔴 **Groque** | **Grátis para sempre** | `whisper-large-v3` — Sussurro OpenAI | 30 RPM (taxa limitada) | - -**Combo sugerido em `/dashboard/combos`:** - -``` -Name: free-transcription -Strategy: Priority -Nodes: - [1] deepgram/nova-3 → uses $200 free first - [2] assemblyai/universal-3-pro → fallback when Deepgram credits run out - [3] groq/whisper-large-v3 → free forever, emergency fallback -``` - -Em seguida, em `/dashboard/media` → guia **Transcrição**: carregue qualquer arquivo de áudio ou vídeo → selecione seu endpoint de combinação → obtenha a transcrição em formatos suportados. - -## 💡 Principais recursos - -OmniRoute v2.0 é construído como uma plataforma operacional, não apenas um proxy de retransmissão. - -### 🆕 Novo — Melhorias inspiradas no ClawRouter (março de 2026) - -| Recurso | O que faz | -| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| ⚡ **Grok-4 Família Rápida** | Modelos xAI por US$ 0,20/US$ 0,50/M – benchmark de 1143 ms (30% mais rápido que Gemini 2.5 Flash) | -| 🧠 **GLM-5 via Z.AI** | Contexto de saída de 128K, US$ 0,5/1 milhão – o mais novo carro-chefe da família GLM | -| 🔮 **MiniMax M2.5** | Raciocínio + tarefas de agência por US$ 0,30/1 milhão — atualização significativa do M2.1 | -| 🎯 **toolCalling Flag por modelo** | Por modelo `toolCalling: true/false` no registro - AutoCombo ignora modelos sem capacidade de ferramenta | -| 🌍 **Detecção de intenção multilíngue** | Palavras-chave PT/ZH/ES/AR na pontuação AutoCombo — melhor seleção de modelos para conteúdo diferente do inglês | -| 📊 **Recursos baseados em benchmarks** | Latência p95 real de solicitações ao vivo alimenta pontuação combinada – AutoCombo aprende com dados reais | -| 🔁 **Solicitar desduplicação** | Janela de desduplicação baseada em hash de conteúdo — segura para vários agentes, evita cobranças duplicadas | -| 🔌 **Estratégia de roteador conectável** | Interface `RouterStrategy` extensível — adicione lógica de roteamento personalizada como plug-ins | - -### 🚀 Anterior v2.0.9+ — Playground, impressões digitais CLI e ACP - -| Recurso | O que faz | -| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🎮 **Parque Modelo** | Página do painel para testar qualquer modelo diretamente - seletores de provedor/modelo/endpoint, Monaco Editor, streaming, aborto, tempo | -| 🔏 **Correspondência de impressão digital CLI** | Ordenação de cabeçalho/corpo por provedor para corresponder às assinaturas CLI nativas — alterne por provedor em Configurações > Segurança. **Seu IP proxy é preservado** | -| 🤝 **Suporte ACP (Protocolo Agente Cliente)** | Descoberta de agente CLI (Codex, Claude, Goose, Gemini CLI, OpenClaw + mais 9), gerador de processo, endpoint `/api/acp/agents` | -| 🤖 **Painel de Agentes ACP** | Depurar › Página Agentes — grade de 14 agentes com status de instalação, versão, formulário de agente personalizado para qualquer ferramenta CLI. Os usuários do **OpenCode** recebem um botão "Baixar opencode.json" que gera automaticamente uma configuração pronta para uso com todos os modelos disponíveis. | -| 🔧 **Roteamento de modelo personalizado `apiFormat`** | Modelos personalizados com `apiFormat: "responses"` agora roteiam corretamente para o tradutor da API de respostas | -| 🏢 **Isolamento do espaço de trabalho do Codex** | Vários espaços de trabalho do Codex por e-mail — OAuth separa corretamente as conexões por ID do espaço de trabalho | -| 🔄 **Atualização automática eletrônica** | O aplicativo de desktop verifica atualizações + instalação automática ao reiniciar | - -### 🤖 Operações de agente e protocolo (v2.0) - -| Recurso | O que faz | -| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | -| 🔧 **Servidor MCP (16 ferramentas)** | Ferramentas IDE/agente por meio de 3 transportes: stdio, SSE (`/api/mcp/sse`), HTTP Streamable (`/api/mcp/stream`) | -| 🤝 **Servidor A2A (JSON-RPC + SSE)** | Execução de tarefas entre agentes com fluxos de sincronização e streaming | -| 🧭 **Página de endpoints consolidados** | Página de gerenciamento com guias com guias Endpoint Proxy, MCP, A2A e API Endpoints | -| 🎚️ **Alternativas de ativação/desativação de serviço** | Chaves ON/OFF para MCP e A2A com persistência de configurações (padrão: OFF) | -| 🛰️ **Pulsação de tempo de execução do MCP** | Status real do processo (pid, tempo de atividade, idade da pulsação, transporte, modo de escopo) | -| 📋 **Trilha de auditoria MCP** | Logs de auditoria filtráveis ​​com sucesso/falha e atribuição de chave | -| 🔐 **Aplicação do escopo do MCP** | 9 permissões de escopo granular para acesso controlado a ferramentas | -| 📡 **Gerenciamento do ciclo de vida de tarefas A2A** | Listar/filtrar tarefas, inspecionar eventos/artefatos, cancelar tarefas em execução | -| 📋 **Descoberta de cartão de agente** | `/.well-known/agent.json` para descoberta automática de cliente | -| 🧪 **Arnês de teste do protocolo E2E** | Fluxos reais de cliente MCP SDK + A2A em `test:protocols:e2e` | -| ⚙️ **Controles operacionais** | Combinação de interruptores, aplicação de perfis de resiliência, reinicialização de disjuntores a partir de uma superfície de controle | - -### 🧠 Roteamento e Inteligência - -| Recurso | O que faz | -| ----------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| 🎯 **Fullback inteligente de 4 camadas** | Roteamento automático: Assinatura → Chave de API → Barato → Grátis | -| 📊 **Acompanhamento de cotas em tempo real** | Contagem de tokens ativos + contagem regressiva redefinida por provedor | -| 🔄 **Tradução de formato** | OpenAI ↔ Claude ↔ Gemini ↔ Respostas com conversões seguras de esquema | -| 👥 **Suporte para múltiplas contas** | Múltiplas contas por provedor com seleção inteligente | -| 🔄 **Atualização automática de token** | Os tokens OAuth são atualizados automaticamente com nova tentativa | -| 🎨 **Combos Personalizados** | 6 estratégias de balanceamento + controle da cadeia de fallback | -| 🌐 **Roteador curinga** | `provider/*` roteamento dinâmico | -| 🧠 **Pensando em controles de orçamento** | Limites de raciocínio de passagem, automático, personalizado e adaptativo | -| 🔀 **Alases de modelo** | Aliasing de modelo integrado + personalizado e segurança de migração | -| ⚡ **Degradação de fundo** | Encaminhar tarefas em segundo plano de baixa prioridade para modelos mais baratos | -| 🧪 **Roteamento inteligente com reconhecimento de tarefas** | Seleção automática de modelo por tipo de conteúdo (codificação/visão/análise/resumo) | -| 💬 **Injeção imediata do sistema** | Controles de comportamento globais aplicados de forma consistente | -| 📄 **Compatibilidade da API de respostas** | Suporte completo `/v1/responses` para Codex e fluxos de trabalho de agência avançados | - -### 🎵 APIs multimodais - -| Recurso | O que faz | -| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 🖼️ **Geração de imagens** | `/v1/images/generations` com nuvem e back-ends locais | -| 📐 **Incorporações** | `/v1/embeddings` para pipelines de pesquisa e RAG | -| 🎤 **Transcrição de áudio** | `/v1/audio/transcriptions` — 7 provedores (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), detecção automática de idioma, suporte a MP4/MP3/WAV | -| 🔊 **Conversão de texto em fala** | `/v1/audio/speech` — 10 provedores (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) com mensagens de erro corretas | -| 🎬 **Geração de Vídeo** | `/v1/videos/generations` (fluxos de trabalho ComfyUI + SD WebUI) | -| 🎵 **Geração Musical** | `/v1/music/generations` (fluxos de trabalho ComfyUI) | -| 🛡️ **Moderações** | `/v1/moderations` verificações de segurança | -| 🔀 **Reclassificação** | `/v1/rerank` para pontuação de relevância | -| 🔍 **Pesquisa na Web** 🆕 | `/v1/search` — 5 provedores (Serper, Brave, Perplexity, Exa, Tavily), mais de 6.500 grátis/mês, failover automático, cache | - -### 🛡️ Resiliência, Segurança e Governança - -| Recurso | O que faz | -| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| 🔌 **Disjuntores** | Acionamento/recuperação por modelo com controles de limite | -| 🎯 **Modelos com reconhecimento de endpoint** | Modelos personalizados declaram endpoints suportados + formato API | -| 🛡️ **Rebanho Anti-Trovão** | Proteções Mutex + semáforo em eventos de nova tentativa/taxa | -| 🧠 **Semântica + Cache de Assinatura** | Redução de custo/latência com duas camadas de cache | -| ⚡ **Solicitar Idempotência** | Janela de proteção duplicada | -| 🔒 **Falsificação de impressão digital TLS** | Impressão digital TLS semelhante a navegador — **reduz a detecção de bots e a sinalização de contas** | -| 🔏 **Correspondência de impressão digital CLI** | Corresponde às assinaturas de solicitação CLI nativas — **reduz o risco de banimento enquanto preserva o IP do proxy** | -| 🌐 **Filtragem de IP** | Controle de lista de permissões/lista de bloqueio para implantações expostas | -| 📊 **Limites de taxas editáveis** | Limites configuráveis ​​em nível global/de provedor com persistência | -| 🔑 **Gerenciamento de chaves de API + escopo** | Emissão/rotação segura de chaves e controles de modelo/provedor | -| 🛡️ **Protegido `/models`** | Autenticação opcional e ocultação de provedor para catálogo de modelos | - -### 📊 Observabilidade e análise - -| Recurso | O que faz | -| -------------------------------------- | ---------------------------------------------------------------------------- | -| 📝 **Solicitação + Registro de Proxy** | Solicitação/resposta completa e registro de proxy | -| 📉 **Streamed Detailed Logs** 🆕 | Reconstructs SSE payload streams cleanly into the UI | -| 📋 **Painel de registros unificado** | Visualizações de solicitação, proxy, auditoria e console em uma página | -| 🔍 **Solicitar Telemetria** | Latência p50/p95/p99 e rastreamento de solicitação | -| 🏥 **Painel de saúde** | Tempo de atividade, estados de disjuntores, bloqueios, estatísticas de cache | -| 💰 **Acompanhamento de custos** | Controles de orçamento e visibilidade de preços por modelo | -| 📈 **Visualizações analíticas** | Insights de uso de modelo/provedor e visualizações de tendências | -| 🧪 **Estrutura de Avaliação** | Teste de Golden Set com estratégias de jogo configuráveis ​​ | - -### ☁️ Implantação e plataforma - -| Recurso | O que faz | -| --------------------------------------- | ------------------------------------------------------------------------------ | -| 🌐 **Implante em qualquer lugar** | Ambientes Localhost, VPS, Docker, Cloud | -| 💾 **Sincronização na nuvem** | Sincronização de configuração via Cloud Worker | -| 🔄 **Backup/Restauração** | Fluxos de exportação/importação e recuperação de desastres | -| 🧙 **Assistente de integração** | Configuração guiada na primeira execução | -| 🔧 **Painel de Ferramentas CLI** | Configuração com um clique para ferramentas de codificação populares | -| 🎮 **Parque Modelo** | Teste qualquer provedor/modelo/endpoint no painel | -| 🔏 **Alternar impressão digital CLI** | Correspondência de impressão digital por provedor em Configurações > Segurança | -| 🌐 **i18n (30 idiomas)** | Painel completo + suporte a idiomas de documentos com cobertura RTL | -| 🧹 **Limpar todos os modelos** | Limpeza da lista de modelos com um clique nos detalhes do provedor | -| 👁️ **Sidebar Controls** 🆕 | Hide components and integrations from Appearance Settings | -| 📋 **Modelos de problemas** | Modelos padronizados do GitHub para bugs e recursos | -| 📂 **Diretório de dados personalizado** | Substituição de `DATA_DIR` para local de armazenamento | - -### Aprofundamento do recurso - -#### Fallback inteligente com controle prático de custos - -```txt -Combo: "my-coding-stack" - 1. cc/claude-opus-4-6 - 2. nvidia/llama-3.3-70b - 3. glm/glm-4.7 - 4. if/kimi-k2-thinking -``` - -Quando a cota, a taxa ou a integridade falham, o OmniRoute passa automaticamente para o próximo candidato sem alternância manual. - -#### Gerenciamento de protocolo visível e operável - -- MCP + A2A podem ser descobertos na interface do usuário e nos documentos (não ocultos) -- APIs de status de protocolo expõem dados operacionais em tempo real (`/api/mcp/*`, `/api/a2a/*`) -- Os painéis incluem ações para operações do dia 2 (alternâncias de combinação, reinicializações de disjuntores, cancelamento de tarefas) - -#### Tradutor + fluxo de trabalho de validação - -A área do Tradutor inclui: - -- **Playground**: solicita verificações de transformação -- **Testador de bate-papo**: solicitação/resposta completa, ida e volta -- **Banco de testes**: vários casos em uma execução -- **Monitoramento ao vivo**: visualização do tráfego em tempo real - -Além de validação de protocolo com clientes reais via `npm run test:protocols:e2e`. - -> 📖 **[MCP Server README](open-sse/mcp-server/README.md)** — Referência de ferramentas, configurações de IDE e exemplos de clientes -> -> 📖 **[A2A Server README](src/lib/a2a/README.md)** — Habilidades, métodos JSON-RPC, streaming e ciclo de vida de tarefas - -## 🧪 Avaliações (Evals) - -OmniRoute inclui uma estrutura de avaliação integrada para testar a qualidade da resposta do LLM em relação a um conjunto dourado. Acesse-o em **Analytics → Evals** no painel. - -### Conjunto Dourado Integrado - -O "OmniRoute Golden Set" pré-carregado contém casos de teste para: - -- Saudações, matemática, geografia, geração de código -- Conformidade com o formato JSON, tradução, geração de descontos -- Recusa de segurança (conteúdo prejudicial), contagem, lógica booleana - -### Estratégias de Avaliação - -| Estratégia | Descrição | Exemplo | -| ---------- | --------------------------------------------------------------------------- | -------------------------------- | -| `exact` | A saída deve corresponder exatamente | `"4"` | -| `contains` | A saída deve conter substring (sem distinção entre maiúsculas e minúsculas) | `"Paris"` | -| `regex` | A saída deve corresponder ao padrão regex | `"1.*2.*3"` | -| `custom` | Função JS personalizada retorna verdadeiro/falso | `(output) => output.length > 10` | - ---- - -## 📖 Guia de configuração - -### Configuração do protocolo (MCP + A2A) - -
-🧩 Configuração MCP (protocolo de contexto do modelo) - -Inicie o transporte MCP no modo stdio: - -```bash -omniroute --mcp -``` - -Fluxo de validação recomendado: - -1. Conecte seu cliente MCP por stdio. -2. Execute `omniroute_get_health`. -3. Execute `omniroute_list_combos`. -4. Abra `/dashboard/mcp` para confirmar pulsação, atividade e auditoria. - -APIs úteis para automação: - -- `GET /api/mcp/status` -- `GET /api/mcp/tools` -- `GET /api/mcp/audit` -- `GET /api/mcp/audit/stats` - -
- -
-🤝 Configuração A2A (Agente2Agente) - -Conheça o agente: - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Envie uma tarefa: - -```bash -curl -X POST http://localhost:20128/a2a \ - -H 'content-type: application/json' \ - -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' -``` - -Gerenciar ciclo de vida: - -- `GET /api/a2a/status` -- `GET /api/a2a/tasks` -- `GET /api/a2a/tasks/:id` -- `POST /api/a2a/tasks/:id/cancel` - -IU operacional: - -- `/dashboard/a2a` para observabilidade de tarefa/estado/fluxo e ações de fumaça - -
- -
-🧪 Validação de protocolo ponta a ponta - -Valide ambos os protocolos com clientes reais: - -```bash -npm run test:protocols:e2e -``` - -Isso verifica: - -- Conexão/lista/chamada do cliente MCP SDK -- Descoberta A2A/enviar/transmitir/obter/cancelar -- Verificação cruzada de dados em APIs de auditoria MCP e gerenciamento de tarefas A2A - -
- -
-💳 Provedores de assinatura - -### Código Claude (Pro/Max) - -```bash -Dashboard → Providers → Connect Claude Code -→ OAuth login → Auto token refresh -→ 5-hour + weekly quota tracking - -Models: - cc/claude-opus-4-6 - cc/claude-sonnet-4-5-20250929 - cc/claude-haiku-4-5-20251001 -``` - -**Dica profissional:** Use o Opus para tarefas complexas e o Sonnet para velocidade. OmniRoute rastreia cota por modelo! - -### Codex OpenAI (Plus/Pro) - -```bash -Dashboard → Providers → Connect Codex -→ OAuth login (port 1455) -→ 5-hour + weekly reset - -Models: - cx/gpt-5.2-codex - cx/gpt-5.1-codex-max -``` - -#### Gerenciamento de limite de conta Codex (5h + semanalmente) - -Cada conta do Codex agora possui opções de política em `Dashboard -> Providers`: - -- `5h` (ON/OFF): impõe a política de limite de janela de 5 horas. -- `Weekly` (ON/OFF): impõe a política de limite de janela semanal. -- Comportamento do limite: quando uma janela habilitada atinge >=90% de uso, essa conta é ignorada. -- Comportamento de rotação: OmniRoute roteia automaticamente para a próxima conta Codex qualificada. -- Comportamento de redefinição: quando o tempo `resetAt` do provedor passar, a conta se tornará elegível novamente automaticamente. - -Cenários: - -- `5h ON` + `Weekly ON`: a conta é ignorada quando uma das janelas atinge o limite. -- `5h OFF` + `Weekly ON`: somente o uso semanal pode bloquear a conta. -- `5h ON` + `Weekly OFF`: apenas o uso de 5 horas pode bloquear a conta. -- `resetAt` aprovado: a conta entra novamente na rotação automaticamente (sem reativação manual). - -### Gemini CLI (GRÁTIS 180K/mês!) - -```bash -Dashboard → Providers → Connect Gemini CLI -→ Google OAuth -→ 180K completions/month + 1K/day - -Models: - gc/gemini-3-flash-preview - gc/gemini-2.5-pro -``` - -**Melhor valor:** Grande nível gratuito! Use isso antes dos níveis pagos. - -### GitHub Copiloto - -```bash -Dashboard → Providers → Connect GitHub -→ OAuth via GitHub -→ Monthly reset (1st of month) - -Models: - gh/gpt-5 - gh/claude-4.5-sonnet - gh/gemini-3-pro -``` - -
- -
-🔑 Provedores de chave de API - -### NVIDIA NIM (acesso GRATUITO para desenvolvedores – mais de 70 modelos) - -1. Inscreva-se: [build.nvidia.com](https://build.nvidia.com) -2. Obtenha uma chave de API gratuita (1.000 créditos de inferência incluídos) -3. Painel → Adicionar Provedor → NVIDIA NIM: - - Chave API: `nvapi-your-key` - -**Modelos:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct` e mais de 50 - -**Dica profissional:** API compatível com OpenAI — funciona perfeitamente com a tradução de formato do OmniRoute! - -### DeepSeek - -1. Inscreva-se: [platform.deepseek.com](https://platform.deepseek.com) -2. Obtenha a chave API -3. Painel → Adicionar provedor → DeepSeek - -**Modelos:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` - -### Groq (nível gratuito disponível!) - -1. Inscreva-se: [console.groq.com](https://console.groq.com) -2. Obtenha a chave API (nível gratuito incluído) -3. Painel → Adicionar Provedor → Groq - -**Modelos:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` - -**Dica profissional:** Inferência ultrarrápida — melhor para codificação em tempo real! - -### OpenRouter (mais de 100 modelos) - -1. Inscreva-se: [openrouter.ai](https://openrouter.ai) -2. Obtenha a chave API -3. Painel → Adicionar Provedor → OpenRouter - -**Modelos:** acesse mais de 100 modelos de todos os principais fornecedores por meio de uma única chave de API. - -
- -
-💰 Provedores baratos (backup) - -### GLM-4.7 (redefinição diária, US$ 0,6/1 milhão) - -1. Inscreva-se: [Zhipu AI](https://open.bigmodel.cn/) -2. Obtenha a chave API do plano de codificação -3. Painel → Adicionar chave API: - - Provedor: `glm` - - Chave API: `your-key` - -**Usar:** `glm/glm-4.7` - -**Dica profissional:** O plano de codificação oferece cota 3× com custo de 1/7! Redefinir diariamente às 10h. - -### MiniMax M2.1 (redefinição de 5h, US$ 0,20/1 milhão) - -1. Inscreva-se: [MiniMax](https://www.minimax.io/) -2. Obtenha a chave API -3. Painel → Adicionar chave API - -**Usar:** `minimax/MiniMax-M2.1` - -**Dica profissional:** Opção mais barata para contexto longo (1 milhão de tokens)! - -### Kimi K2 (US$ 9/mês fixo) - -1. Inscreva-se: [Moonshot AI](https://platform.moonshot.ai/) -2. Obtenha a chave API -3. Painel → Adicionar chave API - -**Usar:** `kimi/kimi-latest` - -**Dica profissional:** $9 fixos/mês para 10 milhões de tokens = $0,90/custo efetivo de 1 milhão! - -
- -
-🆓 Provedores GRATUITOS (backup de emergência) - -### Qoder (5 modelos GRATUITOS via OAuth) - -```bash -Dashboard → Connect Qoder -→ Qoder OAuth login -→ Unlimited usage - -Models: - if/kimi-k2-thinking - if/qwen3-coder-plus - if/glm-4.7 - if/minimax-m2 - if/deepseek-r1 -``` - -### Qwen (4 modelos GRATUITOS via código do dispositivo) - -```bash -Dashboard → Connect Qwen -→ Device code authorization -→ Unlimited usage - -Models: - qw/qwen3-coder-plus - qw/qwen3-coder-flash -``` - -### Kiro (Claude GRÁTIS) - -```bash -Dashboard → Connect Kiro -→ AWS Builder ID or Google/GitHub -→ Unlimited usage - -Models: - kr/claude-sonnet-4.5 - kr/claude-haiku-4.5 -``` - -
- -
-🎨 Criar Combos - -### Exemplo 1: Maximize a assinatura → Backup barato - -``` -Dashboard → Combos → Create New - -Name: premium-coding -Models: - 1. cc/claude-opus-4-6 (Subscription primary) - 2. glm/glm-4.7 (Cheap backup, $0.6/1M) - 3. minimax/MiniMax-M2.1 (Cheapest fallback, $0.20/1M) - -Use in CLI: premium-coding -``` - -### Exemplo 2: somente gratuito (custo zero) - -``` -Name: free-combo -Models: - 1. gc/gemini-3-flash-preview (180K free/month) - 2. if/kimi-k2-thinking (unlimited) - 3. qw/qwen3-coder-plus (unlimited) - -Cost: $0 forever! -``` - -
- -
-🔧 Integração CLI - -### Cursor IDE - -``` -Settings → Models → Advanced: - OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [from OmniRoute dashboard] - Model: cc/claude-opus-4-6 -``` - -### Código Cláudio - -Use a página **Ferramentas CLI** no painel para configuração com um clique ou edite `~/.claude/settings.json` manualmente. - -### CLI do Codex - -```bash -export OPENAI_BASE_URL="http://localhost:20128" -export OPENAI_API_KEY="your-omniroute-api-key" - -codex "your prompt" -``` - -###OpenClaw - -**Opção 1 — Painel (recomendado):** - -``` -Dashboard → CLI Tools → OpenClaw → Select Model → Apply -``` - -**Opção 2 — Manual:** Editar `~/.openclaw/openclaw.json`: - -```json -{ - "models": { - "providers": { - "omniroute": { - "baseUrl": "http://127.0.0.1:20128/v1", - "apiKey": "sk_omniroute", - "api": "openai-completions" - } - } - } -} -``` - -> **Observação:** OpenClaw só funciona com OmniRoute local. Use `127.0.0.1` em vez de `localhost` para evitar problemas de resolução de IPv6. - -### Cline / Continuar / RooCode - -``` -Settings → API Configuration: - Provider: OpenAI Compatible - Base URL: http://localhost:20128/v1 - API Key: [from OmniRoute dashboard] - Model: if/kimi-k2-thinking -``` - -### OpenCode - -**Etapa 1:** Adicione OmniRoute como um provedor personalizado: - -```bash -opencode -/connect -# Select "Other" → Enter ID: "omniroute" → Enter your OmniRoute API key -``` - -**Etapa 2:** Crie/edite `opencode.json` na raiz do seu projeto: - -```json -{ - "$schema": "https://opencode.ai/config.json", - "provider": { - "omniroute": { - "npm": "@ai-sdk/openai-compatible", - "name": "OmniRoute", - "options": { - "baseURL": "http://localhost:20128/v1" - }, - "models": { - "cc/claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }, - "gg/gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }, - "if/kimi-k2-thinking": { "name": "Kimi K2 (Free)" } - } - } - } -} -``` - -**Etapa 3:** Selecione o modelo no OpenCode: - -```bash -/models -# Select any OmniRoute model from the list -``` - -> **Dica:** Adicione qualquer modelo disponível no endpoint `/v1/models` do OmniRoute à seção `models`. Use o formato `provider/model-id` do painel do OmniRoute. - -
- ---- - -## 🐛 Solução de problemas - -
-Clique para expandir o guia de solução de problemas - -**"O modelo de linguagem não forneceu mensagens"** - -- Cota do provedor esgotada → Verifique o rastreador de cota do painel -- Solução: use o combo substituto ou mude para um nível mais barato - -** Limitação de taxa ** - -- Cota de assinatura esgotada → Fallback para GLM/MiniMax -- Adicionar combinação: `cc/claude-opus-4-6 → glm/glm-4.7 → if/kimi-k2-thinking` - -**O token OAuth expirou** - -- Atualizado automaticamente pelo OmniRoute -- Se os problemas persistirem: Painel → Provedor → Reconectar - -**Custos elevados** - -- Verifique as estatísticas de uso em Painel → Custos -- Mude o modelo primário para GLM/MiniMax -- Use o nível gratuito (Gemini CLI, Qoder) para tarefas não críticas - -**As portas do painel/API estão erradas** - -- `PORT` é a porta base canônica (e porta API por padrão) -- `API_PORT` substitui apenas o ouvinte de API compatível com OpenAI -- `DASHBOARD_PORT` substitui apenas o ouvinte dashboard/Next.js -- Defina `NEXT_PUBLIC_BASE_URL` para seu painel/URL público (para retornos de chamada OAuth) - -**Erros de sincronização na nuvem** - -- Verifique `BASE_URL` pontos para sua instância em execução -- Verifique os pontos `CLOUD_URL` para o endpoint de nuvem esperado -- Mantenha os valores `NEXT_PUBLIC_*` alinhados com os valores do lado do servidor - -**Primeiro login não funciona** - -- Verifique `INITIAL_PASSWORD` em `.env` -- Se não definida, a senha substituta é `123456` - -**Sem registros de solicitação** - -- Definir `ENABLE_REQUEST_LOGS=true` em `.env` - -**O teste de conexão mostra "Inválido" para provedores compatíveis com OpenAI** - -- Muitos provedores não expõem um endpoint `/models` -- OmniRoute v1.0.6+ inclui validação de fallback por meio de conclusões de chat -- Certifique-se de que o URL base inclua o sufixo `/v1` - -### 🔐 OAuth em um servidor remoto - - - - -> **⚠️ Importante para usuários executando OmniRoute em um VPS, Docker ou qualquer servidor remoto** - -#### Por que o Antigravity / Gemini CLI OAuth falha em servidores remotos? - -Os provedores **Antigravity** e **Gemini CLI** usam o **Google OAuth 2.0**. O Google exige que `redirect_uri` no fluxo OAuth corresponda exatamente a um dos URIs pré-registrados no Console do Google Cloud do aplicativo. - -As credenciais OAuth incluídas no OmniRoute são registradas **somente para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (por exemplo, `https://omniroute.myserver.com`), o Google rejeita a autenticação com: - -``` -Error 400: redirect_uri_mismatch -``` - -#### Solução: Configure suas próprias credenciais OAuth - -Você precisa criar um **ID do cliente OAuth 2.0** no Console do Google Cloud com o URI do seu servidor. - -#### Passo a passo - -**1. Abra o Console do Google Cloud** - -Vá para: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) - -**2. Crie um novo ID de cliente OAuth 2.0** - -- Clique em **"+ Criar credenciais"** → **"ID do cliente OAuth"** -- Tipo de aplicativo: **"Aplicativo Web"** -- Nome: o que você quiser (por exemplo, `OmniRoute Remote`) - -**3. Adicionar URIs de redirecionamento autorizados** - -No campo **"URIs de redirecionamento autorizados"**, adicione: - -``` -https://your-server.com/callback -``` - -> Substitua `your-server.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, por exemplo, `http://45.33.32.156:20128/callback`). - -**4. Salve e copie as credenciais** - -Após a criação, o Google mostrará o **ID do cliente** e o **Segredo do cliente**. - -**5. Definir variáveis de ambiente** - -Em seu `.env` (ou variáveis de ambiente Docker): - -```bash -# For Antigravity: -ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com -ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret - -# For Gemini CLI: -GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com -GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret -GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret -``` - -**6. Reinicie o OmniRoute** - -```bash -# npm: -npm run dev - -# Docker: -docker restart omniroute -``` - -**7. Tente conectar novamente** - -Painel → Provedores → Antigravidade (ou Gemini CLI) → OAuth - -O Google agora redirecionará corretamente para `https://your-server.com/callback`. - ---- - -#### Solução temporária (sem credenciais personalizadas) - -Se não quiser configurar suas próprias credenciais agora, você ainda pode usar o **fluxo manual de URL**: - -1. OmniRoute abre o URL de autorização do Google -2. Após autorização, o Google tenta redirecionar para `localhost` (que falha no servidor remoto) -3. **Copie o URL completo** da barra de endereço do seu navegador (mesmo que a página não carregue) -4. Cole esse URL no campo mostrado no modal de conexão OmniRoute -5. Clique em **"Conectar"** - -> Isso funciona porque o código de autorização no URL é válido independentemente de a página de redirecionamento ter sido carregada. - ---- - -
-🇧🇷 Versão em Português - -#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? - -Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticação. O Google exige que um `redirect_uri` usado no fluxo OAuth seja **exatamente** uma das URIs pré-cadastradas no Google Cloud Console do aplicativo. - -As credenciais OAuth incorporadas no OmniRoute estão cadastradas **apenas para `localhost`**. Quando você acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticação com: - -``` -Error 400: redirect_uri_mismatch -``` - -#### Solução: Configure suas próprias credenciais OAuth - -Você precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com o URI do seu servidor. - -####Passo a passo - -**1. Acesse o Console do Google Cloud** - -Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) - -**2. Crie um novo ID de cliente OAuth 2.0** - -- Clique em **"+ Criar credenciais"** → **"ID do cliente OAuth"** -- Tipo de aplicativo: **"Aplicativo Web"** -- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) - -**3. Adicionar como URIs de redirecionamento autorizados** - -No campo **"URIs de redirecionamento autorizados"**, adicionado: - -``` -https://seu-servidor.com/callback -``` - -> Substitua `seu-servidor.com` pelo domínio ou IP do seu servidor (inclua a porta se necessário, ex: `http://45.33.32.156:20128/callback`). - -**4. Salve e copie as credenciais** - -Após criar, o Google mostrará o **Client ID** e o **Client Secret**. - -**5. Configurar como variáveis de ambiente** - -No seu `.env` (ou nas variáveis de ambiente do Docker): - -```bash -# Para Antigravity: -ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com -ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret - -# Para Gemini CLI: -GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com -GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret -GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret -``` - -**6. Reinicie o OmniRoute** - -```bash -# Se usando npm: -npm run dev - -# Se usando Docker: -docker restart omniroute -``` - -**7. Tente conectar novamente** - -Painel → Provedores → Antigravidade (ou Gemini CLI) → OAuth - -Agora o Google redirecionará corretamente para `https://seu-servidor.com/callback` e a autenticação funcionará. - ---- - -#### Solução alternativa temporária (sem configurar credenciais próprias) - -Se não quiser criar credenciais próprias agora, ainda é possível usar o fluxo **manual de URL**: - -1. O OmniRoute abrirá uma URL de autorização do Google -2. Após você autorizar, o Google tentará redirecionar para `localhost` (que falha no servidor remoto) -3. **Copie a URL completa** da barra de endereço do seu navegador (mesmo que a página não carregue) -4. Cole essa URL no campo que aparece no modal de conexão do OmniRoute -5. Clique em **"Conectar"** - -> Esta solução alternativa funciona porque o código de autorização na URL é válido, independentemente do redirecionamento ter sido carregado ou não. - -
- ---- - -
- -## 🛠️ Pilha de tecnologia - -
-Clique para expandir os detalhes da pilha de tecnologia - -- **Tempo de execução**: Node.js 18–22 LTS (⚠️ Node.js 24+ **não é compatível** — `better-sqlite3` binários nativos são incompatíveis) -- **Idioma**: TypeScript 5.9 — **100% TypeScript** em `src/` e `open-sse/` (zero `any` em módulos principais desde v2.0) -- **Estrutura**: Next.js 16 + React 19 + Tailwind CSS 4 -- **Banco de dados**: LowDB (JSON) + SQLite (estado do domínio + logs de proxy + auditoria MCP + decisões de roteamento) -- **Esquemas**: Zod (validação de E/S da ferramenta MCP, contratos de API) -- **Protocolos**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) -- **Streaming**: eventos enviados pelo servidor (SSE) -- **Auth**: OAuth 2.0 (PKCE) + JWT + Chaves de API + Autorização com escopo MCP -- **Testes**: executor de testes Node.js + Vitest (mais de 900 testes incluindo unidade, integração, E2E) -- **CI/CD**: GitHub Actions (publicação automática de npm + Docker Hub no lançamento) -- **Site**: [omniroute.online](https://omniroute.online) -- **Pacote**: [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) -- **Docker**: [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) -- **Resiliência**: Disjuntor, espera exponencial, rebanho anti-trovão, falsificação de TLS, autocura de combinação automática - -
- ---- - -## 📖 Documentação - -| Documento | Descrição | -| ---------------------------------------------- | ------------------------------------------------------------------------ | -| [User Guide](docs/USER_GUIDE.md) | Provedores, combos, integração CLI, implantação | -| [API Reference](docs/API_REFERENCE.md) | Todos os endpoints com exemplos | -| [MCP Server](open-sse/mcp-server/README.md) | 16 ferramentas MCP, configurações IDE, clientes Python/TS/Go | -| [A2A Server](src/lib/a2a/README.md) | Protocolo JSON-RPC 2.0, habilidades, streaming, gerenciamento de tarefas | -| [Auto-Combo Engine](docs/auto-combo.md) | Pontuação de 6 fatores, pacotes de modos, autocura | -| [Troubleshooting](docs/TROUBLESHOOTING.md) | Problemas e soluções comuns | -| [Architecture](docs/ARCHITECTURE.md) | Arquitetura do sistema e componentes internos | -| [Contributing](CONTRIBUTING.md) | Configuração e diretrizes de desenvolvimento | -| [OpenAPI Spec](docs/openapi.yaml) | Especificação OpenAPI 3.0 | -| [Security Policy](SECURITY.md) | Relatórios de vulnerabilidades e práticas de segurança | -| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Guia completo: configuração de VM + nginx + Cloudflare | -| [Features Gallery](docs/FEATURES.md) | Tour visual do painel com capturas de tela | -| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Etapas de validação de pré-lançamento | - ---- - -## 🗺️ Roteiro - -OmniRoute tem **210+ recursos planejados** em diversas fases de desenvolvimento. Aqui estão as principais áreas: - -| Categoria | Recursos planejados | Destaques | -| --------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | -| 🧠 **Roteamento e Inteligência** | 25+ | Roteamento de menor latência, roteamento baseado em tags, simulação de cota, seleção de conta P2C | -| 🔒 **Segurança e Conformidade** | 20+ | Proteção SSRF, camuflagem de credenciais, limite de taxa por endpoint, escopo de chave de gerenciamento | -| 📊 **Observabilidade** | 15+ | Integração OpenTelemetry, monitoramento de cotas em tempo real, rastreamento de custos por modelo | -| 🔄 **Integrações com Provedores** | 20+ | Registro de modelo dinâmico, resfriamento de provedor, Codex multicontas, análise de cotas do Copilot | -| ⚡ **Desempenho** | 15+ | Camada de cache dupla, cache de prompt, cache de resposta, manutenção de atividade de streaming, API em lote | -| 🌐 **Ecossistema** | 10+ | API WebSocket, configuração hot-reload, armazenamento de configuração distribuído, modo comercial | - -### 🔜 Em breve - -- 🔗 **Integração OpenCode** — Suporte de provedor nativo para o IDE de codificação OpenCode AI -- 🔗 **Integração TRAE** — Suporte total para a estrutura de desenvolvimento TRAE AI -- 📦 **API Batch** — Processamento assíncrono em lote para solicitações em massa -- 🎯 **Roteamento baseado em tags** — Roteie solicitações com base em tags personalizadas e metadados -- 💰 **Estratégia de custo mais baixo** — Selecione automaticamente o provedor mais barato disponível - -> 📝 Especificações completas de recursos disponíveis em [**OMNI_TOKEN_342**](docs/new-features/) (217 especificações detalhadas) - ---- - -## 👥 Colaboradores - -[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) - -### Como contribuir - -1. Bifurque o repositório -2. Crie sua ramificação de recursos (`git checkout -b feature/amazing-feature`) -3. Confirme suas alterações (`git commit -m 'Add amazing feature'`) -4. Envie para a ramificação (`git push origin feature/amazing-feature`) -5. Abra uma solicitação pull - -Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para obter diretrizes detalhadas. - -### Lançando uma nova versão - -```bash -# Create a release — npm publish happens automatically -gh release create v2.0.0 --title "v2.0.0" --generate-notes -``` - ---- - -## 📊 História das Estrelas - -## Observadores das estrelas ao longo do tempo - -## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute) - -## 🙏 Agradecimentos - -Agradecimentos especiais a **[9router](https://github.com/decolua/9router)** de **[decolua](https://github.com/decolua)** — o projeto original que inspirou este fork. OmniRoute se baseia nessa base incrível com recursos adicionais, APIs multimodais e uma reescrita completa do TypeScript. - -Agradecimentos especiais a **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** — a implementação Go original que inspirou esta versão JavaScript. - ---- - -## 📄 Licença - -Licença MIT - consulte [LICENSE](LICENSE) para obter detalhes. - ---- - -
- Construído com ❤️ para desenvolvedores que codificam 24 horas por dia, 7 dias por semana -
- omniroute.online -
- diff --git a/README.ro.md b/README.ro.md deleted file mode 100644 index 01ff4f4db8..0000000000 --- a/README.ro.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (ro) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/ro/README.md)** diff --git a/README.sk.md b/README.sk.md deleted file mode 100644 index 9345729ed7..0000000000 --- a/README.sk.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (sk) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/sk/README.md)** diff --git a/README.sv.md b/README.sv.md deleted file mode 100644 index 2194e80227..0000000000 --- a/README.sv.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (sv) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/sv/README.md)** diff --git a/README.th.md b/README.th.md deleted file mode 100644 index 488ef8db4f..0000000000 --- a/README.th.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (th) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/th/README.md)** diff --git a/README.uk-UA.md b/README.uk-UA.md deleted file mode 100644 index 39fec3b55c..0000000000 --- a/README.uk-UA.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (uk-UA) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/uk-UA/README.md)** diff --git a/README.vi.md b/README.vi.md deleted file mode 100644 index 0931b18347..0000000000 --- a/README.vi.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🌐 OmniRoute (vi) - -The documentation has been formalized and moved to our centralized i18n structure. - -👉 **[Read the Documentation here](docs/i18n/vi/README.md)** diff --git a/SECURITY.md b/SECURITY.md index b620051d82..c575dd78fa 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -20,9 +20,9 @@ If you discover a security vulnerability in OmniRoute, please report it responsi | Version | Support Status | | ------- | -------------- | -| 1.0.x | ✅ Active | -| 0.8.x | ✅ Security | -| < 0.8.0 | ❌ Unsupported | +| 3.4.x | ✅ Active | +| 3.0.x | ✅ Security | +| < 3.0.0 | ❌ Unsupported | --- @@ -43,6 +43,7 @@ Request → CORS → API Key Auth → Prompt Injection Guard → Input Sanitizer | **OAuth 2.0 + PKCE** | Secure provider auth (Claude, Codex, Gemini, Cursor, etc.) | | **Token Refresh** | Automatic OAuth token refresh before expiry | | **Secure Cookies** | `AUTH_COOKIE_SECURE=true` for HTTPS environments | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | ### 🛡️ Encryption at Rest @@ -98,9 +99,11 @@ PII_REDACTION_ENABLED=true | Feature | Description | | ------------------------ | ---------------------------------------------------------------- | | **CORS** | Configurable origin control (`CORS_ORIGIN` env var, default `*`) | -| **IP Filtering** | Whitelist/blacklist IP ranges in dashboard | +| **IP Filtering** | Allowlist/blocklist IP ranges in dashboard | | **Rate Limiting** | Per-provider rate limits with automatic backoff | | **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | ### 🔌 Resilience & Availability @@ -113,11 +116,13 @@ PII_REDACTION_ENABLED=true ### 📋 Compliance -| Feature | Description | -| ------------------ | --------------------------------------------------- | -| **Log Retention** | Automatic cleanup after `LOG_RETENTION_DAYS` | -| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | -| **Audit Log** | Administrative actions tracked in `audit_log` table | +| Feature | Description | +| ------------------ | ----------------------------------------------------------- | +| **Log Retention** | Automatic cleanup after `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | --- @@ -167,3 +172,4 @@ docker run -d \ - Keep dependencies updated - The project uses `husky` + `lint-staged` for pre-commit checks - CI pipeline runs ESLint security rules on every push +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/COVERAGE_PLAN.md b/docs/COVERAGE_PLAN.md similarity index 100% rename from COVERAGE_PLAN.md rename to docs/COVERAGE_PLAN.md diff --git a/llm.txt b/llm.txt index caab9ce7b4..24c80a0f6e 100644 --- a/llm.txt +++ b/llm.txt @@ -1,6 +1,6 @@ # OmniRoute -> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 67+ AI providers — all through a single OpenAI-compatible endpoint. +> OmniRoute is a free, open-source AI Gateway that acts as a universal API proxy for multi-provider LLMs. It provides smart routing, automatic fallback, load balancing, and format translation across 60+ AI providers — all through a single OpenAI-compatible endpoint. Includes a built-in MCP Server (25 tools), A2A v0.3 protocol, Memory/Skills systems, and an Electron desktop app. ## Overview @@ -8,20 +8,22 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo **Key value:** One endpoint (`http://localhost:20128/v1`), unlimited models, zero downtime, minimal cost. -**Current version:** 3.0.0 +**Current version:** 3.4.2 ## Tech Stack -- **Runtime:** Node.js >= 18 +- **Runtime:** Node.js >= 18 < 24, ES Modules (`"type": "module"`) - **Framework:** Next.js 16 (App Router) with TypeScript 5.9 -- **Database:** SQLite via better-sqlite3 (local, zero-config) +- **Database:** SQLite via better-sqlite3 (local, zero-config, 16 migrations) - **State management:** Zustand (client), SQLite (server persistence) - **UI:** React 19, Tailwind CSS 4, Recharts for analytics, @lobehub/icons for 130+ provider SVG icons - **Auth:** OAuth 2.0 (PKCE) for providers, bcrypt for local user auth +- **Schemas:** Zod v4 for all API / MCP input validation - **Background jobs:** Custom token health check scheduler, 24h model auto-sync - **Streaming:** Server-Sent Events (SSE) for real-time proxy responses - **Proxy engine:** Custom pipeline with format translation, circuit breaker, rate limiting, auto-combo engine - **i18n:** next-intl with 30 languages +- **Desktop:** Electron (cross-platform: Windows, macOS, Linux) - **Package:** Published on npm (`omniroute`) and Docker Hub (`diegosouzapw/omniroute`) ## Project Structure @@ -35,6 +37,9 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo │ │ │ ├── agents/ # ACP Agents dashboard (CLI agent detection + custom agents) │ │ │ ├── analytics/ # Usage analytics and charts │ │ │ ├── api-manager/ # API key management +│ │ │ ├── audit/ # Audit logs +│ │ │ ├── auto-combo/ # Auto-combo engine dashboard +│ │ │ ├── cache/ # Cache dashboard (semantic cache stats) │ │ │ ├── cli-tools/ # CLI tool configuration (Claude Code, Codex, Gemini CLI, etc.) │ │ │ ├── combos/ # Model combo management (9 strategies + 4 templates) │ │ │ ├── costs/ # Cost tracking per provider/model @@ -43,38 +48,130 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo │ │ │ ├── limits/ # Rate limits dashboard │ │ │ ├── logs/ # Request, Proxy, Audit, Console logs (tabbed) │ │ │ ├── media/ # Image/video/music generation + transcription +│ │ │ ├── memory/ # Memory system dashboard +│ │ │ ├── onboarding/ # Onboarding wizard │ │ │ ├── playground/ # Model playground (Monaco editor, streaming) │ │ │ ├── providers/ # Provider management (OAuth + API key + free) +│ │ │ ├── search-tools/ # Search tools configuration │ │ │ ├── settings/ # Settings tabs (General, Appearance, Security, Routing, Resilience, Advanced) +│ │ │ ├── skills/ # Skills system dashboard │ │ │ ├── translator/ # Format translator + debug tools │ │ │ └── usage/ # Usage history -│ │ ├── api/ # REST API endpoints -│ │ │ ├── v1/ # OpenAI-compatible API (chat, models, embeddings, images, audio) +│ │ ├── api/ # REST API endpoints (51 route directories) +│ │ │ ├── v1/ # OpenAI-compatible API (chat, completions, models, embeddings, +│ │ │ │ # images, audio, videos, music, moderations, rerank, search, +│ │ │ │ # responses, messages, registered-keys, quotas, accounts) +│ │ │ ├── v1beta/ # Gemini-compatible API +│ │ │ ├── a2a/ # A2A agent management API │ │ │ ├── acp/ # ACP agent management API │ │ │ ├── oauth/ # OAuth flows per provider │ │ │ ├── providers/ # Provider CRUD and batch testing │ │ │ ├── models/ # Dashboard model listing and aliases │ │ │ ├── combos/ # Combo CRUD (multi-model fallback chains) -│ │ │ └── ... # Other endpoints (usage, logs, health, settings, etc.) -│ │ └── login/ # Login page -│ ├── domain/ # Domain types and business logic interfaces +│ │ │ ├── memory/ # Memory system API +│ │ │ ├── skills/ # Skills system API +│ │ │ ├── evals/ # Eval runner API +│ │ │ ├── mcp/ # MCP HTTP transport API +│ │ │ ├── search/ # Search provider API +│ │ │ ├── webhooks/ # Webhook management +│ │ │ ├── tunnels/ # Cloudflare tunnel management +│ │ │ └── ... # Other endpoints (usage, logs, health, settings, pricing, etc.) +│ │ ├── landing/ # Landing page +│ │ ├── login/ # Login page +│ │ ├── forgot-password/ # Password recovery +│ │ ├── status/ # Status page +│ │ └── docs/ # In-app documentation +│ ├── domain/ # Domain types and policy engine +│ │ ├── policyEngine.ts # Central policy engine +│ │ ├── comboResolver.ts # Combo resolution logic +│ │ ├── costRules.ts # Cost calculation rules +│ │ ├── degradation.ts # Graceful degradation +│ │ ├── fallbackPolicy.ts # Fallback behavior +│ │ ├── lockoutPolicy.ts # Account lockout logic +│ │ ├── modelAvailability.ts # Model availability checks +│ │ ├── providerExpiration.ts # Provider credential expiration +│ │ ├── quotaCache.ts # Quota caching layer +│ │ ├── configAudit.ts # Configuration auditing +│ │ └── responses.ts # Domain response types │ ├── i18n/ # Internationalization │ │ └── messages/ # 30 language JSON files │ ├── lib/ # Core libraries │ │ ├── a2a/ # Agent-to-Agent v0.3 protocol server -│ │ ├── acp/ # ACP agent registry and manager (14 built-in + custom) -│ │ ├── db/ # SQLite database layer (core, providers, models, combos, apiKeys, settings, backup) +│ │ │ ├── skills/ # A2A skills (quotaManagement, smartRouting) +│ │ │ ├── taskManager.ts # Task lifecycle with TTL cleanup +│ │ │ └── streaming.ts # SSE streaming for A2A +│ │ ├── acp/ # Agent Communication Protocol registry and manager +│ │ ├── compliance/ # Compliance policy engine +│ │ ├── db/ # SQLite database layer (21 modules + migrations) +│ │ │ ├── core.ts # Database initialization, connection, schema +│ │ │ ├── providers.ts # Provider connection CRUD +│ │ │ ├── models.ts # Model catalog management +│ │ │ ├── combos.ts # Combo configuration +│ │ │ ├── apiKeys.ts # API key management +│ │ │ ├── settings.ts # Settings persistence +│ │ │ ├── backup.ts # Database backup/restore +│ │ │ ├── proxies.ts # Proxy registry +│ │ │ ├── prompts.ts # Prompt templates +│ │ │ ├── webhooks.ts # Webhook subscriptions +│ │ │ ├── detailedLogs.ts # Detailed request logging +│ │ │ ├── domainState.ts # Domain state persistence +│ │ │ ├── registeredKeys.ts # Registered API keys with quotas +│ │ │ ├── quotaSnapshots.ts # Quota snapshot history +│ │ │ ├── modelComboMappings.ts # Model-to-combo mappings +│ │ │ ├── cliToolState.ts # CLI tool state tracking +│ │ │ ├── encryption.ts # Data encryption +│ │ │ ├── readCache.ts # Read-through cache layer +│ │ │ ├── secrets.ts # Secrets management +│ │ │ ├── stateReset.ts # State reset utilities +│ │ │ ├── migrationRunner.ts # Schema migration runner +│ │ │ └── migrations/ # 16 SQL migration files +│ │ ├── evals/ # Eval runner and scheduler +│ │ ├── memory/ # Persistent conversational memory +│ │ │ ├── extraction.ts # Memory extraction from conversations +│ │ │ ├── injection.ts # Memory injection into context +│ │ │ ├── retrieval.ts # Memory retrieval/search +│ │ │ ├── store.ts # Memory persistence layer +│ │ │ └── summarization.ts # Memory summarization │ │ ├── oauth/ # OAuth providers, services, and utilities │ │ │ ├── constants/ # Default OAuth credentials (overridable via env) │ │ │ ├── providers/ # Provider-specific OAuth configs │ │ │ ├── services/ # Provider-specific token exchange logic │ │ │ └── utils/ # PKCE, callback server, token helpers +│ │ ├── plugins/ # Plugin system +│ │ ├── skills/ # Extensible skill framework +│ │ │ ├── registry.ts # Skill registration +│ │ │ ├── executor.ts # Skill execution engine +│ │ │ ├── sandbox.ts # Skill sandbox environment +│ │ │ ├── builtin/ # Built-in skills +│ │ │ ├── interception.ts # Skill request interception +│ │ │ └── injection.ts # Skill context injection +│ │ ├── usage/ # Usage tracking system +│ │ │ ├── callLogs.ts # Call log persistence +│ │ │ ├── costCalculator.ts # Cost calculation engine +│ │ │ └── usageHistory.ts # Usage history queries │ │ ├── cloudSync.ts # Cloud sync via Cloudflare Workers +│ │ ├── cloudflaredTunnel.ts # Cloudflare tunnel management +│ │ ├── pricingSync.ts # LiteLLM pricing data sync +│ │ ├── semanticCache.ts # Semantic caching layer │ │ ├── tokenHealthCheck.ts # Background OAuth token refresh scheduler +│ │ ├── webhookDispatcher.ts # Webhook event dispatcher │ │ └── localDb.ts # Unified re-export layer for all DB modules +│ ├── middleware/ # Request middleware +│ │ └── promptInjectionGuard.ts # Prompt injection detection +│ ├── mitm/ # MITM proxy capability +│ │ ├── cert/ # Certificate management +│ │ ├── dns/ # DNS handling +│ │ ├── targets/ # Target routing +│ │ └── manager.ts # MITM proxy manager │ ├── shared/ # Shared utilities, components, and constants │ │ ├── components/ # Reusable UI components (Card, Badge, Button, Modal, Sidebar, ProviderIcon, etc.) -│ │ ├── constants/ # Provider definitions, model lists, pricing, upstream headers +│ │ ├── constants/ # Provider definitions (60+), model lists, pricing, routing strategies, MCP scopes +│ │ ├── contracts/ # Shared API contracts +│ │ ├── hooks/ # React hooks +│ │ ├── middleware/ # Shared middleware utilities +│ │ ├── schemas/ # Shared Zod schemas +│ │ ├── services/ # Shared services +│ │ ├── types/ # Shared TypeScript types │ │ ├── validation/ # Zod schemas (settings, providers, routes) │ │ └── utils/ # Helpers (auth, CORS, error codes, machine ID) │ ├── sse/ # SSE proxy pipeline @@ -83,29 +180,109 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo │ ├── store/ # Zustand client-side stores (theme, providers, etc.) │ └── types/ # TypeScript type definitions ├── open-sse/ # Standalone SSE server (npm workspace) -│ ├── config/ # Model registries (embedding, image, audio, rerank, moderation, CLI fingerprints) -│ ├── handlers/ # Request handlers per API type (chat, responses, embeddings, images, audio, search) -│ ├── mcp-server/ # Built-in MCP server (16 tools, 3 transports: stdio/SSE/streamable-HTTP) -│ ├── services/ # Auto-combo engine (6-factor scoring, 4 mode packs, bandit exploration) -│ └── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek) -├── tests/ # Test suites (926 assertions) -│ ├── unit/ # Unit tests (32+ test files) -│ └── integration/ # Integration tests +│ ├── config/ # Model registries (providerRegistry, embedding, image, audio, video, +│ │ # music, rerank, moderation, search, CLI fingerprints, Ollama models) +│ ├── executors/ # Provider-specific request executors (14 executors) +│ │ ├── base.ts # Base executor with shared logic +│ │ ├── default.ts # Default OpenAI-compatible executor +│ │ ├── cursor.ts # Cursor IDE (protobuf + checksum) +│ │ ├── codex.ts # OpenAI Codex CLI +│ │ ├── antigravity.ts # Antigravity IDE +│ │ ├── github.ts # GitHub Copilot +│ │ ├── gemini-cli.ts # Gemini CLI +│ │ ├── kiro.ts # Kiro AI +│ │ ├── qoder.ts # Qoder AI +│ │ ├── vertex.ts # Vertex AI (Service Account JSON) +│ │ ├── cloudflare-ai.ts # Cloudflare Workers AI +│ │ ├── opencode.ts # OpenCode Zen/Go +│ │ ├── pollinations.ts # Pollinations AI +│ │ └── puter.ts # Puter AI +│ ├── handlers/ # Request handlers per API type (11 handlers) +│ │ ├── chatCore.ts # Main chat completions handler +│ │ ├── responsesHandler.ts # OpenAI Responses API handler +│ │ ├── embeddings.ts # Embedding generation +│ │ ├── imageGeneration.ts # Image generation (DALL-E, FLUX, SD, etc.) +│ │ ├── videoGeneration.ts # Video generation +│ │ ├── musicGeneration.ts # Music generation +│ │ ├── audioSpeech.ts # Text-to-speech +│ │ ├── audioTranscription.ts # Speech-to-text (Whisper, Deepgram, AssemblyAI) +│ │ ├── moderations.ts # Content moderation +│ │ ├── rerank.ts # Reranking API +│ │ └── search.ts # Web search API +│ ├── mcp-server/ # Built-in MCP server (25 tools, 3 transports: stdio/SSE/streamable-HTTP) +│ │ ├── server.ts # MCP server core (tool registration, scope enforcement) +│ │ ├── tools/ # Tool implementations (advancedTools, memoryTools, skillTools) +│ │ ├── schemas/ # Zod input schemas (tools, audit, a2a) +│ │ ├── scopeEnforcement.ts # Scope-based access control (10 scopes) +│ │ ├── audit.ts # Tool call audit logging +│ │ ├── runtimeHeartbeat.ts # MCP runtime heartbeat +│ │ └── httpTransport.ts # HTTP transport handler +│ ├── services/ # 36+ service modules +│ │ ├── combo.ts # Core routing engine +│ │ ├── usage.ts # Usage tracking +│ │ ├── tokenRefresh.ts # OAuth token refresh +│ │ ├── rateLimitManager.ts # Rate limit management +│ │ ├── accountFallback.ts # Multi-account fallback +│ │ ├── sessionManager.ts # Session management +│ │ ├── wildcardRouter.ts # Wildcard model routing +│ │ ├── autoCombo/ # Auto-combo engine (6-factor scoring, bandit exploration) +│ │ ├── intentClassifier.ts # Request intent classification +│ │ ├── taskAwareRouter.ts # Task-aware routing +│ │ ├── thinkingBudget.ts # Thinking budget management +│ │ ├── contextManager.ts # Context window management +│ │ ├── modelDeprecation.ts # Model deprecation handling +│ │ ├── modelFamilyFallback.ts # Intra-family model fallback +│ │ ├── emergencyFallback.ts # Emergency fallback +│ │ ├── workflowFSM.ts # Workflow state machine +│ │ ├── backgroundTaskDetector.ts # Background task detection +│ │ ├── ipFilter.ts # IP-based access control +│ │ ├── signatureCache.ts # CLI signature caching +│ │ ├── volumeDetector.ts # Request volume detection +│ │ └── ... # Additional services (16 more modules) +│ ├── transformer/ # Responses API transformer +│ │ └── responsesTransformer.ts +│ ├── translator/ # Format translators (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama ↔ DeepSeek) +│ │ ├── request/ # Request translators per provider +│ │ ├── response/ # Response translators per provider +│ │ ├── helpers/ # Translation helpers +│ │ └── image/ # Image format translation +│ └── utils/ # 22 utility modules (stream, TLS, proxy, logging, etc.) +├── electron/ # Electron desktop app (cross-platform) +│ ├── main.js # Electron main process +│ ├── preload.js # Preload script (IPC bridge) +│ └── assets/ # App icons and assets +├── tests/ # Test suites +│ ├── unit/ # 122 unit test files +│ ├── integration/ # Integration tests +│ ├── e2e/ # Playwright E2E tests +│ ├── security/ # Security tests +│ ├── translator/ # Translator-specific tests +│ └── load/ # Load tests ├── docs/ # Documentation -│ ├── i18n/ # 30-language translated READMEs -│ ├── screenshots/ # Dashboard screenshots -│ ├── a2a-server.md # A2A agent protocol documentation -│ ├── auto-combo.md # Auto-combo engine (6-factor scoring) -│ └── mcp-server.md # MCP server (16 tools) +│ ├── i18n/ # 30-language translated docs +│ ├── ARCHITECTURE.md # Full architecture documentation +│ ├── API_REFERENCE.md # API reference +│ ├── USER_GUIDE.md # User guide +│ ├── CODEBASE_DOCUMENTATION.md # Codebase overview +│ ├── CLI-TOOLS.md # CLI tools integration guide +│ ├── A2A-SERVER.md # A2A agent protocol documentation +│ ├── AUTO-COMBO.md # Auto-combo engine (6-factor scoring) +│ ├── MCP-SERVER.md # MCP server (25 tools) +│ ├── TROUBLESHOOTING.md # Troubleshooting guide +│ ├── VM_DEPLOYMENT_GUIDE.md # VPS deployment guide +│ ├── openapi.yaml # OpenAPI specification +│ └── screenshots/ # Dashboard screenshots ├── bin/ # CLI entry points (omniroute, reset-password) +├── scripts/ # Build and utility scripts └── .env.example # Environment variable template ``` -## Key Features (v3.0.0) +## Key Features (v3.4.2) ### Core Proxy -- **67+ AI providers** with automatic format translation -- **6 routing strategies**: priority, weighted, round-robin, random, least-used, cost-optimized +- **60+ AI providers** with automatic format translation +- **4 provider categories**: Free (4), OAuth (8), API Key (48+), Custom (OpenAI/Anthropic-compatible) +- **9 routing strategies**: priority, weighted, round-robin, fill-first, p2c, random, least-used, cost-optimized, strict-random - **4-tier fallback**: Subscription → API Key → Cheap → Free - **Auto-combo engine**: Self-healing routing optimization with 6-factor scoring, bandit exploration, progressive cooldown - **Semantic caching** with cache hit/miss headers @@ -114,50 +291,81 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo - **Provider Icons**: 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback - **Model Auto-Sync**: 24h scheduler refreshes model lists for 16 providers - **Registered Keys API**: Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement -- **926 tests** with 0 failures +- **Memory System**: Persistent conversational memory with extraction, injection, retrieval, and summarization +- **Skills System**: Extensible skill framework with registry, executor, sandbox, built-in and custom skills +- **Prompt Injection Guard**: Middleware-level prompt injection detection +- **MITM Proxy**: Certificate management, DNS handling, and target routing +- **Cloudflare Tunnels**: Managed tunnel creation for remote access +- **122 unit test files** with comprehensive coverage (55% statements/lines/functions, 60% branches) ### Security - **CodeQL security**: Fixed 10+ CodeQL alerts (polynomial-redos, insecure-randomness, shell-injection) -- **Route validation**: All 176 API routes validated with Zod schemas + `validateBody()` +- **Route validation**: All API routes validated with Zod v4 schemas + `validateBody()` - **omniModel tag sanitization**: Internal `` tags never leak to clients in SSE streams - **TLS Fingerprint Spoofing** — Browser-like TLS fingerprint to reduce bot detection - **CLI Fingerprint Matching** — Per-provider request signature matching +- **Prompt injection guard** — Request middleware detection +- **Provider constants validated at module load** via Zod (`src/shared/validation/providerSchema.ts`) +- **PII sanitizer** — Sensitive data scrubbing in logs -### Dashboard Pages +### Dashboard Pages (23 sections) - **Providers** — OAuth, API key, and free provider management with ProviderIcon SVG icons - **Combos** — Multi-model combo builder with 4 templates (Free Stack, High Availability, Cost Saver, Balanced) + 9 strategies +- **Auto-Combo** — Auto-combo engine dashboard with scoring metrics - **Analytics** — Token consumption, cost, heatmaps, distributions - **Health** — Uptime, memory, latency percentiles, circuit breakers - **Logs** — Request, Proxy, Audit, Console (tabbed) +- **Audit** — Audit trail and compliance logging - **Costs** — Cost tracking per provider/model - **Limits** — Rate limit monitoring +- **Cache** — Semantic cache statistics and management - **CLI Tools** — One-click configuration for 10+ AI CLI tools - **CLI Agents** — Grid of 14+ built-in agents with ProviderIcon and install detection + custom agent registration - **Playground** — Test any model with Monaco editor, streaming responses - **Media** — Image/video/music generation (DALL-E, FLUX, etc.) + audio transcription (up to 2GB files) +- **Search Tools** — Search provider configuration and testing +- **Memory** — Memory system management and visualization +- **Skills** — Skills framework management and execution - **Translator** — Format debugging: playground, chat tester, test bench, live monitor - **Settings** — General, Appearance (7 color themes), Security (TLS/CLI fingerprint, IP filter), Routing, Resilience, Advanced - **Endpoint** — Unified: Endpoint Proxy, MCP Server, A2A Server, API Endpoints (tabbed) +- **Onboarding** — Setup wizard for new users +- **Usage** — Usage history and analytics +- **API Manager** — API key management with scoped permissions ### Protocol Support -- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`, `/v1/audio/speech` +- **OpenAI-compatible** — `/v1/chat/completions`, `/v1/models`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`, `/v1/audio/speech`, `/v1/moderations`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` - **Anthropic** — `/v1/messages`, `/v1/messages/count_tokens` - **OpenAI Responses** — `/v1/responses` - **Gemini** — `/v1beta/models`, `/v1beta/models/{...path}` - **Ollama** — `/v1/api/chat`, `/api/tags` -- **MCP** — 16-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP) +- **Search** — `/v1/search` (Perplexity, Serper, Brave, Exa, Tavily) +- **MCP** — 25-tool MCP server with scope-based auth (3 transports: stdio, SSE, streamable HTTP) - **A2A** — Agent-to-Agent v0.3 protocol (JSON-RPC 2.0, smart-routing + quota-management skills) -- **ACP** — Agent detection, custom agent registry +- **ACP** — Agent Communication Protocol registry and manager -### MCP Server (16 Tools) +### MCP Server (25 Tools) | Category | Tools | |-----------|-------| -| Essential | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog` | -| Advanced | `simulate_route`, `set_budget_guard`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot` | +| Core (18) | `get_health`, `list_combos`, `get_combo_metrics`, `switch_combo`, `check_quota`, `route_request`, `cost_report`, `list_models_catalog`, `simulate_route`, `set_budget_guard`, `set_routing_strategy`, `set_resilience_profile`, `test_combo`, `get_provider_metrics`, `best_combo_for_task`, `explain_route`, `get_session_snapshot`, `sync_pricing` | +| Memory (3) | `memory_search`, `memory_add`, `memory_clear` | +| Skills (4) | `skills_list`, `skills_enable`, `skills_execute`, `skills_executions` | + +**MCP Auth Scopes (10):** `read:health`, `read:combos`, `write:combos`, `read:quota`, `read:usage`, `read:models`, `execute:completions`, `execute:search`, `write:budget`, `write:resilience` + +### Provider Categories + +**Free Providers (4):** Qoder AI, Qwen Code, Gemini CLI (deprecated), Kiro AI + +**OAuth Providers (8):** Claude Code, Antigravity, OpenAI Codex, GitHub Copilot, Cursor IDE, Kimi Coding, Kilo Code, Cline + +**API Key Providers (48+):** OpenAI, Anthropic, Gemini (Google AI Studio), DeepSeek, Groq, xAI (Grok), Mistral, Perplexity, Together AI, Fireworks AI, Cerebras, Cohere, NVIDIA NIM, Nebius AI, SiliconFlow, Hyperbolic, HuggingFace, OpenRouter, Vertex AI, Cloudflare Workers AI, Scaleway AI, AI/ML API, Pollinations AI, Puter AI, LongCat AI, Alibaba Cloud (DashScope), Alibaba Intl, Alibaba (AliCode), Kimi, Kimi Coding (API Key), Minimax, Minimax (China), Blackbox AI, Synthetic, Kilo Gateway, Z.AI, GLM Coding, Deepgram, AssemblyAI, ElevenLabs, Cartesia, PlayHT, Inworld, NanoBanana, SD WebUI, ComfyUI, Ollama Cloud, Perplexity Search, Serper Search, Brave Search, Exa Search, Tavily Search, OpenCode Zen, OpenCode Go, Bailian Coding Plan + +**Custom Providers:** OpenAI-compatible (`openai-compatible-*`) and Anthropic-compatible (`anthropic-compatible-*`) with custom base URLs ### Internationalization - 30 languages for UI (all dashboard pages) -- 30 translated READMEs in docs/i18n/ +- 30 translated documentation sets in docs/i18n/ - Language switcher in documentation ## Key Architectural Decisions @@ -172,16 +380,22 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo 5. **SSE proxy pipeline:** The proxy pipeline is middleware-based: request → auth resolution → rate limiting → circuit breaker → format translation → upstream call → response translation → SSE streaming back to client. -6. **SQLite for persistence:** All state (providers, combos, logs, settings, API keys) stored in a single SQLite database. All DB operations go through `src/lib/db/` modules, never raw SQL in routes. +6. **SQLite for persistence:** All state (providers, combos, logs, settings, API keys, memory, skills) stored in a single SQLite database via 21 domain-specific modules. All DB operations go through `src/lib/db/` modules, never raw SQL in routes. 7. **OAuth with PKCE:** OAuth flows use PKCE for security. Token refresh handled by background job (`tokenHealthCheck.ts`). 8. **ProviderIcon component:** Unified icon system using `@lobehub/icons` (130+ SVG) with PNG fallback and generic icon fallback chain. Used on providers, dashboard, and agents pages. -9. **DB architecture:** `localDb.ts` is a re-export layer only — real logic lives in `src/lib/db/` modules (core, providers, models, combos, apiKeys, settings, backup). +9. **DB architecture:** `localDb.ts` is a re-export layer only — real logic lives in 21 `src/lib/db/` modules with 16 SQL migrations. 10. **Upstream headers:** Custom headers merged in executors after default auth; same header name replaces executor value. Forbidden header names in `src/shared/constants/upstreamHeaders.ts`. +11. **Memory/Skills cross-cutting systems:** Memory and Skills affect the MCP tools, request pipeline, and A2A skills. Memory provides persistent context across sessions; Skills provide extensible tool execution with sandbox isolation. + +12. **Domain policy engine:** `src/domain/` contains policy engine modules (policyEngine, comboResolver, costRules, degradation, fallbackPolicy, lockoutPolicy, modelAvailability, providerExpiration, quotaCache, configAudit) that govern routing decisions independently from the pipeline. + +13. **Provider constants validated at load:** All provider definitions validated via Zod schemas at module load time (`src/shared/validation/providerSchema.ts`). Invalid providers fail fast. + ## Main Flows ### Proxy Request Flow @@ -196,6 +410,8 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo 9. Response translation: provider → OpenAI format 10. omniModel tag sanitization (strip internal tags) 11. SSE streaming back to client +12. Memory extraction (if memory system enabled) +13. Usage logging and cost calculation ### OAuth Flow 1. Dashboard initiates `/api/oauth/[provider]/authorize` @@ -210,22 +426,32 @@ OmniRoute solves the problem of managing multiple AI provider subscriptions, quo 2. **Provider IDs vs aliases:** Providers have both an ID (`claude`, `github`) and a short alias (`cc`, `gh`). Models are referenced as `alias/model-name` (e.g., `cc/claude-opus-4-6`). -3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, and translators. +3. **The `open-sse/` directory is a separate npm workspace** with its own config, handlers, executors, translators, and services. 4. **Environment variables:** All configuration is in `.env` (from `.env.example`). Key vars: `PORT`, `NEXT_PUBLIC_BASE_URL`, `API_KEY`, `ADMIN_PASSWORD`. -5. **Database layer:** Operations go through `src/lib/db/` modules. `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module. +5. **Database layer:** Operations go through `src/lib/db/` modules (21 domain-specific files). `localDb.ts` is re-exports only — add new functions to the proper `db/*.ts` module. -6. **Tests use Node.js built-in test runner:** 926 assertions across 32+ test files. Run `npm test`. +6. **Tests use Node.js built-in test runner:** 122 unit test files. Run `npm test`. Vitest for MCP/autoCombo (`npm run test:vitest`). Playwright for E2E (`npm run test:e2e`). 7. **MCP and A2A pages are embedded as tabs inside `/dashboard/endpoint`**, not standalone routes. -8. **ACP agents** are in `src/lib/acp/registry.ts` (14 built-in) with a 60s detection cache. Custom agents stored via settings DB. +8. **ACP agents** are in `src/lib/acp/registry.ts` with detection cache. Custom agents stored via settings DB. 9. **Auto-combo engine** in `open-sse/services/autoCombo/` — 6-factor scoring, 4 mode packs, bandit exploration, progressive cooldown. 10. **Docker:** Dockerfile has two targets: `runner-base` and `runner-cli`. `docker-compose.yml` for dev (3 profiles), `docker-compose.prod.yml` for production (port 20130). +11. **Electron desktop app** in `electron/` with main.js and preload.js. Build with `npm run electron:build` (supports Windows, macOS, Linux). + +12. **Pricing data** syncs from LiteLLM via `src/lib/pricingSync.ts`. Use `sync_pricing` MCP tool or API endpoint. + +13. **Memory system** in `src/lib/memory/` provides extraction, injection, retrieval, summarization, and persistent store. Exposed via MCP memory tools and `/api/memory/ API. + +14. **Skills system** in `src/lib/skills/` provides registry, executor, sandbox isolation, built-in skills, custom skill support, request interception, and context injection. Exposed via MCP skill tools and `/api/skills/` API. + +15. **Zod v4** is used for all validation. Import from `zod` package. Provider schemas validated at module load time. + ## Links - Repository: https://github.com/diegosouzapw/OmniRoute diff --git a/restart.sh b/restart.sh deleted file mode 100755 index e2d0da0eaa..0000000000 --- a/restart.sh +++ /dev/null @@ -1,119 +0,0 @@ -#!/bin/bash - -PORT=20128 -MAX_ATTEMPTS=3 -echo "🔄 Reiniciando aplicação na porta $PORT..." - -# Função para matar processos pela porta -kill_by_port() { - local attempt=1 - - while [ $attempt -le $MAX_ATTEMPTS ]; do - echo "Tentativa $attempt de $MAX_ATTEMPTS..." - - # Tenta encontrar processos usando lsof - PIDS=$(lsof -ti:$PORT 2>/dev/null) - - if [ -z "$PIDS" ]; then - echo "✓ Porta $PORT está livre" - return 0 - fi - - echo "🔴 Matando processos na porta $PORT: $PIDS" - - # Tenta SIGTERM primeiro (mais gentil) - if [ $attempt -eq 1 ]; then - for PID in $PIDS; do - kill $PID 2>/dev/null && echo " - SIGTERM enviado para PID $PID" - done - sleep 2 - else - # Se não funcionou, usa SIGKILL (força) - for PID in $PIDS; do - kill -9 $PID 2>/dev/null && echo " - SIGKILL enviado para PID $PID" - done - sleep 1 - fi - - # Fallback: tenta fuser se lsof não funcionou - if command -v fuser >/dev/null 2>&1; then - fuser -k -9 $PORT/tcp 2>/dev/null && echo " - fuser utilizado como fallback" - sleep 1 - fi - - attempt=$((attempt + 1)) - done - - # Última verificação - if lsof -ti:$PORT >/dev/null 2>&1; then - echo "❌ Erro: Não foi possível liberar a porta $PORT após $MAX_ATTEMPTS tentativas" - echo "Processos ainda ativos:" - lsof -i:$PORT 2>/dev/null - return 1 - fi - - return 0 -} - -# Executa a função de kill -if ! kill_by_port; then - echo "" - echo "💡 Sugestão: Execute manualmente:" - echo " sudo lsof -ti:$PORT | xargs kill -9" - exit 1 -fi - -echo "" -echo "🧹 Limpando build anterior (.next)..." -rm -rf .next - -echo "🔨 Fazendo build limpo..." -npm run build -if [ $? -ne 0 ]; then - echo "❌ Build falhou!" - exit 1 -fi - -echo "" -# Garante que a porta está livre antes de iniciar (build pode ter ocupado) -fuser -k $PORT/tcp 2>/dev/null -sleep 1 - -echo "🚀 Iniciando servidor na porta $PORT..." -LOG_FILE="/tmp/omniroute.log" -> "$LOG_FILE" - -npx next start --port $PORT >> "$LOG_FILE" 2>&1 & -SERVER_PID=$! - -# Ao fechar (Ctrl+C), mata o servidor e libera a porta -cleanup() { - echo "" - echo "🛑 Parando servidor (PID: $SERVER_PID)..." - kill $SERVER_PID 2>/dev/null - wait $SERVER_PID 2>/dev/null - fuser -k $PORT/tcp 2>/dev/null - echo "✅ Servidor parado. Porta $PORT liberada." - exit 0 -} -trap cleanup SIGINT SIGTERM - -# Aguarda o servidor ficar pronto -echo "⏳ Aguardando servidor iniciar (PID: $SERVER_PID)..." -for i in $(seq 1 15); do - sleep 1 - if curl -s -o /dev/null -w "" http://localhost:$PORT > /dev/null 2>&1; then - echo "" - echo "✅ Servidor rodando em http://localhost:$PORT (PID: $SERVER_PID)" - echo "📄 Pressione Ctrl+C para parar" - echo "────────────────────────────────────────" - break - fi - printf "." -done - -# Fica mostrando os logs na tela até Ctrl+C -tail -f "$LOG_FILE" & -TAIL_PID=$! -wait $SERVER_PID 2>/dev/null -kill $TAIL_PID 2>/dev/null diff --git a/test_exception.ts b/test_exception.ts deleted file mode 100644 index 9caa576d9e..0000000000 --- a/test_exception.ts +++ /dev/null @@ -1,25 +0,0 @@ -import { openaiToOpenAIResponsesRequest } from "./open-sse/translator/request/openai-responses.ts"; - -const root = { - model: "gpt-5.3-codex-xhigh", - messages: [ - { - role: "user", - content: [ - { - type: "text", - text: "\nThe following skills are available...", - }, - ], - }, - ], -}; - -try { - // Let's modify the file to actually export the function throwing or we can just copy the original logic. - // Actually, wait, let's just create a modified version of it here inline to see where it breaks. - const result = openaiToOpenAIResponsesRequest("gpt-5.3-codex-xhigh", root, true, null); - console.log("Result:", JSON.stringify(result, null, 2)); -} catch (e) { - console.error("Test Error:", e); -} diff --git a/test_out.txt b/test_out.txt deleted file mode 100644 index 3e35243487..0000000000 --- a/test_out.txt +++ /dev/null @@ -1,207 +0,0 @@ -[CREDENTIALS] No external credentials file found, using defaults. -[DB] SQLite database ready: /home/diegosouzapw/.omniroute/storage.sqlite -[MODEL] Ambiguous model 'claude-haiku-4.5'. Use provider/model prefix (ex: gh/claude-haiku-4.5 or kr/claude-haiku-4.5). Candidates: gh, kr, anthropic -TAP version 13 -# Subtest: getModelInfoCore resolves unique non-openai unprefixed model -ok 1 - getModelInfoCore resolves unique non-openai unprefixed model - --- - duration_ms: 3.403766 - type: 'test' - ... -# Subtest: getModelInfoCore keeps openai fallback for gpt-4o -ok 2 - getModelInfoCore keeps openai fallback for gpt-4o - --- - duration_ms: 0.535726 - type: 'test' - ... -# Subtest: getModelInfoCore resolves gpt-5.4 to codex -ok 3 - getModelInfoCore resolves gpt-5.4 to codex - --- - duration_ms: 0.321781 - type: 'test' - ... -# Subtest: getModelInfoCore returns explicit ambiguity metadata for ambiguous unprefixed model -ok 4 - getModelInfoCore returns explicit ambiguity metadata for ambiguous unprefixed model - --- - duration_ms: 1.079896 - type: 'test' - ... -# Subtest: getModelInfoCore canonicalizes github legacy alias with explicit provider prefix -ok 5 - getModelInfoCore canonicalizes github legacy alias with explicit provider prefix - --- - duration_ms: 0.370547 - type: 'test' - ... -# Subtest: GithubExecutor routes codex-family model to /responses -ok 6 - GithubExecutor routes codex-family model to /responses - --- - duration_ms: 0.47113 - type: 'test' - ... -# Subtest: GithubExecutor keeps non-codex model on /chat/completions -ok 7 - GithubExecutor keeps non-codex model on /chat/completions - --- - duration_ms: 0.38457 - type: 'test' - ... -# Subtest: DefaultExecutor uses x-api-key for kimi-coding-apikey -ok 8 - DefaultExecutor uses x-api-key for kimi-coding-apikey - --- - duration_ms: 0.451443 - type: 'test' - ... -# Subtest: CodexExecutor forces stream=true for upstream compatibility -ok 9 - CodexExecutor forces stream=true for upstream compatibility - --- - duration_ms: 1.203259 - type: 'test' - ... -# Subtest: Claude native messages can be round-tripped through OpenAI into Claude OAuth format -ok 10 - Claude native messages can be round-tripped through OpenAI into Claude OAuth format - --- - duration_ms: 7.232512 - type: 'test' - ... -# Subtest: CodexExecutor maps fast service tier to priority -ok 11 - CodexExecutor maps fast service tier to priority - --- - duration_ms: 0.489993 - type: 'test' - ... -# Subtest: shouldUseNativeCodexPassthrough only enables responses-native Codex requests -ok 12 - shouldUseNativeCodexPassthrough only enables responses-native Codex requests - --- - duration_ms: 0.441911 - type: 'test' - ... -# Subtest: CodexExecutor can force fast service tier from settings -ok 13 - CodexExecutor can force fast service tier from settings - --- - duration_ms: 0.299575 - type: 'test' - ... -# Subtest: CodexExecutor always requests SSE accept header -ok 14 - CodexExecutor always requests SSE accept header - --- - duration_ms: 0.602914 - type: 'test' - ... -# Subtest: CodexExecutor does not request SSE accept header for compact requests -ok 15 - CodexExecutor does not request SSE accept header for compact requests - --- - duration_ms: 0.322611 - type: 'test' - ... -# Subtest: CodexExecutor preserves native responses payloads for Codex passthrough -not ok 16 - CodexExecutor preserves native responses payloads for Codex passthrough - --- - duration_ms: 1.856261 - type: 'test' - location: '/home/diegosouzapw/dev/proxys/9router/tests/unit/plan3-p0.test.mjs:221:1' - failureType: 'testCodeFailure' - error: |- - Expected values to be strictly equal: - - false !== true - - code: 'ERR_ASSERTION' - name: 'AssertionError' - expected: true - actual: false - operator: 'strictEqual' - stack: |- - TestContext. (file:///home/diegosouzapw/dev/proxys/9router/tests/unit/plan3-p0.test.mjs:242:10) - Test.runInAsyncScope (node:async_hooks:214:14) - Test.run (node:internal/test_runner/test:1047:25) - Test.processPendingSubtests (node:internal/test_runner/test:744:18) - Test.postRun (node:internal/test_runner/test:1173:19) - Test.run (node:internal/test_runner/test:1101:12) - async Test.processPendingSubtests (node:internal/test_runner/test:744:7) - ... -# Subtest: CodexExecutor strips streaming fields for compact passthrough -ok 17 - CodexExecutor strips streaming fields for compact passthrough - --- - duration_ms: 0.296176 - type: 'test' - ... -# Subtest: CodexExecutor routes responses subpaths to matching upstream paths -ok 18 - CodexExecutor routes responses subpaths to matching upstream paths - --- - duration_ms: 0.546657 - type: 'test' - ... -# Subtest: translateNonStreamingResponse converts Responses API payload to OpenAI chat.completion -ok 19 - translateNonStreamingResponse converts Responses API payload to OpenAI chat.completion - --- - duration_ms: 1.483788 - type: 'test' - ... -# Subtest: extractUsageFromResponse reads usage from Responses API payload -ok 20 - extractUsageFromResponse reads usage from Responses API payload - --- - duration_ms: 0.398039 - type: 'test' - ... -# Subtest: detectFormat identifies OpenAI Responses when input is string -ok 21 - detectFormat identifies OpenAI Responses when input is string - --- - duration_ms: 0.359174 - type: 'test' - ... -# Subtest: detectFormat identifies OpenAI Responses by max_output_tokens without input array -ok 22 - detectFormat identifies OpenAI Responses by max_output_tokens without input array - --- - duration_ms: 0.271215 - type: 'test' - ... -# Subtest: detectFormatFromEndpoint forces OpenAI for /v1/chat/completions -ok 23 - detectFormatFromEndpoint forces OpenAI for /v1/chat/completions - --- - duration_ms: 0.52054 - type: 'test' - ... -# Subtest: detectFormatFromEndpoint forces Claude for /v1/messages -ok 24 - detectFormatFromEndpoint forces Claude for /v1/messages - --- - duration_ms: 0.433035 - type: 'test' - ... -# Subtest: translateRequest normalizes openai-responses input string into list payload -ok 25 - translateRequest normalizes openai-responses input string into list payload - --- - duration_ms: 0.358109 - type: 'test' - ... -# Subtest: translateRequest preserves service_tier when converting openai to openai-responses -ok 26 - translateRequest preserves service_tier when converting openai to openai-responses - --- - duration_ms: 1.10454 - type: 'test' - ... -# Subtest: parseSSEToResponsesOutput parses completed response from SSE payload -ok 27 - parseSSEToResponsesOutput parses completed response from SSE payload - --- - duration_ms: 0.575476 - type: 'test' - ... -# Subtest: parseSSEToResponsesOutput returns null for invalid payload -ok 28 - parseSSEToResponsesOutput returns null for invalid payload - --- - duration_ms: 0.302714 - type: 'test' - ... -# Subtest: parseSSEToOpenAIResponse merges split tool call chunks by id without duplication -ok 29 - parseSSEToOpenAIResponse merges split tool call chunks by id without duplication - --- - duration_ms: 0.916032 - type: 'test' - ... -1..29 -# tests 29 -# suites 0 -# pass 28 -# fail 1 -# cancelled 0 -# skipped 0 -# todo 0 -# duration_ms 65.394285 diff --git a/test_target_format.ts b/test_target_format.ts deleted file mode 100644 index eda81bd6c2..0000000000 --- a/test_target_format.ts +++ /dev/null @@ -1,36 +0,0 @@ -import { getTargetFormat } from "./open-sse/services/provider.ts"; -import { parseModelFromRequest, resolveProviderAndModel } from "./open-sse/handlers/chatCore.ts"; // Since they're in chatCore directly? -import { getProviderConfig } from "./open-sse/services/provider.ts"; - -const body = { model: "codex/gpt-5.3-codex-xhigh" }; -const parsedModel = body.model; - -function resolveProviderAndModel(rawModel, providerFromPath = "") { - let provider = providerFromPath; - let model = rawModel; - let resolvedAlias = null; - - if (rawModel && rawModel.includes("/")) { - const parts = rawModel.split("/"); - provider = parts[0]; - model = parts.slice(1).join("/"); - } - - return { provider, model, resolvedAlias: null }; -} - -const { provider, model, resolvedAlias } = resolveProviderAndModel(parsedModel, ""); -const effectiveModel = resolvedAlias || model; - -const config = getProviderConfig(provider); -const modelTargetFormat = config?.models?.find((m) => m.id === effectiveModel)?.targetFormat; -const targetFormat = modelTargetFormat || getTargetFormat(provider); - -console.log({ - provider, - model, - resolvedAlias, - effectiveModel, - modelTargetFormat, - targetFormat, -}); diff --git a/test_translator.ts b/test_translator.ts deleted file mode 100644 index e82aa77369..0000000000 --- a/test_translator.ts +++ /dev/null @@ -1,51 +0,0 @@ -import { translateRequest } from "./open-sse/translator/index.ts"; -import { FORMATS } from "./open-sse/translator/formats.ts"; -import { CodexExecutor } from "./open-sse/executors/codex.ts"; - -const claudeCodeRequest = { - model: "codex/gpt-5.3-codex-xhigh", - messages: [ - { - role: "user", - content: [ - { - type: "text", - text: "What time is it?", - }, - ], - }, - ], - system: "Test system prompt", - tools: [ - { - name: "get_time", - description: "Get the time", - input_schema: { - type: "object", - properties: { timezone: { type: "string" } }, - }, - }, - ], -}; - -try { - const result = translateRequest( - FORMATS.CLAUDE, - FORMATS.OPENAI_RESPONSES, - "gpt-5.3-codex-xhigh", - claudeCodeRequest, - true, // stream - null, // credentials - "codex", // provider - null, // reqLogger - { normalizeToolCallId: false, preserveDeveloperRole: true } - ); - - const exec = new CodexExecutor(); - const finalBody = exec.transformRequest("gpt-5.3-codex-xhigh", result, true, {}); - - console.log("FINAL BODY:", JSON.stringify(finalBody, null, 2)); -} catch (err) { - console.error("ERROR:"); - console.error(err); -} diff --git a/validate-translation.sh b/validate-translation.sh deleted file mode 100755 index 39a3b6be08..0000000000 --- a/validate-translation.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash -# Wrapper for OmniRoute translation validator -# Provides easy CLI access to the Python validation script - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -# Run the Python script with all arguments -exec python3 "$SCRIPT_DIR/scripts/validate_translation.py" "$@"